Initial revision

doc/bison.1

@@ -0,0 +1,292 @@
+.TH BISON 1 local
+.SH NAME
+bison \- GNU Project parser generator (yacc replacement)
+.SH SYNOPSIS
+.B bison
+[
+.BI \-b  " file-prefix"
+] [
+.BI \-\-file-prefix= file-prefix
+] [
+.B \-d
+] [
+.B \-\-defines
+] [
+.B \-l
+] [
+.B \-\-no-lines
+] [
+.BI \-o " outfile"
+] [
+.BI \-\-output-file= outfile
+] [
+.BI \-p " prefix"
+] [
+.BI \-\-name-prefix= prefix
+] [
+.B \-t
+] [
+.B \-\-debug
+] [
+.B \-v
+] [
+.B \-\-verbose
+] [
+.B \-V
+] [
+.B \-\-version
+] [
+.B \-y
+] [
+.B \-\-yacc
+] [
+.B \-h
+] [
+.B \-\-help
+] [
+.B \-\-fixed-output-files
+]
+file
+.SH DESCRIPTION
+.I Bison
+is a parser generator in the style of
+.IR yacc (1).
+It should be upwardly compatible with input files designed
+for
+.IR yacc .
+.PP
+Input files should follow the
+.I yacc
+convention of ending in
+.BR .y .
+Unlike
+.IR yacc ,
+the generated files do not have fixed names, but instead use the prefix
+of the input file.
+For instance, a grammar description file named
+.B parse.y
+would produce the generated parser in a file named
+.BR parse.tab.c ,
+instead of
+.IR yacc 's
+.BR y.tab.c .
+.PP
+This description of the options that can be given to
+.I bison
+is adapted from the node
+.B Invocation
+in the
+.B bison.texinfo
+manual, which should be taken as authoritative.
+.PP
+.I Bison
+supports both traditional single-letter options and mnemonic long
+option names.  Long option names are indicated with
+.B \-\-
+instead of
+.BR \- .
+Abbreviations for option names are allowed as long as they
+are unique.  When a long option takes an argument, like
+.BR \-\-file-prefix ,
+connect the option name and the argument with
+.BR = .
+.SS OPTIONS
+.TP
+.BI \-b " file-prefix"
+.br
+.ns
+.TP
+.BI \-\-file-prefix= file-prefix
+Specify a prefix to use for all
+.I bison
+output file names.  The names are
+chosen as if the input file were named
+\fIfile-prefix\fB.c\fR.
+.TP
+.B \-d
+.br
+.ns
+.TP
+.B \-\-defines
+Write an extra output file containing macro definitions for the token
+type names defined in the grammar and the semantic value type
+.BR YYSTYPE ,
+as well as a few
+.B extern
+variable declarations.
+.sp
+If the parser output file is named
+\fIname\fB.c\fR
+then this file
+is named
+\fIname\fB.h\fR.
+.sp
+This output file is essential if you wish to put the definition of
+.B yylex
+in a separate source file, because
+.B yylex
+needs to be able to refer to token type codes and the variable
+.BR yylval .
+.TP
+.B \-l
+.br
+.ns
+.TP
+.B \-\-no-lines
+Don't put any
+.B #line
+preprocessor commands in the parser file.
+Ordinarily
+.I bison
+puts them in the parser file so that the C compiler
+and debuggers will associate errors with your source file, the
+grammar file.  This option causes them to associate errors with the
+parser file, treating it an independent source file in its own right.
+.TP
+.BI \-o " outfile"
+.br
+.ns
+.TP
+.BI \-\-output-file= outfile
+Specify the name
+.I outfile
+for the parser file.
+.sp
+The other output files' names are constructed from
+.I outfile
+as described under the
+.B \-v
+and
+.B \-d
+switches.
+.TP
+.BI \-p " prefix"
+.br
+.ns
+.TP
+.BI \-\-name-prefix= prefix
+Rename the external symbols used in the parser so that they start with
+.I prefix
+instead of
+.BR yy .
+The precise list of symbols renamed is
+.BR yyparse ,
+.BR yylex ,
+.BR yyerror ,
+.BR yylval ,
+.BR yychar , 
+and
+.BR yydebug .
+.sp
+For example, if you use
+.BR "\-p c" ,
+the names become
+.BR cparse ,
+.BR clex ,
+and so on.
+.TP
+.B \-t
+.br
+.ns
+.TP
+.B \-\-debug
+Output a definition of the macro
+.B YYDEBUG 
+into the parser file,
+so that the debugging facilities are compiled.
+.TP
+.B \-v
+.br
+.ns
+.TP
+.B \-\-verbose
+Write an extra output file containing verbose descriptions of the
+parser states and what is done for each type of look-ahead token in
+that state.
+.sp
+This file also describes all the conflicts, both those resolved by
+operator precedence and the unresolved ones.
+.sp
+The file's name is made by removing
+.B .tab.c
+or
+.B .c
+from the parser output file name, and adding
+.B .output
+instead.
+.sp
+Therefore, if the input file is
+.BR foo.y ,
+then the parser file is called
+.B foo.tab.c
+by default.  As a consequence, the verbose
+output file is called
+.BR foo.output .
+.TP
+.B \-V
+.br
+.ns
+.TP
+.B \-\-version
+Print the version number of
+.I bison
+and exit.
+.TP
+.B \-h
+.br
+.ns
+.B \-\-help
+Print a summary of the options to
+.I bison
+and exit.
+.TP
+.B \-y
+.br
+.ns
+.TP
+.B \-\-yacc
+.br
+.ns
+.TP
+.B \-\-fixed-output-files
+Equivalent to
+.BR "\-o y.tab.c" ;
+the parser output file is called
+.BR y.tab.c ,
+and the other outputs are called
+.B y.output
+and
+.BR y.tab.h .
+The purpose of this switch is to imitate
+.IR yacc 's
+output file name conventions.
+Thus, the following shell script can substitute for
+.IR yacc :
+.sp
+.RS
+.ft B
+bison \-y $*
+.ft R
+.sp
+.RE
+.PP
+The long-named options can be introduced with `+' as well as `\-\-',
+for compatibility with previous releases.  Eventually support for `+'
+will be removed, because it is incompatible with the POSIX.2 standard.
+.SH FILES
+/usr/local/lib/bison.simple	simple parser
+.br
+/usr/local/lib/bison.hairy	complicated parser
+.SH SEE ALSO
+.IR yacc (1)
+.br
+The
+.IR "Bison Reference Manual" ,
+included as the file
+.B bison.texinfo
+in the
+.I bison
+source distribution.
+.SH DIAGNOSTICS
+Self explanatory.
+