ROBODoc 4.99.36 User Manual

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.

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

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:

  ****f* financial.library/StealMoney

It marks the beginning of a header. It also tells ROBODoc

ROBODoc always expects that a / separates the module name and an element name. So ModFoo/funcBar is a valid name, but funcBar is not. See Sections for more information.

Names can also contain spaces but ROBODoc won't create links to names with embedded spaces.

You can also have multiple names for a header. This is useful if you document similar objects together in one header (for example assembly subroutines with multiple jump-in points). Multiple names are separated by commas and can span over more than one line.

  ****f* financial.library/StealMoney, Steal_Money

In the above example all references found to StealMoney and Steal_Money in other headers will be automatically linked to this header. The separation character(s) can be specified by the header separate characters block. See Customizing ROBODoc for more information.

The end marker:

  ******

marks the end of a header.

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

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

In this case the item's name is FUNCTION.

Each line of an item starts with a remark marker. In this case *.

That what ROBODoc needs to recognize a header is therefore:

 /****f* financial.library/StealMoney
  *  NAME
  *
  *  SYNOPSIS
  *
  *  FUNCTION
  *
  *
  *
  *  INPUTS
  *
  *
  *
  *
  *
  *
  *
  *
  *
  *
  *
  *  RESULT
  *
  *
  *  EXAMPLE
  *
  *  NOTES
  *
  *  BUGS
  *
  *
  *
  *
  *  SEE ALSO
  *
  *
  ******

The above example is in C. ROBODoc supports many more languages though. See Languages Supported by Default.

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

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

If a single character is given, the type is defined as listed in the following table

If two characters are given, the first character should be i 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.

So /****if* Module/func1 defines an internal function called func1.

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

You can define your own header types using the ROBODoc configuration file, robodoc.rc. See headertypes block. This way you can document anything you like, for instance makefile entries, system tests, or exceptions.

By default ROBODoc recognizes the following items:

You can define your own items using the ROBODoc configuration file, robodoc.rc. See Customizing ROBODoc.

The structure of source code for a project is usually hierarchical. A project might consists of several applications, an application of several modules, a module of several functions or even sub modules. 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.

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

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

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

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

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

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

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

By default ROBODoc creates preformatted text in the output documentation for all the text it finds in an item. This means that the formatting of the output looks the same as the formatting of the text of an item. Line-breaks and indentation stay the same. This is easy but does not always create the best looking output.

ROBODoc can also try to deduce the formatting of your text based on the layout and indentation of your text and on special characters in the text. It works a bit similar to the input method of Wikis. In the context of this manual this is called Smart Formatting.

You switch this on with the option --nopre. ROBODoc now tries to find three kind of elements: paragraphs, lists, and preformatted text.

Paragraphs are separated by empty lines. So the following item has two paragraphs.

  FUNCTION
    This function does something.

    And it then does something else
    and a bit more.

A List starts with a line that ends with a ':' which is then followed by one or more list items. List items should start with '*', '-', or 'o'. So the following item contains a valid list:

  FUNCTION
     This function does:
     * a lot of foo
     * some snafuing
     * and a bit of foobarring.

A list item can span more than one line if the second and following lines are indented. So this is also a valid list:

  FUNCTION
     This function does:
     * a lot of foo and preprocessing of the
       raw input with the aid
       of the some magic
     * some snafuing
     * and a bit of foobarring.

If list items directly follow the name of a robodoc item they also form a valid list. So this is a valid list:

  INPUTS
    * inputname -- the name of the input file
    * outputname -- the name of the output file
    * n -- the number of characters to be written

Preformatted text is indicated by indenting it more that the surrounding text. The first non-empty line in an item determines the base indenting. Any lines with an indentation larger than this are preformatted. An example:

   FUNCTION
     The following lines are preformatted
        +--------+
        | A box  |
        |        |
        +--------+
     End of the preformatted text.

The following is a complete example.

    This is some example text.
    And some more.

    This is even more, and we start a list:
    * a list item
    * a list item
    * a list item

    And we can also do preformatted stuff
    by indenting
        +--------+
        |        |
        +--------+
    The box will stay.

will be turn into

    <p>This is some example text.
    And some more.</p>

    <p>This is even more, and we start a list:</p>
    <ul>
    <li>a list item</li>
    <li>a list item</li>
    <li>a list item</li>
    </ul>

    <p>And we can also do preformatted stuff
    by indenting</p>
    <pre>
        +--------+
        |        |
        +--------+
    </pre>
    <p> The box will stay.</p>

First of all, ROBODoc can be used in three modes.

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:

robodoc --src source directory --doc document directory --multidoc other options

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

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:

robodoc --src source directory --doc document file without extension --singledoc other options

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

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

robodoc --src source file --doc document file --singlefile other options

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

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.

For this you need a web browser, say FireFox or Mozilla. You can try this in the robodoc root directory. It creates a document called HDocs/masterindex.html plus a lot of smaller documents from all the source files in the directory Source.

robodoc --src ./Source --doc ./HDocs --multidoc --index --html

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

robodoc --src ./Source --doc api --singledoc --rtf --sections

This will create a document called api.rtf.

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.

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.

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

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

DocBook is a xml format to create technical documentation, see. DocBook.org. DocBook is quite nice. This manual for instance is written in DocBook and automatically translated into html and pdf format.

You can use the DocBook output of ROBODoc to create several other formats, for instance: html, pdf, html-help. For this you need a tool that can process a DocBook file. There are several of these tools.

robodoc --src ./Source --doc api --singledoc --dbxml --sections
xsltproc api.xsl api.xml > api.html

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
    <xsl:import href="e:/docbook/html/docbook.xsl"/>
    <xsl:param name="admon.graphics" select="1"/>
    <xsl:param name="section.autolabel" select="1"/>
</xsl:stylesheet>

robodoc --src ./Source --doc api --singledoc --dbxml --sections
xsltproc api.xsl api.xml
hhc htmlhelp.hhp

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
    <xsl:import href="e:/docbook/htmlhelp/htmlhelp.xsl"/>
    <xsl:param name="admon.graphics" select="1"/>
    <xsl:param name="section.autolabel" select="1"/>
</xsl:stylesheet>

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.

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.

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.

In this block you can define the order in which items are to appear in the generated documentation. The items listed here will appear in the given order in the generated documentation. Any remaining items appear after these items in the order they were found in the header. This allows you to make the documentation look more uniform.

In this block you can define the names of items that ROBODoc handles in the same way as the SOURCE item.

In this block you can define the names of items that should be always preformatted. This is useful if you have the --nopre option specified and want specific items (like input and output lists) to be automatically preformatted. See Smart Text Formatting for more information.

In this block you can define the names of items that should be formatted by the Smart Text Formatting feature (like function descriptions) even if the --nopre option has not been specified.

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.

See Options.

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

Additionally the sorting priority can also be specified for each header type. Headers with higher priority will appear earlier in the generated output. (For example you can make module definitions appear at the beginning of a page.) If this parameter is omitted, the header will have the priority 0 (lowest) by default. All pre-defined header types have zero priority, except "Header for a module in a project", which has the sorting priority 1. See Header Types.

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 * and ?. If you use spaces in the expression enclose the expression in quotes.

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

Normally you specify the names of directories here and do the filtering of file names with a accept files block.

In this block you can define the names of files that robodoc should accept. This test is carried out after the 'ignore files' filtering is performed. Any files that do not match the patterns in this block are ignored by ROBODoc.

If there is no accept files block all files are accepted.

In this block you define what ROBODoc will recognize as start of a header. If you use this block ROBODoc only recognizes these markers, any of the inbuilt markers will be ignored.

In this block you define what ROBODoc will recognize as start of remark. If you use this block ROBODoc only recognizes these markers, any of the inbuilt markers will be ignored.

In this block you define what ROBODoc will recognize as end of a header. If you use this block ROBODoc only recognizes these markers, any of the inbuilt markers will be ignored.

In this block you can specify the separation character(s) for multiple header names. The default character is "," (comma) if this block is missing. See Preparing your source code for ROBODoc for more information.

In this block you can specify character(s) where the evaluation of a header should stop. The default character is "[" if this block is missing. This is useful to supply additional information to the header that ROBODoc should not care about.

For example one can include the version number of the function:

  ****f* financial.library/StealMoney [2.0]

Some languages allow remarks to span more than one line. They start a remark with a begin marker and end it with another marker. For instance in C you can have:

   /* This is a
      multi-line remark.
    */

