    Some directives require arguments, which are usually provided following
separating (but optional) tt(=) characters. Arguments of directives, are text,
surrounded by double quotes (strings). If a string must itself contain a
double quote or a backslash, then precede these characters by a backslash. The
exceptions are the tt(%s) and tt(%x) directives, which 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 warnings. This happens when a directive
conflicts with the contents of a 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). In those cases the directive is
ignored, and hand-editing may then be required to effectuate the directive.

    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).

           A warning is issued if this option is used and an already
            existing scanner-class header file does not include
            tt(`filename'). 
    it() bf(%case-insensitive)nl()
           Generates 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.

           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).

           A warning is issued if this option 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. 
COMMENT(
            The tt(%debug) option allows for a  fine-grained control over what
            debug information is provided. This is realized by appending tt(=
            debug-list) to tt(%debug), where tt(debug-list) is a
            comma-separated list of the following keywords:nl()

            table(2)(ll)(
            row(cell(tt(action))cell(show decisions made while matching rules,
                and the numbers of rules that were matched))
            )
END)    
            
    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).

           A warning is issued if this option is used and an already existing
            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. 
    it() bf(%input-interface) tt(= "interface") nl()
           Defines the pathname of the file containing the interface of a
            user-defined tt(Input) class. See section bf(9.1. THE CLASS INPUT)
            in the bf(flexc++)(1) manual page for additional information about
            user-defined tt(Input) classes.
    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(5. INTERACTIVE SCANNER) section
            in the bf(flexc++)(1) 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 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.

          A warning is issued if this option is used and an already existing
            scanner-class header file does not define tt(namespace
            identifier).
    it() bf(%print-tokens) nl() 
           This option 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 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() 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 mini scanner).
    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(%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(%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 mini scanner).
    )
