<!DOCTYPE article
  PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article lang="en">

<articleinfo>
    <title>ROBODoc 4.0.18 User Manual</title>
    <authorgroup>
        <author>
            <surname>Slothouber</surname>
            <firstname>Frans</firstname>
        </author>
        and 
        <author>
            <surname>Kettunen</surname>
            <firstname>Petteri</firstname>
        </author>
    </authorgroup>
    <edition>Users Guide $Id: manual.xml,v 1.28 2004/01/01 19:39:54 gumpu Exp $</edition>
    <pubdate>January 2004</pubdate>
    <copyright>
        <year>1994-2004</year>
        <holder>Frans Slothouber, Petteri Kettunen, Jacco van Weert</holder>
    </copyright>
</articleinfo>

<section>
<title>Preface</title>

    <para>ROBODoc is a API documentation tool for C, C++, Java,
    Assembler, Basic, Fortran, LaTeX, Postscript, Tcl/Tk, LISP, Forth,
    Perl, Shell Scripts, Makefiles, Occam, COBOL, DCL, Visual Basic,
    HTML, DB/C, and many other languages.  It can be made to work with
    any language that supports comments.</para>

    <para>ROBODoc works by extracting specially formated headers from
    your source code and writes these to documentation files. These
    files can be formatted in HTML, ASCII, XML DocBook, or RTF; and
    indirect to PDF.</para>

    <para>ROBODoc is similar to JavaDoc, though the idea is much
    older than JavaDoc.  ROBODoc allows you to maintain a program and
    its documentation in a single file.  This makes it easier to keep
    your documentation up-to-date.</para>

    <para>ROBODoc can be used to document anything you like,
    functions, methods, variables, definitions, test cases, makefile
    entries, and anything else you can think of.</para>

    <para>It can create documentation consisting of many small files.
    For instance in HTML format for easy browsing and publication on
    the web.  It can also create a single file in LaTeX or RTF format
    for inclusion into bigger design documents.  The RTF format is
    suited to be included in Word documents.</para>

    <para>ROBODoc allows you to separate internal documentation from
    external documentation.  In singledoc mode it can create a section
    layout based on the hierarchy of your modules.</para>

    <para>ROBODoc is designed to work with a lot of different
    programming languages.  It has no knowledge of the syntax of a
    programming languages.  It only has some knowledge about how
    remarks start and end in a lot of programming languages.  This
    means that you sometimes have to do a little more work compared to
    other tools that have detailed knowledge of the syntax of a
    particular language.  They can use that knowledge to figure out
    some of the information automatically.  This usually also means
    that they work only with one or two languages.  </para>

</section>


<!-- 
  ========== I N S T A L L I N G  ===========
  -->

<section id="installing">
<title id="installing.title">Installing ROBODoc</title>

    <para>The easiest way to install ROBODoc is to use one of the
    packages.  There are package for RedHat, OSX, and a precompiled
    executable for Windows.</para>

    <para>You can also compile robodoc from the sources.  On a system
    with <command>autoconfig</command> it is as simple as:</para>

<programlisting>
./configure
make
make install
</programlisting>

    <para>On a Windows system with VC++ you have two options.  Either
    use the following commands in the source directory (tested under
    NT):</para>

<programlisting>
vcvars32
nmake -f makefile.win32
</programlisting>

   <para>Or use the supplied project file
   <filename>robodoc.dws</filename> in the <filename>Win32</filename>
   directory.  This only works if the <filename>.dsp</filename> and
   <filename>.dws</filename> have the right format.  Both files should
   use the windows convention for line-endings (cr/lf).  Sometimes
   these get lost while zipping or unzipping the ROBODoc archive, and
   in that case the project will turn op empty.</para>

   <para>There is also a makefile for Borland C, as well as for MINGW.
   For other compilers you might want to try
   <filename>makefile.pain</filename>. </para>

   <para>You can test your executable, by going to the
    <filename>Examples/PerlExample</filename> directory in the
    archive, and running robodoc.  This should create a directory
    called <filename>Doc</filename>.  In there you should now
    find a file called <filename>masterindex.html</filename>.
    </para>

</section>




<section id="preparing">
<title id="preparing.title">Preparing your source code for ROBODoc</title>

    <para> ROBODoc allows you to mix the program documentation with
    the source code.  It does require though that this documentation
    has a particular layout so ROBODoc can recognize it.  There are
    three key concepts: headers, items, and sections.  </para>

<section>
<title>Headers</title>

    <para>Headers are the building blocks of the documentation. Lets
    look at an example. The following header was taken from the
    documentation of the predecessor of ROBODoc, AutoDoc.</para>