Here the markers are /* and */. If you tell ROBODoc what these markers are in a remark begin markers block and remark end markers block. ROBODoc can skip them in source items.

We illustrate this with an example. Say we have a language that start a remark with |* and *|. We define SYNOPSIS to be a source like item. If we now run ROBODoc on the without a remark begin markers and end markers block on the following piece of source,

|****f* Bar/foo
 * FUNCTION
 *   foo computes the foo factor.
 * SYNOPSIS
 *|
int foo( float correction )
|*
 * BUGS
 *   None
 * SOURCE
 *|  .
{
    return correction * 42.0;
}
|*****|

the extracted documentation will look like:

 FUNCTION
   foo computes the foo factor.
 SYNOPSIS
   *|
   int foo( float correction )
   |*
 BUGS
   None
 SOURCE
   *|  .
   {
      return correction * 42.0;
   }

because ROBODoc considers |* and *|.to be part of the source, and not part of the begin or end of a header.

If you add

remark begin markers:
       |*
remark end markers:
       *|

the output will look like:

 FUNCTION
   foo computes the foo factor.
 SYNOPSIS
   int foo( float correction )
 BUGS
   None
 SOURCE
   {
      return correction * 42.0;
   }

These markers will also be used to highlight block comments if the --syntaxcolors_enable block_comments option (or the --syntaxcolors option) is specified (Similar to source line comments block).

