
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).
------

*Examples
~~~~~~~~~

**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
------

**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
------

**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).

**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
------
