    Some directives require arguments, which are usually provided following
separating (but optional) tt(=) characters. Arguments of directives are text,
surrounded by double quotes (strings), or embedded in raw string literals
(rawstrings).  Double quotes or backslashes inside strings must themselves be
preceded by backslashes; these backslashes are not required when rawstrings
are used. 

    The tt(%s) and tt(%x) directives are immediately followed by name lists,
consisting of identifiers separated by blanks.  Here is an example of the
definition of a directive:
        verb(
    %class-name = "MyScanner"
        )

    Directives accepting a `filename' do not accept path names, i.e., they
cannot contain directory separators (tt(/)); options accepting a 'pathname'
may contain directory separators. A 'pathname' using blank characters should
be surrounded by double quotes.

Some directives may generate errors. This happens when a directive 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) directive was provided). To solve the error the offending
directive could be omitted, the existing file could be removed, or the
existing file could be hand-edited according to the directive's specification.
Note that flc() currently does not handle the opposite error condition: if a
previously used directive is omitted, then flc() does not detect the
inconsistency. In those cases you may encounter compilation errors.

    itemization(
    it() bf(%baseclass-header) tt(= "filename") nl()
           Defines the name of the file to contain the scanner class's base
            class interface. Corresponding command-line option:
            tt(--baseclass-header).

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

    it() bf(%baseclass-preinclude) tt(= "filename") nl()

           tt(Filename) defines the path to the file preincluded by the
            scanner's base-class header.  It may (only) be required when a
            user-defined tt(Input) class is used. See the description of the
            tt(--baseclass-preinclude) option for details about this
            directive. Instead of surrounding tt(filename) by double quotes
            pointed brackets (like tt(<filename>)) can also be used.

    it() bf(%case-insensitive)nl()
           Generates a scanner which em(case insensitively) matches 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.

           Corresponding command-line option: tt(--cases-insensitive).

           When this directive 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() bf(%class-header) tt(= "filename") nl()
           Defines the name of the file to contain the scanner class's
            interface. Corresponding command-line option: tt(--class-header).

    it() bf(%class-name) tt( = "className") nl()
           Declares the name of the scanner class generated by flc(). This
            directive corresponds to the tt(%name) directive used by
            bf(flex++)(1). Contrary to bf(flex++)'s tt(%name) declaration,
            tt(class-name) may appear anywhere in the first section of the
            grammar specification file. It may be defined only once. If no
            tt(class-name) is specified the default class name (tt(Scanner))
            is used. Corresponding command-line option:
            tt(--class-name).

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

    it() bf(%debug) 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 no tt(#ifdef DEBUG) macros are used in
            the generated code. 
            

    it() bf(%filenames) tt(= "basename") nl()
           Defines the basename of the tt(Scanner.h, Scanner.ih,) and
            tt(Scannerbase.h) files. E.g., when using the directive
                verb(
    %filenames = "scanner"
                )
           the names of the generated files are, respectively, tt(scanner.h,
            scanner.ih,) and tt(scannerbase.h).  Corresponding command-line
            option: tt(--filenames). The name of the source file (by default
            tt(lex.cc)) is controlled by the tt(%lex-source) directive.

    it() bf(%implementation-header) tt(= "filename") nl()
           Defines the name of the file to contain the implementation header.
            Corresponding command-line option: tt(--implementation-header).

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

    it() bf(%input-implementation) tt(= "sourcefile") nl()
           Defines the pathname of the file containing the implementation of a
            user-defined tt(Input) class.  See section bf(17. THE CLASS INPUT)
            in the bf(flexc++api)(3) manual page for additional information
            about user-defined tt(Input) classes.

    it() bf(%input-inline) tt(= "sourcefile") nl()
           Defines the pathname of the file containing inline implementations
            of a user-defined tt(Input) class. 

    it() bf(%input-interface) tt(= "interface") nl()
           Defines the pathname of the file containing the interface of a
            user-defined tt(Input) class. 

    it() bf(%interactive)nl()
           Generate an interactive scanner. An interactive scanner reads lines
            from the input stream, and then returns the tokens encountered on
            that line. The interactive scanner implemented by flc() only
            predefines the tt(Scanner(std::istream &in, std::ostream &out))
            constructor, by default assuming that input is read from
            tt(std::cin). See also section tt(1. INTERACTIVE SCANNER) section
            in the bf(flexc++api)(3) manual page.

    it() bf(%lex-function-name) tt(= "funname") nl()
           Defines the name of the scanner class's member to perform the
            lexical scanning. If this directive is omitted the default name
            (tt(lex)) is used. Corresponding command-line option:
            tt(--lex-function-name).

    it() bf(%lex-source) tt(= "filename") nl()
           Defines the name of the file to contain the scanner member
            tt(lex). Corresponding command-line option: tt(--lex-source).

    it() bf(%no-lines) nl() 
           Do not put tt(#line) preprocessor directives in the file containing
            the scanner's tt(lex) function. If omitted tt(#line) directives
            are added to this file, unless overridden by the command line
            options tt(--lines) and tt(--no-lines).

    it() bf(%namespace) tt(= "identifer") nl()
           Define the scanner class in the namespace tt(identifier). By
            default no namespace is used. If this directives 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 directive is used and an already
            scanner-class header file does not define tt(namespace
            identifier).

    it() bf(%print-tokens) nl() 
           this directive results in the tokens as well as the matched text to
            be displayed on the standard output stream, just before returning
            the token to tt(lex)'s caller. Displaying is suppressed again when
            the tt(lex.cc) file is generated without using this directive. The
            function showing the tokens (tt(ScannerBase::print_)) is called
            from tt(Scanner::print()), 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 directive 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() bf(%s) tt(namelist) nl()
           The tt(%s) directive is followed by a list of one or more
            identifiers, separated by blanks. Each identifier is the name of
            an em(inclusive start condition).

    it() bf(%skeleton-directory) tt(= "pathname") nl()
           Use tt(pathname) rather than the default (e.g.,
            tt(/usr/share/flexc++)) path when looking for flc()'s skeleton
            files. Corresponding command-line option:
            tt(--skeleton-directory).


    it() bf(startcondition-name) tt( = "startconditionName") nl()
           By default, flc() defines the enum tt(StartCondition_) defining
            the names of start-conditions. The tt(%startcondition-name)
            directive can be used to configure another name for the enum
            containing the names of the start-conditions.  It may be defined
            only once. 

           The name of the startcondition-enum may be modified, and the
            directive can also be omitted again after it has been specified
            before. When changing the name of the startcondition-enum or when
            reverting to the default name newly generated tt(lex.cc) and
            tt(ScannerBase.h) files will use the currently defined
            startcondition-enum name. Be advised, though, that the
            startcondition-enum name may also be used in user-defined members
            of the scanner-class, or in the scanner's header and internal
            header files. If so, the user is responsible for updating those
            files to the currently defined name of the startcondition-enum.

    it() bf(%target-directory) tt(= "pathname") nl()
           tt(Pathname) defines the directory where generated files should be
            written.  By default this is the directory where flc() is
            called. This directive is overruled by the tt(--target-directory)
            command-line option.

    it() bf(%token-path) tt(= "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()
           The bf(bisonc++)(1) parser generator has a similar option
            generating the file containing the tt(struct Tokens).
           This directive is overruled by the tt(--token-path)
            command-line option.

    it() bf(%x) tt(namelist) nl()
           The tt(%x) directive is followed by a list of one or more
            identifiers, separated by blanks. Each identifier is the name of
            an em(exclusive start condition).
    )
