rewrite bullet points as prose

Author: yaahc

src/items/use-declarations.md

@@ -116,7 +116,7 @@ They may create bindings for:
 * [Built-in types]
 * [Attributes]
 * [Derive macros]
-* [Macros by example]
+* [`macro_rules`]
 
 r[items.use.path.disallowed]
 They cannot import [associated items], [generic parameters], [local variables], paths with [`Self`], or [tool attributes]. More restrictions are described below.

src/macros-by-example.md

@@ -326,8 +326,9 @@ fn foo() {
 // m!(); // Error: m is not in scope.
 ```
 
-* textual scope name bindings for macros may shadow path-based scope bindings
-  to macros
+r[macro.decl.scope.textual.shadow.path-based]
+Textual scope name bindings for macros may shadow path-based scope bindings to
+macros.
 
 ```rust
 macro_rules! m {
@@ -348,6 +349,38 @@ use crate::m2 as m;
 m!(); // prints "m\n"
 ```
 
+TODO: note that the opposite is not true, link to relevant name-res ambiguity error section
+
+r[macro.decl.scope.path-based]
+### Path-based scope
+
+r[macro.decl.scope.path-based.intro]
+TODO: intro to path based scope, find old version
+
+There are two ways to gain path-based scope for MBE macros:
+
+* `#[macro_export]`
+* [Use declaration re-export]
+
+r[macro.decl.scope.path.reexport]
+Macros can be re-exported to give them path-based scope from a module other than the crate root.
+
+```rust
+mac::m!(); // OK: Path-based lookup finds m in the mac module.
+
+mod mac {
+    macro_rules! m {
+        () => {};
+    }
+    pub(crate) use m;
+}
+```
+
+r[macro.decl.scope.path-based.visibility]
+* macros have an implicit visibility of `pub(crate)`
+* `#[macro_export]` changes the implicit visibility to `pub`
+* macro definitions do not support direct visibility modifiers
+
 <!-- template:attributes -->
 r[macro.decl.scope.macro_use]
 ### The `macro_use` attribute
@@ -502,25 +535,6 @@ By default, macros only have [textual scope][macro.decl.scope.textual] and canno
 > # fn main() {}
 > ```
 
-r[macro.decl.scope.path.reexport]
-
-* macros can be re-exported to give them path-based scope from a module other than the crate root.
-    * there's some visibility stuff here that may already be mentioned
-      elsewhere. I'm pretty sure that w/o a #[macro_export] the macro being
-      re-exported is implicitly pub(crate) and with one it is implicitly pub.
-      The later is mentioned below, don't remember where I saw the former.
-
-```
-mac::m!(); // OK: Path-based lookup finds m in the mac module.
-
-mod mac {
-    macro_rules! m {
-        () => {};
-    }
-    pub(crate) use m;
-}
-```
-
 r[macro.decl.scope.macro_export.export]
 The `macro_export` attribute causes a macro to be exported from the crate root so that it can be referred to in other crates by path.
 
@@ -765,3 +779,4 @@ For more detail, see the [formal specification].
 [Repetitions]: #repetitions
 [token]: tokens.md
 [`$crate`]: macro.decl.hygiene.crate
+[Use declaration re-export]: items/use-declarations.html#use-visibility