--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/wm.tex	Sat Dec 22 17:52:45 2007 -0500
@@ -0,0 +1,411 @@
+\chapter{Warning and Error Messages}
+\index{Warning messages}\index{Error messages}\index{Messages}\index{Messages}
+
+AnaGram provides diagnostic messages in the \agwindow{Warnings} window
+when it finds constructs in your grammar which might be incorrect, or
+when it finds that it cannot continue its analysis of your grammar.
+AnaGram gives up only if it encounters a syntax error or finds that
+you have not specified a \index{Grammar token}\index{Token}grammar
+token.  Otherwise, it continues its analysis.  If AnaGram succeeds in
+analyzing your grammar, it will be in a position to build a parser for
+you, if you should want one.
+
+When AnaGram finds a syntax error in its input it attempts to continue
+scanning for syntax errors but it does no further analysis of the
+input.
+
+When AnaGram identifies a problem while it is scanning your syntax
+file, it precedes the diagnostic with the line number and column
+number at which it found the problem.  It does not provide line and
+column numbers for those problems it discovers when it is actually
+analyzing the grammar.
+
+As an aid to debugging, for all warnings developed while scanning the
+syntax file, AnaGram locks the cursor in the syntax file window to the
+cursor in the Warnings window.  This means that when you move the
+cursor bar in the Warnings window to a warning message that has a line
+number and column number, the cursor in the syntax file window is
+moved to the corresponding line and column.
+
+\section{Alphabetic Listing of Warning Messages}
+
+In this list of warning messages, each message is classified according
+to whether it is a warning or an error and according to when it
+occurs.  Errors prevent AnaGram from building a parser; warnings do
+not.  Messages may occur at program initialization, while scanning the
+syntax file, while analyzing the grammar, or while building the
+parser.  Messages issued while scanning the syntax file are always
+accompanied by the line and column number in the syntax file where the
+problem is recognized.
+
+% XXX I would like to change ``warning, analysis'' to ``analysis
+% warning'' for all these.
+
+\dualheading{Both error token resynch and auto resynch specified}
+{warning, analysis}
+
+Your grammar defines an \index{Error token}\index{Token}\agparam{error
+token} and also requests automatic resynchronization. AnaGram will
+ignore the request for automatic
+\index{Resynchronization}resynchronization and will provide error
+token \index{Resynchronization}resynchronization. If you named a token
+\agcode{error} but do not wish error token resynchronization, you can
+either rename \agcode{error}, or explicitly specify the error token to be
+something you don't use in your grammar:
+
+\begin{indentingcode}{0.4in}
+{}[ error token = not used ]
+\end{indentingcode}
+
+\dualheading{Conflicts resolved by precedence rules}
+{warning, analysis}
+
+Your grammar has conflicts which AnaGram has resolved by applying the
+precedence rules you supplied.  These conflicts are listed in the
+\index{Resolved Conflicts}\index{Window}\agwindow{Resolved Conflicts}
+window, and are not listed in the
+\index{Conflicts}\index{Window}\agwindow{Conflicts} window.
+
+\dualheading{Duplicate production}
+{warning, scan}
+
+A \index{Production}production has been duplicated.  You will have a
+number of reduce-reduce \index{Conflicts}conflicts as a consequence.
+Eliminate the duplicate, and the conflicts it caused will go away.
+
+\dualheading{Empty keyword string}
+{warning, scan}
+
+\index{Keywords}
+Keyword strings must contain at least one character.  If you wish a
+null match, use a null production instead.
+
+\dualheading{eof token not defined}
+{warning, analysis}
+
+\index{Eof token}\index{Token}
+You have requested either error token or automatic resynchronization
+and you have not defined an end of file token. The resynchronization
+procedure will not work correctly at end of file.
+
+\dualheading{Error defining T\textit{nnn}: \textit{token-representation}}
+{warning, analysis}
+
+Errors were encountered while attempting to evaluate the
+\index{Character set}character set for token number \textit{nnn}.
+This warning is always generated in addition to more detailed warnings
+that were made when the actual errors were encountered.
+
+\dualheading{Event driven parser cannot use pointer input}
+{error, build}
+
+\index{Parser}
+\index{Configuration switches}
+\index{Event driven}
+\index{Pointer input}
+If you are going to use \agparam{pointer input}, you should not
+specify your parser as \agparam{event driven}.
+Conversely, if you really want an event driven parser, you cannot specify
+\agparam{pointer input}.  See Appendix A, Configuration Parameters for
+details on the \agparam{pointer input} and \agparam{event driven}
+switches.
+
+\dualheading{Excessive recursion}
+{error, scan}
+
+An internal \index{Stack}stack in AnaGram overflowed because of the
+complexity of an expression in your grammar.  Simplify your grammar by
+using definition statements to name subexpressions.
+
+\dualheading{Fatal syntax errors}
+{error, analysis}
+
+AnaGram could not complete its analysis of your syntax file because of
+syntax errors.
+
+\dualheading{Grammar is ambiguous. See Conflicts Window}
+{warning, analysis}
+
+Your grammar is ambiguous.  See Chapter 7 for suggestions on how to
+deal with the ambiguities.
+
+\dualheading{Inappropriate value}
+{warning, scan}
+
+The value assigned to a configuration parameter is not appropriate.
+The value of the parameter is unchanged.  Check the definition of the
+parameter in Appendix A, Configuration Parameters.
+
+\dualheading{Input scan aborted}
+{error, scan}
+
+Because of the previous errors, AnaGram was unable to finish scanning
+your syntax file.
+
+\dualheading{Insufficient memory}
+{warning, scan or analysis}
+
+Not enough memory is available to continue parsing or analyzing the
+current syntax file.  If you have been running AnaGram for some time,
+you might succeed in analyzing your grammar if you restart AnaGram.
+Otherwise, you need more memory, or you need to make your grammar
+somewhat less complex.
+
+\dualheading{Internal error: ...}
+{error, any phase}
+
+This error results from internal consistency checks that should never
+fail if AnaGram is
+working properly.  If you are running AnaGram on Windows 95 or Windows
+98, it is
+probably not advisable to continue running AnaGram after receiving
+this warning without rebooting your system.  Sometimes when you are
+testing buggy programs using an operating system that does not have
+complete memory protection, a program may inadvertently alter part of
+the system's memory.  If this happens, problems may snowball.  In this
+situation the problem will not recur after you reboot your system.  If
+the problem recurs on a freshly booted system, it may be a problem in
+AnaGram which should be fixed. Please note the complete error message
+and file a bug report via \url{http://www.parsifalsoft.com}.
+\index{Internal error}\index{Errors}
+A copy of the syntax file which causes the problem
+would be of great assistance in fixing it.
+
+\dualheading{Keyword anomalies found}
+{warning, analysis}
+
+See the
+\index{Anomaly}\index{Keyword Anomalies}\agwindow{Keyword Anomalies}
+table for a list of the anomalies found in your syntax file.
+See Chapter 7 for a treatment of keyword anomalies.
+
+\dualheading{Missing \textit{syntactic-element-1} in
+\textit{syntactic-element-2}}
+{error, scan}
+
+AnaGram expects to see an instance of \textit{syntactic element 1} at
+this location in an instance of \textit{syntactic element 2}.  It
+cannot reliably continue parsing its input.  Therefore, it limits
+further analysis to scanning for syntax errors.
+
+\dualheading{Missing production, T\textit{nnn}: \textit{token-name}}
+{error, scan}
+
+\index{Production}
+Token number \textit{nnn}, a nonterminal token, appears to be defined
+recursively, but there is no initial production to get the recursion
+started.  Check your grammar closely.
+
+\dualheading{Missing reduction procedure, R\textit{nnn}}
+{warning, scan}
+
+\index{Reduction procedure}
+A reduction parameter has been defined in this rule, number
+\textit{nnn}, but there is no reduction procedure to use it.  This
+warning is provided in case the lack of a reduction procedure is an
+oversight.
+
+\dualheading{Multiple definitions for T\textit{nnn}: \textit{token-name}}
+{warning, analysis}
+
+\index{Definitions}
+Token number \textit{nnn} has been defined as a character set and has
+also been defined as a nonterminal token.  It can't be both.
+
+\dualheading{Negative character codes in pointer mode}
+{warning, analysis}
+
+\index{Character codes}
+You have defined negative character codes and you are using pointer
+input.  If you are using the default definition for pointer type you
+will be reading unsigned characters, so that your parser will never
+see the negative codes you have defined.
+
+% I wish there were an easy way to shut this up if the pointer type is
+% signed.
+
+\dualheading{No grammar token specified}
+{error, analysis}
+
+\index{Grammar token}\index{Token}
+You have not specified a grammar token.
+Edit your syntax file to specify one.
+
+\dualheading{No productions in syntax file}
+{error, analysis}
+
+AnaGram did not find any productions at all in the syntax file.  Do
+you have the right file?
+
+\dualheading{No such parameter}
+{warning, scan}
+
+AnaGram does not recognize the name of the configuration parameter you
+have tried to set.  Check the spelling of the parameter you wish to
+set.  See Appendix A, Configuration Parameters.
+
+\dualheading{Not a character set, T\textit{nnn}: \textit{token-name}}
+{warning, analysis}
+
+Token number \textit{nnn} has been used on the left side of a
+production and in a character set expression defining some other
+token.  AnaGram will use an empty set in place of token number
+\textit{nnn} in the character set expression.  You will get another
+warning, Error defining token, when AnaGram finishes its evaluation of
+the character set.
+
+\dualheading{Nothing reduces T\textit{nnn} -$>$ R\textit{mmm}}
+{warning, analysis}
+
+Your grammar does not specify any input to follow an instance of this
+rule, rule number \textit{mmm}.  In all probability, your grammar does
+not have any explicit end of file indicator.  If you do not have any
+conflicts with token T000, then you can get along without an end of
+file indicator.  Otherwise, you should modify your grammar so that it
+recognizes end of file.
+
+\dualheading{Null character in keyword string}
+{warning, scan}
+
+\index{Keywords}
+A keyword string cannot have an embedded null character.  If you must
+allow for a null you will have to rewrite your grammar rule.  For
+example, instead of
+
+\begin{indentingcode}{0.4in}
+widget
+  -> "abc{\bs}0def"
+\end{indentingcode}
+write
+\begin{indentingcode}{0.4in}
+widget
+  -> "abc", 0, "def"
+\end{indentingcode}
+
+If you have defined a symbol as a keyword string, you will have to
+rewrite the definition as a production. Suppose, for example, you had
+written
+
+\begin{indentingcode}{0.4in}
+marker = "abc{\bs}0def"
+\end{indentingcode}
+
+You would have to rewrite this as
+
+\begin{indentingcode}{0.4in}
+marker
+  -> "abc", 0, "def"
+\end{indentingcode}
+
+\dualheading{Parameter \textit{name} has type void}
+{warning, scan}
+
+The specified parameter for a reduction procedure attempts to take the
+value of a token whose type has been specified as void.
+
+\dualheading{Range bounds out of order}
+{warning, scan}
+
+\index{Character range}\index{Range}
+AnaGram interprets 'z-a', for example, as the letters from a to z, but
+provides a warning in case the unusual order was a typo.
+
+\dualheading{Recursive definition of char set: \textit{name}}
+{warning, analysis}
+
+\index{Character sets}
+Character sets cannot be defined recursively.
+
+\dualheading{Redefinition of \textit{name}}
+{warning, analysis}
+
+There is a previous definition statement for this variable.  AnaGram
+ignores the new definition.
+
+\dualheading{Redefinition of grammar token}
+{warning, scan}
+
+\index{Grammar token}\index{Token}
+AnaGram simply discards the old definition of the grammar, or goal,
+token and uses the new one.  The last definition in the syntax file
+wins.  Check your syntax file to be sure you have the grammar token
+you want.
+
+\dualheading{Redefinition of token, T\textit{nnn}: \textit{name}}
+{warning, scan}
+
+This variable has already been used as a nonterminal token, that is,
+it has been used as the left side of a production.  AnaGram will
+ignore this definition statement.
+
+\dualheading{Suspicious production for \textit{token name}}
+{warning, scan}
+
+This production has the form
+
+\begin{indentingcode}{0.4in}
+x -> x
+\end{indentingcode}
+
+You probably have a typo somewhere.  This production causes a conflict
+in your grammar.  AnaGram leaves this production in your grammar, but
+if you build a parser, it will never succeed in recognizing this
+production.
+
+\dualheading{Syntax Analysis Aborted}
+{error, analysis}
+
+Because of the previous errors, AnaGram was unable to complete its
+analysis of your syntax file.
+
+\dualheading{Token not used, T\textit{nnn}: \textit{token name}}
+{warning, analysis}
+
+AnaGram doesn't mind, but warns you just in case there was some sort
+of oversight.
+
+\dualheading{Type Redefinition of T\textit{nnn}: \textit{token name}}
+{warning, analysis}
+
+A previous statement has defined a different data type for token
+number \textit{nnn}.  This definition will override the previous one.
+If you intend to use different type definitions, you should use
+extreme caution and check the generated code to verify that your
+reduction procedures are getting the values you intended.
+
+\dualheading{Undefined symbol: \textit{name}}
+{warning, analysis}
+
+\index{Symbol}
+AnaGram encountered this undefined symbol while evaluating a character
+set.  The next warning in the Warnings window identifies the
+particular token AnaGram was trying to evaluate.
+
+\dualheading{Undefined token T\textit{nnn}: \textit{name}}
+{warning, analysis}
+
+\index{Token}
+This name has been used as though it represented a token, but there is
+no definition of it as a terminal nor does any production define it as
+a nonterminal.
+
+\dualheading{Unexpected \textit{syntactic-element-1} in
+\textit{syntactic-element-2}}
+{error, scan}
+
+AnaGram does not expect to see an instance of
+\textit{syntactic-element-1} at this location in an instance of
+\textit{syntactic-element-2}.
+It cannot reliably continue parsing its input.  Therefore, it limits
+further analysis to scanning for syntax errors.  If this error is not
+the result of some prior error, you should correct your syntax file.
+Remember that this error could just as well result from something
+missing as well as from something extraneous.
+
+\dualheading{Void token, \textit{token-name}, used as parameter}
+{warning, scan}
+
+\index{Token}
+The token being declared as void has previously been used as a
+parameter for a reduction procedure.  Your C compiler will complain
+when it tries to compile the call to the reduction procedure.