## ROBODoc 4.99.42 User Manual

### Frans Slothouber

### Petteri Kettunen

### Gergely Budai

Copyright © 1994-2013 Frans Slothouber, Petteri Kettunen, Jacco van Weert, Gergely Budai

Jul 2013

## 1. Preface

ROBODoc is an 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, XML, and many other languages. It can be made to work with any language that supports comments.

ROBODoc works by extracting specially formatted headers from your source code and writes these to documentation files. These files can be formatted in HTML, ASCII, XML DocBook, or RTF; and indirectly to PDF and HTML Help.

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.

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

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.

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.

ROBODoc is designed to work with a lot of different programming languages. It has no knowledge of the syntax of programming languages. It only has some knowledge about how comments 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.

## 2. Installing ROBODoc

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

You can also compile --- from the sources. On a system with autoconfig it is as simple as:

    ./configure
    make
    make install

This currently does not work with cygwin.

Under Windows you can use one of the makefile. There is a makefile for Borland C, MINGW, and Cygwin. For other compilers you might want to try `makefile.plain`.

For instance for cygwin goto `Source` and run:

    make -f makefile.mingw-cygwin

To install ROBODoc put the generated executable somewhere in your path.

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

## 3. Preparing your source code for ROBODoc

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.

### 3.1. Headers

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.

Example 1. A ROBODoc header in C.

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

- the name of the element that is being documented, StealMoney,

- the module it is part of, financial.library,

- the kind of element, `f`, which stands for function.

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:

Example 2. The markers needed by ROBODoc to recognize a header.

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

### 3.2. Header Types

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

Table 1. Default header types

c | Header for a class
d | Header for a constant (from define)
f | Header for a function
h | Header for a module in a project
m | Header for a method
s | Header for a structure
t | Header for a types
u | Header for a unit test
v | Header for a variable
* | Generic header for everything else

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.

### 3.3. Items

By default ROBODoc recognizes the following items:

NAME

  Item name plus a short description.

COPYRIGHT

  Who own the copyright : "(c) <year>-<year> by <company/person>"

SYNOPSIS , USAGE

  How to use it.

FUNCTION , DESCRIPTION , PURPOSE

  What does it do.

AUTHOR

  Who wrote it.

CREATION DATE

  When did the work start.

MODIFICATION HISTORY , HISTORY

  Who has done which changes and when.

INPUTS , ARGUMENTS , OPTIONS , PARAMETERS , SWITCHES

  What can we feed into it.

OUTPUT , SIDE EFFECTS

  What output is made.

RESULT , RETURN VALUE

  What do we get returned.

EXAMPLE

  A clear example of the items use.

NOTES

  Any annotations

DIAGNOSTICS

  Diagnostic output.

WARNINGS , ERRORS

  Warning and error-messages.

BUGS

  Known bugs.

TODO , IDEAS

  What to implement next and ideas.

PORTABILITY

  Where does it come from, where will it work.

SEE ALSO

  References to other functions, man pages, other documentation.

METHODS , NEW METHODS

  OOP methods.

ATTRIBUTES , NEW ATTRIBUTES

  OOP attributes.

TAGS

  Tag-item description.

DERIVED FROM

  OOP super class.

DERIVED BY

  OOP sub class.

USES , CHILDREN

  What modules are used by this one.

USED BY , PARENTS

  Which modules do use this one.

COMMANDS

  Command description.

SOURCE

  Source code inclusion.

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

### 3.4. Sections

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 `--sections`, 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

### 3.5. Smart Text Formatting

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.

Example 3. 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:

Example 4. A 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:

Example 5. A list where one of the items spans more than one line.

      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:

Example 6. an implicit 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:

Example 7. Preformatted text

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

The following is a complete example.

Example 8. All three elements of smart formatting.

        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

Example 9. The corresponding HTML output.

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

## 4. Extracting Documentation with ROBODoc

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.

### 4.1. Single document or many smaller documents

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

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

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

- singlefile -- in this mode ROBODoc scans a single source file and creates a single documentation file.

### 4.2. multidoc

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.

### 4.3. singledoc

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.

### 4.4. singlefile

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

### 4.5. Output formats

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

- HTML, option `--html`

- RTF, option `--rtf`

- LaTeX, option `--latex`

- XML DocBook, option `--dbxml`

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.

## 5. Examples of How to Create Documentation

### 5.1. HTML Example

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

### 5.2. RTF Example

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.

### 5.3. LaTeX Example

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

### 5.4. XML DocBook Example

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.

#### 5.4.1. DocBook with html output

The easiest to use is xsltproc. It works under Windows and Unix. A typical workflow under Windows is:

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

