Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve handling of <Listing>s #3975

Merged
merged 3 commits into from
Jul 16, 2024
Merged

Conversation

chriskrycho
Copy link
Contributor

  • 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 with xmlparser, 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 &gt; appearing in the rendered output.

    This PR sidesteps all of that complexity and resolves the underlying issue by switching mdbook-trpl-listing over to html_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 than xmlparser. This works because HTML, unlike XML, is totally fine with having < and > appear within the string bodies of attributes. I also evaluated html5ever, 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.

- `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.
@chriskrycho chriskrycho merged commit 9c974f1 into main Jul 16, 2024
6 checks passed
@chriskrycho chriskrycho deleted the chriskrycho/improved-listings-support branch July 16, 2024 18:37
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)
chriskrycho added a commit that referenced this pull request Oct 15, 2024
This restores the work originally done in #3956, which had to be dropped
from that PR because this chapter was blocked on XML handling, which was
resolved in #3975.

Co-authored-by: Bryan Zierk <bryan.zierk@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant