Improve handling of <Listing>s
#3975
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- `tests` -> `src/tests/mod.rs` - `tests::config` -> `src/tests/config.rs` This is just profoundly easier to work with.
When I originally built this, I thought *all* “listings” had numbers and captions, but it turns out that there are a number of places in the book where having the overall `figure`-driven output, i.e. with a file name, is desirable even though there is no number or caption. A potential enhancement later would be to require a caption if a number is present, since that seems to be what the book actually does.
XML does not allow more XML to appear in the body of an attribute, but this is not XML! It is *HTML*, since Markdown allows embedding HTML, and HTML *does* allow embedding further `<` and `>` characters within the attributes on the element. Accordingly, switch to `html_parser`, add a test covering this behavior, and update `ListingBuilder` to take the number, caption, and file name types as owned rather than as references, since that is what `html_parser` supplies. Additionally, refactor the guts a bit so it is easy to see the overall logic of `rewrite_listing`, with the gnarly bits around opening and closing the rewritten listings pushed into a method on the `State` struct, itself renamed to `ListingState` and its `current_listing` field renamed to `current`. This also clarifies the semantics of each part of the rewrite operation, e.g. `ListingState::open_listing` is fallible; `ListingState::close_listing` is not.
20 tasks
ehuss
added a commit
to rustbot/rust
that referenced
this pull request
Jul 29, 2024
matthiaskrgr
added a commit
to matthiaskrgr/rust
that referenced
this pull request
Aug 14, 2024
Update books ## rust-lang/book 7 commits in 67fa536768013d9d5a13f3a06790521d511ef711..04bc1396bb857f35b5dda1d773c9571e1f253304 2024-07-31 13:19:44 UTC to 2024-07-16 18:18:38 UTC - mdbook-trpl-listing: Add missing elided lifetimes (rust-lang/book#3995) - infra: include ghp-import and git push in generate-preview script (rust-lang/book#3998) - infra: add robots.txt for GH Pages previews (rust-lang/book#3997) - Clarify function definitions vs. expressions (rust-lang/book#3870) - infra: fix some shellcheck issues in CI config (rust-lang/book#3988) - infra: support test renderer in mdbook preprocessors (rust-lang/book#3982) - Improve handling of `<Listing>`s (rust-lang/book#3975) ## rust-lang/edition-guide 4 commits in 5454de3d12b9ccc6375b629cf7ccda8264640aac..aeeb287d41a0332c210da122bea8e0e91844ab3e 2024-08-06 21:16:24 UTC to 2024-07-29 21:41:36 UTC - Stabilize unsafe extern blocks (rust-lang/edition-guide#313) - Add chapter for Lifetime Capture Rules 2024 (rust-lang/edition-guide#316) - 2024: Add page for missing_fragment_specifier (rust-lang/edition-guide#315) - Add documentation for 2024 prelude migration. (rust-lang/edition-guide#314) ## rust-lang/nomicon 3 commits in 0ebdacadbda8ce2cd8fbf93985e15af61a7ab895..6ecf95c5f2bfa0e6314dfe282bf775fd1405f7e9 2024-08-11 16:55:29 UTC to 2024-08-09 23:25:22 UTC - Stabilize `min_exhaustive_patterns` (rust-lang/nomicon#445) - repr(int) enums: both size and sign matter (rust-lang/nomicon#458) - Update what-unsafe-does.md (rust-lang/nomicon#457) ## rust-lang/reference 6 commits in 2e191814f163ee1e77e2d6094eee4dd78a289c5b..62cd0df95061ba0ac886333f5cd7f3012f149da1 2024-08-11 21:06:12 UTC to 2024-07-30 06:34:03 UTC - Reformat (and only reformat) the inline assembly chapter (rust-lang/reference#1550) - Changes for unsafe extern blocks (RFC 3484) (rust-lang/reference#1536) - Stabilize Wasm relaxed SIMD (rust-lang/reference#1421) - Remove custom blockquote styling (rust-lang/reference#1547) - Fix std-links for generics with commas. (rust-lang/reference#1549) - Add details on how names are introduced. (rust-lang/reference#1052) ## rust-lang/rust-by-example 3 commits in 89aecb6951b77bc746da73df8c9f2b2ceaad494a..8f94061936e492159f4f6c09c0f917a7521893ff 2024-08-06 17:25:35 UTC to 2024-07-16 20:58:25 UTC - Update lifetime_bounds.md (rust-lang/rust-by-example#1869) - Remove the link to Japanese translation (rust-lang/rust-by-example#1868) - Add an example of implementing the FromStr trait for Circles. (rust-lang/rust-by-example#1865) ## rust-lang/rustc-dev-guide 12 commits in 0c4d55cb59fe440d1a630e4e5774d043968edb3f..43d83780db545a1ed6d45773312fc578987e3968 2024-08-08 17:54:27 UTC to 2024-07-19 07:15:12 UTC - Added 'the' in chapter "Running test" subtitle "Run unit tests on the compiler/library" (rust-lang/rustc-dev-guide#2040) - Correct rust code block in *Dataflow Analysis* (rust-lang/rustc-dev-guide#2037) - linkcheck: fix filtering of the source files (rust-lang/rustc-dev-guide#2019) - chore: fix some comments (rust-lang/rustc-dev-guide#2028) - linkcheck: fix reported broken links (part 2) (rust-lang/rustc-dev-guide#2024) - typo (rust-lang/rustc-dev-guide#2029) - Fix broken links in `llvm-coverage-instrumentation.md` (rust-lang/rustc-dev-guide#2027) - Fix invalid link to toolstate documentation (rust-lang/rustc-dev-guide#2021) - linkcheck: fix reported broken links (part 1) (rust-lang/rustc-dev-guide#2022) - fix link (rust-lang/rustc-dev-guide#2020) - MIR docs: fix borked links and update style (rust-lang/rustc-dev-guide#2017) - Update adding.md (rust-lang/rustc-dev-guide#2016)
rust-timer
added a commit
to rust-lang-ci/rust
that referenced
this pull request
Aug 15, 2024
Rollup merge of rust-lang#129015 - rustbot:docs-update, r=ehuss Update books ## rust-lang/book 7 commits in 67fa536768013d9d5a13f3a06790521d511ef711..04bc1396bb857f35b5dda1d773c9571e1f253304 2024-07-31 13:19:44 UTC to 2024-07-16 18:18:38 UTC - mdbook-trpl-listing: Add missing elided lifetimes (rust-lang/book#3995) - infra: include ghp-import and git push in generate-preview script (rust-lang/book#3998) - infra: add robots.txt for GH Pages previews (rust-lang/book#3997) - Clarify function definitions vs. expressions (rust-lang/book#3870) - infra: fix some shellcheck issues in CI config (rust-lang/book#3988) - infra: support test renderer in mdbook preprocessors (rust-lang/book#3982) - Improve handling of `<Listing>`s (rust-lang/book#3975) ## rust-lang/edition-guide 4 commits in 5454de3d12b9ccc6375b629cf7ccda8264640aac..aeeb287d41a0332c210da122bea8e0e91844ab3e 2024-08-06 21:16:24 UTC to 2024-07-29 21:41:36 UTC - Stabilize unsafe extern blocks (rust-lang/edition-guide#313) - Add chapter for Lifetime Capture Rules 2024 (rust-lang/edition-guide#316) - 2024: Add page for missing_fragment_specifier (rust-lang/edition-guide#315) - Add documentation for 2024 prelude migration. (rust-lang/edition-guide#314) ## rust-lang/nomicon 3 commits in 0ebdacadbda8ce2cd8fbf93985e15af61a7ab895..6ecf95c5f2bfa0e6314dfe282bf775fd1405f7e9 2024-08-11 16:55:29 UTC to 2024-08-09 23:25:22 UTC - Stabilize `min_exhaustive_patterns` (rust-lang/nomicon#445) - repr(int) enums: both size and sign matter (rust-lang/nomicon#458) - Update what-unsafe-does.md (rust-lang/nomicon#457) ## rust-lang/reference 6 commits in 2e191814f163ee1e77e2d6094eee4dd78a289c5b..62cd0df95061ba0ac886333f5cd7f3012f149da1 2024-08-11 21:06:12 UTC to 2024-07-30 06:34:03 UTC - Reformat (and only reformat) the inline assembly chapter (rust-lang/reference#1550) - Changes for unsafe extern blocks (RFC 3484) (rust-lang/reference#1536) - Stabilize Wasm relaxed SIMD (rust-lang/reference#1421) - Remove custom blockquote styling (rust-lang/reference#1547) - Fix std-links for generics with commas. (rust-lang/reference#1549) - Add details on how names are introduced. (rust-lang/reference#1052) ## rust-lang/rust-by-example 3 commits in 89aecb6951b77bc746da73df8c9f2b2ceaad494a..8f94061936e492159f4f6c09c0f917a7521893ff 2024-08-06 17:25:35 UTC to 2024-07-16 20:58:25 UTC - Update lifetime_bounds.md (rust-lang/rust-by-example#1869) - Remove the link to Japanese translation (rust-lang/rust-by-example#1868) - Add an example of implementing the FromStr trait for Circles. (rust-lang/rust-by-example#1865) ## rust-lang/rustc-dev-guide 12 commits in 0c4d55cb59fe440d1a630e4e5774d043968edb3f..43d83780db545a1ed6d45773312fc578987e3968 2024-08-08 17:54:27 UTC to 2024-07-19 07:15:12 UTC - Added 'the' in chapter "Running test" subtitle "Run unit tests on the compiler/library" (rust-lang/rustc-dev-guide#2040) - Correct rust code block in *Dataflow Analysis* (rust-lang/rustc-dev-guide#2037) - linkcheck: fix filtering of the source files (rust-lang/rustc-dev-guide#2019) - chore: fix some comments (rust-lang/rustc-dev-guide#2028) - linkcheck: fix reported broken links (part 2) (rust-lang/rustc-dev-guide#2024) - typo (rust-lang/rustc-dev-guide#2029) - Fix broken links in `llvm-coverage-instrumentation.md` (rust-lang/rustc-dev-guide#2027) - Fix invalid link to toolstate documentation (rust-lang/rustc-dev-guide#2021) - linkcheck: fix reported broken links (part 1) (rust-lang/rustc-dev-guide#2022) - fix link (rust-lang/rustc-dev-guide#2020) - MIR docs: fix borked links and update style (rust-lang/rustc-dev-guide#2017) - Update adding.md (rust-lang/rustc-dev-guide#2016)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Add support for listings which have file names but no caption or number. This means that we now support having all such be optional; in that case we still emit some nice semantic HTML with the listing wrapped in a
<figure>, just without a<figcaption>or a<span>for the file name.Add support for having captions like
"This is a caption about a Box<T>". XML parsers reject this, because XML does not allow the<or>to appear in attributes unescaped. We could stick withxmlparser, and attempt to switch to using owned strings which we preprocess to escape them, but that is a tricky dance: we also need to run Markdown handling on them, so we would somehow need to do so prior to parsing the XML at all, so that we do not end up with the literal>appearing in the rendered output.This PR sidesteps all of that complexity and resolves the underlying issue by switching
mdbook-trpl-listingover tohtml_parser, which is a much lighter-weight crate which simply implements a compliant HTML parser using Pest. I read the source today and it is quite reasonable, and is much smaller and simpler thanxmlparser. This works because HTML, unlike XML, is totally fine with having<and>appear within the string bodies of attributes. I also evaluatedhtml5ever, but while that is notionally more robust, it also comes with substantially more wiring to do and a harder-to-use API.These two changes should unblock the rest of the work on #3919.