Where `api.xsl` contains:

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

For this you need xsltproc. For Windows these can be found at http://www.zlatkovic.com libxml.en.html, and the stylesheets which can be found at http://docbook.sourceforge.net/. In the example above the style sheets are installed on `e:/docbook/`.

More information about xsl can be found at http://www.sagehill.net/docbookxsl/.

#### 5.4.2. DocBook with html help output

The same program can be used to create a html help file. For this you need HTML Help Workshop . The workflow now is:

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

Where `api.xsl` contains:

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

## 6. Options

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

-c

  Show the copyright message.

--cmode

  Use ANSI C grammar in SOURCE items and use this for syntax highlighting (`HTML` only).

--css

  Use the content of the specified file to create the `robodoc.css`. The content of the file is copied into `robodoc.css`.

--dbxml

  Generate documentation in XML DocBook format.

--debug

  Works like --tell, bug gives a lot more information.

--doc

  Define the path to the documentation directory or documentation file. A path can start with `./` or `/`. Do not use `..` 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 --src ./sources together with --doc ./documents is fine, but --src ./Everything together with --doc ./Everything is not.

--doctype_name

  DocBook output requires a `<!DOCTYPE>` tag. With this option you can specify your own version of it. You have to use it in combination with --doctype_location. An example:

          robodoc --src test --doc test
              --doctype_location "-//OASIS//DTD Simplified DocBook XML V1.1//EN"
              --doctype_name docbook-simple/sdocbook.dtd
              --dbxml

  results in the following docbook file with the following head:

      <!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.1//EN"
      "docbook-simple/sdocbook.dtd">

--doctype_location

  See --doctype_name.

--headless

  Do not create the head of a document. This allows you to create documents that can be included in other documents, or to which you can add your own style.

  For html output this means that no `<html><head> ..... <body>` is generated.

  For LaTeX output this means none of the document initialization code is generated, such as `\documentclass{article}` or `\begin{document}` is generated. If you use this option in combination with `--footless` you can use `\include` or `\input` commands to include the ROBODoc generated documents in a larger document.

  For XML DocBook output this means no `<!DOCTYPE>`, `<article>`, and `<articleinfo>` is generated.

--first_section_level

  Make the first section start at the specified level instead of 1. This is useful if you want to include the generated documentation in another document.

--footless

  Do not create the foot of a document. This allows you to create documents that can be included in other documents, or to which you can add your own style.

  For html output this means that no `</body></html>` is generated.

  For LaTeX output this means no `\end{document}` is generated.

  For XML DocBook output this means no `</article>` is generated.

--html

  Generate documentation in HTML format.

--ignore_case_when_linking

  Ignore differences in case when creating cross links. This is handy for languages such as Fortran or Pascal, but in most cases it is better not to use it.

--internal

  Also include headers marked internal.

--internalonly

  Only include headers marked internal.

--index

  Also create a master index file.

--lock

  Per source file robodoc locks on the first header marker it finds and will recognize only that particular header marker 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.

--multidoc

  Generate one document per source file, and copy the directory hierarchy.

--nosource

  Do not include the SOURCE items.

--no_subdirectories

  Do not create any subdirectories in the documentation directory instead write all the documentation files in the root directory. The root directory is the one specified with `--doc`.

--nodesc

  Do not scan any subdirectories, scan only the top level directory of the source tree.

--nosort

  Do not sort the headers when generating the documentation. The headers will appear in the same order in the documentation as they appear in the source code.

--nopre

  With this option ROBODoc does not generate preformatted text when creating the item documentation. (Using the `<PRE>` and `</PRE>` construction in HTML format for instance). Instead ROBODoc tries to deduce the formatting from the indentation and special characters. See Smart Text Formatting. This creates much better looking documentation.

--nogeneratedwith

  Do not add the "generated with robodoc" message at the top of each documentation file.

--one_file_per_header

  Create a separate documentation file for each header.

--rc

  Use the specified file instead of `robodoc.rc`.

--rtf

  Generate documentation in RTF format.

--sections

  Create sections based on the module hierarchy.

--sectionnameonly

  ROBODoc generates the section headers with names only, no chapter numbers, no parent section names.

--singledoc

  Define the documentation directory or documentation file.

--singlefile

  Generate a single document from a single file

--src

  Define the path for the source directory or source file. The path can start with `./` or `/`. Do not use `..` in the path.

--tabsize

  Lets you specify the tab size.

--tabstops

  Specify tab stop locations in a comma separated list.

  Example: `--tabstops 10,20,40,80`

--toc

  Add a table of contents. This works in multidoc mode as well as singledoc mode.

