fix javadoc generation

[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 c55b5cb..e8863d0 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,6 +80,7 @@ If the parse was <i>not</i> ambiguous, you can call
 
 </p>
           
+<a name=example></a>
 <h2>Guide to the API</h2>
           
 <h2>Example</h2>
@@ -165,4 +167,82 @@ 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>
 
+<a name=faq></a>
+<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>
+
+Bug reports are especially appreciated when you submit them as a test
+case (here's the
+<a href=../../../../../tests/testcase.g>grammar</a> and some
+<a href=../../../../../tests/regression.tc>examples</a>).
+
+This way we can add your bug report as part of the regression suite,
+and be sure we never release a new version in which the bug has crept
+back in!
+
+</p>
+
+<p>
+For now, please send bug reports to <a
+href=http://research.cs.berkeley.edu/project/sbp/list/>the mailing
+list</a>.
+</p>
+
 </body>