Skip to content

Commit

Permalink
Reformat (and only reformat) the inline assembly chapter
Browse files Browse the repository at this point in the history
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 things turned out, we were fortunate enough to hire someone with
significant experience with Rust.  This resulted in a PR that amounts
to a rewrite of the inline assembly chapter (see PR #1523).  Whatever
the virtues of that, it's not what we were expecting, and the degree
of change in one PR has complicated and stalled effective review.
This puts in jeopardy completion of the reformatting on the timeline
we had expected.

Consequently, this PR takes a different approach.  Here, we
perform *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.

Contra to earlier claims that this is not possible to do, our finding,
having done this, is that it works out fine.  The original text was
already organized reasonably well enough to just leave it in place and
add the identifiers.

Is this perfect?  Almost certainly not.  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.
  • Loading branch information
traviscross committed Jul 28, 2024
1 parent 2e19181 commit 51a8cd2
Showing 1 changed file with 156 additions and 2 deletions.
Loading

0 comments on commit 51a8cd2

Please sign in to comment.