\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.