Add mdbook-spec #1520

ehuss · 2024-07-01T21:28:04Z

This adds the use of mdbook-spec for the reference. The intent is to support some extensions that will help with the formatting that we eventually want to add, and to make authoring easier. Most of the changes are described in authoring.md.

This includes several changes split into separate commits. This includes a sync of the authoring document which was over in the rust-lang/spec repo.

This includes some tentative example changes in the CSS, but those will certainly want to change over time (particularly to support different theme colors). These aren't quite being used, yet. The current formatting of the reference should be identical as to before this PR. I will follow up with future PRs to do additional changes, such as removing explicit std links.

This will require some changes in rust-lang/rust in order to work properly, which I will handle before the next book sync.

This preprocessor adds support for several Markdown extensions that should assist with writing.

The next commit will update to keep in sync with the reference.

ehuss · 2024-07-02T22:32:27Z

For more context: It is noted that it is not optimal to have mdbook-spec in a separate repo. The reasons are complicated, due to the way the documentation is published. This is just intended as a short-term solution to unblock progress. Later I will try to figure out something so that we can move it to this repo and make it easier to develop and use.

This link section was already sorted but for a recent change (that understandably probably preferred to keep the diff contained). Let's restore the sort order of the links here.

The CONTRIBUTING guide seems wrapped at 80 character lines. Let's rewrap a paragraph with a line that had overflowed.

Let's follow our own rules in the authoring guide by, e.g., using `---` rather than the Unicode em-dash character, not wrapping lines, specifying the language for code block sections, etc. To improve formatting, we broke out some descriptions that were in code block sections into the main text. We replaced references to "the spec" with "the reference" for consistency, as that's what most of this document uses. And we made some other small editorial improvements.

These two items of style were the only bits present in the style guide and missing from the authoring guide. Let's copy them over, since they are true of the Reference, and this will let us delete the style guide entirely.

The authoring guide now fully incorporates and supersedes the style guide, so let's simply link to that from the style guide.

Update books ## rust-lang/book 3 commits in f1e49bf7a8ea6c31ce016a52b8a4f6e1ffcfbc64..67fa536768013d9d5a13f3a06790521d511ef711 2024-07-12 21:21:45 UTC to 2024-07-05 17:35:06 UTC - Use Rust 2021 Edition for mdBook (rust-lang/book#3974) - Backport changes to chapter 11 (rust-lang/book#3969) - Upgrade to Rust 1.79.0 (rust-lang/book#3968) ## rust-lang/edition-guide 2 commits in 941db8b3df45fd46cd87b50a5c86714b91dcde9c..5454de3d12b9ccc6375b629cf7ccda8264640aac 2024-07-14 07:06:34 UTC to 2024-07-12 06:05:29 UTC - Update timeline etc. for Rust 2024 - 2024: Add note about never_type_fallback_flowing_into_unsafe lint level. (rust-lang/edition-guide#311) ## rust-embedded/book 1 commits in b10c6acaf0f43481f6600e95d4b5013446e29f7a..019f3928d8b939ec71b63722dcc2e46330156441 2024-07-11 17:46:10 UTC to 2024-07-11 17:46:10 UTC - typo on tooling.md (rust-embedded/book#373) ## rust-lang/reference 9 commits in 1ae3deebc3ac16e276b6558e01420f8e605def08..e2f0bdc4031866734661dcdb548184bde1450baf 2024-06-29 16:59:51 +0000 to 2024-07-15 17:52:44 +0000 - Suppress type length limit test and note that it is not enforced (rust-lang/reference#1527) - elaborate on slice wide pointer metadata (rust-lang/reference#1499) - '.inst' in inline-assembly changed to '.insn' (rust-lang/reference#1453) - Clarify that `asm!` blocks can be duplicated or deduplicated by the compiler (rust-lang/reference#1441) - Add mdbook-spec (rust-lang/reference#1520) - Add note about static libraries not linking their dependencies (rust-lang/reference#1472) - more explicitly explain the UB around immutable extern statics (rust-lang/reference#1502) - Improvements to `items/functions.md` (rust-lang/reference#1458) - Enable mdbook smart-punctuation. (rust-lang/reference#1516) ## rust-lang/rust-by-example 1 commits in 658c6c27cb975b92227936024816986c2d3716fb..89aecb6951b77bc746da73df8c9f2b2ceaad494a 2024-07-11 12:33:43 UTC to 2024-07-11 12:33:43 UTC - Update option_result.md (rust-lang/rust-by-example#1864) ## rust-lang/rustc-dev-guide 6 commits in d6e3a32a557db5902e714604def8015d6bb7e0f7..0c4d55cb59fe440d1a630e4e5774d043968edb3f 2024-07-15 15:16:43 UTC to 2024-07-01 19:05:14 UTC - Improve documentation of MIR queries & passes (rust-lang/rustc-dev-guide#1434) - Bump dependencies for date-check tool (rust-lang/rustc-dev-guide#2012) - Fix typo: lists -> lints (rust-lang/rustc-dev-guide#2011) - use "bootstrap" instead of "rustbuild" (rust-lang/rustc-dev-guide#2010) - Fix grammar issue in optimize-build.md (rust-lang/rustc-dev-guide#2009) - Update name of Fuchsia builder (rust-lang/rustc-dev-guide#2008)

