Docs/manual.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ROBODoc 4.99.34 User Manual</title><link rel="stylesheet" href="manual.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.72.0" /></head><body><div class="article" lang="en" xml:lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="id2434377"></a>ROBODoc 4.99.34 User Manual</h1></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Frans</span> <span class="surname">Slothouber</span></h3></div><div class="author"><h3 class="author"><span class="firstname">Petteri</span> <span class="surname">Kettunen</span></h3></div><div class="author"><h3 class="author"><span class="firstname">Gergely</span> <span class="surname">Budai</span></h3></div></div></div><div><p class="copyright">Copyright © 1994-2007
   4           Frans Slothouber, Petteri Kettunen,
   5           Jacco van Weert, Gergely Budai
   6         </p></div><div><p class="pubdate">Apr 2007</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id2488392">1. Preface</a></span></dt><dt><span class="section"><a href="#installing">2. Installing ROBODoc</a></span></dt><dt><span class="section"><a href="#preparing">3. Preparing your source code for ROBODoc</a></span></dt><dd><dl><dt><span class="section"><a href="#id2495696">3.1. Headers</a></span></dt><dt><span class="section"><a href="#header_types">3.2. Header Types</a></span></dt><dt><span class="section"><a href="#id2496633">3.3. Items</a></span></dt><dt><span class="section"><a href="#sections">3.4. Sections</a></span></dt><dt><span class="section"><a href="#formatting">3.5. Smart Text Formatting</a></span></dt></dl></dd><dt><span class="section"><a href="#id2498762">4. Extracting Documentation with ROBODoc</a></span></dt><dd><dl><dt><span class="section"><a href="#id2498774">4.1. Single document or many smaller documents</a></span></dt><dt><span class="section"><a href="#id2497592">4.2. multidoc</a></span></dt><dt><span class="section"><a href="#id2498822">4.3. singledoc</a></span></dt><dt><span class="section"><a href="#id2498869">4.4. singlefile</a></span></dt><dt><span class="section"><a href="#id2498898">4.5. Output formats</a></span></dt></dl></dd><dt><span class="section"><a href="#id2498342">5. Examples of How to Create Documentation</a></span></dt><dd><dl><dt><span class="section"><a href="#id2498347">5.1. HTML Example</a></span></dt><dt><span class="section"><a href="#id2498374">5.2. RTF Example</a></span></dt><dt><span class="section"><a href="#id2498448">5.3. LaTeX Example</a></span></dt><dt><span class="section"><a href="#id2498537">5.4. XML DocBook Example</a></span></dt></dl></dd><dt><span class="section"><a href="#options">6. Options</a></span></dt><dt><span class="section"><a href="#customizing">7. Customizing ROBODoc</a></span></dt><dd><dl><dt><span class="section"><a href="#id2502679">7.1. items block</a></span></dt><dt><span class="section"><a href="#id2502700">7.2. ignore items block</a></span></dt><dt><span class="section"><a href="#id2502714">7.3. item order block</a></span></dt><dt><span class="section"><a href="#sourceitems">7.4. source items block</a></span></dt><dt><span class="section"><a href="#id2502749">7.5. preformatted items block</a></span></dt><dt><span class="section"><a href="#id2502783">7.6. format items block</a></span></dt><dt><span class="section"><a href="#id2502813">7.7. options block</a></span></dt><dt><span class="section"><a href="#headertypes_block">7.8. headertypes block</a></span></dt><dt><span class="section"><a href="#id2502896">7.9. ignore files block</a></span></dt><dt><span class="section"><a href="#id2502963">7.10. accept files block</a></span></dt><dt><span class="section"><a href="#id2502981">7.11. header markers block</a></span></dt><dt><span class="section"><a href="#id2502994">7.12. remark markers block</a></span></dt><dt><span class="section"><a href="#id2503006">7.13. end markers block</a></span></dt><dt><span class="section"><a href="#separate_characters_block">7.14. header separate characters block</a></span></dt><dt><span class="section"><a href="#header_ignore_characters_block">7.15. header ignore characters block</a></span></dt><dt><span class="section"><a href="#remark_begin_end">7.16.
   7 remark begin markers and remark end markers block</a></span></dt><dt><span class="section"><a href="#linecomments">7.17. source line comments block</a></span></dt><dt><span class="section"><a href="#keywords">7.18. keywords block</a></span></dt><dt><span class="section"><a href="#id2503510">7.19. Configuration file location</a></span></dt></dl></dd><dt><span class="section"><a href="#id2504528">8. Tips and Tricks</a></span></dt><dd><dl><dt><span class="section"><a href="#id2504533">8.1. The SOURCE Item</a></span></dt><dt><span class="section"><a href="#id2504567">8.2. Minimizing Duplicate Information</a></span></dt><dt><span class="section"><a href="#id2504666">8.3. Advanced formatting with raw HTML and LaTeX code</a></span></dt><dt><span class="section"><a href="#id2504752">8.4. Linking to external documents (href, file, mailto, images)</a></span></dt><dt><span class="section"><a href="#id2504846">8.5. Linking from an external document</a></span></dt><dt><span class="section"><a href="#tools">8.6. Using external tools</a></span></dt><dt><span class="section"><a href="#id2505111">8.7. ROBODoc-ing an existing project</a></span></dt><dt><span class="section"><a href="#id2505169">8.8. Using ROBODoc under Windows</a></span></dt></dl></dd><dt><span class="section"><a href="#defaultheaders">9. Languages Supported by Default</a></span></dt><dd><dl><dt><span class="section"><a href="#id2504474">9.1. C</a></span></dt><dt><span class="section"><a href="#id2504152">9.2. Modula-2</a></span></dt><dt><span class="section"><a href="#id2506135">9.3. Pascal</a></span></dt><dt><span class="section"><a href="#id2506189">9.4. C++</a></span></dt><dt><span class="section"><a href="#id2506241">9.5. Tcl</a></span></dt><dt><span class="section"><a href="#id2506293">9.6. Perl</a></span></dt><dt><span class="section"><a href="#id2506344">9.7. LaTeX/TeX</a></span></dt><dt><span class="section"><a href="#id2506397">9.8. Postscript</a></span></dt><dt><span class="section"><a href="#id2506449">9.9. Occam</a></span></dt></dl></dd><dt><span class="section"><a href="#id2505449">10. Suggestions and Bugs</a></span></dt></dl></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2488392"></a>1. Preface</h2></div></div></div><p>ROBODoc is an API documentation tool for C, C++, Java, Assembler,
   8         Basic, Fortran, LaTeX, Postscript, Tcl/Tk, LISP, Forth, Perl, Shell
   9         Scripts, Makefiles, Occam, COBOL, DCL, Visual Basic, HTML, DB/C, XML,
  10         and many other languages.  It can be made to work with any language that
  11         supports comments.</p><p>ROBODoc works by extracting specially formatted headers from your
  12         source code and writes these to documentation files. These files can be
  13         formatted in HTML, ASCII, XML DocBook, or RTF; and indirectly to
  14         PDF and HTML Help.</p><p>ROBODoc is similar to JavaDoc, though the idea is much
  15         older than JavaDoc.  ROBODoc allows you to maintain a program and
  16         its documentation in a single file.  This makes it easier to keep
  17         your documentation up-to-date.</p><p>ROBODoc can be used to document anything you like,
  18         functions, methods, variables, definitions, test cases, makefile
  19         entries, and anything else you can think of.</p><p>It can create documentation consisting of many small files.
  20         For instance in HTML format for easy browsing and publication on
  21         the web.  It can also create a single file in LaTeX or RTF format
  22         for inclusion into bigger design documents.  The RTF format is
  23         suited to be included in Word documents.</p><p>ROBODoc allows you to separate internal documentation from
  24         external documentation.  In singledoc mode it can create a section
  25         layout based on the hierarchy of your modules.</p><p>ROBODoc is designed to work with a lot of different
  26         programming languages.  It has no knowledge of the syntax of
  27         programming languages.  It only has some knowledge about how
  28         comments start and end in a lot of programming languages.  This
  29         means that you sometimes have to do a little more work compared to
  30         other tools that have detailed knowledge of the syntax of a
  31         particular language.  They can use that knowledge to figure out
  32         some of the information automatically.  This usually also means
  33         that they work only with one or two languages.  </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="installing"></a>2. Installing ROBODoc</h2></div></div></div><p>The easiest way to install ROBODoc is to use one of the
  34     packages.  There are package for RedHat, Debian, OSX, and a precompiled
  35     executable for Windows.</p><p>You can also compile --- from the sources.  On a system
  36     with <span><strong class="command">autoconfig</strong></span> it is as simple as:</p><pre class="programlisting">
  37 ./configure
  38 make
  39 make install
  40 </pre><p>This currently does not work with cygwin.</p><p>Under Windows you can use one of the makefile. There is a makefile for Borland C, MINGW,
  41        and Cygwin.  For other compilers you might want to try  <code class="filename">makefile.plain</code>.
  42 </p><p>For instance for cygwin goto <code class="filename">Source</code> and run:</p><pre class="programlisting">
  43 make -f makefile.mingw-cygwin
  44 </pre><p>To install <span><strong class="command">ROBODoc</strong></span> put the generated executable somewhere in your path.</p><p>You can test your executable, by going to the
  45        <code class="filename">Examples/PerlExample</code> directory in the
  46        archive, and running <span><strong class="command">robodoc</strong></span>.
  47        This should create a directory
  48        called <code class="filename">Doc</code>.  In there you should now
  49        find a file called <code class="filename">masterindex.html</code>.
  50 </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="preparing"></a>3. Preparing your source code for ROBODoc</h2></div></div></div><p> ROBODoc allows you to mix the program documentation with
  51     the source code.  It does require though that this documentation
  52     has a particular layout so ROBODoc can recognize it.  There are
  53     three key concepts: headers, items, and sections.  </p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2495696"></a>3.1. Headers</h3></div></div></div><p>Headers are the building blocks of the documentation. Lets
  54     look at an example. The following header was taken from the
  55     documentation of the predecessor of ROBODoc, AutoDoc.</p><div class="example"><a id="robodocheader"></a><p class="title"><b>Example 1. A ROBODoc header in C.</b></p><div class="example-contents"><pre class="programlisting">
  56  /****f* financial.library/StealMoney
  57   *  NAME
  58   *    StealMoney -- Steal money from the Federal Reserve Bank. (V77)
  59   *  SYNOPSIS
  60   *    error = StealMoney( userName, amount, destAccount, falseTrail )
  61   *  FUNCTION
  62   *    Transfer money from the Federal Reserve Bank into the
  63   *    specified interest-earning checking account.  No records of
  64   *    the transaction will be retained.
  65   *  INPUTS
  66   *    userName    - name to make the transaction under.  Popular
  67   *                  favorites include "Ronald Reagan" and
  68   *                  "Mohamar Quadaffi".
  69   *    amount      - Number of dollars to transfer (in thousands).
  70   *    destAccount - A filled-in AccountSpec structure detailing the
  71   *                  destination account (see financial/accounts.h).
  72   *                  If NULL, a second Great Depression will be
  73   *                  triggered.
  74   *    falseTrail  - If the DA_FALSETRAIL bit is set in the
  75   *                  destAccount, a falseTrail structure must be
  76   *                  provided.
  77   *  RESULT
  78   *    error - zero for success, else an error code is returned
  79   *           (see financial/errors.h).
  80   *  EXAMPLE
  81   *    Federal regulations prohibit a demonstration of this function.
  82   *  NOTES
  83   *    Do not run on Tuesdays!
  84   *  BUGS
  85   *    Before V88, this function would occasionally print the
  86   *    address and home phone number of the caller on local police
  87   *    976 terminals.  We are confident that this problem has been
  88   *    resolved.
  89   *  SEE ALSO
  90   *    CreateAccountSpec(),security.device/SCMD_DESTROY_EVIDENCE,
  91   *    financial/misc.h
  92   ******
  93   * You can use this space for remarks that should not be included
  94   * in the documentation.
  95   */
  96 </pre></div></div><br class="example-break" /><p>A header consists of three different elements: a
  97     begin marker, a number of items, and an end marker.  The begin marker
  98     in the example is:</p><pre class="programlisting">
  99   ****f* financial.library/StealMoney
 100 </pre><p>It marks the beginning of a header.  It also tells ROBODoc
 101 </p><div class="itemizedlist"><ul type="disc"><li><p>the name of the element that is being documented, StealMoney,</p></li><li><p>the module it is part of, financial.library,</p></li><li><p>the kind of element, <code class="literal">f</code>, which stands for function.</p></li></ul></div><p>
 102     ROBODoc always expects that a <code class="literal">/</code> separates the module name and an element name.
 103     So <code class="literal">ModFoo/funcBar</code>
 104     is a valid name, but <code class="literal">funcBar</code> is not.
 105     See <a href="#sections" title="3.4.&#xA0;Sections">Sections</a> for more
 106     information.
 107 </p><p>
 108     Names can also contain spaces but ROBODoc won't create links to names with
 109     embedded spaces.
 110 </p><p>
 111     You can also have multiple names for a header. This is useful if you
 112     document similar objects together in one header (for example assembly
 113     subroutines with multiple jump-in points). Multiple names are separated by
 114     commas and can span over more than one line.
 115 </p><pre class="programlisting">
 116   ****f* financial.library/StealMoney, Steal_Money
 117 </pre><p>
 118     In the above example all references found to <code class="literal">StealMoney</code>
 119     and <code class="literal">Steal_Money</code> in other headers will be automatically
 120     linked to this header.
 121     The separation character(s) can be specified by the
 122     <a href="#separate_characters_block" title="7.14.&#xA0;header separate characters block">header separate characters block</a>.
 123     See <a href="#customizing" title="7.&#xA0;Customizing ROBODoc">Customizing ROBODoc</a> for more
 124     information.
 125 </p><p>
 126 The end marker:
 127 </p><pre class="programlisting">
 128   ******
 129 </pre><p>
 130     marks the end of a header.
 131     </p><p>Items begin with an item name and are followed by the
 132     item's body.  An example: </p><pre class="programlisting">
 133   *  FUNCTION
 134   *    Transfer money from the Federal Reserve Bank into the
 135   *    specified interest-earning checking account.  No records of
 136   *    the transaction will be retained.
 137 </pre><p>
 138     In this case the item's name is FUNCTION.
 139     </p><p>
 140     Each line of an item starts with a remark marker.  In this case
 141     <code class="literal">*</code>.
 142     </p><p>That what ROBODoc needs to recognize a header is therefore:</p><div class="example"><a id="id2488316"></a><p class="title"><b>Example 2. The markers needed by ROBODoc to recognize a header.</b></p><div class="example-contents"><pre class="programlisting">
 143  /****f* financial.library/StealMoney
 144   *  NAME
 145   *
 146   *  SYNOPSIS
 147   *
 148   *  FUNCTION
 149   *
 150   *
 151   *
 152   *  INPUTS
 153   *
 154   *
 155   *
 156   *
 157   *
 158   *
 159   *
 160   *
 161   *
 162   *
 163   *
 164   *  RESULT
 165   *
 166   *
 167   *  EXAMPLE
 168   *
 169   *  NOTES
 170   *
 171   *  BUGS
 172   *
 173   *
 174   *
 175   *
 176   *  SEE ALSO
 177   *
 178   *
 179   ******
 180 </pre></div></div><br class="example-break" /><p>
 181     The above example is in C.  ROBODoc supports many more
 182     languages though.  See <a href="#defaultheaders" title="9.&#xA0;Languages Supported by Default">Languages Supported by Default</a>.
 183     </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="header_types"></a>3.2. Header Types</h3></div></div></div><p> ROBODoc defines a number of header types.  You don't need
 184     to use them but they can be useful for sorting information.  The
 185     header type tells ROBODoc what kind of object you are documenting.
 186     This information allows ROBODoc to create more useful index
 187     tables.</p><p>The type is identified by one or two characters.  ROBODoc
 188     expects to find them after the fourth <code class="literal">*</code> in the
 189     begin marker.  So <code class="literal">#****f</code> is a valid marker,
 190     but <code class="literal">#**f**</code> is not.</p><p>If a single character is given, the type is defined as
 191     listed in the following table</p><div class="table"><a id="id2496438"></a><p class="title"><b>Table 1. Default header types</b></p><div class="table-contents"><table summary="Default header types" border="1"><colgroup><col align="left" /><col align="left" /></colgroup><tbody><tr><td align="left">c</td><td align="left">Header for a class </td></tr><tr><td align="left">d</td><td align="left">Header for a constant (from define)</td></tr><tr><td align="left">f</td><td align="left">Header for a function</td></tr><tr><td align="left">h</td><td align="left"><a id="header_type_h"></a>Header for a module in a project</td></tr><tr><td align="left">m</td><td align="left">Header for a method</td></tr><tr><td align="left">s</td><td align="left">Header for a structure</td></tr><tr><td align="left">t</td><td align="left">Header for a types</td></tr><tr><td align="left">u</td><td align="left">Header for a unit test</td></tr><tr><td align="left">v</td><td align="left">Header for a variable</td></tr><tr><td align="left">*</td><td align="left">Generic header for everything else</td></tr></tbody></table></div></div><br class="table-break" /><p>If two characters are given, the first character should be
 192     <code class="literal">i</code> and the second can be any of the other
 193     characters from the table above.  This creates an internal header
 194     of the type specified by the second character.  Internal headers
 195     are special.  They can be used to hide certain headers. They are
 196     only extracted if requested. You can use them to document internal
 197     functions, classes, etc. that you do not want clients to see,
 198     creating what might be a programmer's manual as opposed to a
 199     user's manual.</p><p>So <code class="literal">/****if* Module/func1</code> defines an
 200     internal function called <code class="literal">func1</code>.
 201     </p><p>Headers marked internal are by default not included in the
 202     generated documentation.  If you want to include them use the
 203     option <code class="option">--internal</code>.   You can also generate the
 204     documentation from only the internal headers with the option
 205     <code class="option">--internalonly</code>.
 206     </p><p>You can define your own header types using the ROBODoc
 207     configuration file, <code class="filename">robodoc.rc</code>.
 208     See <a href="#headertypes_block" title="7.8.&#xA0;headertypes block">headertypes block</a>.
 209     This way you can document anything you like, for instance makefile
 210     entries, system tests, or exceptions.
 211     </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2496633"></a>3.3. Items</h3></div></div></div><p> By default ROBODoc recognizes the following items: </p><div class="variablelist"><dl><dt><span class="term">
 212                 NAME
 213             </span></dt><dd><p>Item name plus a short description.
 214                 </p></dd><dt><span class="term">
 215                 COPYRIGHT
 216             </span></dt><dd><p>Who own the copyright : "(c) &lt;year&gt;-&lt;year&gt; by
 217                     &lt;company/person&gt;"
 218                 </p></dd><dt><span class="term">
 219                 SYNOPSIS
 220             , </span><span class="term">
 221                 USAGE
 222             </span></dt><dd><p>
 223                     How to use it.
 224                 </p></dd><dt><span class="term">
 225                 FUNCTION
 226             , </span><span class="term">
 227                 DESCRIPTION
 228             , </span><span class="term">
 229                 PURPOSE
 230             </span></dt><dd><p>
 231                     What does it do.
 232                 </p></dd><dt><span class="term">
 233                 AUTHOR
 234             </span></dt><dd><p>
 235                     Who wrote it.
 236                 </p></dd><dt><span class="term">
 237                 CREATION DATE
 238             </span></dt><dd><p>When did the work start.
 239                 </p></dd><dt><span class="term">
 240                 MODIFICATION HISTORY
 241             , </span><span class="term">
 242                 HISTORY
 243             </span></dt><dd><p>Who has done which changes and when.
 244                 </p></dd><dt><span class="term">
 245                 INPUTS
 246             , </span><span class="term">
 247                 ARGUMENTS
 248             , </span><span class="term">
 249                 OPTIONS
 250             , </span><span class="term">
 251                 PARAMETERS
 252             , </span><span class="term">
 253                 SWITCHES
 254             </span></dt><dd><p>
 255                     What can we feed into it.
 256                 </p></dd><dt><span class="term">
 257                 OUTPUT
 258             , </span><span class="term">
 259                 SIDE EFFECTS
 260             </span></dt><dd><p>What output is made.
 261                 </p></dd><dt><span class="term">
 262                 RESULT
 263             , </span><span class="term">
 264                 RETURN VALUE
 265             </span></dt><dd><p>
 266                     What do we get returned.
 267                 </p></dd><dt><span class="term">
 268                 EXAMPLE
 269             </span></dt><dd><p>
 270                     A clear example of the items use.
 271                 </p></dd><dt><span class="term">
 272                 NOTES
 273             </span></dt><dd><p>
 274                     Any annotations
 275                 </p></dd><dt><span class="term">
 276                 DIAGNOSTICS
 277             </span></dt><dd><p> Diagnostic output.
 278                 </p></dd><dt><span class="term">
 279                 WARNINGS
 280             , </span><span class="term">
 281                 ERRORS
 282             </span></dt><dd><p>Warning and error-messages.
 283                 </p></dd><dt><span class="term">
 284                 BUGS
 285             </span></dt><dd><p>Known bugs.
 286                 </p></dd><dt><span class="term">
 287                 TODO
 288             , </span><span class="term">
 289                 IDEAS
 290             </span></dt><dd><p>What to implement next and ideas. </p></dd><dt><span class="term">
 291                 PORTABILITY
 292             </span></dt><dd><p>Where does it come from, where will it work. </p></dd><dt><span class="term">
 293                 SEE ALSO
 294             </span></dt><dd><p>References to other functions, man pages, other documentation. </p></dd><dt><span class="term">
 295                 METHODS
 296             , </span><span class="term">
 297                 NEW METHODS
 298             </span></dt><dd><p>OOP methods.</p></dd><dt><span class="term">
 299                 ATTRIBUTES
 300             , </span><span class="term">
 301                 NEW ATTRIBUTES
 302             </span></dt><dd><p>OOP attributes.</p></dd><dt><span class="term">
 303                 TAGS
 304             </span></dt><dd><p>Tag-item description.
 305             </p></dd><dt><span class="term">
 306                 DERIVED FROM
 307             </span></dt><dd><p>OOP super class. </p></dd><dt><span class="term">
 308                 DERIVED BY
 309             </span></dt><dd><p>OOP sub class. </p></dd><dt><span class="term">
 310                 USES
 311             , </span><span class="term">
 312                 CHILDREN
 313             </span></dt><dd><p>What modules are used by this one. </p></dd><dt><span class="term">
 314                 USED BY
 315             , </span><span class="term">
 316                 PARENTS
 317             </span></dt><dd><p>Which modules do use this one. </p></dd><dt><span class="term">
 318                 COMMANDS
 319             </span></dt><dd><p>Command description. </p></dd><dt><span class="term">
 320                 SOURCE
 321             </span></dt><dd><p>Source code inclusion. </p></dd></dl></div><p>You can define your own items using the ROBODoc
 322     configuration file, <code class="filename">robodoc.rc</code>.  See <a href="#customizing" title="7.&#xA0;Customizing ROBODoc">Customizing ROBODoc</a>.  </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sections"></a>3.4. Sections</h3></div></div></div><p>The structure of source code for a project is usually
 323     hierarchical.  A project might consists of several applications,
 324     an application of several modules, a module of several functions
 325     or even sub modules.  ROBODoc allows you to show this hierarchy in
 326     your documentation.  For this you specify the hierarchy in the
 327     header name.  For instance,  you have a project that is going to
 328     create a new language called D.  The D Language project might
 329     consists of three applications: a preprocessor, a compiler, and a
 330     linker.  The compiler consists of two modules, a parser and a
 331     generator.  The parser module consists of several
 332     functions.</p><p>The following three headers show how this hierarchy can be
 333     defined in the header name.</p><pre class="programlisting">
 334 #****h* D-Language/Compiler
 335 # FUNCTION
 336 #   The compiler takes a preprocessed source file and
 337 #   turns it into an object file.
 338 #***
 339 </pre><pre class="programlisting">
 340 #****h* D-Language/Linker
 341 # FUNCTION
 342 #   The linker module contains functions that scan a
 343 #   object file and build the executable.
 344 #***
 345 </pre><pre class="programlisting">
 346 #****h* Compiler/Parser
 347 # FUNCTION
 348 #   The parser module contains functions that scan a
 349 #   preprocessed source file and build the syntax tree.
 350 #***
 351 </pre><pre class="programlisting">
 352 #****f* Parser/ReadToken
 353 # FUNCTION
 354 #   ReadToken reads the next token from the input
 355 #   file.
 356 #***
 357 </pre><p>When you generate documentation with the option
 358     <code class="option">--section</code>, ROBODoc uses the hierarchical
 359     information when generating the table of contents and document
 360     section information. For instance in HTML sections are started
 361     with &lt;H1&gt;,  &lt;H2&gt;,  &lt;H3&gt; depending on the level
 362     in the hierarchy.  The table of contents will also contain levels.  The
 363     table of contents for the above example will be: </p><pre class="programlisting">
 364 1. D-Language/Compiler
 365 1.1 Compiler/Parser
 366 1.1.1 Parser/ReadToken
 367 2. D-Language/Linker
 368 </pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="formatting"></a>3.5. Smart Text Formatting</h3></div></div></div><p>By default ROBODoc creates preformatted text in the output
 369 documentation for all the text it finds in an item.  This means
 370 that the formatting of the output looks the same as the formatting of
 371 the text of an item.  Line-breaks and indentation stay the same.
 372 This is easy but does not always create the best looking
 373 output.</p><p>ROBODoc can also try to deduce the formatting of your text based
 374 on the layout and indentation of your text and on special characters in the text.
 375 It works a bit similar to the input method of Wikis.  In the context of this
 376 manual this is called Smart Formatting.
 377 </p><p>You switch this on with the option <code class="option">--nopre</code>.
 378 ROBODoc now tries to find three kind of elements: paragraphs,
 379 lists, and preformatted text.</p><p>Paragraphs are separated by empty lines.  So the following item
 380 has two paragraphs.</p><div class="example"><a id="id2497225"></a><p class="title"><b>Example 3. Two paragraphs.</b></p><div class="example-contents"><pre class="programlisting">
 381   FUNCTION
 382     This function does something.
 383
 384     And it then does something else
 385     and a bit more.
 386 </pre></div></div><br class="example-break" /><p> A List starts with a line that ends with a ':' which is then
 387 followed by one or more list items. List items should start with '*',
 388 '-', or 'o'.   So the following item contains a valid list: </p><div class="example"><a id="id2497246"></a><p class="title"><b>Example 4. A list.</b></p><div class="example-contents"><pre class="programlisting">
 389   FUNCTION
 390      This function does:
 391      * a lot of foo
 392      * some snafuing
 393      * and a bit of foobarring.
 394 </pre></div></div><br class="example-break" /><p> A list item can span more than one line if the second and following
 395 lines are indented.  So this is also a valid list:</p><div class="example"><a id="id2497265"></a><p class="title"><b>Example 5. A list where one of the items spans more than one line.</b></p><div class="example-contents"><pre class="programlisting">
 396   FUNCTION
 397      This function does:
 398      * a lot of foo and preprocessing of the
 399        raw input with the aid
 400        of the some magic
 401      * some snafuing
 402      * and a bit of foobarring.
 403 </pre></div></div><br class="example-break" /><p>If list items directly follow the name of a robodoc item they
 404 also form a valid list.  So this is a valid list:</p><div class="example"><a id="id2497287"></a><p class="title"><b>Example 6. an implicit list</b></p><div class="example-contents"><pre class="programlisting">
 405   INPUTS
 406     * inputname -- the name of the input file
 407     * outputname -- the name of the output file
 408     * n -- the number of characters to be written
 409 </pre></div></div><br class="example-break" /><p> Preformatted text is indicated by indenting it more that the
 410 surrounding text.  The first non-empty line in an item determines the
 411 base indenting.  Any lines with an indentation larger than this are
 412 preformatted.  An example:</p><div class="example"><a id="id2497309"></a><p class="title"><b>Example 7. Preformatted text</b></p><div class="example-contents"><pre class="literallayout">
 413    FUNCTION
 414      The following lines are preformatted
 415         +--------+
 416         | A box  |
 417         |        |
 418         +--------+
 419      End of the preformatted text.
 420 </pre></div></div><br class="example-break" /><p>The following is a complete example.</p><div class="example"><a id="fullsmart"></a><p class="title"><b>Example 8. All three elements of smart formatting.</b></p><div class="example-contents"><pre class="literallayout">
 421     This is some example text.
 422     And some more.
 423
 424     This is even more, and we start a list:
 425     * a list item
 426     * a list item
 427     * a list item
 428
 429     And we can also do preformatted stuff
 430     by indenting
 431         +--------+
 432         |        |
 433         +--------+
 434     The box will stay.
 435 </pre></div></div><br class="example-break" /><p>will be turn into</p><div class="example"><a id="fulloutput"></a><p class="title"><b>Example 9. The corresponding HTML output.</b></p><div class="example-contents"><pre class="literallayout">
 436     &lt;p&gt;This is some example text.
 437     And some more.&lt;/p&gt;
 438
 439     &lt;p&gt;This is even more, and we start a list:&lt;/p&gt;
 440     &lt;ul&gt;
 441     &lt;li&gt;a list item&lt;/li&gt;
 442     &lt;li&gt;a list item&lt;/li&gt;
 443     &lt;li&gt;a list item&lt;/li&gt;
 444     &lt;/ul&gt;
 445
 446     &lt;p&gt;And we can also do preformatted stuff
 447     by indenting&lt;/p&gt;
 448     &lt;pre&gt;
 449         +--------+
 450         |        |
 451         +--------+
 452     &lt;/pre&gt;
 453     &lt;p&gt; The box will stay.&lt;/p&gt;
 454 </pre></div></div><br class="example-break" /></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2498762"></a>4. Extracting Documentation with ROBODoc</h2></div></div></div><p>Now that you have prepared your source code for use with
 455     ROBODoc you are ready to extract the documentation.  There are
 456     several choices to be made.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2498774"></a>4.1. Single document or many smaller documents</h3></div></div></div><p>First of all, ROBODoc can be used in three modes.</p><div class="itemizedlist"><ul type="disc"><li><p>multidoc -- in this mode ROBODoc scans
 457     all the source files in your source directory and creates a
 458     separate document file for each of these in a document directory.
 459     The document directory is created automatically. Its structure is
 460     a mirror of the structure of your source directory.</p></li><li><p>singledoc -- in this mode ROBODoc scans all the source
 461     files in your source directory and creates a single documentation
 462     file that contains all the documentation extracted from your
 463     source files.  </p></li><li><p>singlefile -- in this mode ROBODoc scans a single source
 464     file and creates a single documentation file.</p></li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2497592"></a>4.2. multidoc</h3></div></div></div><p>The multidoc mode is useful to create browsable documents.
 465     For instance many small HTML files that can be viewed with a
 466     web-browser.  This mode requires the following arguments:</p><p>
 467     <span><strong class="command">robodoc
 468     --src <em class="replaceable"><code>source directory</code></em>
 469     --doc <em class="replaceable"><code>document directory</code></em>
 470     --multidoc
 471     other options
 472     </strong></span>
 473 </p><p>An additional option that is useful with this mode is
 474     <code class="option">--index</code>, this creates a series of index files,
 475     one for each header type.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2498822"></a>4.3. singledoc</h3></div></div></div><p> The singledoc mode is useful to create bulk documentation
 476     that can be incorporated in other documents, or that can be
 477     delivered to a client as a single document.  For instance a file
 478     created in RTF format can be included into a larger design
 479     document written in Word format.  This mode requires the following
 480     arguments:</p><p>
 481     <span><strong class="command">robodoc
 482         --src <em class="replaceable"><code>source directory</code></em>
 483         --doc <em class="replaceable"><code>document file without extension</code></em>
 484         --singledoc
 485         <em class="replaceable"><code>other options</code></em>
 486     </strong></span>
 487 </p><p>An additional option that is useful with this mode is
 488     <code class="option">--sections</code>, this causes the headers to follow a
 489     section layout based on the module element hierarchy defined in the
 490     header name.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2498869"></a>4.4. singlefile</h3></div></div></div><p>The singlefile mode is not very useful.  It is mainly used
 491     for debugging purposes.  This mode requires the following
 492     arguments:</p><p>
 493     <span><strong class="command">robodoc
 494     --src <em class="replaceable"><code>source file</code></em>
 495     --doc <em class="replaceable"><code>document file</code></em>
 496     --singlefile
 497     other options
 498 </strong></span>
 499 </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2498898"></a>4.5. Output formats</h3></div></div></div><p>Your next choice is the output format. ROBODoc can create
 500     documentation in several formats:</p><div class="itemizedlist"><ul type="disc"><li><p>HTML, option <code class="option">--html</code></p></li><li><p>RTF, option <code class="option">--rtf</code></p></li><li><p>LaTeX, option <code class="option">--latex</code></p></li><li><p>XML DocBook, option <code class="option">--dbxml</code></p></li></ul></div><p>What format to use depends on your wishes. If you want a
 501     single printable document, use LaTeX or XML DocBook.  If you want
 502     a document that can be included into a larger (Word) document use
 503     RTF.  If you want something that is browsable use HTML, or use XML
 504     DocBook and then convert it to HTML.</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2498342"></a>5. Examples of How to Create Documentation</h2></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2498347"></a>5.1. HTML Example</h3></div></div></div><p> For this you need a web browser, say FireFox or Mozilla.  You can try
 505   this in the robodoc root directory.  It creates a document called
 506   <code class="filename">HDocs/masterindex.html</code> plus a lot of smaller
 507   documents from all the source files in the directory
 508   <code class="filename">Source</code>.</p><pre class="programlisting">
 509 <span><strong class="command">robodoc</strong></span> <code class="option">--src</code> ./Source <code class="option">--doc</code> ./HDocs <code class="option">--multidoc</code> <code class="option">--index</code> <code class="option">--html</code>
 510 </pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2498374"></a>5.2. RTF Example</h3></div></div></div><p>For this you need an rtf reader, for instance
 511     <span><strong class="command">Word</strong></span>.  You can try this in the robodoc root
 512     directory.</p><pre class="programlisting">
 513 <span><strong class="command">robodoc</strong></span> <code class="option">--src</code> ./Source <code class="option">--doc</code> api <code class="option">--singledoc</code> <code class="option">--rtf</code> <code class="option">--sections</code>
 514 </pre><p>This will create a document called
 515     <code class="filename">api.rtf</code>.</p><p>By default the document looks pretty plain.  There is no
 516     chapter numbering or a table of contents, even if you asked for
 517     it.  All the information for this is included but not visible.
 518     This is because chapter numbering and a table of contents are
 519     generated by Word based on formatting information that is part of
 520     a Word document but not part of a RTF document.  </p><p>To make it visible you include the generated document into a
 521     bigger document with the right formatting options.  This is best
 522     done with a cut-and-paste operation.  Use the cut-past-paste
 523     special menu, and paste it as RTF formatted text into your Word
 524     document.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2498448"></a>5.3. LaTeX Example</h3></div></div></div><p> For this you need <span><strong class="command">latex</strong></span> and
 525   <span><strong class="command">makeindex</strong></span>. You can try this in the robodoc root
 526   directory.  It creates a single document called
 527   <code class="filename">api.dvi</code> from all the source files in the
 528   directory Source.</p><pre class="programlisting">
 529 <span><strong class="command">robodoc</strong></span> <code class="option">--src</code> ./Source <code class="option">--doc</code> api <code class="option">--singledoc</code> <code class="option">--latex</code> <code class="option">--sections</code>
 530 <span><strong class="command">latex</strong></span> api.tex
 531 <span><strong class="command">latex</strong></span> api.tex
 532 <span><strong class="command">makeindex</strong></span> api.idx
 533 <span><strong class="command">latex</strong></span> api.tex
 534 <span><strong class="command">xdvi</strong></span> api.dvi
 535 </pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2498537"></a>5.4. XML DocBook Example</h3></div></div></div><p>
 536     DocBook is a xml format to create technical documentation, see.
 537     <a href="http://www.docbook.org/" target="_top"><em class="citetitle">DocBook.org</em></a>.
 538     DocBook is quite nice. This manual for instance is written in DocBook and
 539     automatically translated into html and pdf format.
 540 </p><p>
 541     You can use the DocBook output of ROBODoc to create several other formats,
 542     for instance: html, pdf, html-help.
 543     For this you need a tool that can process a DocBook file. There
 544     are several of these tools.
 545 </p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2498564"></a>5.4.1. DocBook with html output</h4></div></div></div><p>The easiest to use is <span><strong class="command">xsltproc</strong></span>. It works under
 546     Windows and Unix.  A typical workflow under Windows is:
 547 </p><pre class="programlisting">
 548 <span><strong class="command">robodoc</strong></span> <code class="option">--src</code> ./Source <code class="option">--doc</code> api <code class="option">--singledoc</code> <code class="option">--dbxml</code> <code class="option">--sections</code>
 549 <span><strong class="command">xsltproc</strong></span> api.xsl api.xml &gt; api.html
 550 </pre><p>
 551     Where <code class="filename">api.xsl</code> contains:
 552 </p><pre class="literallayout">
 553 &lt;?xml version='1.0'?&gt;
 554 &lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"&gt;
 555     &lt;xsl:import href="e:/docbook/html/docbook.xsl"/&gt;
 556     &lt;xsl:param name="admon.graphics" select="1"/&gt;
 557     &lt;xsl:param name="section.autolabel" select="1"/&gt;
 558 &lt;/xsl:stylesheet&gt;
 559
 560 </pre><p>For this you need <span><strong class="command">xsltproc</strong></span>. For Windows these can be found at
 561     <a href="http://www.zlatkovic.com/libxml.en.html" target="_top">
 562         <em class="citetitle">http://www.zlatkovic.com libxml.en.html</em></a>,
 563     and the stylesheets which can be found at
 564     <a href="http://docbook.sourceforge.net/" target="_top"><em class="citetitle">http://docbook.sourceforge.net/</em></a>.
 565     In the example above the style sheets are installed on <code class="filename">e:/docbook/</code>.
 566 </p><p>
 567     More information about xsl can be found at
 568     <a href="http://www.sagehill.net/docbookxsl/" target="_top"><em class="citetitle">http://www.sagehill.net/docbookxsl/</em></a>.
 569 </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id2499568"></a>5.4.2. DocBook with html help output</h4></div></div></div><p>The same program can be used to
 570     <a href="http://docbook.sourceforge.net/release/xsl/current/doc/htmlhelp.html" target="_top">
 571         <em class="citetitle">create a html help</em>
 572     </a> file. For this you need
 573     <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp" target="_top">
 574         <em class="citetitle">HTML Help Workshop</em>
 575     </a>. The workflow now is:
 576 </p><pre class="programlisting">
 577 <span><strong class="command">robodoc</strong></span> <code class="option">--src</code> ./Source <code class="option">--doc</code> api <code class="option">--singledoc</code> <code class="option">--dbxml</code> <code class="option">--sections</code>
 578 <span><strong class="command">xsltproc</strong></span> api.xsl api.xml
 579 <span><strong class="command">hhc</strong></span> htmlhelp.hhp
 580 </pre><p>
 581     Where <code class="filename">api.xsl</code> contains:
 582 </p><pre class="literallayout">
 583 &lt;?xml version='1.0'?&gt;
 584 &lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"&gt;
 585     &lt;xsl:import href="e:/docbook/htmlhelp/htmlhelp.xsl"/&gt;
 586     &lt;xsl:param name="admon.graphics" select="1"/&gt;
 587     &lt;xsl:param name="section.autolabel" select="1"/&gt;
 588 &lt;/xsl:stylesheet&gt;
 589
 590 </pre></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="options"></a>6. Options</h2></div></div></div><p>The behavior of ROBODoc can be further fine-tune with a large number of
 591         options.</p><div class="variablelist"><dl><dt><span class="term">-c</span></dt><dd><p>Show the copyright message.</p></dd><dt><a id="cmode"></a><span class="term"><a id="cmode.term"></a>--cmode</span></dt><dd><p>Use ANSI C grammar in SOURCE items and use this
 592                     for syntax highlighting (<code class="literal">HTML</code> only).</p></dd><dt><span class="term">--css</span></dt><dd><p> Use the content of the specified file to create the
 593                     <code class="filename">robodoc.css</code>.  The content of the file is
 594                     copied into <code class="filename">robodoc.css</code>.  </p></dd><dt><span class="term">--dbxml</span></dt><dd><p>Generate documentation in XML DocBook format.</p></dd><dt><span class="term">--debug</span></dt><dd><p>Works like --tell, bug gives a lot more information.</p></dd><dt><span class="term">--doc</span></dt><dd><p>Define the path to the documentation directory or
 595                     documentation file.  A path can start with
 596                     <code class="literal">./</code> or <code class="literal">/</code>.  Do not use
 597                     <code class="literal">..</code> in the path.  The documentation
 598                     directory can be a subdirectory of the source directory,
 599                     or be parallel to the source directory,
 600                     however they can not be equal. So
 601                     <span><strong class="command">--src ./sources</strong></span>
 602                     together with
 603                     <span><strong class="command">--doc ./documents</strong></span>
 604                     is fine,
 605                     but
 606                     <span><strong class="command">--src ./Everything</strong></span>
 607                     together with
 608                     <span><strong class="command">--doc ./Everything</strong></span>
 609                     is not.
 610                 </p></dd><dt><span class="term">--doctype_name</span></dt><dd><p>DocBook output requires a <code class="literal">&lt;!DOCTYPE&gt;</code> tag.
 611                     With this option you can specify your own version of it.  You have
 612                     to use it in combination with <span><strong class="command">--doctype_location</strong></span>.
 613                     An example:
 614                 </p><pre class="programlisting">
 615     robodoc --src test --doc test
 616         --doctype_location "-//OASIS//DTD Simplified DocBook XML V1.1//EN"
 617         --doctype_name docbook-simple/sdocbook.dtd
 618         --dbxml
 619 </pre><p>
 620                     results in the following docbook file with the following head:
 621                 </p><pre class="programlisting">
 622 &lt;!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.1//EN"
 623 "docbook-simple/sdocbook.dtd"&gt;
 624 </pre></dd><dt><span class="term">--doctype_location</span></dt><dd><p>See <span><strong class="command">--doctype_name</strong></span>.</p></dd><dt><span class="term">--headless</span></dt><dd><p>Do not create the head of a document. This allows you to
 625                     create documents that can be included in other documents, or
 626                     to which you can add your own style.</p><p>For html output this means that no
 627                     <code class="literal">&lt;html&gt;&lt;head&gt; ..... &lt;body&gt;</code>
 628                     is generated.
 629                 </p><p>For LaTeX output this means none of the document
 630                     initialization code is generated, such as
 631                     <code class="literal">\documentclass{article}</code> or
 632                     <code class="literal">\begin{document}</code> is generated.  If you use
 633                     this option in combination with <code class="option"> --footless</code>
 634                     you can use <code class="literal">\include</code> or
 635                     <code class="literal">\input</code> commands to include the ROBODoc
 636                     generated documents in a larger document.</p><p>For XML DocBook output this means no
 637                     <code class="literal">&lt;!DOCTYPE&gt;</code>,
 638                     <code class="literal">&lt;article&gt;</code>, and
 639                     <code class="literal">&lt;articleinfo&gt;</code> is generated.
 640                 </p></dd><dt><span class="term">--first_section_level</span></dt><dd><p>Make the first section start at the specified level
 641                     instead of 1.  This is useful if you want to include the
 642                     generated documentation in another document.
 643                 </p></dd><dt><span class="term">--footless</span></dt><dd><p>Do not create the foot of a document. This allows you to
 644                     create documents that can be included in other documents, or
 645                     to which you can add your own style.</p><p>For html output this means that no
 646                     <code class="literal">&lt;/body&gt;&lt;/html&gt;</code>
 647                     is generated.
 648                 </p><p>For LaTeX output this means no
 649                     <code class="literal">\end{document}</code> is generated.
 650                 </p><p>For XML DocBook output this means no
 651                     <code class="literal">&lt;/article&gt;</code> is generated.
 652                 </p></dd><dt><span class="term">--html</span></dt><dd><p>Generate documentation in HTML format.</p></dd><dt><span class="term">--ignore_case_when_linking</span></dt><dd><p>Ignore differences in case when creating cross links.
 653                     This is handy for languages such as Fortran or Pascal, but
 654                     in most cases it is better not to use it.</p></dd><dt><span class="term">--internal</span></dt><dd><p>Also include headers marked internal.</p></dd><dt><span class="term">--internalonly</span></dt><dd><p>Only include headers marked internal.</p></dd><dt><span class="term">--index</span></dt><dd><p>Also create a master index file.</p></dd><dt><span class="term">--lock</span></dt><dd><p> Per source file robodoc locks on the first header marker
 655                     it finds and will recognize only that particular header marker
 656                     for the remaining part of the file.  In addition it locks on
 657                     the first remark marker in each header and will recognize only
 658                     that particular remark marker for the remaining part of the
 659                     header.  </p></dd><dt><span class="term">--multidoc</span></dt><dd><p>Generate one document per source file, and copy the
 660                     directory hierarchy.</p></dd><dt><span class="term">--nosource</span></dt><dd><p>Do not include the SOURCE items.</p></dd><dt><span class="term">--no_subdirectories</span></dt><dd><p>Do not create any subdirectories in the documentation directory
 661                 instead write all the documentation files in the root directory. The root directory is the one specified with <code class="option">--doc</code>.</p></dd><dt><span class="term">--nodesc</span></dt><dd><p>Do not scan any subdirectories, scan only the top level
 662                     directory of the source tree.</p></dd><dt><span class="term">--nosort</span></dt><dd><p>Do not sort the headers when generating the
 663                     documentation. The headers will appear in the same order in
 664                     the documentation as they appear in the source code.</p></dd><dt><a id="nopre"></a><span class="term"><a id="nopre.term"></a>--nopre</span></dt><dd><p>With this option ROBODoc does not generate preformatted
 665                     text when creating the item documentation. (Using
 666                     the <code class="literal">&lt;PRE&gt;</code> and
 667                     <code class="literal">&lt;/PRE&gt;</code> construction in HTML format
 668                     for instance). Instead ROBODoc tries to deduce
 669                     the formatting from the indentation and special
 670                     characters. See <a href="#formatting" title="3.5.&#xA0;Smart Text Formatting">Smart Text Formatting</a>. This creates much better
 671                     looking documentation.
 672                 </p></dd><dt><span class="term">--nogeneratedwith</span></dt><dd><p>Do not add the "generated with robodoc" message at the
 673                     top of each documentation file.</p></dd><dt><span class="term">--one_file_per_header</span></dt><dd><p>Create a separate documentation file for each header.
 674                 </p></dd><dt><span class="term">--rc</span></dt><dd><p>Use the specified file instead of <code class="filename">robodoc.rc</code>.
 675                 </p></dd><dt><span class="term">--rtf</span></dt><dd><p>Generate documentation in RTF format.</p></dd><dt><span class="term">--sections</span></dt><dd><p>Create sections based on the module hierarchy.</p></dd><dt><span class="term">--sectionnameonly</span></dt><dd><p>ROBODoc generates the section headers with names only,
 676                     no chapter numbers, no parent section names.</p></dd><dt><span class="term">--singledoc</span></dt><dd><p> Define the documentation directory or documentation
 677                     file.</p></dd><dt><span class="term">--singlefile</span></dt><dd><p> Generate a single document from a single file </p></dd><dt><span class="term">--src</span></dt><dd><p> Define the path for the source directory or source
 678                     file.  The path can start with <code class="literal">./</code> or
 679                     <code class="literal">/</code>.  Do not use <code class="literal">..</code> in the
 680                     path.  </p></dd><dt><span class="term">--tabsize</span></dt><dd><p>Lets you specify the tab size.</p></dd><dt><span class="term">--tabstops</span></dt><dd><p>Specify tab stop locations in a comma separated list.</p><p>
 681                   Example: <code class="option">--tabstops 10,20,40,80</code>
 682                 </p></dd><dt><span class="term">--toc</span></dt><dd><p>Add a table of contents. This works in multidoc mode as
 683                     well as singledoc mode.</p></dd><dt><span class="term">--latex</span></dt><dd><p>Generate documentation in <code class="literal">LaTeX</code> format.</p></dd><dt><span class="term">--tell</span></dt><dd><p>ROBODoc tells you what steps it is taking.</p></dd><dt><span class="term">--documenttitle</span></dt><dd><p>Specify the Title of the whole documentation.</p></dd><dt><span class="term">--altlatex</span></dt><dd><p>Alternate <code class="literal">LaTeX</code> file format
 684                 (bigger / clearer than normal).
 685                 </p></dd><dt><span class="term">--latexparts</span></dt><dd><p>Make the first module level as <code class="literal">PART</code>
 686                 in <code class="literal">LaTeX</code> output
 687                 (Gives you one more subsection level).</p></dd><dt><a id="syntaxcolors_enable"></a><span class="term"><a id="syntaxcolors_enable.term"></a>--syntaxcolors_enable</span></dt><dd><p>Enable only specific syntax highlighting features in
 688                 <code class="literal">SOURCE</code> items (<code class="literal">HTML</code> only).</p><p>Usage:
 689                   <code class="option">--syntaxcolors_enable
 690                   quotes,squotes,line_comments,block_comments,keywords,non_alpha</code>
 691                 </p><div class="itemizedlist"><ul type="disc"><li><code class="option">quotes</code>
 692                     -- Enable highlighting of <code class="literal">"string literals"
 693                   </code></li><li><code class="option">squotes</code>
 694                     -- Enable highlighting of <code class="literal">'string literals'
 695                   </code></li><li><a id="syntaxcolors_enable_line_comments"></a><code class="option"><a id="syntaxcolors_enable_line_comments.option"></a>line_comments</code>
 696                     -- Enable highlighting of comments that span until the end of lines
 697                     (See <a href="#linecomments" title="7.17.&#xA0;source line comments block">source line comments block</a>)
 698                   </li><li><a id="syntaxcolors_enable_block_comments"></a><code class="option"><a id="syntaxcolors_enable_block_comments.option"></a>block_comments</code>
 699                     -- Enable highlighting of block comments
 700                     (See <a href="#remark_begin_end" title="7.16.&#xA0; remark begin markers and remark end markers block">
 701 remark begin markers and remark end markers block</a>)
 702                   </li><li><a id="syntaxcolors_enable_keywords"></a><code class="option"><a id="syntaxcolors_enable_keywords.option"></a>keywords</code>
 703                     -- Enable highlighting of keywords
 704                     (See <a href="#keywords" title="7.18.&#xA0;keywords block">keywords block</a>)
 705                   </li><li><code class="option">non_alpha</code>
 706                     -- Enable highlighting of non alphanumeric characters
 707                     (like: <code class="literal">#</code>, <code class="literal">$</code>, <code class="literal">%</code>, etc...)
 708                   </li></ul></div><p>You don't need this if you have the
 709                   <code class="option"><a href="#cmode">--cmode</a></code>
 710                   option specified.
 711                 </p><p> See also the
 712                   <code class="option"><a href="#syntaxcolors">--syntaxcolors</a></code>
 713                   option.
 714                 </p></dd><dt><a id="syntaxcolors"></a><span class="term"><a id="syntaxcolors.term"></a>--syntaxcolors</span></dt><dd><p>Turn on all syntax highlighting features in <code class="literal">SOURCE</code>
 715                 items (<code class="literal">HTML</code> only).</p><p>This option equals to:
 716                   <code class="option">--syntaxcolors_enable
 717                   quotes,squotes,line_comments,block_comments,keywords,non_alpha</code>
 718                 </p><p>You don't need this if you have the
 719                   <code class="option"><a href="#cmode">--cmode</a></code>
 720                   option specified.
 721                 </p><p> See also the
 722                   <code class="option"><a href="#syntaxcolors_enable">--syntaxcolors_enable</a></code>
 723                   option.
 724                 </p></dd><dt><span class="term">--dotname</span></dt><dd><p>Specify the name (and path / options) of
 725                 <code class="literal">DOT</code> tool.</p><p>See <a href="#tools" title="8.6.&#xA0;Using external tools">Using external tools</a>.</p></dd><dt><span class="term">--masterindex</span></dt><dd><p>Specify the title and filename of the master index page
 726                 </p><p>Usage:
 727                   <code class="option">--masterindex
 728                   <em class="replaceable"><code>title</code></em>,<em class="replaceable"><code>filename</code></em>
 729                   </code>
 730                 </p><p>Example:
 731                   <code class="option">--masterindex "Index Page,index"</code>
 732                 </p></dd><dt><span class="term">--sourceindex</span></dt><dd><p>Specify the title and filename of the source files index
 733                 page</p><p>Usage:
 734                   <code class="option">--sourceindex
 735                   <em class="replaceable"><code>title</code></em>,<em class="replaceable"><code>filename</code></em>
 736                   </code>
 737                 </p><p>Example:
 738                   <code class="option">--sourceindex "Source files,sources"</code>
 739                 </p></dd><dt><span class="term">--header_breaks</span></dt><dd><p>If a header has multiple names, ROBODoc can insert line breaks after every
 740                 specified number of header names to improve readability. If you do not specify this
 741                 option, ROBODoc will insert a line break after every two header names. Set it to
 742                 zero to disable the line breaks.</p><p>
 743                   Example: <code class="option">--header_breaks 3</code>
 744                 </p></dd></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="customizing"></a>7. Customizing ROBODoc</h2></div></div></div><p> ROBODoc can be configured with a configuration file called
 745     <code class="filename">robodoc.rc</code>.  With it you can define item
 746     names, frequently used options, and translations for English
 747     terms. One should note that if a configuration file is specified,
 748     its definitions over-ride ROBODoc internal (i.e. built-in) settings.
 749     This is a feature; some arbitrary language may include syntax
 750     which conflicts with ROBODoc's internal markers. By taking advantage
 751     of a configuration file, these sort of issues and conflicts
 752     can be circumvented.  An example is shown below.
 753 </p><pre class="programlisting">
 754 # Example robodoc.rc
 755 #
 756 items:
 757     NAME
 758     FUNCTION
 759     SYNOPSIS
 760     INPUTS
 761     OUTPUTS
 762     SIDE EFFECTS
 763     HISTORY
 764     BUGS
 765     EXAMPLE
 766 ignore items:
 767     HISTORY
 768     BUGS
 769 item order:
 770     FUNCTION
 771     SYNOPSIS
 772     INPUTS
 773     OUTPUTS
 774 source items:
 775     SYNOPSIS
 776 preformatted items:
 777     INPUTS
 778     OUTPUTS
 779 format items:
 780     FUNCTION
 781     SIDE EFFECTS
 782 options:
 783     --src ./source
 784     --doc ./doc
 785     --html
 786     --multidoc
 787     --index
 788     --tabsize 8
 789 headertypes:
 790     J  "Projects"          robo_projects    2
 791     F  "Files"             robo_files       1
 792     e  "Makefile Entries"  robo_mk_entries
 793     x  "System Tests"      robo_syst_tests
 794     q  Queries             robo_queries
 795 ignore files:
 796     README
 797     CVS
 798     *.bak
 799     *~
 800     "a test_*"
 801 accept files:
 802     *.c
 803     *.h
 804     *.pl
 805 header markers:
 806     /****
 807     #****
 808 remark markers:
 809     *
 810     #
 811 end markers:
 812     ****
 813     #****
 814 header separate characters:
 815     ,
 816 header ignore characters:
 817     [
 818 remark begin markers:
 819     /*
 820 remark end markers:
 821     */
 822 source line comments:
 823     //
 824 keywords:
 825     if
 826     do
 827     while
 828     for
 829 </pre><p>The configuration file consists of a number of blocks.
 830     Each block starts with a name followed by a
 831     <code class="literal">:</code>.
 832     In each block you define a number of values.  Each value must
 833     start with at least one space.
 834 </p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2502679"></a>7.1. items block</h3></div></div></div><p>In this block you can define the names of items that
 835         ROBODoc should recognize.  Item names can consist of more than
 836         one word but should be written in all uppercase characters.
 837         Define one item name per line.  You do not need to put quotes
 838         around them if they contain spaces.
 839     </p><p>If you do not define an items block ROBODoc uses its
 840         default list of item names.  If you define an items block
 841         ROBODoc uses only those item names, any of the default items names
 842         (except SOURCE) are no longer recognized.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2502700"></a>7.2. ignore items block</h3></div></div></div><p>In this block you can define the names of items that
 843         ROBODoc should ignore when generating documentation.
 844         This can be useful if you want to create documentation
 845         for a client, but for instance do not want to include
 846         the history items and bugs items.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2502714"></a>7.3. item order block</h3></div></div></div><p>In this block you can define the order in which items
 847         are to appear in the generated documentation.
 848         The items listed here will appear in the given order in the
 849         generated documentation.  Any remaining items appear
 850         after these items in the order they were found in the header.
 851         This allows you to make the documentation look more uniform.
 852         </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sourceitems"></a>7.4. source items block</h3></div></div></div><p>In this block you can define the names of items that
 853         ROBODoc handles in the same way as the SOURCE item.
 854     </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2502749"></a>7.5. preformatted items block</h3></div></div></div><p>
 855     In this block you can define the names of items that should be always
 856     preformatted. This is useful if you have the
 857     <code class="option"><a href="#nopre">--nopre</a></code> option
 858     specified and want specific items (like input and output lists) to be
 859     automatically preformatted. See
 860     <a href="#formatting" title="3.5.&#xA0;Smart Text Formatting">Smart Text Formatting</a> for more
 861     information.
 862   </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2502783"></a>7.6. format items block</h3></div></div></div><p>
 863     In this block you can define the names of items that should be formatted by
 864     the <a href="#formatting" title="3.5.&#xA0;Smart Text Formatting">Smart Text Formatting</a> feature
 865     (like function descriptions) even if the
 866     <code class="option"><a href="#nopre">--nopre</a></code>
 867     option has not been specified.
 868   </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2502813"></a>7.7. options block</h3></div></div></div><p>In this block you can define frequently used options.
 869         The options you specify here are added to any options you
 870         specify on the command line.</p><p>
 871       See <a href="#options" title="6.&#xA0;Options">Options</a>.
 872     </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="headertypes_block"></a>7.8. headertypes block</h3></div></div></div><p>In this block you can define your own header types.
 873         These are added to the existing header types.  Each new
 874         header type requires three parameters: the character used to
 875         indicate a header of this type, the title for this type as
 876         used in the master index and the name of the file in which the
 877         index of this type is stored.  If you use a character of an
 878         existing header type, this header type is overwritten.
 879     </p><p>
 880         Additionally the sorting priority can also be specified for each header
 881         type. Headers with higher priority will appear earlier in the
 882         generated output. (For example you can make module definitions appear
 883         at the beginning of a page.) If this parameter is omitted, the header
 884         will have the priority 0 (lowest) by default. All pre-defined header
 885         types have zero priority, except
 886         "<a href="#header_type_h">Header for a module in a project</a>",
 887         which has the sorting priority 1.
 888         See <a href="#header_types" title="3.2.&#xA0;Header Types">Header Types</a>.
 889     </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2502896"></a>7.9. ignore files block</h3></div></div></div><p>In this block you can define the names of files or
 890         directories that ROBODoc should ignore while scanning
 891         the directory tree for source files.  You can use the
 892         wildcard symbols <code class="literal">*</code> and
 893         <code class="literal">?</code>.  If you use spaces in the expression
 894         enclose the expression in quotes.
 895     </p><p> For instance, the rc file above causes ROBODoc
 896         to skip all <code class="filename">README</code> files, all files with
 897         the name <code class="filename">CVS</code> (these are usually
 898         directories).  It also skips all files with a name that ends
 899         with <code class="filename">.bak</code> or <code class="filename">~</code> or
 900         that start with <code class="filename">a test_</code> </p><p>Normally you specify the names of directories here
 901         and do the filtering of file names with a accept files block.
 902     </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2502963"></a>7.10. accept files block</h3></div></div></div><p>In this block you can define the names of files that
 903         robodoc should accept. This test is carried out after the
 904         'ignore files' filtering is performed.  Any files that do
 905         not match the patterns in this block are ignored by ROBODoc.
 906     </p><p>
 907         If there is no accept files block all files are accepted.
 908     </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2502981"></a>7.11. header markers block</h3></div></div></div><p>
 909         In this block you define what ROBODoc will recognize
 910         as start of a header.  If you use this block ROBODoc only
 911         recognizes these markers, any of the inbuilt markers will
 912         be ignored.
 913     </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2502994"></a>7.12. remark markers block</h3></div></div></div><p>
 914         In this block you define what ROBODoc will recognize
 915         as start of remark.  If you use this block ROBODoc only
 916         recognizes these markers, any of the inbuilt markers will
 917         be ignored.
 918     </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2503006"></a>7.13. end markers block</h3></div></div></div><p>
 919         In this block you define what ROBODoc will recognize
 920         as end of a header.  If you use this block ROBODoc only
 921         recognizes these markers, any of the inbuilt markers will
 922         be ignored.
 923     </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="separate_characters_block"></a>7.14. header separate characters block</h3></div></div></div><p>
 924     In this block you can specify the separation character(s) for multiple
 925     header names. The default character is "<code class="literal">,</code>" (comma) if
 926     this block is missing. See
 927     <a href="#preparing" title="3.&#xA0;Preparing your source code for ROBODoc">Preparing your source code for ROBODoc</a>
 928     for more information.
 929   </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="header_ignore_characters_block"></a>7.15. header ignore characters block</h3></div></div></div><p>
 930     In this block you can specify character(s) where the evaluation of a header
 931     should stop. The default character is "<code class="literal">[</code>" if this block
 932     is missing. This is useful to supply additional information to the header
 933     that ROBODoc should not care about.
 934   </p><p>
 935     For example one can include the version number of the function:
 936 </p><pre class="programlisting">
 937   ****f* financial.library/StealMoney [2.0]
 938 </pre><p>
 939   </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="remark_begin_end"></a>7.16.
 940 remark begin markers and remark end markers block</h3></div></div></div><p>
 941         Some languages allow remarks to span more than one line. They
 942         start a remark with a begin marker and end it with another
 943         marker.  For instance in C you can have:
 944     </p><pre class="programlisting">
 945    /* This is a
 946       multi-line remark.
 947     */
 948 </pre><p>
 949         Here the markers are <code class="literal">/*</code> and <code class="literal">*/</code>.
 950         If you tell ROBODoc what these markers are in a remark begin
 951         markers block and remark end markers block. ROBODoc can skip
 952         them in source items.</p><p>We illustrate this with an example. Say we have a language
 953         that start a remark with <code class="literal">|*</code> and
 954         <code class="literal">*|</code>.  We define <code class="literal">SYNOPSIS</code>
 955         to be a source like item.  If we now run ROBODoc on the
 956         without a remark begin markers and
 957         end markers block on the following piece of source, </p><pre class="programlisting">
 958 |****f* Bar/foo
 959  * FUNCTION
 960  *   foo computes the foo factor.
 961  * SYNOPSIS
 962  *|
 963 int foo( float correction )
 964 |*
 965  * BUGS
 966  *   None
 967  * SOURCE
 968  *|  .
 969 {
 970     return correction * 42.0;
 971 }
 972 |*****|
 973 </pre><p>the extracted documentation will look like:</p><pre class="literallayout">
 974  FUNCTION
 975    foo computes the foo factor.
 976  SYNOPSIS
 977    *|
 978    int foo( float correction )
 979    |*
 980  BUGS
 981    None
 982  SOURCE
 983    *|  .
 984    {
 985       return correction * 42.0;
 986    }
 987 </pre><p>because ROBODoc considers
 988     <code class="literal">|*</code> and <code class="literal">*|</code>.to be part of the
 989     source, and not part of the begin or end of a header.</p><p> If you add</p><pre class="programlisting">
 990 remark begin markers:
 991        |*
 992 remark end markers:
 993        *|
 994 </pre><p>the output will look like:</p><pre class="literallayout">
 995  FUNCTION
 996    foo computes the foo factor.
 997  SYNOPSIS
 998    int foo( float correction )
 999  BUGS
