---

yaml
---
r: 193114
b: refs/heads/beta
c: df08657
h: refs/heads/master
v: v3

Author: Keegan McAllister

[refs]

@@ -31,7 +31,7 @@ refs/heads/automation-fail: 1bf06495443584539b958873e04cc2f864ab10e4
 refs/heads/issue-18208-method-dispatch-3-quick-reject: 2009f85b9f99dedcec4404418eda9ddba90258a2
 refs/heads/batch: b7fd822592a4fb577552d93010c4a4e14f314346
 refs/heads/building: 126db549b038c84269a1e4fe46f051b2c15d6970
-refs/heads/beta: 1804242a2d4037fd3ae854989a97a65e16bda05a
+refs/heads/beta: df0865754e56d3d804df3b2bb15d405e344e2015
 refs/heads/windistfix: 7608dbad651f02e837ed05eef3d74a6662a6e928
 refs/tags/1.0.0-alpha: e42bd6d93a1d3433c486200587f8f9e12590a4d7
 refs/heads/tmp: de8a23bbc3a7b9cbd7574b5b91a34af59bf030e6

branches/beta/src/doc/trpl/macros.md

@@ -189,14 +189,12 @@ shorthand for a data type could be valid as either an expression or a pattern.
 
 ## Repetition
 
-The repetition behavior can seem somewhat magical, especially when multiple
-names are bound at multiple nested levels of repetition. The two rules to keep
-in mind are:
+The repetition operator follows two principal rules:
 
-1. the behavior of `$(...)*` is to walk through one "layer" of repetitions, for
-all of the `$name`s it contains, in lockstep, and
+1. `$(...)*` walks through one "layer" of repetitions, for all of the `$name`s
+   it contains, in lockstep, and
 2. each `$name` must be under at least as many `$(...)*`s as it was matched
-against. If it is under more, it'll be duplicated, as appropriate.
+   against. If it is under more, it'll be duplicated, as appropriate.
 
 This baroque macro illustrates the duplication of variables from outer
 repetition levels.
@@ -226,6 +224,10 @@ That's most of the matcher syntax. These examples use `$(...)*`, which is a
 more" match. Both forms optionally include a separator, which can be any token
 except `+` or `*`.
 
+This system is based on
+"[Macro-by-Example](http://www.cs.indiana.edu/ftp/techreports/TR206.pdf)"
+(PDF link).
+
 # Hygiene
 
 Some languages implement macros using simple text substitution, which leads to
@@ -273,19 +275,26 @@ macro, using [a GNU C extension] to emulate Rust's expression blocks.
 })
 ```
 
-This looks reasonable, but watch what happens in this example:
+Here's a simple use case that goes terribly wrong:
 
 ```text
 const char *state = "reticulating splines";
-LOG(state);
+LOG(state)
 ```
 
-The program will likely segfault, after it tries to execute
+This expands to
 
 ```text
-printf("log(%d): %s\n", state, state);
+const char *state = "reticulating splines";
+int state = get_log_state();
+if (state > 0) {
+    printf("log(%d): %s\n", state, state);
+}
 ```
 
+The second variable named `state` shadows the first one.  This is a problem
+because the print statement should refer to both of them.
+
 The equivalent Rust macro has the desired behavior.
 
 ```rust