🚀 go-pugleaf

Submitted-by: Adam Bryant <adb@cs.bu.edu>
Posting-number: Volume 2, Issue 40
Archive-name: cextract/part02
Supersedes: cextract: Volume 1, Issue 4-8

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#		"End of archive 2 (of 5)."
# Contents:  cextract.1 cextract.doc cextract.hlp cextrc.doc
# Wrapped by adb@csa on Fri Oct 30 16:20:36 1992
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'cextract.1' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'cextract.1'\"
else
echo shar: Extracting \"'cextract.1'\" \(11153 characters\)
sed "s/^X//" >'cextract.1' <<'END_OF_FILE'
X.TH CEXTRACT 1 "30 October 1992"
X.SH NAME
Xcextract, CDOCNAME \- C prototype/documentation extractor
X.SH SYNOPSIS
X.B cextract
X.RB [ " \-Q# " ]
X.RB [ " \+AaPpNnxZ "]
X.RB [ " \-o "
X.IR "ofile " ]
X.RB [ " \-H\fIstr\fB \-Y\fIprog\fB \-B \-b \-V \-v " ]
X.RB [[ " \-options " ]
X.IR filename \&.\|.\|. " " ]
X.LP
X.B CDOCNAME
X.RB [ " \-Q# " ]
X.RB [ " \+AaNnx "]
X.RB [ " \-o "
X.IR "outfile " ]
X.RB [ " \-Y\fIprogram\fB \-B \-b \-V \-v " ]
X.RB [[ " \-options " ]
X.IR filename \&.\|.\|. " " ]
X.SH DESCRIPTION
XThe
X.I cextract
Xprogram is used to extract the function descriptions (aka prototypes)
Xfrom a list of C source files and send them out to the standard output
Xor a specified file.  It may also be used to generate basic
Xdocumentation for a list of C source files.
X.sp
XThe specific reason this program was written was to provide a method
Xof automatically generating header files, containing prototypes, for
Xall of the functions used throughout a multi-file project.
X.sp
XAlong with the standard C preprocessing options, -D, -I, and -U, there
Xare options which allow more control of what form the output will
Xtake.
X.sp
XTo allow for conditional processing, \fIcextract\fR automatically
Xpredefines the __CEXTRACT__ identifier.  Preprocessor commands, such
Xas "#if", "#ifdef" and "#ifndef" may then be used to control what code
Xis parsed by \fIcextract\fR.  If the \fICDOCNAME\fR command is used,
Xthe program will also define __CEXTDOC__.
X.sp
XThe \fIcextract\fR program also supports the use of customization
Xfiles.  A system configuration file will be read, and then any
X"NORMRC" file in the user's home directory, and finally any "NORMRC"
Xfile in the current directory.  For a description of the format of the
Xcustomization file, see the \fIcextrc\fR(5) manual page.
X.SH COMMAND LINE OPTIONS
XThe \fIcextract\fR and \fICDOCNAME\fR programs support both long and
Xshort command line options.  Also, a `+' sign before an option
Xdescription means that it can be either on or off, with a `+' prefix
Xenabling that option or a `-' prefix disabling it.  The prefix of
X"no-" (or "no") is also supported for disabling an option.
X.sp
XMost command line arguments may be used anywhere on the command line,
Xbut a few must be used before any file parsing begins [such as the -N,
X+Z and -x options], and one can only be the first argument on the
Xcommand line [the -Q flag].
X.IP "+A, +sort-all"
XSort the output, listing all functions in alphabetical order.  This
Xoption is not compatible with the +C flag, since functions are sorted
Xover the entire spectrum, not just for each file.
X.IP "+a, +sort-by-files"
XSort the output, listing functions alphabetically for each file.
XSince this option sorts each file separately, it is compatible with
Xthe +C flag, unlike the +A option.  For \fIcextract\fR, the default is
Xto not do any sorting, while the \fICDOCNAME\fR default is to sort by
Xfiles.
X.IP "-b, -build-config"
XAutomatically build a configuration file in the current directory
Xbased on the current program settings.
X.IP "-B, -system-build"
XGenerate a system wide configuration file based on the current program
Xsettings.
X.IP "+C, +first-comments"
XCapture the first comment encountered in each file and include it in
Xthe generated output. [default off]
X.IP "+c, +comments, +yank-comments"
XTake the comment immediately preceding the function declaration and
Xsend it as output along with the function prototype. [default on]
X.IP "-D\fIexpression\fR, -define=\fIexpression\fR"
XDefine a macro, as per the C "#define" preprocessor statement.
X.IP "+E, +externs"
XPlace the string 'extern' before each function prototype. [default on]
X.IP "+F, +filename"
XPrepend the name of the file to the initial comment when it
Xis processed.  This flag requires the +C option. [default off]
X.IP "-f%##, -font-%-##"
XSpecify what fonts are to be used when generating troff documentation
Xoutput.  The font name is a one or two character troff name which will
Xbe interpreted later by the troff processor.  Four fonts are used: `1'
Xor `t' which is used only for the title words "Function:" and "File:"
X[default value of "C", Courier]; `2' or `c' which is used for comments
X[default value of "CO", Courier Oblique]; `3' or `n' which is used for
Xthe function name [default value of "B", Times Bold]; and `4' or `p' for
Xthe parameter list [default value of "R", Times Roman].  Note that the `%'
Xcharacter indicates the type being adjusted, and "##" indicates the
Xone or two character font name.
X.IP "-H\fIstring\fR, -header-string=\fIstring\fR"
XDuring the normal extraction mode, enclose the output within the
Xsequence "#ifndef \fIstring\fR", "#define \fIstring\fR", ..., "#endif
X/* \fIstring\fR */".  This method is used with many system header
Xfiles and prevents the header file from being parsed more than once.
XIf this option is not used, the output will be enclosed within a
X"#ifndef __CEXTRACT__", "#endif /* __CEXTRACT__ */" sequence instead.
X.IP "-I\fIdirectory\fR, -include=\fIdirectory\fR"
XAdd the indicated directory to the search path for include files
Xaccessed via the "#include" preprocessor statement.  This flag is
Xpassed on to the C preprocessor.
X.IP "+m, +multi-comments, +multiple-comments"
XIf the -c flag is set, look for a "block" of multiple comments,
Xinstead of a single comment.  Comments with more than one newline in
Xbetween are considered separate. [default off]
X.IP "-N, -roff-mode, -troff-mode"
XEnable documentation mode, sending output as -ms troff format.
X.IP "-n, -doc-mode"
XEnable documentation mode, sending output as normal text.  This is the
Xdefault mode of the \fICDOCNAME\fR program.
X.IP "-o \fIoutfile\fR, -output-file \fIoutfile\fR, -output-file=\fIoutfile\fR"
XSend output to the specified file instead of the standard output.  The
Xfile name need not immediately follow the `\-o' flag, but it must be
Xthe first non-option argument. Warning: This will overwrite any
Xexisting file of the same name.
X.IP "+P, +dual-output"
XIn extraction mode, generate both styles of C prototypes, separated by
Xusing "#ifdef" and "#else" statements to test for __STDC__.  This
Xoption must precede any file arguments. [default on]
X.IP "+p, +ansi-code"
XProduce output in ANSI C prototype format; otherwise, produce
Xold-style declarations.  This option must precede any file arguments.
X[default off]
X.IP "-q\fIfile\fR, -config-file=\fIfile\fR"
XRead in the specified file and parse it for customization commands.
X.IP "-Q#, -read-config=#"
XAn octal digit specifies which configuration files should be read;
X1 for the system configuration file, 2 for the $HOME/NORMRC file and
X4 for the "NORMRC" file in the current directory.  Add values to read
Xmultiple files.  If no number is specified, a 0 is assumed.  This
Xoption must be the very first argument on the command line.  [default
Xvalue of 7 reads all three files]
X.IP "+r, +remove-names, +discard-names"
XStrip out the variable names when sending out the prototype lists.
X.IP "+S, +show-all, +show-anyway"
XIf the -p flag is off, output the prototype list anyway, but enclosed
Xwithin comments. If the -P flag is set, comments and commented
Xprototypes should also be duplicated within the non-ANSI portion of
Xthe output. [default on]
X.IP "+s, +s:none|all|only, +statics, +statics: none|all|only"
XIndicate how static functions are to be treated.  If "none" is chosen,
Xstatic functions will be ignored, if "only" then any non-static
Xfunctions will be ignored, and "any" indicates that all functions will
Xbe included.  If no selection is given, either "any" (`+' flag),  or
X"none" (`-' flag) will be used.
X.IP "-T#, -tab-width=#"
XSpecify the tab width used during documentation output.  If no value
Xis given, or a value of zero is given, tabs are passed though
Xunformatted.
X.IP "-U\fIname\fR, -undefine=\fIname\fR"
XUndefine a macro.  If "-D\fIname\fR" was specified in a previous
Xargument, it is removed from the argument list; otherwise, this option
Xis passed on to the C preprocessor.
X.IP "-V, -settings"
XShow the current settings of the various program options.
X.IP "-v, -version-info"
XDisplay the version number of the program.
X.IP "+W, +break-after-types, +break-types"
XWhen enabled, a newline will be inserted between the function type and
Xthe function name in the function declarations.
X.IP "+w#, +wrap-parameters=#"
XIf the length of the parameter list for a function would cause it to
Xexceed a given number of columns [72 by default], a newline will be
Xinserted in place of a space character, so that the function will not
Xexceed that given length.  The optional number after the command will
Xoverride a negation prefix if encountered.
X.IP "-x, -extract-mode"
XRun \fIcextract\fR or \fICDOCNAME\fR as a prototype extractor.  This is
Xthe default mode for \fIcextract\fR.
X.IP "-Y\fIprogram\fR -cpp-program=\fIprogram\fR"
XSpecify which program to use as the C preprocessor.  This program
Xshould resolve all of the C defines and preprocessor statements while,
Xhopefully, leaving comments intact.
X.IP "+Z, -merge-output"
XCombine the ANSI and K&R C output of the \fIcextract\fR on one line,
Xto create a much more compact header file.
X.SH VMS
XConfiguration files are also supported under VMS.  The default
Xconfiguration files for VMS systems are sys$library:cext.cnf,
Xsys$login:cext.cnf, and cext.cnf.
X.sp
XSince the VMS C compiler strips out comments, the documentation mode
Xand comment options are not very useful.  Using the GNU C preprocessor
Xinstead might be a possible solution.
X.SH COPYRIGHT
XThe code is freely distributable and there are no restrictions other
Xthan the fact that it not be used for monetary gain and that copyright
Xnotices must be kept intact.
X.sp
XBoth \fIcextract\fR and \fICDOCNAME\fR may be used to generate
Xproprietary source code or documentation, but its own source code may
Xnot be used as a part of any proprietary programs.
X.sp
XThe header files and documentation generated by \fIcextract\fR and
X\fICDOCNAME\fR are not subject to this COPYRIGHT notice because they
Xare derived from the source code which was read in by the program to
Xcreate the output.
X.SH FILES
X.IP "SYSCXTRC, $HOME/NORMRC, NORMRC"
XThe list of configuration files, and the order in which they are read
Xin.
X.SH SEE ALSO
Xcc(1), cextrc(5)
X.SH AUTHORS
X.nf
XAdam Bryant
Xadb@cs.bu.edu
X.sp
Xinitial VMS port by John Carr
Xjrcarr@iup.bitnet
X.sp
Xspecial thanks to comp.sources.reviewed reviewers, without whom this
Xprogram would be much less useful.
X.fi
X.SH VMS
XOn VMS systems, only the longer command line options are available,
Xand the '/' character is used to specify command line options.
X.SH BUGS
X1) As far as I know, there is no way to tell the normal VMS C compiler
Xnot to strip out comments.  This renders the comment extraction and
Xdocumentation mode portions rather useless to VMS sites.  Getting the
XGNU C preprocessor for such sites is recommended.
X.sp
X2) Cextract has problems with function pointers and structure
Xdefinitions within the parameter list, using typedefs for such
Xdeclarations is recommended.
X.sp
X3) Does not yet fully support C++ code.
X.sp
X4) It is dependent on the given C preprocessor, so will have any
Xlimitations (such as maximum #defines) which the C preprocessor has.
X.sp
XIf any other bugs are detected, please notify the author.
END_OF_FILE
if test 11153 -ne `wc -c <'cextract.1'`; then
    echo shar: \"'cextract.1'\" unpacked with wrong size!
fi
# end of 'cextract.1'
fi
if test -f 'cextract.doc' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'cextract.doc'\"
else
echo shar: Extracting \"'cextract.doc'\" \(13534 characters\)
sed "s/^X//" >'cextract.doc' <<'END_OF_FILE'
X
X
X
XCEXTRACT(1)              USER COMMANDS                CEXTRACT(1)
X
X
X
XNAME
X     cextract, cextdoc - C prototype/documentation extractor
X
XSYNOPSIS
X     cextract [ -Q# ] [ +AaPpNnxZ ] [ -o ofile ] [  -Hstr  -Yprog
X     -B -b -V -v ] [[ -options ] filename... ]
X
X     cextdoc [ -Q# ] [ +AaNnx ] [ -o outfile ] [ -Yprogram -B  -b
X     -V -v ] [[ -options ] filename... ]
X
XDESCRIPTION
X     The  cextract  program  is  used  to  extract  the  function
X     descriptions  (aka prototypes) from a list of C source files
X     and send them out to the  standard  output  or  a  specified
X     file.   It  may also be used to generate basic documentation
X     for a list of C source files.
X
X     The specific reason this program was written was to  provide
X     a  method of automatically generating header files, contain-
X     ing prototypes, for all of the functions used  throughout  a
X     multi-file project.
X
X     Along with the standard C preprocessing options, -D, -I, and
X     -U,  there are options which allow more control of what form
X     the output will take.
X
X     To allow for conditional processing, cextract  automatically
X     predefines  the  __CEXTRACT__ identifier.  Preprocessor com-
X     mands, such as "#if", "#ifdef" and  "#ifndef"  may  then  be
X     used  to  control  what  code is parsed by cextract.  If the
X     cextdoc command  is  used,  the  program  will  also  define
X     __CEXTDOC__.
X
X     The cextract program also supports the use of  customization
X     files.   A  system configuration file will be read, and then
X     any ".cextrc" file in the user's home directory, and finally
X     any ".cextrc" file in the current directory.  For a descrip-
X     tion of the  format  of  the  customization  file,  see  the
X     cextrc(5) manual page.
X
XCOMMAND LINE OPTIONS
X     The cextract and cextdoc  programs  support  both  long  and
X     short  command  line  options.   Also,  a `+' sign before an
X     option description means that it can be either  on  or  off,
X     with a `+' prefix enabling that option or a `-' prefix disa-
X     bling it.  The prefix of "no-" (or "no") is  also  supported
X     for disabling an option.
X
X     Most command line arguments may be used anywhere on the com-
X     mand  line,  but  a few must be used before any file parsing
X     begins [such as the -N, +Z and -x options], and one can only
X     be the first argument on the command line [the -Q flag].
X
X
X
XSun Release 4.1   Last change: 30 October 1992                  1
X
X
X
X
X
X
XCEXTRACT(1)              USER COMMANDS                CEXTRACT(1)
X
X
X
X     +A, +sort-all
X          Sort the output, listing all functions in  alphabetical
X          order.  This option is not compatible with the +C flag,
X          since functions are sorted over  the  entire  spectrum,
X          not just for each file.
X
X     +a, +sort-by-files
X          Sort the output, listing functions  alphabetically  for
X          each   file.    Since   this  option  sorts  each  file
X          separately, it is compatible with the +C  flag,  unlike
X          the  +A option.  For cextract, the default is to not do
X          any sorting, while the cextdoc default is  to  sort  by
X          files.
X
X     -b, -build-config
X          Automatically build a configuration file in the current
X          directory based on the current program settings.
X
X     -B, -system-build
X          Generate a system wide configuration file based on  the
X          current program settings.
X
X     +C, +first-comments
X          Capture the first comment encountered in each file  and
X          include it in the generated output. [default off]
X
X     +c, +comments, +yank-comments
X          Take the comment  immediately  preceding  the  function
X          declaration  and send it as output along with the func-
X          tion prototype. [default on]
X
X     -Dexpression, -define=expression
X          Define a macro, as per  the  C  "#define"  preprocessor
X          statement.
X
X     +E, +externs
X          Place the string 'extern' before each  function  proto-
X          type. [default on]
X
X     +F, +filename
X          Prepend the name of the file  to  the  initial  comment
X          when  it  is  processed.   This  flag  requires  the +C
X          option. [default off]
X
X     -f%##, -font-%-##
X          Specify what fonts are to be used when generating troff
X          documentation  output.   The  font name is a one or two
X          character troff name which will be interpreted later by
X          the  troff  processor.  Four fonts are used: `1' or `t'
X          which is used only for the title words "Function:"  and
X          "File:"  [default  value  of  "C", Courier]; `2' or `c'
X          which is used for  comments  [default  value  of  "CO",
X
X
X
XSun Release 4.1   Last change: 30 October 1992                  2
X
X
X
X
X
X
XCEXTRACT(1)              USER COMMANDS                CEXTRACT(1)
X
X
X
X          Courier  Oblique];  `3'  or  `n'  which is used for the
X          function name [default value of "B", Times  Bold];  and
X          `4'  or  `p'  for  the parameter list [default value of
X          "R", Times Roman].  Note that the `%'  character  indi-
X          cates  the  type being adjusted, and "##" indicates the
X          one or two character font name.
X
X     -Hstring, -header-string=string
X          During the normal extraction mode, enclose  the  output
X          within the sequence "#ifndef string", "#define string",
X          ..., "#endif /* string */".  This method is  used  with
X          many  system  header files and prevents the header file
X          from being parsed more than once.  If  this  option  is
X          not used, the output will be enclosed within a "#ifndef
X          __CEXTRACT__", "#endif  /*  __CEXTRACT__  */"  sequence
X          instead.
X
X     -Idirectory, -include=directory
X          Add the indicated directory  to  the  search  path  for
X          include  files accessed via the "#include" preprocessor
X          statement.  This flag is passed on to the C  preproces-
X          sor.
X
X     +m, +multi-comments, +multiple-comments
X          If the -c flag is set, look for a "block"  of  multiple
X          comments,  instead  of a single comment.  Comments with
X          more  than  one  newline  in  between  are   considered
X          separate. [default off]
X
X     -N, -roff-mode, -troff-mode
X          Enable documentation mode, sending output as -ms  troff
X          format.
X
X     -n, -doc-mode
X          Enable documentation mode,  sending  output  as  normal
X          text.  This is the default mode of the cextdoc program.
X
X     -o outfile, -output-file outfile, -output-file=outfile
X          Send output to the specified file instead of the  stan-
X          dard output.  The file name need not immediately follow
X          the `-o' flag, but it  must  be  the  first  non-option
X          argument.  Warning:  This  will  overwrite any existing
X          file of the same name.
X
X     +P, +dual-output
X          In extraction mode, generate both styles  of  C  proto-
X          types,  separated  by using "#ifdef" and "#else" state-
X          ments to test for __STDC__.  This option  must  precede
X          any file arguments. [default on]
X
X     +p, +ansi-code
X          Produce output in ANSI C prototype  format;  otherwise,
X
X
X
XSun Release 4.1   Last change: 30 October 1992                  3
X
X
X
X
X
X
XCEXTRACT(1)              USER COMMANDS                CEXTRACT(1)
X
X
X
X          produce  old-style declarations.  This option must pre-
X          cede any file arguments.  [default off]
X
X     -qfile, -config-file=file
X          Read in the specified file and parse it for  customiza-
X          tion commands.
X
X     -Q#, -read-config=#
X          An octal  digit  specifies  which  configuration  files
X          should  be read; 1 for the system configuration file, 2
X          for the $HOME/.cextrc file and 4 for the ".cextrc" file
X          in  the current directory.  Add values to read multiple
X          files.  If no number is  specified,  a  0  is  assumed.
X          This option must be the very first argument on the com-
X          mand line.  [default value of 7 reads all three files]
X
X     +r, +remove-names, +discard-names
X          Strip out the variable names when sending out the  pro-
X          totype lists.
X
X     +S, +show-all, +show-anyway
X          If the -p flag is off, output the prototype  list  any-
X          way,  but  enclosed  within comments. If the -P flag is
X          set, comments and commented prototypes should  also  be
X          duplicated  within  the non-ANSI portion of the output.
X          [default on]
X
X     +s, +s:none|all|only, +statics, +statics: none|all|only
X          Indicate how static functions are to  be  treated.   If
X          "none"  is chosen, static functions will be ignored, if
X          "only" then any non-static functions will  be  ignored,
X          and   "any"   indicates  that  all  functions  will  be
X          included.  If no selection is given, either "any"  (`+'
X          flag),  or "none" (`-' flag) will be used.
X
X     -T#, -tab-width=#
X          Specify the tab width used during documentation output.
X          If no value is given, or a value of zero is given, tabs
X          are passed though unformatted.
X
X     -Uname, -undefine=name
X          Undefine a macro.  If "-Dname" was specified in a  pre-
X          vious  argument,  it is removed from the argument list;
X          otherwise, this option is passed on to the C preproces-
X          sor.
X
X     -V, -settings
X          Show  the  current  settings  of  the  various  program
X          options.
X
X     -v, -version-info
X          Display the version number of the program.
X
X
X
XSun Release 4.1   Last change: 30 October 1992                  4
X
X
X
X
X
X
XCEXTRACT(1)              USER COMMANDS                CEXTRACT(1)
X
X
X
X     +W, +break-after-types, +break-types
X          When enabled, a newline will be  inserted  between  the
X          function  type  and  the  function name in the function
X          declarations.
X
X     +w#, +wrap-parameters=#
X          If the length of the  parameter  list  for  a  function
X          would  cause it to exceed a given number of columns [72
X          by default], a newline will be inserted in place  of  a
X          space  character,  so that the function will not exceed
X          that given length.  The optional number after the  com-
X          mand will override a negation prefix if encountered.
X
X     -x, -extract-mode
X          Run cextract or cextdoc as a prototype extractor.  This
X          is the default mode for cextract.
X
X     -Yprogram -cpp-program=program
X          Specify which program to use  as  the  C  preprocessor.
X          This  program  should  resolve all of the C defines and
X          preprocessor statements while, hopefully, leaving  com-
X          ments intact.
X
X     +Z, -merge-output
X          Combine the ANSI and K&R C output of  the  cextract  on
X          one line, to create a much more compact header file.
X
XVMS
X     Configuration files  are  also  supported  under  VMS.   The
X     default    configuration   files   for   VMS   systems   are
X     sys$library:cext.cnf, sys$login:cext.cnf, and cext.cnf.
X
X     Since the VMS C compiler strips out comments, the documenta-
X     tion  mode  and  comment options are not very useful.  Using
X     the GNU C preprocessor instead might be a possible solution.
X
XCOPYRIGHT
X     The code is freely distributable and there are  no  restric-
X     tions  other  than the fact that it not be used for monetary
X     gain and that copyright notices must be kept intact.
X
X     Both  cextract  and  cextdoc  may  be   used   to   generate
X     proprietary source code or documentation, but its own source
X     code may not be used as a part of any proprietary programs.
X
X     The header files and documentation generated by cextract and
X     cextdoc  are  not  subject  to this COPYRIGHT notice because
X     they are derived from the source code which was read  in  by
X     the program to create the output.
X
XFILES
X     /usr/local/lib/cext.config, $HOME/.cextrc, .cextrc
X
X
X
XSun Release 4.1   Last change: 30 October 1992                  5
X
X
X
X
X
X
XCEXTRACT(1)              USER COMMANDS                CEXTRACT(1)
X
X
X
X          The list of configuration files, and the order in which
X          they are read in.
X
XSEE ALSO
X     cc(1), cextrc(5)
X
XAUTHORS
X     Adam Bryant
X     adb@cs.bu.edu
X
X     initial VMS port by John Carr
X     jrcarr@iup.bitnet
X
X     special thanks to comp.sources.reviewed reviewers, without whom this
X     program would be much less useful.
X
XVMS
X     On VMS systems, only the longer  command  line  options  are
X     available,  and the '/' character is used to specify command
X     line options.
X
XBUGS
X     1) As far as I know, there is no way to tell the normal  VMS
X     C compiler not to strip out comments.  This renders the com-
X     ment extraction and documentation mode portions rather  use-
X     less  to VMS sites.  Getting the GNU C preprocessor for such
X     sites is recommended.
X
X     2) Cextract has problems with function pointers  and  struc-
X     ture  definitions  within the parameter list, using typedefs
X     for such declarations is recommended.
X
X     3) Does not yet fully support C++ code.
X
X     4) It is dependent on the given C preprocessor, so will have
X     any  limitations  (such  as  maximum  #defines)  which the C
X     preprocessor has.
X
X     If any other bugs are detected, please notify the author.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
XSun Release 4.1   Last change: 30 October 1992                  6
X
X
X
END_OF_FILE
if test 13534 -ne `wc -c <'cextract.doc'`; then
    echo shar: \"'cextract.doc'\" unpacked with wrong size!
fi
# end of 'cextract.doc'
fi
if test -f 'cextract.hlp' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'cextract.hlp'\"
else
echo shar: Extracting \"'cextract.hlp'\" \(11297 characters\)
sed "s/^X//" >'cextract.hlp' <<'END_OF_FILE'
X1 CEXTRACT
X
X  CEXTRACT is a program which will extract C prototypes from source
X  code and then generate a header file or documentation file listing
X  those functions which were encountered.
X
X  The extraction mode is ideal for building header files for multiple
X  source projects, and the documentation mode is useful in helping
X  write documentation for such projects.  [Note: due to limitations in
X  the VAX compiler the comment extraction routines may not be
X  available on your system.  This would cause the documentation mode
X  to be mostly inoperable.]
X
X  Format:
X
X    CEXTRACT [/OPTIONS] file-name ...
X
X2 Parameter
X
X    file-name ...
X
X  Specify the list of files to be parsed by cextract.  Any parameter
X  not beginning with a '/', '-', or a '+' is interpreted as a file
X  name; the others will be parsed as command qualifiers.
X
X
X2 Command_Qualifiers
X
X  Command qualifiers may be prefixed by either a '/', '-' or a '+'.
X  If a '-' precedes a command qualifier, that option will be disabled,
X  if appropriate, otherwise, it will be enabled.  Also, a "no" or
X  "no-" may also be used to indicate negation.
X
X
X/ANSI-CODE
X
X /ANSI-CODE                                     (default disabled)
X /NOANSI-CODE
X
X If in extraction mode, with dual-output and merge-output disabled,
X the output should be in ANSI C format.
X
X/BREAK-AFTER-TYPES
X
X /BREAK-TYPES					(default disabled)
X /BREAK-AFTER-TYPES
X /NOBREAK-TYPES
X /NOBREAK-AFTER-TYPES
X
X When enabled, a newline will be inserted between the function type
X and the function name in the function declarations.
X
X/BUILD-CONFIG
X
X Generate a configuration file in the current directory based on the
X current program settings.
X
X/COMMENTS
X
X /COMMENTS                                      (default disabled)
X /NOCOMMENTS
X /YANK-COMMENTS
X /NOYANK-COMMENTS
X
X Capture the comment immediately preceding the function definition and
X use it as a description of that function.
X
X/CONFIG-FILE
X
X /CONFIG-FILE=file_name
X
X Read in the indicated file and parse it for configuration commands.
X
X/CPP-PROGRAM
X
X /CPP-PROGRAM=program_name
X
X Specify which program is to be used as a C preprocessor.  This
X program should resolve all C defines and preprocessor statements
X while, hopefully, leaving all of the comments in place.  Note that
X the default VMS C preprocessor is known to remove the comments, so
X finding an alternative is recommended.
X
X/DOC-MODE
X
X /DOC-MODE                                      (default for cextdoc)
X
X Format the output as a normal text documentation file.
X
X/DEFINE
X
X /DEFINE=expression
X
X This option defines a macro by passing it on to the C preprocessor.
X
X/DUAL-OUTPUT
X
X /DUAL-OUTPUT                                   (default enabled)
X /NODUAL-OUTPUT
X
X Generate both ANSI C and K&R C output when in extraction mode.  The
X two styles will be separated using "#if __STDC__", "#else", and
X "#endif" constructs.  This option may be overridden by the
X merge-output option.
X
X/EXTERNS
X
X /EXTERNS                                       (default enabled)
X /NOEXTERNS
X
X Prepend an extern to each function prototype before output.
X
X/EXTRACT-MODE
X
X /EXTRACT-MODE                                  (default mode for cextract)
X
X Extract the prototypes to build a header file for the functions.
X
X/FIRST-COMMENTS
X
X /FIRST-COMMENTS                                (default disabled)
X /NOFIRST-COMMENTS
X  
X Capture the first comment encountered in each file and include it as
X part of the output.
X
X/FILENAME
X
X /FILENAME                                      (default disabled)
X /NOFILENAME
X /PREPEND-FILENAME
X /NOPREPEND-FILENAME
X
X If the first_comments option is enabled, prepend the name of the file
X to the comment.
X
X/FONT
X
X /FONT_1_%%                                     (default="C", Courier)
X /FONT_T_%%
X
X Specify the title font for troff-mode output.
X
X /FONT_2_%%                                     (default="CO", Courier Oblique)
X /FONT_C_%%
X
X Specify the comment font for troff-mode output.
X
X /FONT_3_%%                                     (default="B", Times Bold)
X /FONT_N_%%
X
X Specify the function name font for troff-mode output.
X
X /FONT_4_%%                                     (default="R", Times Roman)
X /FONT_P_%%
X
X Specify the parameter list font for troff-mode output.
X
X/HEADER-STRING
X
X /HEADER-STRING=string                          (default disabled)
X
X Specify a string to be used as an indicator for file inclusion.  This
X will cause the extraction mode output to be enclosed within the
X construct:
X
X        #ifndef string
X        #define string
X
X         /*... output ...*/
X
X        #endif /* string */
X
X This technique is used in many system header files to assure that the
X header file is not "#included" more than once.  If not enabled, the
X output will be enclosed within the construct:
X
X        #ifndef __CEXTRACT__
X
X         /*... output ...*/
X
X        #endif /* __CEXTRACT__ */
X
X/INCLUDE
X
X /INCLUDE=directory
X
X Specify a directory to be added to the include file search path.
X This qualifier is passed on to the C preprocessor.
X
X/MERGE-OUTPUT
X
X /MERGE-OUTPUT                                  (default disabled)
X /NOMERGE-OUTPUT
X
X In extraction mode, generate the prototypes enclosed within a macro
X so that both the ANSI C and K&R C declarations are handled on the
X same line.  This option overrides both the dual-output and ansi-code
X option settings.
X
X/MULTIPLE-COMMENTS
X
X /MULTI-COMMENTS                                (default disabled)
X /NOMULTI-COMMENTS
X /MULTIPLE-COMMENTS
X /NOMULTIPLE-COMMENTS 
X
X When extracting comments, assume that consecutive comments are
X actually a single comment.  This allows for coding styles which make
X use of "block" comments.
X
X/OUTPUT-FILE
X
X /OUTPUT-FILE=file_name                         (default=terminal)
X
X Specify a file to which output should be sent.  If no file name is
X specified as part of the qualifier, the first non-qualifier is used
X as the name of the output file.
X
X/READ-CONFIG
X
X /READ-CONFIG=#                                 (default=7)
X
X Specify an octal digit representing which configuration files should
X or should not be read.  The system file is 1, the file in the user's
X default directory is 2, and the file in the current directory is 4.
X Add the numbers together to read in multiple configuration files.  If
X no number is specified a zero is assumed.
X
X/REMOVE-NAMES
X
X /REMOVE-NAMES					(default disabled)
X /NOREMOVE-NAMES
X /DISCARD-NAMES
X /NODISCARD-NAMES
X
X Do not display the variable names in the prototype output.
X
X/ROFF-MODE
X
X /ROFF-MODE                                     (this mode is not a default)
X /TROFF-MODE
X
X Generate documentation output, and use a UNIX -ms troff format.  This
X will probably not prove too useful on a VMS system.
X
X/SETTINGS
X
X Show all of the configuration settings.  This is very useful for
X determining if a configuration file is working properly.
X
X/SHOW-ALL
X
X /SHOW-ALL                                      (default enabled)
X /NOSHOW-ALL
X /SHOW-ANYWAY
X /NOSHOW-ANYWAY
X
X If any output in K&R C is generated, that output should include the
X ANSI C prototypes enclosed within comments.
X
X/SINGLE-COMMENTS
X
X /SINGLE-COMMENTS                               (default enabled)
X /NOSINGLE-COMMENTS
X
X When extracting comments, do not search for multi-line comments.
X
X/SORT
X
X /SORT-ALL                                      (default=NOSORT)
X /SORT-BY-FILES
X /NOSORT
X
X Specify a sorting method for the functions.  Sort alphabetically
X either over all of the functions, over each file, or not at all.
X
X/STATICS
X
X /STATICS                                       (default disabled)
X /NOSTATICS                                     (enabled for cextdoc)
X /STATICS=NONE
X /STATICS=ANY
X /STATICS=ONLY
X
X Set how static variables should be treated by the program.  By
X default, they are excluded from searches, but they may also be either
X included with non-statics, or searched for alone.  Using these
X options you can determine whether the header file is for an entire
X program or library, or just for a single file.
X
X/SYSTEM-BUILD
X
X Generate the system configuration file based on the current program
X settings.
X
X/TAB-WIDTH
X
X /TAB-WIDTH=width                               (default=0)
X
X Specify a numeric width for the tab setting during conversion of tabs
X to spaces for documentation generation.  A setting of 0 means to not
X perform any conversion.
X
X/UNDEFINE
X
X /UNDEFINE=macro
X
X Specify a macro to undefine when calling the C preprocessor.
X
X/VERSION-INFO
X
X /VERSION-INFO
X
X Display the version information for the program.
X
X/WRAP-PARAMETERS
X
X /WRAP-PARAMETERS				(default disabled)
X /NOWRAP-PARAMETERS
X
X If the length of the parameter list for a function would cause it to
X exceed a given number of columns [72 by default], a newline will be
X inserted in place of a space character, so that the function will not
X exceed that given length.  The optional number after the command will
X override a negation prefix if encountered.
X
X
X2 Customization Files
X
X  CEXTRACT has support for customization files which are read at
X  startup, before the qualifiers are checked, or whenever specified by
X  the /CONFIG-FILE qualifier.
X
X  Configuration files are checked for (on most VMS systems) in the
X  following locations:
X
X     sys$library:cext.cnf	- the system configuration file
X     sys$login:cext.cnf		- the initial directory upon login
X     cext.cnf			- the current directory
X
X  The file should be a normal text file, with each customization
X  command on a separate line.  Blank lines, and any line beginning
X  with a "#" will be ignored.  All commands should be in lowercase.
X
X  Any command preceded by the string "doc-only " will only be used
X  during the documentation mode, and any command preceded by
X  "extract-only " will only be used during the extraction mode.
X
X  Commands which are preceded by either a "!", the string "no", or
X  the string "no-" will be interpreted as disabling that option, if
X  appropriate.
X
X  The supported commands include all of the command qualifiers
X  (without the preceding '/', of course), except for the "read-config"
X  command, which is unsupported for obvious reasons.
X
X  In addition to the command qualifiers, the "replace" command is
X  supported to allow for the replacement of types, variables or
X  type-variable combinations after a "#define" has been expanded.
X
X  The format of the replace command is:
X
X     replace [type/variable/all] "string1" "string2"
X
X  As an example, the default replacement of FILE usually has the
X  format:
X
X     replace type "struct _iobuf" "FILE"
X
X  The varargs system is also replaced using this command.
X
X2 Examples
X
X  CEXTRACT FILEA.C
X
X  Extract the function prototypes in the default extraction format from
X  the C source file FILEA.C.
X
X  CEXTDOC FILEA.C FILEB.C
X
X  Extract the function prototypes in a normal documentation format from
X  the C source files FILEA.C and FILEB.C.
X
X  CEXTRACT /TROFF-MODE FILEA.C FILEB.C
X
X  Extract the function prototypes in a troff documentation format from
X  the C source files FILEA.C and FILEB.C.  Probably useless on a VMS
X  system.
X
X  CEXTRACT /SETTINGS
X
X  Find out what all of the default settings are.  This will show what
X  the normal environment is.
X
X  CEXTRACT /READ-CONFIG /DUAL-OUTPUT FILEA.C
X
X  Extract the function prototypes assuring that the configuration
X  files are not read in.  Also assure that both K&R and ANSI C output
X  will be used.
END_OF_FILE
if test 11297 -ne `wc -c <'cextract.hlp'`; then
    echo shar: \"'cextract.hlp'\" unpacked with wrong size!
fi
# end of 'cextract.hlp'
fi
if test -f 'cextrc.doc' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'cextrc.doc'\"
else
echo shar: Extracting \"'cextrc.doc'\" \(9703 characters\)
sed "s/^X//" >'cextrc.doc' <<'END_OF_FILE'
X
X
X
XCEXTRC(5)                 FILE FORMATS                  CEXTRC(5)
X
X
X
XNAME
X     cextrc - C prototype/documentation  extractor  customization
X     file format
X
XSYNOPSIS
X     .cextrc
X
XDESCRIPTION
X     The programs cextract(1)  and  cextdoc(1)  extract  function
X     prototypes from C source code and create header and documen-
X     tation files respectively.  The .cextrc customization  files
X     allow  users to specify which options are set for those pro-
X     grams, without having to always use the command line.
X
X     The configuration files are read prior to the parsing of the
X     command  line  options, as well as whenever the `-q' flag is
X     encountered.
X
XFORMAT
X     The file should be a normal text file, with each  customiza-
X     tion  command  on a separate line.  Blank lines and any line
X     beginning with a `#' will be ignored.
X
X     Any command preceded by the string "doc-only " will only  be
X     used  in  documentation  mode,  and  any command preceded by
X     "extract-only " will only be used in extraction mode.
X
X     Commands which are preceded by either a `!'  or  the  string
X     "no-"  or "no" will be interpreted as disabling that option,
X     if appropriate.
X
XCOMMANDS
X     The full list of configuration commands is given below.
X
X     ansi-code
X          If dual-output and merge-output modes are not  enabled,
X          produce output in ANSI C format, with full prototyping.
X          This command does not do anything when used in documen-
X          tation mode.
X
X     break-after-types
X
X     break-types
X          When enabled, a newline will be  inserted  between  the
X          function  type  and  the  function name in the function
X          declarations.
X
X     comments
X
X     yank-comments
X          Extract the comment  immediately  before  the  function
X          definition, and display it upon output.
X
X
X
XSun Release 4.1   Last change: 3 September 1992                 1
X
X
X
X
X
X
XCEXTRC(5)                 FILE FORMATS                  CEXTRC(5)
X
X
X
X     config-file: file
X          Read in the specified file and parse it for  configura-
X          tion commands.
X
X     cpp-program: program
X          Specify which program is to be used as a  C  preproces-
X          sor.   This  program  should  resolve all C defines and
X          while, hopefully, leaving the comments intact.
X
X     doc-mode
X          Enable documentation  mode  with  normal  text  output.
X          This is the default setting for cextdoc(1).
X
X     define: expression
X          Pass the specified expression  to  the  C  preprocessor
X          with  a  "-D"  string prepended to it.  This command is
X          equivalent to the `-D' command line option.
X
X     dual-output
X          Provide  output  in  both  ANSI  and  K&R  C   formats,
X          separated by an "#if __STDC__" ... "#else" ... "#endif"
X          construct.  This command does not do anything when used
X          in  documentation mode or if the merge-output option is
X          enabled.
X
X     externs
X          Prepend an "extern" to each function  description  upon
X          output.
X
X     extract-mode
X          Enable extraction mode and generate output which can be
X          used as a C header file defining the prototypes for all
X          of the functions which are  encountered.   The  is  the
X          default mode for cextract(1).
X
X     first-comments
X          Include in the output the initial  comment  encountered
X          in each file.
X
X     filename
X
X     prepend-filename
X          If the "first-comments" option is enabled, prepend  the
X          name of each file to the output of initial comments.
X
X     font % ##
X          Assign a troff font "##" to a given font type `%', when
X          using  troff  documentation  mode.   The  possible font
X          types are `1' or `t', `2' or `c', `3' or `n',  and  `4'
X          or `p' for the title, comment, name, and parameter list
X          respectively.  The troff font "##" is a normal  one  or
X          two  character  troff  font,  such  as "CO" for Courier
X
X
X
XSun Release 4.1   Last change: 3 September 1992                 2
X
X
X
X
X
X
XCEXTRC(5)                 FILE FORMATS                  CEXTRC(5)
X
X
X
X          Oblique.
X
X     header-string: string
X          When in extraction  mode,  enclose  the  output  within
X          preprocessor  directives  testing for the definition of
X          string.  This method is used with  many  system  header
X          files,  to  insure  that  they are not "#include"d more
X          than once.  If this option is not used, the output will
X          be enclosed within a "#ifndef __CEXTRACT__", "#endif /*
X          __CEXTRACT__ */" sequence instead.
X
X     include: directory
X          Pass the specified directory to the C preprocessor with
X          a  "-I"  string  prepended  to  it.   This  command  is
X          equivalent to the `-I' command-line option.
X
X     merge-output
X          Merge the ANSI and K&R output into  a  single  line  of
X          output  to make it take up less space.  A macro is used
X          to expand the parameter list for ANSI compilers.   This
X          option  overrides  both  the  dual-output and ansi-code
X          options.  There is no affect if the documentation  mode
X          is enabled.
X
X     multi-comments
X
X     multiple-comments
X          When extracting comments, assume that consecutive  com-
X          ments  are  actually  one  single comment.  This allows
X          people that place comment delimiters at  the  beginning
X          and  end  of  each line to have their comments properly
X          captured.
X
X     output-file: outfile
X          Store the output in the specified file.
X
X     replace
X          Replace the first  string  which  matches  a  variable,
X          type,  or  both  (as  selected) with the second string.
X          The format is:
X               replace [all/type/variable] "string1" "string2"
X          For example, on  Sun  machines,  the  automatic  "FILE"
X          replacement could be accomplished using a command like:
X               replace type "struct _iobuf" "FILE"
X          However, this should not need  to  be  entered  by  the
X          average  user since it is handled automatically by cex-
X          tract(1), as is the varargs system.
X
X     remove-names
X
X     discard-names
X          Remove variable names from the prototype list prior  to
X
X
X
XSun Release 4.1   Last change: 3 September 1992                 3
X
X
X
X
X
X
XCEXTRC(5)                 FILE FORMATS                  CEXTRC(5)
X
X
X
X          output.
X
X     roff-mode
X
X     troff-mode
X          Enable documentation mode with troff -ms format output.
X          This  option  is overridden by the doc-mode or extract-
X          mode options.
X
X     show-all
X
X     show-anyway
X          When output is K&R C, display prototypes  in  comments.
X          When  dual-output is enabled, display comments and pro-
X          totypes in both sections; otherwise,  display  comments
X          and prototypes only in the ANSI C portion.  This option
X          does nothing in documentation mode.
X
X     single-comments
X          When extracting comments from a  file,  take  only  one
X          comment,   discarding  all  preceding  comments.   This
X          option is the reverse of the multi-comments option.
X
X     sort-all
X          Alphabetically sort all of the functions  from  all  of
X          the files before generating output.
X
X     sort-by-files
X          For each file processed,  sort  all  of  the  functions
X          prior to output.
X
X     statics
X
X     statics: none
X
X     statics: any
X
X     statics: only
X          Select the method for how static  functions  should  be
X          treated.   If  "none"  is  selected,  statics  will  be
X          ignored.  If "only" is selected,  non-static  functions
X          will  be  ignored.   Finally,  "any" indicates that all
X          functions will be extracted.  If no selection is  made,
X          it  will  be  the  same  as  selecting "any" or (with a
X          preceding `!') "none".
X
X     tab-width: width
X          Set the tab width to be an integer number width.   This
X          works only during documentation generation.
X
X     undefine: name
X          Undefine any previously  defined  macro.   If  none  is
X
X
X
XSun Release 4.1   Last change: 3 September 1992                 4
X
X
X
X
X
X
XCEXTRC(5)                 FILE FORMATS                  CEXTRC(5)
X
X
X
X          encountered,  pass  the  specified  expression to the C
X          preprocessor with a "-U" string prepended to it.   This
X          command is equivalent to the `-U' command-line option.
X
X     wrap-parameters: #
X          If the length of the  parameter  list  for  a  function
X          would  cause it to exceed a given number of columns [72
X          by default], a newline will be inserted in place  of  a
X          space  character,  so that the function will not exceed
X          that given length.  The optional number after the  com-
X          mand will override a negation prefix if encountered.
X
XFILES
X     /usr/local/lib/cext.config, $HOME/.cextrc, .cextrc
X          configuration files.
X
XVMS
X     Configuration files  are  also  supported  under  VMS.   The
X     default    configuration   files   for   VMS   systems   are
X     sys$library:cext.cnf, sys$login:cext.cnf, and cext.cnf.
X
X     Since the VMS C compiler strips out comments, the documenta-
X     tion  mode  and  comment options are not very useful.  Using
X     the GNU C preprocessor instead might be a possible solution.
X
XSEE ALSO
X     cextract(1), cextdoc(1)
X
XAUTHOR
X     Adam Bryant
X     adb@bu.edu
X
X     initial VMS port by John Carr
X     jrcarr@iup.bitnet
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
XSun Release 4.1   Last change: 3 September 1992                 5
X
X
X
END_OF_FILE
if test 9703 -ne `wc -c <'cextrc.doc'`; then
    echo shar: \"'cextrc.doc'\" unpacked with wrong size!
fi
# end of 'cextrc.doc'
fi
echo shar: End of archive 2 \(of 5\).
cp /dev/null ark2isdone
MISSING=""
for I in 1 2 3 4 5 ; do
    if test ! -f ark${I}isdone ; then
	MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 5 archives.
    rm -f ark[1-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0

exit 0 # Just in case...
-- 
        Andrew Patrick acting as Comp.Sources.Reviewed Moderator
              Department of Communications, Ottawa, CANADA
                         csr@calvin.dgbt.doc.CA