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