Block *everything*. We do not want any of this to be indexed, because we
*only* use it for previews, and do not want its content to be cached or
(especially!) surfaced to readers, since it may have a variety of issues
ranging from pedagogical missteps to outright errors!
- Swap the ordering to match the order in the text (concurrent is first,
at least for now).
- Make them go left-to-right instead of top-to-bottom for compactness in
the text.
- Fix rendering issues resulting from the VS Code extension doing things
that normal `dot` does not, for who knows what reasons.
- Drop the history lesson and comparisons to other approaches. Focus on
what async gives us instead.
- Simplify and clarify the
- Talk about “the network” instead of “network sockets” and simplify the
example code to match.
Use the original transitional paragraph and structure, adding to it
instead of rewriting it entirely.
HT @timClicks (Tim McNamara <paperless@timmcnamara.co.nz>) for pointing
out how my rephrasing here made it worse!
Note: this does *not* include all fixes for the text, only for the links
themselves. For the text, we will also need to search for references to
chapters 17-20. This catches a few of those along the way, but there are
no doubt others.
- Rewrite the `StreamExt` definition to be more correct, and extract it
to a standalone “no-listing listing” so we can make sure its
definition at least type checks.
- Update all the listings in the chapter to use `extern crate` since
`mdbook test` does not understand Rust 2018. Alas.
- Ignore the listings (inline or otherwise!) which are *intended* not to
compile, so mdbook does not try to test them.
- Clarify some of the text around the *actual* Tokio definition of the
`StreamExt::next` method.
- Update all the listings in the chapter to use `extern crate` since
`mdbook test` does not understand Rust 2018. Alas.
- Ignore a listing which has a missing body apurpose.
- Update all the listings in the chapter to use `extern crate` since
`mdbook test` does not understand Rust 2018. Alas.
- Fix one listing which had gotten out of sync somewhere along the way.
(This also fixes a comment flagged up by a reviewer!)
- Update all the listings in the chapter to use `extern crate` since
`mdbook test` does not understand Rust 2018. Alas.
- Ignore two of the listings because they never stop.
- Update the contents of the code in the chapter so it is correct, and
update the text to match. Given this is about `Future`, this may also
warrant moving/simplifying that whole chunk of code, too.
- Update the listing to use `extern crate` since it does not otherwise
work correctly with `mdbook test`. Alas.
mdBook does not currently have particularly good support for “external”
crates. To make the test suite work correctly with `trpl`, we must first
build `trpl` itself (`mdbook` will not do it), and then explicitly pass
its `deps` path as a library search path for `mdbook test`. That will
make sure all the crates can be resolved when running the tests.
.github/workflows/main.yml
XML does not allow more XML to appear in the body of an attribute, but
this is not XML! It is *HTML*, since Markdown allows embedding HTML, and
HTML *does* allow embedding further `<` and `>` characters within the
attributes on the element. Accordingly, switch to `html_parser`, add a
test covering this behavior, and update `ListingBuilder` to take the
number, caption, and file name types as owned rather than as references,
since that is what `html_parser` supplies.
Additionally, refactor the guts a bit so it is easy to see the overall
logic of `rewrite_listing`, with the gnarly bits around opening and
closing the rewritten listings pushed into a method on the `State`
struct, itself renamed to `ListingState` and its `current_listing` field
renamed to `current`. This also clarifies the semantics of each part of
the rewrite operation, e.g. `ListingState::open_listing` is fallible;
`ListingState::close_listing` is not.
When I originally built this, I thought *all* “listings” had numbers and
captions, but it turns out that there are a number of places in the book
where having the overall `figure`-driven output, i.e. with a file name,
is desirable even though there is no number or caption.
A potential enhancement later would be to require a caption if a number
is present, since that seems to be what the book actually does.
