book

book copied to clipboard

Background

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!");
}
```

</Listing>

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

<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.

Contributing

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.

Do add a <Listing> for all code blocks (including rust, text, console, etc.) which have either or both of:

• an explicit listing number, in the form <span class="caption">Listing XX-YY: …</span>
• an explicit file name, in the form <span class="filename">Filename: src/main.rs</span>

Do not add a <Listing> for code blocks which do not have at least one or the other of those.

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.

• [x] Chapter 1 (@davidkurilla - #3924)
• [x] Chapter 2 (@davidkurilla – #3926)
• [x] Chapter 3 (@davidkurilla – #3926)
• [x] Chapter 4 (@jpmelos – #4043)
• [ ] Chapter 5 (@jpmelos – #4051)
• [ ] Chapter 6 (@SpectralPixel)
• [ ] Chapter 7 (@SpectralPixel)
• [ ] Chapter 8 (@SpectralPixel)
• [ ] Chapter 9 (@SpectralPixel)
• [ ] Chapter 10 (@SpectralPixel)
• [x] Chapter 11 (@bzierk – #3955)
• [x] Chapter 12 (@bzierk – #3959)
• [x] Chapter 13 (@bzierk – #3959)
• [x] Chapter 14 (@bzierk – #3959)
• [ ] Chapter 15 (@bzierk)
• [ ] Chapter 16 (@LifeAdventurer – #4066)
• [x] Chapter 17 (@chriskrycho did this from the start while writing the new chapter!)
• [x] Chapter 18 (@chriskrycho – #4060)
• [x] Chapter 19 (@chriskrycho – #4060)
• [x] Chapter 20 (@chriskrycho – #4060)
• [x] Chapter 21 (@chriskrycho – #4060)

I'd like to help with chapter 1.

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

Very good! Thank you! 💙

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

I am working on converting chapter 11.

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.

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

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

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

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 :)

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.)

@SpectralPixel sorry, just saw these questions.

1. For the listing preprocessor, it worked just fine in this repo anyway, and it has been fixed in the rust repo, so nothing to worry about there.
2. Mmmm, those are interesting – we probably need to think about how <Listing> should handle those. I will poke at how many of those there are and figure out what we ought to do with them!

Hmmm, I already converted those special <Listing>s, so I'll add them in my PR. Feel free to revert those commits if necessary though. I'll try to finish it all up this afternoon.

Weird, mdbook seems not to work on my machine when I install it the way that is recommended for this repo... I guess I'll just send the PR so you can check if it works fine, it's probably just me doing something wrong with mdbook...

@SpectralPixel if you consistently have issues with mdbook not working, would you open an issue? That way we can track fixing that—it’s important to us to make sure folks can contribute easily!

Well, I'm not sure if I have it set up properly...

@SpectralPixel @bzierk I believe #3975 should address the issues each of you were separately hitting in terms of what the <Listing> preprocessor supports!

I did chapter 4 here: https://github.com/rust-lang/book/pull/4043.

I think some explanation about which listings need to be converted would be helpful:

• Just the ones with listing number, caption, or file name? Or also the ones without any of those things?
• Only Rust listings, or all of them (even the console ones, for example)?

Thanks for the note, @jpmelos – I’ll update the issue description here. Basically, it should only be converted if it has an explicit listing number (<span class="caption">Listing XX-YY: …</span>), an explicit file name (<span class="filename">Filename: …</span>), or both. Otherwise, it isn’t a “listing” in the way we approach it, so should not be converted!

I did chapter 05 here: https://github.com/rust-lang/book/pull/4051.

@SpectralPixel would you like me to fix up those PRs you opened and get them across the line? (No worries; I have very often been the guy who started something and then life got busy!)

Oh, I must've forgotten to revert those few commits. Should be only one per PR, otherwise they're all ready to go.

I'd like to help with chapter 16.

@LifeAdventurer go for it – I’ll mark you down on the list! Thanks!

@SpectralPixel see the PRs—they’re all currently failing; I think it’s primarily a function of line-wrapping (see my comment on #3977 for more).

I did all the line wrapping in at most one commit per PR, could you revert these? I'm quite busy at the moment. Other than that, the PRs should be ready to go. :)

Ah, got it—that’ll work!

@LifeAdventurer go for it – I’ll mark you down on the list! Thanks!

Thanks! I'll get started on it now.

@chriskrycho While working on this, I noticed the changes in your PR #4060 for a different chapter and saw that a <span> tag might have been unintentionally left in the listing: https://github.com/rust-lang/book/blob/2399b906ca173c0fc23c71b0031cc9c75f1cd247/src/ch18-01-what-is-oo.md?plain=1#L61-L69

Also, both the text Listing 18-1: and Listing 18-2: still remain in the caption:

https://github.com/rust-lang/book/blob/2399b906ca173c0fc23c71b0031cc9c75f1cd247/src/ch18-01-what-is-oo.md?plain=1#L47 https://github.com/rust-lang/book/blob/2399b906ca173c0fc23c71b0031cc9c75f1cd247/src/ch18-01-what-is-oo.md?plain=1#L61

Could you check if they need to be removed? If needed, I can open another pull request to fix it.

Thanks for noting that, @LifeAdventurer – I went ahead and fixed it this morning, and am reviewing your PR for ch. 16 now!