CEXTRC(5)
FILE FORMATS
CEXTRC(5)
NAME
cextrc - C prototype/documentation
file format
extractor
customization
SYNOPSIS
.cextrc
DESCRIPTION
The programs cextract(1) and cextdoc(1) extract function
prototypes from C source code and create header and documentation files respectively. The .cextrc customization files
allow users to specify which options are set for those programs, without having to always use the command line.
The configuration files are read prior to the parsing of the
command line options, as well as whenever the `-q' flag is
encountered.
FORMAT
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.
Any command preceded by the string "doc-only " will only be
used in documentation mode, and any command preceded by
"extract-only " will only be used in extraction mode.
Commands which are preceded by either a `!' or the string
"no-" or "no" will be interpreted as disabling that option,
if appropriate.
COMMANDS
The full list of configuration commands is given below.
ansi-code
If dual-output and merge-output modes are not enabled,
produce output in ANSI C format, with full prototyping.
This command does not do anything when used in documentation mode.
break-after-types
break-types
When enabled, a newline will be inserted between the
function type and the function name in the function
declarations.
comments
yank-comments
Extract the comment immediately before
definition, and display it upon output.
the
function
Sun Release 4.1
CEXTRC(5)
Last change: 3 September 1992
1
FILE FORMATS
CEXTRC(5)
config-file: file
Read in the specified file and parse it for
tion commands.
configura-
cpp-program: program
Specify which program is to be used as a C preprocessor.
This program should resolve all C defines and
while, hopefully, leaving the comments intact.
doc-mode
Enable documentation mode with normal text
This is the default setting for cextdoc(1).
output.
define: expression
Pass the specified expression to the C preprocessor
with a "-D" string prepended to it. This command is
equivalent to the `-D' command line option.
dual-output
Provide output in both ANSI and K&R C
formats,
separated by an "#if __STDC__" ... "#else" ... "#endif"
construct. This command does not do anything when used
in documentation mode or if the merge-output option is
enabled.
externs
Prepend an "extern" to each function
output.
description
upon
extract-mode
Enable extraction mode and generate output which can be
used as a C header file defining the prototypes for all
of the functions which are encountered.
The is the
default mode for cextract(1).
first-comments
Include in the output the initial
in each file.
comment
encountered
filename
prepend-filename
If the "first-comments" option is enabled, prepend the
name of each file to the output of initial comments.
font % ##
Assign a troff font "##" to a given font type `%', when
using troff documentation mode.
The possible font
types are `1' or `t', `2' or `c', `3' or `n', and `4'
or `p' for the title, comment, name, and parameter list
respectively. The troff font "##" is a normal one or
two character troff font, such as "CO" for Courier
Sun Release 4.1
Last change: 3 September 1992
CEXTRC(5)
FILE FORMATS
2
CEXTRC(5)
Oblique.
header-string: string
When in extraction mode, enclose the output within
preprocessor directives testing for the definition of
string. This method is used with many system header
files, to insure that they are not "#include"d more
than once. If this option is not used, the output will
be enclosed within a "#ifndef __CEXTRACT__", "#endif /*
__CEXTRACT__ */" sequence instead.
include: directory
Pass the specified directory to the C preprocessor with
a "-I" string prepended to it.
This command is
equivalent to the `-I' command-line option.
merge-output
Merge the ANSI and K&R output into a single line of
output to make it take up less space. A macro is used
to expand the parameter list for ANSI compilers.
This
option overrides both the dual-output and ansi-code
options. There is no affect if the documentation mode
is enabled.
multi-comments
multiple-comments
When extracting comments, assume that consecutive comments are actually one single comment. This allows
people that place comment delimiters at the beginning
and end of each line to have their comments properly
captured.
output-file: outfile
Store the output in the specified file.
replace
Replace the first string which matches a variable,
type, or both (as selected) with the second string.
The format is:
replace [all/type/variable] "string1" "string2"
For example, on Sun machines, the automatic "FILE"
replacement could be accomplished using a command like:
replace type "struct _iobuf" "FILE"
However, this should not need to be entered by the
average user since it is handled automatically by cextract(1), as is the varargs system.
remove-names
discard-names
Remove variable names from the prototype list prior
Sun Release 4.1
Last change: 3 September 1992
CEXTRC(5)
to
3
FILE FORMATS
CEXTRC(5)
output.
roff-mode
troff-mode
Enable documentation mode with troff -ms format output.
This option is overridden by the doc-mode or extractmode options.
show-all
show-anyway
When output is K&R C, display prototypes in comments.
When dual-output is enabled, display comments and prototypes in both sections; otherwise, display comments
and prototypes only in the ANSI C portion. This option
does nothing in documentation mode.
single-comments
When extracting comments from a file, take only one
comment,
discarding all preceding comments.
This
option is the reverse of the multi-comments option.
sort-all
Alphabetically sort all of the functions
the files before generating output.
sort-by-files
For each file processed,
prior to output.
sort
all
of
from
the
all
of
functions
statics
statics: none
statics: any
statics: only
Select the method for how static
functions
should
be
treated.
ignored.
will be
functions
it will
preceding
If "none" is selected, statics will be
If "only" is selected, non-static functions
ignored.
Finally, "any" indicates that all
will be extracted. If no selection is made,
be the same as selecting "any" or (with a
`!') "none".
tab-width: width
Set the tab width to be an integer number width.
works only during documentation generation.
undefine: name
Undefine any previously
Sun Release 4.1
CEXTRC(5)
defined
macro.
If
none
Last change: 3 September 1992
FILE FORMATS
This
is
4
CEXTRC(5)
encountered, pass the specified expression to the C
preprocessor with a "-U" string prepended to it.
This
command is equivalent to the `-U' command-line option.
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.
FILES
/usr/local/lib/cext.config, $HOME/.cextrc, .cextrc
configuration files.
VMS
Configuration files are also supported under VMS.
default
configuration
files
for
VMS
systems
sys$library:cext.cnf, sys$login:cext.cnf, and cext.cnf.
The
are
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.
SEE ALSO
cextract(1), cextdoc(1)
AUTHOR
Adam Bryant
adb@bu.edu
initial VMS port by John Carr
jrcarr@iup.bitnet
Sun Release 4.1
Last change: 3 September 1992
5