Update for review comments and minor additions.

- Address review comments.
- Minor typo and formatting fixes.
- Link `macro_use` and `macro_export` to their new home.

Author: ehuss

src/attributes.md

@@ -175,15 +175,10 @@ which can be used to control type layout.
 
 ## Macro-related attributes
 
-- `macro_use` on a `mod` — macros defined in this module will be visible in the
-  module's parent, after this module has been included.
+- [`macro_use`] — Expands macro visibility, or imports macros from other
+  crates.
 
-- `macro_use` on an `extern crate` — load macros from this crate.  An optional
-  list of names `#[macro_use(foo, bar)]` restricts the import to just those
-  macros named.  The `extern crate` must appear at the crate root, not inside
-  `mod`, which ensures proper function of the `$crate` macro variable.
-
-- `macro_export` - export a `macro_rules` macro for cross-crate usage.
+- [`macro_export`] — Exports a `macro_rules` macro for cross-crate usage.
 
 - `no_link` on an `extern crate` — even if we load this crate for macros, don't
   link it into the output.
@@ -634,3 +629,5 @@ pub fn f() {}
 [`meta` macro fragment specifier]: macros-by-example.html
 [`used`]: abi.html#the-used-attribute
 [`panic_handler`]: runtime.html#the-panic_handler-attribute
+[`macro_use`]: macros-by-example.html#the-macro_use-attribute
+[`macro_export`]: macros-by-example.html#path-based-scope

src/items/extern-crates.md

@@ -98,7 +98,7 @@ into the macro-use prelude.
 
 [IDENTIFIER]: identifiers.html
 [RFC 940]: https://github.com/rust-lang/rfcs/blob/master/text/0940-hyphens-considered-harmful.md
-[`#[macro_use]` attribute]: attributes.html#macro-related-attributes
+[`#[macro_use]` attribute]: macros-by-example.html#the-macro_use-attribute
 [`alloc`]: https://doc.rust-lang.org/alloc/
 [`crate::`]: paths.html#crate
 [`no_implicit_prelude`]: items/modules.html#prelude-items

src/items/modules.md

