---

yaml
---
r: 30072
b: refs/heads/incoming
c: 9297d1f
h: refs/heads/master
v: v3

Author: paulstansifer

[refs]

@@ -6,7 +6,7 @@ refs/heads/try: d324a424d8f84b1eb049b12cf34182bda91b0024
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
 refs/heads/try2: d0c6ce338884ee21843f4b40bf6bf18d222ce5df
-refs/heads/incoming: 7669032dd377d6207c4d78e52c9e858e2f2d4180
+refs/heads/incoming: 9297d1f00a27ac6bb272d5b2b75535697f1e2e4b
 refs/heads/dist-snap: 2f32a1581f522e524009138b33b1c7049ced668d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/incoming/doc/rust.md

@@ -522,7 +522,8 @@ matches, in a structure that mimics the structure of the repetition
 encountered on a successful match. The job of the transcriber is to sort that
 structure out.
 
-The rules for transcription of these repetitions are called "Macro By Example". Essentially, one "layer" of repetition is discharged at a time, and all of
+The rules for transcription of these repetitions are called "Macro By Example".
+Essentially, one "layer" of repetition is discharged at a time, and all of
 them must be discharged by the time a name is transcribed. Therefore,
 `( $( $i:ident ),* ) => ( $i )` is an invalid macro, but
 `( $( $i:ident ),* ) => ( $( $i:ident ),*  )` is acceptable (if trivial).
@@ -537,6 +538,20 @@ transcribes to `( (a,d), (b,e), (c,f) )`.
 
 Nested repetitions are allowed.
 
+### Parsing limitations
+
+The parser used by the macro system is reasonably powerful, but the parsing of
+Rust syntax is restricted in two ways:
+
+1. The parser will always parse as much as possible. If it attempts to match
+`$i:expr [ , ]` against `8 [ , ]`, it will attempt to parse `i` as an array
+index operation and fail. Adding a separator can solve this problem.
+2. The parser must have eliminated all ambiguity by the time it reaches a
+`$` _name_ `:` _designator_. This most often affects them when they occur in
+the beginning of, or immediately after, a `$(...)*`; requiring a distinctive
+token in front can solve the problem.
+
+
 ## Syntax extensions useful for the macro author
 
 * `log_syntax!` : print out the arguments at compile time

branches/incoming/doc/tutorial.md

@@ -2481,8 +2481,9 @@ Macros, as currently implemented, are not for the faint of heart. Even
 ordinary syntax errors can be more difficult to debug when they occur inside
 a macro, and errors caused by parse problems in generated code can be very
 tricky. Invoking the `log_syntax!` macro can help elucidate intermediate
-states, and using `--pretty expanded` as an argument to the compiler will
-show the result of expansion.
+states, using `trace_macros!(true)` will automatically print those
+intermediate states out, and using `--pretty expanded` as an argument to the
+compiler will show the result of expansion.
 
 # Traits