Description
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.
- 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 (@jpmelos – Convert ch04 to
<Listing>#4043) - Chapter 5 (@jpmelos – Convert ch05 to
<Listing>#4051) - Chapter 6 (@SpectralPixel – Convert Listings in Chapter 06 to
<Listing>#3977) - Chapter 7 (@SpectralPixel – Convert Listings in Chapter 07 to
<Listing>#3979) - Chapter 8 (@SpectralPixel – Convert Listings in Chapter 08 to
<Listing>#3981) - Chapter 9 (@SpectralPixel – Convert Listings in Chapter 09 to
<Listing>#3980) - Chapter 10 (@SpectralPixel – Convert Listings in Chapter 10 to
<Listing>#3978) - 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 – Use
<Listing>for Chapter 15 #4072) - Chapter 16 (@LifeAdventurer – Use
<Listing>preprocessor for chapter 16 #4066) - Chapter 17 (@chriskrycho did this from the start while writing the new chapter!)
- Chapter 18 (@chriskrycho – Use
<Listing>for final chapters (after restructuring) #4060) - Chapter 19 (@chriskrycho – Use
<Listing>for final chapters (after restructuring) #4060) - Chapter 20 (@chriskrycho – Use
<Listing>for final chapters (after restructuring) #4060) - Chapter 21 (@chriskrycho – Use
<Listing>for final chapters (after restructuring) #4060)