ROBODoc 4.0.18 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 example is:

  ****f* financial.library/StealMoney  

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, f, which stands for function. ROBODoc always expects a module name and an element name separated by a /. So ModFoo/funcBar is a valid name, but funcBar is not. See Sections 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 *.

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.

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

<!--****     HTML Code
*
***

<!---****    HTML Code
*
***

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

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

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

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

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

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

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 # you can use the Tcl/Tk markers, and create headers such as:

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

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.

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 headertypes using the ROBODoc configuration file, robodoc.rc. See Customizing ROBODoc. 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 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.

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

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:

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:

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:

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.

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

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 frequently used options. The options you specify here are added to any options you specify on the command line.

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.

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

For instance, the example 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 test_

ROBODoc searches the your current directory for the robodoc.rc file. With the --rc option can tell ROBODoc to use a different file then robodoc.rc as configuration file. The 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

For this you need a web browser, say 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

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

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

To create a PDF document use:

xmlto pdf api.xml

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.

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

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.