@@ -14,7 +14,7 @@ occasional maintenance tasks.
1414 does)
1515- Inspect the changes (by looking at the files changed according to git) and
1616 their effects (by looking at the files in ` tmp/book-before ` and
17- `tmp/book-after`) and commit them if they look good
17+ ` tmp/book-after ` ) and commit them if they look good
1818- Grep for ` manual-regeneration ` and follow the instructions in those places to
1919 update output that cannot be generated by a script
2020
@@ -36,9 +36,8 @@ create a new release artifact, for example if there have been code changes due
3636to edits or due to updating Rust and ` rustfmt ` , do the following:
3737
3838- Create a git tag for the release and push it to GitHub, or create a new tag
39- by going to the GitHub UI, [ drafting a new
40- release](https://github.com/rust-lang/book/releases/new), and entering a new
41- tag instead of selecting an existing tag
39+ by going to the GitHub UI, [ drafting a new release] ( https://github.com/rust-lang/book/releases/new ) , and entering a new
40+ tag instead of selecting an existing tag
4241- Run ` cargo run --bin release_listings ` , which will generate
4342 ` tmp/listings.tar.gz `
4443- Upload ` tmp/listings.tar.gz ` in the GitHub UI for the draft release
@@ -54,50 +53,50 @@ extracted into a file. To do that:
5453- Find where the new listing should go in the ` listings ` directory.
5554 - There is one subdirectory for each chapter
5655 - Numbered listings should use ` listing-[chapter num]-[listing num] ` for
57- their directory names.
56+ their directory names.
5857 - Listings without a number should start with ` no-listing- ` followed by a
59- number that indicates its position in the chapter relative to the other
60- listings without numbers in the chapter, then a short description that
61- someone could read to find the code they're looking for.
58+ number that indicates its position in the chapter relative to the other
59+ listings without numbers in the chapter, then a short description that
60+ someone could read to find the code they're looking for.
6261 - Listings used only for displaying the output of the code (for example, when
63- we say "if we had written x instead of y, we would get this compiler
64- error:" but we don't actually show code x) should be named with
65- `output-only-` followed by a number that indicates its position in the
66- chapter relative to the other listings used only for output, then a short
67- description that authors or contributors could read to find the code
68- they're looking for.
62+ we say "if we had written x instead of y, we would get this compiler
63+ error:" but we don't actually show code x) should be named with
64+ ` output-only- ` followed by a number that indicates its position in the
65+ chapter relative to the other listings used only for output, then a short
66+ description that authors or contributors could read to find the code
67+ they're looking for.
6968 - ** Remember to adjust surrounding listing numbers as appropriate!**
7069- Create a full Cargo project in that directory, either by using ` cargo new ` or
7170 copying another listing as a starting point.
7271- Add the code and any surrounding code needed to create a full working example.
7372- If you only want to show part of the code in the file, use anchor comments
7473 (` // ANCHOR: some_tag ` and ` // ANCHOR_END: some_tag ` ) to mark the parts of
75- the file you want to show.
74+ the file you want to show.
7675- For Rust code, use the ` {{#rustdoc_include [filename:some_tag]}} ` directive
7776 within the code blocks in the text. The ` rustdoc_include ` directive gives the
78- code that doesn't get displayed to `rustdoc` for `mdbook test` purposes.
77+ code that doesn't get displayed to ` rustdoc ` for ` mdbook test ` purposes.
7978- For anything else, use the ` {{#include [filename:some_tag]}} ` directive.
8079- If you want to display the output of a command in the text as well, create an
8180 ` output.txt ` file in the listing's directory as follows:
8281 - Run the command, like ` cargo run ` or ` cargo test ` , and copy all of the
83- output.
82+ output.
8483 - Create a new ` output.txt ` file with the first line `$ [ the command you
8584 ran]`.
8685 - Paste the output you just copied.
8786 - Run ` ./tools/update-rustc.sh ` , which should perform some normalization on
88- the compiler output.
87+ the compiler output.
8988 - Include the output in the text with the ` {{#include [filename]}} ` directive.
9089 - Add and commit output.txt.
9190- If you want to display output but for some reason it can't be generated by a
9291 script (say, because of user input or external events like making a web
93- request), keep the output inline but make a comment that contains
94- `manual-regeneration` and instructions for manually updating the inline
95- output.
92+ request), keep the output inline but make a comment that contains
93+ ` manual-regeneration ` and instructions for manually updating the inline
94+ output.
9695- If you don't want this example to even be attempted to be formatted by
9796 ` rustfmt ` (for example because the example doesn't parse on purpose), add a
98- `rustfmt-ignore` file in the listing's directory and the reason it's not
99- being formatted as the contents of that file (in case it's a rustfmt bug that
100- might get fixed someday).
97+ ` rustfmt-ignore ` file in the listing's directory and the reason it's not
98+ being formatted as the contents of that file (in case it's a rustfmt bug that
99+ might get fixed someday).
101100
102101## See the effect of some change on the rendered book
103102
0 commit comments