Moved LLgen documentation from the main ACK documentation directory into LLgen's own documentation directory.

util/LLgen/doc/LLgen.1

@@ -0,0 +1,139 @@
+.\" $Id$
+.TH LLGEN 1 "$Revision$"
+.ad
+.SH NAME
+LLgen, an extended LL(1) parser generator
+.SH SYNOPSIS
+LLgen [ \-vxwans ] [ \-j[\fInum\fP] ] [ \-l\fInum\fP ] [ \-h\fInum\fP ] file ...
+.SH DESCRIPTION
+\fILLgen\fP
+converts a context-free grammar into a set of
+functions which form a recursive descent parser with no backtrack.
+The grammar may be ambiguous;
+ambiguities can be broken by user specifications.
+.PP
+\fILLgen\fP
+reads each
+\fIfile\fP
+in sequence.
+Together, these files must constitute a context-free grammar.
+For each file,
+\fILLgen\fP
+generates an output file, which must be compiled by the
+C-compiler.
+In addition, it generates the files
+\fILpars.c\fP
+and
+\fILpars.h.\fP
+\fILpars.h\fP
+contains the
+\fIdefine\fP
+statements that associate the
+\fILLgen\fP-assigned `token-codes' with user declared `token-names'.
+This allows other source files, for instance the source file
+containing the lexical analyzer,
+to access the token-codes by
+using the token-names.
+\fILpars.c\fP
+contains the error recovery routines and tables. It must also
+be compiled by the C-compiler. When the generated parser uses non-correcting
+error recovery (
+\fB\-n\fP 
+option) 
+\fILLgen\fP
+also generates a file 
+\fILncor.c\fP
+that contains the non-correcting recovery mechanism.
+.PP
+\fILLgen\fP
+will only update those output files that differ from their previous
+version.
+This allows
+\fILLgen\fP
+to be used with
+\fImake\fP
+(1) convieniently.
+.PP
+To obtain a working program, the user must also supply a
+lexical analyzer, as well as
+\fImain\fP
+and
+\fILLmessage\fP,
+an error reporting routine;
+\fILex\fP
+(1) is a useful program for creating lexical analysers usable
+by
+\fILLgen\fP.
+.PP
+\fILLgen\fP accepts the following flags:
+.IP \fB\-v\fP
+create a file called
+\fILL.output\fP,
+which contains a description of the conflicts that
+were not resolved.
+If the flag is given more than once,
+\fILLgen\fP
+will be more "verbose".
+If it is given three times, a complete description of the
+grammar will be supplied.
+.IP \fB\-x\fP
+the sets that are computed are extended with the nonterminal
+symbols and these extended sets are also included in the
+\fILL.output\fP
+file.
+.IP \fB\-w\fP
+no warnings are given.
+.IP \fB\-a\fP
+Produce ANSI C function headers and prototypes.
+.IP \fB\-n\fP
+Produce a parser with non-correcting error recovery.
+.IP \fB\-s\fP
+Simulate the calling of all defined subparsers in all semantic actions. When 
+using non-correcting error recovery, subparsers that are called in semantic
+actions may cause problems; this flag provides a `brute-force' solution. 
+.IP \fB\-j\fP[\fInum\fP]
+when this flag is given, \fILLgen\fP will generate dense switches,
+so that the compiler can generate a jump table for it. This will only be
+done for switches that have density between
+\fIlow_percentage\fP and \fIhigh_percentage\fP, as explained below.
+Usually, compilers generate a jumptable when the density of the switch
+is above a certain threshold. When jump tables are to be used more often,
+\fIhigh_percentage\fP must be set to this threshold, and \fIlow_percentage\fP
+must be set to a minimum threshold. There is a time-space trade-off here.
+.I num
+is the minimum number of cases in a switch for the \fB\-j\fP option to be
+effective. The default value (if
+.I num
+is not given) is 8.
+.IP \fB\-l\fP\fInum\fP
+The \fIlow_percentage\fP, as described above. Default value is 10.
+.IP \fB\-h\fP\fInum\fP
+The \fIhigh_percentage\fP, as described above. Default value is 30.
+.SH FILES
+LL.output                 verbose output file
+.br
+Lpars.c                   the error recovery routines
+.br
+Lncor.c                   non-correcting error recovery mechanism
+.br
+Lpars.h                   defines for token names
+.SH "SEE ALSO"
+\fIlex\fP(1)
+.br
+\fImake\fP(1)
+.br
+\fILLgen, an Extended LL(1) Parser Generator\fP
+by C.J.H. Jacobs.
+.br
+\fITop-down Non-Correcting Error Recovery in LLgen\fP
+by A.W van Deudekom and P.J. Kooiman
+.SH DIAGNOSTICS
+Are intended to be self-explanatory. They are reported
+on standard error. A more detailed report is found in the
+\fILL.output\fP
+file.
+.SH AUTHOR
+Ceriel J. H. Jacobs
+.br
+The non-correcting error recovery mechanism is written by
+A.W van Deudekom and P.J. Kooiman.

util/LLgen/doc/LLgen.refs

@@ -0,0 +1,54 @@
+%T An ALL(1) Compiler Generator
+%A D. R. Milton
+%A L. W. Kirchhoff
+%A B. R. Rowland
+%B Proc. of the SIGPLAN '79 Symposium on Compiler Construction
+%D August 1979 
+%J SIGPLAN Notices
+%N 8
+%P 152-157
+%V 14
+
+%T Lex - A Lexical Analyser Generator
+%A M. E. Lesk
+%I Bell Laboratories
+%D October 1975
+%C Murray Hill, New Jersey
+%R Comp. Sci. Tech. Rep. No. 39
+
+%T Yacc: Yet Another Compiler Compiler
+%A S. C. Johnson
+%I Bell Laboratories
+%D 1975
+%C Murray Hill, New Jersey
+%R Comp. Sci. Tech. Rep. No. 32
+
+%T The C Programming Language
+%A B. W. Kernighan
+%A D. M. Ritchie
+%I Prentice-Hall, Inc.
+%C Englewood Cliffs, New Jersey
+%D 1978
+
+%A M. Griffiths
+%T LL(1) Grammars and Analysers
+%E F. L. Bauer and J. Eickel
+%B Compiler Construction, An Advanced Course
+%I Springer-Verlag
+%C New York, N.Y.
+%D 1974
+
+%T Make - A Program for Maintaining Computer Programs
+%A S. I. Feldman
+%J Software - Practice and Experience
+%V 10
+%N 8
+%P 255-265
+%D August 1979
+
+%T Methods for the Automatic Construction of Error Correcting Parsers
+%A J. R\*:ohrich
+%J Acta Informatica
+%V 13
+%P 115-139
+%D 1980