From 73fbd4030a2c18fa674ac2db0aee69e70e433d88 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 27 Jun 2024 10:07:13 -0700 Subject: [PATCH 1/9] Start using mdbook-spec for the reference. This preprocessor adds support for several Markdown extensions that should assist with writing. --- README.md | 7 ++ book.toml | 2 + theme/reference.css | 166 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 175 insertions(+) diff --git a/README.md b/README.md index c52561736..ff75557c6 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ what we have for now. - Nightly Rust - [mdbook](https://rust-lang.github.io/mdBook/) +- [`mdbook-spec`](https://github.com/rust-lang/spec/tree/main/mdbook-spec) ## Installing dependencies @@ -29,6 +30,12 @@ build the Reference: cargo install --locked mdbook ``` +Also install `mdbook-spec` which is a preprocessor which adds some Markdown extensions: + +```sh +cargo install --locked mdbook-spec +``` + ## Building To build the Reference, first clone the project: diff --git a/book.toml b/book.toml index 505e0816d..3bafa2492 100644 --- a/book.toml +++ b/book.toml @@ -16,3 +16,5 @@ smart-punctuation = true [rust] edition = "2021" + +[preprocessor.spec] diff --git a/theme/reference.css b/theme/reference.css index 02e5f63df..8d000fbf0 100644 --- a/theme/reference.css +++ b/theme/reference.css @@ -1,3 +1,5 @@ +/* Custom CSS for the Rust Specification. */ + /* .parenthetical class used to keep e.g. "less-than symbol (<)" from wrapping the end parenthesis onto its own line. Use in a span between the last word and @@ -51,3 +53,167 @@ main .warning p::before { .ayu main .warning p a { color: #80d0d0; } + +/* tags can be used to highlight specific character elements. */ +kbd { + border: 1px solid #999; + display: inline-block; + border-radius: 3px; + padding: 0 0.6ex; + background: #eee; + box-shadow: inset -1px -1px 0 #999; + vertical-align: baseline; + color: #000; + height: 1.55em; + font-style: normal; + font-weight: bold; + font-family: inherit; + font-size: revert; + line-height: revert; +} +kbd.optional { + border-style: dashed; + background: #fff; +} +var.optional { + border-style: dashed; +} + +/* tags can be used for non-terminals. */ +var { + border: 1px solid #9c9; + box-shadow: inset -1px -1px 0 #9c9; + font-style: normal; + display: inline-block; + vertical-align: baseline; + border-radius: 7px; + padding: 0 4px; + background: #dfd; + margin: 2px; +} +var.type { + box-shadow: inset -1px -1px 0 #c99; + border-color: #c99; + background: #fdd; +} + +/* can be used for a grammar production that repeats zero or more times. */ +span.repeat { + position: relative; + border: 1px dashed #393; + border-radius: 10px; + display: inline-block; + padding: 6px; + margin-left: 0.5ex; + margin-top: 1em; + margin-bottom: 0.5ex; + min-width: 3.8em; + text-align: center; +} +span.repeat::before { + content: "zero or more"; + white-space: nowrap; + display: block; + text-align: center; + font-size: 0.75em; + position: absolute; + left: 0; + right: 0; + top: -1.4em; + color: #393; +} +var > span { + display: inline-block; + border-right: 1px dotted green; + padding-right: 0.5ex; + margin-right: 0.5ex; + font-style: italic; +} + +/* can be used to highlight a specific version of Rust. */ +span.version { + float: right; + margin-left: 1em; + margin-bottom: 1em; + background: #f7c0eb; + padding: 0.2ex 0.5ex; + border-radius: 5px; + display: block; + box-shadow: inset -1px -1px 0 #a06894; + font-size: 0.9em; +} + +/* tags are used to indicate a specific word or phrase is being defined. */ +dfn { + font-style: italic; + text-decoration: underline; +} + +.content main { + /* Provides space on the left for the rule call-outs. */ + padding-left: 4em; +} + +/* Rules are generated via r[foo.bar] syntax, processed by mdbook-spec. */ +.rule { + /* Allows the rule to be positioned. */ + position: relative; + /* Position slightly to the left. */ + left: -4em; + color: #999; + font-size: 0.8em; +} +/* mdbook will wrap the rule content in a

tag, with a margin. However, we + don't need the extra space +*/ +.rule ~ p { + margin-top: 0px; +} + +/* Change the default styling of blockquotes. */ +blockquote { + padding: 1ex 1em; + margin: 1ex; + margin-left: 2em; + /* vw units allow this to be adaptive to the screen size so it isn't too small on mobile. */ + margin-right: 12vw; +} + +/* mdbook will wrap the blockquote content in a

tag, with a margin. However, + that adds too much space, so remove it. +*/ +blockquote > p { + margin-top: 0px; + margin-bottom: 0px; +} + +/* When the sidebar is visible, reduce the spacing of rules so that the + content doesn't get shifted too far, and make the text too narrow. +*/ +.sidebar-visible .rule { + left: -1em; +} +.sidebar-visible .content main { + padding-left: 1em; +} + +/* Remove the blue coloring of links on rules that mdbook normally sets. */ +.rule-link { + color: #999 !important; +} + +/* When clicking a rule, it is added as a URL fragment and the browser will + navigate to it. This adds an indicator that the linked rule is the one that + is "current", just like normal headers are in mdbook. +*/ +.rule:target::before { + display: inline-block; + content: "»"; + margin-inline-start: -20px; + width: 20px; +} + +/* Sets the color for [!HISTORY] blockquote admonitions. */ +.history > blockquote { + background: #f7c0eb; +} From 850cdf43854c90154c07c708f972013461d011b4 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 1 Jul 2024 13:43:42 -0700 Subject: [PATCH 2/9] Copy the spec authoring guide over verbatim. The next commit will update to keep in sync with the reference. --- docs/authoring.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 docs/authoring.md diff --git a/docs/authoring.md b/docs/authoring.md new file mode 100644 index 000000000..f92b44231 --- /dev/null +++ b/docs/authoring.md @@ -0,0 +1,79 @@ +# Authoring Guide + +## Markdown formatting + +* Use [ATX-style headings][atx] (not Setext) with [sentence case]. +* Do not use tabs, only spaces. +* Files must end with a newline. +* Lines must not end with spaces. Double spaces have semantic meaning, but can be invisible. Use a trailing backslash if you need a hard line break. +* If possible, avoid double blank lines. +* Do not use indented code blocks, use 3+ backticks code blocks instead. +* Code blocks should have an explicit language tag. +* Do not wrap long lines. This helps with reviewing diffs of the source. +* Use [smart punctuation] instead of Unicode characters. For example, use `---` for em-dash instead of the Unicode character. Characters like em-dash can be difficult to see in a fixed-width editor, and some editors may not have easy methods to enter such characters. + +There are automated checks for some of these rules. Run `cargo run --manifest-path style-check/Cargo.toml -- spec` to run them locally. + +[atx]: https://spec.commonmark.org/0.31.2/#atx-headings +[sentence case]: https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case +[smart punctuation]: https://rust-lang.github.io/mdBook/format/markdown.html#smart-punctuation + +## Special markdown constructs + +### Rules + +Most clauses should be preceded with a rule. +Rules can be specified in the markdown source with the following on a line by itself: + +``` +r[foo.bar] +``` + +The rule name should be lowercase, with periods separating from most general to most specific (like `r[array.repeat.zero]`). + +Rules can be linked to by their ID using markdown such as `[foo.bar]`. There are automatic link references so that any rule can be referred to from any page in the book. + +In the HTML, the rules are clickable just like headers. + +### Standard library links + +You should link to the standard library without specifying a URL in a fashion similar to [rustdoc intra-doc links][intra]. Some examples: + +``` +Link to Option is [`std::option::Option`] + +You can include generics, they are ignored, like [`std::option::Option`] + +You can shorthand things if you don't want the full path in the text, +like [`Option`](std::option::Option). + +Macros can use `!`, which also works for disambiguation, +like [`alloc::vec!`] is the macro, not the module. + +Explicit namespace disambiguation is also supported, such as [`std::vec`](mod@std::vec). +``` + +[intra]: https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html + +### Admonitions + +Admonitions use a style similar to GitHub-flavored markdown, where the style name is placed at the beginning of a blockquote, such as: + +``` +> [!WARNING] +> This is a warning. +``` + +All this does is apply a CSS class to the blockquote. You should define the color or style of the rule in the `css/custom.css` file if it isn't already defined. + +## Content guidelines + +The following are guidelines for the content of the spec. + +### Targets + +The spec does not document which targets exist, or the properties of specific targets. The spec may refer to *platforms* or *target properties* where required by the language. Some examples: + +* Conditional-compilation keys like `target_os` are specified to exist, but not what their values must be. +* The `windows_subsystem` attribute specifies that it only works on Windows platforms. +* Inline assembly and the `target_feature` attribute specify the architectures that are supported. From b5966e99dbf676f1779fded7e7bf77a6f89fba0b Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 1 Jul 2024 13:53:37 -0700 Subject: [PATCH 3/9] Merge the Reference style guide to the authoring guide. --- CONTRIBUTING.md | 4 +-- docs/authoring.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 63 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8cf73c1fd..6a9fe6a16 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,7 +16,7 @@ enough that we can remove the warning. It is encouraged for you to read the [introduction] to familiarize yourself with the kind of content the reference is expected to contain and the -conventions it uses. Also, the [style guide] provides more detailed guidelines +conventions it uses. Also, the [Authoring Guide] provides more detailed guidelines for formatting and content. ## Critiquing the Reference @@ -72,5 +72,5 @@ helpful for writing the documentation. [issue tracker]: https://github.com/rust-lang/reference/issues [playpen]: https://play.rust-lang.org/ [rust-lang/rust]: https://github.com/rust-lang/rust/ -[style guide]: STYLE.md +[Authoring Guide]: docs/authoring.md [unstable]: https://doc.rust-lang.org/nightly/unstable-book/ diff --git a/docs/authoring.md b/docs/authoring.md index f92b44231..3a9200619 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -1,5 +1,10 @@ # Authoring Guide +This document serves as a guide for editors and reviewers. +Some conventions and content guidelines are specified in the [introduction]. + +[introduction]: ../src/introduction.md + ## Markdown formatting * Use [ATX-style headings][atx] (not Setext) with [sentence case]. @@ -11,15 +16,58 @@ * Code blocks should have an explicit language tag. * Do not wrap long lines. This helps with reviewing diffs of the source. * Use [smart punctuation] instead of Unicode characters. For example, use `---` for em-dash instead of the Unicode character. Characters like em-dash can be difficult to see in a fixed-width editor, and some editors may not have easy methods to enter such characters. +* Links should be relative with the `.md` extension. + Links to other rust-lang books that are published with the reference or the standard library API should also be relative so that the linkchecker can validate them. +* The use of reference links is preferred, with shortcuts if appropriate. + Place the sorted link reference definitions at the bottom of the file, or at the bottom of a section if there is an unusually large number of links that are specific to the section. + + ``` + Example of shortcut link: [enumerations] + Example of reference link with label: [block expression][block] -There are automated checks for some of these rules. Run `cargo run --manifest-path style-check/Cargo.toml -- spec` to run them locally. + [block]: expressions/block-expr.md + [enumerations]: types/enum.md + ``` +* See the [Conventions] section for formatting callouts such as notes, edition differences, and warnings. + +There are automated checks for some of these rules. Run `cargo run --manifest-path style-check/Cargo.toml -- src` to run them locally. [atx]: https://spec.commonmark.org/0.31.2/#atx-headings [sentence case]: https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case [smart punctuation]: https://rust-lang.github.io/mdBook/format/markdown.html#smart-punctuation +[conventions]: ../src/introduction.md#conventions + +### Code examples + +Code examples should use code blocks with triple backticks. +The language should always be specified (such as `rust`). + +```rust +println!("Hello!"); +``` + +See for a list of supported languages. + +Rust examples are tested via rustdoc, and should include the appropriate annotations when tests are expected to fail: + +* `edition2015` or `edition2018` — If it is edition-specific (see `book.toml` for the default). +* `no_run` — The example should compile successfully, but should not be executed. +* `should_panic` — The example should compile and run, but produce a panic. +* `compile_fail` — The example is expected to fail to compile. +* `ignore` — The example shouldn't be built or tested. + This should be avoided if possible. + Usually this is only necessary when the testing framework does not support it (such as external crates or modules, or a proc-macro), or it contains pseudo-code which is not valid Rust. + An HTML comment such as `` should be placed before the example to explain why it is ignored. +* `Exxxx` — If the example is expected to fail to compile with a specific error code, include that code so that rustdoc will check that the expected code is used. + +See the [rustdoc documentation] for more detail. + +[rustdoc documentation]: https://doc.rust-lang.org/rustdoc/documentation-tests.html ## Special markdown constructs +The following are extensions provided by [`mdbook-spec`](https://github.com/rust-lang/spec/tree/main/mdbook-spec). + ### Rules Most clauses should be preceded with a rule. @@ -66,6 +114,13 @@ Admonitions use a style similar to GitHub-flavored markdown, where the style nam All this does is apply a CSS class to the blockquote. You should define the color or style of the rule in the `css/custom.css` file if it isn't already defined. +## Style + +Idioms and styling to avoid: + +* Avoid slashes for alternatives ("program/binary"), use conjunctions or rewrite it ("program or binary"). +* Avoid qualifying something as "in Rust", the entire reference is about Rust. + ## Content guidelines The following are guidelines for the content of the spec. @@ -77,3 +132,8 @@ The spec does not document which targets exist, or the properties of specific ta * Conditional-compilation keys like `target_os` are specified to exist, but not what their values must be. * The `windows_subsystem` attribute specifies that it only works on Windows platforms. * Inline assembly and the `target_feature` attribute specify the architectures that are supported. + +### Editions + +The main text and flow should document only the current edition. +Whenever there is a difference between editions, the differences should be called out with an "Edition Differences" block. From 31555be3d98b083edcc4a73181ed03efa6bf35d9 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 1 Jul 2024 14:13:49 -0700 Subject: [PATCH 4/9] Update CI to use mdbook-spec --- .github/workflows/main.yml | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 219695210..227aeba5e 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -3,12 +3,25 @@ on: pull_request: merge_group: +env: + MDBOOK_VERSION: 0.4.40 + # When updating, be sure to also update rust-lang/rust. + MDBOOK_SPEC_VERSION: 0.1.0 + jobs: test: name: Test runs-on: ubuntu-latest steps: - uses: actions/checkout@master + - name: Cache + uses: actions/cache@v4 + with: + path: | + ~/.cargo/bin/ + ~/.cargo/.crates.toml + ~/.cargo/.crates2.json + key: ms-${MDBOOK_SPEC_VERSION} - name: Update rustup run: rustup self update - name: Install Rust @@ -19,13 +32,15 @@ jobs: - name: Install mdbook run: | mkdir bin - curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin + curl -sSL https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin echo "$(pwd)/bin" >> $GITHUB_PATH - name: Report versions run: | rustup --version rustc -Vv mdbook --version + - name: Install mdbook-spec + run: cargo install --locked mdbook-spec@${MDBOOK_SPEC_VERSION} - name: Run tests run: mdbook test - name: Style checks From a7a9a699e13112dc8cd6aa71e5f70a60417a34d2 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Thu, 4 Jul 2024 03:59:19 +0000 Subject: [PATCH 5/9] Sort link section alphabetically 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. --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6a9fe6a16..af811b2f5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -68,9 +68,9 @@ This should include links to any relevant information, such as the stabilization PR, the RFC, the tracking issue, and anything else that would be helpful for writing the documentation. +[Authoring Guide]: docs/authoring.md [introduction]: src/introduction.md [issue tracker]: https://github.com/rust-lang/reference/issues [playpen]: https://play.rust-lang.org/ [rust-lang/rust]: https://github.com/rust-lang/rust/ -[Authoring Guide]: docs/authoring.md [unstable]: https://doc.rust-lang.org/nightly/unstable-book/ From 6c5c9725ac502fa2908a2f66ef85834932581c3c Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Thu, 4 Jul 2024 04:02:19 +0000 Subject: [PATCH 6/9] Rewrap paragraph The CONTRIBUTING guide seems wrapped at 80 character lines. Let's rewrap a paragraph with a line that had overflowed. --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index af811b2f5..4877903d2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,10 +14,10 @@ for the Reference. As such, we have the warning saying there's work that needs to be done. Eventually, we plan to make sure everything is well documented enough that we can remove the warning. -It is encouraged for you to read the [introduction] to familiarize yourself -with the kind of content the reference is expected to contain and the -conventions it uses. Also, the [Authoring Guide] provides more detailed guidelines -for formatting and content. +It is encouraged for you to read the [introduction] to familiarize yourself with +the kind of content the reference is expected to contain and the conventions it +uses. Also, the [Authoring Guide] provides more detailed guidelines for +formatting and content. ## Critiquing the Reference From b82955c536bc2b0312c570c6e577744a71fec5e8 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Thu, 4 Jul 2024 04:49:01 +0000 Subject: [PATCH 7/9] Follow the authoring guide in the authoring guide 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. --- docs/authoring.md | 83 +++++++++++++++++++++++++---------------------- 1 file changed, 45 insertions(+), 38 deletions(-) diff --git a/docs/authoring.md b/docs/authoring.md index 3a9200619..beafaa3a5 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -1,7 +1,6 @@ # Authoring Guide -This document serves as a guide for editors and reviewers. -Some conventions and content guidelines are specified in the [introduction]. +This document serves as a guide for editors and reviewers. Some conventions and content guidelines are specified in the [introduction]. [introduction]: ../src/introduction.md @@ -12,16 +11,14 @@ Some conventions and content guidelines are specified in the [introduction]. * Files must end with a newline. * Lines must not end with spaces. Double spaces have semantic meaning, but can be invisible. Use a trailing backslash if you need a hard line break. * If possible, avoid double blank lines. -* Do not use indented code blocks, use 3+ backticks code blocks instead. +* Do not use indented code blocks; use 3+ backticks code blocks instead. * Code blocks should have an explicit language tag. * Do not wrap long lines. This helps with reviewing diffs of the source. * Use [smart punctuation] instead of Unicode characters. For example, use `---` for em-dash instead of the Unicode character. Characters like em-dash can be difficult to see in a fixed-width editor, and some editors may not have easy methods to enter such characters. -* Links should be relative with the `.md` extension. - Links to other rust-lang books that are published with the reference or the standard library API should also be relative so that the linkchecker can validate them. -* The use of reference links is preferred, with shortcuts if appropriate. - Place the sorted link reference definitions at the bottom of the file, or at the bottom of a section if there is an unusually large number of links that are specific to the section. +* Links should be relative with the `.md` extension. Links to other rust-lang books that are published with the reference or the standard library API should also be relative so that the linkchecker can validate them. +* The use of reference links is preferred, with shortcuts if appropriate. Place the sorted link reference definitions at the bottom of the file, or at the bottom of a section if there are an unusually large number of links that are specific to the section. - ``` + ```markdown Example of shortcut link: [enumerations] Example of reference link with label: [block expression][block] @@ -33,14 +30,13 @@ Some conventions and content guidelines are specified in the [introduction]. There are automated checks for some of these rules. Run `cargo run --manifest-path style-check/Cargo.toml -- src` to run them locally. [atx]: https://spec.commonmark.org/0.31.2/#atx-headings +[conventions]: ../src/introduction.md#conventions [sentence case]: https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case [smart punctuation]: https://rust-lang.github.io/mdBook/format/markdown.html#smart-punctuation -[conventions]: ../src/introduction.md#conventions ### Code examples -Code examples should use code blocks with triple backticks. -The language should always be specified (such as `rust`). +Code examples should use code blocks with triple backticks. The language should always be specified (such as `rust`). ```rust println!("Hello!"); @@ -48,17 +44,14 @@ println!("Hello!"); See for a list of supported languages. -Rust examples are tested via rustdoc, and should include the appropriate annotations when tests are expected to fail: +Rust examples are tested via rustdoc, and should include the appropriate annotations: -* `edition2015` or `edition2018` — If it is edition-specific (see `book.toml` for the default). -* `no_run` — The example should compile successfully, but should not be executed. -* `should_panic` — The example should compile and run, but produce a panic. -* `compile_fail` — The example is expected to fail to compile. -* `ignore` — The example shouldn't be built or tested. - This should be avoided if possible. - Usually this is only necessary when the testing framework does not support it (such as external crates or modules, or a proc-macro), or it contains pseudo-code which is not valid Rust. - An HTML comment such as `` should be placed before the example to explain why it is ignored. -* `Exxxx` — If the example is expected to fail to compile with a specific error code, include that code so that rustdoc will check that the expected code is used. +* `edition2015` or `edition2018` --- If it is edition-specific (see `book.toml` for the default). +* `no_run` --- The example should compile successfully, but should not be executed. +* `should_panic` --- The example should compile and run, but produce a panic. +* `compile_fail` --- The example is expected to fail to compile. +* `ignore` --- The example shouldn't be built or tested. This should be avoided if possible. Usually this is only necessary when the testing framework does not support it (such as external crates or modules, or a proc-macro), or it contains pseudo-code which is not valid Rust. An HTML comment such as `` should be placed before the example to explain why it is ignored. +* `Exxxx` --- If the example is expected to fail to compile with a specific error code, include that code so that rustdoc will check that the expected code is used. See the [rustdoc documentation] for more detail. @@ -70,10 +63,9 @@ The following are extensions provided by [`mdbook-spec`](https://github.com/rust ### Rules -Most clauses should be preceded with a rule. -Rules can be specified in the markdown source with the following on a line by itself: +Most clauses should be preceded with a rule. Rules can be specified in the markdown source with the following on a line by itself: -``` +```markdown r[foo.bar] ``` @@ -87,18 +79,34 @@ In the HTML, the rules are clickable just like headers. You should link to the standard library without specifying a URL in a fashion similar to [rustdoc intra-doc links][intra]. Some examples: +We can link to the page on `Option`: + +```markdown +[`std::option::Option`] ``` -Link to Option is [`std::option::Option`] -You can include generics, they are ignored, like [`std::option::Option`] +In these links, generics are ignored and can be included: -You can shorthand things if you don't want the full path in the text, -like [`Option`](std::option::Option). +```markdown +[`std::option::Option`] +``` -Macros can use `!`, which also works for disambiguation, -like [`alloc::vec!`] is the macro, not the module. +If we don't want the full path in the text, we can write: -Explicit namespace disambiguation is also supported, such as [`std::vec`](mod@std::vec). +```markdown +[`Option`](std::option::Option) +``` + +Macros can end in `!`. This can be helpful for disambiguation. For example, this refers to the macro rather than the module: + +```markdown +[`alloc::vec!`] +``` + +Explicit namespace disambiguation is also supported: + +```markdown +[`std::vec`](mod@std::vec) ``` [intra]: https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html @@ -107,7 +115,7 @@ Explicit namespace disambiguation is also supported, such as [`std::vec`](mod@st Admonitions use a style similar to GitHub-flavored markdown, where the style name is placed at the beginning of a blockquote, such as: -``` +```markdown > [!WARNING] > This is a warning. ``` @@ -118,16 +126,16 @@ All this does is apply a CSS class to the blockquote. You should define the colo Idioms and styling to avoid: -* Avoid slashes for alternatives ("program/binary"), use conjunctions or rewrite it ("program or binary"). -* Avoid qualifying something as "in Rust", the entire reference is about Rust. +* Avoid slashes for alternatives ("program/binary"); use conjunctions or rewrite it ("program or binary"). +* Avoid qualifying something as "in Rust"; the entire reference is about Rust. ## Content guidelines -The following are guidelines for the content of the spec. +The following are guidelines for the content of the reference. ### Targets -The spec does not document which targets exist, or the properties of specific targets. The spec may refer to *platforms* or *target properties* where required by the language. Some examples: +The reference does not document which targets exist, or the properties of specific targets. The reference may refer to *platforms* or *target properties* where required by the language. Some examples: * Conditional-compilation keys like `target_os` are specified to exist, but not what their values must be. * The `windows_subsystem` attribute specifies that it only works on Windows platforms. @@ -135,5 +143,4 @@ The spec does not document which targets exist, or the properties of specific ta ### Editions -The main text and flow should document only the current edition. -Whenever there is a difference between editions, the differences should be called out with an "Edition Differences" block. +The main text and flow should document only the current edition. Whenever there is a difference between editions, the differences should be called out with an "Edition Differences" block. From 1b57f6ca48f51a760d84df4d42b8f5927668f3c1 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Thu, 4 Jul 2024 04:55:59 +0000 Subject: [PATCH 8/9] Copy remaining style guidance to authoring guide 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. --- docs/authoring.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/authoring.md b/docs/authoring.md index beafaa3a5..256cb3082 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -126,6 +126,8 @@ All this does is apply a CSS class to the blockquote. You should define the colo Idioms and styling to avoid: +* Use American English spelling. +* Use Oxford commas. * Avoid slashes for alternatives ("program/binary"); use conjunctions or rewrite it ("program or binary"). * Avoid qualifying something as "in Rust"; the entire reference is about Rust. From d376cba3f93ac5c6876df21f4883b7b79df22be7 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Thu, 4 Jul 2024 04:59:54 +0000 Subject: [PATCH 9/9] Replace style guide with a link to the authoring guide The authoring guide now fully incorporates and supersedes the style guide, so let's simply link to that from the style guide. --- STYLE.md | 70 ++------------------------------------------------------ 1 file changed, 2 insertions(+), 68 deletions(-) diff --git a/STYLE.md b/STYLE.md index 977637b08..5a6488461 100644 --- a/STYLE.md +++ b/STYLE.md @@ -1,71 +1,5 @@ # Rust reference style guide -Some conventions and content guidelines are specified in the [introduction]. -This document serves as a guide for editors and reviewers. +See the [Authoring Guide] for details on the style used in the reference. -There is a [`style-check`](style-check/) tool which is run in CI to check some of these. To use it locally, run `cargo run --manifest-path=style-check/Cargo.toml src`. - -## Markdown formatting - -* Use ATX-style heading with sentence case. -* Use one line per sentence to make diffs nicer. - Do not wrap long lines. -* Use reference links, with shortcuts if appropriate. - Place the sorted link reference definitions at the bottom of the file, or at the bottom of a section if there is an unusually large number of links that are specific to the section. - - ``` - Example of shortcut link: [enumerations] - Example of reference link with label: [block expression][block] - - [block]: expressions/block-expr.md - [enumerations]: types/enum.md - ``` - -* Links should be relative with the `.md` extension. - Links to other rust-lang books that are published with the reference or the standard library API should also be relative so that the linkchecker can validate them. -* See the [Conventions] section for formatting callouts such as notes, edition differences, and warnings. -* Formatting to avoid: - * Avoid trailing spaces. - * Avoid double blank lines. - -### Code examples - -Code examples should use code blocks with triple backticks. -The language should always be specified (such as `rust`). - -```rust -println!("Hello!"); -``` - -See https://highlightjs.org/ for a list of supported languages. - -Rust examples are tested via rustdoc, and should include the appropriate annotations when tests are expected to fail: - -* `edition2015` or `edition2018` --- If it is edition-specific (see `book.toml` for the default). -* `no_run` --- The example should compile successfully, but should not be executed. -* `should_panic` --- The example should compile and run, but produce a panic. -* `compile_fail` --- The example is expected to fail to compile. -* `ignore` --- The example shouldn't be built or tested. - This should be avoided if possible. - Usually this is only necessary when the testing framework does not support it (such as external crates or modules, or a proc-macro), or it contains pseudo-code which is not valid Rust. - An HTML comment such as `` should be placed before the example to explain why it is ignored. - -See the [rustdoc documentation] for more detail. - -## Language and grammar - -* Use American English spelling. -* Use Oxford commas. -* Idioms and styling to avoid: - * Avoid slashes for alternatives ("program/binary"), use conjunctions or rewrite it ("program or binary"). - * Avoid qualifying something as "in Rust", the entire reference is about Rust. - -## Content - -* Whenever there is a difference between editions, the differences should be called out with an "Edition Differences" block. - The main text should stick to what is common between the editions. - However, for large differences (such as "async"), the main text may contain edition-specific content as long as it is made clear which editions it applies to. - -[conventions]: src/introduction.md#conventions -[introduction]: src/introduction.md -[rustdoc documentation]: https://doc.rust-lang.org/rustdoc/documentation-tests.html +[Authoring Guide]: docs/authoring.md