@@ -123,7 +123,7 @@ mod thread {
 ## Prelude Items
 
 Modules implicitly have some names in scope. These name are to built-in types,
-macros imported with `#[macro_use]` on an extern crate, and by the crate's
+macros imported with [`#[macro_use]`] on an extern crate, and by the crate's
 [prelude]. These names are all made of a single identifier. These names are not
 part of the module, so for example, any name `name`, `self::name` is not a
 valid path. The names added by the [prelude] can be removed by placing the
@@ -142,6 +142,7 @@ The built-in attributes that have meaning on a function are [`cfg`],
 [_InnerAttribute_]: attributes.html
 [_Item_]: items.html
 [_OuterAttribute_]: attributes.html
+[`#[macro_use]`]: macros-by-example.html#the-macro_use-attribute
 [`cfg`]: conditional-compilation.html
 [`deprecated`]: attributes.html#deprecation
 [`doc`]: attributes.html#documentation

src/macro-ambiguity.md

@@ -118,7 +118,7 @@ legal macro definition will continue to assign the same determination as to
 where `... tt` ends and `uu ...` begins, even as new syntactic forms are added
 to the language.
 
-The second invariant says that a separated complex NT must use a seperator token
+The second invariant says that a separated complex NT must use a separator token
 that is part of the predetermined follow set for the internal contents of the
 NT. This ensures that a legal macro definition will continue to parse an input
 fragment into the same delimited sequence of `tt ...`'s, even as new syntactic
@@ -273,7 +273,7 @@ LAST(M), defined by case analysis on M itself (a sequence of token-trees):
 
 Below are some examples of FIRST and LAST.
 (Note in particular how the special ε element is introduced and
-eliminated based on the interation between the pieces of the input.)
+eliminated based on the interaction between the pieces of the input.)
 
 Our first example is presented in a tree structure to elaborate on how
 the analysis of the matcher composes. (Some of the simpler subtrees
@@ -365,7 +365,7 @@ why particular matchers are legal and others are not.
 
  * `( $($a:tt $b:tt)* ; )` : legal, because FIRST(`$b:tt`) = { `$b:tt` } is ⊆ FOLLOW(`tt`) = ANYTOKEN, as is FIRST(`;`) = { `;` }.
 
- * `( $($t:tt),* , $(t:tt),* )` : legal,  (though any attempt to actually use this macro will signal a local ambguity error during expansion).
+ * `( $($t:tt),* , $(t:tt),* )` : legal,  (though any attempt to actually use this macro will signal a local ambiguity error during expansion).
 
  * `($ty:ty $(; not sep)* -)` : illegal, because FIRST(`$(; not sep)* -`) = { `;`, `-` } is not in FOLLOW(`ty`).
 

src/macros-by-example.md

@@ -49,6 +49,8 @@ the matcher and the transcriber must be surrounded by delimiters. Macros can
 expand to expressions, statements, items (including traits, impls, and foreign
 items), types, or patterns.
 
+## Transcription
+
 When a macro is invoked, the macro expander looks up macro invocations by name,
 and tries each macro rule in turn. It transcribes the first successful match; if
 this results in an error, then future matches are not tried. When matching, no
@@ -60,19 +62,56 @@ invocation unambiguously:
 
 ```rust,compile_fail
 macro_rules! ambiguity {
-    ($($i:ident)* $j:ident) => { ($($i)-*) * $j };
+    ($($i:ident)* $j:ident) => { };
 }
 
 ambiguity!(error); // Error: local ambiguity
 ```
 
 In both the matcher and the transcriber, the `$` token is used to invoke special
-behaviours from the macro engine. Tokens that aren't part of such an invocation
-are matched and transcribed literally, with one exception. The exception is that
-the outer delimiters for the matcher will match any pair of delimiters. Thus,
-for instance, the matcher `(())` will match `{()}` but not `{{}}`. The character
+behaviours from the macro engine (described below in [Metavariables] and
+[Repetitions]). Tokens that aren't part of such an invocation are matched and
+transcribed literally, with one exception. The exception is that the outer
+delimiters for the matcher will match any pair of delimiters. Thus, for
+instance, the matcher `(())` will match `{()}` but not `{{}}`. The character
 `$` cannot be matched or transcribed literally.
 
+When forwarding a matched fragment to another macro-by-example, matchers in
+the second macro will see an opaque AST of the fragment type. The second macro
+can't use literal tokens to match the fragments in the matcher, only a
+fragment specifier of the same type. The `ident`, `lifetime`, and `tt`
+fragment types are an exception, and can be matched by literal tokens. The
+following illustrates this restriction:
+
+```rust,compile_fail
+macro_rules! foo {
+    ($l:expr) => { bar!($l); }
+// ERROR:               ^^ no rules expected this token in macro call
+}
+
+macro_rules! bar {
+    (3) => {}
+}
+
+foo!(3);
+```
+
+The following illustrates how tokens can be directly matched after matching a
+`tt` fragment:
+
+```rust
+// compiles OK
+macro_rules! foo {
+    ($l:tt) => { bar!($l); }
+}
+
+macro_rules! bar {
+    (3) => {}
+}
+
+foo!(3);
+```
+
 ## Metavariables
 
 In the matcher, `$` _name_ `:` _fragment-specifier_ matches a Rust syntax
@@ -94,40 +133,44 @@ fragment specifiers are:
   * `vis`: a possibly empty [_Visibility_] qualifier
   * `literal`: matches `-`<sup>?</sup>[_LiteralExpression_]
 
-In the transcriber, metavariables are referred to simply by $`_name_`, since
+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. 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.
 
-## Repititions
+## Repetitions
 
 In both the matcher and transcriber, repetitions are indicated by placing the
-tokens to be repeated inside `$( ... )`, followed by a repetition operator,
+tokens to be repeated inside `$(`…`)`, followed by a repetition operator,
 optionally with a separator token between. The separator token can be any token
 other than a delimiter or one of the repetition operators, but `;` and `,` are
 the most common. For instance, `$( $i:ident ),*` represents any number of
-identifiers separated by commas. Nested repititions are permitted.
+identifiers separated by commas. Nested repetitions are permitted.
+
+The repetition operators are:
 
-The repetition operators are `*`, which indicates any number of repetitions,
-`+`, which indicates any number but at least one, and `?` which indicates an
-optional fragment with zero or one occurrences. Since `?` represents at most one
-occurrence, it cannot be used with a separator.
+- `*` — indicates any number of repetitions.
+- `+` — indicates any number but at least one.
+- `?` — indicates an optional fragment with zero or one occurrences.
+
+Since `?` represents at most one occurrence, it cannot be used with a
+separator.
 
 The repeated fragment both matches and transcribes to the specified number of
 the fragment, separated by the separator token. Metavariables are matched to
 every repetition of their corresponding fragment. For instance, the `$( $i:ident
 ),*` example above matches `$i` to all of the identifiers in the list.
 
-During transcription, additional restrictions apply to repititions so that the
+During transcription, additional restrictions apply to repetitions so that the
 compiler knows how to expand them properly:
 
 1.  A metavariable must appear in exactly the same number, kind, and nesting
     order of repetitions in the transcriber as it did in the matcher. So for the
-    matcher `$( $i:ident ),*`, the transcribers `=> $i`, `=> $( $( $i)* )*`, and
-    `=> $( $i )+` are all illegal, but `=> { $( $i );* }` is correct and
-    replaces a comma-separated list of identifiers with a semicolon-separated
-    list.
+    matcher `$( $i:ident ),*`, the transcribers `=> { $i }`,
+    `=> { $( $( $i)* )* }`, and `=> { $( $i )+ }` are all illegal, but
+    `=> { $( $i );* }` is correct and replaces a comma-separated list of
+    identifiers with a semicolon-separated list.
 1.  Second, each repetition in the transcriber must contain at least one
     metavariable to decide now many times to expand it. If multiple
     metavariables appear in the same repetition, they must be bound to the same
@@ -147,12 +190,12 @@ compiler knows how to expand them properly:
 For historical reasons, the scoping of macros by example does not work entirely like
 items. Macros have two forms of scope: textual scope, and path-based scope.
 Textual scope is based on the order that things appear in source files, or even
-across multiple files, and is the default scoping. It's explained further below.
+across multiple files, and is the default scoping. It is explained further below.
 Path-based scope works exactly the same way that item scoping does. The scoping,
 exporting, and importing of macros is controlled largely by attributes.
 
 When a macro is invoked by an unqualified identifier (not part of a multi-part
-path), it's first looked up in textual scoping. If this does not yield any
+path), it is first looked up in textual scoping. If this does not yield any
 results, then it is looked up in path-based scoping. If the macro's name is
 qualified with a path, then it is only looked up in path-based scoping.
 
