1 CEXTRACT CEXTRACT is a program which will extract C prototypes from source code and then generate a header file or documentation file listing those functions which were encountered. The extraction mode is ideal for building header files for multiple source projects, and the documentation mode is useful in helping write documentation for such projects. [Note: due to limitations in the VAX compiler the comment extraction routines may not be available on your system. This would cause the documentation mode to be mostly inoperable.] Format: CEXTRACT [/OPTIONS] file-name ... 2 Parameter file-name ... Specify the list of files to be parsed by cextract. Any parameter not beginning with a '/', '-', or a '+' is interpreted as a file name; the others will be parsed as command qualifiers. 2 Command_Qualifiers Command qualifiers may be prefixed by either a '/', '-' or a '+'. If a '-' precedes a command qualifier, that option will be disabled, if appropriate, otherwise, it will be enabled. Also, a "no" or "no-" may also be used to indicate negation. /ANSI-CODE /ANSI-CODE (default disabled) /NOANSI-CODE If in extraction mode, with dual-output and merge-output disabled, the output should be in ANSI C format. /BREAK-AFTER-TYPES /BREAK-TYPES (default disabled) /BREAK-AFTER-TYPES /NOBREAK-TYPES /NOBREAK-AFTER-TYPES When enabled, a newline will be inserted between the function type and the function name in the function declarations. /BUILD-CONFIG Generate a configuration file in the current directory based on the current program settings. /COMMENTS /COMMENTS (default disabled) /NOCOMMENTS /YANK-COMMENTS /NOYANK-COMMENTS Capture the comment immediately preceding the function definition and use it as a description of that function. /CONFIG-FILE /CONFIG-FILE=file_name Read in the indicated file and parse it for configuration commands. /CPP-PROGRAM /CPP-PROGRAM=program_name Specify which program is to be used as a C preprocessor. This program should resolve all C defines and preprocessor statements while, hopefully, leaving all of the comments in place. Note that the default VMS C preprocessor is known to remove the comments, so finding an alternative is recommended. /DOC-MODE /DOC-MODE (default for cextdoc) Format the output as a normal text documentation file. /DEFINE /DEFINE=expression This option defines a macro by passing it on to the C preprocessor. /DUAL-OUTPUT /DUAL-OUTPUT (default enabled) /NODUAL-OUTPUT Generate both ANSI C and K&R C output when in extraction mode. The two styles will be separated using "#if __STDC__", "#else", and "#endif" constructs. This option may be overridden by the merge-output option. /EXTERNS /EXTERNS (default enabled) /NOEXTERNS Prepend an extern to each function prototype before output. /EXTRACT-MODE /EXTRACT-MODE (default mode for cextract) Extract the prototypes to build a header file for the functions. /FIRST-COMMENTS /FIRST-COMMENTS (default disabled) /NOFIRST-COMMENTS Capture the first comment encountered in each file and include it as part of the output. /FILENAME /FILENAME (default disabled) /NOFILENAME /PREPEND-FILENAME /NOPREPEND-FILENAME If the first_comments option is enabled, prepend the name of the file to the comment. /FONT /FONT_1_%% (default="C", Courier) /FONT_T_%% Specify the title font for troff-mode output. /FONT_2_%% (default="CO", Courier Oblique) /FONT_C_%% Specify the comment font for troff-mode output. /FONT_3_%% (default="B", Times Bold) /FONT_N_%% Specify the function name font for troff-mode output. /FONT_4_%% (default="R", Times Roman) /FONT_P_%% Specify the parameter list font for troff-mode output. /HEADER-STRING /HEADER-STRING=string (default disabled) Specify a string to be used as an indicator for file inclusion. This will cause the extraction mode output to be enclosed within the construct: #ifndef string #define string /*... output ...*/ #endif /* string */ This technique is used in many system header files to assure that the header file is not "#included" more than once. If not enabled, the output will be enclosed within the construct: #ifndef __CEXTRACT__ /*... output ...*/ #endif /* __CEXTRACT__ */ /INCLUDE /INCLUDE=directory Specify a directory to be added to the include file search path. This qualifier is passed on to the C preprocessor. /MERGE-OUTPUT /MERGE-OUTPUT (default disabled) /NOMERGE-OUTPUT In extraction mode, generate the prototypes enclosed within a macro so that both the ANSI C and K&R C declarations are handled on the same line. This option overrides both the dual-output and ansi-code option settings. /MULTIPLE-COMMENTS /MULTI-COMMENTS (default disabled) /NOMULTI-COMMENTS /MULTIPLE-COMMENTS /NOMULTIPLE-COMMENTS When extracting comments, assume that consecutive comments are actually a single comment. This allows for coding styles which make use of "block" comments. /OUTPUT-FILE /OUTPUT-FILE=file_name (default=terminal) Specify a file to which output should be sent. If no file name is specified as part of the qualifier, the first non-qualifier is used as the name of the output file. /READ-CONFIG /READ-CONFIG=# (default=7) Specify an octal digit representing which configuration files should or should not be read. The system file is 1, the file in the user's default directory is 2, and the file in the current directory is 4. Add the numbers together to read in multiple configuration files. If no number is specified a zero is assumed. /REMOVE-NAMES /REMOVE-NAMES (default disabled) /NOREMOVE-NAMES /DISCARD-NAMES /NODISCARD-NAMES Do not display the variable names in the prototype output. /ROFF-MODE /ROFF-MODE (this mode is not a default) /TROFF-MODE Generate documentation output, and use a UNIX -ms troff format. This will probably not prove too useful on a VMS system. /SETTINGS Show all of the configuration settings. This is very useful for determining if a configuration file is working properly. /SHOW-ALL /SHOW-ALL (default enabled) /NOSHOW-ALL /SHOW-ANYWAY /NOSHOW-ANYWAY If any output in K&R C is generated, that output should include the ANSI C prototypes enclosed within comments. /SINGLE-COMMENTS /SINGLE-COMMENTS (default enabled) /NOSINGLE-COMMENTS When extracting comments, do not search for multi-line comments. /SORT /SORT-ALL (default=NOSORT) /SORT-BY-FILES /NOSORT Specify a sorting method for the functions. Sort alphabetically either over all of the functions, over each file, or not at all. /STATICS /STATICS (default disabled) /NOSTATICS (enabled for cextdoc) /STATICS=NONE /STATICS=ANY /STATICS=ONLY Set how static variables should be treated by the program. By default, they are excluded from searches, but they may also be either included with non-statics, or searched for alone. Using these options you can determine whether the header file is for an entire program or library, or just for a single file. /SYSTEM-BUILD Generate the system configuration file based on the current program settings. /TAB-WIDTH /TAB-WIDTH=width (default=0) Specify a numeric width for the tab setting during conversion of tabs to spaces for documentation generation. A setting of 0 means to not perform any conversion. /UNDEFINE /UNDEFINE=macro Specify a macro to undefine when calling the C preprocessor. /VERSION-INFO /VERSION-INFO Display the version information for the program. /WRAP-PARAMETERS /WRAP-PARAMETERS (default disabled) /NOWRAP-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. 2 Customization Files CEXTRACT has support for customization files which are read at startup, before the qualifiers are checked, or whenever specified by the /CONFIG-FILE qualifier. Configuration files are checked for (on most VMS systems) in the following locations: sys$library:cext.cnf - the system configuration file sys$login:cext.cnf - the initial directory upon login cext.cnf - the current directory The file should be a normal text file, with each customization command on a separate line. Blank lines, and any line beginning with a "#" will be ignored. All commands should be in lowercase. Any command preceded by the string "doc-only " will only be used during the documentation mode, and any command preceded by "extract-only " will only be used during the extraction mode. Commands which are preceded by either a "!", the string "no", or the string "no-" will be interpreted as disabling that option, if appropriate. The supported commands include all of the command qualifiers (without the preceding '/', of course), except for the "read-config" command, which is unsupported for obvious reasons. In addition to the command qualifiers, the "replace" command is supported to allow for the replacement of types, variables or type-variable combinations after a "#define" has been expanded. The format of the replace command is: replace [type/variable/all] "string1" "string2" As an example, the default replacement of FILE usually has the format: replace type "struct _iobuf" "FILE" The varargs system is also replaced using this command. 2 Examples CEXTRACT FILEA.C Extract the function prototypes in the default extraction format from the C source file FILEA.C. CEXTDOC FILEA.C FILEB.C Extract the function prototypes in a normal documentation format from the C source files FILEA.C and FILEB.C. CEXTRACT /TROFF-MODE FILEA.C FILEB.C Extract the function prototypes in a troff documentation format from the C source files FILEA.C and FILEB.C. Probably useless on a VMS system. CEXTRACT /SETTINGS Find out what all of the default settings are. This will show what the normal environment is. CEXTRACT /READ-CONFIG /DUAL-OUTPUT FILEA.C Extract the function prototypes assuring that the configuration files are not read in. Also assure that both K&R and ANSI C output will be used.