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).
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
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