Add a <Listing> preprocessor
#3918
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
Instead of requiring a bunch of `<span>` wrangling, add a custom tag, `<Listing>`, whose attributes get rewritten into the desired output format, using `<figure>` and `<figcaption>` for improved semantic HTML. Support both a default (nice and fancy) HTML output mode and a “simple” mode to make it so we get the desired output format for the NoStarch input files as well.
This does not yet update all the workspace dependencies to be shared between the listing and note preprocessors; it *only* integrates the repo histories.
- Add CSS for `figure.listing`; this now renders identically to how the existing listings render. - Convert the first listing in the book to use `<Listing>` instead of a bunch of `<span>`s.
21 tasks
matthiaskrgr
added a commit
to matthiaskrgr/rust
that referenced
this pull request
May 20, 2024
Update books ## rust-lang/book 8 commits in bebcf527e67755a989a1739b7cfaa8f0e6b30040..5e9051f71638aa941cd5dda465e25c61cde9594f 2024-05-16 14:58:56 UTC to 2024-05-07 23:58:22 UTC - Convert ch01-03-hello-cargo.md Listing 1-2 using `<Listing>` (rust-lang/book#3924) - infra: fix rendering bug in mdbook-trpl-note (rust-lang/book#3925) - infra: support `Listing`s without `file-name` (rust-lang/book#3920) - Add a `<Listing>` preprocessor (rust-lang/book#3918) - Update explanation according to code listing (rust-lang/book#3916) - infra: run package tests (rust-lang/book#3915) - Fix workspace behavior by excluding `listings` (rust-lang/book#3914) - Backport changes to chapter 8 (rust-lang/book#3913) ## rust-embedded/book 1 commits in 17842ebb050f62e40a4618edeb8e8ee86e758707..dd962bb82865a5284f2404e5234f1e3222b9c022 2024-05-17 23:43:59 UTC to 2024-05-17 23:43:59 UTC - 'llvm-tools-preview' component is now named 'llvm-tools' (rust-embedded/book#372) ## rust-lang/reference 2 commits in 51817951d0d213a0011f82b62aae02c3b3f2472e..e356977fceaa8591c762312d8d446769166d4b3e 2024-05-10 12:49:15 UTC to 2024-05-07 13:32:57 UTC - Document inline const/const block expression (rust-lang/reference#1295) - patterns: include yet unstable exclusive range patterns (rust-lang/reference#1484) ## rust-lang/rust-by-example 7 commits in 229ad13b64d919b12e548d560f06d88963b25cd3..20482893d1a502df72f76762c97aed88854cdf81 2024-05-20 14:36:21 UTC to 2024-05-14 16:17:03 UTC - Clarify interchangability for From and Into (rust-lang/rust-by-example#1851) - Update ja.po based on the latest master (rust-lang/rust-by-example#1850) - Add explicit section link (rust-lang/rust-by-example#1847) - Adjust translation build on CI (rust-lang/rust-by-example#1849) - Update mdbook version in CI (rust-lang/rust-by-example#1848) - Fix some broken links in ja.po (rust-lang/rust-by-example#1844) - Fix an external link to absolute (rust-lang/rust-by-example#1842) ## rust-lang/rustc-dev-guide 8 commits in 2d1947f..b6d4a49 2024-05-17 17:04:58 UTC to 2024-05-09 13:22:03 UTC - Add a high level explanation of early/late bound params (rust-lang/rustc-dev-guide#1982) - Fix broken link to "Lowering" (rust-lang/rustc-dev-guide#1981) - Broken link fix (rust-lang/rustc-dev-guide#1980) - Add note about how to pick up abandoned PRs (rust-lang/rustc-dev-guide#1977) - Toc here is overkill (rust-lang/rustc-dev-guide#1976) - Link to lint `L-*` labels (rust-lang/rustc-dev-guide#1975) - Update the rustc_interface examples for current rustc (rust-lang/rustc-dev-guide#1974) - Edit `Parameter Environments`'s url as it has been edited in rust-lang#1953 (rust-lang/rustc-dev-guide#1973)
matthiaskrgr
added a commit
to matthiaskrgr/rust
that referenced
this pull request
May 20, 2024
Update books ## rust-lang/book 8 commits in bebcf527e67755a989a1739b7cfaa8f0e6b30040..5e9051f71638aa941cd5dda465e25c61cde9594f 2024-05-16 14:58:56 UTC to 2024-05-07 23:58:22 UTC - Convert ch01-03-hello-cargo.md Listing 1-2 using `<Listing>` (rust-lang/book#3924) - infra: fix rendering bug in mdbook-trpl-note (rust-lang/book#3925) - infra: support `Listing`s without `file-name` (rust-lang/book#3920) - Add a `<Listing>` preprocessor (rust-lang/book#3918) - Update explanation according to code listing (rust-lang/book#3916) - infra: run package tests (rust-lang/book#3915) - Fix workspace behavior by excluding `listings` (rust-lang/book#3914) - Backport changes to chapter 8 (rust-lang/book#3913) ## rust-embedded/book 1 commits in 17842ebb050f62e40a4618edeb8e8ee86e758707..dd962bb82865a5284f2404e5234f1e3222b9c022 2024-05-17 23:43:59 UTC to 2024-05-17 23:43:59 UTC - 'llvm-tools-preview' component is now named 'llvm-tools' (rust-embedded/book#372) ## rust-lang/reference 2 commits in 51817951d0d213a0011f82b62aae02c3b3f2472e..e356977fceaa8591c762312d8d446769166d4b3e 2024-05-10 12:49:15 UTC to 2024-05-07 13:32:57 UTC - Document inline const/const block expression (rust-lang/reference#1295) - patterns: include yet unstable exclusive range patterns (rust-lang/reference#1484) ## rust-lang/rust-by-example 7 commits in 229ad13b64d919b12e548d560f06d88963b25cd3..20482893d1a502df72f76762c97aed88854cdf81 2024-05-20 14:36:21 UTC to 2024-05-14 16:17:03 UTC - Clarify interchangability for From and Into (rust-lang/rust-by-example#1851) - Update ja.po based on the latest master (rust-lang/rust-by-example#1850) - Add explicit section link (rust-lang/rust-by-example#1847) - Adjust translation build on CI (rust-lang/rust-by-example#1849) - Update mdbook version in CI (rust-lang/rust-by-example#1848) - Fix some broken links in ja.po (rust-lang/rust-by-example#1844) - Fix an external link to absolute (rust-lang/rust-by-example#1842) ## rust-lang/rustc-dev-guide 8 commits in 2d1947f..b6d4a49 2024-05-17 17:04:58 UTC to 2024-05-09 13:22:03 UTC - Add a high level explanation of early/late bound params (rust-lang/rustc-dev-guide#1982) - Fix broken link to "Lowering" (rust-lang/rustc-dev-guide#1981) - Broken link fix (rust-lang/rustc-dev-guide#1980) - Add note about how to pick up abandoned PRs (rust-lang/rustc-dev-guide#1977) - Toc here is overkill (rust-lang/rustc-dev-guide#1976) - Link to lint `L-*` labels (rust-lang/rustc-dev-guide#1975) - Update the rustc_interface examples for current rustc (rust-lang/rustc-dev-guide#1974) - Edit `Parameter Environments`'s url as it has been edited in rust-lang#1953 (rust-lang/rustc-dev-guide#1973)
rust-timer
added a commit
to rust-lang-ci/rust
that referenced
this pull request
May 21, 2024
Rollup merge of rust-lang#125332 - rustbot:docs-update, r=ehuss Update books ## rust-lang/book 8 commits in bebcf527e67755a989a1739b7cfaa8f0e6b30040..5e9051f71638aa941cd5dda465e25c61cde9594f 2024-05-16 14:58:56 UTC to 2024-05-07 23:58:22 UTC - Convert ch01-03-hello-cargo.md Listing 1-2 using `<Listing>` (rust-lang/book#3924) - infra: fix rendering bug in mdbook-trpl-note (rust-lang/book#3925) - infra: support `Listing`s without `file-name` (rust-lang/book#3920) - Add a `<Listing>` preprocessor (rust-lang/book#3918) - Update explanation according to code listing (rust-lang/book#3916) - infra: run package tests (rust-lang/book#3915) - Fix workspace behavior by excluding `listings` (rust-lang/book#3914) - Backport changes to chapter 8 (rust-lang/book#3913) ## rust-embedded/book 1 commits in 17842ebb050f62e40a4618edeb8e8ee86e758707..dd962bb82865a5284f2404e5234f1e3222b9c022 2024-05-17 23:43:59 UTC to 2024-05-17 23:43:59 UTC - 'llvm-tools-preview' component is now named 'llvm-tools' (rust-embedded/book#372) ## rust-lang/reference 2 commits in 51817951d0d213a0011f82b62aae02c3b3f2472e..e356977fceaa8591c762312d8d446769166d4b3e 2024-05-10 12:49:15 UTC to 2024-05-07 13:32:57 UTC - Document inline const/const block expression (rust-lang/reference#1295) - patterns: include yet unstable exclusive range patterns (rust-lang/reference#1484) ## rust-lang/rust-by-example 7 commits in 229ad13b64d919b12e548d560f06d88963b25cd3..20482893d1a502df72f76762c97aed88854cdf81 2024-05-20 14:36:21 UTC to 2024-05-14 16:17:03 UTC - Clarify interchangability for From and Into (rust-lang/rust-by-example#1851) - Update ja.po based on the latest master (rust-lang/rust-by-example#1850) - Add explicit section link (rust-lang/rust-by-example#1847) - Adjust translation build on CI (rust-lang/rust-by-example#1849) - Update mdbook version in CI (rust-lang/rust-by-example#1848) - Fix some broken links in ja.po (rust-lang/rust-by-example#1844) - Fix an external link to absolute (rust-lang/rust-by-example#1842) ## rust-lang/rustc-dev-guide 8 commits in 2d1947f..b6d4a49 2024-05-17 17:04:58 UTC to 2024-05-09 13:22:03 UTC - Add a high level explanation of early/late bound params (rust-lang/rustc-dev-guide#1982) - Fix broken link to "Lowering" (rust-lang/rustc-dev-guide#1981) - Broken link fix (rust-lang/rustc-dev-guide#1980) - Add note about how to pick up abandoned PRs (rust-lang/rustc-dev-guide#1977) - Toc here is overkill (rust-lang/rustc-dev-guide#1976) - Link to lint `L-*` labels (rust-lang/rustc-dev-guide#1975) - Update the rustc_interface examples for current rustc (rust-lang/rustc-dev-guide#1974) - Edit `Parameter Environments`'s url as it has been edited in rust-lang#1953 (rust-lang/rustc-dev-guide#1973)
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.
This lets us write
<Listing>with some attributes (kind of like writing custom component in a templating language) and have the output generated automatically using<figure>and<figcaption>markup instead of a bunch of disconnected<span>tags. In the case of the nostarch build, we just strip the markup and emit exactly what was there before.The primary win here is that it provides better accessibility for the book, by using semantic HTML elements which actually structure the document. (We might think about upstreaming this basic functionality to
mdBookitself, but it would need some further design consideration I think.) Secondarily, since we have this structure in place, we can if we so choose tweak the presentation of these items using CSS which targets specificallyfigure.listingand its children.This does not yet walk the entire repo and replace all listings! That will take a bit of work, but can also be done piecemeal. (I will open an issue to track it.)
The first listing, converted: