Previously, the error message from the compiler only suggested changing
the `impl` to use `&mut self`, but a (very helpful!) update to the error
message suggests changing both the `impl` and the `trait` definitions,
which is much better in the general case since changing one without the
other will just produce a new error message: a point the original text
points to with its suggestion to try and see what happens.
Account for the new error message by keeping the framing of the reason
as avoiding breaking the trait contract, but now explicitly in terms of
good testing habits.
Fixes#4140
Stop using the `pulldown-cmark` parser to rewrite the listings. Instead,
find the tags and parse them with the DOM parser, and then rewrite the
lines of the string directly.
Preprocessors using `pulldown-cmark-to-cmark` do not yet perform round
trips 100% correctly, and insert leading spaces and an extra initial `>`
for block quotes, so strip those. Once that is fixed upstream, this will
become a no-op, and can be removed then.
This (in principle) lets us get better support for round-tripping and
therefore less hoop-jumping to get the desired Markdown output after
preprocessing some text. This intentionally keeps the rendering the same
as it was on previous versions.
Instead of using `mdbook:new_cmark_parser`, provide our own utility
function which does the same thing. This allows us to preprocess the
text using versions of `pulldown-cmark` and `pulldown-cmark-to-cmark`
different from those used by `mdbook` itself so long as we take care
that the configuration continues to match.
Building on the shared infra from `mdbook_trpl`, this preprocessor takes
nicely accessible and semantic HTML input like this:
<figure>
<img src="https://www.example.com/something.jpg">
<figcaption>Figure 12-34: An illustration of something</figcaption>
</figure>
It produces output like this:
<img src="https://www.example.com/something.jpg">
Figure 12-34: An illustration of something
This matches what we need for the nostarch output. Accordingly, wire up
the `nostarch/book.toml` to use this. There is no need to worry about
ordering of the two preprocessors, because in `Simple` mode the listing
preprocessor emits plain text output for listings (much as this does for
figures).
- Create an `mdbook_trpl` library package which hosts shared concerns
for the packages, e.g. error and config handling.
- Move `mdbook-trpl-note` and `mdbook-trpl-listing` into the new shared
package, with binaries at `src/bin/(note|listing)/main.rs` and the
existing libraries at `src/note/mod.rs` and `src/listing/mod.rs` with
their associated tests.
- Extract their actual shared pieces into the crate root.
- Update `tools/nostarch.sh` to build all the bins in `mdbook_trpl` at
one time.
At the moment, this doesn't do a lot except trim down the number of
packages in the repository, but it sets things up nicely to support more
preprocessors (which I am going to add shortly).
Fix a garden-path expression that can be confusing for those who are familiar with referring to packages using dots, especially when English is a second language for the reader.
- Introduce the concept at the end of 18.2 when discussing the tradeoffs
of dynamic dispatch, with a link to the reference. The link is not
currently valid, because of the versioning timeline, but it will be
when this stabilizes!
- In 18.3, simply replace “object safe” with “dyn compatible”. There is
still probably not enough discussion of it, but with the introduction
and link in 18.2, it is *probably* enough for now?
This appears to still work with pulldown-cmark, but not necessarily in
all renderers, and (more to the point at present) is not compatible with
dprint, which does not like the line wrapping that way!
Multiple people have filed or commented on issues over the past few
years (at least #3782, #4101, #4090, and #3921; and possibly others I
have not found) because seeing “compare” here led them to jump ahead to
the conversion (in the next paragraph). The text was technically correct
as it stood, but since it kept derailing/hijacking people’s train of
thought, tweaking it seems helpful.