--latex

  Generate documentation in `LaTeX` format.

--tell

  ROBODoc tells you what steps it is taking.

--documenttitle

  Specify the Title of the whole documentation.

--altlatex

  Alternate `LaTeX` file format (bigger / clearer than normal).

--latexparts

  Make the first module level as `PART` in `LaTeX` output (Gives you one more subsection level).

--syntaxcolors_enable

  Enable only specific syntax highlighting features in `SOURCE` items (`HTML` only).

  Usage: `--syntaxcolors_enable quotes,squotes,line_comments,block_comments,keywords,non_alpha`

  - `quotes` -- Enable highlighting of `"string literals"`
  - `squotes` -- Enable highlighting of `'string literals'`
  - `line_comments` -- Enable highlighting of comments that span until the end of lines (See source line comments block)
  - `block_comments` -- Enable highlighting of block comments (See remark begin markers and remark end markers block)
  - `keywords` -- Enable highlighting of keywords (See keywords block)
  - `non_alpha` -- Enable highlighting of non alphanumeric characters (like: `#`, `$`, `%`, etc...)

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

  See also the `--syntaxcolors` option.

--syntaxcolors

  Turn on all syntax highlighting features in `SOURCE` items (`HTML` only).

  This option equals to: `--syntaxcolors_enable quotes,squotes,line_comments,block_comments,keywords,non_alpha`

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

  See also the `--syntaxcolors_enable` option.

--dotname

  Specify the name (and path / options) of `DOT` tool.

  See Using external tools.

--masterindex

  Specify the title and filename of the master index page

  Usage: `--masterindex `title`,`filename``

  Example: `--masterindex "Index Page,index"`

--sourceindex

  Specify the title and filename of the source files index page

  Usage: `--sourceindex `title`,`filename``

  Example: `--sourceindex "Source files,sources"`

--header_breaks

  If a header has multiple names, ROBODoc can insert line breaks after every specified number of header names to improve readability. If you do not specify this option, ROBODoc will insert a line break after every two header names. Set it to zero to disable the line breaks.

  Example: `--header_breaks 3`

--source_line_numbers

  Display original source line numbers for SOURCE items.

## 7. Customizing ROBODoc

ROBODoc can be configured with a configuration file called `robodoc.rc`. With it you can define item names, frequently used options, and translations for English terms. One should note that if a configuration file is specified, its definitions over-ride ROBODoc internal (i.e. built-in) settings. This is a feature; some arbitrary language may include syntax which conflicts with ROBODoc's internal markers. By taking advantage of a configuration file, these sort of issues and conflicts can be circumvented. An example is shown below.

    # Example robodoc.rc
    #
    items:
        NAME
        FUNCTION
        SYNOPSIS
        INPUTS
        OUTPUTS
        SIDE EFFECTS
        HISTORY
        BUGS
        EXAMPLE
    ignore items:
        HISTORY
        BUGS
    item order:
        FUNCTION
        SYNOPSIS
        INPUTS
        OUTPUTS
    source items:
        SYNOPSIS
    preformatted items:
        INPUTS
        OUTPUTS
    format items:
        FUNCTION
        SIDE EFFECTS
    options:
        --src ./source
        --doc ./doc
        --html
        --multidoc
        --index
        --tabsize 8
    headertypes:
        J  "Projects"          robo_projects    2
        F  "Files"             robo_files       1
        e  "Makefile Entries"  robo_mk_entries
        x  "System Tests"      robo_syst_tests
        q  Queries             robo_queries
    ignore files:
        README
        CVS
        *.bak
        *~
        "a test_*"
    accept files:
        *.c
        *.h
        *.pl
    header markers:
        /****
        #****
    remark markers:
        *
        #
    end markers:
        ****
        #****
    header separate characters:
        ,
    header ignore characters:
        [
    remark begin markers:
        /*
    remark end markers:
        */
    source line comments:
        //
    keywords:
        if
        do
        while
        for

The configuration file consists of a number of blocks. Each block starts with a name followed by a `:`. In each block you define a number of values. Each value must start with at least one space.

### 7.1. items block

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.

### 7.2. ignore items block

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.

### 7.3. item order block

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.

### 7.4. source items block

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

### 7.5. preformatted items block

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.

### 7.6. format items block

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.

### 7.7. options block

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.

### 7.8. headertypes block

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.

### 7.9. ignore files block

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.

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

### 7.11. header markers block

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.

### 7.12. remark markers block

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.

### 7.13. end markers block

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.

### 7.14. header separate characters block

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.

### 7.15. header ignore characters block

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]