@@ -194,7 +237,7 @@ mod has_macro {
 
 //// src/has_macro/uses_macro.rs
 
-m!{} // OK: appears after delcaration of m in src/lib.rs
+m!{} // OK: appears after declaration of m in src/lib.rs
 ```
 
 It is not an error to define a macro multiple times; the most recent declaration
@@ -241,7 +284,9 @@ fn foo() {
 // m!(); // Error: m is not in scope.
 ```
 
-The `#[macro_use]` attribute has two purposes. First, it can be used to make a
+### The `macro_use` attribute
+
+The *`macro_use` attribute* has two purposes. First, it can be used to make a
 module's macro scope not end when the module is closed, by applying it to a
 module:
 
@@ -257,7 +302,7 @@ m!();
 ```
 
 Second, it can be used to import macros from another crate, by attaching it to
-an  `extern crate` declaration appearing in the crate's root module. Macros
+an `extern crate` declaration appearing in the crate's root module. Macros
 imported this way are imported into the prelude of the crate, not textually,
 which means that they can be shadowed by any other name. While macros imported
 by `#[macro_use]` can be used before the import statement, in case of a
@@ -270,7 +315,7 @@ module.
 extern crate lazy_static;
 
 lazy_static!{};
-// self::lazy_static!{} // Error: lazy_static is not defined inself
+// self::lazy_static!{} // Error: lazy_static is not defined in `self`
 ```
 
 Macros to be imported with `#[macro_use]` must be exported with
@@ -302,7 +347,7 @@ mod mac {
 Macros labeled with `#[macro_export]` are always `pub` and can be referred to
 by other crates, either by path or by `#[macro_use]` as described above.
 
-## Hygiene 
+## Hygiene
 
 By default, all identifiers referred to in a macro are expanded as-is, and are
 looked up at the macro's invocation site. This can lead to issues if a macro
@@ -418,22 +463,24 @@ When repetitions are involved, then the rules apply to every possible number of
 expansions, taking separators into account. This means:
 
   * If the repetition includes a separator, that separator must be able to
-    follow the contents of the repitition.
-  * If the repitition can repeat multiple times (`*` or `+`), then the contents
+    follow the contents of the repetition.
+  * If the repetition can repeat multiple times (`*` or `+`), then the contents
     must be able to follow themselves.
   * The contents of the repetition must be able to follow whatever comes
     before, and whatever comes after must be able to follow the contents of the
-    repitition.
-  * If the repitition can match zero times (`*` or `?`), then whatever comes
+    repetition.
+  * If the repetition can match zero times (`*` or `?`), then whatever comes
     after must be able to follow whatever comes before.
 
 
 For more detail, see the [formal specification].
 
+[Hygiene]: #hygiene
 [IDENTIFIER]: identifiers.html
 [IDENTIFIER_OR_KEYWORD]: identifiers.html
 [LIFETIME_TOKEN]: tokens.html#lifetimes-and-loop-labels
-[formal specification]: macro-ambiguity.html
+[Metavariables]: #metavariables
+[Repetitions]: #repetitions
 [_BlockExpression_]: expressions/block-expr.html
 [_DelimTokenTree_]: macros.html
 [_Expression_]: expressions.html
@@ -447,5 +494,5 @@ For more detail, see the [formal specification].
 [_TypePath_]: paths.html#paths-in-types
 [_Type_]: types.html#type-expressions
 [_Visibility_]: visibility-and-privacy.html
+[formal specification]: macro-ambiguity.html
 [token]: tokens.html
-[Hygiene]: #hygiene