cdoc

[ XITE Reference Manual | XITE home ]

Contents

Name

cdoc - Extract documentation from comments in c-programs.

Syntax

 cdoc [<option>...] <input_file>
 cdoc [<option>...] <input_file> <output_file>
 cdoc [<option>...] <input_file> <output_dir>

Description

Extract comments from c-files and generate documentation.

cdoc is a tool for automatic documentation of c-programs. cdoc will search for the pattern "/*?*" (? is any letter), "/*?:subject*" or "/*?:subject=manpage* /" in the c-code and format the comments (which end with * /). The latter kind of specification links the description of subject to the description of manpage (see Format 3 below).

The comment section must end with a line starting with the two characters * and /.

input_file can be given as "-" or "-0" (for stdin), and output_file can be given as "-" or "-1" (for stdout). If only one filename is specified, this is interpreted as input_file. Default input extension is ".c" (see option -s).

The result is written to a file with the same main name and extension according to document type. If two file names are specified, the first name is input_file, and the second name is output_file. If output_file is a directory, i.e. output_dir, the output filename becomes output_dir/subject with some suitable extension.

Options

-e spec
You may specify which letters or subject cdoc should search for by specifying -e <letter> or -e <letter:subject>. Default search letters are "DFP". Multiple -e options may be specified.

If you want to create a Unix manual page or hypertext reference manual page, the man section number is derived from letter:
P
section number 1
S
section number 2
F
section number 3
E
section number 4
D
section number 5
G
section number 6
M
section number 7
A
section number 8

-m sec
If you want to create a Unix manual page or hypertext reference manual page, you must either use the switch -m sec (where sec is the man section number), or specify the section number through letter in an -e option.

-h
Produce html code (-> _1.html, _3.html or _5.html) A table of contents list is written at the top of the document if the document consists of more than a number of lines given by the -k option.

-l
Produce LaTeX code (default) (-> .tex)

-n
Produce nLaTeX code (-> .tex)

-t
Produce troff code (-> .1, .3 or .5)

-x
Extract comments without formatting (-> .txt)

-c
Do not add table of contents to top of hypertext reference manual page.

-k num
If option -h is in use and the hypertext reference manual page exceeds approximately num lines, a table of contents will be added at the top of the page. Default: 80.

-s extension
Use extension as default extension for the input source file.

Format 1

 Line  1: /*?:subject*
 Line  2:
 Line  3: _______________________________________
 Line  4:
 Line  5:              modulename
 Line  6: _______________________________________
 Line  7:
 Line  8: Name:        modulename - one line description
 Line  9: Syntax:      | modulename [ <option>... ] args
 Line 10:              | more syntax
 Line 11: Keyword 1:   text
 Line 12:              text may go over more than one line
 Line 13: Keyword 2:   You may underline a word by
 Line 14:              putting it between 'apostrophes'
 Line 15:              (apostrophes may be printed by
 Line 16:              using two apostrophes '').
 Line 17:
 Line 18:              Lines will be aligned if you
 Line 19:              prefix them with a '|'.
 Line 20:
 Line 21:              &An ampersand starts an item.
 Line 22:              The line with the ampersand will
 Line 23:              be the name of the item.
 Line 24:              The following lines will be
 Line 25:              automatically indented.
 Line 26:              The indentation can be cancelled
 Line 27:              -&like this.
 Line 28:              &&A double ampersand starts a
 Line 29:              second level of item indentation.
 Line 30:              It can be cancelled by -&&.
 Line 31:              See the 'Options:' section above
 Line 32:              and src/xshow/xshow.c for
 Line 33:              examples.
 Line 34:
       etc.
 Line n: * /

Only one dash ("-") is allowed in the Name section above. If several items have the same description, they must appear in a comma-separated list before the dash.

Leading blanks are skipped. If the first non-blank symbol is a "|", this symbol is skipped, and the rest of the line is written unformatted.

Format 2

 Line  1: /*?*
 Line  2:
 Line  3: _______________________________________
 Line  4:
 Line  5:              modulename
 Line  6: _______________________________________
 Line  7:
 etc.
Same as above.

Format 3

 Line  1: /*?:subject=manpage* /
Make a man page which is a link to another manpage.

In this case, the comma-separated list of names in the Name section must start with manpage. This is to ensure correct links for the hypertext reference manual.

Files

$XITE_HOME/etc/emacs-header - Auto header generator.

Examples

 cdoc -t -e P:cdoc cdoc.c $XITE_MAN/man1/cdoc
 cdoc -t -e F:func -e P:func func.c $XITE_MAN/

Author

Otto Milvang

Id

$Id: cdoc.c,v 1.60 1997/09/04 10:00:17 svein Exp $