<screen>
 /****f* financial.library/StealMoney
  *  NAME
  *    StealMoney -- Steal money from the Federal Reserve Bank. (V77)
  *  SYNOPSIS
  *    error = StealMoney( userName, amount, destAccount, falseTrail )
  *  FUNCTION
  *    Transfer money from the Federal Reserve Bank into the
  *    specified interest-earning checking account.  No records of
  *    the transaction will be retained.
  *  INPUTS
  *    userName    - name to make the transaction under.  Popular
  *                  favorites include "Ronald Reagan" and
  *                  "Mohamar Quadaffi".
  *    amount      - Number of dollars to transfer (in thousands).
  *    destAccount - A filled-in AccountSpec structure detailing the
  *                  destination account (see financial/accounts.h).
  *                  If NULL, a second Great Depression will be
  *                  triggered.
  *    falseTrail  - If the DA_FALSETRAIL bit is set in the
  *                  destAccount, a falseTrail structure must be
  *                  provided.
  *  RESULT
  *    error - zero for success, else an error code is returned
  *           (see financial/errors.h).
  *  EXAMPLE
  *    Federal regulations prohibit a demonstration of this function.
  *  NOTES
  *    Do not run on Tuesdays!
  *  BUGS
  *    Before V88, this function would occasionally print the
  *    address and home phone number of the caller on local police
  *    976 terminals.  We are confident that this problem has been
  *    resolved.
  *  SEE ALSO
  *    CreateAccountSpec(),security.device/SCMD_DESTROY_EVIDENCE,
  *    financial/misc.h
  ******
  * You can use this space for remarks that should not be included
  * in the documentation.
  */
</screen>

    <para>A header consists of three different elements. A
    begin marker, a number of items, and an end marker.  The begin marker
    in the example is example is:</para>

<screen>
  ****f* financial.library/StealMoney  
</screen>

    <para>It marks the that marks the begin of a header.  It also
    tells ROBODoc the name of the element that is being documented,
    StealMoney, the module it is part of, financial.library, and the
    kind of element, <literal>f</literal>, which stands for function.
    ROBODoc always expects a module name and an element name separated
    by a <literal>/</literal>.  So <literal>ModFoo/funcBar</literal>
    is a valid name, but <literal>funcBar</literal> is not.
    See <xref linkend="sections" endterm="sections.title" /> for more
    information.</para>

    <para>
    The end marker:
    </para>

<screen>
  ******
</screen>

    <para>
    marks the end of a header.
    </para>

    <para>Items begin with an item name and are followed by the
    item's body.  An example: </para>

<screen>
  *  FUNCTION
  *    Transfer money from the Federal Reserve Bank into the
  *    specified interest-earning checking account.  No records of
  *    the transaction will be retained.
</screen>

    <para>
    In this case the item's name is FUNCTION.
    </para>

    <para>
    Each line of an item starts with a remark marker.  In this case
    <literal>*</literal>.
    </para>

    <para>
    The above example is a C example.  ROBODoc supports many more
    languages though. The following table shows all the markers that
    ROBODoc supports by default.
    </para>

<screen>

/****       C, C++
 *
 ***/

//****      C++
//
//***

(****       Pascal, Modula-2
 *
 ***
 *)

{****       Pascal
 *
 ***
 *}

;****       M68K assembler
;
;***

****        M68K assembler, COBOL
*
***

C     ****  Fortran
C     
C     ***

REM ****    BASIC
REM *
REM ***

%****       LaTeX, TeX, Postscript
%
%***

#****       Tcl/Tk
#
#***

--****      Occam
--
--***

&lt;!--****     HTML Code
*
***

&lt;!---****    HTML Code
*
***

|****       GNU Assembler
|
|***

$!****      DCL
$!
$!***

'****       Visual Basic, Lotus script
'*
'***

.****       DB/C
.*
.***

!!****      FORTRAN 90
!!
!!***

!****       FORTRAN 90
!
!***

</screen>

    <para> Any of these markers can be mixed, and they are not limited
    to the languages listed.  So if you have a language that is not
    listed but that has remarks that start with a <literal>#</literal>
    you can use the Tcl/Tk markers, and create headers such as:
    </para>

<screen>
#****f* Foo/Bar
# FUNCTION
#   Bar snarfs the Foo input and mangles it.  Given the right settings
#   it might also do a bit of snu snu.
#***
</screen>

</section>


