Expand docs on Macros By Example.

src/SUMMARY.md

@@ -115,8 +115,8 @@
 
 - [The Rust runtime](runtime.md)
 
-[Appendix: Influences](influences.md)
-
-[Appendix: As-yet-undocumented Features](undocumented.md)
-
-[Appendix: Glossary](glossary.md)
+- [Appendices](appendices.md)
+    - [Macro Follow-Set Ambiguity Formal Specification](macro-ambiguity.md)
+    - [Influences](influences.md)
+    - [As-Yet-Undocumented Features](undocumented.md)
+    - [Glossary](glossary.md)

src/appendices.md

@@ -0,0 +1 @@
+# Appendices

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