Minor doc updates.

Author: paulstansifer

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

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