1000    None
1001  SOURCE
1002    {
1003       return correction * 42.0;
1004    }
1005 </pre><p>
1006     These markers will also be used to highlight block comments if the
1007     <code class="option">
1008       <a href="#syntaxcolors_enable">--syntaxcolors_enable</a>
1009       <a href="#syntaxcolors_enable_block_comments">block_comments</a>
1010     </code>
1011     option (or the
1012     <code class="option">
1013       <a href="#syntaxcolors">--syntaxcolors</a>
1014     </code>
1015     option) is specified (Similar to
1016     <a href="#linecomments" title="7.17.&#xA0;source line comments block">source line comments block</a>).
1017 </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="linecomments"></a>7.17. source line comments block</h3></div></div></div><p>
1018         Here you can specify markers which start whole line comments.
1019         (Comments that span until the end of line like "<code class="literal">//</code>",
1020         "<code class="literal">REM</code>", "<code class="literal">;</code>", etc...)
1021         These lines will be highlighted in the generated <code class="literal">HTML</code>
1022         output if the
1023         <code class="option">
1024           <a href="#syntaxcolors_enable">--syntaxcolors_enable</a>
1025           <a href="#syntaxcolors_enable_line_comments">line_comments</a>
1026         </code>
1027         option (or the
1028         <code class="option">
1029           <a href="#syntaxcolors">--syntaxcolors</a>
1030         </code>
1031         option) has been specified.</p><p>
1032         You don't need this if you have the
1033         <code class="option">
1034           <a href="#cmode">--cmode</a>
1035         </code>
1036         option specified.
1037     </p><p>
1038         The default highlighting color can be changed in the <code class="literal">CSS</code>
1039         file (<code class="literal">span.comment</code>).
1040     </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="keywords"></a>7.18. keywords block</h3></div></div></div><p>
1041         Here you can specify the keywords in your <code class="literal">SOURCE</code> items.
1042         These keywords will be highlighted in the generated <code class="literal">HTML</code>
1043         output if the
1044         <code class="option">
1045           <a href="#syntaxcolors_enable">--syntaxcolors_enable</a>
1046           <a href="#syntaxcolors_enable_keywords">keywords</a>
1047         </code>
1048         option (or the
1049         <code class="option">
1050           <a href="#syntaxcolors">--syntaxcolors</a>
1051         </code>
1052         option) has been specified. Keywords meant to be the language native ones
1053         (<code class="literal">for</code>, <code class="literal">if</code>, etc...).
1054     </p><p>
1055         You don't need this if you have the
1056         <code class="option">
1057           <a href="#cmode">--cmode</a>
1058         </code>
1059         option specified.
1060     </p><p>
1061         The default highlighting color can be changed in the <code class="literal">CSS</code>
1062         file (<code class="literal">span.keyword</code>).
1063     </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2503510"></a>7.19. Configuration file location</h3></div></div></div><p>ROBODoc searches the your current directory for the
1064     <code class="filename">robodoc.rc</code> file. If it can't find
1065     it there it will search in <code class="literal">$HOME/</code>, then
1066     <code class="filename">$HOMEDRIVE$HOMEPATH/</code>, and finally in
1067     <code class="filename">/usr/share/robodoc/</code>.</p><p>With the <code class="option">--rc</code> option you can tell ROBODoc to
1068     use a different file than <code class="filename">robodoc.rc</code> as
1069     configuration file.  This is handy if you want to create
1070     documentation in different formats.  For instance: </p><pre class="programlisting">
1071 robodoc --rc  htmlsingle.rc
1072 robodoc --rc  rtfsingle.rc
1073 robodoc --rc  htmlmulti.rc
1074 </pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2504528"></a>8. Tips and Tricks</h2></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2504533"></a>8.1. The SOURCE Item</h3></div></div></div><p> With a little extra work you can include part of your
1075     source code into your documentation too.  The following example
1076     shows how this is done:</p><pre class="programlisting">
1077 /****f* Robodoc/RB_Panic [2.0d]
1078  * NAME
1079  *   RB_Panic - Shout panic, free resources, and shut down.
1080  * SYNOPSIS
1081  *   RB_Panic (cause, add_info)
1082  *   RB_Panic (char *, char *)
1083  * FUNCTION
1084  *   Prints an error message.
1085  *   Frees all resources used by robodoc.
1086  *   Terminates program.
1087  * INPUTS
1088  *   cause    - pointer to a string which describes the
1089  *              cause of the error.
1090  *   add_info - pointer to a string with additional information.
1091  * SEE ALSO
1092  *   RB_Close_The_Shop ()
1093  * SOURCE
1094  */
1095
1096   void RB_Panic (char *cause, char *add_info)
1097   {
1098     printf ("Robodoc: Error, %s\n",cause) ;
1099     printf ("         %s\n", add_info) ;
1100     printf ("Robodoc: Panic Fatal error, closing down..\n") ;
1101     RB_Close_The_Shop () ; /* Free All Resources */
1102     exit(100) ;
1103   }
1104
1105 /*******/
1106 </pre><p>You can add a SOURCE item as the last item of your header. Then
1107     instead of closing your header with an end marker, you close it
1108     normally.  The end marker is instead placed at the end of the
1109     fragment of source code that you want to include.  </p><p>SOURCE items are included by default.  If you want to create a
1110     document without the SOURCE items use the option
1111     <code class="option">--nosource</code>.</p><p>You can also make normal items work like the source item,
1112     see <a href="#sourceitems" title="7.4.&#xA0;source items block">source items block</a>.
1113 </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2504567"></a>8.2. Minimizing Duplicate Information</h3></div></div></div><p>It is always good to avoid having the same information in several different locations.
1114     It is easy to create headers that have a lot information duplication.  Take for instance
1115     the following header.
1116 </p><pre class="programlisting">
1117 /****f* Robodoc/RB_Panic [2.0d]
1118  * NAME
1119  *   RB_Panic - Shout panic, free resources, and shut down.
1120  * SYNOPSIS
1121  *   RB_Panic (cause, add_info)
1122  *   RB_Panic (char *, char *)
1123  * FUNCTION
1124  *   Prints an error message.
1125  *   Frees all resources used by robodoc.
1126  *   Terminates program.
1127  * INPUTS
1128  *   cause    - pointer to a string which describes the
1129  *              cause of the error.
1130  *   add_info - pointer to a string with additional information.
1131  * SEE ALSO
1132  *   RB_Close_The_Shop ()
1133  * SOURCE
1134  */
1135
1136   void RB_Panic (char *cause, char *add_info)
1137   {
1138     printf ("Robodoc: Error, %s\n",cause) ;
1139     printf ("         %s\n", add_info) ;
1140     printf ("Robodoc: Panic Fatal error, closing down..\n") ;
1141     RB_Close_The_Shop () ; /* Free All Resources */
1142     exit(100) ;
1143   }
1144
1145 /*******/
1146 </pre><p>
1147     The name <code class="literal">RB_Panic</code> occurs five times.  This is tedious to
1148     type and difficult to maintain.
1149     However with a the right <code class="filename">robodoc.rc</code> this can be changed
1150     to:
1151 </p><pre class="programlisting">
1152 /****f* Robodoc/RB_Panic [2.0d]
1153  * SUMMARY
1154  *   Shout panic, free resources, and shut down.
1155  * SYNOPSIS
1156  */
1157
1158 void RB_Panic (char* cause, char *add_info)
1159
1160 /*
1161  * FUNCTION
1162  *   Prints an error message.
1163  *   Frees all resources used by robodoc.
1164  *   Terminates program.
1165  * INPUTS
1166  *   cause    - pointer to a string which describes the
1167  *              cause of the error.
1168  *   add_info - pointer to a string with additional information.
1169  * SEE ALSO
1170  *   RB_Close_The_Shop ()
1171  * SOURCE
1172  */
1173   {
1174     printf ("Robodoc: Error, %s\n",cause) ;
1175     printf ("         %s\n", add_info) ;
1176     printf ("Robodoc: Panic Fatal error, closing down..\n") ;
1177     RB_Close_The_Shop () ; /* Free All Resources */
1178     exit(100) ;
1179   }
1180
1181 /*******/
1182 </pre><p><code class="literal">RB_Panic</code> occurs only twice now. In addition changes
1183 to the function definition only have to be done once.</p><p>The <code class="filename">robodoc.rc</code> required for this is: </p><pre class="programlisting">
1184 # robodoc.rc file
1185 items:
1186     SUMMARY
1187     SYNOPSIS
1188     INPUTS
1189     OUTPUTS
1190     SEE ALSO
1191     BUGS
1192 source items:
1193     SYNOPSIS
1194 remark begin markers:
1195     /*
1196 remark end markers:
1197     */
1198 </pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2504666"></a>8.3. Advanced formatting with raw HTML and LaTeX code</h3></div></div></div><p> By default an item's body shows up in your documentation in
1199     the same way as it is formatted in your source code.  All special
1200     characters for the output mode are escaped.  For instance an &lt;
1201     is translated to a &amp;lt; in HTML mode.  Sometimes however you
1202     like to have some more control of what goes into the
1203     documentation.  This is possible with the piping.  If a line of
1204     your item's body starts with one of the special piping markers, the
1205     text after this marker is copied verbatim into your documentation.
1206     The following example shows how this is done, and how to add
1207     equations to your documentation.
1208     </p><pre class="programlisting">
1209 /****m* pipe/pipetest
1210  * NAME
1211  *   pipetest
1212  * DESCRIPTION
1213  *   Simple header to show "piping" features in items.
1214  * EXAMPLE
1215  *   Only "pipes" which match selected output style are picked up.
1216  *   |html &lt;CENTER&gt;This will be included in &lt;B&gt;HTML&lt;/B&gt; output.&lt;/CENTER&gt;
1217  *   |latex \centerline{This will be included in \LaTeX output}
1218  *   Space is mandatory following the pipe marker. The following is not a
1219  *   valid pipe marker:
1220  *   |html&lt;B&gt;Moi!&lt;/B&gt;
1221  *   You should see an equation on the following line:
1222  *   |html y = x^2 (sorry, plain HTML is not very powerful)
1223  *   |latex \centerline{$y = x^2$}
1224  *   How does this look like?
1225  *   Here comes a multi-line equation array:
1226  *    |latex \begin{eqnarray}
1227  *    |latex \frac{\partial u}{\partial \tau} &amp; = &amp; D_u {\nabla}^2 u +
1228  *    |latex \frac{1}{\epsilon}
1229  *    |latex \left ( \hat{u}-{\hat{u}}^2-f\, {v} \, \frac{\hat{u}-q}{\hat{u}+q}
1230  *    |latex \right ) \; ,  \label{diffspot:1} \\
1231  *    |latex \frac{\partial v}{\partial \tau} &amp; = &amp; \hat{u}-v \; ,
1232  *    |latex \label{diffspot:2} \\
1233  *    |latex \frac{\partial r}{\partial \tau} &amp; = &amp; D_r {\nabla}^2 r \; .
1234  *    |latex \label{diffspAot:3}
1235  *    |latex \end{eqnarray}
1236  *    |html &lt;I&gt;TODO: write this in html&lt;/I&gt;
1237  *   End of the example.
1238  ******
1239  */
1240 </pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2504752"></a>8.4. Linking to external documents (href, file, mailto, images)</h3></div></div></div><p> In HTML mode ROBODoc recognizes the following links to
1241     external documents.  </p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">href:body</code> -- This is replaced with
1242       <code class="literal">&lt;a href="body"&gt;body&lt;/A&gt;</code>
1243     </p></li><li><p><code class="literal">file:/body</code> -- This is replaced with
1244     <code class="literal">&lt;a href="file:/body"&gt;file:/body&lt;/A&gt;</code>
1245     </p></li><li><p><code class="literal">mailto:body</code> -- This is replaced with
1246     <code class="literal">&lt;a href="mailto:body"&gt;body&lt;/A&gt;</code>
1247     </p></li><li><p><code class="literal">http://body</code> -- This is replaced with
1248     <code class="literal">&lt;a href="http://body"&gt;http://body&lt;/A&gt;</code>
1249     </p></li><li><p><code class="literal">image:body</code> -- This is replaced with
1250     <code class="literal">&lt;image src="body"&gt;</code>
1251     </p></li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2504846"></a>8.5. Linking from an external document</h3></div></div></div><p>To link from an external document to one of the HTML
1252     documents generated by ROBODoc you need a label.  ROBODoc creates
1253     two labels for each header. The first one starts with
1254     <code class="literal">robo</code> followed by a number.  You can not use
1255     this one because the numbers will change each time you run
1256     ROBODoc.  The second label is an escaped version of the whole
1257     header name.  In this label all the non alphanumeric characters of
1258     the name are replaced by their two digit hexadecimal code.</p><p>An example, if your header name is
1259     <code class="literal">Analyser/RB_ToBeAdded</code> the label is
1260     <code class="literal">Analyser2fRB5fToBeAdded</code>.  Here
1261     <code class="literal">/</code> was replaced by <code class="literal">2f</code> and
1262     <code class="literal">_</code> was replaced by <code class="literal">5f</code>.  As
1263     long as you do not change the header name, this label stays the
1264     same each time you run ROBODoc.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="tools"></a>8.6. Using external tools</h3></div></div></div><p>
1265     You can also execute external tools from <code class="literal">ROBODoc</code> and even
1266     pass data to them.
1267     The output of these tools can be included in your documentation for instance.
1268     </p><p>
1269     There are several types of external tools you can use:
1270     </p><div class="orderedlist"><ol type="1"><li>Arbitrary tool with passing data through stdin</li><li>Arbitrary tool without passing data through stdin</li><li>The <code class="literal">DOT</code> tool</li></ol></div><p>
1271     The following example shows how to use each of them.
1272     </p><pre class="programlisting">
1273 /****m* tools/tooltest
1274  *
1275  * NAME
1276  *   Tooltest
1277  *
1278  * DESCRIPTION
1279  *   Example showing how to invoke external tools.
1280  *
1281  * EXAMPLE
1282  * This one sorts elements into the file href:nexus-6.txt
1283  * The input data is passed through stdin.
1284  *
1285  * |tool sort &gt; nexus-6.txt
1286  * Zhora
1287  * Pris
1288  * Leon Kowalski
1289  * Roy Batty
1290  * Rachel
1291  * Rick Deckard?
1292  * |tool end
1293  *
1294  * We can also execute tools without having any stdin data.
1295  * In the following example the output is simply redirected into href:tears.txt
1296  *
1297  * |exec echo "All those moments will be lost in time like tears in rain." &gt; tears.txt
1298  *
1299  * You can also include neat DOT graphs in your documentation.
1300  * This one shows a hash table.
1301  *
1302  * |dot start
1303  * digraph G {
1304  *   nodesep=.05;
1305  *   rankdir=LR;
1306  *   node [shape=record,width=.1,height=.1];
1307  *
1308  *   node0 [label = "&lt;f0&gt; |&lt;f1&gt; |&lt;f2&gt; |&lt;f3&gt; |&lt;f4&gt; |&lt;f5&gt; |&lt;f6&gt; | ",height=2.0];
1309  *   node [width = 1.5];
1310  *   node1 [label = "{&lt;n&gt; n14 | 719 |&lt;p&gt; }"];
1311  *   node2 [label = "{&lt;n&gt; a1  | 805 |&lt;p&gt; }"];
1312  *   node3 [label = "{&lt;n&gt; i9  | 718 |&lt;p&gt; }"];
1313  *   node4 [label = "{&lt;n&gt; e5  | 989 |&lt;p&gt; }"];
1314  *   node5 [label = "{&lt;n&gt; t20 | 959 |&lt;p&gt; }"] ;
1315  *   node6 [label = "{&lt;n&gt; o15 | 794 |&lt;p&gt; }"] ;
1316  *   node7 [label = "{&lt;n&gt; s19 | 659 |&lt;p&gt; }"] ;
1317  *
1318  *   node0:f0 -&gt; node1:n;
1319  *   node0:f1 -&gt; node2:n;
1320  *   node0:f2 -&gt; node3:n;
1321  *   node0:f5 -&gt; node4:n;
1322  *   node0:f6 -&gt; node5:n;
1323  *   node2:p -&gt; node6:n;
1324  *   node4:p -&gt; node7:n;
1325  * }
1326  * |dot end
1327  *
1328  ******
1329  */
1330 </pre><p>
1331     If you want to use the <code class="literal">DOT</code> tool you need the
1332     <code class="literal">Graphviz</code> package.
1333     More information and the binaries can be found at
1334     <a href="http://www.graphviz.org/" target="_top">
1335         <em class="citetitle">http://www.graphviz.org/
1336     </em></a>.
1337     The created graphs are automatically included in the documentation
1338     (<code class="literal">HTML</code> and <code class="literal">LaTeX</code> only).
1339     If you generate <code class="literal">PDF</code> output from your <code class="literal">LaTeX</code>
1340     file and you want to include <code class="literal">DOT</code> graphs in it, you will also
1341     need the <span><strong class="command">epstopdf</strong></span> utility.
1342     <code class="literal">ROBODoc</code> lets <code class="literal">DOT</code> generate
1343     <code class="literal">PNG</code> images for <code class="literal">HTML</code> output and
1344     <code class="literal">PS</code> and <code class="literal">PDF</code> images for
1345     <code class="literal">LaTeX</code> output.
1346     </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2505111"></a>8.7. ROBODoc-ing an existing project</h3></div></div></div><p>
1347   The ROBODoc package includes also a standalone binary named
1348   <code class="literal">robohdrs</code>.
1349   This helper program can take clean source file and insert
1350   ROBODoc headers to functions, global variables, and macros.
1351   There are issues with this tool but it saves lots of cumbersome typing
1352   when starting on documenting an existing code-base with ROBODoc.
1353   Type
1354 <span><strong class="command">
1355 man robohdrs
1356 </strong></span>
1357   or
1358 <span><strong class="command">
1359 robohdrs -h
1360 </strong></span>
1361   for help.
1362   Example:
1363 <span><strong class="command">
1364 robohdrs -s -p testproj -i "MODIFICATION HISTORY" -i IDEAS testproj.c
1365 </strong></span>
1366 </p><p>
1367   Note that <code class="literal">robohdrs</code> is supported on UNIX-like platforms only.
1368   It requires <code class="literal">fork()</code> and  Exuberant Ctags 5.3.1 or newer.
1369   </p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2505169"></a>8.8. Using ROBODoc under Windows</h3></div></div></div><p>When you use ROBODoc under windows, don't forget that it is
1370     a command line tool.  ROBODoc relies on the console window to
1371     inform you about problems and errors.</p><p>An easy mistake to make is to create a shortcut to
1372     <code class="literal">robodoc.exe</code> and then click on the icon to
1373     generate the documentation each time you made some changes to your
1374     source code.  If you have a fast machine a console window pops up
1375     quickly and after that your documentation is ready.</p><p>This works very fine until you make a mistake in one of your
1376     headers.  The console window still pops up, but before you have a chance
1377     to read any of the error messages it is gone again.  Most likely
1378     you won't even have noticed there were error messages.  You will
1379     end up with empty documentation or old documentation.  </p><p>It is Better to create a batch file with the following commands
1380     and to store all the options in a <code class="filename">robodoc.rc</code>
1381     file:</p><pre class="programlisting">
1382 robodoc.exe
1383 pause
1384 </pre><p>Now the console window stays open and you have the
1385     opportunity to read the error messages.</p><p>While the window is open, right click on the title bar,
1386     go to properties-&gt;layout and set the buffer size to something
1387     like 2500. That way, the next time you run it, you can scroll back
1388     and view all error messages.
1389     </p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="defaultheaders"></a>9. Languages Supported by Default</h2></div></div></div><p>
1390         ROBODoc support a whole range of languages by default.
1391         These languages are listed in the following sections.
1392         For each language two example headers are shown.
1393         One example header without any source items and
1394         one example header with source items.
1395     </p><p> Any of these markers can be mixed, and they are not limited
1396     to the languages listed.  So if you have a language that is not
1397     listed but that has remarks that start with a <code class="literal">#</code>
1398     you can use the Tcl markers, and create headers such as:
1399     </p><pre class="programlisting">
1400 #****f* Foo/Bar
1401 # FUNCTION
1402 #   Bar snarfs the Foo input and mangles it.  Given the right settings
1403 #   it might also do a bit of snu snu.
1404 #***
1405 </pre><p>
1406         In addition for each language the corresponding entries in
1407         the <code class="filename">robodoc.rc</code> are shown.
1408         You do not need these, as ROBODoc has these entries
1409         built-in.  They are shown to make it easier
1410         to determine what needs to be specified for languages
1411         that ROBODoc does not yet support.
1412     </p><p>
1413         You can also use these entries if you want to create
1414         a <code class="filename">robodoc.rc</code> that supports only a limited
1415         number of languages.
1416         This because if you specify your own markers, ROBODoc
1417         ignores any of the in-built markers.
1418     </p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2504474"></a>9.1. C</h3></div></div></div><div class="example"><a id="id2504479"></a><p class="title"><b>Example 10. A simple header without any source items in C.</b></p><div class="example-contents"><pre class="programlisting">
1419 /****f* ModuleName/Foo
1420 * FUNCTION
1421 *   Foo computes the foo factor
1422 *   using a fudge factor.
1423 ****
1424 */
1425 </pre></div></div><br class="example-break" /><div class="example"><a id="id2504500"></a><p class="title"><b>Example 11. A header with source items in C.</b></p><div class="example-contents"><pre class="programlisting">
1426 /****f* ModuleName/Foo
1427 * FUNCTION
1428 *   Foo computes the foo factor
1429 *   using a fudge factor.
1430 * SYNOPSIS
1431 */
1432 int Foo( int fudge )
1433 /*
1434 * INPUTS
1435 *   fudge -- the fudge factor
1436 * SOURCE
1437 */
1438
1439  more source code..
1440
1441 /*****/
1442 </pre></div></div><br class="example-break" /><div class="example"><a id="id2504516"></a><p class="title"><b>Example 12. The robodoc.rc file required for C if it were not supported by default.</b></p><div class="example-contents"><pre class="programlisting">
1443 header markers:
1444   /****
1445 remark markers:
1446   *
1447 end markers:
1448   ****
1449   /****
1450 remark begin markers:
1451   /*
1452 remark end markers:
1453   */
1454 </pre></div></div><br class="example-break" /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2504152"></a>9.2. Modula-2</h3></div></div></div><div class="example"><a id="id2504158"></a><p class="title"><b>Example 13. A simple header without any source items in Modula-2.</b></p><div class="example-contents"><pre class="programlisting">
1455 (****f* ModuleName/Foo
1456 * FUNCTION
1457 *   Foo computes the foo factor
1458 *   using a fudge factor.
1459 ****
1460 *)
1461 </pre></div></div><br class="example-break" /><div class="example"><a id="id2504173"></a><p class="title"><b>Example 14. A header with source items in Modula-2.</b></p><div class="example-contents"><pre class="programlisting">
1462 (****f* ModuleName/Foo
1463 * FUNCTION
1464 *   Foo computes the foo factor
1465 *   using a fudge factor.
1466 * SYNOPSIS
1467 *)
1468 int Foo( int fudge )
1469 (*
1470 * INPUTS
1471 *   fudge -- the fudge factor
1472 * SOURCE
1473 *)
1474
1475  more source code..
1476
1477 (*****)
1478 </pre></div></div><br class="example-break" /><div class="example"><a id="id2506119"></a><p class="title"><b>Example 15. The robodoc.rc file required for Modula-2 if it were not supported by default.</b></p><div class="example-contents"><pre class="programlisting">
1479 header markers:
1480   (****
1481 remark markers:
1482   *
1483 end markers:
1484   ****
1485   (****
1486 remark begin markers:
1487   (*
1488 remark end markers:
1489   *)
1490 </pre></div></div><br class="example-break" /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2506135"></a>9.3. Pascal</h3></div></div></div><div class="example"><a id="id2506141"></a><p class="title"><b>Example 16. A simple header without any source items in Pascal.</b></p><div class="example-contents"><pre class="programlisting">
1491 {****f* ModuleName/Foo
1492 * FUNCTION
1493 *   Foo computes the foo factor
1494 *   using a fudge factor.
1495 ****
1496 *}
1497 </pre></div></div><br class="example-break" /><div class="example"><a id="id2506156"></a><p class="title"><b>Example 17. A header with source items in Pascal.</b></p><div class="example-contents"><pre class="programlisting">
1498 {****f* ModuleName/Foo
1499 * FUNCTION
1500 *   Foo computes the foo factor
1501 *   using a fudge factor.
1502 * SYNOPSIS
1503 *}
1504 int Foo( int fudge )
1505 {*
1506 * INPUTS
1507 *   fudge -- the fudge factor
1508 * SOURCE
1509 *}
1510
1511  more source code..
1512
1513 {*****}
1514 </pre></div></div><br class="example-break" /><div class="example"><a id="id2506172"></a><p class="title"><b>Example 18. The robodoc.rc file required for Pascal if it were not supported by default.</b></p><div class="example-contents"><pre class="programlisting">
1515 header markers:
1516   {****
1517 remark markers:
1518   *
1519 end markers:
1520   ****
1521   {****
1522 remark begin markers:
1523   {*
1524 remark end markers:
1525   *}
1526 </pre></div></div><br class="example-break" /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2506189"></a>9.4. C++</h3></div></div></div><div class="example"><a id="id2506194"></a><p class="title"><b>Example 19. A simple header without any source items in C++.</b></p><div class="example-contents"><pre class="programlisting">
1527 //****f* ModuleName/Foo
1528 // FUNCTION
1529 //   Foo computes the foo factor
1530 //   using a fudge factor.
1531 //****
1532 </pre></div></div><br class="example-break" /><div class="example"><a id="id2506209"></a><p class="title"><b>Example 20. A header with source items in C++.</b></p><div class="example-contents"><pre class="programlisting">
1533 //****f* ModuleName/Foo
1534 // FUNCTION
1535 //   Foo computes the foo factor
1536 //   using a fudge factor.
1537 // SYNOPSIS
1538 int Foo( int fudge )
1539 // INPUTS
1540 //   fudge -- the fudge factor
1541 // SOURCE
1542
1543  more source code..
1544
1545 //****
1546 </pre></div></div><br class="example-break" /><div class="example"><a id="id2506225"></a><p class="title"><b>Example 21. The robodoc.rc file required for C++ if it were not supported by default.</b></p><div class="example-contents"><pre class="programlisting">
1547 header markers:
1548   //****
1549 remark markers:
1550   //
1551 end markers:
1552   //****
1553 </pre></div></div><br class="example-break" /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2506241"></a>9.5. Tcl</h3></div></div></div><div class="example"><a id="id2506246"></a><p class="title"><b>Example 22. A simple header without any source items in Tcl.</b></p><div class="example-contents"><pre class="programlisting">
1554 #****f* ModuleName/Foo
1555 # FUNCTION
1556 #   Foo computes the foo factor
1557 #   using a fudge factor.
1558 #****
1559 </pre></div></div><br class="example-break" /><div class="example"><a id="id2506261"></a><p class="title"><b>Example 23. A header with source items in Tcl.</b></p><div class="example-contents"><pre class="programlisting">
1560 #****f* ModuleName/Foo
1561 # FUNCTION
1562 #   Foo computes the foo factor
1563 #   using a fudge factor.
1564 # SYNOPSIS
1565 int Foo( int fudge )
1566 # INPUTS
1567 #   fudge -- the fudge factor
1568 # SOURCE
1569
1570  more source code..
1571
1572 #****
1573 </pre></div></div><br class="example-break" /><div class="example"><a id="id2506277"></a><p class="title"><b>Example 24. The robodoc.rc file required for Tcl if it were not supported by default.</b></p><div class="example-contents"><pre class="programlisting">
1574 header markers:
1575   #****
1576 remark markers:
1577   #
1578 end markers:
1579   #****
1580 </pre></div></div><br class="example-break" /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2506293"></a>9.6. Perl</h3></div></div></div><div class="example"><a id="id2506298"></a><p class="title"><b>Example 25. A simple header without any source items in Perl.</b></p><div class="example-contents"><pre class="programlisting">
1581 #****f* ModuleName/Foo
1582 # FUNCTION
1583 #   Foo computes the foo factor
1584 #   using a fudge factor.
1585 #****
1586 </pre></div></div><br class="example-break" /><div class="example"><a id="id2506313"></a><p class="title"><b>Example 26. A header with source items in Perl.</b></p><div class="example-contents"><pre class="programlisting">
1587 #****f* ModuleName/Foo
1588 # FUNCTION
1589 #   Foo computes the foo factor
1590 #   using a fudge factor.
1591 # SYNOPSIS
1592 int Foo( int fudge )
1593 # INPUTS
1594 #   fudge -- the fudge factor
1595 # SOURCE
1596
1597  more source code..
1598
1599 #****
1600 </pre></div></div><br class="example-break" /><div class="example"><a id="id2506329"></a><p class="title"><b>Example 27. The robodoc.rc file required for Perl if it were not supported by default.</b></p><div class="example-contents"><pre class="programlisting">
1601 header markers:
1602   #****
1603 remark markers:
1604   #
1605 end markers:
1606   #****
1607 </pre></div></div><br class="example-break" /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2506344"></a>9.7. LaTeX/TeX</h3></div></div></div><div class="example"><a id="id2506350"></a><p class="title"><b>Example 28. A simple header without any source items in LaTeX/TeX.</b></p><div class="example-contents"><pre class="programlisting">
1608 %****f* ModuleName/Foo
1609 % FUNCTION
1610 %   Foo computes the foo factor
1611 %   using a fudge factor.
1612 %****
1613 </pre></div></div><br class="example-break" /><div class="example"><a id="id2506365"></a><p class="title"><b>Example 29. A header with source items in LaTeX/TeX.</b></p><div class="example-contents"><pre class="programlisting">
1614 %****f* ModuleName/Foo
1615 % FUNCTION
1616 %   Foo computes the foo factor
1617 %   using a fudge factor.
1618 % SYNOPSIS
1619 int Foo( int fudge )
1620 % INPUTS
1621 %   fudge -- the fudge factor
1622 % SOURCE
1623
1624  more source code..
1625
1626 %****
1627 </pre></div></div><br class="example-break" /><div class="example"><a id="id2506381"></a><p class="title"><b>Example 30. The robodoc.rc file required for LaTeX/TeX if it were not supported by default.</b></p><div class="example-contents"><pre class="programlisting">
1628 header markers:
1629   %****
1630 remark markers:
1631   %
1632 end markers:
1633   %****
1634 </pre></div></div><br class="example-break" /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2506397"></a>9.8. Postscript</h3></div></div></div><div class="example"><a id="id2506402"></a><p class="title"><b>Example 31. A simple header without any source items in Postscript.</b></p><div class="example-contents"><pre class="programlisting">
1635 %****f* ModuleName/Foo
1636 % FUNCTION
1637 %   Foo computes the foo factor
1638 %   using a fudge factor.
1639 %****
1640 </pre></div></div><br class="example-break" /><div class="example"><a id="id2506417"></a><p class="title"><b>Example 32. A header with source items in Postscript.</b></p><div class="example-contents"><pre class="programlisting">
1641 %****f* ModuleName/Foo
1642 % FUNCTION
1643 %   Foo computes the foo factor
1644 %   using a fudge factor.
1645 % SYNOPSIS
1646 int Foo( int fudge )
1647 % INPUTS
1648 %   fudge -- the fudge factor
1649 % SOURCE
1650
1651  more source code..
1652
1653 %****
1654 </pre></div></div><br class="example-break" /><div class="example"><a id="id2506434"></a><p class="title"><b>Example 33. The robodoc.rc file required for Postscript if it were not supported by default.</b></p><div class="example-contents"><pre class="programlisting">
1655 header markers:
1656   %****
1657 remark markers:
1658   %
1659 end markers:
1660   %****
1661 </pre></div></div><br class="example-break" /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id2506449"></a>9.9. Occam</h3></div></div></div><div class="example"><a id="id2506455"></a><p class="title"><b>Example 34. A simple header without any source items in Occam.</b></p><div class="example-contents"><pre class="programlisting">
1662 __****f* ModuleName/Foo
1663 __ FUNCTION
1664 __   Foo computes the foo factor
1665 __   using a fudge factor.
1666 __****
1667 </pre></div></div><br class="example-break" /><div class="example"><a id="id2506470"></a><p class="title"><b>Example 35. A header with source items in Occam.</b></p><div class="example-contents"><pre class="programlisting">
1668 __****f* ModuleName/Foo
1669 __ FUNCTION
1670 __   Foo computes the foo factor
1671 __   using a fudge factor.
1672 __ SYNOPSIS
1673 int Foo( int fudge )
1674 __ INPUTS
1675 __   fudge -- the fudge factor
1676 __ SOURCE
1677
1678  more source code..
1679
1680 __****
1681 </pre></div></div><br class="example-break" /><div class="example"><a id="id2506486"></a><p class="title"><b>Example 36. The robodoc.rc file required for Occam if it were not supported by default.</b></p><div class="example-contents"><pre class="programlisting">
1682 header markers:
1683   __****
1684 remark markers:
1685   __
1686 end markers:
1687   __****
1688 </pre></div></div><br class="example-break" /></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2505449"></a>10. Suggestions and Bugs</h2></div></div></div><p>If you find any bugs, catch them, put them in a jar, and
1689     send them to: Frans Slothouber at rfsber {at} xs4all.nl.   Suggestions are also welcome at
1690     this address.  Flames can be directed to the sun.</p></div></div></body></html>