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).
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
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
The hardest format to generate is HTML because in this case you must run docc twice, example:
$ cd tmp $ docc href -o hrefs ptf.txt docc.cc docx.cc $ ls hrefs
$ 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).
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