Rollup merge of rust-lang#127770 - rustbot:docs-update, r=ehuss Update books ## rust-lang/book 3 commits in f1e49bf7a8ea6c31ce016a52b8a4f6e1ffcfbc64..67fa536768013d9d5a13f3a06790521d511ef711 2024-07-12 21:21:45 UTC to 2024-07-05 17:35:06 UTC - Use Rust 2021 Edition for mdBook (rust-lang/book#3974) - Backport changes to chapter 11 (rust-lang/book#3969) - Upgrade to Rust 1.79.0 (rust-lang/book#3968) ## rust-lang/edition-guide 2 commits in 941db8b3df45fd46cd87b50a5c86714b91dcde9c..5454de3d12b9ccc6375b629cf7ccda8264640aac 2024-07-14 07:06:34 UTC to 2024-07-12 06:05:29 UTC - Update timeline etc. for Rust 2024 - 2024: Add note about never_type_fallback_flowing_into_unsafe lint level. (rust-lang/edition-guide#311) ## rust-embedded/book 1 commits in b10c6acaf0f43481f6600e95d4b5013446e29f7a..019f3928d8b939ec71b63722dcc2e46330156441 2024-07-11 17:46:10 UTC to 2024-07-11 17:46:10 UTC - typo on tooling.md (rust-embedded/book#373) ## rust-lang/reference 9 commits in 1ae3deebc3ac16e276b6558e01420f8e605def08..e2f0bdc4031866734661dcdb548184bde1450baf 2024-06-29 16:59:51 +0000 to 2024-07-15 17:52:44 +0000 - Suppress type length limit test and note that it is not enforced (rust-lang/reference#1527) - elaborate on slice wide pointer metadata (rust-lang/reference#1499) - '.inst' in inline-assembly changed to '.insn' (rust-lang/reference#1453) - Clarify that `asm!` blocks can be duplicated or deduplicated by the compiler (rust-lang/reference#1441) - Add mdbook-spec (rust-lang/reference#1520) - Add note about static libraries not linking their dependencies (rust-lang/reference#1472) - more explicitly explain the UB around immutable extern statics (rust-lang/reference#1502) - Improvements to `items/functions.md` (rust-lang/reference#1458) - Enable mdbook smart-punctuation. (rust-lang/reference#1516) ## rust-lang/rust-by-example 1 commits in 658c6c27cb975b92227936024816986c2d3716fb..89aecb6951b77bc746da73df8c9f2b2ceaad494a 2024-07-11 12:33:43 UTC to 2024-07-11 12:33:43 UTC - Update option_result.md (rust-lang/rust-by-example#1864) ## rust-lang/rustc-dev-guide 6 commits in d6e3a32a557db5902e714604def8015d6bb7e0f7..0c4d55cb59fe440d1a630e4e5774d043968edb3f 2024-07-15 15:16:43 UTC to 2024-07-01 19:05:14 UTC - Improve documentation of MIR queries & passes (rust-lang/rustc-dev-guide#1434) - Bump dependencies for date-check tool (rust-lang/rustc-dev-guide#2012) - Fix typo: lists -> lints (rust-lang/rustc-dev-guide#2011) - use "bootstrap" instead of "rustbuild" (rust-lang/rustc-dev-guide#2010) - Fix grammar issue in optimize-build.md (rust-lang/rustc-dev-guide#2009) - Update name of Fuchsia builder (rust-lang/rustc-dev-guide#2008)

ehuss added 4 commits July 2, 2024 13:42

Start using mdbook-spec for the reference.

73fbd40

This preprocessor adds support for several Markdown extensions that should assist with writing.

Copy the spec authoring guide over verbatim.

850cdf4

The next commit will update to keep in sync with the reference.

Merge the Reference style guide to the authoring guide.

b5966e9

Update CI to use mdbook-spec

31555be

ehuss force-pushed the mdbook-spec branch from ab6eabf to 31555be Compare July 2, 2024 20:43

traviscross added 5 commits July 4, 2024 03:59

Sort link section alphabetically

a7a9a69

This link section was already sorted but for a recent change (that understandably probably preferred to keep the diff contained). Let's restore the sort order of the links here.

Rewrap paragraph

6c5c972

The CONTRIBUTING guide seems wrapped at 80 character lines. Let's rewrap a paragraph with a line that had overflowed.

Copy remaining style guidance to authoring guide

1b57f6c

These two items of style were the only bits present in the style guide and missing from the authoring guide. Let's copy them over, since they are true of the Reference, and this will let us delete the style guide entirely.

Replace style guide with a link to the authoring guide

d376cba

The authoring guide now fully incorporates and supersedes the style guide, so let's simply link to that from the style guide.

traviscross approved these changes Jul 4, 2024

View reviewed changes

traviscross added this pull request to the merge queue Jul 4, 2024

Merged via the queue into rust-lang:master with commit aa99472 Jul 4, 2024
1 check passed

rustbot mentioned this pull request Jul 15, 2024

Update books rust-lang/rust#127770

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add mdbook-spec #1520

Add mdbook-spec #1520

ehuss commented Jul 1, 2024

ehuss commented Jul 2, 2024

Add mdbook-spec #1520

Add mdbook-spec #1520

Conversation

ehuss commented Jul 1, 2024

ehuss commented Jul 2, 2024