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

Add a <Listing> preprocessor #3918

Merged
merged 8 commits into from
May 14, 2024
Merged

Add a <Listing> preprocessor #3918

merged 8 commits into from
May 14, 2024

Conversation

chriskrycho
Copy link
Contributor

@chriskrycho chriskrycho commented May 14, 2024

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 mdBook itself, 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 specifically figure.listing and 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:

CleanShot 2024-05-14 at 10 58 13@2x

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.
@chriskrycho chriskrycho merged commit 444932b into main May 14, 2024
6 checks passed
@chriskrycho chriskrycho deleted the trpl-listing branch May 14, 2024 17:54
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 2d1947ff34d50ca46dfe242ad75531a4c429bb52..b6d4a4940bab85cc91eec70cc2e3096dd48da62d
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 2d1947ff34d50ca46dfe242ad75531a4c429bb52..b6d4a4940bab85cc91eec70cc2e3096dd48da62d
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 2d1947ff34d50ca46dfe242ad75531a4c429bb52..b6d4a4940bab85cc91eec70cc2e3096dd48da62d
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
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant