| commit | 44cc4d93e954cc552080ec4e306ada57e490894a | [log] [tgz] |
|---|---|---|
| author | Travis Cross <tc@traviscross.com> | Sun Jul 28 00:09:57 2024 +0000 |
| committer | Travis Cross <tc@traviscross.com> | Tue Aug 06 06:12:29 2024 +0000 |
| tree | 8b5141cf4e1a90987ce88c68963e888cbb0d6710 | |
| parent | 2e191814f163ee1e77e2d6094eee4dd78a289c5b [diff] |
Reformat (and only reformat) the inline assembly chapter The go forward plan adopted by T-spec on 2024-06-13 includes, as one step, to reformat all of the chapters of the Reference to attach named identifiers to each claim, more or less. The resulting text will use the `mdbook-spec` extension for rendering (see PR #1542). Adding these named identifiers more granularly throughout the document is one step in allowing the Reference to be used as a specification for Rust in safety-critical applications. Per our plan, we want to reformat one chapter first, to ensure our happiness with that and to perfect our process, and to then reformat (and review and merge those reformattings of) all of the rest of the Reference chapters in the same way. We discussed and imagined that this reformatting would be somewhat mechanical, and that it could be done by a technical writer with limited experience with Rust. This is what gave us confidence that this work could be hired out, completed, and reviewed on the months-scale timeline that we had set out. As a demonstration of the first step in that plan, this PR performs *only* reformatting. That is, we add identifiers to each claim, more or less, *and nothing else*. We change *none* of the verbiage in this chapter. Our finding is that doing things this way works out fine. The original text was already organized reasonably well enough to just leave it in place and add the identifiers. There's always more that could be done to improve a chapter. E.g., perhaps some claims could be broken down further still and more identifiers added, though there is a distinct readability tradeoff here. We've tried to strike a reasonable balance in this PR. The point of the exercise contained in this PR is that this diff is straightforward to review and moves us in the direction that we want to go. We can always make other changes later, and by separating them out, those changes will be easier to review also. Note that we're unhappy with the current rendering when two identifiers need to be stacked, e.g.: ``` [asm] [asm.intro] ``` We'll plan to improve this later and separately with work in `mdbook-spec` or in the style sheets.
This document is the primary reference for the Rust programming language.
This document is not normative. It may include details that are specific to rustc itself, and should not be taken as a specification for the Rust language. We intend to produce such a document someday, but this is what we have for now.
First, ensure that you have a recent copy of the nightly Rust compiler installed, as this is needed in order to run the tests:
rustup toolchain install nightly
Now, ensure you have mdbook installed, as this is needed in order to build the Reference:
cargo install --locked mdbook
To build the Reference, first clone the project:
git clone https://github.com/rust-lang/reference.git
(Alternatively, if you don't want to use git, download a ZIP file of the project, extract it using your preferred tool, and rename the top-level directory to reference.)
Now change your current directory to the working directory:
cd reference
To test all of the code examples in the Reference, run:
mdbook test
For authors, consider using the server functionality which supports automatic reload.
To build the Reference locally (in build/) and open it in a web browser, run:
mdbook build --open
This will open a browser with a websocket live-link to automatically reload whenever the source is updated.
You can also open any current build of the reference by running:
mdbook serve --open