--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/intro.tex	Sat Dec 22 17:52:45 2007 -0500
@@ -0,0 +1,174 @@
+% This file was converted by WP2LaTeX version 2.99
+% (and modified a lot afterwards)
+
+%\baselineskip=2.00ex
+%
+%\headtext{\evenpages}{
+%\thepage AnaGram User's Guide
+%}
+%\foottext{\allpages}{
+%\strut\hfill \today{}
+%}
+%\headtext{\oddpages}{
+%Chapter 1\hfill Introduction\thepage 
+%}
+%\vspace{2.55cm}%
+%\begin{flushright}
+%
+%\section{{    Chapter 1
+%Introduction to AnaGram}}
+%\end{flushright}
+
+\chapter{Introduction to AnaGram}
+
+AnaGram is a software development tool which brings the power of
+syntax directed parsing to the C or C++ programmer.  AnaGram provides
+a rule-based, non-procedural system for dealing with input to computer
+programs.
+
+AnaGram is a completely new LALR parser generator with a powerful
+notation for representing context free grammars.  A flexible,
+interactive environment combined with powerful debugging capabilities
+and language extensions make it easy to incorporate syntax directed
+parsing in your programs.  AnaGram makes it possible for you to reap
+the benefits of syntax directed parsing on all of your projects, big
+and small.
+
+Syntax directed parsing has long been recognized as the most powerful
+technique available for interpreting program input.  Up to now, the
+tools available to the software developer to support this technique
+have been primitive and hard to use, suitable mainly for compilers and
+other large projects.  AnaGram was specifically designed to make
+syntax directed parsing accessible to the software developer for
+everyday use.
+
+Few portions of a program are more prone to errors than the logic that
+deciphers the input to the program.  To interpret its input a program
+usually needs many flags and switches, many tests, and a lot of
+conditional code.  Of necessity such a program has many paths and many
+opportunities to go awry.  Such code is hard to write, hard to
+document, hard to debug and hard to maintain.
+
+With AnaGram, you can completely separate the analysis of input from
+the processing of data.  Instead of writing a detailed procedure for
+interpreting input, you write a {\it description} of that input using
+an adaptation of 
+% noindex
+Backus-Naur Form, or BNF.
+AnaGram builds for you,
+based on your description, a procedure to interpret your input.  All
+those tests, all that conditional code, all those flags and switches
+vanish.  In a convenient way you can attach, to the procedure, code to
+process the data once it is identified in the input stream.  Your
+input processing now takes on the aspect of a rule-based,
+non-procedural system.
+
+There are many benefits to this approach.  Your program is easier to
+understand.  It is easier to debug.  It is easier to extend and
+maintain.  A large project can be more easily divided up among the
+members of your team.  The description, or grammar, of your input can
+serve as solid and reliable documentation.  You will also find that it
+becomes much easier to re-use code on other projects, because the data
+processing is cleanly separated from the parsing, or input analysis.
+
+These benefits are now available because AnaGram, in addition to
+implementing the basic algorithms of an LALR parser generator,
+provides powerful new features that make syntax directed parsing a
+practical reality.  Here is a summary of some of the more important
+features of AnaGram:
+
+\paragraph{Interactive File Trace.}
+An online 
+% noindex
+\agwindow{File Trace} function lets you run test files through your
+grammar interactively.  You can see how your parser will interpret
+them.  You can see the contents of the parse stack.  You can see the
+grammar rules that are partially matched at any stage in the parse.
+You can back up the parse to any point and try again.  You can go
+through a test file in single step mode, one character at a time, or
+simply parse the whole file to see if it has any errors.  While
+interpreting your grammar and parsing your file, AnaGram will count
+the number of times each grammar rule is matched and give you a report
+so you can assess the thoroughness of your testing.
+
+\paragraph{Grammar Trace.}
+The
+% noindex
+\agwindow{Grammar Trace} is another feature which allows you to
+inspect the workings of your parser interactively.  It is particularly
+suited for dealing with ``what if?'' questions.  You can work through
+a parse at whatever level of detail is necessary to see how an error
+arises, to see the nature of an ambiguity, or simply to gain
+confidence in the way the parser works.  In case of certain types of
+errors, AnaGram will provide pre-built grammar traces to illustrate
+the problem.
+
+\paragraph{Other Debugging Tools.}
+AnaGram provides a number of debugging tools that can help you get
+your program up and running on schedule.  In particular, AnaGram has
+powerful tools for identifying ambiguities in your grammar.  AnaGram
+also has coverage analysis facilities to help you ascertain the
+effectiveness of your test suites.
+
+When AnaGram analyzes a grammar, it creates numerous tables describing
+various aspects of the grammar.  To facilitate inspection of these
+tables, AnaGram has an interactive interface to enable you to find
+quickly any problems in your grammar.  An extensive, on-line help
+system provides quick online answers to the questions you have about
+AnaGram.
+
+\paragraph{No Lexical Scanner Required.}
+\index{Lexical scanner}
+When you use AnaGram, you seldom have to use a ``lexical scanner'', or
+input processor, written in still another programming language, to
+``tokenize'' character-based input for your parser.  Instead, you can
+specify {\it all} the details of the input stream directly in your
+grammar in a natural way.  If those details need to be changed, you
+can make all the changes in one place and rebuild your parser without
+having to deal with a cumbersome lexical scanner interface.  AnaGram
+accomplishes this by providing a notation that allows you to specify
+keywords and character sets simply and intuitively.  AnaGram also
+provides options for selectively ignoring white space or other
+uninteresting characters in your input.
+
+On the other hand, if you already have a lexical scanner, or some
+other data source, you can interface it cleanly and simply to a parser
+AnaGram generates.  If the nature of your problem requires a lexical
+scanner, or multi-stage parsing, you can use AnaGram for each level of
+parsing.
+
+\paragraph{Flexible Interfacing.}
+AnaGram provides numerous ways for you to interface your parser to the
+rest of your program.  Since you can even configure a parser to work
+in an event driven mode, you can use AnaGram very effectively to deal
+with the new programming styles required by modern window based
+operating systems.
+
+AnaGram provides new notation for linking data to your processing
+routines.  Symbolic hooks tie syntactic constructs directly to your C
+or C++ code.  The processing routines are easier to write and to
+modify.  You can also modify your grammar without having to alter your
+data processing routines.
+
+\paragraph{Virtual Productions.}
+AnaGram provides a powerful, intuitive shorthand notation to help you
+to describe many commonly occurring syntactic forms, such as optional
+elements, lists, and simple sets of options.
+
+\paragraph{Semantic Control over Syntactic Analysis.}
+Extensions to the basic algorithms for developing LALR parsers allow
+you to exert semantic control over syntactic processing by using a new
+feature called ``semantically determined productions''.
+
+\paragraph{Precise Control over White Space.}
+Convenient attribute statements allow you to skip white space and
+comments where they are meaningless, but recognize them where it
+matters.
+
+\paragraph{Easy Configuration.}
+An extensive set of configuration switches and parameters allow you to
+configure both AnaGram and the parsers you build to your precise
+requirements.  Wherever AnaGram provides options, it also provides
+sensible defaults, so that you can ignore most switches and parameters
+until you need the capability they control.
+