From 66e1da76de885a86f224b47ce21b0ee2738975ef Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 26 Nov 2025 18:19:10 -0800 Subject: [PATCH 01/12] Unwrap the introduction --- src/introduction.md | 54 +++++++++++---------------------------------- 1 file changed, 13 insertions(+), 41 deletions(-) diff --git a/src/introduction.md b/src/introduction.md index d5eb4888a3..8fbcf3e2a8 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -7,64 +7,39 @@ This book is the primary reference for the Rust programming language. ## Rust releases -Rust has a new language release every six weeks. -The first stable release of the language was Rust 1.0.0, followed by Rust 1.1.0 and so on. -Tools (`rustc`, `cargo`, etc.) and documentation ([Standard library], this book, etc.) are released with the language release. +Rust has a new language release every six weeks. The first stable release of the language was Rust 1.0.0, followed by Rust 1.1.0 and so on. Tools (`rustc`, `cargo`, etc.) and documentation ([Standard library], this book, etc.) are released with the language release. -The latest release of this book, matching the latest Rust version, can always be found at . -Prior versions can be found by adding the Rust version before the "reference" directory. -For example, the Reference for Rust 1.49.0 is located at . +The latest release of this book, matching the latest Rust version, can always be found at . Prior versions can be found by adding the Rust version before the "reference" directory. For example, the Reference for Rust 1.49.0 is located at . ## What *The Reference* is not -This book does not serve as an introduction to the language. -Background familiarity with the language is assumed. -A separate [book] is available to help acquire such background familiarity. +This book does not serve as an introduction to the language. Background familiarity with the language is assumed. A separate [book] is available to help acquire such background familiarity. -This book also does not serve as a reference to the [standard library] included in the language distribution. -Those libraries are documented separately by extracting documentation attributes from their source code. -Many of the features that one might expect to be language features are library features in Rust, so what you're looking for may be there, not here. +This book also does not serve as a reference to the [standard library] included in the language distribution. Those libraries are documented separately by extracting documentation attributes from their source code. Many of the features that one might expect to be language features are library features in Rust, so what you're looking for may be there, not here. -Similarly, this book does not usually document the specifics of `rustc` as a tool or of Cargo. -`rustc` has its own [book][rustc book]. -Cargo has a [book][cargo book] that contains a [reference][cargo reference]. -There are a few pages such as [linkage] that still describe how `rustc` works. +Similarly, this book does not usually document the specifics of `rustc` as a tool or of Cargo. `rustc` has its own [book][rustc book]. Cargo has a [book][cargo book] that contains a [reference][cargo reference]. There are a few pages such as [linkage] that still describe how `rustc` works. -This book also only serves as a reference to what is available in stable Rust. -For unstable features being worked on, see the [Unstable Book]. +This book also only serves as a reference to what is available in stable Rust. For unstable features being worked on, see the [Unstable Book]. -Rust compilers, including `rustc`, will perform optimizations. -The reference does not specify what optimizations are allowed or disallowed. -Instead, think of the compiled program as a black box. -You can only probe by running it, feeding it input and observing its output. -Everything that happens that way must conform to what the reference says. +Rust compilers, including `rustc`, will perform optimizations. The reference does not specify what optimizations are allowed or disallowed. Instead, think of the compiled program as a black box. You can only probe by running it, feeding it input and observing its output. Everything that happens that way must conform to what the reference says. ## How to use this book -This book does not assume you are reading this book sequentially. -Each chapter generally can be read standalone, but will cross-link to other chapters for facets of the language they refer to, but do not discuss. +This book does not assume you are reading this book sequentially. Each chapter generally can be read standalone, but will cross-link to other chapters for facets of the language they refer to, but do not discuss. There are two main ways to read this document. -The first is to answer a specific question. -If you know which chapter answers that question, you can jump to that chapter in the table of contents. -Otherwise, you can press `s` or click the magnifying glass on the top bar to search for keywords related to your question. -For example, say you wanted to know when a temporary value created in a let statement is dropped. -If you didn't already know that the [lifetime of temporaries] is defined in the [expressions chapter], you could search "temporary let" and the first search result will take you to that section. +The first is to answer a specific question. If you know which chapter answers that question, you can jump to that chapter in the table of contents. Otherwise, you can press `s` or click the magnifying glass on the top bar to search for keywords related to your question. For example, say you wanted to know when a temporary value created in a let statement is dropped. If you didn't already know that the [lifetime of temporaries] is defined in the [expressions chapter], you could search "temporary let" and the first search result will take you to that section. -The second is to generally improve your knowledge of a facet of the language. -In that case, just browse the table of contents until you see something you want to know more about, and just start reading. -If a link looks interesting, click it, and read about that section. +The second is to generally improve your knowledge of a facet of the language. In that case, just browse the table of contents until you see something you want to know more about, and just start reading. If a link looks interesting, click it, and read about that section. That said, there is no wrong way to read this book. Read it however you feel helps you best. ### Conventions -Like all technical books, this book has certain conventions in how it displays information. -These conventions are documented here. +Like all technical books, this book has certain conventions in how it displays information. These conventions are documented here. -* Statements that define a term contain that term in *italics*. - Whenever that term is used outside of that chapter, it is usually a link to the section that has this definition. +* Statements that define a term contain that term in *italics*. Whenever that term is used outside of that chapter, it is usually a link to the section that has this definition. An *example term* is an example of a term being defined. @@ -122,10 +97,7 @@ r[example.rule.label] We welcome contributions of all kinds. -You can contribute to this book by opening an issue or sending a pull request to [the Rust Reference repository]. -If this book does not answer your question, and you think its answer is in scope of it, please do not hesitate to [file an issue] or ask about it in the `t-lang/doc` stream on [Zulip]. -Knowing what people use this book for the most helps direct our attention to making those sections the best that they can be. -And of course, if you see anything that is wrong or is non-normative but not specifically called out as such, please also [file an issue]. +You can contribute to this book by opening an issue or sending a pull request to [the Rust Reference repository]. If this book does not answer your question, and you think its answer is in scope of it, please do not hesitate to [file an issue] or ask about it in the `t-lang/doc` stream on [Zulip]. Knowing what people use this book for the most helps direct our attention to making those sections the best that they can be. And of course, if you see anything that is wrong or is non-normative but not specifically called out as such, please also [file an issue]. [book]: ../book/index.html [github issues]: https://github.com/rust-lang/reference/issues From fba425ccf9f960aa89c7ed8eeb04fbc7806d966d Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 26 Nov 2025 18:21:21 -0800 Subject: [PATCH 02/12] Extend intro, and move bug note This elaborates the intro a little, and moves the bug note (since I do not consider it to be so important to be at the very beginning). --- src/introduction.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/introduction.md b/src/introduction.md index 8fbcf3e2a8..545a6c3473 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -1,9 +1,6 @@ # Introduction -This book is the primary reference for the Rust programming language. - -> [!NOTE] -> For known bugs and omissions in this book, see our [GitHub issues]. If you see a case where the compiler behavior and the text here do not agree, file an issue so we can think about which is correct. +This book is the primary reference for the Rust programming language. It serves as a description of the syntax, semantics, and interpretation of the Rust language. ## Rust releases @@ -35,6 +32,9 @@ The second is to generally improve your knowledge of a facet of the language. In That said, there is no wrong way to read this book. Read it however you feel helps you best. +> [!NOTE] +> For known bugs and omissions in this book, see our [GitHub issues]. If you see a case where the compiler behavior and the text here do not agree, file an issue so we can think about which is correct. + ### Conventions Like all technical books, this book has certain conventions in how it displays information. These conventions are documented here. From b38e2bc46292c23262c7509fe63e2e9cdd069a89 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 26 Nov 2025 18:22:34 -0800 Subject: [PATCH 03/12] Sort introduction links --- src/introduction.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/introduction.md b/src/introduction.md index 545a6c3473..568c8b4228 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -100,17 +100,17 @@ We welcome contributions of all kinds. You can contribute to this book by opening an issue or sending a pull request to [the Rust Reference repository]. If this book does not answer your question, and you think its answer is in scope of it, please do not hesitate to [file an issue] or ask about it in the `t-lang/doc` stream on [Zulip]. Knowing what people use this book for the most helps direct our attention to making those sections the best that they can be. And of course, if you see anything that is wrong or is non-normative but not specifically called out as such, please also [file an issue]. [book]: ../book/index.html -[github issues]: https://github.com/rust-lang/reference/issues -[standard library]: std -[the Rust Reference repository]: https://github.com/rust-lang/reference/ -[Unstable Book]: https://doc.rust-lang.org/nightly/unstable-book/ [cargo book]: ../cargo/index.html [cargo reference]: ../cargo/reference/index.html [example rule]: example.rule.label [expressions chapter]: expressions.html [file an issue]: https://github.com/rust-lang/reference/issues +[github issues]: https://github.com/rust-lang/reference/issues [lifetime of temporaries]: expressions.html#temporaries [linkage]: linkage.html -[rustc book]: ../rustc/index.html [Notation]: notation.md +[rustc book]: ../rustc/index.html +[standard library]: std +[the Rust Reference repository]: https://github.com/rust-lang/reference/ +[Unstable Book]: https://doc.rust-lang.org/nightly/unstable-book/ [Zulip]: https://rust-lang.zulipchat.com/#narrow/stream/237824-t-lang.2Fdoc From 6bb6382c252b9e73a6dd90be6256fabce87bd55c Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 27 Nov 2025 06:44:35 -0800 Subject: [PATCH 04/12] Add the audience This describes who the Reference is for. This links to the upcoming scope chapter which is in a future commit. Closes https://github.com/rust-lang/reference/issues/550 --- src/introduction.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/introduction.md b/src/introduction.md index 568c8b4228..af3b738ed7 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -2,6 +2,16 @@ This book is the primary reference for the Rust programming language. It serves as a description of the syntax, semantics, and interpretation of the Rust language. +## Audience + +The audience for this book includes: + +- Rust users who want to learn about the specifics and details of the language. +- Tool developers who need to know the syntax and semantics of the language. +- Language designers who work on the evolution of the language. + +See the [scope chapter] for a detailed explanation of what constitutes the Reference. + ## Rust releases Rust has a new language release every six weeks. The first stable release of the language was Rust 1.0.0, followed by Rust 1.1.0 and so on. Tools (`rustc`, `cargo`, etc.) and documentation ([Standard library], this book, etc.) are released with the language release. @@ -110,6 +120,7 @@ You can contribute to this book by opening an issue or sending a pull request to [linkage]: linkage.html [Notation]: notation.md [rustc book]: ../rustc/index.html +[scope chapter]: scope.md [standard library]: std [the Rust Reference repository]: https://github.com/rust-lang/reference/ [Unstable Book]: https://doc.rust-lang.org/nightly/unstable-book/ From afcfa09066cdb64653ebd512f2491b1cc8eedbaf Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 27 Nov 2025 07:02:33 -0800 Subject: [PATCH 05/12] Rename notation to "grammar notation" This is in preparation to rearrange notational conventions. This chapter *only* deals with grammar, so let's be explicit about that. --- src/SUMMARY.md | 2 +- src/notation.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index c3786707fa..e8f91a2945 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -2,7 +2,7 @@ [Introduction](introduction.md) -- [Notation](notation.md) +- [Grammar notation](notation.md) - [Lexical structure](lexical-structure.md) - [Input format](input-format.md) diff --git a/src/notation.md b/src/notation.md index e88679220c..bc6c8be2b0 100644 --- a/src/notation.md +++ b/src/notation.md @@ -1,5 +1,5 @@ r[notation] -# Notation +# Grammar notation r[notation.grammar] ## Grammar From 9743740741270c8c44b5f6f7e6aa350f03a6f712 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 27 Nov 2025 07:06:39 -0800 Subject: [PATCH 06/12] Move conventions to a dedicated chapter The intent here is to tie together the different conventions used in the book (with the grammar), and to provide a more focused place to house this content. I've also noticed this is a more common approach to including this kind of content. --- src/SUMMARY.md | 3 ++- src/conventions.md | 59 +++++++++++++++++++++++++++++++++++++++++++++ src/introduction.md | 59 --------------------------------------------- 3 files changed, 61 insertions(+), 60 deletions(-) create mode 100644 src/conventions.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index e8f91a2945..8d1f1f2235 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -2,7 +2,8 @@ [Introduction](introduction.md) -- [Grammar notation](notation.md) +- [Notational conventions](conventions.md) + - [Grammar notation](notation.md) - [Lexical structure](lexical-structure.md) - [Input format](input-format.md) diff --git a/src/conventions.md b/src/conventions.md new file mode 100644 index 0000000000..d805432ae6 --- /dev/null +++ b/src/conventions.md @@ -0,0 +1,59 @@ +# Notational conventions + +## Conventions + +Like all technical books, this book has certain conventions in how it displays information. These conventions are documented here. + +* Statements that define a term contain that term in *italics*. Whenever that term is used outside of that chapter, it is usually a link to the section that has this definition. + + An *example term* is an example of a term being defined. + +* The main text describes the latest stable edition. Differences to previous editions are separated in edition blocks: + + > [!EDITION-2018] + > Before the 2018 edition, the behavior was this. As of the 2018 edition, the behavior is that. + +* Notes that contain useful information about the state of the book or point out useful, but mostly out of scope, information are in note blocks. + + > [!NOTE] + > This is an example note. + +* Example blocks show an example that demonstrates some rule or points out some interesting aspect. Some examples may have hidden lines which can be viewed by clicking the eye icon that appears when hovering or tapping the example. + + > [!EXAMPLE] + > This is a code example. + > ```rust + > println!("hello world"); + > ``` + +* Warnings that show unsound behavior in the language or possibly confusing interactions of language features are in a special warning box. + + > [!WARNING] + > This is an example warning. + +* Code snippets inline in the text are inside `` tags. + + Longer code examples are in a syntax highlighted box that has controls for copying, executing, and showing hidden lines in the top right corner. + + ```rust + # // This is a hidden line. + fn main() { + println!("This is a code example"); + } + ``` + + All examples are written for the latest edition unless otherwise stated. + +* The grammar and lexical productions are described in the [Notation] chapter. + +r[example.rule.label] +* Rule identifiers appear before each language rule enclosed in square brackets. These identifiers provide a way to refer to and link to a specific rule in the language ([e.g.][example rule]). The rule identifier uses periods to separate sections from most general to most specific ([destructors.scope.nesting.function-body] for example). On narrow screens, the rule name will collapse to display `[*]`. + + The rule name can be clicked to link to that rule. + + > [!WARNING] + > The organization of the rules is currently in flux. For the time being, these identifier names are not stable between releases, and links to these rules may fail if they are changed. We intend to stabilize these once the organization has settled so that links to the rule names will not break between releases. + +* Rules that have associated tests will include a `Tests` link below them (on narrow screens, the link is `[T]`). Clicking the link will pop up a list of tests, which can be clicked to view the test. For example, see [input.encoding.utf8]. + + Linking rules to tests is an ongoing effort. See the [Test summary](test-summary.md) chapter for an overview. diff --git a/src/introduction.md b/src/introduction.md index af3b738ed7..fdd9466a08 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -45,64 +45,6 @@ That said, there is no wrong way to read this book. Read it however you feel hel > [!NOTE] > For known bugs and omissions in this book, see our [GitHub issues]. If you see a case where the compiler behavior and the text here do not agree, file an issue so we can think about which is correct. -### Conventions - -Like all technical books, this book has certain conventions in how it displays information. These conventions are documented here. - -* Statements that define a term contain that term in *italics*. Whenever that term is used outside of that chapter, it is usually a link to the section that has this definition. - - An *example term* is an example of a term being defined. - -* The main text describes the latest stable edition. Differences to previous editions are separated in edition blocks: - - > [!EDITION-2018] - > Before the 2018 edition, the behavior was this. As of the 2018 edition, the behavior is that. - -* Notes that contain useful information about the state of the book or point out useful, but mostly out of scope, information are in note blocks. - - > [!NOTE] - > This is an example note. - -* Example blocks show an example that demonstrates some rule or points out some interesting aspect. Some examples may have hidden lines which can be viewed by clicking the eye icon that appears when hovering or tapping the example. - - > [!EXAMPLE] - > This is a code example. - > ```rust - > println!("hello world"); - > ``` - -* Warnings that show unsound behavior in the language or possibly confusing interactions of language features are in a special warning box. - - > [!WARNING] - > This is an example warning. - -* Code snippets inline in the text are inside `` tags. - - Longer code examples are in a syntax highlighted box that has controls for copying, executing, and showing hidden lines in the top right corner. - - ```rust - # // This is a hidden line. - fn main() { - println!("This is a code example"); - } - ``` - - All examples are written for the latest edition unless otherwise stated. - -* The grammar and lexical productions are described in the [Notation] chapter. - -r[example.rule.label] -* Rule identifiers appear before each language rule enclosed in square brackets. These identifiers provide a way to refer to and link to a specific rule in the language ([e.g.][example rule]). The rule identifier uses periods to separate sections from most general to most specific ([destructors.scope.nesting.function-body] for example). On narrow screens, the rule name will collapse to display `[*]`. - - The rule name can be clicked to link to that rule. - - > [!WARNING] - > The organization of the rules is currently in flux. For the time being, these identifier names are not stable between releases, and links to these rules may fail if they are changed. We intend to stabilize these once the organization has settled so that links to the rule names will not break between releases. - -* Rules that have associated tests will include a `Tests` link below them (on narrow screens, the link is `[T]`). Clicking the link will pop up a list of tests, which can be clicked to view the test. For example, see [input.encoding.utf8]. - - Linking rules to tests is an ongoing effort. See the [Test summary](test-summary.md) chapter for an overview. - ## Contributing We welcome contributions of all kinds. @@ -112,7 +54,6 @@ You can contribute to this book by opening an issue or sending a pull request to [book]: ../book/index.html [cargo book]: ../cargo/index.html [cargo reference]: ../cargo/reference/index.html -[example rule]: example.rule.label [expressions chapter]: expressions.html [file an issue]: https://github.com/rust-lang/reference/issues [github issues]: https://github.com/rust-lang/reference/issues From c7eb5ad15e97f10b62026d0704804aabf284dcc2 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 27 Nov 2025 07:13:59 -0800 Subject: [PATCH 07/12] Reorganize conventions This changes the conventions chapter to use sections instead of a list. It also rearranges the order into something that for whatever reason seems a little more logical to me. --- src/conventions.md | 88 +++++++++++++++++++++++++++------------------ src/introduction.md | 1 - 2 files changed, 54 insertions(+), 35 deletions(-) diff --git a/src/conventions.md b/src/conventions.md index d805432ae6..2cc5724345 100644 --- a/src/conventions.md +++ b/src/conventions.md @@ -4,56 +4,76 @@ Like all technical books, this book has certain conventions in how it displays information. These conventions are documented here. -* Statements that define a term contain that term in *italics*. Whenever that term is used outside of that chapter, it is usually a link to the section that has this definition. +## Rules - An *example term* is an example of a term being defined. +r[example.rule.label] +Rule identifiers appear before each language rule enclosed in square brackets. These identifiers provide a way to refer to and link to a specific rule in the language ([e.g.][example rule]). The rule identifier uses periods to separate sections from most general to most specific ([destructors.scope.nesting.function-body] for example). On narrow screens, the rule name will collapse to display `[*]`. -* The main text describes the latest stable edition. Differences to previous editions are separated in edition blocks: +The rule name can be clicked to link to that rule. - > [!EDITION-2018] - > Before the 2018 edition, the behavior was this. As of the 2018 edition, the behavior is that. +> [!WARNING] +> The organization of the rules is currently in flux. For the time being, these identifier names are not stable between releases, and links to these rules may fail if they are changed. We intend to stabilize these once the organization has settled so that links to the rule names will not break between releases. -* Notes that contain useful information about the state of the book or point out useful, but mostly out of scope, information are in note blocks. +### Rule tests - > [!NOTE] - > This is an example note. +Rules that have associated tests will include a `Tests` link below them (on narrow screens, the link is `[T]`). Clicking the link will pop up a list of tests, which can be clicked to view the test. For example, see [input.encoding.utf8]. -* Example blocks show an example that demonstrates some rule or points out some interesting aspect. Some examples may have hidden lines which can be viewed by clicking the eye icon that appears when hovering or tapping the example. +Linking rules to tests is an ongoing effort. See the [Test summary](test-summary.md) chapter for an overview. - > [!EXAMPLE] - > This is a code example. - > ```rust - > println!("hello world"); - > ``` +## Definitions -* Warnings that show unsound behavior in the language or possibly confusing interactions of language features are in a special warning box. +Statements that define a term contain that term in *italics*. Whenever that term is used outside of that chapter, it is usually a link to the section that has this definition. - > [!WARNING] - > This is an example warning. +An *example term* is an example of a term being defined. -* Code snippets inline in the text are inside `` tags. +## Examples - Longer code examples are in a syntax highlighted box that has controls for copying, executing, and showing hidden lines in the top right corner. +Example blocks show an example that demonstrates some rule or points out some interesting aspect. Some examples may have hidden lines which can be viewed by clicking the eye icon that appears when hovering or tapping the example. - ```rust - # // This is a hidden line. - fn main() { - println!("This is a code example"); - } - ``` +> [!EXAMPLE] +> This is a code example. +> ```rust +> println!("hello world"); +> ``` - All examples are written for the latest edition unless otherwise stated. +## Code blocks -* The grammar and lexical productions are described in the [Notation] chapter. +Code snippets inline in the text are inside `` tags. -r[example.rule.label] -* Rule identifiers appear before each language rule enclosed in square brackets. These identifiers provide a way to refer to and link to a specific rule in the language ([e.g.][example rule]). The rule identifier uses periods to separate sections from most general to most specific ([destructors.scope.nesting.function-body] for example). On narrow screens, the rule name will collapse to display `[*]`. +Longer code examples are in a syntax highlighted box that has controls for copying, executing, and showing hidden lines in the top right corner. + +```rust +# // This is a hidden line. +fn main() { + println!("This is a code example"); +} +``` + +All examples are written for the latest edition unless otherwise stated. + +## Grammar + +The grammar and lexical productions are described in the [Notation] chapter. + +## Notes + +Notes that contain useful information about the state of the book or point out useful, but mostly out of scope, information are in note blocks. + +> [!NOTE] +> This is an example note. + +## Warnings + +Warnings that show unsound behavior in the language or possibly confusing interactions of language features are in a special warning box. + +> [!WARNING] +> This is an example warning. - The rule name can be clicked to link to that rule. +## Editions - > [!WARNING] - > The organization of the rules is currently in flux. For the time being, these identifier names are not stable between releases, and links to these rules may fail if they are changed. We intend to stabilize these once the organization has settled so that links to the rule names will not break between releases. +The main text describes the latest stable edition. Differences to previous editions are separated in edition blocks: -* Rules that have associated tests will include a `Tests` link below them (on narrow screens, the link is `[T]`). Clicking the link will pop up a list of tests, which can be clicked to view the test. For example, see [input.encoding.utf8]. +> [!EDITION-2018] +> Before the 2018 edition, the behavior was this. As of the 2018 edition, the behavior is that. - Linking rules to tests is an ongoing effort. See the [Test summary](test-summary.md) chapter for an overview. +[example rule]: example.rule.label diff --git a/src/introduction.md b/src/introduction.md index fdd9466a08..b8b116584d 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -59,7 +59,6 @@ You can contribute to this book by opening an issue or sending a pull request to [github issues]: https://github.com/rust-lang/reference/issues [lifetime of temporaries]: expressions.html#temporaries [linkage]: linkage.html -[Notation]: notation.md [rustc book]: ../rustc/index.html [scope chapter]: scope.md [standard library]: std From 54ccc85fb59e36250e386579a1808c2c68d8a3a4 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 27 Nov 2025 07:19:11 -0800 Subject: [PATCH 08/12] Apply some light edits to the conventions chapter --- src/conventions.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/src/conventions.md b/src/conventions.md index 2cc5724345..aac51ac865 100644 --- a/src/conventions.md +++ b/src/conventions.md @@ -7,7 +7,7 @@ Like all technical books, this book has certain conventions in how it displays i ## Rules r[example.rule.label] -Rule identifiers appear before each language rule enclosed in square brackets. These identifiers provide a way to refer to and link to a specific rule in the language ([e.g.][example rule]). The rule identifier uses periods to separate sections from most general to most specific ([destructors.scope.nesting.function-body] for example). On narrow screens, the rule name will collapse to display `[*]`. +Rule identifiers appear before each language rule, enclosed in square brackets. These identifiers provide a way to refer to and link to a specific rule in the language ([e.g.][example rule]). The rule identifier uses periods to separate sections from most general to most specific ([destructors.scope.nesting.function-body] for example). On narrow screens, the rule name will collapse to display `[*]`. The rule name can be clicked to link to that rule. @@ -16,9 +16,9 @@ The rule name can be clicked to link to that rule. ### Rule tests -Rules that have associated tests will include a `Tests` link below them (on narrow screens, the link is `[T]`). Clicking the link will pop up a list of tests, which can be clicked to view the test. For example, see [input.encoding.utf8]. +Rules that have associated tests will include a `Tests` link below them (on narrow screens, the link is `[T]`). Clicking the link will display a list of tests, which can be clicked to view each test. For example, see [input.encoding.utf8]. -Linking rules to tests is an ongoing effort. See the [Test summary](test-summary.md) chapter for an overview. +Linking rules to tests is an ongoing effort. See the [test summary] chapter for an overview. ## Definitions @@ -26,6 +26,8 @@ Statements that define a term contain that term in *italics*. Whenever that term An *example term* is an example of a term being defined. +The [glossary] contains a list of definitions. + ## Examples Example blocks show an example that demonstrates some rule or points out some interesting aspect. Some examples may have hidden lines which can be viewed by clicking the eye icon that appears when hovering or tapping the example. @@ -38,14 +40,12 @@ Example blocks show an example that demonstrates some rule or points out some in ## Code blocks -Code snippets inline in the text are inside `` tags. - -Longer code examples are in a syntax highlighted box that has controls for copying, executing, and showing hidden lines in the top right corner. +Code examples have controls for copying, executing, and showing hidden lines in the top right corner. ```rust # // This is a hidden line. fn main() { - println!("This is a code example"); + println!("This is a code example"); } ``` @@ -53,7 +53,7 @@ All examples are written for the latest edition unless otherwise stated. ## Grammar -The grammar and lexical productions are described in the [Notation] chapter. +The grammar and lexical productions are described in the [grammar notation chapter][notation]. ## Notes @@ -77,3 +77,5 @@ The main text describes the latest stable edition. Differences to previous editi > Before the 2018 edition, the behavior was this. As of the 2018 edition, the behavior is that. [example rule]: example.rule.label +[Glossary]: glossary.md +[test summary]: test-summary.md From d21b3ceb137ea4f1cab589841ef1fd7bb7946d48 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 27 Nov 2025 07:24:13 -0800 Subject: [PATCH 09/12] Move "rust releases" below "how to use" For whatever reason, I feel like this flows a little better as "how to read" is directly tied to the audience (the reader). It also doesn't seem to be a very high priority section to me. --- src/introduction.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/introduction.md b/src/introduction.md index b8b116584d..1cbc224c3c 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -12,12 +12,6 @@ The audience for this book includes: See the [scope chapter] for a detailed explanation of what constitutes the Reference. -## Rust releases - -Rust has a new language release every six weeks. The first stable release of the language was Rust 1.0.0, followed by Rust 1.1.0 and so on. Tools (`rustc`, `cargo`, etc.) and documentation ([Standard library], this book, etc.) are released with the language release. - -The latest release of this book, matching the latest Rust version, can always be found at . Prior versions can be found by adding the Rust version before the "reference" directory. For example, the Reference for Rust 1.49.0 is located at . - ## What *The Reference* is not This book does not serve as an introduction to the language. Background familiarity with the language is assumed. A separate [book] is available to help acquire such background familiarity. @@ -45,6 +39,12 @@ That said, there is no wrong way to read this book. Read it however you feel hel > [!NOTE] > For known bugs and omissions in this book, see our [GitHub issues]. If you see a case where the compiler behavior and the text here do not agree, file an issue so we can think about which is correct. +## Rust releases + +Rust has a new language release every six weeks. The first stable release of the language was Rust 1.0.0, followed by Rust 1.1.0 and so on. Tools (`rustc`, `cargo`, etc.) and documentation ([Standard library], this book, etc.) are released with the language release. + +The latest release of this book, matching the latest Rust version, can always be found at . Prior versions can be found by adding the Rust version before the "reference" directory. For example, the Reference for Rust 1.49.0 is located at . + ## Contributing We welcome contributions of all kinds. From c6978467ed69d83b47b8b4e50f3bd7231bec73a3 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 27 Nov 2025 07:24:22 -0800 Subject: [PATCH 10/12] Add a reminder to link to the contributor guide --- src/introduction.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/introduction.md b/src/introduction.md index 1cbc224c3c..368fe878b4 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -51,6 +51,8 @@ We welcome contributions of all kinds. You can contribute to this book by opening an issue or sending a pull request to [the Rust Reference repository]. If this book does not answer your question, and you think its answer is in scope of it, please do not hesitate to [file an issue] or ask about it in the `t-lang/doc` stream on [Zulip]. Knowing what people use this book for the most helps direct our attention to making those sections the best that they can be. And of course, if you see anything that is wrong or is non-normative but not specifically called out as such, please also [file an issue]. + + [book]: ../book/index.html [cargo book]: ../cargo/index.html [cargo reference]: ../cargo/reference/index.html From 41071a5b4b318ca73de05171528deb6d584a29da Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 27 Nov 2025 07:27:41 -0800 Subject: [PATCH 11/12] Apply some light edits to the introduction --- src/introduction.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/introduction.md b/src/introduction.md index 368fe878b4..26cd8dc5e3 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -26,11 +26,11 @@ Rust compilers, including `rustc`, will perform optimizations. The reference doe ## How to use this book -This book does not assume you are reading this book sequentially. Each chapter generally can be read standalone, but will cross-link to other chapters for facets of the language they refer to, but do not discuss. +This book does not assume you are reading it sequentially. Each chapter generally can be read standalone, but will cross-link to other chapters for facets of the language they refer to but do not discuss. There are two main ways to read this document. -The first is to answer a specific question. If you know which chapter answers that question, you can jump to that chapter in the table of contents. Otherwise, you can press `s` or click the magnifying glass on the top bar to search for keywords related to your question. For example, say you wanted to know when a temporary value created in a let statement is dropped. If you didn't already know that the [lifetime of temporaries] is defined in the [expressions chapter], you could search "temporary let" and the first search result will take you to that section. +The first is to answer a specific question. If you know which chapter answers that question, you can jump to that chapter in the table of contents. Otherwise, you can press `s` or click the magnifying glass on the top bar to search for keywords related to your question. For example, say you wanted to know when a temporary value created in a `let` statement is dropped. If you didn't already know that the [lifetime of temporaries] is defined in the [expressions chapter], you could search "temporary let" and the first search result will take you to that section. The second is to generally improve your knowledge of a facet of the language. In that case, just browse the table of contents until you see something you want to know more about, and just start reading. If a link looks interesting, click it, and read about that section. @@ -49,7 +49,7 @@ The latest release of this book, matching the latest Rust version, can always be We welcome contributions of all kinds. -You can contribute to this book by opening an issue or sending a pull request to [the Rust Reference repository]. If this book does not answer your question, and you think its answer is in scope of it, please do not hesitate to [file an issue] or ask about it in the `t-lang/doc` stream on [Zulip]. Knowing what people use this book for the most helps direct our attention to making those sections the best that they can be. And of course, if you see anything that is wrong or is non-normative but not specifically called out as such, please also [file an issue]. +You can contribute to this book by opening an issue or sending a pull request to [the Rust Reference repository]. If this book does not answer your question and you think its answer is in scope, please do not hesitate to [file an issue] or ask about it in the `t-lang/doc` stream on [Zulip]. Knowing what people use this book for the most helps direct our attention to making those sections the best they can be. And of course, if you see anything that is wrong or is non-normative but not specifically called out as such, please also [file an issue]. From a1a5948de4c678e08365ea788773af138f81f5e3 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 28 Nov 2025 07:04:26 -0800 Subject: [PATCH 12/12] Add a new scope chapter This chapter describes exactly what is in and out of scope for the Reference, along with the characteristics of how it is covered. --- src/SUMMARY.md | 2 + src/introduction.md | 18 ------ src/scope.md | 132 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 134 insertions(+), 18 deletions(-) create mode 100644 src/scope.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 8d1f1f2235..c96954d4a9 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -2,6 +2,8 @@ [Introduction](introduction.md) +- [Scope](scope.md) + - [Notational conventions](conventions.md) - [Grammar notation](notation.md) diff --git a/src/introduction.md b/src/introduction.md index 26cd8dc5e3..572ecf1e51 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -12,18 +12,6 @@ The audience for this book includes: See the [scope chapter] for a detailed explanation of what constitutes the Reference. -## What *The Reference* is not - -This book does not serve as an introduction to the language. Background familiarity with the language is assumed. A separate [book] is available to help acquire such background familiarity. - -This book also does not serve as a reference to the [standard library] included in the language distribution. Those libraries are documented separately by extracting documentation attributes from their source code. Many of the features that one might expect to be language features are library features in Rust, so what you're looking for may be there, not here. - -Similarly, this book does not usually document the specifics of `rustc` as a tool or of Cargo. `rustc` has its own [book][rustc book]. Cargo has a [book][cargo book] that contains a [reference][cargo reference]. There are a few pages such as [linkage] that still describe how `rustc` works. - -This book also only serves as a reference to what is available in stable Rust. For unstable features being worked on, see the [Unstable Book]. - -Rust compilers, including `rustc`, will perform optimizations. The reference does not specify what optimizations are allowed or disallowed. Instead, think of the compiled program as a black box. You can only probe by running it, feeding it input and observing its output. Everything that happens that way must conform to what the reference says. - ## How to use this book This book does not assume you are reading it sequentially. Each chapter generally can be read standalone, but will cross-link to other chapters for facets of the language they refer to but do not discuss. @@ -53,17 +41,11 @@ You can contribute to this book by opening an issue or sending a pull request to -[book]: ../book/index.html -[cargo book]: ../cargo/index.html -[cargo reference]: ../cargo/reference/index.html [expressions chapter]: expressions.html [file an issue]: https://github.com/rust-lang/reference/issues [github issues]: https://github.com/rust-lang/reference/issues [lifetime of temporaries]: expressions.html#temporaries -[linkage]: linkage.html -[rustc book]: ../rustc/index.html [scope chapter]: scope.md [standard library]: std [the Rust Reference repository]: https://github.com/rust-lang/reference/ -[Unstable Book]: https://doc.rust-lang.org/nightly/unstable-book/ [Zulip]: https://rust-lang.zulipchat.com/#narrow/stream/237824-t-lang.2Fdoc diff --git a/src/scope.md b/src/scope.md new file mode 100644 index 0000000000..33ef610cef --- /dev/null +++ b/src/scope.md @@ -0,0 +1,132 @@ +# Scope + +## Scope of the Reference + +The scope of the Rust Reference is to fully describe the syntax and semantics of the Rust language. In this context, the language encompasses: + +- Valid syntax and forms. +- Meaning and interpretation of the syntax. +- Semantic properties of the runtime behavior. +- Built-in attributes. +- Built-in types. +- *Language items* from the standard library, which directly interface with the language (such as operators desugaring to trait calls). +- All [editions] of Rust. + +## Out of scope + +The Reference does not cover: + +- Contents of the standard library, unless required to describe other language aspects. + - The standard library is described in [the standard library API documentation][std]. +- Introductions or guides to the language. Background familiarity with the language is assumed. A separate [book] is available to help acquire such background familiarity. +- Recommendations on how to write Rust code. + - Exceptional cases may be included in a [note] or [warning]. +- Specifics of tooling provided by the Rust organization, such as `rustc` or Cargo. + - `rustc` has its own [book][rustc book]. Cargo has a [book][cargo book] that contains a [reference][cargo reference]. + - In exceptional circumstances, notes may refer to these tools when they have significant relevance. +- Specifics of which targets exist, or properties of specific targets. See [target-specific behavior] for more details. +- Unstable features only available on the [nightly channel]. + - For documentation of unstable features, see the [Unstable Book]. + - Occasionally the Reference may refer to an unstable feature because it is important to understand the model of stable code. +- Future changes, with the following exceptions: + - Language constructs that are designed to specifically allow for future extensions. For example, some syntax is reserved for future use, or some values such as config predicates may be documented as *open*, meaning they may be extended in the future. + - Notes for [incomplete or undecided behavior] may refer to the future intentions. + - Notes about deviation from [intended behavior] may mention that the behavior may change. +- Version history or past behavior. + - Changes in Rust releases are recorded in the [Release Notes]. Prior releases of the Reference are available as described in [Rust releases]. +- Historical documentation. + - This includes documentation such as [RFCs], design documents, reports, blog posts, issues, pull requests, etc. +- Rationale for most aspects of the language. + - Rationale may be included in a note in exceptional situations, particularly when a feature is not obvious or has especially useful relevance. +- `rustc` lints. + - Lints are documented in the [rustc book][lints]. + - Lints that have a specific relation to some part of the language may be referred to by name. For example, the `expect` attribute can issue the `unfulfilled_lint_expectations` lint. However, the exact behavior of when the lint is issued is usually not documented in the Reference. + - Notes may refer to lints when the lint has exceptional relevance to some aspect of the language. +- Method of translation into executable code, unless required (for example, as it relates to the translation of [inline assembly]). +- Allowed or disallowed optimizations, unless specifically afforded by the language. +- Limits on compiler inputs (such as maximum source file size), unless the language explicitly defines specific limits (for example, see [limits] or the [number of `#` symbols in raw strings][lex.token.literal.str-raw.intro]). + +## Completeness + +Portions of the Reference may be incomplete or undecided. Work is ongoing to complete these sections. New features and changes to the language must be completely documented, unless they involve sections of the language that were previously undocumented. + +*Complete* means that the syntax and semantics are sufficiently documented for someone reasonably skilled in the art to fully understand them. However, because the majority of the Reference is written in English prose rather than a rigorous formalism, ambiguities or misunderstandings can arise. If you encounter something unclear, we welcome your feedback through our [issue tracker]. Separate work is ongoing to provide more formal definitions of the language in the future. + +## Correctness + +The Reference is intended to be correct in all aspects. If errors or ambiguities are discovered, the Reference is updated to correct them. + +If there are errors, ambiguities, or conflicts with the `rustc` implementation, we must first determine the [intended behavior](#intended-behavior). Whether something is an error can sometimes be unclear; in those situations, the Reference editors consult: + +- The behavior in `rustc`. +- Historical documentation and communication. +- Teams in the Rust organization. + +## Intended behavior + +At times, the actual behavior of the official `rustc` implementation may diverge from the documented or intended behavior. Generally, the Reference documents the intended behavior, even if it differs from the actual behavior in `rustc`. Informational notes may be included to highlight significant discrepancies. These notes may refer to *future-incompatible warnings*, which are lints used by `rustc` to alert users about planned changes. + +However, documenting every bug or implementation quirk in `rustc` is out of scope. Only discrepancies that are significant, long-standing, or particularly likely to affect users are mentioned. Minor bugs, temporary implementation issues, or behaviors expected to be fixed in an upcoming release are typically not documented. + +## Unspecified behavior + +*Unspecified behavior* is behavior that is documented as not explicitly defined, but still covers a well-formed program. This should be a relatively rare concept, as the intent is for programmers to rely on expected behavior in as many areas as possible. Unspecified behavior may change between releases or compilation settings, and may become specified in a future release. + +Behavior is typically left unspecified when the language intentionally allows implementation flexibility for optimization or platform-specific concerns, provided the variation does not affect program correctness. Examples include the exact layout of certain types using [the `Rust` representation] or how and when optimization hints such as inlining occur. + +Unspecified behavior differs from [undefined behavior](#undefined-behavior) in that all possible outcomes are valid and do not compromise program safety. Programs should not rely on specific unspecified behaviors, as they may vary between compiler versions, optimization levels, or platforms. + +Unspecified behavior differs from [incomplete documentation](#completeness) in that the Reference specifically identifies the behavior as intentionally unspecified, whereas incomplete documentation is intended to be specified but has not yet been written. + +## Undefined behavior + +[*Undefined behavior*][undefined] is compile-time or run-time behavior that is not specified. See the corresponding chapter for a complete description. Other chapters may mention undefined behavior where relevant, but should also link back to the [undefined behavior][undefined] chapter. + +## Target-specific behavior + +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. Examples of defined target properties include: + +- 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 supported architectures. + +For a list of targets supported by `rustc`, see [the rustc book][rustc-platforms]. + +## Normative and informational content + +The Reference contains both normative and informational content. *Normative content* defines the official requirements and specifications of the Rust language: the rules that determine what constitutes valid Rust code and its behavior. *Informational content* provides context, examples, and clarifications that aid understanding but do not define requirements. + +Normative content consists of [rules], [grammar productions], and anything else explicitly listed as normative. + +Informational content consists of [notes], [examples], [warnings], introductions (rule labels ending in `.intro`), footnotes, and appendices (unless otherwise noted). + +[`target_feature` attribute]: attributes.codegen.target_feature +[`target_os`]: cfg.target_os +[`windows_subsystem` attribute]: runtime.windows_subsystem +[book]: ../book/index.html +[cargo book]: ../cargo/index.html +[cargo reference]: ../cargo/reference/index.html +[editions]: conventions.md#editions +[examples]: conventions.md#examples +[grammar productions]: notation.md +[incomplete or undecided behavior]: #completeness +[Inline assembly]: asm +[intended behavior]: #intended-behavior +[issue tracker]: https://github.com/rust-lang/reference/issues +[limits]: attributes.limits +[lints]: ../rustc/lints/index.html +[nightly channel]: ../book/appendix-07-nightly-rust.html +[note]: conventions.md#notes +[notes]: conventions.md#notes +[Release Notes]: https://doc.rust-lang.org/releases.html +[RFCs]: https://rust-lang.github.io/rfcs/ +[rules]: conventions.md#rules +[Rust releases]: introduction.md#rust-releases +[rustc book]: ../rustc/index.html +[rustc-platforms]: ../rustc/platform-support.html +[std]: ../std/index.html +[target-specific behavior]: #target-specific-behavior +[the `Rust` representation]: layout.repr.rust +[Unstable Book]: https://doc.rust-lang.org/nightly/unstable-book/ +[warning]: conventions.md#warnings +[warnings]: conventions.md#warnings