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

Better is 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 you can scroll back too the next time you run it.

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:

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

Note that ROBODoc will skip the first line after the line that contains SOURCE. In this case the line with */. This is to ensure that this line does not end up in the documentation. For C sources this is obvious, but for Tcl sources for instance, it is not. Tcl does not need a seperate line to close of a remark. So a Tcl programmer would be tempted to write:

#****f* ModA/foobar
# FUNCTION
#   foobar computes the foo factor of a given file.
# SOURCE
sub foobar( f )
{

}
#****

and end up without sub foobar( f ) in the documentation.

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

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

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

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.