Commits on Aug 6, 2024

1. 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.

   

   traviscross committed Aug 6, 2024
   Configuration menu

   • View commit details
   • Copy full SHA for 44cc4d9
   • Browse repository at this point

   Copy the full SHA

   44cc4d9 View commit details

   Browse the repository at this point in the history