Contents More cryptic commands The docx utility The docx utility

12 The docc utility

See also the docx utility.

docc is auto-documented. Simply type docc to list its generic options:

$ docc
usage: docc target_format [generic_options] [format_options] {input_file}+

target_format: latex, man, html, rtf or href (pseudo-format)

Note that PTF comments are automatically extracted from C/C++ source files
using docx if the extension of the input file name is .[hH]* or .[cC]*. Tcl
source files are supported too if the extension of the input file name is .tcl
or .TCL.

generic_options:
-c 
Each input file is individually translated to a stand-alone
documentation file (like 'cc -c').
Default: all input files are translated to a single output file.
-o <%255s>
Specify the name of the output file (like 'cc -o').
Default: the basename of the input file+a format specific suffix.
-href (-h) <%255s>
Specify the name of the hypertext references file to be loaded
(generated during a first pass using the 'href' pseudo-format).
Default: none.
-sed (-s) <%255s>
Specify the name of a file which contains sed commands. These
sed commands are applied to all PTF source files (even if
automatically extracted using docx) just before their translation
to the target format.
Default: none.
-borders (-b) 
Tell docx to add borders around extracted code.
Default: no borders.

Type 'docc target_format' to list the options related to
target_format.

Then, for example, type docc rtf to list the options related to the RTF format:

$ docc rtf
-linear (-li) 
The output RTF file does not contain hypertext links a la WinHelp.
Default: non linear (WinHelp).
-adobefonts (-af) 
Use Adobe fonts (Helvetica, Times, etc).
Default: Windows fonts (Arial, Time New Roman, etc).

12.1 Examples

12.1.1 LaTeX

PTF comments are directly extracted from C/C++ sources files.

$ cd tmp
$ docc latex -dc article -dco a4paper \
-ti 'The PTF Format and Related Utilties' \
-o ptf.tex ptf.txt docc.cc docx.cc
$ ls
ptf.tex

12.1.2 troff -man

docc is run on docc.cc and then on docx.cc to generate two man pages with different headers.

$ cd tmp
$ docc man -c -ti docc -se 1 -he 'Text Utilities' -fo Pixware docc.cc
$ docc man -c -ti docx -se 1 -he 'Text Utilities' -fo Pixware docx.cc
$ ls
docc.man        docx.man

12.1.3 HTML

The hardest format to generate is HTML because in this case you must run docc twice, example:

First pass
Resolve all hypertext links and save them in a file called hrefs. To do this, you need to use the href pseudo-format.
$ cd tmp
$ docc href -o hrefs ptf.txt docc.cc docx.cc
$ ls
hrefs
Second pass
For each input file, generate an HTML file (the -c option). Load file hrefs (the -h hrefs option) to be able to resolve hypertext links.
$ docc html -br -h hrefs -c ptf.txt docc.cc docx.cc
$ ls
docc.html        hrefs           previous.gif
docx.html        next.gif        ptf.html

The -br option is used to chain the generated HTML files not only through hypertext links but also sequentially (i.e. like the pages of a book).

12.1.4 RTF

Always use -o when generating non-linear RTF format (WinHelp) to get a single .rtf file and a single .hpj (help project) file.

$ cd tmp
$ docc rtf -o docc.rtf ptf.txt docc.cc docx.cc
$ ls
docc.hpj        docc.rtf

Unlike the HTML format, the generation of WinHelp files does not require running docc twice. The hypertext links are resolved by the help compiler (example hc31.exe) that you must run under DOS on the generated .hpj file.

C> hc31 docc