Added [embedded] to standard.mly. Extensive comment.

TODO

 * Document anonymous rules.
   Produce well-chosen (predictable) names for anonymous rules.
+  In the standard library, possibly rename "anonymous" and "embedded"
+  and document them. The non-inline version allows embedding an action in the
+  middle of a rule.
 
 * ErrorReporting: experiment with merging several symbols
   so as to reduce the noise (e.g. operators, expressions,

src/standard.mly

@@ -9,11 +9,71 @@
 
 (* [anonymous(X)] is the same as [X]. *)
 
-(* This can be useful because it allows placing an anonymous sub-rule in
-   the middle of a rule, as in [foo anonymous(bar { ... } | quux { ...}) baz]. *)
+(* This allows placing an anonymous sub-rule in the middle of a rule, as in:
+
+     foo
+     anonymous(baz { action1 })
+     bar
+     { action2 }
+
+   Because anonymous is marked %inline, everything is expanded away. So,
+   this is equivalent to:
+
+     foo baz bar { action1; action2 }
+
+   Note that [action1] moves to the end of the rule. The anonymous sub-rule
+   can even have several branches, as in:
+
+     foo
+     anonymous(baz { action1a } | quux { action1b })
+     bar
+     { action2 }
+
+   This is expanded to:
+
+     foo baz  bar { action1a; action2 }
+   | foo quux bar { action1b; action2 }
+
+*)
 
 %public %inline anonymous(X):
-  x = X
+x = X
+    { x }
+
+(* [embedded(X)] is the same as [X]. *)
+
+(* This allows placing an anonymous sub-rule in the middle of a rule, as in:
+
+     foo
+     embedded(baz { action1 })
+     bar
+     { action2 }
+
+   Because [embedded] is not marked %inline, this is equivalent to:
+
+     foo xxx bar { action2 }
+
+   where the fresh non-terminal symbol [xxx] is separately defined by:
+
+     xxx: baz { action1 }
+
+   In particular, if there is no [baz], what we get is a semantic action
+   embedded in the middle of a rule. For instance,
+   
+     foo embedded({ action1 }) bar { action2 }
+
+   is equivalent to:
+
+     foo xxx bar { action2 }
+
+   where [xxx] is separately defined by the rule:
+
+     xxx: { action1 }
+
+*)
+
+%public embedded(X):
+x = X
     { x }
 
 (* ------------------------------------------------------------------------- *)