<section>
<title>Header Types</title>

    <para> ROBODoc defines a number of header types.  You don't need
    to use them but they can be useful for sorting information.  The
    headertype tells ROBODoc what kind of object you are documenting.
    This information allows ROBODoc to create more useful index
    tables.</para>

    <para>The type is identified by one or two characters.  ROBODoc
    expects to find them after the fourth <literal>*</literal> in the
    begin marker.  So <literal>#****f</literal> is a valid marker,
    but <literal>#**f**</literal> is not.</para>

    <para>If a single character is given, the type is defined as
    listed in the following table</para>

    <itemizedlist> 
    <listitem> c -- Header for a class.  </listitem>
    <listitem> d -- Header for a constant (from define). </listitem>
    <listitem> f -- Header for a function.  </listitem>
    <listitem> h -- Header for a module in a project.  </listitem>
    <listitem> m -- Header for a method.  </listitem>
    <listitem> s -- Header for a structure.  </listitem>
    <listitem> t -- Header for a types. </listitem>
    <listitem> u -- Header for a unittest. </listitem>
    <listitem> v -- Header for a variable.  </listitem>
    <listitem> * -- Generic header for every thing else. </listitem>
    </itemizedlist> 

    <para>If two characters are given, the first character should be
    <literal>i</literal> and the second can be any of the other
    characters from the table above.  This creates an internal header
    of the type specified by the second character.  Internal headers
    are special.  They can be used to hide certain headers. They are
    only extracted if requested. You can use them to document internal
    functions, classes, etc. that you do not want clients to see,
    creating what might be a programmer's manual as opposed to a
    user's manual.</para>

    <para>So <literal>/****if* Module/func1</literal> defines an
    internal function called <literal>func1</literal>.
    </para>

    <para>Headers marked internal are by default not included in the
    generated documentation.  If you want to include them use the
    option <option>--internal</option>.   You can also generate the
    documentation from only the internal headers with the option
    <option>--internalonly</option>.
    </para>

    <para>You can define your own headertypes using the ROBODoc
    configuration file, <filename>robodoc.rc</filename>. 
    See <xref linkend="customizing" endterm="customizing.title" />.
    This way you can document anything you like, for instance makefile
    entries, system tests, or exceptions.
    </para>

</section>


<section>
<title>Items</title>

    <para> By default ROBODoc recognizes the following items: </para>

<itemizedlist>
    <listitem> NAME -- Item name plus a short description. </listitem> 
    <listitem> COPYRIGHT -- Who own the copyright : "(c) &lt;year&gt;-&lt;year&gt; by 
             &lt;company/person&gt;" </listitem>
    <listitem> SYNOPSIS, USAGE -- How to use it. </listitem>
    <listitem> FUNCTION, DESCRIPTION,  PURPOSE -- What does it do. </listitem>
    <listitem> AUTHOR -- Who wrote it. </listitem> 
    <listitem> CREATION DATE -- When did the work start. </listitem> 
    <listitem> MODIFICATION HISTORY,  HISTORY -- Who has done which changes and when. </listitem>
    <listitem> INPUTS, ARGUMENTS, OPTIONS, PARAMETERS, SWITCHES -- What can we feed into it.  </listitem>
    <listitem> OUTPUT, SIDE EFFECTS -- What output is made. </listitem>
    <listitem> RESULT, RETURN VALUE -- What do we get returned. </listitem>
    <listitem> EXAMPLE  -- A clear example of the items use. </listitem> 
    <listitem> NOTES -- Any annotations </listitem> 
    <listitem> DIAGNOSTICS  -- Diagnostic output  </listitem>
    <listitem> WARNINGS, ERRORS  -- Warning and error-messages. </listitem>
    <listitem> BUGS -- Known bugs. </listitem> 
    <listitem> TODO, IDEAS  -- What to implement next and ideas. </listitem> 
    <listitem> PORTABILITY -- Where does it come from, where will it work. </listitem>
    <listitem> SEE ALSO -- References to other functions, man pages, other documentation. </listitem>
    <listitem> METHODS, NEW METHODS -- OOP methods. </listitem>
    <listitem> ATTRIBUTES, NEW ATTRIBUTES -- OOP attributes  </listitem>
    <listitem> TAGS -- Tag-item description. </listitem>
    <listitem> COMMANDS -- Command description. </listitem>
    <listitem> DERIVED FROM -- OOP super class. </listitem>
    <listitem> DERIVED BY -- OOP sub class. </listitem>
    <listitem> USES, CHILDREN -- What modules are used by this one. </listitem>
    <listitem> USED BY, PARENTS -- Which modules do use this one. </listitem>
    <listitem> SOURCE -- Source code inclusion. </listitem>
</itemizedlist>

    <para>You can define your own items using the ROBODoc
    configuration file, <filename>robodoc.rc</filename>.  See <xref
    linkend="customizing" endterm="customizing.title" />.  </para>

</section>

<section id="sections">
<title id="sections.title">Sections</title>

    <para>The structure of source code for an project is usually
    hierarchical.  A project might consists of several applications,
    an application of several modules, a module of several functions
    or even submodules.  ROBODoc allows you to show this hierarchy in
    your documentation.  For this you specify the hierarchy in the
    header name.  For instance,  you have a project that is going to
    create a new language called D.  The D Language project might
    consists of three applications: a preprocessor, a compiler, and a
    linker.  The compiler consists of two modules, a parser and a
    generator.  The parser module consists of several
    functions.</para>

    <para>The following three headers show how this hierarchy can be
    defined in the header name.</para>

<screen>
#****h* D-Language/Compiler
# FUNCTION
#   The compiler takes a preprocessed source file and
#   turns it into an object file.
#***
</screen>

<screen>
#****h* D-Language/Linker
# FUNCTION
#   The linker module contains functions that scan a 
#   object file and build the executable.
#***
</screen>

<screen>
#****h* Compiler/Parser
# FUNCTION
#   The parser module contains functions that scan a 
#   preprocessed source file and build the syntax tree.
#***
</screen>

<screen>
#****f* Parser/ReadToken
# FUNCTION
#   ReadToken reads the next token from the input
#   file.
#***
</screen>

    <para>When you generate documentation with the option
    <option>--section</option>, ROBODoc uses the hierarchical
    information when generating the table of content and document
    section information. For instance in HTML sections are started
    with &lt;H1&gt;,  &lt;H2&gt;,  &lt;H3&gt; depending on the level
    in the hierarchy.  The table of will also contain levels.  The
    table of contents for the above example will be: </para>

<screen>
1. D-Language/Compiler
1.1 Compiler/Parser
1.1.1 Parser/ReadToken
2. D-Language/Linker
</screen>

</section>
</section>


<section>
<title>Extracting Documentation with ROBODoc</title>

    <para>Now that you have prepared your source code for use with
    ROBODoc you are ready to extract the documentation.  There are
    several choices to be made.</para>

<section>
<title>Single document or many smaller documents</title>

    <para>First of all, ROBODoc can be used in three modes.</para>

    <itemizedlist> 

    <listitem>multidoc -- in this mode ROBODoc scans
    all the source files in your source directory and creates a
    separate document file for each of these in a document directory.
    The document directory is created automatically. Its structure is
    a mirror of the structure of your source directory.</listitem> 

    <listitem>singledoc -- in this mode ROBODoc scans all the source
    files in your source directory and creates a single documentation
    file that contains all the documentation extracted from your
    source files.  </listitem>

    <listitem>singlefile -- in this mode ROBODoc scans a single source
    file and creates a single documentation file.</listitem>

    </itemizedlist>
</section>

<section>
<title>multidoc</title>

    <para>The multidoc mode is useful to create browsable documents.
    For instance many small HTML files that can be viewed with a
    web-browser.  This mode requires the following arguments:</para>

<cmdsynopsis>
    <command>robodoc</command>
    <arg choice='req'>--src <replaceable>source directory</replaceable></arg>
    <arg choice='req'>--doc <replaceable>document directory</replaceable></arg>
    <arg choice='req'>--multidoc</arg>
    <arg>other options</arg>
</cmdsynopsis>

    <para>An additional option that is useful with this mode is
    <option>--index</option>, this creates a series of index files,
    one for each header type.</para>
</section>


<section>
<title>singledoc</title>

    <para> The singledoc mode is useful to create bulk documentation
    that can be incorporated in other documents, or that can be
    delivered to a client as a single document.  For instance a file
    created in RTF format can be included into a larger design
    document written in Word format.  This mode requires the following
    arguments:</para>

<cmdsynopsis>
    <command>robodoc</command>
    <arg choice='req'>--src <replaceable>source directory</replaceable></arg>
    <arg choice='req'>--doc <replaceable>document file without extension</replaceable></arg>
    <arg choice='req'>--singledoc</arg>
    <arg>other options</arg>
</cmdsynopsis>

    <para>An additional option that is useful with this mode is
    <option>--sections</option>, this causes the headers to follow a
    section layout based on the module element hierarchy defined in the
    header name.</para>

</section>


<section>
<title>singlefile</title>

    <para>The singlefile mode is not very useful.  It is mainly used
    for debugging purposes.  This mode requires the following
    arguments:</para>

<cmdsynopsis>
    <command>robodoc</command>
    <arg choice='req'>--src <replaceable>source file</replaceable></arg>
    <arg choice='req'>--doc <replaceable>document file</replaceable></arg>
    <arg choice='req'>--singlefile</arg>
    <arg>other options</arg>
</cmdsynopsis>

</section>

<section>
<title>Output formats</title>

    <para>Your next choice is the output format. ROBODoc can create
    documentation in several formats:</para>

    <itemizedlist> 
    <listitem>HTML, option <option>--html</option></listitem> 
    <listitem>RTF, option <option>--rtf</option></listitem> 
    <listitem>LaTeX, option <option>--latex</option></listitem> 
    <listitem>XML DocBook, option <option>--dbxml</option></listitem> 
    </itemizedlist>

    <para>What format to use depends on your wishes. If you want a
    single printable document, use LaTeX or XML DocBook.  If you want
    a document that can be included into a larger (Word) document use
    RTF.  If you want something that is browsable use HTML, or use XML
    DocBook and then convert it to HTML.</para>

</section>


<!-- 
  ========== O P T I O N S  ===========
  -->

<section>
<title>Options</title>

    <para>The behavior of ROBODoc can be further fine-tune with a large number of
    options.</para>

    <section><title>-c</title>
        <para>Show the copyright message.</para>
    </section>

    <section><title>--cmode</title>
        <para>Use ANSI C grammar in SOURCE items and use this
              for some syntax highlighting (HTML only).</para>
    </section>

    <section><title>--css</title>
        <para> Use to content of the specified file to create the
        <filename>robodoc.css</filename>.  The content of the file is
        copied into <filename>robodoc.css</filename>.  </para>
    </section>

    <section><title>--dbxml</title>
        <para>Generate documentation in XML DocBook format.</para>
    </section>

    <section><title>--doc</title>
        <para>Define the path to the documentation directory or
        documentation file.  A path can start with
        <literal>./</literal> or <literal>/</literal>.  Do not use
        <literal>..</literal> in the path.  The documentation
        directory can be a subdirectory of the source directory,
        or be parallel to the source directory, 
        however they can not be equal. So 
        <command>--src ./sources</command>
        together with 
        <command>--doc ./documents</command>
        is fine,
        but 
        <command>--src ./Everything</command>
        together with 
        <command>--doc ./Everything</command>
        is not.
        </para>
    </section>

    <section><title>--folds</title>
        <para>Use fold marks to split a big document into smaller ones.</para>
    </section>

    <section><title>--html</title>
        <para>Generate documentation in HTML format.</para>
    </section>

    <section><title>--internal</title> 
        <para>Also include headers marked internal.</para>
    </section>

    <section><title>--internalonly</title> 
        <para>Only include headers marked internal.</para>
    </section>

    <section><title>--index</title> 
        <para>Also create a master index file.</para>
    </section>

    <section><title>--lock</title> 
        <para> Per source file robodoc locks on the first headermarker
        it finds and will recognize only that particular headermarker
        for the remaining part of the file.  In addition it locks on
        the first remark marker in each header and will recognize only
        that particular remark marker for the remaining part of the
        header.  </para>
    </section>

    <section><title>--multidoc</title>
        <para>Generate one document per source file, and copy the
        directory hierarchy.</para>
    </section>

    <section><title>--nosource</title>
        <para>Do not include the SOURCE items.</para>
    </section>

    <section><title>--nodesc</title>
        <para>Do not scan any subdirectories, scan only the top level
        directory of the source tree.</para>
    </section>

    <section><title>--rc</title>
        <para>Use the specified file instead of <filename>robodoc.rc</filename>.
        </para>
    </section>

    <section><title>--rtf</title> 
        <para>Generate documentation in RTF format.</para>
    </section>

    <section><title>--sections</title>
        <para>Create sections based on the module hierarchy.</para>
    </section>

    <section><title>--singledoc</title>
        <para> Define the documentation directory or documentation
        file.</para>
    </section>

    <section><title>--singlefile</title>
        <para> Generate a single document from a single file </para>
    </section>

    <section><title>--src</title>
        <para> Define the path for the source directory or source
        file.  The path can start with <literal>./</literal> or
        <literal>/</literal>.  Do not use <literal>..</literal> in the
        path.  </para>
    </section>

    <section><title>--tabsize</title>
        <para>Lets you specify the tabsize.</para>
    </section>

    <section><title>--toc</title>
        <para>Add a table of contents. This works in multidoc mode as
        well as singledoc mode.</para>
    </section>

    <section><title>--latex</title>
        <para>Generate documentation in LaTeX format.</para>
    </section>

    <section><title>--tell</title> 
        <para>ROBODoc tells you what steps it is taking.</para>
    </section>

</section>

<!--
<section>
<title>Errors and warnings</title>
    <para>To be completed</para>
</section>
-->

</section>



<!-- 
  ========== C O N F I G U R A T I O N 
  -->

<section id="customizing">
<title id="customizing.title">Customizing ROBODoc</title>

    <para> ROBODoc can be configured with a configuration file called
    <filename>robodoc.rc</filename>.  With it you can define item
    names, frequently used options, and translations for English
    terms.  An example is shown below.
    </para>

<programlisting>
# Example robodoc.rc
#
items:
    NAME
    SYNOPSIS
    INPUTS
    OUTPUTS
    SIDE EFFECTS
    HISTORY
    BUGS
ignore items:
    HISTORY
    BUGS
options:
    --src ./source
    --doc ./doc
    --html
    --multidoc
    --index
    --tabsize 8
headertypes:
    e  "Makefile Entries"  robo_mk_entries
    x  "System Tests"      robo_syst_tests
    q  Queries             robo_queries
ignore files:
    README
    CVS
    *.bak
    *~
    test_*
</programlisting>

    <para>The configuration file consists of a number of blocks.
    Each block starts with a name followed by a
    <literal>:</literal>.  There are currently four blocks:
    items, ignore items, options, header types, and ignore files.
    In each block you define a number of values.  Each value must
    start with at least one space.
    </para>

    <section><title>items block</title>
        <para>In this block you can define the names of items that
        ROBODoc should recognize.  Item names can consist of more than 
        one word but should be written in all uppercase characters.
        Define one item name per line.  You do not need to put quotes
        around them if they contain spaces.
        </para>

        <para>If you do not define an items block ROBODoc uses its
        default list of item names.  If you define an items block 
        ROBODoc uses only those item names, any of the default items names
        (except SOURCE) are no longer recognized.</para>
    </section>

    <section><title>ignore items block</title>
        <para>In this block you can define the names of items that
        ROBODoc should ignore when generating documentation.
        This can be useful if you want to create documentation
        for a client, but for instance do not want to include
        the history items and bugs items.</para>
    </section>

    <section><title>options block</title>
        <para>In this block you can define frequently used options.
        The options you specify here are added to any options you
        specify on the command line.</para>
    </section>

    <section><title>headertypes block</title>
        <para>In this block you can define your own headertypes.
        These are added to the existing headertypes.  Each new
        headertype requires three parameters: the character used to
        indicate a header of this type, the title for this type as
        used in the master index, the name of the file in which the
        index this type is stored.  If you use a character of an
        existing headertype, this headertype is overwritten.
        </para>
    </section>

    <section><title>ignore files block</title>
        <para>In this block you can define the names of files or
        directories that ROBODoc should ignore while scanning 
        the directory tree for source files.  You can use the
        wildcard symbols <literal>*</literal> and
        <literal>?</literal>.
        </para>

        <para> For instance, the example rc file above causes ROBODoc
        to skip all <filename>README</filename> files, all files with
        the name <filename>CVS</filename> (these are usually
        directories).  It also skips all files with a name that ends
        with <filename>.bak</filename> or <filename>~</filename> or
        that start with <filename>test_</filename> </para>
    </section>

    <section><title>Configuration file location</title>

    <para>ROBODoc searches the your current directory for the
    <filename>robodoc.rc</filename> file.  With the
    <option>--rc</option> option can tell ROBODoc to use a different
    file then <filename>robodoc.rc</filename> as configuration file.
    The is handy if you want to create documentation in different
    formats.  For instance: </para>

<programlisting>
robodoc --rc  htmlsingle.rc
robodoc --rc  rtfsingle.rc
robodoc --rc  htmlmulti.rc
</programlisting>

    </section>

</section>


<!-- 
  ========== H I S T O R Y  ===========
  -->


<section>
<title>Examples</title>

<section>
<title>HTML Example</title>
  <para> For this you need a web browser, say mozilla.  You can try
  this in the robodoc root directory.  It creates a document called
  <filename>HDocs/masterindex.html</filename> plus a lot of smaller
  documents from all the source files in the directory
  <filename>Source</filename>.</para>

<programlisting>
robodoc --src ./Source --doc ./HDocs --multidoc --index --html
</programlisting>
</section>

<section>
<title>RTF Example</title>

    <para>For this you need an rtf reader, for instance
    <command>Word</command>.  You can try this in the robodoc root
    directory.</para>

<programlisting>
robodoc --src ./Source --doc api --singledoc --rtf --sections
</programlisting>

    <para>This will create a document called
    <filename>api.rtf</filename>.</para>

    <para>By default the document looks pretty plain.  There is no
    chapter numbering or a table of contents, even if you asked for
    it.  All the information for this is included but not visible.
    This is because chapter numbering and a table of contents are
    generated by Word based on formatting information that is part of
    a Word document but not part of a RTF document.  </para>

    <para>To make it visible you include the generated document into a
    bigger document with the right formatting options.  This is best
    done with a cut-and-paste operation.  Use the cut-past-paste
    special menu, and paste it as RTF formatted text into your Word
    document.</para>

</section>

<section>
<title>LaTeX Example</title>

  <para> For this you need <command>latex</command> and
  <command>makeindex</command>. You can try this in the robodoc root
  directory.  It creates a single document called
  <filename>api.dvi</filename> from all the source files in the
  directory Source.</para>

<programlisting>
robodoc --src ./Source --doc api --singledoc --latex --sections
latex api.tex
latex api.tex
makeindex api.idx
latex api.tex
xdvi api.dvi
</programlisting>
</section>

<section>
<title>XML DocBook Example</title>

  <para> For this you need <command>xmlto</command> You can try this
  in the robodoc root directory.  It creates a single document called
  <filename>api.xml</filename> from all the source files in the
  directory Source.  The <command>xmlto</command> then creates
  a browsable HTML document from this.</para>

<programlisting>
robodoc --src ./Source --doc api --singledoc --dbxml --sections
xmlto html api.xml
</programlisting>

  <para>To create a PDF document use:</para>
<programlisting>
xmlto pdf api.xml
</programlisting>

</section>
</section>


<section>
<title>Tips and Tricks</title>

<section>
<title>Using ROBODoc under Windows</title>
    <para>When you use ROBODoc under windows, don't forget that it is
    a command line tool.  ROBODoc relies on the console window to
    inform you about problems and errors.</para>

    <para>An easy mistake to make it to create a shortcut to
    <literal>robodoc.exe</literal> and then click on the icon to
    generate the documentation each time you made some changes to your
    source code.  If you have a fast machine a console window pops up
    quickly and after that your documentation is ready.</para>

    <para>This works very fine until you make a mistake in one of your
    headers.  The console window still pops up, but before you have a chance
    to read any of the error messages it is gone again.  Most likely
    you won't even have noticed there were error messages.  You will
    end up with empty documentation or old documentation.  </para>

    <para>Better is to create a batch file with the following commands
    and to store all the options in a <literal>robodoc.rc</literal>
    file:</para>
<programlisting>
robodoc.exe
pause
</programlisting>
    <para>Now the console window stays open and you have the
    opportunity to read the error messages.</para>

    <para>While the window is open, right click on the title bar,
    go to properties->layout and set the buffer size to something
    like 2500. That way you can scroll back too the next time
    you run it.</para>

</section>

<section>
<title>The SOURCE Item</title>

    <para> With a little extra work you can include part of your
    source code into your documentation to.  The following example
    shows how this is done:</para>

<programlisting>
/****f* Robodoc/RB_Panic [2.0d]
 * NAME
 *   RB_Panic - Shout panic, free resources, and shut down.
 * SYNOPSIS
 *   RB_Panic (cause, add_info)
 *   RB_Panic (char *, char *)
 * FUNCTION
 *   Prints an error message.
 *   Frees all resources used by robodoc.
 *   Terminates program.
 * INPUTS
 *   cause    - pointer to a string which describes the
 *              cause of the error.
 *   add_info - pointer to a string with additional information.
 * SEE ALSO
 *   RB_Close_The_Shop ()
 * SOURCE
 */

  void RB_Panic (char *cause, char *add_info)
  {
    printf ("Robodoc: Error, %s\n",cause) ;
    printf ("         %s\n", add_info) ;
    printf ("Robodoc: Panic Fatal error, closing down...\n") ;
    RB_Close_The_Shop () ; /* Free All Resources */
    exit(100) ;
  }

