Convert all code listings to use new <Listing> preprocessor

[chriskrycho]

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.

---

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.

• Chapter 1 (@davidkurilla - Convert ch01-03-hello-cargo.md Listing 1-2 using <Listing> #3924)
• Chapter 2 (@davidkurilla – Convert ch02 and ch03 listings to <Listing> #3926)
• Chapter 3 (@davidkurilla – Convert ch02 and ch03 listings to <Listing> #3926)
• Chapter 4
• Chapter 5
• Chapter 6 (@SpectralPixel)
• Chapter 7 (@SpectralPixel)
• Chapter 8 (@SpectralPixel)
• Chapter 9 (@SpectralPixel)
• Chapter 10 (@SpectralPixel)
• Chapter 11 (@bzierk – Convert chapter 11 to use Listing component #3955)
• Chapter 12 (@bzierk – Convert Chapters 12-14 #3959)
• Chapter 13 (@bzierk – Convert Chapters 12-14 #3959)
• Chapter 14 (@bzierk – Convert Chapters 12-14 #3959)
• Chapter 15 (@bzierk)
• Chapter 16
• Chapter 17
• Chapter 18
• Chapter 19
• Chapter 20

[davidkurilla]

I'd like to help with chapter 1.

[davidkurilla]

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

[chriskrycho]

Very good! Thank you! 💙

[SpectralPixel]

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

[bzierk]

I am working on converting chapter 11.

[bzierk]

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]

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

[bzierk]

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]

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

[SpectralPixel]

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]

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

[chriskrycho]

@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!

[SpectralPixel]

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.

[SpectralPixel]

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

[chriskrycho]

@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!

[SpectralPixel]

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

[chriskrycho]

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