Add "scopes" chapter.

.github/workflows/main.yml

@@ -1,5 +1,7 @@
 name: CI
-on: [push, pull_request]
+on:
+  pull_request:
+  merge_group:
 
 jobs:
   test:

README.md

@@ -1,6 +1,7 @@
 # The Rust Language Reference
 
-This document is the primary reference for the Rust programming language.
+This document is the primary reference for the Rust programming
+language.
 
 This document is not normative. It may include details that are specific
 to `rustc` itself, and should not be taken as a specification for the
@@ -9,52 +10,54 @@ what we have for now.
 
 ## Dependencies
 
-- rustc (the Rust compiler).
-- [mdbook](https://rust-lang.github.io/mdBook/) (use `cargo install mdbook` to install it).
-- rust nightly (you would be required to set your Rust version to the nightly version to make sure all tests pass)
+- Nightly Rust
+- [mdbook](https://rust-lang.github.io/mdBook/)
 
-## Build steps
+## Installing dependencies
 
-To build the project, follow the steps given below :
+First, ensure that you have a recent copy of the nightly Rust compiler
+installed, as this is needed in order to run the tests:
 
-Clone the project by downloading the ZIP from the [GitHub page](/~https://github.com/rust-lang/reference) or
-run the following command:
-
-```
-git clone /~https://github.com/rust-lang/reference
+```sh
+rustup toolchain install nightly
 ```
 
-Change the directory to the downloaded repository:
+Now, ensure you have `mdbook` installed, as this is needed in order to
+build the Reference:
 
 ```sh
-cd reference
+cargo install --locked mdbook
 ```
 
-To run the tests, you would need to set the Rust version to the nightly release. You can do this by executing the following command:
+## Building
+
+To build the Reference, first clone the project:
 
-```shell
-rustup override set nightly
+```sh
+git clone /~https://github.com/rust-lang/reference.git
 ```
 
-This will set the nightly version only for your the current project.
+(Alternatively, if you don't want to use `git`, [download][] a ZIP file
+of the project, extract it using your preferred tool, and rename the
+top-level directory to `reference`.)
 
-If you wish to set Rust nightly for all your projects, you can run the command: 
+[download]: /~https://github.com/rust-lang/reference/archive/refs/heads/master.zip
 
-```shell
-rustup default nightly
+Now change your current directory to the working directory:
+
+```sh
+cd reference
 ```
 
-Now, run the following command to test the code snippets to catch compilation errors:
+To test all of the code examples in the Reference, run:
 
-```shell
+```sh
 mdbook test
 ```
 
-
-To generate a local instance of the book, run:
+To build the Reference locally (in `build/`) and open it in a web
+browser, run:
 
 ```sh
-mdbook build
+mdbook build --open
 ```
-
-The generated HTML will be in the `book` folder.

book.toml

@@ -6,9 +6,12 @@ author = "The Rust Project Developers"
 [output.html]
 additional-css = ["theme/reference.css"]
 git-repository-url = "/~https://github.com/rust-lang/reference/"
+edit-url-template = "/~https://github.com/rust-lang/reference/edit/master/{path}"
 
 [output.html.redirect]
 "/expressions/enum-variant-expr.html" = "struct-expr.html"
+"/unsafe-blocks.html" = "unsafe-keyword.html"
+"/unsafe-functions.html" = "unsafe-keyword.html"
 
 [rust]
 edition = "2021"

rust-toolchain.toml

@@ -0,0 +1,2 @@
+[toolchain]
+channel = "nightly"

src/SUMMARY.md

@@ -44,6 +44,7 @@
     - [Code generation](attributes/codegen.md)
     - [Limits](attributes/limits.md)
     - [Type System](attributes/type_system.md)
+    - [Debugger](attributes/debugger.md)
 
 - [Statements and expressions](statements-and-expressions.md)
     - [Statements](statements.md)
@@ -118,8 +119,7 @@
 - [Inline assembly](inline-assembly.md)
 
 - [Unsafety](unsafety.md)
-    - [Unsafe functions](unsafe-functions.md)
-    - [Unsafe blocks](unsafe-blocks.md)
+    - [The `unsafe` keyword](unsafe-keyword.md)
     - [Behavior considered undefined](behavior-considered-undefined.md)
     - [Behavior not considered unsafe](behavior-not-considered-unsafe.md)
 

src/attributes.md

@@ -196,7 +196,7 @@ struct S {
 pub fn f() {}
 ```
 
-> Note: `rustc` currently recognizes the tools "clippy" and "rustfmt".
+> Note: `rustc` currently recognizes the tools "clippy", "rustfmt" and "diagnostic".
 
 ## Built-in attributes index
 
@@ -224,10 +224,14 @@ The following is an index of all built-in attributes.
   - [`allow`], [`warn`], [`deny`], [`forbid`] — Alters the default lint level.
   - [`deprecated`] — Generates deprecation notices.
   - [`must_use`] — Generates a lint for unused values.
+  - [`diagnostic::on_unimplemented`] — Hints the compiler to emit a certain error
+    message if a trait is not implemented.
 - ABI, linking, symbols, and FFI
   - [`link`] — Specifies a native library to link with an `extern` block.
   - [`link_name`] — Specifies the name of the symbol for functions or statics
     in an `extern` block.
+  - [`link_ordinal`] — Specifies the ordinal of the symbol for functions or
+    statics in an `extern` block.
   - [`no_link`] — Prevents linking an extern crate.
   - [`repr`] — Controls type layout.
   - [`crate_type`] — Specifies the type of crate (library, executable, etc.).
@@ -246,6 +250,7 @@ The following is an index of all built-in attributes.
   - [`no_builtins`] — Disables use of certain built-in functions.
   - [`target_feature`] — Configure platform-specific code generation.
   - [`track_caller`] - Pass the parent call location to `std::panic::Location::caller()`.
+  - [`instruction_set`] - Specify the instruction set used to generate a functions code
 - Documentation
   - `doc` — Specifies documentation. See [The Rustdoc Book] for more
     information. [Doc comments] are transformed into `doc` attributes.
@@ -268,10 +273,13 @@ The following is an index of all built-in attributes.
 - Type System
   - [`non_exhaustive`] — Indicate that a type will have more fields/variants
     added in future.
+- Debugger
+  - [`debugger_visualizer`] — Embeds a file that specifies debugger output for a type.
+  - [`collapse_debuginfo`] — Controls how macro invocations are encoded in debuginfo.
 
 [Doc comments]: comments.md#doc-comments
-[ECMA-334]: https://www.ecma-international.org/publications/standards/Ecma-334.htm
-[ECMA-335]: https://www.ecma-international.org/publications/standards/Ecma-335.htm
+[ECMA-334]: https://www.ecma-international.org/publications-and-standards/standards/ecma-334/
+[ECMA-335]: https://www.ecma-international.org/publications-and-standards/standards/ecma-335/
 [Expression Attributes]: expressions.md#expression-attributes
 [IDENTIFIER]: identifiers.md
 [RAW_STRING_LITERAL]: tokens.md#raw-string-literals
@@ -286,8 +294,10 @@ The following is an index of all built-in attributes.
 [`cfg_attr`]: conditional-compilation.md#the-cfg_attr-attribute
 [`cfg`]: conditional-compilation.md#the-cfg-attribute
 [`cold`]: attributes/codegen.md#the-cold-attribute
+[`collapse_debuginfo`]: attributes/debugger.md#the-collapse_debuginfo-attribute
 [`crate_name`]: crates-and-source-files.md#the-crate_name-attribute
 [`crate_type`]: linkage.md
+[`debugger_visualizer`]: attributes/debugger.md#the-debugger_visualizer-attribute
 [`deny`]: attributes/diagnostics.md#lint-check-attributes
 [`deprecated`]: attributes/diagnostics.md#the-deprecated-attribute
 [`derive`]: attributes/derive.md
@@ -296,7 +306,9 @@ The following is an index of all built-in attributes.
 [`global_allocator`]: runtime.md#the-global_allocator-attribute
 [`ignore`]: attributes/testing.md#the-ignore-attribute
 [`inline`]: attributes/codegen.md#the-inline-attribute
+[`instruction_set`]: attributes/codegen.md#the-instruction_set-attribute
 [`link_name`]: items/external-blocks.md#the-link_name-attribute
+[`link_ordinal`]: items/external-blocks.md#the-link_ordinal-attribute
 [`link_section`]: abi.md#the-link_section-attribute
 [`link`]: items/external-blocks.md#the-link-attribute
 [`macro_export`]: macros-by-example.md#path-based-scope
@@ -344,3 +356,4 @@ The following is an index of all built-in attributes.
 [closure]: expressions/closure-expr.md
 [function pointer]: types/function-pointer.md
 [variadic functions]: items/external-blocks.html#variadic-functions
+[`diagnostic::on_unimplemented`]: attributes/diagnostics.md#the-diagnosticon_unimplemented-attribute