/*******/
</programlisting>

    <para>You add a SOURCE item as the last item of your header. Then
    instead of closing your header with an end marker, you close it
    normally.  The end marker is instead placed at the end of the
    fragment of source code that you want to include.  </para>

    <para>SOURCE items are included by default.  If want to create a
    document without the SOURCE items use the option
    <option>--nosource</option>.</para>

</section>

<section>
<title>Advanced formating with raw HTML and LaTeX code</title>

    <para> By default an item's body shows up in your documentation in
    the same way as it is formatted in your source code.  All special
    characters for the output mode are escaped.  For instance an &lt;
    is translated to a &amp;lt; in HTML mode.  Sometimes however you
    like to have some more control of what goes into the
    documentation.  This is possible with the piping.  If a line of
    your item's body starts with on of the special piping markers, the
    text after this marker is copied verbatim into your documentation.
    The following example shows how this is done, and how to add
    equations to your documentation.
    </para>

<programlisting>
/****m* pipe/pipetest
 * NAME
 *   pipetest
 * NAME
 *   Simple header to show "piping" features in items. 
 * EXAMPLE
 *   Only "pipes" which match selected output style are picked up. 
 *   |html &lt;CENTER&gt;This will be included in &lt;B&gt;HTML&lt;/B&gt; output.&lt;/CENTER&gt;
 *   |latex \centerline{This will be included in \LaTeX output}
 *   Space is mandatory following the pipe marker. The following is not a
 *   valid pipe marker:
 *   |html&lt;B&gt;Moi!&lt;/B&gt;
 *   You should see an equation on the following line:
 *   |html y = x^2 (sorry, plain HTML is not very powerful)
 *   |latex \centerline{$y = x^2$}
 *   How does this look like?
 *   Here comes a multi-line equation array:
 *    |latex \begin{eqnarray}
 *    |latex \frac{\partial u}{\partial \tau} &amp; = &amp; D_u {\nabla}^2 u + 
 *    |latex \frac{1}{\epsilon}
 *    |latex \left ( \hat{u}-{\hat{u}}^2-f\, {v} \, \frac{\hat{u}-q}{\hat{u}+q}
 *    |latex \right ) \; ,  \label{diffspot:1} \\
 *    |latex \frac{\partial v}{\partial \tau} &amp; = &amp; \hat{u}-v \; ,  
 *    |latex \label{diffspot:2} \\
 *    |latex \frac{\partial r}{\partial \tau} &amp; = &amp; D_r {\nabla}^2 r \; .
 *    |latex \label{diffspAot:3}
 *    |latex \end{eqnarray}
 *    |html &lt;I&gt;TODO: write this in html&lt;/I&gt;
 *   End of the example.
 ******
 */
