--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/winsum.tex	Sat Dec 22 17:52:45 2007 -0500
@@ -0,0 +1,437 @@
+\chapter{Alphabetic Listing of Windows}
+
+\index{Windows}
+The following paragraphs summarize the windows AnaGram provides. More
+detailed descriptions may be found in Chapters 5, 6 and 7. In addition
+to these windows AnaGram always provides a window to allow you to
+inspect your syntax file. It is always listed in the \agmenu{Browse}
+menu.
+
+\index{Trace}\index{Auxiliary Trace}\index{Window}
+\paragraph{Auxiliary Trace.}
+\agwindow{Auxiliary Trace} windows may be accessed through the
+\agmenu{Auxiliary Windows} popup menu for most windows which display
+parser state information.  The \agwindow{Auxiliary Trace} is a
+prebuilt \agwindow{Grammar Trace} showing one of perhaps many ways to
+get to the state identified by the cursor bar in the active window.
+
+When obtained from the \agwindow{Parser Stack} pane of the
+\agwindow{File Trace} or \agwindow{Grammar Trace}, the
+\agwindow{Auxiliary Trace} is simply a copy of the current status of
+the trace so you can explore alternatives while still retaining the
+status of the original trace for reference.
+
+\index{Window}\index{Character Map}
+\paragraph{Character Map.}
+The \agwindow{Character Map} table shows you the mapping of input
+characters to token numbers.  The \agcode{ag{\us}tcv} table in your
+parser is based on the information in this table.
+
+\index{Character Sets}\index{Window}
+\paragraph{Character Sets.}
+This table lists all of the distinct character sets which you defined,
+implicitly or explicitly, in your grammar.  Each line in the table
+describes one such set.
+
+\index{Window}\index{Configuration Parameters}
+\paragraph{Configuration Parameters.}
+The \agwindow{Configuration Parameters} window lists the configuration
+parameters AnaGram accepts with their current values, as set by the
+configuration files it has read and by the most recent syntax file it
+has analyzed.  This window does not include the color settings for the
+screen, which are controlled separately by the \agwindow{Set Colors}
+window.
+% XXX should expand that to say it doesn't include the user interface
+% preferences, because it's not just colors but fonts and other things.
+
+\index{Trace}\index{Window}\index{Conflict Trace}
+\paragraph{Conflict Trace.}
+You may select a \agwindow{Conflict Trace} window from the
+\agmenu{Auxiliary Windows} menu of either a \agwindow{Conflicts} or
+\agwindow{Resolved Conflicts} window.  The \agwindow{Conflict Trace}
+is a ready-made \agwindow{Grammar Trace} which shows you one of
+perhaps many ways to get to the state which has the conflict you
+selected.  The use of this window is explained more fully in Chapter
+7.
+
+\index{Conflicts}\index{Window}
+\paragraph{Conflicts.}
+The \agwindow{Conflicts} window lists the conflicts which AnaGram
+found in your grammar.  The table identifies the parser states in which
+it found conflicts, the reducing tokens for which it had more than one
+option, and the marked rules which characterize each such option.  If
+AnaGram was able to resolve a conflict by using
+\index{Precedence declarations}\agparam{precedence} or
+\index{Sticky declaration}\agparam{sticky} declarations, the conflict
+will be listed in the
+\index{Resolved Conflicts}\index{Window}\agwindow{Resolved Conflicts}
+window instead.
+
+% XXX that should be ``Conflicts window'', not ``menu'', right?
+The \agmenu{Auxiliary Windows} menu for the Conflicts menu includes a
+number of options specially designed to help in identifying the source
+of conflicts.  These are the \agwindow{Conflict Trace}, the
+\agwindow{Reduction Trace}, the \agwindow{Expansion Chain}, the
+\agwindow{Rule Derivation} and the \agwindow{Token Derivation}
+windows.  The use of these windows is explained more fully in Chapter
+7.
+
+\paragraph{Control Panel.}
+The \agwindow{Control Panel} is the main AnaGram window.  It contains
+pull down menus to provide access to AnaGram functionality.  In
+addition there is a panel of buttons to invoke the most frequently
+used AnaGram functions.  A text box can be used to enter text to
+search for.  Next to the text box are buttons that implement forward
+and reverse searching.  Searching is always in the most recently
+active AnaGram window.
+
+\index{Trace}\index{Window}\index{Error Trace}
+\paragraph{Error Trace.}
+If you (1) turn on the
+\index{Error trace}\index{Configuration switches}\agparam{error trace}
+configuration switch for your grammar, (2) build a parser from your
+grammar, (3) run the parser and encounter a syntax error, your parser
+will checkpoint the parser stack to a file.  If you then run AnaGram
+again and analyze the grammar, AnaGram will read the checkpoint file
+and prepare a pre-built \agwindow{Grammar Trace} (see below) which
+shows how your parser got to the state where it encountered the error.
+% XXX get rid of ``(see below)'', or maybe change it to ``window''
+
+\index{Expansion Chain}\index{Window}
+\paragraph{Expansion Chain.}
+The \agwindow{Expansion Chain} window is available in the
+\agmenu{Auxiliary Windows} menu from any window that contains
+expansion rules.  Its purpose is to show how a particular expansion
+rule in a particular state derives from a characteristic rule for that
+state.  The first rule in the window is a characteristic rule for the
+given state.  Each subsequent rule is produced by the marked token in
+the preceding rule.  The last rule is the rule selected by the cursor
+bar in the parent window.
+
+\index{Expansion Rules}\index{Window}
+\paragraph{Expansion Rules.}
+The \agwindow{Expansion Rules} window is available in the
+\agmenu{Auxiliary Windows} menu from any window that identifies
+tokens.  It displays a complete left expansion of the selected token
+if the token is nonterminal.  That is, it is a list of rules that
+begins with all the rules produced by the token followed by all the
+rules produced by the first token of any rule in the list.
+% XXX ...clear as mud.
+
+\index{Trace}\index{Window}\index{File Trace}
+\paragraph{File Trace.}
+Select the \agwindow{File Trace} window from the \agmenu{Action} menu.
+The \agwindow{File Trace} window lets you see precisely how your
+grammar parses a test file.  You can see the contents of the parse
+stack at any point in the parse.  You can watch the parse progress at
+any level of detail you choose.  If you wish, you may back up and try
+again. When AnaGram runs the \agwindow{File Trace} it also builds a
+\index{Trace Coverage}\index{Coverage}\agwindow{Trace Coverage} table.
+
+Note that AnaGram normally uses a number of short-cut parsing actions.
+To make the parse look like a textbook parse, set the
+\index{Traditional engine}\index{Configuration switches}
+\agparam{traditional engine} configuration parameter in your syntax file.
+
+\index{Trace}\index{Window}\index{Grammar Trace}
+\paragraph{Grammar Trace.}
+The \agwindow{Grammar Trace} facility of AnaGram allows you to examine
+the workings of your parser in detail.  Using the various options
+associated with this window you can set up a representation of the
+parser state stack and parser state as they might appear in the course
+of execution of your parser.  You can then examine the possible inputs
+and the changes to the state and the state stack caused by any input
+you choose.
+
+You can select input options interactively and see how the parser
+stack changes.  You can back up and try other options.  You can also
+enter text directly in the text entry field.  By selecting an 
+\agwindow{Auxiliary Trace} from the popup menu in the \agwindow{Parser
+Stack} pane, you can compare the results of different sequences of
+input starting at the same point.  You may bypass AnaGram's parser
+optimization by setting the
+\index{Traditional engine}\index{Configuration switches}
+\agparam{traditional engine}
+configuration switch in your syntax file.  When AnaGram runs the
+\agwindow{Grammar Trace} it also builds a \agwindow{Trace Coverage}
+table or updates the existing one if one already exists.
+
+The use of the \agwindow{Grammar Trace} is described in detail in
+Chapter 5.
+
+\index{Help}\index{Help Topics}\index{Window}
+\paragraph{Help Topics.}
+The \agwindow{Help Topics} window is an alphabetical list of all the
+help topics in AnaGram's help file.  Some help topics can be accessed
+by more than one key word, so there are actually a few more entries in
+this table than there are help topics.
+
+There is an entry for the \agwindow{Help Topics} window in the
+\agmenu{Help} menu.
+
+\index{Keyword Anomalies}\index{Window}
+\paragraph{Keyword Anomalies.}
+This window is available only if your grammar has keyword anomalies.
+Each entry in the \agwindow{Keyword Anomalies} window consists of two
+lines.  The first line identifies the parser state in which the
+anomaly occurs and the offending keyword.  The second line identifies
+the grammar rule which the keyword may erroneously reduce.
+
+\index{Trace}\index{Window}\index{Keyword Anomaly Trace}
+\paragraph{Keyword Anomaly Trace.}
+The \agwindow{Keyword Anomaly Trace} window is a prebuilt
+\agwindow{Grammar Trace} accessible through the \agmenu{Auxiliary
+Windows} menu from the 
+\index{Keyword Anomalies}\index{Window}\agwindow{Keyword Anomalies}
+window.  This trace shows one of perhaps many ways to get to the state
+which has the keyword anomaly selected in the \agwindow{Keyword
+Anomalies} window.
+
+\index{Keywords} \index{Window}
+\paragraph{Keywords.}
+A \agwindow{Keywords} window is accessible from the
+\agmenu{Auxiliary Windows} popup menu of any window that identifies
+parser states.  It displays all the keywords the parser will recognize
+in that state, regardless of whether they are used as shift or as
+reducing tokens.
+
+\index{Partition Sets}\index{Window}
+\paragraph{Partition Sets.}
+In the \agmenu{Browse} menu, \agwindow{Partition Sets} lists all the
+partition sets that cover the character universe.  In an
+\agmenu{Auxiliary Windows} menu, \agwindow{Partition Sets} shows the
+partition sets that cover the character set identified in the parent
+window.
+
+\index{Window}\index{Previous States}
+\paragraph{Previous States.}
+A \agwindow{Previous States} window can be accessed via the
+\agmenu{Auxiliary Windows} menu from any window which identifies
+parser states.  It shows the defining rules for all the states which
+jump to the specified state.
+
+\index{Window}\index{Productions}
+\paragraph{Productions.}
+The \agwindow{Productions} window can be accessed using the
+\agmenu{Auxiliary Windows} menu from any window that identifies
+tokens.  If the selected token is a nonterminal, the
+\agwindow{Productions} window will display all the grammar rules it
+produces.
+
+\index{Reduction Procedures}\index{Window}
+\paragraph{Reduction Procedures.}
+The \agwindow{Reduction Procedures} window lists all of the reduction
+procedures you have defined in your grammar.  Each line of the table
+gives the C/C++ function prototype.  When this window is active, the
+syntax file window is synchronized with the cursor to show you the
+text of the reduction procedure.
+
+\index{Window}\index{Reduction States}
+\paragraph{Reduction States.}
+A \agwindow{Reduction States} window can be accessed via the 
+\agmenu{Auxiliary Windows} popup menu from most windows which display
+marked rules with a specified state.  In this case, if the highlighted
+rule is complete, that is, there is at is no marked token, the
+\agwindow{Reduction States} window will show you all the possible
+states the parser could go to on reducing the rule.
+% XXX ``is at is no''?
+% XXX s/on reducing/upon reducing/
+
+\index{Reduction Trace}\index{Trace}\index{Window}
+\paragraph{Reduction Trace.}
+A \agwindow{Reduction Trace} window can be requested using the
+\agmenu{Auxiliary Windows} popup menu from a \agwindow{Conflicts}
+window or a \agwindow{Resolved Conflicts} window.  The
+\agwindow{Reduction Trace} is coordinated with the \agwindow{Conflict
+Trace} window, so that the \agwindow{Reduction Trace} shows the result
+of reducing the selected rule in the \agwindow{Conflict Trace} window.
+
+\index{Resolved Conflicts}\index{Window}
+\paragraph{Resolved Conflicts.}
+AnaGram creates the \agwindow{Resolved Conflicts} window only when the
+grammar it is analyzing has conflicts and when some of those conflicts
+have been resolved by precedence rules or by use of the
+\agparam{sticky} directive.  In this case, it will list, in the
+\agwindow{Resolved Conflicts} window, the conflicts that were resolved
+and the way in which they were resolved.  Rules which your parser will
+observe are marked with asterisks.  Those which your parser will
+ignore will not be so marked.  Any unresolved conflicts will be listed
+in the \agwindow{Conflicts} window.
+
+\index{Rule Context}\index{Window}
+\paragraph{Rule Context.}
+A \agwindow{Rule Context} window can be requested using the 
+\agmenu{Auxiliary Windows} menu from any window that identifies
+grammar rules.  It shows the usage of all tokens that produce the
+selected rule.
+
+\index{Rule Coverage}\index{Window}\index{Coverage}
+\paragraph{Rule Coverage.}
+If you have enabled the
+\index{Rule coverage}\index{Configuration switches}\agparam{rule coverage}
+configuration switch, your parser will have the capability of counting
+the number of times each rule in the grammar is reduced during
+execution of your parser.  The \agwindow{Rule Coverage} option on the
+\agmenu{Browse} menu will be enabled so you can select a rule count
+file.
+% XXX s/execution of your parser/execution/
+% XXX s/have the capability of counting/will be able to count/
+
+% XXX s/menu, from the/menu of the/ ?
+\index{Rule Derivation}\index{Window}
+\paragraph{Rule Derivation.}
+You may select a \agwindow{Rule Derivation} from the \agmenu{Auxiliary
+Windows} menu, from the \agwindow{Conflicts} window, the
+\agwindow{Resolved Conflicts} window, or the \agwindow{Keyword
+Anomalies} window.  The purpose of this window is to show how a
+particular conflict or ambiguity arises in your grammar.  AnaGram
+develops this window in conjunction with the \agwindow{Token
+Derivation} window which you may also select.
+
+Position the cursor bar on a
+\index{Completed rule}\index{Rule}\agterm{completed rule}, 
+that is, one with no marked token.  If you don't, AnaGram will scan
+down the table for the next completed rule.  The \agwindow{Rule
+Derivation} and the \agwindow{Token Derivation} show you two sequences
+of productions, both deriving from one original rule, which
+demonstrate how the conflict arises.  One sequence of productions, the
+\agwindow{Rule Derivation}, shows how the completed rule derives from the
+original rule.  The other sequence of productions, the \agwindow{Token
+Derivation}, shows how the reducing token derives from the original
+rule.  These derivations are discussed in greater detail in Chapter 7.
+
+
+\index{Set Elements}\index{Window}
+\paragraph{Set Elements.}
+The \agwindow{Set Elements} window can be accessed through the
+\agmenu{Auxiliary Windows} menu in a window that identifies a
+character set, a partition set, or a terminal token.  The
+\agwindow{Set Elements} window shows the numeric code and screen
+representation for each element of the set.  In the case of a terminal
+token, the character set displayed is the character set corresponding
+to the terminal token.  If you select \agwindow{Set Elements} in a
+window that identifies tokens, and the selected token is nonterminal,
+AnaGram will simply beep.
+
+\index{State Definition}\index{Window}
+\paragraph{State Definition.}
+The \agwindow{State Definition} window can be accessed through the
+\agmenu{Auxiliary Windows} menu in any window that identifies a state
+but does not provide its characteristic rules.  The format is the same
+as that in the \agwindow{State Definition Table}, except that it is
+limited to a single state.
+
+\index{State Definition Table}\index{Window}
+\paragraph{State Definition Table.}
+The \agwindow{State Definition Table} lists, for each parser state,
+all of the characteristic rules which define that state. The rules are
+displayed with the marked token in a distinctive font. 
+\index{Rule}\index{Completed rule}\index{Rule}If there is no
+marked token, the rule is complete.  Otherwise, the marked token found
+to continue the match.
+% XXX ``the marked token found to continue the match''?
+% (yes, this is how it is in the wordperfect version)
+% it also said ``with a the marked token'' but I fixed that.
+
+Each line contains the state number, the rule number, and finally the
+rule itself.  The state number field is blank if it is the same as the
+state number on the previous line.  The cursor bar is synched with the
+syntax file to show the grammar rule in context.
+
+\index{State Expansion}\index{Window}
+\paragraph{State Expansion.}
+The \agwindow{State Expansion} window may be accessed using the
+\agmenu{Auxiliary Windows} menu from any window that identifies a state.
+It shows the complete set of expansion rules for the state, consisting
+of the union of the set of characteristic rules and the sets of
+expansion rules for the token to the right of the mark in each
+characteristic rule.  The \agwindow{State Expansion} window shows all
+possible legal input to your parser in the given state.
+
+% XXX \index{Show statistics} ?
+\paragraph{Statistical Summary.}
+While your grammar is being analyzed, a \agwindow{Statistical Summary}
+window pops up to show the progress of the analysis.  Unless you have
+turned off the \agparam{show statistics} switch on the
+\agmenu{Options} menu, this window will remain on-screen for
+reference.  Among other things it shows you the number of rules and
+states in your grammar, and the number of conflicts and warnings, if
+any.
+
+Note that if your grammar is small and you have the \agparam{show
+statistics} switch disabled, the appearance of this window on your
+monitor may be exceedingly brief - you may just see a flash.
+% XXX or nothing at all.
+
+If the window is turned off or you have closed it, you can get it from
+the \agmenu{Browse} menu.
+
+\index{Symbol Table}\index{Window}
+\paragraph{Symbol Table.}
+The \agwindow{Symbol Table} lists all the symbols you used in your
+grammar.  Symbols may be used, of course, to identify tokens,
+definitions, or virtual productions or to provide alternative names
+for tokens.
+
+Each line in this table identifies a single symbol.  The first field
+is the token number, if any.  This is followed by the name.  If the
+name identifies a set expression or virtual production, it is followed
+by an equal sign and the expression or virtual production.
+
+\index{Token Derivation}\index{Window}
+\paragraph{Token Derivation.}
+See \agwindow{Rule Derivation}.
+
+\index{Token Table}\index{Window}
+\paragraph{Token Table.}
+The \agwindow{Token Table} lists all the tokens of your grammar.  The
+first field is the token number.  It is followed by a flag field which
+is ``zl'' if the token is a nonterminal token and is zero length.  If
+the token is nonterminal and not zero length, the flag field contains
+``nt''.  If the token is a terminal token, the field is blank.  The
+next field is blank unless the token has been declared
+\agparam{sticky} or has had a precedence level assigned.  If the token
+is sticky, this field will contain ``s''.  If a precedence level has
+been assigned, this field will contain the letter ``l'', ``r'', or
+``n'' to indicate associativity followed by the precedence level.
+Finally there is the data type of the semantic value of this token and
+the token representation.
+
+\index{Token Usage}\index{Window}
+\paragraph{Token Usage.}
+You may access a \agwindow{Token Usage} window from the
+\agmenu{Auxiliary Windows} menu of any window that identifies a
+token.  It shows all grammar rules which use the token.  In each rule
+the marked token, if any, will follow the selected token, so that
+further \agwindow{Auxiliary Windows} menu choices will refer to the
+marked token rather than the selected token.
+
+\index{Trace Coverage}\index{Window}\index{Coverage}
+\paragraph{Trace Coverage.}
+When you run a \agwindow{File Trace}, AnaGram automatically counts the
+number of times each rule in your grammar is reduced.  You may inspect
+these counts using the \agwindow{Trace Coverage} window.  Unless you
+have set the \agparam{rule coverage} switch, certain optimizations in
+AnaGram's tables will cause some null productions and rules consisting
+of a single token to not be counted.
+
+\index{Warnings}\index{Window}
+\paragraph{Warnings.}
+If while analyzing your syntax file, AnaGram finds something
+suspicious, it issues a warning, regardless of the severity of the
+problem.  The \agwindow{Warnings} window will pop up automatically
+when the analysis has been completed.  If the warning is for a
+\index{Errors}syntax error in your input file, you will have to fix
+it, because AnaGram cannot successfully interpret your syntax file.
+Otherwise, no matter how serious the warnings may be, AnaGram will
+create a parser if it is instructed to do so.  Thus if you decide the
+warnings are of no consequence, you may choose to ignore them.  Note
+that AnaGram will resolve \index{Conflicts}shift-reduce conflicts by
+choosing the shift action.  It will resolve
+\index{Conflicts}reduce-reduce conflicts by choosing the rule that
+occurred first in the grammar.
+
+If you have syntax errors, AnaGram will synchronize the cursor in the
+syntax file window with the cursor in the warning window so that as
+you move through the warning messages, the cursor in the syntax file
+window will move to the point of the error.