--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/ra.tex	Sat Dec 22 17:52:45 2007 -0500
@@ -0,0 +1,415 @@
+\chapter{Running AnaGram}
+
+
+\section{Overview}
+
+AnaGram's main window is a small
+\index{\agwindow{Control Panel}}\agwindow{Control Panel}
+with menus, a toolbar, a status indicator, and a simple search
+facility.  Its default position is at the upper right of your screen.
+AnaGram's two basic commands,
+\index{Analyze Grammar}\agmenu{Analyze Grammar}
+and
+\index{Build Parser}\agmenu{Build Parser},
+are available from the \agmenu{Action} menu of the \agwindow{Control
+Panel}.
+
+% XXX remove the stuff about time; nowadays it's all instantaneous
+The commands take as input a syntax file containing the specifications
+of your grammar.  \agmenu{Build Parser} creates a parser file, in C or
+C++, and a header file.  \agmenu{Analyze Grammar} does not write any
+\index{Output files}\index{File}output files, and therefore takes a
+little less time than \agmenu{Build Parser} to run.  Normally you
+would use \agmenu{Build Parser} when you are ready to start compiling
+and testing your parser.  You would use \agmenu{Analyze Grammar} while
+you are working on the grammar itself.
+
+% XXX s/build/create/
+Both of these commands cause AnaGram to build a number of tables
+describing your grammar.  These tables, accessible from the
+\agmenu{Browse} menu, will interest you mainly when you are debugging
+your grammar.  These tables and their use are described in Chapters 6
+and 7.  An alphabetic listing of the tables with summaries of their
+content may be found in Appendix C.
+
+The primary purpose of AnaGram's user interface is to enable you to
+inspect the grammar tables, and to use the \agwindow{Grammar Trace}
+and \agwindow{File Trace} facilities to study, at any level of detail
+you wish, how your parser analyzes any sequence of input characters or
+tokens.
+
+AnaGram is documented with an extensive, hypertext \agwindow{Online
+Help} system in addition to this User's Guide.  Supplementary
+documentation in browser-readable format can be found in the
+\agfile{html} directory distributed with AnaGram.
+
+
+\section{Executables}
+\index{Executables}
+
+% XXX s/make files/makefiles/
+% (better do a global search and replace)
+
+\index{Make files}\index{\agfile{ag.exe}}\index{\agfile{agcl.exe}}
+AnaGram has two executables: one interactive, \agfile{ag.exe}, and
+one, \agfile{agcl.exe}, for use in make files.
+
+\index{Command line}
+If you provide \agfile{ag.exe} with a syntax file name on the command
+line, AnaGram will load the file and do either \agmenu{Analyze
+Grammar} or \agmenu{Build Parser}, depending on the setting of the
+\index{\agoption{Autobuild}}\agoption{Autobuild} option.
+
+The command line version, \agfile{agcl.exe}, builds a parser for the
+syntax file specified on the command line.  Warning and error messages
+from \agfile{agcl.exe} are directed to \agcode{stdout}.
+
+\index{File extension}\index{syn}\index{.syn}
+The default extension for syntax files appearing on the command line
+is \agfile{.syn}.
+
+
+\section{Input Files}
+\index{Input Files}\index{Files}\index{File}
+
+Input files for AnaGram are called syntax files and usually have the
+\index{File extension}\index{syn}\index{.syn}
+extension \agfile{.syn}.
+\index{Syntax file}\index{File}
+Syntax files are written in a variant
+of
+\index{Backus-Naur form}Backus-Naur form,
+and may include reduction procedures written in C or C++ as well as
+other embedded C or C++ code.  The general theory of syntax files is
+given in Chapter 4.  The rules for writing syntax files are given in
+Chapter 8.
+
+When you run AnaGram and analyze a grammar, the syntax file you have
+chosen will appear in the \agmenu{Browse} menu under the heading
+\agmenu{Syntax File} followed by the file name.  It will also appear
+in a window on your screen unless you have turned the
+\index{Show Syntax}\agoption{Show Syntax} option off.
+
+
+\section{Output Files}
+\index{Output Files}\index{Files}\index{File}
+
+% XXX s/parser file/source file/
+When you choose the \agmenu{Build Parser} command, AnaGram builds two
+output files: a header file and a parser file.  Normally these files
+have the same name as your syntax file and the \index{File
+extension}extensions \agfile{.h} and \agfile{.c}, respectively.  You
+may change the names or the extensions by use of the
+\index{File name}\index{Header file name}\agparam{header file name}
+and
+\index{File name}\index{Parser file name}\agparam{parser file name}
+\index{Configuration parameters}configuration parameters
+(see Appendix A).  If you are using C++, you will probably wish to set
+% XXX s/in your configuration file/accordingly/
+the \agparam{parser file name} parameter in your configuration file.
+Include the following line in your configuration file or section:
+
+% This is really part of the preceding paragraph and latex won't
+% space it accordingly even if you don't have any line breaks in
+% between. This looks unsightly at first glance but it makes things
+% clearer when actually reading.
+\vskip -1.25ex
+
+% This was 1 inch, but wp2latex must have made that up out of thin air
+\begin{indentingcode}{0.4in}
+parser file name = "\#.cpp"
+\end{indentingcode}
+
+The \index{Header file}\index{File}header file contains typedef
+statements and macro definitions which are needed by the parser and
+which you may need to use in other modules to interface your parser to
+the rest of your program.
+
+The \index{Parser file}\index{File}parser file contains the reduction
+procedures and embedded C or C++ code that AnaGram finds in your
+syntax file, a number of tables which summarize your grammar, and a
+parsing engine customized to your requirements.  The
+\index{Parsing engine}parsing engine
+is written in C.  Care has been taken to assure that it can be
+compiled by almost any C/C++ compiler.  The content of the header file
+and the parser file is described in Chapter 9.
+
+
+\section{AnaGram's Help}
+\index{Help}\index{Online help}
+
+There are three main ways to access AnaGram's \agwindow{Online Help}:
+
+\begin{itemize}
+\item Press F1 for context-sensitive help from most windows and menu
+items.
+\item Similarly, use the \agwindow{Help Cursor} on the
+\agwindow{Control Panel} toolbar (described below) from most windows
+and menu items.
+\item From the \agmenu{Help} menu on the \agwindow{Control Panel}, you
+can bring up a complete list of help topics and choose a topic.
+\end{itemize}
+
+You can also get fly-over help for the toolbar buttons on the
+\agwindow{Control Panel}.  \agwindow{File} and \agwindow{Grammar
+Traces} have a \agmenu{Help} button.
+
+AnaGram's \agwindow{Help} windows remain on-screen until you dismiss
+them.  This means you can refer to several topics at once.  They have
+hypertext links to other Help topics.  Also, right-clicking the mouse
+on a \agwindow{Help} window or pressing F1 will pop up an Auxiliary
+Windows menu of all linked topics in the window.  ``Using Help'' is
+always available from this popup menu.
+
+% XXX s/that,/that/
+Note that, for the \agwindow{Warnings}, \agwindow{Configuration
+Parameters} and \agwindow{Help Topics} windows, F1 will give you help
+for the item on the highlighted line, whereas the \agwindow{Help
+Cursor} allows you to select any line by clicking on it.
+
+AnaGram also has browser-readable documentation of examples, a
+glossary, brief descriptions of the \agwindow{File} and
+\agwindow{Grammar Traces}, and some further topics in the
+\agfile{html} directory distributed with AnaGram.
+
+
+\section{Control Panel Components}
+\index{Control Panel}
+
+\index{Action Menu}\index{Menu}\subsection{Action Menu}
+In addition to the basic \agmenu{Analyze Grammar} and \agmenu{Build
+Parser} commands, the \agmenu{Action} menu provides some variations on
+these commands for your convenience:
+
+\begin{itemize}
+
+\item If a grammar has already been analyzed, but not yet built, there
+will also be an extra \agmenu{Build} command with the name of your
+syntax file.
+
+\item The \agmenu{Reanalyze} and \agmenu{Rebuild} commands are
+initially greyed out.  They become available if the current syntax
+file is changed externally by another program.
+
+\item At the bottom of the menu is a list of up to six recently used
+syntax files. Clicking on one of these gives the same effect as
+\agmenu{Analyze Grammar}, or if the
+\index{\agoption{Autobuild}}\agoption{Autobuild} option
+is on, the same effect as \agmenu{Build Parser}.
+
+\end{itemize}
+
+Before executing an \agmenu{Analyze Grammar} or \agmenu{Build Parser}
+command, AnaGram closes all windows related to the current syntax
+file, if any, and resets
+\index{Configuration parameters}configuration parameters to their initial
+values, as determined by the built in defaults and the configuration
+files read at program initialization.
+
+The \agmenu{Action} menu also lets you select a \agmenu{File Trace} or
+\agmenu{Grammar Trace}, and if the
+\index{error trace}\agparam{error trace}
+\index{Configuration parameters}configuration switch is
+enabled, an \agmenu{Error Trace}.  The traces are covered in Chapter
+5.
+
+
+\subsection{Browse Menu}
+\index{Menu}\index{Browse Menu}
+
+Most of the \agmenu{Browse} menu entries are tables describing your
+grammar which become available as soon as you analyze it.  The tables
+are described in Chapters 6 and 7.  The tables themselves often have
+associated tables available via an
+\index{Auxiliary Windows}\agmenu{Auxiliary Windows}
+menu which pops up when you right-click on a highlighted
+line.
+
+A window showing your syntax file is also available from this window.
+Do not overlook the 
+% noindex (XXX?)
+\agmenu{Configuration Parameters}
+entry.  AnaGram has a great many parameters available so you can make
+AnaGram behave in a variety of ways and produce parsers with the
+features you want.  Configuration parameters are documented in
+Appendix A.
+
+
+\subsection{Options Menu}
+\index{Options Menu}\index{Menu}
+
+Items you set from the \agmenu{Options} menu will be saved in the
+Windows Registry so they can be restored every time you start AnaGram.
+
+\paragraph{Fonts and Colors.}
+\index{Fonts}\index{Colors}
+You can set AnaGram's fonts and colors to suit your own tastes.  Make
+sure that the \agmenu{Marked Tokens} font is very distinctive so these
+tokens show up clearly even if they are only one or two characters
+long.  Try an underlined font for them if you like.  Notice also that
+the \agwindow{Test File} pane requires three different sets of text
+and background colors.  You should make sure that the backgrounds, at
+least, can be easily distinguished from each other so the trace
+information can be properly displayed.  You also want to take care
+that an active pane in a \agwindow{File} or \agwindow{Grammar Trace}
+can be distinguished from inactive panes.
+
+Color changes pertain only to the client areas of AnaGram windows.
+The remaining parts of your windows will have the customary colors you
+have chosen for your system.
+
+\paragraph{Autobuild.}
+\index{Autobuild}
+When \agoption{Autobuild} is checked, selecting a file from the list
+of most recently used files on the \agmenu{Action} menu invokes the
+\agmenu{Build Parser} command.  Otherwise, the \agmenu{Analyze
+Grammar} command is invoked.
+
+\index{Show Statistics}\index{Statistics}
+\paragraph{Show Statistics.}
+If this entry is checked, AnaGram will leave the \agwindow{Statistical
+Summary} window on the screen after it has analyzed your grammar.  If
+the entry is not checked or you have closed the window, you can select
+it from the \agmenu{Browse} menu.
+
+\paragraph{Show Syntax.}
+\index{Show Syntax}\index{Syntax}
+If this entry is checked, AnaGram will display the syntax file when it
+has analyzed your grammar.  If this entry is not checked or you have
+closed the syntax file window, you can select the window from the
+\agmenu{Browse} menu.
+
+\paragraph{Stay On Top.}
+\index{Stay On Top}
+This entry allows you to specify whether the \agwindow{Control Panel}
+stays on top of other AnaGram windows.
+
+
+\subsection{Windows Menu}
+\index{Windows Menu}\index{Menu}
+
+In addition to the list of open (including hidden) windows, this menu
+has the customary \agmenu{Cascade}, \agmenu{Close}, \agmenu{Hide} and
+\agmenu{Restore Windows} commands.  A \agmenu{Copy} feature lets you
+copy the currently active table or \agwindow{Help} topic to the
+\index{Copy}\index{Clipboard}clipboard.
+
+
+\subsection{Help Menu}
+\index{Help Menu}\index{Menu}
+
+The \agmenu{Help} menu has \agmenu{Getting Started}, \agmenu{Using
+Help}, and \agmenu{What's New} entries, all of which you will probably
+want to take a look at when you begin using AnaGram.  In the long
+term, you will probably find
+\index{Help}\index{Help Topics}\agmenu{Help Topics} to be the most
+useful item in this menu.  It provides a complete list of
+\agwindow{Help Topics} titles.  You can bring up the window for a
+highlighted topic by double-clicking with the left mouse button,
+pressing F1, or using the \agwindow{Help Cursor}.  You may want to use
+the \agmenu{Search} facility in this window.
+
+
+\subsection{Control Panel Toolbar}
+\index{Control Panel}\index{Toolbar}
+
+The first four toolbar buttons provide quick access to the
+\agmenu{Analyze Grammar}, \agmenu{Build Parser}, \agmenu{File Trace}
+and \agmenu{Grammar Trace} commands.  Two more buttons bring up the
+\agwindow{Warnings} and \agwindow{Conflicts} windows if they have any
+entries.
+
+The last button, with a question mark, enables a \agwindow{Help
+Cursor}, which is convenient for getting help on warnings,
+\agmenu{Browse} tables, menu items, and so on.  Once enabled, the
+\agwindow{Help Cursor} can be dragged with the mouse.  A further mouse
+click will provide help for the item under the cursor.  Note that
+AnaGram also has F1 help which you may find simpler and faster than
+the \agwindow{Help Cursor}.
+
+
+\subsection{Status Indicator}
+\index{Status Indicator}\index{Indicator}
+
+The status indicator at the right of the \agwindow{Control Panel} has
+six possible states: Ready, Loaded, Error, Parsed, Analyzed, and
+Built.  ``Ready'' appears only when no grammar has been selected.
+``Loaded'' and ``Parsed'' should be transitory.  If ``Error'' appears,
+one or more syntax errors have been found in your grammar and AnaGram
+cannot continue its analysis.  Check the Warnings window to determine
+the nature of the problem.  ``Analyzed'' means that analysis of the
+grammar has been completed.  ``Built'' means the analysis has been
+completed and also output files have been written.
+
+
+\subsection{Search}
+\index{Search}
+
+\index{Searching for text}AnaGram has a simple search facility to let
+you search for text strings in AnaGram windows.  A text entry field on
+the \agwindow{Control Panel} is provided for you to enter text.
+Left-clicking on the neighboring \agmenu{Find Next} and \agmenu{Find
+Previous} buttons lets you search either forward or backward for a
+line in the active window which contains at least one instance of the
+text.
+
+Note that the search begins at the next line after the highlighted
+line for forward search; at the line preceding the highlighted line
+for backward search.
+\index{Case sensitivity}Searches are not case sensitive.
+
+
+\section{Statistical Summary}
+\index{Statistical Summary}\index{Summary}
+
+While your grammar is being analyzed, a \agwindow{Statistical Summary}
+window pops up to show you the progress of the analysis.  Unless you
+have turned off \agmenu{Show Statistics} on the \agmenu{Options} menu,
+this window will remain on-screen for your 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 \agmenu{Show
+Statistics} turned off, the appearance of this window on your monitor
+may be exceedingly brief -- you may just see a flash.
+
+If this window is turned off or you have closed it, you can select it
+from the \agmenu{Browse} menu.
+
+
+\section{Auxiliary Windows Popup Menu}
+\index{Auxiliary Windows}\index{Popup Menu}\index{Menu}
+
+For many tables you can get more detailed information keyed to the
+highlighted item by right clicking the mouse to pop up the
+\agmenu{Auxiliary Windows} menu.
+
+Some auxiliary windows are keyed simply to a state number, a token
+number, a rule number, a character set number, or a partition set
+number identified by the highlighted item.  Others are keyed to some
+combination of these numbers.  If the cursor bar is highlighting a
+marked rule, the \index{Marked Token}\index{Token}marked token is the
+token to which the auxiliary window is keyed.  The key, whether it is
+a state number, token number, or other identifier, is always displayed
+on the title bar of the window.
+
+Help windows also have popup \agmenu{Auxiliary Windows} menus.  For a
+Help window, the popup menu shows all linked topics in the window.
+
+
+\section{Keyboard Control}
+\index{Keyboard}
+
+AnaGram can be controlled entirely from the keyboard.  In the
+\agwindow{Control Panel}, you can tab to any button and press Enter to
+select it.  In addition to the conventional Windows keyboard
+functions, the following keys have been implemented:
+
+% XXX this doesn't look so great
+\index{Escape}\index{F8}\index{F10}\index{F10}
+\begin{tabular}{rll}
+$\bullet$&Escape&Closes any AnaGram window except the Control Panel.\\
+$\bullet$&F8&Toggles between an active AnaGram window and the Control Panel.\\
+$\bullet$&F10&Accesses the Control Panel menu from any AnaGram Window.\\
+$\bullet$&Shift F10&Pops up the Auxiliary Windows menu.\\
+\end{tabular}