Initial revision

util/LLgen/LLgen.1

@@ -0,0 +1,120 @@
+.\" $Header$
+.TH LLGEN 1
+.SH NAME
+LLgen, an extended LL(1) parser generator
+.SH SYNOPSIS
+\fBLLgen\fP
+[
+\fB\-vVxXfF\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.
+.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
+(I) 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
+(I) is a useful program for creating lexical analysers usable
+by
+\fILLgen\fP.
+.PP
+If the
+\fB\-v\fP
+or the
+\fB\-V\fP
+flag is given, the file
+\fILL.output\fP
+is prepared, which contains a description of the conflicts that
+were not resolved.
+If it 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.
+.PP
+If the
+\fB\-x\fP
+or the
+\fB\-X\fP
+flag is given,
+the sets that are computed are extended with the nonterminal
+symbols and these extended sets are also included in the
+\fILL.output\fP
+file.
+.PP
+If the
+\fB\-f\fP
+or the
+\fB\-F\fP
+flag is given,
+\fILLgen\fP generates code, that enables the C-compiler to generate jump-
+tables for switches. This option should only be used when a large address
+space is available.
+.SH FILES
+LL.output                 verbose output file
+.br
+Lpars.c                   the error recovery routines
+.br
+Lpars.h                   defines for token names
+.SH "SEE ALSO"
+\fIlex\fP (I)
+.br
+\fImake\fP (I)
+.br
+\fILLgen, an Extended LL(1) Parser Generator\fP
+by C.J.H. Jacobs.
+.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 BUGS
+Because some file names are fixed, at most one
+\fILLgen\fP
+process can be active in a given directory at
+a time.
+.SH AUTHOR
+Ceriel J. H. Jacobs