    Where available, single letter options are listed between parentheses
following their associated long-option variants. Single letter options require
arguments if their associated long options require arguments as well.  Options
affecting the class header or implementation header file 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.

COMMENT(
    class header:           warn for class-name mismatch
                            warn for namespace mismatch
                            warn for not including baseclass-header
    implementation header:  warn for not including the class header
END)

Some options may generate errors. This happens when an option conflicts with
the contents of an existing file which flc() cannot modify (e.g., a scanner
class header file exists, but doesn't define a name space, but a
tt(--namespace) option was provided). 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 flc()
currently does not handle the opposite error condition: if a previously used
option is omitted, then flc() does not detect the inconsistency. In those
cases you may encounter compilation errors.

    itemization(
    it() lsoption(baseclass-header)(b)(filename)nl()
          Use tt(filename) as the name of the file to contain the scanner
           class's base class. Defaults to the name of the scanner class plus
           tt(base.h)

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

    it() lsoption(baseclass-preinclude)(H)(pathname)nl()
           tt(Pathname) defines the path to the file preincluded in the
            scanner's base-class header. This option (or the corresponding
            directive) may be required when using a user-defined tt(Input)
            class using types etc. which aren't yet provided by the scanner's
            base class header. E.g., if a user-defined tt(Input) class uses a
            stack, then tt(#include <stack>) must have been declared when
            compiling that class (see the description of the tt(%input-...)
            declarations in the bf(flexc++input)(7) man-page for details).  By
            specifying this option (or the corresponding directive) the
            required header(s) are included when compiling the files generated
            by flc(). By default the tt(pathname) argument is surrounded by
            double quotes (which can also explicitly be
            provided). Alternatively, if tt(pathname) is surrounded by pointed
            brackets then those are used.

    it() lsoption(baseclass-skeleton)(C)(pathname)nl() 
           Use tt(pathname) as the path to the file containing the skeleton of
            the scanner class's base class. Its filename defaults to
            tt(flexc++base.h).

    it() loption(case-insensitive)nl()
           Use this option to generate a scanner em(case insensitively)
            matching regular expressions. All regular expressions specified in
            flc()'s input file are interpreted case insensitively and the
            resulting scanner object will case insensitively interpret its
            input. 

           When this option is specified the resulting scanner does not
            distinguish between the following rules:
           verb(
        First       // initial F is transformed to f
        first
        FIRST       // all capitals are transformed to lower case chars
                )
           With a case-insensitive scanner only the first rule can be matched,
            and flc() will issue warnings for the second and third rule about
            rules that cannot be matched.

           Input processed by a case-insensitive scanner is also handled case
            insensitively. The above mentioned tt(First) rule is matched for
            all of the following input words: tt(first First FIRST firST). 

           Although the matching process proceeds case insensitively, the
            matched text (as returned by the scanner's tt(matched()) member)
            always contains the original, unmodified text. So, with the above
            input tt(matched()) returns, respectively tt(first, First, FIRST)
            and tt(firST), while matching the rule tt(First).

    it() lsoption(class-header)(c)(filename)nl()
           Use tt(filename) as the name of the file to contain the scanner
            class. Defaults to the name of the scanner class plus the suffix
            tt(.h)

    it() laoption(class-name)(className)nl()
           Use tt(className) (rather than tt(Scanner)) as the name of the
            scanner class. Unless overridden by other options generated files
            will be given the (transformed to lower case) tt(className*) name
            instead of tt(scanner)*.

           It is an error if this option is used and an already
            existing scanner-class header file does not define tt(class
            `className')

    it() lsoption(class-skeleton)(C)(pathname)nl()
           Use tt(pathname) as the path to the file containing the skeleton of
            the scanner class. Its filename defaults to tt(flexc++.h).

    it() loption(construction) (soption(K))nl()
           Write details about the lexical scanner to the file
            tt(`rules-file'.output). Details cover the used character ranges,
            information about the regexes, the raw NFA states, and the final
            DFAs.

    it() loption(debug) (soption(d))nl() 
           Provide tt(lex) and its support functions with debugging code,
            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. Note that tt(#ifdef DEBUG) macros are not used
            anymore. By rerunning flc() without the bf(--debug) option an
            equivalent scanner is generated not containing the debugging
            code. This option does not provide debug information about flc()
            itself. For that use the options tt(--own-parser) and/or
            tt(--own-tokens) (see below). 

    it() lsoption(filenames)(f)(genericName)nl()
           Generic name of generated files (header files, not the
            tt(lex)-function source file, see the tt(--lex-source) option for
            that). By default the header file names will be equal to the name
            of the generated class.

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

    it() lsoption(implementation-header)(i)(filename)nl() 
           Use tt(filename) as the name of the file to contain the
            implementation header. Defaults to the name of the generated
            scanner class plus the suffix tt(.ih). The implementation header
            should contain all directives and declarations em(only) used by
            the implementations of the scanner's member functions. It is the
            only header file that is included by the source file containing
            bf(lex())'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 scanner class in one header
            file.

           It is an error if this option is used and an already existing
            tt('filename') file does not include the scanner class header
            file.

    it() lsoption(implementation-skeleton)(I)(pathname)nl()
           Use tt(pathname) as the path to the file containing the skeleton of
            the implementation header. Its filename defaults to
            tt(flexc++.ih).

    it() lsoption(lex-skeleton)(L)(pathname)nl()
           Use tt(pathname) as the path to the file containing the
            tt(lex()) member function's skeleton. Its filename defaults to
            tt(flexc++.cc).

    it() laoption(lex-function-name)(funname)nl()
           Use tt(funname) rather than tt(lex) as the name of the member
            function performing the lexical scanning.

    it() lsoption(lex-source)(l)(filename)nl()
           Define tt(filename) as the name of the source file to contain the
            scanner member function tt(lex). Defaults to tt(lex.cc).

    it() loption(matched-rules) (soption('R'))nl()
           The generated scanner will write the numbers of matched rules to 
            the standard output. It is implied by the tt(--debug) option.
            Displaying the matched rules can be suppressed by calling the
            generated  scanner's member tt(setDebug(false)) (or, of course, by
            re-generating the scanner without using specifying 
            tt(--matched-rules)).

    it() lsoption(max-depth)(m)(depth)nl()
           Set the maximum inclusion depth of the lexical scanner's
            specification files to tt(depth). By default the maximum depth is
            set to 10. When more than tt(depth) specification files are used
            the scanner throws a tt(Max stream stack size exceeded)
            tt(std::length_error) exception. 

    it() laoption(namespace)(identifier) nl()
           Define the scanner class in the namespace tt(identifier). By default
            no namespace is used. If this options is used the
            implementation header is provided with a commented out tt(using
            namespace) declaration for the requested namespace.  In addition,
            the scanner and scanner 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
            scanner-class header file does not define tt(namespace
            identifier). 

    it() loption(no-baseclass-header)nl()
           Do not write the file containing the scanner's base class interface
            even if it doesn't yet exist. By default the file containing the
            scanner's base class interface is (re)written each time flc() is
            called.

    it() loption(no-lines)nl() 
           Do not put bf(#line) preprocessor directives in the file containing
            the scanner's tt(lex) function. By default tt(#line) directives
            are entered at the beginning of the action statements in the
            generated tt(lex.cc) file, allowing the compiler and debuggers
            to associate errors with lines in your grammar specification
            file, rather than with the source file containing the tt(lex)
            function itself.

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

    it() loption(own-parser) (soption(P))nl() 
           The actions performed by flc()'s own parser are written to the
            standard output stream.

           This option does em(not) result in the generated program optionally
            displaying the actions of its tt(lex) function. If that is what
            you want, use the tt(--debug) option.

    it() loption(own-tokens) (soption(T))nl() 
           The tokens returned as well as the text matched by flc() are
            written to the standard output stream when this option is used.

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

    it() loption(print-tokens) (soption(t))nl() 
           The tokens returned as well as the text matched by the
            em(generated) tt(lex) function are displayed on the standard
            output stream, just before returning the token to tt(lex)'s
            caller. Displaying tokens and matched text is suppressed again
            when the tt(lex.cc) file is generated without using this
            option. The function showing the tokens (tt(ScannerBase::print_))
            is called from tt(Scanner::printTokens), which is defined in-line
            in tt(Scanner.h). Calling tt(ScannerBase::print_), therefore, can
            also easily be controlled by an option controlled by the program
            using the scanner object.

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

    it() loption(regex-calls)nl() 
           Show the function call order when parsing regular expressions (this
            option is normally not required. Its main purpose is to help
            developers understand what happens when regular expressions are
            parsed).

    it() loption(show-filenames) (soption(F))nl() 
           Write the names of the files that are generated to the 
            standard error stream.

    it() lsoption(skeleton-directory)(S)(pathname)nl() 
           Specifies the directory containing the skeleton files. This option
            can be overridden by the specific skeleton-specifying options
            (tt(-B -C, -H,) and tt(-I)).

    it() laoption(target-directory)(pathname) nl() 
           Specifies the directory where generated files should be written.
            By default this is the directory where flc() is called.

    it() lsoption(token-path)(O)(pathname) nl() 
           Specifies the location of the file containing the tt(struct Tokens)
            defining the (parser's) symbolic tokens which can be returned by
            the scanner's tt(lex()) function.nl()
           By default (i.e., if tt(token_path) is not specified) sumbolic
            tokens to be returned by the scanner's tt(lex()) function must
            otherwise be made available to the scanner, e.g., by defining them
            in the scanner class.
           The bf(bisonc++)(1) parser generator has a similar option
            generating the file containing the tt(struct Tokens).

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

    it() loption(verbose)(soption(V))nl() 
           The verbose option generates on the standard output stream various
            pieces of additional information, not covered by the
            tt(--construction) and tt(--show-filenames) options.

    it() loption(version) (soption(v))nl()
            Display flc()'s version number and terminate.
    )
