Merge pull request #1816 from Daniel-Aaron-Bloom/dollar-crate

Minor fixes to `$crate` behavior

Author: ehuss

src/macros-by-example.md

@@ -134,7 +134,7 @@ Valid fragment specifiers are:
   * `block`: a [BlockExpression]
   * `expr`: an [Expression]
   * `expr_2021`: an [Expression] except [UnderscoreExpression] and [ConstBlockExpression] (see [macro.decl.meta.edition2024])
-  * `ident`: an [IDENTIFIER_OR_KEYWORD] or [RAW_IDENTIFIER]
+  * `ident`: an [IDENTIFIER_OR_KEYWORD], [RAW_IDENTIFIER], or [`$crate`]
   * `item`: an [Item]
   * `lifetime`: a [LIFETIME_TOKEN]
   * `literal`: matches `-`<sup>?</sup>[LiteralExpression]
@@ -151,10 +151,10 @@ r[macro.decl.meta.transcription]
 In the transcriber, metavariables are referred to simply by `$`_name_, since
 the fragment kind is specified in the matcher. Metavariables are replaced with
 the syntax element that matched them.
+Metavariables can be transcribed more than once or not at all.
 
 r[macro.decl.meta.dollar-crate]
-The keyword metavariable `$crate` can be used to refer to the current crate; see [Hygiene] below. Metavariables can be
-transcribed more than once or not at all.
+The keyword metavariable [`$crate`] can be used to refer to the current crate.
 
 r[macro.decl.meta.edition2021]
 > [!EDITION-2021]
@@ -594,3 +594,4 @@ For more detail, see the [formal specification].
 [Metavariables]: #metavariables
 [Repetitions]: #repetitions
 [token]: tokens.md
+[`$crate`]: macro.decl.hygiene.crate

src/paths.md

@@ -368,11 +368,11 @@ r[paths.qualifiers.macro-crate]
 ### `$crate`
 
 r[paths.qualifiers.macro-crate.allowed-positions]
-`$crate` is only used within [macro transcribers], and can only be used as the first
+[`$crate`] is only used within [macro transcribers], and can only be used as the first
 segment, without a preceding `::`.
 
 r[paths.qualifiers.macro-crate.hygiene]
-`$crate` will expand to a path to access items from the
+[`$crate`] will expand to a path to access items from the
 top level of the crate where the macro is defined, regardless of which crate the macro is
 invoked.
 
@@ -472,6 +472,7 @@ mod without { // crate::without
 # fn main() {}
 ```
 
+[`$crate`]: macro.decl.hygiene.crate
 [implementations]: items/implementations.md
 [items]: items.md
 [literal]: expressions/literal-expr.md

src/procedural-macros.md

@@ -350,8 +350,9 @@ r[macro.proc.token.conversion.to-proc_macro]
 When passed to a proc-macro
 - All multi-character operators are broken into single characters.
 - Lifetimes are broken into a `'` character and an identifier.
-- All metavariable substitutions are represented as their underlying token
-  streams.
+- The keyword metavariable [`$crate`] is passed as a single identifier.
+- All other metavariable substitutions are represented as their underlying
+  token streams.
     - Such token streams may be wrapped into delimited groups ([`Group`]) with
       implicit delimiters ([`Delimiter::None`]) when it's necessary for
       preserving parsing priorities.
@@ -376,6 +377,7 @@ their equivalent `#[doc = r"str"]` attributes when passed to macros.
 [Cargo's build scripts]: ../cargo/reference/build-scripts.html
 [Derive macros]: #derive-macros
 [Function-like macros]: #function-like-procedural-macros
+[`$crate`]: macro.decl.hygiene.crate
 [`Delimiter::None`]: proc_macro::Delimiter::None
 [`Group`]: proc_macro::Group
 [`TokenStream`]: proc_macro::TokenStream