Reformat (and only reformat) the inline assembly chapter

[traviscross]

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.

cc @rust-lang/spec @Amanieu

r? @ehuss

[traviscross]

@rfcbot fcp merge

We should decide via FCP whether, as a matter of process, we want the PRs for the remaining chapters to looks like this.¹ This isn't to say that we don't want other, later, PRs that may make more extensive changes. It's just to say that, as the first step, we want reformatting PRs whose diffs look like this, and that we want to see this for as many chapters of the Reference as possible.

That's what I propose that we should expect, and that's the consensus we'd be adopting here via this FCP.

Footnotes

1. We've discussed how there might be some chapters that are a total loss and might in fact just need to be deleted. We can set aside separately these "trashcan" chapters. ↩

[rfcbot]

Team member @traviscross has proposed to merge this. The next step is review by the rest of the tagged team members:

• @JoelMarcey
• @ehuss
• @m-ou-se
• @pnkfelix
• @traviscross

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[ehuss]

Checking my box since I will be away for a while.

A minor comment is that we should probably make a decision about using underscores or hyphens in the rule names. I can understand if a rule contains something that is literal in rust (like clobbers_abi) that it is natural to use underscores. My instinct is to just standardize on that, but I don't have a strong opinion. However, I do think we should have guidance to avoid inconsistent usage.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

psst @traviscross, I wasn't able to add the final-comment-period label, please do so.

[traviscross]

In our 2024-08-01 spec meeting, we agreed to use kebab-case for these identifiers except when including a literal token like global_asm or preserves_flags. This PR has now been updated accordingly.

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

psst @traviscross, I wasn't able to add the finished-final-comment-period label, please do so.