Where available, single letter options are listed between parentheses
beyond their associated long-option variants. Single letter options require
arguments if their associated long options also require arguments. Options
affecting the class- or implementation header files are ignored if these
files already exist. Options accepting a `filename' do not accept path names,
i.e., they cannot contain directory separators (tt(/)); options accepting a
'pathname' may contain directory separators.

Some options may cause errors. This happens when they conflict with the
contents of a file which bic() cannot modify (e.g., a parser class header file
exists, but doesn't define a namespace, but a tt(--namespace) option was
specified).

To solve the error the offending option could be omitted; the existing file
could be removed; or the existing file could be hand-edited according to the
option's specification. 

Note that bic() currently does not handle the opposite error condition: if a
previously used option is omitted, then bic() does not report an
inconsistency. In those cases compilation errors may be observed.

    itemization(
    it() loption(analyze-only) (soption(A))nl()
           Only analyze the grammar. No files are (re)written. This option can
            be used to test the grammatic correctness of modification `in
            situ', without overwriting previously generated files. If the
            grammar contains syntactic errors only syntax analysis is 
            performed.

    it() lsoption(baseclass-header)(b)(filename)nl()
           tt(Filename) defines the name of the file to contain the parser's
            base class. This class defines, e.g., the parser's symbolic
            tokens. Defaults to the name of the parser class plus the suffix
            tt(base.h). It is generated, unless otherwise indicated (see
            tt(--no-baseclass-header) and tt(--dont-rewrite-baseclass-header)
            below).

           It is an error if this option is used and an already
            existing parser class header file does not contain tt(#include
            "filename").

    it() label(PREINCLUDE) lsoption(baseclass-preinclude)(H)(pathname)nl()
           tt(Pathname) defines  the path to the file preincluded in the
            parser's base-class header. This option is needed in situations
            where the base class header file refers to types which might not
            yet be known. E.g., with polymorphic semantic values a
            tt(std::string) value type might be used. Since the tt(string)
            header file is not by default included in tt(parserbase.h) we
            somehow need to inform the compiler about this and possibly other
            headers. The suggested procedure is to use a pre-include header
            file declaring the required types. By default `tt(header)' is
            surrounded by double quotes: tt(#include "header") is used when
            the option tt(-H header) is specified.  When the argument is
            surrounded by pointed brackets tt(#include <header>) is
            included. In the latter case, quotes might be required to escape
            interpretation by the shell (e.g., using tt(-H '<header>')).

    it() lsoption(baseclass-skeleton)(B)(pathname)nl() 
           tt(Pathname) defines the path name to the file containing the
            skeleton of the parser's base class. It defaults to the
            installation-defined default path name (e.g.,
            tt(/usr/share/bisonc++/) plus tt(bisonc++base.h)).

    it() lsoption(class-header)(c)(filename)nl()
           tt(Filename) defines the name of the file to contain the parser
            class. Defaults to the name of the parser class plus the suffix
            tt(.h)

           It is an error if this option is used and an already
            existing implementation header file does not contain tt(#include
            "filename").

    it() loption(class-name) tt(className) nl()
           Defines the name of the bf(C++) class that is generated.  If
            neither this option, nor the tt(%class-name) directory is
            specified, then the default class name (tt(Parser)) is used.

           It is an error if this option is used and tt(className) differs
            from the name of the class that is defined in an already existing
            parser-class header file and/or if an already existing
            implementation header file does not define members of the class
            tt(`className').

    it() lsoption(class-skeleton)(C)(pathname)nl()
           tt(Pathname) defines the path name to the file containing the
            skeleton of the parser class. It defaults to the
            installation-defined default path name (e.g.,
            tt(/usr/share/bisonc++/) plus tt(bisonc++.h)).

    it() loption(construction)nl() 
           Details about the construction of the parsing tables are written to
            the same file as written by the tt(--verbose) option (i.e.,
            tt(<grammar>.output), where tt(<grammar>) is the input file read
            by bic()). This information is primarily useful for developers. It
            augments the information written to the verbose grammar output
            file, generated by the tt(--verbose) option.

    it() loption(debug)nl() 
           Provide the generated tt(parse) and its support functions with
            debugging code, optionally showing the actual parsing process on
            the standard output stream. When included, the debugging output is
            active by default, but its activity may be controlled using the
            tt(setDebug(bool on-off)) member. Bic() does not use tt(#ifdef
            DEBUG) macros. Rerun bic() without the tt(--debug) option to
            remove the debugging code.

            Note that this option does em(not) show the actions of bic()'s own
            parser, its own lexical scanner or merely the numbers of the
            case-entries executed by the parser's tt(parse) function. If that
            is what you want, use the tt(--own-debug, --action-cases,
            --scanner-debug) and/or tt(--own-tokens) options.

           When polymorphic semantic values
            are used (see section
IFDEF(manpagetext)(\
            bf(POLYMORPHIC SEMANTIC VALUES)\
)(\
            ref(POLYMORPHIC)\
))
           then the generated parser might attempt to retrieve an incorrect
            polymorphic value. In that case a fatal error is generated, ending
            bic()'s run. The error message itself cannot refer to the action
            block where the error occurred. If this situation is encountered,
            rerun bic(), specifying tt(--debug) and call
            tt(parser.setDebug(Parser::ACTIONCASES)): as a debugging aid the
            generated parser then shows the executeAction switch's case entry
            numbers just before their execution.

    it() lsoption(default-actions)(d)(off|quiet|warn)nl()
           When tt(warn) is specified (which is the default) an action block
            executing tt($$ = $1) (or tt($$ = STYPE_{}) for empty production
            rules) is added to production rules that do not explicitly define
            their own final action blocks, while issuing a warning. When
            tt(quiet) is specified these action blocks are silently added. It
            is an error when the types of $$ and $1 differ (but it is OK if
            neither $$ nor $1 is associated with a specific type). When
            tt(off) is specified no action blocks are added (issuing a warning
            unless the option/directive tt(tag-mismatches off) has been 
            specified).

    it() label(ERRORVERBOSE)loption(error-verbose)nl()
           When a syntactic error is reported, the generated parse function
            dumps the parser's state stack to the standard output
            stream. The stack dump shows on separate lines a stack index
            followed by the state stored at the indicated stack element. The
            first stack element is the stack's top element.

    it() lsoption(filenames)(f)(filename)nl()
           tt(Filename) is a generic file name that is used for all header
            files generated by bic(). Options defining specific file names are
            also available (which then, in turn, overrule the name specified
            by this option).

    it() loption(flex)nl() 
           Bic() generates code calling tt(d_scanner.yylex()) to obtain the
            next lexical token, and calling tt(d_scanner.YYText()) for the
            matched text, unless overruled by options or directives explicitly
            defining these functions. By default, the interface defined by
            bf(flexc++)(1) is used. This option is only interpreted if the
            tt(--scanner) option or tt(%scanner) directive is also used.

    it() loption(help) (soption(h))nl()
            Write basic usage information to the standard output stream and
            terminate. 

    it() lsoption(implementation-header)(i)(filename)nl()
           tt(Filename) defines the name of the file to contain the
            implementation header. It defaults to the name of the generated
            parser class plus the suffix tt(.ih).

           The implementation header should contain all directives and
            declarations em(only) used by the implementations of the parser's
            member functions. It is the only header file that is included by
            the source file containing tt(parse)'s implementation. User
            defined implementation of other class members may use the same
            convention, thus concentrating all directives and declarations
            that are required for the compilation of other source files
            belonging to the parser class in one header file.

    it() lsoption(implementation-skeleton)(I)(pathname)nl()
           tt(Pathname) defines the path name to the file containing the
            skeleton of the implementation header. t defaults to the
            installation-defined default path name (e.g.,
            tt(/usr/share/bisonc++/) plus tt(bisonc++.ih)).

    it() loption(insert-stype)nl()
           This option is only effective if the tt(debug) option (or
            tt(%debug) directive) has been specified. When tt(insert-stype)
            has been specified the parsing function's debug output also shows
            selected semantic values. It should only be used if objects or
            variables of the semantic value type tt(STYPE_) can be inserted
            into tt(ostreams).

    it() label(MAXDEPTH) laoption(max-inclusion-depth)(value)nl()
           Set the maximum number of nested grammar files. Defaults to 10.

    it() loption(namespace) tt(identifier) nl()
           Define all of the code generated by bic() in the namespace
            tt(identifier). By default no namespace is defined. If this
            options is used the implementation header is provided with a
            commented out tt(using namespace) declaration for the specified
            namespace. In addition, the parser and parser base class
            header files also use the specified namespace to define their
            include guard directives.

           It is an error if this option is used and an already existing
            parser-class header file and/or implementation header file does
            not define tt(namespace identifier).

    it() loption(no-baseclass-header)nl()
           Do not write the file containing the parser class' base class, even
            if that file doesn't yet exist. By default the file containing the
            parser's base class is (re)written each time bic() is called. Note
            that this option should normally be avoided, as the base class
            defines the symbolic terminal tokens that are returned by the
            lexical scanner. When the construction of this file is suppressed,
            modifications of these terminal tokens are not communicated to the
            lexical scanner.

    it() loption(no-decoration) (soption(D))nl()
           Do not include user-defined or default actions when generating the
            parser's tt(parse) member. This effectively generates a parser
            which merely performs syntax checks, without performing the
            actions which are normally executed when rules have been
            matched. This may be useful in situations where a (partially or
            completely) decorated grammar is reorganized, and the syntactic
            correctness of the modified grammar must be verified, or in
            situations where the grammar has already been decorated, but
            functions which are called from the rules's actions have not yet
            been impleemented.

    it() loption(no-lines)nl() 
           Do not put tt(#line) preprocessor directives in the file containing
            the parser's tt(parse) function. By default the file containing
            the parser's tt(parse) function also contains tt(#line)
            preprocessor directives. This option allows the compiler and
            debuggers to associate errors with lines in your grammar
            specification file, rather than with the source file containing
            the tt(parse) function itself.

    it() loption(no-parse-member)nl()
           Do not write the file containing the parser's predefined parser
            member functions, even if that file doesn't yet exist. By default
            the file containing the parser's tt(parse) member function is
            (re)written each time bic() is called. Note that this option
            should normally be avoided, as this file contains parsing
            tables which are altered whenever the grammar definition is
            modified. 

    it() loption(own-debug)nl()
           Displays the actions performed by bic()'s parser when it processes
            the grammar specification file(s) (lots of output!). This implies
            the tt(--verbose) option.

    it() loption(own-tokens) (soption(T))nl()
           The tokens returned as well as the text matched by bic()'s lexcial
            scanner are shown when this option is used.

           This option does em(not) result in the em(generated) parsing
            function displaying returned tokens and matched text. If that is
            what you want, use the tt(--print-tokens) option.

    it() lsoption(parsefun-skeleton)(P)(pathname)nl()
           tt(Pathname) defines the path name of the file containing the
            parsing member function's skeleton. It defaults to the
            installation-defined default path name (e.g.,
            tt(/usr/share/bisonc++/) plus tt(bisonc++.cc)).

    it() lsoption(parsefun-source)(p)(filename)nl()
           tt(Filename) defines the name of the source file to contain the
            parser member function tt(parse). Defaults to tt(parse.cc).

    it() lsoption(polymorphic-code-skeleton)(L)(pathname)nl()
           tt(Pathname) defines the path name of the file containing the
            non-template members of the polymorphic Base class.  It defaults
            to the installation-defined default path name (e.g.,
            tt(/usr/share/bisonc++/) plus tt(bisonc++polymorphic.code)).

    it() lsoption(polymorphic-skeleton)(M)(pathame)nl()
           tt(Pathname) defines the path name of the file containing the
            skeleton of the polymorphic template classes. It defaults to the
            installation-defined default path name (e.g.,
            tt(/usr/share/bisonc++/) plus tt(bisonc++polymorphic)).

    it() loption(print-tokens) (soption(t))nl()
           The generated parsing function implements a function tt(print_)
            displaying (on the standard output stream) the tokens returned by
            the parser's scanner as well as the corresponding matched
            text. This implementation is suppressed when the parsing function
            is generated without using this option. The member tt(print_) is
            called from tt(Parser::print), which is defined in-line in the the
            parser's class header. Calling tt(Parser::print_) can thus easily
            be controlled from tt(print), using, e.g., a variable that set by
            the program using the parser generated by bic().

           This option does em(not) show the tokens returned and text matched
            by bic() itself when it is reading its input file(s). If
            that is what you want, use the tt(--own-tokens) option.

    it() loption(prompt)nl()
           When adding debugging code (using the tt(debug) option or
            directive) the debug information is displayed continuously while
            the parser processes its input. When using the tt(prompt) option
            (or directive) the generated parser displays a prompt (a question
            mark) at each step of the parsing process. Caveat: when using this
            option the parser's input cannot be provided at the parser's
            standard input stream.

   it() label(REQUIRED) laoption(required-tokens)(number)nl()
           Following a syntactic error, require at least tt(number)
            successfully processed tokens before another syntactic error can
            be reported. By default tt(number) is zero.

    it() label(SCANOPT) lsoption(scanner)(s)(pathname)nl()
           tt(Pathname) defines the path name to the file defining the
            scanner's class interface (e.g., tt("../scanner/scanner.h")). When
            this option is used the parser's member tt(int lex()) is
            predefined as
           verb(
    int Parser::lex()
    {
        return d_scanner.lex();
    }
                )
           and an object tt(Scanner d_scanner) is composed into the parser
            (but see also option tt(scanner-class-name)). The example shows
            the function that's called by default. When the tt(--flex) option
            (or tt(%flex) directive) is specified the function
            tt(d_scanner.yylex()) is called. Any other function to call can be
            specified using the tt(--scanner-token-function) option (or
            tt(%scanner-token-function) directive).

           By default bic() surrounds tt(pathname) by double quotes (using,
            e.g., tt(#include "pathname")).  When tt(pathname) is surrounded
            by pointed brackets tt(#include <pathname>) is included.

           It is an error if this option is used and an already existing
            parser class header file does not include tt(`pathname').

    it() loption(scanner-class-name) tt(scannerClassName) nl() 
           Defines the name of the scanner class, declared by the tt(pathname)
            header file that is specified at the tt(scanner) option or 
            directive. By default the class name tt(Scanner) is used.

           It is an error if this option is used and either the
            tt(scanner) option was not provided, or the parser class interface
            in an already existing parser class header file does not declare a
            scanner class tt(d_scanner) object.

    it() loption(scanner-debug)nl() 
           Show de scanner's matched rules and returned tokens. This
            extensively displays the rules and tokens matched and returned by
            bic()'s scanner, instead of just showing the tokens and matched
            text which are received by bic(). If you want the latter, use the
            option tt(--own-tokens).

    it() laoption(scanner-matched-text-function)(function-call)nl() 
           The scanner function returning the text that was matched at the
            last call of the scanner's token function. A complete function
            call expression should be provided (including a scanner object, if
            used). This option overrules the tt(d_scanner.matched()) call used
            by default when the tt(%scanner) directive is specified, and it
            overrules the tt(d_scanner.YYText()) call used when the tt(%flex)
            directive is provided. Example:
           verb(
    --scanner-matched-text-function "myScanner.matchedText()"
                )

    it() laoption(scanner-token-function)(function-call)nl() 
           The scanner function returning the next token, called from the
            parser's tt(lex) function. A complete function
            call expression should be provided (including a scanner object, if
            used). This option overrules the tt(d_scanner.lex()) call used
            by default when the tt(%scanner) directive is specified, and it
            overrules the tt(d_scanner.yylex()) call used when the tt(%flex)
            directive is provided. Example:
           verb(
    --scanner-token-function "myScanner.nextToken()"
                )

           It is an error if this option is used and the scanner token
            function is not called from the code in an already
            existing implementation header.

    it() loption(show-filenames)nl() 
           Writes the names of the generated files to the standard error
            stream.

    it() lsoption(skeleton-directory)(S)(directory)nl() 
           Specifies the directory containing the skeleton files. In addition
            to specifying a common names for the skeleton files the locations
            of individual skeleton files can be specified using the options
            (tt(-B -C, -H, -I, -L) and tt(-M)).

    it() loption(stack-expansion)(size)nl() 
           Defines the number of elements to be added to the generated
            parser's semantic value stack when it must be enlarged. By default
            10 elements are added to the stack. This option/directive is
            interpreted only once, and only if tt(size) at least equals the
            default stack expansion size of 10.

    it() loption(tag-mismatches) tt(off|on)nl()
           When tt(on) is specified (which is the default), a warning is
            issued if no $$ assignment was detected in an action block, or if
            adding a default $$ = ... action was suppressed (cf.  the
            tt(default-actions off) option or directive).

    it() laoption(target-directory)(pathname) nl() 
           tt(Pathname) defines the directory where generated files should be
            written.  By default this is the directory where bic() is
            called. 

    it() loption(thread-safe)nl() 
           Only used with polymorphic semantic values, and then only required
            when the parser is used in multiple threads: it ensures that each
            thread's polymorphic code only accesses its own parser's error
            counting variable.

    it() lsoption(token-class)(K)(classname)nl()
           tt(Classname) defines the name of the tt(Tokens) class that is
            defined when tt(token-path) (see below) is specified. If
            tt(token-path) isn't specified then this option is ignored. By
            default the class name tt(Tokens) is used.

    it() lsoption(token-namespace)(N)(namespace)nl()
           If tt(token-path) is specified (see below) then tt(namespace)
            defines the namespace of the tt(Tokens) class. By default no
            namespace is used.

    it() lsoption(token-path)(F)(pathname)nl()
           tt(Pathname) defines the path name of the file to contain the
            tt(struct Tokens) defining the enumeration tt(Tokens_) containing
            the symbolic tokens of the generated grammar. If this option is
            specified the tt(ParserBase) class is derived from it, thus making
            the tokens available to the generated parser class. The name of
            the tt(struct Tokens) can be altered using the tt(token-class)
            directive or option. 
           By default (i.e., if tt(token_path) is not specified) the tokens
            are defined as the tt(enum Tokens_) in the tt(ParserBase) class.
            If tt(pathname) doesn't exist it is created by bic(). If the
            tt(pathname) file already exists it is rewritten at each new run
            of bic().

    it() loption(usage)nl()
            Writes basic usage information to the standard output stream and
            terminates. 

    it() loption(verbose) (soption(V))nl() 
           Writes a file containing verbose descriptions of the parser states
            and what is done for each type of look-ahead token in that state.
            This file also describes all conflicts detected in the grammar,
            both those resolved by operator precedence and those that remain
            unresolved.  It is not created by default, but if requested the
            information is written on tt(<grammar>.output), where
            tt(<grammar>) is the grammar specification file passed to bic().

    it() loption(version) (soption(v))nl()
            Displays bic()'s version number and terminates.

    )