Here you can specify markers which start whole line comments. (Comments that span until the end of line like "//", "REM", ";", etc...) These lines will be highlighted in the generated HTML output if the --syntaxcolors_enable line_comments option (or the --syntaxcolors option) has been specified.

You don't need this if you have the --cmode option specified.

The default highlighting color can be changed in the CSS file (span.comment).

Here you can specify the keywords in your SOURCE items. These keywords will be highlighted in the generated HTML output if the --syntaxcolors_enable keywords option (or the --syntaxcolors option) has been specified. Keywords meant to be the language native ones (for, if, etc...).

You don't need this if you have the --cmode option specified.

The default highlighting color can be changed in the CSS file (span.keyword).

ROBODoc searches the your current directory for the robodoc.rc file. If it can't find it there it will search in $HOME/, then $HOMEDRIVE$HOMEPATH/, and finally in /usr/share/robodoc/.

With the --rc option you can tell ROBODoc to use a different file than robodoc.rc as configuration file. This is handy if you want to create documentation in different formats. For instance:

robodoc --rc  htmlsingle.rc
robodoc --rc  rtfsingle.rc
robodoc --rc  htmlmulti.rc

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

/****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) ;
  }

/*******/

You can 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.

SOURCE items are included by default. If you want to create a document without the SOURCE items use the option --nosource.

You can also make normal items work like the source item, see source items block.

It is always good to avoid having the same information in several different locations. It is easy to create headers that have a lot information duplication. Take for instance the following header.

/****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) ;
  }

/*******/

The name RB_Panic occurs five times. This is tedious to type and difficult to maintain. However with a the right robodoc.rc this can be changed to:

/****f* Robodoc/RB_Panic [2.0d]
 * SUMMARY
 *   Shout panic, free resources, and shut down.
 * SYNOPSIS
 */

void RB_Panic (char* cause, char *add_info)

/*
 * 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
 */
  {
    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) ;
  }

/*******/

RB_Panic occurs only twice now. In addition changes to the function definition only have to be done once.

The robodoc.rc required for this is:

# robodoc.rc file
items:
    SUMMARY
    SYNOPSIS
    INPUTS
    OUTPUTS
    SEE ALSO
    BUGS
source items:
    SYNOPSIS
remark begin markers:
    /*
remark end markers:
    */

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 < is translated to a &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 one 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.

