search

rust-lang / book

The Rust Programming Language
https://doc.rust-lang.org/book/
Other
14.56k stars 3.31k forks source link

Convert all code listings to use new `<Listing>` preprocessor #3919

Open chriskrycho opened 1 month ago

chriskrycho commented 1 month ago

As of #3918, we have a preprocessor that allows us to author with a custom HTML tag, Listing, roughly as if it were a component in a templating language. This input:

<Listing number="1-1" file-name="src/lib.rs" caption="A listing showing how to use a `Listing`">

```rust
fn main() {
    println!("Hello, listing!");
}


…will generate this output in the regular book (and strip all the tags in the NoStarch book):

````html
<figure class="listing">
<span class="file-name">Filename: src/lib.rs</span>
<pre><pre class="playground"><code class="language-rust">fn main() {
    println!("Hello, listing!");
}</code></pre></pre>
<figcaption>Listing 1-2: A listing showing how to use a <code>Listing</code></figcaption>
</figure>

As described in the PR adding support for this, the result is more accessible HTML, which will also give us a nice way to hook in for styling things better if we so choose.

If you’d like to help, please leave a comment below noting which chapter you’d like to pick up so folks don’t do duplicate work! If it already has a user handle by it, please don’t work on that chapter.

Note for contributors: when converting to a <Listing>, you can drop the leading Listing <number>: from the caption arg, since it handles that automatically with the number arg.

davidkurilla commented 1 month ago

I'd like to help with chapter 1.

davidkurilla commented 1 month ago

Thanks for the feedback for my pervious contribution! I plan to work on converting chapters 2 and 3

chriskrycho commented 1 month ago

Very good! Thank you! 💙

SpectralPixel commented 1 month ago

I'll do chapters 6-10. Already working on it.

bzierk commented 3 weeks ago

I am working on converting chapter 11.

bzierk commented 2 weeks ago

I'm in the process of converting 12-15. It is mostly working but all captions which have angle brackets (eg Box<T>) are breaking the xml parser. Will work on handling the necessary escape characters.

chriskrycho commented 2 weeks ago

Interesting – I would not have expected that! 🤔 Let me know what you come up with.

bzierk commented 2 weeks ago

The issue appears to be that < is not a valid character in the body of an attribute in XML. These characters have to be escaped but with the ListingBuilder taking things by reference its a little trickier.

https://github.com/RazrFalcon/xmlparser/blob/e54c2768f20814140c11e6c92f94ee74bfd54808/src/lib.rs#L1037

SpectralPixel commented 2 weeks ago

I've been quite busy over here, I hope to get back to work soon and finish the chapters.

SpectralPixel commented 1 week ago

How do I build the mdbook with the Listing pre-processor? If I recall correctly, <Listing> support hasn't been upstreamed yet, so how do I test the book? Or is that responsibility offloaded to code reviewers? Thanks :)

SpectralPixel commented 1 week ago

Also, what about code that is preceded by a filename, yet doesn't have a listing number? Are these also turned into <Listing>s that don't have a number or caption? (Edit: I'll do these as well for now, feel free to revert them later.)