CEXTRACT(1)

NAME
cextract, CDOCNAME - C prototype/documentation extractor

SYNOPSIS
cextract [ -Q# ] [ +AaPpNnxZ ] [ -o ofile ] [ -Hstr -Yprog -B -b -V -v ] [[ -options ] filename... ]

CDOCNAME [ -Q# ] [ +AaNnx ] [ -o outfile ] [ -Yprogram -B -b -V -v ] [[ -options ] filename... ]

DESCRIPTION
The cextract program is used to extract the function descriptions (aka prototypes) from a list of C source files and send them out to the standard output or a specified file. It may also be used to generate basic documentation for a list of C source files.

The specific reason this program was written was to provide a method of automatically generating header files, containing prototypes, for all of the functions used throughout a multi-file project.

Along with the standard C preprocessing options, -D, -I, and -U, there are options which allow more control of what form the output will take.

To allow for conditional processing, cextract automatically predefines the __CEXTRACT__ identifier. Preprocessor commands, such as "#if", "#ifdef" and "#ifndef" may then be used to control what code is parsed by cextract. If the CDOCNAME command is used, the program will also define __CEXTDOC__.

The cextract program also supports the use of customization files. A system configuration file will be read, and then any "NORMRC" file in the user's home directory, and finally any "NORMRC" file in the current directory. For a description of the format of the customization file, see the cextrc(5) manual page.

COMMAND LINE OPTIONS
The cextract and CDOCNAME programs support both long and short command line options. Also, a `+' sign before an option description means that it can be either on or off, with a `+' prefix enabling that option or a `-' prefix disabling it. The prefix of "no-" (or "no") is also supported for disabling an option.

Most command line arguments may be used anywhere on the command line, but a few must be used before any file parsing begins [such as the -N, +Z and -x options], and one can only be the first argument on the command line [the -Q flag].

+A, +sort-all
    Sort the output, listing all functions in alphabetical order. This option is not compatible with the +C flag, since functions are sorted over the entire spectrum, not just for each file.

+a, +sort-by-files
    Sort the output, listing functions alphabetically for each file. Since this option sorts each file separately, it is compatible with the +C flag, unlike the +A option. For cextract, the default is to not do any sorting, while the CDOCNAME default is to sort by files.

-b, -build-config
    Automatically build a configuration file in the current directory based on the current program settings.

-B, -system-build
    Generate a system wide configuration file based on the current program settings.

+C, +first-comments
    Capture the first comment encountered in each file and include it in the generated output. [default off]

+c, +comments, +yank-comments
    Take the comment immediately preceding the function declaration and send it as output along with the function prototype. [default on]

-Dexpression, -define=expression
    Define a macro, as per the C "#define" preprocessor statement.

+E, +externs
    Place the string 'extern' before each function prototype. [default on]

+F, +filename
    Prepend the name of the file to the initial comment when it is processed. This flag requires the +C option. [default off]

-f%##, -font-%-##
    Specify what fonts are to be used when generating troff documentation output. The font name is a one or two character troff name which will be interpreted later by the troff processor. Four fonts are used: `1' or `t' which is used only for the title words "Function:" and "File:" [default value of "C", Courier]; `2' or `c' which is used for comments [default value of "CO", Courier Oblique]; `3' or `n' which is used for the function name [default value of "B", Times Bold]; and `4' or `p' for the parameter list [default value of "R", Times Roman]. Note that the `%' character indicates the type being adjusted, and "##" indicates the one or two character font name.

-Hstring, -header-string=string
    During the normal extraction mode, enclose the output within the sequence "#ifndef string", "#define string", ..., "#endif /* string */". This method is used with many system header files and prevents the header file from being parsed more than once. If this option is not used, the output will be enclosed within a "#ifndef __CEXTRACT__", "#endif /* __CEXTRACT__ */" sequence instead.

-Idirectory, -include=directory
    Add the indicated directory to the search path for include files accessed via the "#include" preprocessor statement. This flag is passed on to the C preprocessor.

+m, +multi-comments, +multiple-comments
    If the -c flag is set, look for a "block" of multiple comments, instead of a single comment. Comments with more than one newline in between are considered separate. [default off]

-N, -roff-mode, -troff-mode
    Enable documentation mode, sending output as -ms troff format.

-n, -doc-mode
    Enable documentation mode, sending output as normal text. This is the default mode of the CDOCNAME program.

-o outfile, -output-file outfile, -output-file=outfile
    Send output to the specified file instead of the standard output. The file name need not immediately follow the `-o' flag, but it must be the first non-option argument. Warning: This will overwrite any existing file of the same name.

+P, +dual-output
    In extraction mode, generate both styles of C prototypes, separated by using "#ifdef" and "#else" statements to test for __STDC__. This option must precede any file arguments. [default on]

+p, +ansi-code
    Produce output in ANSI C prototype format; otherwise, produce old-style declarations. This option must precede any file arguments. [default off]

-qfile, -config-file=file
    Read in the specified file and parse it for customization commands.

-Q#, -read-config=#
    An octal digit specifies which configuration files should be read; 1 for the system configuration file, 2 for the $HOME/NORMRC file and 4 for the "NORMRC" file in the current directory. Add values to read multiple files. If no number is specified, a 0 is assumed. This option must be the very first argument on the command line. [default value of 7 reads all three files]

+r, +remove-names, +discard-names
    Strip out the variable names when sending out the prototype lists.

+S, +show-all, +show-anyway
    If the -p flag is off, output the prototype list anyway, but enclosed within comments. If the -P flag is set, comments and commented prototypes should also be duplicated within the non-ANSI portion of the output. [default on]

+s, +s:none|all|only, +statics, +statics: none|all|only
    Indicate how static functions are to be treated. If "none" is chosen, static functions will be ignored, if "only" then any non-static functions will be ignored, and "any" indicates that all functions will be included. If no selection is given, either "any" (`+' flag), or "none" (`-' flag) will be used.

-T#, -tab-width=#
    Specify the tab width used during documentation output. If no value is given, or a value of zero is given, tabs are passed though unformatted.

-Uname, -undefine=name
    Undefine a macro. If "-Dname" was specified in a previous argument, it is removed from the argument list; otherwise, this option is passed on to the C preprocessor.

-V, -settings
    Show the current settings of the various program options.

-v, -version-info
    Display the version number of the program.

+W, +break-after-types, +break-types
    When enabled, a newline will be inserted between the function type and the function name in the function declarations.

+w#, +wrap-parameters=#
    If the length of the parameter list for a function would cause it to exceed a given number of columns [72 by default], a newline will be inserted in place of a space character, so that the function will not exceed that given length. The optional number after the command will override a negation prefix if encountered.

-x, -extract-mode
    Run cextract or CDOCNAME as a prototype extractor. This is the default mode for cextract.

-Yprogram -cpp-program=program
    Specify which program to use as the C preprocessor. This program should resolve all of the C defines and preprocessor statements while, hopefully, leaving comments intact.

+Z, -merge-output
    Combine the ANSI and K&R C output of the cextract on one line, to create a much more compact header file.

VMS
Configuration files are also supported under VMS. The default configuration files for VMS systems are sys$library:cext.cnf, sys$login:cext.cnf, and cext.cnf.

Since the VMS C compiler strips out comments, the documentation mode and comment options are not very useful. Using the GNU C preprocessor instead might be a possible solution.

COPYRIGHT
The code is freely distributable and there are no restrictions other than the fact that it not be used for monetary gain and that copyright notices must be kept intact.

Both cextract and CDOCNAME may be used to generate proprietary source code or documentation, but its own source code may not be used as a part of any proprietary programs.

The header files and documentation generated by cextract and CDOCNAME are not subject to this COPYRIGHT notice because they are derived from the source code which was read in by the program to create the output.

FILES

SYSCXTRC, $HOME/NORMRC, NORMRC
    The list of configuration files, and the order in which they are read in.

SEE ALSO
cc(1), cextrc(5)

AUTHORS
Adam Bryant
adb@cs.bu.edu

initial VMS port by John Carr
jrcarr@iup.bitnet

special thanks to comp.sources.reviewed reviewers, without whom this
program would be much less useful.

VMS
On VMS systems, only the longer command line options are available, and the '/' character is used to specify command line options.

BUGS
1) As far as I know, there is no way to tell the normal VMS C compiler not to strip out comments. This renders the comment extraction and documentation mode portions rather useless to VMS sites. Getting the GNU C preprocessor for such sites is recommended.

2) Cextract has problems with function pointers and structure definitions within the parameter list, using typedefs for such declarations is recommended.

3) Does not yet fully support C++ code.

4) It is dependent on the given C preprocessor, so will have any limitations (such as maximum #defines) which the C preprocessor has.

If any other bugs are detected, please notify the author.