### 7.16. remark begin markers and remark end markers block

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

### 7.17. 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`).

### 7.18. keywords block

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

### 7.19. Configuration file location

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

## 8. Tips and Tricks

### 8.1. The SOURCE Item

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.

### 8.2. Minimizing Duplicate Information

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

### 8.3. Advanced formatting with raw HTML and LaTeX code

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

### 8.4. Linking to external documents (href, file, mailto, images)

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

- `href:body` -- This is replaced with `<a href="body">body</A>`

- `file:/body` -- This is replaced with `<a href="file:/body">file:/body</A>`

- `mailto:body` -- This is replaced with `<a href="mailto:body">body</A>`

- `http://body` -- This is replaced with `<a href="http://body">http://body</A>`

- `image:body` -- This is replaced with `<image src="body">`

### 8.5. Linking from an external document

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.

### 8.6. Using external tools

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:

1. Arbitrary tool with passing data through stdin
2. Arbitrary tool without passing data through stdin
3. The `DOT` tool

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

### 8.7. ROBODoc-ing an existing project

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.

### 8.8. Using ROBODoc under Windows

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.

## 9. Languages Supported by Default

ROBODoc support a whole range of languages by default. These languages are listed in the following sections. For each language two example headers are shown. One example header without any source items and one example header with source items.

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

In addition for each language the corresponding entries in the `robodoc.rc` are shown. You do not need these, as ROBODoc has these entries built-in. They are shown to make it easier to determine what needs to be specified for languages that ROBODoc does not yet support.

You can also use these entries if you want to create a `robodoc.rc` that supports only a limited number of languages. This because if you specify your own markers, ROBODoc ignores any of the in-built markers.

### 9.1. C

Example 10. A simple header without any source items in C.

    /****f* ModuleName/Foo
    * FUNCTION
    *   Foo computes the foo factor
    *   using a fudge factor.
    ****
    */

Example 11. A header with source items in C.

    /****f* ModuleName/Foo
    * FUNCTION
    *   Foo computes the foo factor
    *   using a fudge factor.
    * SYNOPSIS
    */
    int Foo( int fudge )
    /*
    * INPUTS
    *   fudge -- the fudge factor
    * SOURCE
    */

     more source code..

    /*****/

Example 12. The robodoc.rc file required for C if it were not supported by default.

    header markers:
      /****
    remark markers:
      *
    end markers:
      ****
      /****
    remark begin markers:
      /*
    remark end markers:
      */

### 9.2. Modula-2

Example 13. A simple header without any source items in Modula-2.

    (****f* ModuleName/Foo
    * FUNCTION
    *   Foo computes the foo factor
    *   using a fudge factor.
    ****
    *)

Example 14. A header with source items in Modula-2.

    (****f* ModuleName/Foo
    * FUNCTION
    *   Foo computes the foo factor
    *   using a fudge factor.
    * SYNOPSIS
    *)
    int Foo( int fudge )
    (*
    * INPUTS
    *   fudge -- the fudge factor
    * SOURCE
    *)

     more source code..

    (*****)

