Documentation

r2/libmarpa/dev/api.texi

@@ -819,7 +819,14 @@ To fully generalize the input model,
 we now need to remove only one restriction.
 We now allow empty earlemes -- earlemes with
 no tokens and no Earley set.
-
+For the generalized input model,
+the effect on the earleme variables of
+a call
+to @code{marpa_r_alternative()} is exactly
+the same as it is for the variable length input model.
+The effect on the earleme variables of a call to
+to @code{marpa_r_earleme_complete()} depends on
+whether or not that call creates an empty earleme.
 A call
 to @code{marpa_r_earleme_complete()},
 creates an empty earleme if and only if
@@ -836,23 +843,59 @@ the previous call
 to @code{marpa_r_earleme_complete()}.
 @end itemize
 
-If a call to @code{marpa_r_earleme_complete()} creates
-an empty earleme,
-the latest earleme remains unchanged from its
-prior value.
-This means that, since the current earleme will
-change, the latest earleme will be less
-than the current earleme.
-As always the furthest earleme is unchanged by
-the call to @code{marpa_r_earleme_complete()}.
+Suppose, in the generalized input model that,
+for a call
+to @code{marpa_r_earleme_complete()}
+that creates an empty earleme,
+the following is true:
+@itemize
+@item The current earleme before the call is @var{c}.
+@item The latest earleme before the call is @var{old_l}.
+@item The furthest earleme before the call is @var{old_f}.
+@end itemize
+In that case,
+after the call
+to @code{marpa_r_earleme_complete()},
+the following would be true:
+@itemize
+@item The current earleme would be advanced to @var{c+1}.
+@item The latest earleme will remain at @var{old_l}.
+This means that the latest earleme will be less than
+the current earleme.
+@item The furthest earleme will remain at @var{old_f}.
+The furthest earleme is never changed by a call
+to @code{marpa_r_earleme_complete()}.
+@end itemize
+
+Suppose, in the generalized input model that,
+for a call
+to @code{marpa_r_earleme_complete()}
+that does not creates an empty earleme,
+the following is true:
+@itemize
+@item The current earleme before the call is @var{c}.
+@item The latest earleme before the call is @var{old_l}.
+@item The furthest earleme before the call is @var{old_f}.
+@end itemize
+In that case,
+after the call
+to @code{marpa_r_earleme_complete()},
+the following would be true:
+@itemize
+@item The current earleme would be advanced to @var{c+1}.
+@item The latest earleme will be advanced to @var{c+1}.
+@item The furthest earleme will remain at @var{old_f}.
+The furthest earleme is never changed by a call
+to @code{marpa_r_earleme_complete()}.
+@end itemize
 
 @node General rules for the earleme variables,  , The generalized model, Earlemes
 @subsection General rules for the earleme variables
 
 At this point, the most generalized input model has been
 introduced.
-Next we state some facts that will always be the case,
-no matter what input model is in use.
+Here are some useful facts about the earleme variables that will always be the case,
+no matter which of the input models is in use.
 
 @itemize
 @item The current earleme is greater than