Document.

CHANGES

+2015/06/29:
+Changed the treatment of positional parameters which are now
+rewritten into named parameters of the form '_i' where 'i'
+is an integer.
+
 2015/02/11:
 Added support for anonymous rules. This allows writing, e.g.,
 list(e = expression SEMI { e })

doc/main.tex

@@ -516,7 +516,9 @@ semantic values of the terminal or nonterminal symbols that appear in the
 production via the semantic value identifiers bound by the production. For
 compatibility with \ocamlyacc, semantic actions can also refer to these
 semantic values via positional keywords of the form
-\kw{\$1}, \kw{\$2}, etc.\ This style is discouraged.
+\kw{\$1}, \kw{\$2}, etc.\ This style is discouraged. Furthermore, as
+a positional keyword of the form \kw{\$i} is internally rewritten as
+\nt{\_i}, such identifiers are forbidden.
 
 \paragraph{\dprec annotations}
 \label{sec:prec}

src/keyword.mli

@@ -18,7 +18,12 @@ type where =
 
 (* The user can request position information about a production's
    left-hand side or about one of the symbols in its right-hand
-   side, which he can refer to by position or by name. *)
+   side, which he can refer to by position or by name.
+
+   A positional reference of the form [$i] is a syntactic sugar for the
+   name [_i]. This surface syntax is first parsed as a [parsed_subject]
+   and desugared as a [subject] during keywords rewriting into actual
+   OCaml identifiers. (See {!Lexer.transform_keywords}) *)
 type parsed_subject =
   | PLeft
   | PRightDollar of int
@@ -29,8 +34,11 @@ and subject =
   | RightNamed of string
 
 (* Keywords inside semantic actions. They allow access to semantic
-   values or to position information. *)
+   values or to position information.
 
+   As said previously, a positional reference is a syntactic sugar
+   which appears in a [parsed_keyword] but is desugared in the
+   actual [keyword] representation. *)
 type parsed_keyword =
   | PDollar of int
   | PPosition of parsed_subject * where * flavor

src/parserAux.ml

@@ -49,6 +49,8 @@ let check_production_group right_hand_sides =
   end;
   right_hand_sides
 
+(* [normalize_producer i p] assigns a name of the form [_i]
+   to the unnamed producer [p]. *)
 let normalize_producer i (pos, opt_identifier, parameter) =
   let id =
     match opt_identifier with