home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 October / usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso / reviewed / volume01 / cextract / part01 / cextract.doc < prev    next >
Text File  |  1991-07-08  |  12KB  |  397 lines
  1.  
  2.  
  3.  
  4. CEXTRACT(1)              USER COMMANDS                CEXTRACT(1)
  5.  
  6.  
  7.  
  8. NAME
  9.      cextract, cextdoc - C prototype/documentation extractor
  10.  
  11. SYNOPSIS
  12.      cextract [ -Q# ] [ +AaPpNnx ] [ -o _o_u_t_f_i_l_e ] [  -Hstring  -v
  13.      -V ] [[ -options ] _f_i_l_e_n_a_m_e... ]
  14.  
  15.      cextdoc [ -Q# ] [ +AaNnx ] [ -o _o_u_t_f_i_l_e  ]  [  -v  -V  ]  [[
  16.      -options ] _f_i_l_e_n_a_m_e... ]
  17.  
  18. DESCRIPTION
  19.      _C_E_X_T_R_A_C_T is used to extract the function  descriptions  (aka
  20.      prototypes)  from a list of C source files and send them out
  21.      to the standard output or a specified file.  It may also  be
  22.      used  to generate basic documentation for a list of C source
  23.      files.
  24.  
  25.      The specific reason this program was written was to  provide
  26.      a  method of automatically generating header files, contain-
  27.      ing prototypes, for all of the functions used  throughout  a
  28.      multi-file project.
  29.  
  30.      Along with the standard C preprocessing options, -D, -I, and
  31.      -U,  there are options which allow more control of what form
  32.      the output will take.
  33.  
  34.      To allow for conditional processing, _c_e_x_t_r_a_c_t  automatically
  35.      predefines  the  __CEXTRACT__ identifier.  Preprocessor com-
  36.      mands, such as "#if", "#ifdef" and  "#ifndef"  may  then  be
  37.      used  to  control  what  code is parsed by _c_e_x_t_r_a_c_t.  If the
  38.      _c_e_x_t_d_o_c command  is  used,  the  program  will  also  define
  39.      __CEXTDOC__.
  40.  
  41.      The _c_e_x_t_r_a_c_t program also supports the use of  customization
  42.      files.   A  system configuration file will be read, and then
  43.      any ".cextrc" file in the user's home directory, and finally
  44.      any ".cextrc" file in the current directory.  For a descrip-
  45.      tion of the  format  of  the  customization  file,  see  the
  46.      _c_e_x_t_r_c(5) manual page.
  47.  
  48. COMMAND LINE OPTIONS
  49.      The _c_e_x_t_r_a_c_t and _c_e_x_t_d_o_c  programs  support  both  long  and
  50.      short  command  line  options.   Also,  a `+' sign before an
  51.      option description means that it can be either  on  or  off,
  52.      with a `+' prefix enabling that option or a `-' prefix disa-
  53.      bling it.  The prefix of "no-" ("no" on VMS systems) is also
  54.      supported for disabling an option.
  55.  
  56.      Most command line arguments can be used anywhere on the com-
  57.      mand line, but there are a few which must be used before any
  58.      file parsing begins [such as the -N, -n and -x options], and
  59.      one which can only be the first argument on the command line
  60.  
  61.  
  62.  
  63. Sun Release 4.1     Last change: 3 July 1991                    1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CEXTRACT(1)              USER COMMANDS                CEXTRACT(1)
  71.  
  72.  
  73.  
  74.      [the -Q flag].
  75.  
  76.      +A, +sort-all
  77.           Sort the output, listing all functions in  alphabetical
  78.           order.  This option is not compatible with the +C flag,
  79.           since functions are sorted over  the  entire  spectrum,
  80.           not just for each file.
  81.  
  82.      +a, +sort-by-files
  83.           Sort the output, listing functions  alphabetically  for
  84.           each   file.    Since   this  option  sorts  each  file
  85.           separately, it is compatible with the +C  flag,  unlike
  86.           the  +A option.  For _c_e_x_t_r_a_c_t, the default is to not do
  87.           any sorting, while the _c_e_x_t_d_o_c default is  to  sort  by
  88.           files.
  89.  
  90.      +C, +first-comments
  91.           Capture the first comment encountered in each file  and
  92.           include it in the generated output. [default off]
  93.  
  94.      +c, +comments, +yank-comments
  95.           Take the comment  immediately  preceding  the  function
  96.           declaration  and send it as output along with the func-
  97.           tion prototype. [default on]
  98.  
  99.      -Dexpression, -define=expression
  100.           Define a macro, as per  the  C  "#define"  preprocessor
  101.           statement.
  102.  
  103.      +E, +externs
  104.           Place the string 'extern' before each  function  proto-
  105.           type. [default on]
  106.  
  107.      +F, +filename
  108.           Prepend the name of the file  to  the  initial  comment
  109.           when  it  is  processed.   This  flag  requires  the -C
  110.           option. [default off]
  111.  
  112.      -f#%%, -font-#-%%
  113.           Specify what fonts are to be used when generating troff
  114.           documentation  output.   The  font name is a one or two
  115.           character troff name which will be interpreted later by
  116.           the  troff  processor.  Four fonts are used: `1' or `t'
  117.           which is used only for the title words "Function:"  and
  118.           "File:"  [default  value  of  "C", Courier]; `2' or `c'
  119.           which is used for  comments  [default  value  of  "CO",
  120.           Courier  Oblique];  `3'  or  `n'  which is used for the
  121.           function name [default value of "B", Times  Bold];  and
  122.           `4'  or  `p'  for  the parameter list [default value of
  123.           "R", Times Roman].  Note that the `#'  character  indi-
  124.           cates  the  type being adjusted, and "%%" indicates the
  125.           one or two character font name.
  126.  
  127.  
  128.  
  129. Sun Release 4.1     Last change: 3 July 1991                    2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CEXTRACT(1)              USER COMMANDS                CEXTRACT(1)
  137.  
  138.  
  139.  
  140.      -Hstring, -header-string=string
  141.           During the normal extraction mode, enclose  the  output
  142.           within the sequence "#ifndef string", "#define string",
  143.           ..., "#endif /* string */".  This method is  used  with
  144.           many  system  header files and prevents the header file
  145.           from being parsed more than once.  If  this  option  is
  146.           not used, the output will be enclosed within a "#ifndef
  147.           __CEXTRACT__", "#endif  /*  __CEXTRACT__  */"  sequence
  148.           instead.
  149.  
  150.      -Idir, -include=dir
  151.           Add the directory "dir" to the search path for  include
  152.           files  accessed  via the "#include" preprocessor state-
  153.           ment.  This flag is passed on to the C preprocessor.
  154.  
  155.      +m, +multi-comments, +multiple-comments
  156.           If the -c flag is set, look for a "block"  of  multiple
  157.           comments,  instead  of a single comment.  Comments with
  158.           more  than  one  newline  in  between  are   considered
  159.           separate. [default off]
  160.  
  161.      -N, -roff-mode, -troff-mode
  162.           Enable documentation mode, sending output as -ms  troff
  163.           format.
  164.  
  165.      -n, -doc-mode
  166.           Enable documentation mode,  sending  output  as  normal
  167.           text.  This is the default mode of the _c_e_x_t_d_o_c program.
  168.  
  169.      -o outfile, -output-file outfile, -output-file=outfile
  170.           Send output to the specified file instead of the  stan-
  171.           dard output.  The file name need not immediately follow
  172.           the `-o' flag, but it  must  be  the  first  non-option
  173.           argument.  Warning:  This  will  overwrite any existing
  174.           file of the same name.
  175.  
  176.      +P, +dual-output
  177.           In extraction mode, generate both styles  of  C  proto-
  178.           types,  separated  by using "#ifdef" and "#else" state-
  179.           ments to test for __STDC__.  This option  must  precede
  180.           any file arguments. [default on]
  181.  
  182.      +p, +ansi-code
  183.           Produce output in ANSI C prototype  format;  otherwise,
  184.           produce  old-style declarations.  This option must pre-
  185.           cede any file arguments.  [default off]
  186.  
  187.      -qfile, -config-file=file
  188.           Read in the specified file and parse it for  customiza-
  189.           tion commands.
  190.  
  191.      -Q#, -read-config=#
  192.  
  193.  
  194.  
  195. Sun Release 4.1     Last change: 3 July 1991                    3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. CEXTRACT(1)              USER COMMANDS                CEXTRACT(1)
  203.  
  204.  
  205.  
  206.           An octal  digit  specifies  which  configuration  files
  207.           should  be read; 1 for the system configuration file, 2
  208.           for the $HOME/.cextrc file and 4 for the ".cextrc" file
  209.           in  the current directory.  Add values to read multiple
  210.           files.  If no number is  specified,  a  0  is  assumed.
  211.           This option must be the very first argument on the com-
  212.           mand line.  [default value of 7 reads all three files]
  213.  
  214.      +r, +remove-names, +discard-names
  215.           Do not include the variable names within in prototypes.
  216.  
  217.      +S, +show-all, +show-anyway
  218.           If the -p flag is off, output the prototype  list  any-
  219.           way,  but  enclosed  within comments. If the -P flag is
  220.           set, comments and commented prototypes should  also  be
  221.           duplicated  within  the non-ANSI portion of the output.
  222.           [default on]
  223.  
  224.      +s, +statics
  225.           Do not ignore static functions when searching for func-
  226.           tion declarations.  [default off]
  227.  
  228.      -T#, -tab-width=#
  229.           Specify the tab width used during documentation output.
  230.           If no value is given, or a value of zero is given, tabs
  231.           are passed though unformatted.
  232.  
  233.      -Uname, -undefine=name
  234.           Undefine a macro.  If "-Dname" was specified in a  pre-
  235.           vious  argument,  it is removed from the argument list;
  236.           otherwise, this option is passed on to the C preproces-
  237.           sor.
  238.  
  239.      -V, -settings
  240.           Show  the  current  settings  of  the  various  program
  241.           options.
  242.  
  243.      -v, -version-info
  244.           Display the version number of the program.
  245.  
  246.      -x, -extract-mode
  247.           Run _c_e_x_t_r_a_c_t or _c_e_x_t_d_o_c as a prototype extractor.  This
  248.           is the default mode for _c_e_x_t_r_a_c_t.
  249.  
  250. COPYRIGHT
  251.      The code is freely distributable and there are  no  restric-
  252.      tions  other  than the fact that it not be used for monetary
  253.      gain and that copyright notices must be kept intact.
  254.  
  255.      Both  _c_e_x_t_r_a_c_t  and  _c_e_x_t_d_o_c  may  be   used   to   generate
  256.      proprietary source code or documentation, but its own source
  257.      code may not be used as a part of any proprietary programs.
  258.  
  259.  
  260.  
  261. Sun Release 4.1     Last change: 3 July 1991                    4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. CEXTRACT(1)              USER COMMANDS                CEXTRACT(1)
  269.  
  270.  
  271.  
  272. FILES
  273.      /usr/local/lib/cext.config, $HOME/.cextrc, .cextrc
  274.           The list of configuration files, and the order in which
  275.           they are read in.
  276.  
  277. SEE ALSO
  278.      cc(1), cextrc(5)
  279.  
  280. AUTHORS
  281.      Adam Bryant
  282.      adb@cs.bu.edu
  283.  
  284.      initial VMS port by John Carr
  285.      jrcarr@iup.bitnet
  286.  
  287. VMS
  288.      On VMS systems, only the longer  command  line  options  are
  289.      available,  and the '/' character is used to specify command
  290.      line options.
  291.  
  292. BUGS
  293.      1) This isn't a full compiler, so it won't give very helpful
  294.      syntax error messages.  [This is a feature, really! :-)}
  295.  
  296.      2) Because it uses the C preprocessor, macros  in  parameter
  297.      lists are always expanded to the actual (perhaps unreadable)
  298.      value.  This will still be correct, but it tends to make the
  299.      generated output non-portable.  The varargs and FILE defini-
  300.      tions are already checked for and properly replaced since on
  301.      most  systems they are macros.  Use the "replace" configura-
  302.      tion file command to handle other macros properly.
  303.  
  304.      3) As far as I know, there is no way to tell the normal  VMS
  305.      C compiler not to strip out comments.  This renders the com-
  306.      ment extraction and documentation mode portions rather  use-
  307.      less to VMS sites.
  308.  
  309.      4) Might barf on extremely large or extremely complex  code.
  310.      I  have  tried  to be sure that I could parse any C function
  311.      declaration I could think of, but I no  doubt  forgot  some-
  312.      thing.
  313.  
  314.      5) Using the `+r' flag might  be  risky  with  more  complex
  315.      declarations,  since  they  may become ambiguous without the
  316.      variable name.
  317.  
  318.      6) Cextract cannot handle a function returning a "struct" or
  319.      a  pointer to such where the full struct declaration is done
  320.      when the function itself is declared.
  321.  
  322.      7) currently, only one replacement can be handled at a time.
  323.      So,  if  a  type  and a variable replacement can take place,
  324.  
  325.  
  326.  
  327. Sun Release 4.1     Last change: 3 July 1991                    5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. CEXTRACT(1)              USER COMMANDS                CEXTRACT(1)
  335.  
  336.  
  337.  
  338.      only the first one detected will be handled.
  339.  
  340.      If any other bugs are detected, please notify the author.
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393. Sun Release 4.1     Last change: 3 July 1991                    6
  394.  
  395.  
  396.  
  397.