home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 October / usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso / reviewed / volume01 / cextract / part01 / cextract.hlp < prev    next >
Text File  |  1991-07-08  |  9KB  |  337 lines
  1. 1 CEXTRACT
  2.  
  3.   CEXTRACT is a program which will extract C prototypes from source
  4.   code and then generate a header file or documentation file listing
  5.   those functions which were encountered.
  6.  
  7.   The extraction mode is ideal for building header files for multiple
  8.   source projects, and the documentation mode is useful in helping
  9.   write documentation for such projects.  [Note: due to limitations in
  10.   the VAX compiler the comment extraction routines may not be
  11.   available on your system.  This would make the documentation mode
  12.   mostly inoperable.]
  13.  
  14.   Format:
  15.  
  16.     CEXTRACT [/OPTIONS] file-name ...
  17.  
  18. 2 Parameter
  19.  
  20.     file-name ...
  21.  
  22.   Specify the list of files to be parsed by cextract.  Any parameter
  23.   not beginning with a '/', '-', or a '+' is interpreted as a file
  24.   name; the others will be parsed as command qualifiers.
  25.  
  26.  
  27. 2 Command_Qualifiers
  28.  
  29.   Command qualifiers may be prefixed by either a '/', '-' or a '+'.
  30.   If a '-' precedes a command qualifier, that option will be disabled,
  31.   if appropriate, otherwise, it will be enabled.
  32.  
  33.  
  34. /ANSI-CODE
  35.  
  36.  /ANSI-CODE                                     (default disabled)
  37.  /NOANSI-CODE
  38.  
  39.  If in extraction mode, with dual-output disabled, the output should
  40.  be in ANSI C format.
  41.  
  42. /COMMENTS
  43.  
  44.  /COMMENTS                                      (default disabled)
  45.  /NOCOMMENTS
  46.  /YANK-COMMENTS
  47.  /NOYANK-COMMENTS
  48.  
  49.  Capture the comment immediately preceding the function definition and
  50.  use it as a description of that function.
  51.  
  52. /CONFIG-FILE
  53.  
  54.  /CONFIG-FILE=file_name
  55.  
  56.  Read in the indicated file and parse it for configuration commands.
  57.  
  58. /DOC-MODE
  59.  
  60.  /DOC-MODE                                      (default for cextdoc)
  61.  
  62.  Format the output as a normal text documentation file.
  63.  
  64. /DEFINE
  65.  
  66.  /DEFINE=expression
  67.  
  68.  This option defines a macro by passing it on to the C preprocessor.
  69.  
  70. /DUAL-OUTPUT
  71.  
  72.  /DUAL-OUTPUT                                   (default enabled)
  73.  /NODUAL-OUTPUT
  74.  
  75.  Generate both ANSI C and K&R C output when in extraction mode.  The
  76.  two styles will be separated using "#ifdef __STDC__" constructs.
  77.  
  78. /EXTERNS
  79.  
  80.  /EXTERNS                                       (default enabled)
  81.  /NOEXTERNS
  82.  
  83.  Prepend an extern to each function prototype before output.
  84.  
  85. /EXTRACT-MODE
  86.  
  87.  /EXTRACT-MODE                                  (default mode for cextract)
  88.  
  89.  Extract the prototypes to build a header file for the functions.
  90.  
  91. /FIRST-COMMENTS
  92.  
  93.  /FIRST-COMMENTS                                (default disabled)
  94.  /NOFIRST-COMMENTS
  95.   
  96.  Capture the first comment encountered in each file and include it as
  97.  part of the output.
  98.  
  99. /FILENAME
  100.  
  101.  /FILENAME                                      (default disabled)
  102.  /NOFILENAME
  103.  /PREPEND-FILENAME
  104.  /NOPREPEND-FILENAME
  105.  
  106.  If the first_comments option is enabled, prepend the name of the file
  107.  to the comment.
  108.  
  109. /FONT
  110.  
  111.  /FONT_1_%%                                     (default="C", Courier)
  112.  /FONT_T_%%
  113.  
  114.  Specify the title font for troff-mode output.
  115.  
  116.  /FONT_2_%%                                     (default="CO", Courier Oblique)
  117.  /FONT_C_%%
  118.  
  119.  Specify the comment font for troff-mode output.
  120.  
  121.  /FONT_3_%%                                     (default="B", Times Bold)
  122.  /FONT_N_%%
  123.  
  124.  Specify the function name font for troff-mode output.
  125.  
  126.  /FONT_4_%%                                     (default="R", Times Roman)
  127.  /FONT_P_%%
  128.  
  129.  Specify the parameter list font for troff-mode output.
  130.  
  131. /HEADER-STRING
  132.  
  133.  /HEADER-STRING=string                          (default disabled)
  134.  
  135.  Specify a string to be used as an indicator for file inclusion.  This
  136.  will cause the extraction mode output to be enclosed within the
  137.  construct:
  138.  
  139.         #ifndef string
  140.         #define string
  141.  
  142.          /*... output ...*/
  143.  
  144.         #endif /* string */
  145.  
  146.  This technique is used in many system header files to assure that the
  147.  header file is not "#included" more than once.  If not enabled, the
  148.  output will be enclosed within the construct:
  149.  
  150.         #ifndef __CEXTRACT__
  151.  
  152.          /*... output ...*/
  153.  
  154.         #endif /* __CEXTRACT__ */
  155.  
  156. /INCLUDE
  157.  
  158.  /INCLUDE=directory
  159.  
  160.  Specify a directory to be added to the include file search path.
  161.  This qualifier is passed on to the C preprocessor.
  162.  
  163. /MULTIPLE-COMMENTS
  164.  
  165.  /MULTI-COMMENTS                                (default disabled)
  166.  /NOMULTI-COMMENTS
  167.  /MULTIPLE-COMMENTS
  168.  /NOMULTIPLE-COMMENTS 
  169.  
  170.  When extracting comments, assume that consecutive comments are
  171.  actually a single comment.  This allows for coding styles which make
  172.  use of "block" comments.
  173.  
  174. /OUTPUT-FILE
  175.  
  176.  /OUTPUT-FILE=file_name                         (default=terminal)
  177.  
  178.  Specify a file to which output should be sent.  If no file name is
  179.  specified as part of the qualifier, the first non-qualifier is used
  180.  as the name of the output file.
  181.  
  182. /READ-CONFIG
  183.  
  184.  /READ-CONFIG=#                                 (default=7)
  185.  
  186.  Specify an octal digit representing which configuration files should
  187.  or should not be read.  The system file is 1, the file in the user's
  188.  default directory is 2, and the file in the current directory is 4.
  189.  Add the numbers together to read in multiple configuration files.  If
  190.  no number is specified a zero is assumed.
  191.  
  192. /REMOVE-NAMES
  193.  
  194.  /REMOVE-NAMES                    (default disabled)
  195.  /NOREMOVE-NAMES
  196.  /DISCARD-NAMES
  197.  /NODISCARD-NAMES
  198.  
  199.  Do not display the variable names in the prototype output.
  200.  
  201. /ROFF-MODE
  202.  
  203.  /ROFF-MODE                                     (this mode is not a default)
  204.  /TROFF-MODE
  205.  
  206.  Generate documentation output, and use a UNIX -ms troff format.  This
  207.  will probably not prove too useful on a VMS system.
  208.  
  209. /SETTINGS
  210.  
  211.  Show all of the configuration settings.  This is very useful for
  212.  determining if a configuration file is working properly.
  213.  
  214. /SHOW-ALL
  215.  
  216.  /SHOW-ALL                                      (default enabled)
  217.  /NOSHOW-ALL
  218.  /SHOW-ANYWAY
  219.  /NOSHOW-ANYWAY
  220.  
  221.  If any output in K&R C is generated, that output should include the
  222.  ANSI C prototypes enclosed within comments.
  223.  
  224. /SINGLE-COMMENTS
  225.  
  226.  /SINGLE-COMMENTS                               (default enabled)
  227.  /NOSINGLE-COMMENTS
  228.  
  229.  When extracting comments, do not search for multi-line comments.
  230. /SORT
  231.  
  232.  /SORT-ALL                                      (default=NOSORT)
  233.  /SORT-BY-FILES
  234.  /NOSORT
  235.  
  236.  Specify a sorting method for the functions.  Sort alphabetically
  237.  either over all of the functions, over each file, or not at all.
  238.  
  239. /STATICS
  240.  
  241.  /STATICS                                       (default disabled)
  242.  /NOSTATICS                                     (enabled for cextdoc)
  243.  
  244.  When searching for functions, do not discard static functions.
  245.  
  246. /TAB-WIDTH
  247.  
  248.  /TAB-WIDTH=width                               (default=0)
  249.  
  250.  Specify a numeric width for the tab setting during conversion of tabs
  251.  to spaces for documentation generation.  A setting of 0 means to not
  252.  perform any conversion.
  253.  
  254. /UNDEFINE
  255.  
  256.  /UNDEFINE=macro
  257.  
  258.  Specify a macro to undefine when calling the C preprocessor.
  259.  
  260. /VERSION-INFO
  261.  
  262.  /VERSION-INFO
  263.  
  264.  Display the version information for the program.
  265.  
  266. 2 Customization Files
  267.  
  268.   CEXTRACT has support for customization files which are read at
  269.   startup, before the qualifiers are checked, or whenever specified by
  270.   the /CONFIG-FILE qualifier.
  271.  
  272.   Configuration files are checked for (on most VMS systems) in the
  273.   following locations:
  274.  
  275.      sys$library:cext.cnf    - the system configuration file
  276.      sys$login:cext.cnf        - the initial directory upon login
  277.      cext.cnf            - the current directory
  278.  
  279.   The file should be a normal text file, with each customization
  280.   command on a separate line.  Blank lines, and any line beginning
  281.   with a "#" will be ignored.  All commands should be in lowercase.
  282.  
  283.   Any command preceded by the string "doc-only " will only be used
  284.   during the documentation mode, and any command preceded by
  285.   "extract-only " will only be used during the extraction mode.
  286.  
  287.   Commands which are preceded by either a "!" or the string "no"
  288.   be interpreted as disabling that option, if appropriate.
  289.  
  290.   The supported commands include all of the command qualifiers
  291.   (without the preceding '/', of course), except for the "read-config"
  292.   command, which is unsupported for obvious reasons.
  293.  
  294.   In addition to the command qualifiers, the "replace" command is
  295.   supported to allow for the replacement of types, variables or
  296.   type-variable combinations after a "#define" has been expanded.
  297.  
  298.   The format of the replace command is:
  299.  
  300.      replace [type/variable/all] "string1" "string2"
  301.  
  302.   As an example, the default replacement of FILE usually has the
  303.   format:
  304.  
  305.      replace type "struct _iobuf" "FILE"
  306.  
  307.   The varargs system is also replaced using this command.
  308.  
  309. 2 Examples
  310.  
  311.   CEXTRACT FILEA.C
  312.  
  313.   Extract the function prototypes in the default extraction format from
  314.   the C source file FILEA.C.
  315.  
  316.   CEXTDOC FILEA.C FILEB.C
  317.  
  318.   Extract the function prototypes in a normal documentation format from
  319.   the C source files FILEA.C and FILEB.C.
  320.  
  321.   CEXTRACT /TROFF-MODE FILEA.C FILEB.C
  322.  
  323.   Extract the function prototypes in a troff documentation format from
  324.   the C source files FILEA.C and FILEB.C.  Probably useless on a VMS
  325.   system.
  326.  
  327.   CEXTRACT /SETTINGS
  328.  
  329.   Find out what all of the default settings are.  This will show what
  330.   the normal environment is.
  331.  
  332.   CEXTRACT /READ-CONFIG /DUAL-OUTPUT FILEA.C
  333.  
  334.   Extract the function prototypes assuring that the configuration
  335.   files are not read in.  Also assure that both K&R and ANSI C output
  336.   will be used.
  337.