The book was located under 'src/doc/trpl' because originally, it was
going to be hosted under that URL. Late in the game, before 1.0, we
decided that /book was a better one, so we changed the output, but
not the input. This causes confusion for no good reason. So we'll change
the source directory to look like the output directory, like for every
other thing in src/doc.
When going through the docs, it is not clear that binary files cannot be tested. Additionally, it is hard to find the proper structure of a Rust crate and it took me several hours of looking through the docs to find the crates and modules section. I think we can link to it from here and it will be beneficial to those who are coming to the language.
We don't completely cover documentation tests in the testing chapter,
since we cover them in the documentation chapter. So make sure people
know that.
Fixes#28082
This adds strictly more information to the source files and reduces the
need for customized tooling to render the book.
(While this should not change the output of _rustbook_, it is very
useful when rendering the sources with external tools like Pandoc.)
Changes the style guidelines regarding unit tests to recommend using a
sub-module named "tests" instead of "test" for unit tests as "test"
might clash with imports of libtest.
Fixes#24030
Of the four code samples with modules in TRPL:
- 2 use `mod test`
- 2 use `mod tests`
We should be consistent here, but which is right? The stdlib is split:
$ grep -r 'mod tests {' src/lib* | wc -l
63
$ grep -r 'mod test {' src/lib* | wc -l
58
Subjectively, I like the plural, but both the language reference and the
style guide recommend the singular. So we'll go with that here, for now.
The documentation says that 'The current convention is to use the `test` module
to hold your "unit-style"' but then defines the module as "tests" instead.
Replaced outdated use of the `range(start, end)` function where
approriate with `start..end`, and tweaked the examples to compile and run with the latest rust. I also fixed two periphery compile issues in reference.md which were occluding whether there were any new errors created by these changes, so I fixed them.
This commit is an attempt to standardize the use of punctuation and
formatting in "The Rust Programming Language" as discussed in #19823.
- Convert bold text to italicized textcwhen referring to terminology.
- Convert single-quoted text to italicized or double-quoted text,
depending on context.
- Use double quotes only in the case of scare quotes or quotations.