</programlisting>

</section>


<section>
<title>Linking to external documents (href, file, mailto, images)</title>

    <para> In HTML mode ROBODoc recognizes the following links to
    external documents.  </para>

    <itemizedlist> 

    <listitem> <literal>href:body</literal> -- This is replaced with
      <literal>&lt;a href="body"&gt;body&lt;/A&gt;</literal>
    </listitem>

    <listitem> <literal>file:/body</literal> -- This is replaced with
    <literal>&lt;a href="file:/body"&gt;file:/body&lt;/A&gt;</literal>
    </listitem>

    <listitem> <literal>mailto:body</literal> -- This is replaced with
    <literal>&lt;a href="mailto:body"&gt;body&lt;/A&gt;</literal>
    </listitem>

    <listitem> <literal>http://body</literal> -- This is replaced with
    <literal>&lt;a href="http://body"&gt;http://body&lt;/A&gt;</literal>
    </listitem>

    <listitem> <literal>image:body</literal> -- This is replaced with 
    <literal>&lt;image src="body"&gt;</literal>
    </listitem>

    </itemizedlist> 
</section>


<section>
<title>Linking from an external document.</title>

    <para>To link from an external document to one of the HTML
    documents generated by ROBODoc you need a label.  ROBODoc creates
    two labels for each header. The first one starts with
    <literal>robo</literal> followed by a number.  You can not use
    this one because the numbers will change each time you run
    ROBODoc.  The second label is an escaped version of the whole
    header name.  In this label all the non alphanumeric characters of
    the name are replaced by their two digit hexadecimal code.</para>

    <para>An example, if your header name is
    <literal>Analyser/RB_ToBeAdded</literal> the label is
    <literal>Analyser2fRB5fToBeAdded</literal>.  Here
    <literal>/</literal> was replaced by <literal>2f</literal> and
    <literal>_</literal> was replaced by <literal>5f</literal>.  As
    long as you do not change the header name, this label stays the
    same each time you run ROBODoc.</para>

</section>

<!--
<section>
<title>Folds</title>

  <para>To be completed</para>

</section>
-->

</section>


<!--
<section>
<title>Extending ROBODoc</title>
    <para>To be completed</para>
</section>

-->

<section>
<title>Suggestions and Bugs</title>
    <para>If you find any bugs, catch them, put them in a jar, and
    send them to: rfsber {at} xs4all.nl.   Suggestions are also welcome at
    this address.  Flames can be directed to the sun.</para>
</section>

</article>