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.

Author: traviscross

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,32 +30,28 @@ 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!");
 ```
 
 See <https://rust-lang.github.io/mdBook/format/theme/syntax-highlighting.html#supported-languages> 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 `<!-- ignore: requires extern crate -->` 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 `<!-- ignore: requires extern crate -->` 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<T>`]
+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<T>`]
+```
 
-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,22 +126,21 @@ 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.
 * 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.
+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.