--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/gs.tex	Sat Dec 22 17:52:45 2007 -0500
@@ -0,0 +1,310 @@
+\chapter{Getting Started}
+
+
+\section{Hardware and Software Requirements}
+\index{Requirements}
+\index{Hardware requirements}
+\index{Software requirements}
+
+AnaGram V2.0 will run on any Windows 95 or Windows NT system.  The
+installation requires approximately five megabytes of hard disk space.
+
+The parsers AnaGram generates are either C or C++ program modules, and
+can be compiled and run using almost any C or C++ compiler, in any
+operating system environment.  If your compiler does not support
+\agcode{near} and \agcode{far} declarations, or does not support ANSI
+function declarations, see the descriptions of the
+\index{Near functions}\agparam{near functions}
+and
+\index{Old style}\agparam{old style}
+\index{Configuration switches}configuration switches in Appendix A.
+
+
+\section{Installation}
+\index{Installation}
+
+For details on installation, please see the \agfile{readme.txt} file
+on the AnaGram installation disk.
+
+The AnaGram installation disk contains the AnaGram executables,
+several support files, an \agfile{html} documentation directory, an
+\index{\agfile{examples}}\agfile{examples} directory, and a
+\agfile{classlib} directory.  The \agfile{examples} directory
+contains a number of subdirectories, each of which contains the
+necessary syntax files and supporting C or C++ code to build and run a
+different example of the use of AnaGram.
+
+The HTML documentation directory contains introductory material which can be
+read on line, as well as documentation for the examples. 
+
+The \index{\agfile{classlib}}\agfile{classlib} directory contains
+class definitions which support the C++ examples provided.  The
+\agfile{classlib} directory has three subdirectories, which contain
+header files, source files, and documentation files, respectively.
+
+% XXX this should be pruned. nobody cares about a minimal installation
+% when drive space is $0.50 per gigabyte.
+%
+% also, I suspect the ``PATH command'' bit needs updating somewhere,
+% but I'm not sure what right now. (and I'm not doing updates on this
+% pass through the thing.)
+%
+% and, s/make file/makefile/. or say ``with \agfile{make}''.
+%
+A minimal AnaGram installation requires files: \agfile{ag.exe},
+\agfile{ag1.dll}, \agfile{AnaGram.cgb}, and \agfile{AnaGram.hlp}.
+They must all be in the same directory.
+\index{PATH command}
+If any of these files is missing, AnaGram cannot run.  If you wish to
+use the command line version of AnaGram in make files, you also need
+\agfile{agcl.exe}.
+
+
+\section{Configuration}
+\index{Configuration}
+
+AnaGram has a large number of configuration parameters which control
+various aspects of its operation.  All configuration parameters have
+default values which are normally acceptable to most beginning users.
+Configuration parameters can be set either in configuration files,
+named
+\index{Configuration file}\index{File}\index{\agfile{AnaGram.cfg}}
+\agfile{AnaGram.cfg}, or in your syntax files.  When AnaGram
+initializes itself, it checks the AnaGram
+\index{Directory}\index{AnaGram}directory, the directory that contains
+the AnaGram executable file.  If it finds \agfile{AnaGram.cfg}, it
+reads it and sets the
+\index{Configuration parameters}configuration parameters accordingly.
+It then checks for \agfile{AnaGram.cfg} in your working directory and,
+if it finds it, reads it in turn, overriding the setting for any
+parameter which had been set previously.  Configuration parameter
+settings in a syntax file, of course, override any values set in a
+configuration file.
+
+The \index{File}configuration files are simple ASCII files so they can
+be created or modified with any program editor.  Neither configuration
+file is necessary.  A complete listing of configuration parameters is
+given in Appendix A.  Specific configuration parameters are discussed
+in this manual where appropriate.
+
+\section{Familiarizing Yourself with AnaGram}
+
+AnaGram has extensive online help, so you should be able to get
+started without reading much of this manual.  Once you have obtained
+an initial familiarity with AnaGram, you should take another look at
+the manual since there are a number of features that you may otherwise
+overlook.
+
+To help get you started, a number of examples have been provided in
+the \index{\agfile{examples}}\agfile{examples} directory of the
+AnaGram distribution disk.  These examples range from very elementary
+to quite complex.  The elementary examples are intended to give you a
+quick understanding of how to use AnaGram.  The complex examples are
+intended to demonstrate the capabilities of AnaGram.  All of the
+examples are complete working programs.  Many example grammars are
+provided with sample input files so you can use AnaGram's \agmenu{File
+Trace} command to see how the parsing is controlled by the grammar.
+The \agwindow{File Trace} facility is described in Chapter 5.
+
+% For some reason I don't understand this paragraph doesn't fold
+% correctly. (It looks ugly with the explicit break, but it's worse
+% hanging out into the margin, which is what happens otherwise. XXX)
+The examples are documented in the HTML documentation directory.
+Point your web browser at\\
+\agfile{html/start.html}.
+
+The best way to learn AnaGram is by using it.  Start by looking at the
+examples provided in the \agfile{examples} directory.  Once you have
+looked over a file to get an idea of what it is about, you should run
+\agmenu{File Trace} to see how it works.  You might then want to build
+a parser for one of the examples, compile it, and try running it.  You
+can also try modifying the examples before starting to write grammars
+of your own.
+
+To investigate a syntax file select the \agmenu{Analyze Grammar}
+command from the \agmenu{Action} menu.  After this command has run you
+can run the \agwindow{File Trace} or \agwindow{Grammar Trace} to see
+how the grammar works.  You may also look at any of a number of
+windows listed in the \agmenu{Browse} menu to investigate various
+aspects of the grammar.
+
+To build a parser file that you can compile with your C or C++
+compiler, select the \agmenu{Build Parser} command.  If you have
+already analyzed a grammar, the \agmenu{Build Parser} command will
+simply build a parser for the grammar you have already analyzed.  If
+you have already built a parser for the grammar you presently have
+loaded, the \agmenu{Build Parser} command will offer you the option of
+loading a new file.
+
+When AnaGram analyzes a grammar, it creates a number of tables.
+Windows displaying these tables can be opened from the \agmenu{Browse}
+menu.  AnaGram's windows are described in Chapter 3, Running AnaGram.
+
+\section{Guide to this Manual}
+
+Chapter 3, \textit{Running AnaGram}, describes AnaGram's on-line
+features and how to use them.
+
+Chapter 4, \textit{Introduction to Syntax Directed Parsing}, provides
+a general introduction to parsing and an introduction to AnaGram
+syntax files.  In particular, it introduces important terminology used
+throughout the manual.
+
+Chapter 5, \textit{Exploring Your Grammar I: Trace Functions},
+explains the usage of the \agwindow{File Trace} and the
+\agwindow{Grammar Trace} in exploring and understanding your grammar.
+
+Chapter 6, \textit{Exploring Your Grammar II: Grammar Tables},
+describes the use of the principal tables AnaGram provides to
+summarize your grammar.
+
+Chapter 7, \textit{Exploring Your Grammar III: Diagnostic Windows},
+describes the use of the tables AnaGram provides to help you
+investigate error conditions in your grammar.
+
+Chapter 8, \textit{Syntax Files}, describes the rules for writing
+syntax files.  This chapter is meant to be used largely for reference.
+
+Chapter 9, \textit{Programming with AnaGram}, describes how you
+interface a parser to the rest of your program.  In particular, it
+describes your options for naming and calling your parser, providing
+input, and dealing with errors.
+
+Appendix A, \textit{Configuration Parameters}, explains how to use
+configuration files and configuration parameters.  It also lists each
+configuration parameter and explains the options available.
+
+Appendix B, \textit{Warning Messages}, explains the various warnings
+AnaGram creates when it finds errors or other anomalies in your syntax
+file.
+
+Appendix C, \textit{Alphabetic Listing of Windows}, provides a quick
+overview of the various windows AnaGram uses to display the results of
+analyzing a grammar.
+
+Appendix D, \textit{Syntactic Building Blocks}, provides examples of
+AnaGram syntax for the most common elements of any grammar: end of
+file, end of line, comments, numbers, names, quoted strings, character
+constants and simple expressions.
+
+Appendix E, \textit{Parser Control Block}, provides a summary of
+fields in the parser control block which you may need to inspect or
+use from time to time.
+
+Appendix F, \textit{Glossary}, explains some of the terminology of
+syntax directed parsing.
+
+\section{Examples}
+
+The \index{\agfile{examples}}\agfile{examples} directory contains a
+number of examples of programs written using AnaGram.  Each example is
+in a subdirectory by itself.  Where necessary, each directory also
+contains supporting modules in C or C++, depending on the example, to
+build a complete working program.  The C++ examples also use
+supporting modules found in
+\index{\agfile{classlib}}\agfile{classlib}.  Documentation for the
+examples may be found in the HTML directory.  Begin with
+\agfile{html/start.html}.
+
+If you are not already familiar with AnaGram you should take a look at
+the examples.  The purpose of the examples is twofold: to provide a
+quick introduction to AnaGram, and to suggest methods of using AnaGram
+to solve problems.  The examples are provided as is, with no
+guarantees of any sort.  You may freely copy portions of these
+examples for your own use.  However, in doing so, you assume the
+responsibility of verifying their performance and reliability.
+
+The following list gives a brief description of some of the example
+programs to be found in the \index{\agfile{examples}}\agfile{examples}
+directory.
+
+\paragraph{Hello, World!}
+The \agfile{hw} directory contains two versions of the traditional ``Hello,
+world!'' One version, \agfile{hw1.syn}, uses C.  The other,
+\agfile{hw2.syn}, uses C++.  These programs are utterly trivial, but
+useful for getting started with the mechanics of using AnaGram.  They
+illustrate AnaGram's default settings using an absolutely minimal
+grammar.
+
+\paragraph{Fahrenheit-Celsius Conversion.}
+The \agfile{fc} directory contains a graded sequence of very simple
+examples.  Each example is a complete working program.  These programs
+introduce a number of the most important features of AnaGram.  The
+documentation is designed to be a tutorial, to lead you into using
+AnaGram by simple steps.  It includes an example of how to find and
+fix the conflicts in an ambiguous grammar.  All of these examples use
+C.
+
+\paragraph{Roman Numeral Calculator.}
+\agfile{rcalc.syn} is a simple four function desk calculator
+that takes its input and displays its output using Roman numerals.
+\agfile{rcalc} uses C.
+
+\paragraph{Four Function Calculator.}
+\agfile{ffcalc} is intended to provide an example of how
+to parse simple expressions.  A companion program, \agfile{ffcalcx},
+demonstrates the use of precedence statements to resolve a
+deliberately ambiguous grammar.
+
+\paragraph{DOS Script Language.}
+\agfile{dsl.syn} is meant more as an illustration of what can be
+done with AnaGram than as an ideal design of a script language.  In
+particular, \agfile{dsl} is largely composed of grammar elements
+copied from other programs.  \agfile{dsl} uses C++.
+
+%
+%\paragraph{Spreadsheet Formula Evaluators.}
+%This is a collection of grammars which you
+%can use to replace the formula evaluation in the TCALC spreadsheet
+%distributed as an example with Borland C and C++ compilers.  Modify these
+%grammars to make a spreadsheet that calculates according to your own
+%specifications. 
+%
+%\paragraph{Simple Spreadsheet.}
+%This is a complete working spreadsheet program, modeled
+%after TCALC.  It uses two grammars, one for keyboard control and one for
+%evaluating expressions. 
+%
+%
+%\paragraph{Pascal Grammar.}
+%This is a complete grammar for Turbo Pascal, version 5.  It
+%demonstrates the use of semantically determined productions to distinguish
+%various categories of identifiers.  Add reduction procedures to make your
+%own compiler. 
+%
+%
+%
+%\paragraph{Data Base Query example.}
+%The purpose of this grammar is simply to
+%demonstrate some of the techniques you might use to create a very nearly
+%natural language query system.  DBQ illustrates methods for parsing a number
+%of unconventional (to programmers, anyway) syntaxes.  Think of it as a
+%source of ideas and techniques rather than as a specific query language. 
+%
+%For example, it shows how to parse inequalities as represented by
+%mathematicians:
+%$0 < x < y < 1$
+%It also shows how to parse inequalities as expressed in ordinary speech:
+%``Sales over \$500 and under \$2,000 during March''.
+%
+%
+
+\paragraph{Macro Preprocessor with C Grammars.}
+\agfile{mpp} is the biggest and most complex example provided.  This
+example provides a complete macro preprocessor with your choice of two
+C grammars.  By adding reduction procedures to one of the C grammars
+you can build yourself a syntax checker, a compiler, an analysis tool
+or whatever you choose.
+
+The preprocessor uses four distinct AnaGram grammars and illustrates
+many of the ways you can interface parsers to other modules.  For an
+overview of the macro preprocessor and how it works, read
+\agfile{html/macproc.html}.  Each grammar and each support module
+is separately described in its own documentation file.
+
+%
+% XXX perhaps note that this cpp is not standards-compliant.
+%
+% actually this whole section should probably be moved to an appendix,
+% especially as it's likely to grow.
+%