added first FAQ

[sbp.git] / src / edu / berkeley / sbp / package.html

diff --git a/src/edu/berkeley/sbp/package.html b/src/edu/berkeley/sbp/package.html
index 6841473..4aab655 100644 (file)
--- a/src/edu/berkeley/sbp/package.html
+++ b/src/edu/berkeley/sbp/package.html
@@ -5,7 +5,8 @@
    APIs and all other packages are subject to change in future
    releases.<br><br>Be sure to read <a
    href=../../../../jargon.txt>doc/jargon.txt</a> and the <a
-   href=#package_description>description</a> below.
+   href=#package_description>description</a> below.  There is also a
+   <a href=#faq>faq</a> a the end of this document.
 
 </p>
 
@@ -79,7 +80,7 @@ If the parse was <i>not</i> ambiguous, you can call
 
 </p>
           
-<a name=example>
+<a name=example></a>
 <h2>Guide to the API</h2>
           
 <h2>Example</h2>
@@ -166,6 +167,62 @@ Expr&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=&nb
 output:&nbsp;add:{8&nbsp;+&nbsp;mult:{add:{1&nbsp;+&nbsp;3}&nbsp;*&nbsp;7}}<br>
 </div>
 
+<h2>FAQs</h2>
+
+<hr>
+<p>
+<b>I get the error <tt>java.lang.Error: multiple non-dropped elements
+   in sequence</tt>, what does this mean?</b>
+</p>
+
+<p>
+<font color=red><b>Note</b></font>: this question deals with the
+package <tt>edu.berkeley.sbp.<b>meta</b></tt>, which is not considered
+stable.
+</p>
+
+<p>
+When using the class <tt>edu.berkeley.sbp.meta.Grammar</tt>, you must
+supply an instance of <tt>Grammar.Bindings</tt>; this instance tells
+SBP how to create a parse tree for an expression using the parse trees
+of its subexpressions.
+</p>
+
+<p>
+SBP has no trouble determining what to do when parsing an expression
+that drops all of its subexpressions, or all but one -- for example:
+</p>
+
+<div class=example>
+A = B! C D! E!
+</div>
+
+<p>
+... in this example, only <tt>C</tt> is "non-dropped".  In this case,
+the result of parsing <tt>A</tt> is simply the result of parsing
+<tt>C</tt>.
+</p>
+
+<p>
+However, if we were to leave more than one element un-dropped, SBP
+needs to know how to form a single tree out of the two non-dropped
+subtrees.  There are two ways to do this.  The simplest is to provide
+a tag -- a string which becomes the common parent of the two subtrees:
+</p>
+
+<div class=example>
+Expr = <b>Mult::</b>  Expr "*" Expr
+</div>
+
+<p>
+If you are using <tt>AnnotationGrammarBindings</tt>, you can also deal
+with this situation by declaring a method/inner-class whose name
+matches the nonterminal (<tt>Expr</tt>) and has appropriate
+annotations.  This is fairly advanced stuff, and the code it uses
+isn't quite as mature as the rest of the code.
+</p>
+
+
 <h2>Reporting Bugs</h2>
 
 <p>