Skip to content

Commit d376cba

Browse files
committed
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.
1 parent 1b57f6c commit d376cba

File tree

1 file changed

+2
-68
lines changed

1 file changed

+2
-68
lines changed

STYLE.md

+2-68
Original file line numberDiff line numberDiff line change
@@ -1,71 +1,5 @@
11
# Rust reference style guide
22

3-
Some conventions and content guidelines are specified in the [introduction].
4-
This document serves as a guide for editors and reviewers.
3+
See the [Authoring Guide] for details on the style used in the reference.
54

6-
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`.
7-
8-
## Markdown formatting
9-
10-
* Use ATX-style heading with sentence case.
11-
* Use one line per sentence to make diffs nicer.
12-
Do not wrap long lines.
13-
* Use reference links, with shortcuts if appropriate.
14-
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.
15-
16-
```
17-
Example of shortcut link: [enumerations]
18-
Example of reference link with label: [block expression][block]
19-
20-
[block]: expressions/block-expr.md
21-
[enumerations]: types/enum.md
22-
```
23-
24-
* Links should be relative with the `.md` extension.
25-
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.
26-
* See the [Conventions] section for formatting callouts such as notes, edition differences, and warnings.
27-
* Formatting to avoid:
28-
* Avoid trailing spaces.
29-
* Avoid double blank lines.
30-
31-
### Code examples
32-
33-
Code examples should use code blocks with triple backticks.
34-
The language should always be specified (such as `rust`).
35-
36-
```rust
37-
println!("Hello!");
38-
```
39-
40-
See https://highlightjs.org/ for a list of supported languages.
41-
42-
Rust examples are tested via rustdoc, and should include the appropriate annotations when tests are expected to fail:
43-
44-
* `edition2015` or `edition2018` --- If it is edition-specific (see `book.toml` for the default).
45-
* `no_run` --- The example should compile successfully, but should not be executed.
46-
* `should_panic` --- The example should compile and run, but produce a panic.
47-
* `compile_fail` --- The example is expected to fail to compile.
48-
* `ignore` --- The example shouldn't be built or tested.
49-
This should be avoided if possible.
50-
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.
51-
An HTML comment such as `<!-- ignore: requires extern crate -->` should be placed before the example to explain why it is ignored.
52-
53-
See the [rustdoc documentation] for more detail.
54-
55-
## Language and grammar
56-
57-
* Use American English spelling.
58-
* Use Oxford commas.
59-
* Idioms and styling to avoid:
60-
* Avoid slashes for alternatives ("program/binary"), use conjunctions or rewrite it ("program or binary").
61-
* Avoid qualifying something as "in Rust", the entire reference is about Rust.
62-
63-
## Content
64-
65-
* Whenever there is a difference between editions, the differences should be called out with an "Edition Differences" block.
66-
The main text should stick to what is common between the editions.
67-
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.
68-
69-
[conventions]: src/introduction.md#conventions
70-
[introduction]: src/introduction.md
71-
[rustdoc documentation]: https://doc.rust-lang.org/rustdoc/documentation-tests.html
5+
[Authoring Guide]: docs/authoring.md

0 commit comments

Comments
 (0)