/****m* pipe/pipetest
 * NAME
 *   pipetest
 * DESCRIPTION
 *   Simple header to show "piping" features in items.
 * EXAMPLE
 *   Only "pipes" which match selected output style are picked up.
 *   |html <CENTER>This will be included in <B>HTML</B> output.</CENTER>
 *   |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<B>Moi!</B>
 *   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} & = & 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} & = & \hat{u}-v \; ,
 *    |latex \label{diffspot:2} \\
 *    |latex \frac{\partial r}{\partial \tau} & = & D_r {\nabla}^2 r \; .
 *    |latex \label{diffspAot:3}
 *    |latex \end{eqnarray}
 *    |html <I>TODO: write this in html</I>
 *   End of the example.
 ******
 */

In HTML mode ROBODoc recognizes the following links to external documents.

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

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

You can also execute external tools from ROBODoc and even pass data to them. The output of these tools can be included in your documentation for instance.

There are several types of external tools you can use:

The following example shows how to use each of them.

/****m* tools/tooltest
 *
 * NAME
 *   Tooltest
 *
 * DESCRIPTION
 *   Example showing how to invoke external tools.
 *
 * EXAMPLE
 * This one sorts elements into the file href:nexus-6.txt
 * The input data is passed through stdin.
 *
 * |tool sort > nexus-6.txt
 * Zhora
 * Pris
 * Leon Kowalski
 * Roy Batty
 * Rachel
 * Rick Deckard?
 * |tool end
 *
 * We can also execute tools without having any stdin data.
 * In the following example the output is simply redirected into href:tears.txt
 *
 * |exec echo "All those moments will be lost in time like tears in rain." > tears.txt
 *
 * You can also include neat DOT graphs in your documentation.
 * This one shows a hash table.
 *
 * |dot start
 * digraph G {
 *   nodesep=.05;
 *   rankdir=LR;
 *   node [shape=record,width=.1,height=.1];
 *
 *   node0 [label = "<f0> |<f1> |<f2> |<f3> |<f4> |<f5> |<f6> | ",height=2.0];
 *   node [width = 1.5];
 *   node1 [label = "{<n> n14 | 719 |<p> }"];
 *   node2 [label = "{<n> a1  | 805 |<p> }"];
 *   node3 [label = "{<n> i9  | 718 |<p> }"];
 *   node4 [label = "{<n> e5  | 989 |<p> }"];
 *   node5 [label = "{<n> t20 | 959 |<p> }"] ;
 *   node6 [label = "{<n> o15 | 794 |<p> }"] ;
 *   node7 [label = "{<n> s19 | 659 |<p> }"] ;
 *
 *   node0:f0 -> node1:n;
 *   node0:f1 -> node2:n;
 *   node0:f2 -> node3:n;
 *   node0:f5 -> node4:n;
 *   node0:f6 -> node5:n;
 *   node2:p -> node6:n;
 *   node4:p -> node7:n;
 * }
 * |dot end
 *
 * DOT graphs can be also included by specifying external DOT files.
 *
 * |dotfile tree.dot
 *
 ******
 */

If you want to use the DOT tool, you need the Graphviz package. More information and the binaries can be found at http://www.graphviz.org/ . The created graphs are automatically included in the documentation (HTML and LaTeX only). If you generate PDF output from your LaTeX file and you want to include DOT graphs in it, you will also need the epstopdf utility. ROBODoc lets DOT generate PNG images for HTML output and PS images for LaTeX output. (Don't forget to convert all the generated PS images to PDF images with the epstopdf utility, if you are generating PDF output.)

The ROBODoc package includes also a standalone binary named robohdrs. This helper program can take clean source file and insert ROBODoc headers to functions, global variables, and macros. There are issues with this tool but it saves lots of cumbersome typing when starting on documenting an existing code-base with ROBODoc. Type man robohdrs or robohdrs -h for help. Example: robohdrs -s -p testproj -i "MODIFICATION HISTORY" -i IDEAS testproj.c

Note that robohdrs is supported on UNIX-like platforms only. It requires fork() and Exuberant Ctags 5.3.1 or newer.

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.

An easy mistake to make is to create a shortcut to robodoc.exe 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.

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.

It is Better to create a batch file with the following commands and to store all the options in a robodoc.rc file:

robodoc.exe
pause

Now the console window stays open and you have the opportunity to read the error messages.

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, the next time you run it, you can scroll back and view all error messages.