---

yaml
---
r: 135749
b: refs/heads/auto
c: 4ced7a9
h: refs/heads/master
i:
  135747: d01c151
v: v3

Author: Keegan McAllister

[refs]

@@ -13,7 +13,7 @@ refs/heads/try3: 9387340aab40a73e8424c48fd42f0c521a4875c0
 refs/tags/release-0.3.1: 495bae036dfe5ec6ceafd3312b4dca48741e845b
 refs/tags/release-0.4: e828ea2080499553b97dfe33b3f4d472b4562ad7
 refs/tags/release-0.5: 7e3bcfbf21278251ee936ad53e92e9b719702d73
-refs/heads/auto: c8bdba77fca16ebf5ad6c63a37a8dd8fd2afda8e
+refs/heads/auto: 4ced7a9637c10196883733fa81ac67d02269a76e
 refs/heads/servo: af82457af293e2a842ba6b7759b70288da276167
 refs/tags/release-0.6: b4ebcfa1812664df5e142f0134a5faea3918544c
 refs/tags/0.1: b19db808c2793fe2976759b85a355c3ad8c8b336

branches/auto/src/doc/guide-macros.md

@@ -448,6 +448,66 @@ fn main() {
 The two `'x` names did not clash, which would have caused the loop
 to print "I am never printed" and to run forever.
 
+# Scoping and macro import/export
+
+Macros occupy a single global namespace. The interaction with Rust's system of
+modules and crates is somewhat complex.
+
+Definition and expansion of macros both happen in a single depth-first,
+lexical-order traversal of a crate's source. So a macro defined at module scope
+is visible to any subsequent code in the same module, which includes the body
+of any subsequent child `mod` items.
+
+If a module has the `macro_escape` attribute, its macros are also visible in
+its parent module after the child's `mod` item. If the parent also has
+`macro_escape` then the macros will be visible in the grandparent after the
+parent's `mod` item, and so forth.
+
+Independent of `macro_escape`, the `macro_export` attribute controls visibility
+between crates.  Any `macro_rules!` definition with the `macro_export`
+attribute will be visible to other crates that have loaded this crate with
+`phase(plugin)`. There is currently no way for the importing crate to control
+which macros are imported.
+
+An example:
+
+```rust
+# #![feature(macro_rules)]
+macro_rules! m1 (() => (()))
+
+// visible here: m1
+
+mod foo {
+    // visible here: m1
+
+    #[macro_export]
+    macro_rules! m2 (() => (()))
+
+    // visible here: m1, m2
+}
+
+// visible here: m1
+
+macro_rules! m3 (() => (()))
+
+// visible here: m1, m3
+
+#[macro_escape]
+mod bar {
+    // visible here: m1, m3
+
+    macro_rules! m4 (() => (()))
+
+    // visible here: m1, m3, m4
+}
+
+// visible here: m1, m3, m4
+# fn main() { }
+```
+
+When this library is loaded with `#[phase(plugin)] extern crate`, only `m2`
+will be imported.
+
 # A final note
 
 Macros, as currently implemented, are not for the faint of heart. Even