Example 15. The robodoc.rc file required for Modula-2 if it were not supported by default.

    header markers:
      (****
    remark markers:
      *
    end markers:
      ****
      (****
    remark begin markers:
      (*
    remark end markers:
      *)

### 9.3. Pascal

Example 16. A simple header without any source items in Pascal.

    {****f* ModuleName/Foo
    * FUNCTION
    *   Foo computes the foo factor
    *   using a fudge factor.
    ****
    *}

Example 17. A header with source items in Pascal.

    {****f* ModuleName/Foo
    * FUNCTION
    *   Foo computes the foo factor
    *   using a fudge factor.
    * SYNOPSIS
    *}
    int Foo( int fudge )
    {*
    * INPUTS
    *   fudge -- the fudge factor
    * SOURCE
    *}

     more source code..

    {*****}

Example 18. The robodoc.rc file required for Pascal if it were not supported by default.

    header markers:
      {****
    remark markers:
      *
    end markers:
      ****
      {****
    remark begin markers:
      {*
    remark end markers:
      *}

### 9.4. C++

Example 19. A simple header without any source items in C++.

    //****f* ModuleName/Foo
    // FUNCTION
    //   Foo computes the foo factor
    //   using a fudge factor.
    //****

Example 20. A header with source items in C++.

    //****f* ModuleName/Foo
    // FUNCTION
    //   Foo computes the foo factor
    //   using a fudge factor.
    // SYNOPSIS
    int Foo( int fudge )
    // INPUTS
    //   fudge -- the fudge factor
    // SOURCE

     more source code..

    //****

Example 21. The robodoc.rc file required for C++ if it were not supported by default.

    header markers:
      //****
    remark markers:
      //
    end markers:
      //****

### 9.5. Tcl

Example 22. A simple header without any source items in Tcl.

    #****f* ModuleName/Foo
    # FUNCTION
    #   Foo computes the foo factor
    #   using a fudge factor.
    #****

Example 23. A header with source items in Tcl.

    #****f* ModuleName/Foo
    # FUNCTION
    #   Foo computes the foo factor
    #   using a fudge factor.
    # SYNOPSIS
    int Foo( int fudge )
    # INPUTS
    #   fudge -- the fudge factor
    # SOURCE

     more source code..

    #****

Example 24. The robodoc.rc file required for Tcl if it were not supported by default.

    header markers:
      #****
    remark markers:
      #
    end markers:
      #****

### 9.6. Perl

Example 25. A simple header without any source items in Perl.

    #****f* ModuleName/Foo
    # FUNCTION
    #   Foo computes the foo factor
    #   using a fudge factor.
    #****

Example 26. A header with source items in Perl.

    #****f* ModuleName/Foo
    # FUNCTION
    #   Foo computes the foo factor
    #   using a fudge factor.
    # SYNOPSIS
    int Foo( int fudge )
    # INPUTS
    #   fudge -- the fudge factor
    # SOURCE

     more source code..

    #****

Example 27. The robodoc.rc file required for Perl if it were not supported by default.

    header markers:
      #****
    remark markers:
      #
    end markers:
      #****

### 9.7. LaTeX/TeX

Example 28. A simple header without any source items in LaTeX/TeX.

    %****f* ModuleName/Foo
    % FUNCTION
    %   Foo computes the foo factor
    %   using a fudge factor.
    %****

Example 29. A header with source items in LaTeX/TeX.

    %****f* ModuleName/Foo
    % FUNCTION
    %   Foo computes the foo factor
    %   using a fudge factor.
    % SYNOPSIS
    int Foo( int fudge )
    % INPUTS
    %   fudge -- the fudge factor
    % SOURCE

     more source code..

    %****

Example 30. The robodoc.rc file required for LaTeX/TeX if it were not supported by default.

    header markers:
      %****
    remark markers:
      %
    end markers:
      %****

### 9.8. Postscript

Example 31. A simple header without any source items in Postscript.

    %****f* ModuleName/Foo
    % FUNCTION
    %   Foo computes the foo factor
    %   using a fudge factor.
    %****

Example 32. A header with source items in Postscript.

    %****f* ModuleName/Foo
    % FUNCTION
    %   Foo computes the foo factor
    %   using a fudge factor.
    % SYNOPSIS
    int Foo( int fudge )
    % INPUTS
    %   fudge -- the fudge factor
    % SOURCE

     more source code..

    %****

Example 33. The robodoc.rc file required for Postscript if it were not supported by default.

    header markers:
      %****
    remark markers:
      %
    end markers:
      %****

### 9.9. Occam

Example 34. A simple header without any source items in Occam.

    __****f* ModuleName/Foo
    __ FUNCTION
    __   Foo computes the foo factor
    __   using a fudge factor.
    __****

Example 35. A header with source items in Occam.

    __****f* ModuleName/Foo
    __ FUNCTION
    __   Foo computes the foo factor
    __   using a fudge factor.
    __ SYNOPSIS
    int Foo( int fudge )
    __ INPUTS
    __   fudge -- the fudge factor
    __ SOURCE

     more source code..

    __****

Example 36. The robodoc.rc file required for Occam if it were not supported by default.

    header markers:
      __****
    remark markers:
      __
    end markers:
      __****

### 9.10. Fortran 90

Example 37. A simple header without any source items in Fortran 90.

    __****f* ModuleName/Foo
    __ FUNCTION
    __   Foo computes the foo factor
    __   using a fudge factor.
    __****

Example 38. A header with source items in Fortran 90.

    __****f* ModuleName/Foo
    __ FUNCTION
    __   Foo computes the foo factor
    __   using a fudge factor.
    __ SYNOPSIS
    int Foo( int fudge )
    __ INPUTS
    __   fudge -- the fudge factor
    __ SOURCE

     more source code..

    __****

Example 39. The robodoc.rc file required for Fortran 90 if it were not supported by default.

    header markers:
      __****
    remark markers:
      __
    end markers:
      __****

## 10. Suggestions and Bugs

If you find any bugs, catch them, put them in a jar, and send them to: Frans Slothouber at frans.slothouber {at} gmail.com. Suggestions are also welcome at this address. Flames can be directed to the sun.