Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reformat (and only reformat) the inline assembly chapter #2

Merged
merged 1 commit into from
Dec 11, 2024

Conversation

Tiger0202
Copy link
Owner

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.

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.
@Tiger0202 Tiger0202 merged commit af118ad into Gankra-patch-1 Dec 11, 2024
0 of 2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant