Rework the introduction and add a scope chapter

src/SUMMARY.md

@@ -2,7 +2,10 @@
 
 [Introduction](introduction.md)
 
-- [Notation](notation.md)
+- [Scope](scope.md)
+
+- [Notational conventions](conventions.md)
+    - [Grammar notation](notation.md)
 
 - [Lexical structure](lexical-structure.md)
     - [Input format](input-format.md)

src/conventions.md

@@ -0,0 +1,81 @@
+# Notational conventions
+
+## Conventions
+
+Like all technical books, this book has certain conventions in how it displays information. These conventions are documented here.
+
+## 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 `[*]`.
+
+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.
+
+### 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 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] chapter for an overview.
+
+## Definitions
+
+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 [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.
+
+> [!EXAMPLE]
+> This is a code example.
+> ```rust
+> println!("hello world");
+> ```
+
+## Code blocks
+
+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");
+}
+```
+
+All examples are written for the latest edition unless otherwise stated.
+
+## Grammar
+
+The grammar and lexical productions are described in the [grammar notation chapter][notation].
+
+## 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.
+
+## Editions
+
+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.
+
+[example rule]: example.rule.label
+[Glossary]: glossary.md
+[test summary]: test-summary.md

src/introduction.md

@@ -1,144 +1,51 @@
 # Introduction
 
-This book is the primary reference for the Rust programming language.
+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.
 
-> [!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.
+## Audience
 
-The latest release of this book, matching the latest Rust version, can always be found at <https://doc.rust-lang.org/reference/>.
-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 <https://doc.rust-lang.org/1.49.0/reference/>.
+The audience for this book includes:
 
-## What *The Reference* is not
+- 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.
 
-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.
+See the [scope chapter] for a detailed explanation of what constitutes the Reference.
 
 ## 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.
+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.
-
-* 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 `<code>` 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.
+> [!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.
 
-  > [!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.
+## Rust 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].
+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.
 
-  Linking rules to tests is an ongoing effort. See the [Test summary](test-summary.md) chapter for an overview.
+The latest release of this book, matching the latest Rust version, can always be found at <https://doc.rust-lang.org/reference/>. 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 <https://doc.rust-lang.org/1.49.0/reference/>.
 
 ## Contributing
 
 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].
+
+<!-- TODO: Link to contributing guide -->
 
-[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
+[scope chapter]: scope.md
+[standard library]: std
+[the Rust Reference repository]: https://github.com/rust-lang/reference/
 [Zulip]: https://rust-lang.zulipchat.com/#narrow/stream/237824-t-lang.2Fdoc

src/notation.md

@@ -1,5 +1,5 @@
 r[notation]
-# Notation
+# Grammar notation
 
 r[notation.grammar]
 ## Grammar