util/robodoc/Docs/robodoc.html

   1
   2 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"><HTML>
   3 <HEAD><LINK rel=stylesheet href="main.css"><TITLE>ROBODoc Manual</TITLE></HEAD>
   4 <BODY>
   5 <H1>ROBODoc 3.2.3 Manual</H1>
   6
   7 <P><STRONG>Updated July 2000</STRONG></P>
   8
   9 <P>ROBODoc is a documentation tool for C, C++, Java, Assembler, Basic,
  10 Fortran, LaTeX, Postscript, Tcl/Tk, LISP, Forth, Perl, Shell
  11 Scripts, Occam, COBOL, HTML and many other languages. Additional
  12 languages can be supported by a few modifications to the source
  13 code.</P>
  14
  15 <P>Copyright (C) 1994-2000 Frans Slothouber and Jacco van Weert.</P>
  16
  17 <P>This program is free software; you can redistribute it and/or
  18 modify it under the terms of the GNU General Public License as
  19 published by the Free Software Foundation; either version 2 of
  20 the License, or (at your option) any later version.</P>
  21
  22 <P>This program is distributed in the hope that it will be
  23 useful, but WITHOUT ANY WARRANTY; without even the implied
  24 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  25 See the GNU General Public License for more details.</P>
  26
  27 <P>You should have received a copy of the GNU General Public
  28 License along with this program; if not, write to the Free
  29 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  30 02111-1307 USA</P>
  31
  32
  33
  34  <H2><font color="red">1  </font><A NAME="creds">Credits</A></H2>
  35
  36 <UL>
  37
  38   <LI>Original program and idea: Jacco van Weert</LI>
  39
  40   <LI>Versions 2.0 and up: Frans Slothouber, Petteri Kettunen,
  41       Bernd Koesling, Anthon Pang, Thomas Aglassinger,
  42       and Stefan Kost, Guillaume Etorre, Simo Muinonen,
  43       Petter Reinholdtsen.
  44   </LI>
  45
  46   <LI>Maintainer: Frans Slothouber (fslothouber@acm.org),
  47       The Netherlands.</LI>
  48
  49 </UL>
  50
  51
  52  <H2><font color="red">2  </font><A NAME="toc">Table of Contents</A></H2>
  53
  54 <STRONG><FONT COLOR="red">01</FONT>......... <A HREF="#creds">Credits</A></STRONG><BR>
  55 <STRONG><FONT COLOR="red">02</FONT>......... <A HREF="#toc">Table of Contents</A></STRONG><BR>
  56 <STRONG><FONT COLOR="red">03</FONT>......... <A HREF="#INTRO">Introduction</A></STRONG><BR>
  57 <STRONG><FONT COLOR="red">04</FONT>......... <A HREF="#HSR">Hardware and software requirements</A></STRONG><BR>
  58 <STRONG><FONT COLOR="red">05</FONT>......... <A HREF="#LMT">Goals and Limitations</A></STRONG><BR>
  59 <STRONG><FONT COLOR="red">06</FONT>......... <A HREF="#HFCWR">How to Format Your Code for use with ROBODoc</A></STRONG><BR>
  60 <STRONG><font color="red">06.01</font>.......... <A HREF="#hname">Header Names</A></STRONG><BR>
  61 <STRONG><font color="red">06.02</font>.......... <A HREF="#htypes">Header Types</A></STRONG><BR>
  62 <STRONG><font color="red">06.03</font>.......... <A HREF="#bmar">Begin Marker</A></STRONG><BR>
  63 <STRONG><font color="red">06.04</font>.......... <A HREF="#rmarker">Remark Marker</A></STRONG><BR>
  64 <STRONG><font color="red">06.05</font>.......... <A HREF="#emar">End Marker</A></STRONG><BR>
  65 <STRONG><font color="red">06.06</font>.......... <A HREF="#hitem">Header Items</A></STRONG><BR>
  66 <STRONG><font color="red">06.07</font>.......... <A HREF="#inlimits">Item Name Limitations</A></STRONG><BR>
  67 <STRONG><font color="red">06.08</font>.......... <A HREF="#SI">Source Item</A></STRONG><BR>
  68 <STRONG><FONT COLOR="red">07</FONT>......... <A HREF="#CLD">Creating Cross Links</A></STRONG><BR>
  69 <STRONG><font color="red">07.01</font>.......... <A HREF="#limits">Limitations</A></STRONG><BR>
  70 <STRONG><FONT COLOR="red">08</FONT>......... <A HREF="#MAIND">Master Index File</A></STRONG><BR>
  71 <STRONG><font color="red">08.01</font>.......... <A HREF="#MIEXM">examples</A></STRONG><BR>
  72 <STRONG><FONT COLOR="red">09</FONT>......... <A HREF="#makefile">Automation with <TT>make</TT></A></STRONG><BR>
  73 <STRONG><FONT COLOR="red">10</FONT>......... <A HREF="#MDSO">What to do if You have Sources in Multiple Directories</A></STRONG><BR>
  74 <STRONG><FONT COLOR="red">11</FONT>......... <A HREF="#RDF">The ROBODoc Defaults File</A></STRONG><BR>
  75 <STRONG><FONT COLOR="red">12</FONT>......... <A HREF="#UOB">ROBODoc Command Line Options</A></STRONG><BR>
  76 <STRONG><FONT COLOR="red">13</FONT>......... <A HREF="#ADV">Adding New Languages</A></STRONG><BR>
  77 <STRONG><FONT COLOR="red">14</FONT>......... <A HREF="#SAB">Suggestions and Bugs</A></STRONG><BR>
  78
  79
  80
  81
  82  <H2><font color="red">3  </font><A NAME="INTRO">Introduction</A></H2>
  83
  84 <P>ROBODoc is based on the AutoDocs program written some time ago
  85 by Commodore.  The idea is to include for every function a
  86 standard header containing all sorts of information about that
  87 procedure/function.  An AutoDocs program extracts these headers
  88 from the source file and puts them in an autodocs file.  This
  89 allows you to include the program documentation in the source
  90 code and makes it unnecessary to maintain two documents.</P>
  91
  92
  93 <P>ROBODoc is such a program, however ROBODoc has several
  94 additions.  For one it can generate the documentation in
  95 different formats, ASCII, HTML, RTF, LaTeX, and AmigaGuide.
  96 Another feature is that it automatically creates links within the
  97 document, and to other documents.  It is also possible to include
  98 parts of the source in you documentation, complete with links.
  99 For instance it is possible to include the complete source code
 100 of a function, and have the function names in the source point to
 101 their documentation. Besides documenting functions, you can also
 102 document classes, methods, structures, variables, and
 103 constants.</P>
 104
 105
 106 <P>If you never have used AutoDoc or ROBODoc before you might
 107 take a look at the example in the <TT>Source/</TT>.  Run the
 108 command:</P>
 109
 110 <PRE>
 111   make xhtml
 112   make example
 113 </PRE>
 114
 115
 116 <P>This creates the ROBODoc
 117 <A HREF="../Source/ROBODoc_mi.html">documentation</A> for the
 118 ROBODoc program itself and then starts netscape to view the
 119 documentation. Also have a look at the source files, they
 120 illustrates the use of headers.</P>
 121
 122 <P>ROBODoc can generate documentation in five different
 123 formats:</P>
 124
 125 <UL>
 126   <LI>HTML format complete with hyperlinks and mark-ups.</LI>
 127
 128   <LI>LaTeX, based on D. Knuth excellent typesetting system.</LI>
 129
 130   <LI>Plain ASCII text file, this file is very close to what the
 131       original AutoDocs program would generate.</LI>
 132
 133   <LI>RTF, Rich Text Format, mostly used on Windows machines
 134       before WWW revolution.</LI>
 135
 136   <LI>AmigaGuide format, it is the Amiga computer's equivalent
 137       HTML. The AmigaGuide program is necessary to view the
 138       resulting autodocs-file. (This was the preferred format when the
 139       program was written in 1994.)</LI>
 140
 141 </UL>
 142
 143
 144  <H2><font color="red">4  </font><A NAME="HSR">Hardware and software requirements</A></H2>
 145
 146 <P>ROBODoc was developed in 1994 on a standard Amiga 1200, a
 147 system with a 20MHz 68020 processor and 2 Mbyte of RAM. It should
 148 therefore be no problem to run it on any of the currently
 149 available systems :) The complete source code consists of a
 150 series of file that can be found in the <TT>Source</TT>
 151 directory.  It is written according (hopefully) to the ANSI C
 152 standard and uses no special functions, so it should run on every
 153 system with an ANSI C-compiler.</P>
 154
 155
 156  <H2><font color="red">5  </font><A NAME="LMT">Goals and Limitations</A></H2>
 157
 158 <P>ROBODoc is intended for small to medium sized projects
 159 that have a relatively flat structure and especially projects
 160 that use a mix of different programming languages.</P>
 161
 162 <P>
 163 ROBODoc was designed to be easy to use and to work with a lot of
 164 different programming languages.  It has no knowledge of the
 165 syntax of a programming languages.  It just some knowledge about
 166 how remarks start and end in some programming languages. This
 167 means that you sometimes have to do a little more work compared
 168 to other tools that have detailed knowledge of the syntax of a
 169 particular language.  They can use that knowledge to figure out
 170 some of the information automatically.  This usually also means
 171 that they work only with one or two languages.
 172 </P>
 173
 174 <P>ROBODoc operates on one file at a time.  It has no mechanism to
 175 process whole sets of source files. Makefiles should be used for
 176 this.  How to do this is explained in this document with various
 177 example makefiles. Have a look at them.
 178 </P>
 179
 180 <P>ROBODoc can work with projects where the source code is located
 181 in different subdirectories. However the generated documentation is
 182 expected to go into one single directory.</P>
 183
 184
 185  <H2><font color="red">6  </font><A NAME="HFCWR">How to Format Your Code for use with ROBODoc</A></H2>
 186
 187 <P>ROBODoc allows you to mix the program documentation with the
 188 source code.  It does require though that this documentation has
 189 a particular layout so ROBODoc can recognize it. The following
 190 header was taken from the original ROBODoc program (many versions
 191 back).</P>
 192
 193 <TABLE>
 194 <TR>
 195 <TD>
 196 <PRE>
 197            <FONT COLOR="red">------------------------------- Header Name</FONT>
 198           <FONT COLOR="red">/                          \</FONT>
 199   /****f* financial.library/StealMoney  <FONT COLOR="red">&lt;---- Begin Marker</FONT>
 200   *    <FONT COLOR="red">^------- Header Type</FONT>
 201   *
 202   *  <FONT COLOR="red">&lt;---- Remark Marker</FONT>
 203   *  NAME
 204   *    StealMoney -- Steal money from the Federal Reserve Bank. (V77)
 205   *  SYNOPSIS  <FONT COLOR="red">&lt;---- Item Name</FONT>
 206   *    error = StealMoney( userName,amount,destAccount,falseTrail )
 207   *    D0,Z                D0       D1.W    A0         [A1]
 208   *
 209   *    BYTE StealMoney
 210   *         ( STRPTR,UWORD,struct AccountSpec *,struct falseTrail *);
 211   *  FUNCTION
 212   *    Transfer money from the Federal Reserve Bank into the
 213   *    specified interest-earning checking account.  No records of
 214   *    the transaction will be retained.
 215   *  INPUTS
 216   *    userName    - name to make the transaction under.  Popular
 217   *                  favorites include "Ronald Reagan" and
 218   *                  "Mohamar Quadaffi".
 219   *    amount      - Number of dollars to transfer (in thousands).
 220   *    destAccount - A filled-in AccountSpec structure detailing the
 221   *                  destination account (see financial/accounts.h).
 222   *                  If NULL, a second Great Depression will be
 223   *                  triggered.
 224   *    falseTrail  - If the DA_FALSETRAIL bit is set in the
 225   *                  destAccount, a falseTrail structure must be
 226   *                  provided.
 227   *  RESULT
 228   *    error - zero for success, else an error code is returned
 229   *           (see financial/errors.h).  The Z condition code
 230   *           is guaranteed.
 231   *  EXAMPLE
 232   *    Federal regulations prohibit a demonstration of this function.
 233   *  NOTES
 234   *    Do not run on Tuesdays!
 235   *  BUGS
 236   *    Before V88, this function would occasionally print the
 237   *    address and home phone number of the caller on local police
 238   *    976 terminals.  We are confident that this problem has been
 239   *    resolved.
 240   *  SEE ALSO
 241   *    CreateAccountSpec(),security.device/SCMD_DESTROY_EVIDENCE,
 242   *    financial/misc.h
 243   *
 244   ******  <FONT COLOR="red">&lt;---- End Marker</FONT>
 245   *
 246   * You can use this space for remarks that should not be included
 247   * in the documentation.
 248   *
 249   */
 250 </PRE>
 251 </TD>
 252 </TR>
 253 </TABLE>
 254
 255 <P>You would place this headers in front of functions, classes,
 256 methods, structure definitions, or any of the major components in
 257 your program.  The header itself contains a number of items that
 258 provide structured information about the component. </P>
 259
 260 <P>There are a number of special markers in a header (indicated
 261 in red above).  There are two special markers that mark the begin
 262 and end of a header.  Each line in a header should start with a
 263 remark marker.  The starts of each item is marked by an Item Name
 264 (in all capitals).</P>
 265
 266
 267 <H3><font color="red">6.1  </font><A NAME="hname">Header Names</A></H3>
 268
 269 <P>ROBODoc makes some assumptions about the structure a project.
 270 It assumes that a project consists of a number of modules, and
 271 that each module consists of a number of components.  These
 272 components can be anything that you care to document; functions,
 273 variables, structures, classes, methods etc.</P>
 274
 275 <P> Projects, modules, and components all have names.  The names
 276 allow ROBODoc to structure the documentation and create
 277 cross-links. Names are defined in the header name.  It is either
 278 of the form <TT> &lt;project name&gt;/&lt;module name&gt;</TT>
 279 for a module header, or of the form <TT>&lt;module
 280 name&gt;/&lt;component name&gt;</TT> for all other headers.</P>
 281
 282 <H3><font color="red">6.2  </font><A NAME="htypes">Header Types</A></H3>
 283
 284 <P>You can provide ROBODoc with some additional information
 285 by specifying the header type.  The header type tells ROBODoc
 286 what kind of component you are documenting. This information
 287 allows ROBODoc to create more useful index tables.</P>
 288
 289 <P>The type is identified by a single character, as listed in the
 290 following table</P>
 291
 292 <TABLE>
 293 <TR><TD>h</TD><TD>Header for a module in a project.</TD></TR>
 294 <TR><TD>f</TD><TD>Header for a function.</TD></TR>
 295 <TR><TD>s</TD><TD>Header for a structure.</TD></TR>
 296 <TR><TD>c</TD><TD>Header for a class.</TD></TR>
 297 <TR><TD>m</TD><TD>Header for a method.</TD></TR>
 298 <TR><TD>v</TD><TD>Header for a variable.</TD></TR>
 299 <TR><TD>d</TD><TD>Header for a constant
 300 (from <STRONG>d</STRONG>efine).</TD></TR>
 301 <TR><TD>*</TD><TD>Generic header for every thing else.</TD></TR>
 302 <TR><TD>i</TD><TD>Internal header.</TD></TR>
 303 </TABLE>
 304
 305 <P>Internal headers are special. They can be used to hide certain
 306 headers. They are only extracted if requested. You could use to
 307 document internal functions that you do now want clients to
 308 see.</P>
 309
 310
 311 <H3><font color="red">6.3  </font><A NAME="bmar">Begin Marker</A></H3>
 312
 313 <P>The beginning of a header is marked with a special marker.
 314 The above header is intended for a program in C.  In other
 315 programming languages the marker looks slightly different, since
 316 each language has its own convention for starting remarks.
 317 ROBODoc recognizes the following begin markers:</P>
 318
 319 <TABLE >
 320 <TR><TD><TT>"/****"</TT>
 321     <TD>C, C++</TD>
 322 </TR>
 323 <TR><TD><TT>"//****"</TT></TD>
 324     <TD>C++</TD>
 325 </TR>
 326 <TR><TD><TT>";****"</TT></TD>
 327     <TD>Assembler</TD>
 328 </TR>
 329 <TR><TD><TT>"****"</TT></TD>
 330     <TD>Assembler</TD>
 331 </TR>
 332 <TR><TD><TT>"{****"</TT></TD>
 333     <TD>Pascal</TD>
 334 </TR>
 335 <TR><TD><TT>"REM ****"</TT></TD>
 336     <TD>Basic (Rem, rem, or even rEM also works)</TD>
 337 </TR>
 338 <TR><TD><TT>"C     ****"</TT></TD>
 339     <TD>Fortran (c     **** also works)</TD>
 340 </TR>
 341 <TR><TD><TT>"%****"</TT></TD>
 342     <TD>LaTeX, TeX, Postscript.</TD>
 343 </TR>
 344 <TR><TD><TT>"#****"</TT></TD>
 345     <TD>Tcl/Tk, Perl, makefiles, gnuplot etc.</TD>
 346 </TR>
 347 <TR><TD><TT>"(****"</TT></TD>
 348     <TD>Pascal, Modula-2, LISP</TD>
 349 </TR>
 350 <TR><TD><TT>"--****"</TT></TD>
 351     <TD>Occam</TD>
 352 </TR>
 353 <TR><TD><TT>"&lt;!--****"</TT></TD>
 354     <TD>HTML</TD>
 355 </TR>
 356 <TR><TD><TT>"&lt;!---****"</TT></TD>
 357     <TD>HTML</TD>
 358 </TR>
 359 <TR><TD><TT>"|****"</TT></TD>
 360     <TD>GNU Assembler</TD>
 361 </TR>
 362 <TR><TD><TT>"!!****"</TT></TD>
 363     <TD>Fortran 90</TD>
 364 </TR>
 365 </TABLE>
 366
 367 <P>After these initial four asterisks, there is the character to
 368 identify the kind of header, then another asterisks, and then
 369 header name. After this you can specify a version number
 370 surrounded by "[]". The version number is stored but not used for
 371 anything at the moment. All characters after that are
 372 ignored.</P>
 373
 374 <P>This might sound terribly complicated, it is not. Here are
 375 some examples:</P>
 376
 377 <P>A header for a module called analyser in a project called ChessMaster
 378 for C, is has version number 1.0</P>
 379 <PRE>
 380   /****h* ChessMaster/analyser [1.0] *
 381 </PRE>
 382
 383 <P>In Assembler, a function header, for the function init() in the
 384   module finance.library:</P>
 385 <PRE>
 386   ****f* finance.library/init *
 387 </PRE>
 388
 389 <P>In C++, a class header for class Puppet, for the module puppetmaster,
 390 version v2.12</P>
 391 <PRE>
 392   /****c* puppetMaster/Puppet [v2.12] ******
 393 </PRE>
 394
 395 <P>For the same class a method called Puppet::Talk</P>
 396 <PRE>
 397   /****m* puppetMaster/Puppet::Talk [v2.12] ******
 398 </PRE>
 399
 400 <P>A project header, in Fortran</P>
 401 <PRE>
 402   C     ****h* ChessMaster/analyser              C
 403 </PRE>
 404
 405 <P>In Basic</P>
 406 <PRE>
 407   REM ****h* ChessMaster/analyser
 408 </PRE>
 409
 410
 411
 412 <H3><font color="red">6.4  </font><A NAME="rmarker">Remark Marker</A></H3>
 413
 414 <P>Each line in the body of a header should start with a remark
 415 marker.  This marker is stripped from the line and the remaining
 416 part is used to generated the documentation.  The following
 417 markers are recognized by ROBODoc.</P>
 418
 419 <TABLE >
 420 <TR><TD><TT>"*"</TT></TD>
 421     <TD>C, C++, Pascal, Modula-2</TD>
 422 </TR>
 423 <TR><TD><TT>"//"</TT></TD>
 424     <TD>C++</TD>
 425 </TR>
 426 <TR><TD><TT>" *"</TT></TD>
 427     <TD>C, C++, M68K assembler, Pascal, Modula-2, HTML</TD>
 428 </TR>
 429 <TR><TD><TT>";*"</TT></TD>
 430     <TD>M68K assembler</TD>
 431 </TR>
 432 <TR><TD><TT>";"</TT></TD>
 433     <TD>M68K assembler</TD>
 434 </TR>
 435 <TR><TD><TT>"C    "</TT></TD>
 436     <TD>Fortran</TD>
 437 </TR>
 438 <TR><TD><TT>"REM "</TT></TD>
 439     <TD>BASIC</TD>
 440 </TR>
 441 <TR><TD><TT>"%"</TT></TD>
 442     <TD>LaTeX, TeX, Postscript</TD>
 443 </TR>
 444 <TR><TD><TT>"#"</TT></TD>
 445     <TD>Tcl/Tk, shell scripts, makefiles</TD>
 446 </TR>
 447 <TR><TD><TT>"      *"</TT></TD>
 448     <TD>COBOL</TD>
 449 </TR>
 450 <TR><TD><TT>"--"</TT></TD>
 451     <TD>Occam</TD>
 452 </TR>
 453 <TR><TD><TT>"|"</TT></TD>
 454     <TD>GNU Assembler</TD>
 455 </TR>
 456 <TR><TD><TT>"!!"</TT></TD>
 457     <TD>Fortan 90</TD>
 458 </TR>
 459 </TABLE>
 460
 461
 462
 463
 464 <H3><font color="red">6.5  </font><A NAME="emar">End Marker</A></H3>
 465
 466 <P>A header ends with an end marker.  An end marker is a remark
 467 marker followed by three asterisks.  ROBODoc recognizes following
 468 strings as end markers:</P>
 469
 470 <TABLE >
 471 <TR><TD><TT>"/***"</TT></TD>
 472     <TD> C, C++ </TD></TR>
 473 <TR><TD><TT>"//***"</TT></TD>
 474     <TD> C++ </TD></TR>
 475 <TR><TD><TT>" ****"</TT></TD>
 476     <TD> C, C++, Pascal, Modula-2 </TD></TR>
 477 <TR><TD><TT>"{***"</TT></TD>
 478     <TD> Pascal </TD></TR>
 479 <TR><TD><TT>"(***"</TT></TD>
 480     <TD> Pascal, Modula-2, B52 LISP</TD></TR>
 481 <TR><TD><TT>";***"</TT></TD>
 482     <TD> M68K assembler </TD></TR>
 483 <TR><TD><TT>"****"</TT></TD>
 484     <TD> M68K assembler </TD></TR>
 485 <TR><TD><TT>"C     ***"</TT></TD>
 486     <TD> Fortran </TD></TR>
 487 <TR><TD><TT>"REM ***"</TT></TD>
 488     <TD> BASIC </TD></TR>
 489 <TR><TD><TT>"%***"</TT></TD>
 490     <TD> LaTeX, TeX, Postscript </TD></TR>
 491 <TR><TD><TT>"#***"</TT></TD>
 492     <TD> Tcl/Tk, Perl, Makefiles, Shell scripts </TD></TR>
 493 <TR><TD><TT>"      ****"</TT></TD>
 494     <TD> COBOL </TD></TR>
 495 <TR><TD><TT>"--***"</TT></TD>
 496     <TD> Occam </TD></TR>
 497 <TR><TD><TT>"&lt;!--***"</TT></TD>
 498     <TD> HTML </TD></TR>
 499 <TR><TD><TT>"&lt;!---***"</TT></TD>
 500     <TD> HTML </TD></TR>
 501 <TR><TD><TT>"|***"</TT></TD>
 502     <TD>GNU Assembler</TD></TR>
 503 <TR><TD><TT>"!!***"</TT></TD>
 504     <TD>Fortan 90</TD></TR>
 505 </TABLE>
 506
 507
 508
 509
 510 <H3><font color="red">6.6  </font><A NAME="hitem">Header Items</A></H3>
 511
 512 <P>When ROBODoc has found a header it will try to identify the
 513 items in this header.  It does this by looking for the item name. The following
 514 item names are currently supported:</P>
 515
 516 <TABLE >
 517 <TR><TD> NAME </TD>
 518     <TD> Item name plus a short description. </TD>
 519 <TR><TD> COPYRIGHT </TD>
 520     <TD> Who own the copyright : "(c) &lt;year&gt;-&lt;year&gt; by
 521          &lt;company/person&gt;" </TD>
 522 <TR><TD> SYNOPSIS, USAGE </TD>
 523     <TD> How to use it. </TD>
 524 <TR><TD> FUNCTION, DESCRIPTION,  PURPOSE </TD>
 525     <TD> What does it do. </TD>
 526 <TR><TD> AUTHOR </TD>
 527     <TD>Who wrote it. </TD>
 528 <TR><TD> CREATION DATE </TD>
 529     <TD> When did the work start. </TD>
 530 <TR><TD> MODIFICATION HISTORY,  HISTORY </TD>
 531     <TD> Who has done which changes and when. </TD>
 532 <TR><TD> INPUTS, ARGUMENTS, OPTIONS, PARAMETERS, SWITCHES </TD>
 533     <TD> What can we feed into it.  </TD>
 534 <TR><TD> OUTPUT, SIDE EFFECTS </TD>
 535     <TD> What output is made. </TD>
 536 <TR><TD> RESULT, RETURN VALUE </TD>
 537     <TD> What do we get returned. </TD>
 538 <TR><TD> EXAMPLE  </TD>
 539     <TD> A clear example of the items use. </TD>
 540 <TR><TD> NOTES </TD>
 541     <TD> Any annotations </TD>
 542 <TR><TD> DIAGNOSTICS  </TD>
 543     <TD>Diagnostical output  </TD>
 544 <TR><TD> WARNINGS, ERRORS  </TD>
 545     <TD> Warning & error-messages. </TD>
 546 <TR><TD> BUGS </TD>
 547     <TD> Known bugs. </TD>
 548 <TR><TD> TODO, IDEAS  </TD>
 549     <TD> What to implement next & ideas. </TD>
 550 <TR><TD> PORTABILITY </TD>
 551     <TD> Where does it come from, where will it work. </TD>
 552 <TR><TD> SEE ALSO </TD>
 553     <TD> References to other functions, man pages, other documentation. </TD>
 554 <TR><TD> METHODS, NEW METHODS </TD>
 555     <TD> OOP methods. </TD>
 556 <TR><TD> ATTRIBUTES, NEW ATTRIBUTES </TD>
 557     <TD> OOP attributes  </TD>
 558 <TR><TD> TAGS </TD>
 559     <TD> Tag-item description. </TD>
 560 <TR><TD> COMMANDS </TD>
 561     <TD> Command description. </TD>
 562 <TR><TD> DERIVED FROM </TD>
 563     <TD> OOP super class. </TD>
 564 <TR><TD> DERIVED BY </TD>
 565     <TD> OOP sub class. </TD>
 566 <TR><TD> USES, CHILDREN </TD>
 567     <TD> What modules are used by this one. </TD>
 568 <TR><TD> USED BY, PARENTS </TD>
 569     <TD> Which modules do use this one. </TD>
 570 <TR><TD> SOURCE </TD>
 571     <TD> Source code inclusion. </TD>
 572 </TABLE>
 573
 574 <P>ROBODoc does this so that it can format each item with a
 575 different style (colour, font, etc.) if the user want it.  These
 576 can be specified in the robodoc.defaults file, see the next
 577 section more information.</P>
 578
 579
 580 <H3><font color="red">6.7  </font><A NAME="inlimits">Item Name Limitations</A></H3>
 581
 582 <P>If you happen to have a function which name is in all uppercase,
 583 this sometimes conflicts with where ROBODoc thinks an item name
 584 starts and where the item body starts.
 585 Bernhard Roessmann suggest the following workaround:
 586 Example header producing this error:</P>
 587 <PRE>
 588 /***** basic.c/RETURN
 589 * NAME
 590 *  RETURN : Return from subroutine
 591 * SYNOPSIS
 592 *  RETURN
 593 * FUNCTION
 594 *  Return from subroutine
 595 ******/
 596 </PRE>
 597 <P>Here the item name  "FUNCTION" will be interpreted as ordinary text,
 598 not as an item name.  Workaround: Add an empty line:</P>
 599 <PRE>
 600 /***** basic.c/RETURN
 601 * NAME
 602 *  RETURN : Return from subroutine
 603 * SYNOPSIS
 604 *  RETURN
 605 *
 606 * FUNCTION
 607 *  Return from subroutine
 608 ******/
 609 </PRE>
 610
 611
 612
 613 <H3><font color="red">6.8  </font><A NAME="SI">Source Item</A></H3>
 614
 615 <P>The source item allows you to include part of the source in
 616 the documentation as is demonstrated by the following
 617 example.</P>
 618
 619 <TABLE><TR><TD><PRE>
 620 /****f* Robodoc/RB_Panic [2.0d]
 621  * NAME
 622  *   RB_Panic -- Shout panic, free resources, and shut down.
 623  * SYNOPSIS
 624  *   RB_Panic (cause, add_info)
 625  *   RB_Panic (char *, char *)
 626  * FUNCTION
 627  *   Prints an error message.
 628  *   Frees all resources used by robodoc.
 629  *   Terminates program.
 630  * INPUTS
 631  *   cause    - pointer to a string which describes the
 632  *              cause of the error.
 633  *   add_info - pointer to a string with additional information.
 634  * SEE ALSO
 635  *   RB_Close_The_Shop ()
 636  * SOURCE
 637  */
 638
 639   void RB_Panic (char *cause, char *add_info)
 640   {
 641     printf ("Robodoc: Error, %s\n",cause) ;
 642     printf ("         %s\n", add_info) ;
 643     printf ("Robodoc: Panic Fatal error, closing down...\n") ;
 644     RB_Close_The_Shop () ; /* Free All Resources */
 645     exit(100) ;
 646   }
 647
 648 /*******/
 649
 650 </PRE></TD></TABLE>
 651
 652 <P>This would create the following documentation</P>
 653
 654 <TABLE><TR><TD>
 655 <FONT SIZE="+1">NAME</FONT>
 656 <PRE><EM>   <B>RB_Panic</B> -- Shout panic, free resources, and shut down.
 657 </EM></PRE><FONT SIZE="+1">SYNOPSIS</FONT>
 658 <PRE>   <B>RB_Panic</B> (cause, add_info)
 659    <B>RB_Panic</B> (char *, char *)
 660 </PRE><FONT SIZE="+1">FUNCTION</FONT>
 661 <PRE>   Prints an error message.
 662    Frees all resources used by robodoc.
 663    Terminates program.
 664 </PRE><FONT SIZE="+1">INPUTS</FONT>
 665 <PRE>   cause    - pointer to a string which describes the
 666               cause of the error.
 667    add_info - pointer to a string with additional information.
 668 </PRE><FONT SIZE="+1">SEE ALSO</FONT>
 669 <PRE>   RB_Close_The_Shop ()
 670 </PRE><FONT SIZE="+1">SOURCE</FONT>
 671 <PRE>      void <B>RB_Panic</B> (char *cause, char *add_info)
 672       {
 673         printf ("Robodoc: Error, %s\n",cause) ;
 674         printf ("         %s\n", add_info) ;
 675         printf ("Robodoc: Panic Fatal error, closing down...\n") ;
 676         RB_Close_The_Shop () ; <FONT COLOR = "#FF0000">/* Free All Resources */</FONT>
 677         exit(100) ;
 678       }
 679 </PRE></TD></TR></TABLE>
 680
 681
 682
 683
 684  <H2><font color="red">7  </font><A NAME="CLD">Creating Cross Links</A></H2>
 685
 686 <P>Creating hyper links within a document and across documents
 687 is the most interesting feature of ROBODoc.  A document with such
 688 links is much more easier to read.  If your source code consists
 689 of just one file, creating links is easy.  Just tell ROBODoc that
 690 you want to have the output in HTML or AmigaGuide format, and it
 691 will automatically generate the links.  That is, at the beginning
 692 of the document it will create a table of contents that consists
 693 of links to all your function headers.</P>
 694
 695 <P>ROBODoc will also search the complete text of you
 696 documentation for reference to function names, and it will create
 697 a link to the documentation of that function.</P>
 698
 699 <P>In most cases, however, your source code does not consists of
 700 a single file.  It is also possible, however, to create links to
 701 other files.  This does require the use of some additional files,
 702 called xref files. These files can be generated with ROBODoc.
 703 These files contain information about in which file and where in
 704 the file references can be found.</P>
 705
 706 <P>Lets assume your project is split up in five different source
 707 files, and you want to generate links between these five files.
 708 What you have to do to accomplish this is to create a xref file
 709 for each of those five files.</P>
 710
 711 <P>With the GENXREF option ROBODoc will generate such a xref file
 712 from the a source-file.  When you use this option, only the xref
 713 file is created not the autodocs-file, however you still have to
 714 specify the name of the autodocs file because this name is needed
 715 for the creation of the xref file.</P>
 716
 717 <P>When all xref files are created you are ready to create the
 718 documentation.  To do so you use ROBODOC with the XREF option. It
 719 needs a parameter which is the name of the file in which the
 720 names of all xref files are defined.  Notice: this is a file with
 721 file names, it has to be created it by hand.</P>
 722
 723 <P>An example will make things more clear. In the ROBODoc
 724 archive, under <TT>examples/C</TT> there are two source files
 725 <A HREF="../Examples/C/prog1.c">prog1.c</A> and
 726 <A HREF="../Examples/C/prog2.c">prog2.c</A>.  We can create
 727 documentation with hyper links from these two files as follows:
 728 </P>
 729
 730 <P>First create the xref files:</P>
 731
 732 <TABLE>
 733 <TR>
 734 <TD>
 735 <PRE>
 736   robodoc prog1.c prog1.c.html GENXREF prog1.c.xref HTML INTERNAL
 737   robodoc prog2.c prog2.c.html GENXREF prog2.c.xref HTML INTERNAL
 738 </PRE>
 739 </TD>
 740 </TR>
 741 </TABLE>
 742
 743 <P>Now there are two xref files: prog1.c.xref and prog2.c.xref.
 744 Note that ROBODoc did not create any HTML files, just the xref
 745 files. The name prog1.c.html is needed to create the correct xref
 746 files.  For prog1.c internal headers were also included. </P>
 747
 748 <P>Now create a file with the xref file names.  This file will
 749 hold only two lines. You can give it any name, say
 750 <TT>xref_files</TT>.</P>
 751 <TABLE>
 752 <TR>
 753 <TD>
 754 <PRE>
 755   echo prog1.c.xref &gt;  xref_files
 756   echo prog2.c.xref &gt;&gt; xref_files
 757 </PRE>
 758 </TD>
 759 </TR>
 760 </TABLE>
 761 <P>Now generate the final documentation:</P>
 762 <TABLE>
 763 <TR>
 764 <TD>
 765 <PRE>
 766   robodoc prog1.c prog1.c.html XREF xref_files HTML INTERNAL
 767   robodoc prog2.c prog2.c.html XREF xref_files HTML INTERNAL
 768 </PRE>
 769 </TD>
 770 </TR>
 771 </TABLE>
 772
 773 <P>Have a look the the documentation generated:</P>
 774 <OL>
 775   <LI><A HREF="../Examples/C/prog1.c.html">prog1.c.html</A></LI>
 776   <LI><A HREF="../Examples/C/prog2.c.html">prog2.c.html</A></LI>
 777 </OL>
 778
 779
 780
 781 <H3><font color="red">7.1  </font><A NAME="limits">Limitations</A></H3>
 782
 783 <P> ROBODoc knows very little about the grammar of programming
 784 languages.  Links are created by looking up words in a table.
 785 This means that it sometimes creates links where there should be
 786 none.  For instance if you have a function called usage(); every
 787 time you use the word usage in any of your documentation a link
 788 will show up. It also means that sometimes is does not create
 789 links where you would like it to create a link. Say you include
 790 the source code of a method using the source item. Your method
 791 uses other methods of the class. You would like to have links
 792 pointing to the documentation of these methods each time you use
 793 one. They will not appear though. Since to ROBODoc stores the
 794 whole name of a method, ie, <TT>someClass::MethodName</TT>. In
 795 the method source you will use just <TT>MethodName()</TT>. </P>
 796
 797
 798
 799  <H2><font color="red">8  </font><A NAME="MAIND">Master Index File</A></H2>
 800
 801 <P>If your project consists of many source files you might want
 802 to create a master index file.</P>
 803
 804 <P>For HTML output this file contains links to the documentation
 805 generated from each of your source files as well as a list of all
 806 "objects" that you documented. All "objects" are listed according
 807 to header type, using the following order: Projects, Classes,
 808 Methods, Stuctures, Functions, Variables, Constants, Generic,
 809 Internal.</P>
 810
 811 <P>For LaTeX output this file is one big document that contains
 812 the documentation generated from all your source files. It also
 813 includes a table of contents and an index section.  This index
 814 lists the page number of the page a function's documentation.
 815 </P>
 816
 817 <P>This index file is generated based on the information found in
 818 your xrefs file. That is the file with the names of all your xref
 819 files. So before you can create the master index file you have to
 820 create all your xref files.</P>
 821
 822 <P>To generate a master index file use:</P>
 823 <PRE>
 824    robodoc &lt;xrefs file&gt; &lt;master index file&gt; INDEX HTML TITLE "Master Index"
 825 </PRE>
 826 <P>or</P>
 827 <PRE>
 828    robodoc &lt;xrefs file&gt; &lt;master index file&gt; INDEX LATEX TITLE "ROBODoc API Documentation"
 829 </PRE>
 830 <P>The master index file can currently only be generated in HTML or LaTeX.</P>
 831
 832 <P>If you use if for LaTeX documentation you need to use the option
 833 <TT>SINGLEDOC</TT> when you generate the documentation from your various
 834 source files.  This ensures that no document preambles are generated.
 835 The master index file contains command that includes all your documentation
 836 files and make it into one single document.</P>
 837
 838
 839 <H3><font color="red">8.1  </font><A NAME="MIEXM">examples</A></H3>
 840
 841 <P>Here are some examples of master index files</P>
 842 <UL>
 843
 844   <LI><A HREF="../Examples/CPP/masterindex.html">Master index for a C++ project</A> to be found in
 845       <TT>Examples/CPP/</TT></LI>
 846
 847   <LI><A HREF="../Source/ROBODoc_mi.html">Master index for ROBODoc</A> to be found in
 848       <TT>Source/</TT>.
 849   </LI>
 850
 851 </UL>
 852
 853
 854
 855  <H2><font color="red">9  </font><A NAME="makefile">Automation with <TT>make</TT></A></H2>
 856
 857 <P>The whole process of creating documentation with ROBODoc is of
 858 course best automated with <TT>make</TT>.
 859 Have a look at the following makefile.</P>
 860
 861 <TABLE><TR><TD><PRE>
 862 SHELL = /bin/sh
 863 .SUFFIXES:
 864
 865 ROBODOC=robodoc
 866 ROBOOPTS=C SORT
 867
 868 # Your source files.
 869 #
 870 SOURCES=analyser.c generator.c items.c util.c \
 871   folds.c headers.c links.c robodoc.c \
 872   analyser.h generator.h items.h util.h \
 873   folds.h headers.h links.h robodoc.h
 874
 875 # The name of your Project
 876 #
 877 PROJECT=robodoc
 878
 879 # The various documentation files, derived from the source files.
 880 # HTML
 881 #
 882 HTMLDOCS=$(SOURCES:=.html)
 883 HTMLXREFS=$(HTMLDOCS:.html=.html.xref)
 884 HTMLXREFSFILE=$(PROJECT)_html.xrefs
 885 # LATEX
 886 #
 887 LATEXDOCS=$(SOURCES:=.tex)
 888 LATEXXREFS=$(LATEXDOCS:.tex=.tex.xref)
 889 LATEXXREFSFILE=$(PROJECT)_tex.xrefs
 890 # ASCII
 891 #
 892 ASCIIDOCS=$(SOURCES:=.txt)
 893 # RTF
 894 #
 895 RTFDOCS=$(SOURCES:=.rtf)
 896 RTFXREFS=$(RTFDOCS:.rtf=.rtf.xref)
 897 RTFXREFSFILE=$(PROJECT)_rtf.xrefs
 898
 899 # Some common targets
 900 xrefall: xrefhtml xreftex xrefrtf
 901 docall: html tex ascii rtf
 902
 903 # Create the xref files for the various formats.
 904 xhtml: $(HTMLXREFSFILE)
 905 xtex: $(LATEXXREFSFILE)
 906 xrtf: $(RTFXREFSFILE)
 907
 908 # Create the documentation files for the various formats.
 909 html: $(HTMLDOCS) $(PROJECT)_mi.html
 910 tex: $(LATEXDOCS) $(PROJECT)_mi.tex
 911 rtf: $(RTFDOCS)
 912 ascii: $(ASCIIDOCS)
 913
 914 # master index file, currently works only for html and latex documentation.
 915 # Note that you can define the title of the document.
 916 $(PROJECT)_mi.html: $(HTMLXREFSFILE)
 917         $(ROBODOC) $&lt; $@ INDEX HTML TITLE "$(PROJECT) Master Index"
 918
 919 $(PROJECT)_mi.tex: $(LATEXXREFSFILE)
 920         $(ROBODOC) $&lt; $@ INDEX LATEX TITLE "$(PROJECT) API Reference"
 921
 922 # create xrefs file (file with the names of all .xref files).
 923 $(HTMLXREFSFILE) : $(HTMLXREFS)
 924         /bin/ls $(HTMLXREFS) &gt; $@
 925 $(LATEXXREFSFILE) : $(LATEXXREFS)
 926         /bin/ls  $(LATEXXREFS) &gt; $@
 927 $(RTFXREFSFILE) : $(RTFXREFS)
 928         /bin/ls  $(RTFXREFS) &gt; $@
 929
 930 # Rule to create an .xref file from a source file for the various formats.
 931 %.html.xref : %
 932         $(ROBODOC) $&lt; $(@:.xref=) $(ROBOOPTS) INTERNAL GENXREF $@
 933 %.tex.xref : %
 934         $(ROBODOC) $&lt; $(@:.xref=) $(ROBOOPTS) INTERNAL GENXREF $@
 935 %.rtf.xref : %
 936         $(ROBODOC) $&lt; $(@:.xref=) $(ROBOOPTS) INTERNAL GENXREF $@
 937
 938 # Rule to create html documentation from a source file.
 939 %.html : %
 940         $(ROBODOC) $&lt; $@ HTML $(ROBOOPTS) XREF $(HTMLXREFSFILE)
 941
 942 # Rule to create latex documentation from a source file.
 943 # We do not include source items, and generate laxtex documents
 944 # than can be included in a master document.
 945 %.tex : %
 946         $(ROBODOC) $&lt; $@ LATEX $(ROBOOPTS) NOSOURCE SINGLEDOC XREF $(LATEXXREFSFILE)
 947
 948 # Rule to create ascii documentation from a source file.
 949 %.txt : %
 950         $(ROBODOC) $&lt; $@ ASCII
 951
 952 # Rule to create rtf documentation from a source file.
 953 %.rtf : %
 954         $(ROBODOC) $&lt; $@ RTF $(ROBOOPTS) XREF $(RTFXREFSFILE)
 955
 956 # Use netscape to view the master index file for our project.
 957 htmlview: html
 958         netscape $(PROJECT)_mi.html
 959
 960 # Use the latex programs to generate a .dvi from the master index file
 961 # for our prokect. View this .dvi file with xdvi
 962 texview:  tex
 963         latex $(PROJECT)_mi
 964         makeindex $(PROJECT)_mi
 965         latex $(PROJECT)_mi
 966         latex $(PROJECT)_mi
 967         xdvi  $(PROJECT)_mi.dvi
 968
 969 # Clean-up the mess we made
 970 #
 971 clean:
 972         rm -f $(HTMLXREFS)
 973         rm -f $(HTMLDOCS)
 974         rm -f $(LATEXXREFS)
 975         rm -f $(LATEXDOCS)
 976         rm -f $(PROJECT)_mi.* *.aux
 977         rm -f $(RTFXREFS)
 978         rm -f $(RTFDOCS)
 979         rm -f $(ASCIIDOCS)
 980         rm -f $(HTMLXREFSFILE)
 981         rm -f $(LATEXXREFSFILE)
 982         rm -f $(RTFXREFSFILE)
 983 </PRE></TD></TR></TABLE>
 984
 985 <P>It includes all the necessary commands to generate and view the documentation for you project. You create documentation in any of the four formats.
 986 For instance to create documentation in html format use:</P>
 987 <TABLE><TR><TD><PRE>
 988   make xhtml
 989   make html
 990 </PRE></TD></TR></TABLE>
 991 <P>To make documentation in LaTeX format use:</P>
 992 <TABLE><TR><TD><PRE>
 993   make xtex
 994   make tex
 995 </PRE></TD></TR></TABLE>
 996 <P>To view your documentation use:</P>
 997 <TABLE><TR><TD><PRE>
 998   make xhtml
 999   make texview
1000 </PRE></TD></TR></TABLE>
1001 <P>or</P>
1002 <TABLE><TR><TD><PRE>
1003   make xtex
1004   make texview
1005 </PRE></TD></TR></TABLE>
1006
1007
1008 <P>To clean up all the documentation files use:</P>
1009 <PRE>
1010   make clean
1011 </PRE>
1012
1013 <P>To use this make file in project set the variable
1014 <TT>SOURCE</TT> to the names of your source files and set the
1015 variable <TT>PROJECT</TT> to the name of your project.</P>
1016
1017 <P>You can find a copy of the above makefile
1018 <TT>Docs/example_makefile</TT>.  This should get you started in
1019 no time.</P>
1020
1021  <H2><font color="red">10  </font><A NAME="MDSO">What to do if You have Sources in Multiple Directories</A></H2>
1022
1023 <P>It is possible to have your sources in multiple
1024 subdirectories. However the generated documentation is expected
1025 to be in one single directory. If not the cross references will
1026 be wrong, at least in the HTML documentation.</P>
1027
1028 <P>Say you have the following directory structure:</P>
1029 <TABLE><TR><TD><PRE>
1030   Project/
1031      Dir1/
1032         program1.c
1033      Dir2/
1034         program2.c
1035 </PRE></TD></TR></TABLE>
1036
1037 <P>You can create the documentation for that as follows (assuming
1038 you are in Project):
1039 </P>
1040 <TABLE><TR><TD><PRE>
1041   robodoc Dir1/prog1.c prog1.c.html HTML GENXREF Dir1/prog1.xref
1042   robodoc Dir2/prog2.c prog2.c.html HTML GENXREF Dir2/prog2.xref
1043   echo "Dir1/prog1.xref" &gt; xreffiles
1044   echo "Dir2/prog2.xref" &gt;&gt; xreffiles
1045   robodoc Dir1/prog1.c prog1.c.html HTML XREF xreffiles
1046   robodoc Dir2/prog2.c prog2.c.html HTML XREF xreffiles
1047   robodoc xreffiles master_index.html INDEX HTML
1048 </PRE></TD></TR></TABLE>
1049 <P>
1050 This generates the following files:
1051 </P>
1052 <TABLE><TR><TD><PRE>
1053    prog1.c.html
1054    prog2.c.html
1055    master_index.html
1056 </PRE></TD></TR></TABLE>
1057
1058
1059 <P>With some version of make (for instance the gnu version) you
1060 can strip the directory part of a filename with $(notdir NAME)
1061 How this can be used is shown in the following example
1062 makefile.  Here we have the sources for robodoc, the <TT>.c</TT> files are
1063 in the directory <TT>Sources/</TT> and <TT>.h</TT> files are in the
1064 directory <TT>Headers/</TT>.</P>
1065
1066 <TABLE><TR><TD><PRE>
1067 SHELL = /bin/sh
1068 .SUFFIXES:
1069
1070 ROBODOC=./robodoc
1071 ROBOOPTS=C SORT
1072
1073 # Your source files.
1074 #
1075 SOURCES=Sources/analyser.c Sources/generator.c Sources/items.c Sources/util.c \
1076   Sources/folds.c Sources/headers.c Sources/links.c Sources/robodoc.c \
1077   Headers/analyser.h Headers/generator.h Headers/items.h Headers/util.h \
1078   Headers/folds.h Headers/headers.h Headers/links.h Headers/robodoc.h
1079
1080 # The name of your Project
1081 #
1082 PROJECT=ROBODoc
1083
1084 # The various documentation files, derived from the source files.
1085 #
1086 HTMLDOCS=$(SOURCES:=.html)
1087 HTMLXREFS=$(HTMLDOCS:.html=.html.xref)
1088 HTMLXREFSFILE=$(PROJECT)_html.xrefs
1089
1090 # Create the xref files for the various formats.
1091 xhtml: $(HTMLXREFSFILE)
1092
1093 # Create the documentation
1094 html: $(HTMLDOCS) $(PROJECT)_mi.html
1095
1096 # Create master index file.
1097 $(PROJECT)_mi.html: $(HTMLXREFSFILE)
1098         $(ROBODOC) $&lt; $@ INDEX HTML TITLE "$(PROJECT) Master Index"
1099
1100 # Create the file with the names of all xref files.
1101 $(HTMLXREFSFILE) : $(HTMLXREFS)
1102         /bin/ls $(HTMLXREFS) &gt; $@
1103
1104 # Rule to create an .xref file from a source file
1105 %.html.xref : %
1106         $(ROBODOC) $&lt; $(notdir $(@:.xref=)) $(ROBOOPTS) INTERNAL GENXREF $@
1107
1108 # Rule to create html documentation from a source file.
1109 %.html : %
1110         $(ROBODOC) $&lt; $(notdir ${@}) HTML $(ROBOOPTS) XREF $(HTMLXREFSFILE)
1111 </PRE></TD></TR></TABLE>
1112
1113
1114
1115  <H2><font color="red">11  </font><A NAME="RDF">The ROBODoc Defaults File</A></H2>
1116
1117 <P>The robodoc.default file can be used to change the appearance
1118 of the documentation. For each item type you can define how the
1119 corresponding text should be rendered.  Each line in the default
1120 file consists of two parts, the item type and the item
1121 attributes. For instance</P>
1122
1123 <PRE>
1124 AUTHOR                    LARGE ITALICS BOLD UNDERLINE
1125 </PRE>
1126
1127 <P>Specifies that the AUTHOR item has the attributes LARGE,
1128 ITALICS, BOLD, and UNDERLINE.  The effect of each attribute is
1129 listed in the following table.</P>
1130
1131 <TABLE>
1132 <TR><TD>Item Attributes</TD>
1133     <TD>Effect in HTML</TD>
1134 </TR>
1135 <TR><TD>LARGE</TD>
1136     <TD>&lt;FONT SIZE=5&gt;,&lt;/FONT&gt;</TD>
1137 </TR>
1138 <TR><TD>SMALL</TD>
1139     <TD>&lt;FONT SIZE=-1&gt;,&lt;/FONT&gt;</TD>
1140 </TR>
1141 <TR><TD>ITALICS</TD>
1142     <TD>&lt;I&gt;,&lt;/I&gt;</TD>
1143 </TR>
1144 <TR><TD>BOLD</TD>
1145     <TD>&lt;B&gt;,&lt;/B&gt;</TD>
1146 </TR>
1147 <TR><TD>UNDERLINE</TD>
1148     <TD>&lt;U&gt;,&lt;/U&gt;</TD>
1149 </TR>
1150 <TR><TD>HIGHLIGHT</TD>
1151     <TD>&lt;EM&gt;,&lt;/EM&gt;</TD>
1152 </TR>
1153 </TABLE>
1154
1155
1156  <H2><font color="red">12  </font><A NAME="UOB">ROBODoc Command Line Options</A></H2>
1157
1158 <P>When using ROBODoc you should provide at least two
1159 parameters</P>
1160
1161 <PRE>
1162   robodoc &lt;source file&gt; &lt;documentation file&gt; [options]
1163 </PRE>
1164
1165 <P>Here sourcefile is the file with the program source from which
1166 the documentation is to be extracted. The documentation file is
1167 the file that will contain the extracted documentation.  </P>
1168
1169 <P>In case you are creating a master index file you have to
1170 specify three parameters</P>
1171 <PRE>
1172   robodoc &lt;xrefs file&gt; &lt;master index file&gt; INDEX [options]
1173 </PRE>
1174
1175
1176 <P>In addition to this you can specify one or more of the
1177 following options:</P>
1178
1179 <TABLE >
1180   <TR><TD><TT>ASCII</TT></TD>
1181       <TD>Generate documentation in ASCII format (default)</TD>
1182   </TR>
1183   <TR><TD><TT>GUIDE</TT></TD>
1184       <TD>Generate documentation in AmigaGuide format.</TD>
1185   </TR>
1186   <TR><TD><TT>HTML</TT></TD>
1187       <TD>Generate documentation in HTML format.</TD>
1188   </TR>
1189   <TR><TD><TT>LATEX</TT></TD>
1190       <TD>Generate documentation in LaTeX format. (Experimental)</TD>
1191   </TR>
1192   <TR><TD><TT>RTF</TT></TD>
1193       <TD>Generate documentation in RTF format.</TD>
1194   </TR>
1195   <TR><TD><TT>C</TT></TD>
1196       <TD>Use ANSI C grammar in source items (test, HTML only)</TD>
1197   </TR>
1198   <TR><TD><TT>FOLD</TT></TD>
1199       <TD>Enable folding. (Experimental)</TD>
1200   </TR>
1201   <TR><TD><TT>GENXREF &lt;xref file&gt;</TT></TD>
1202       <TD>Generate a xref file, which can be used to create
1203          <A HREF="#CLD">cross links</A> between documents.</TD>
1204   </TR>
1205   <TR><TD><TT>XREF &lt;xrefs file&gt;</TT></TD>
1206       <TD>Use a set of xref files to create references (links) to other
1207       documents or within the document. <TT>&lt;xrefs file&gt;</TT>
1208       is a file with xref file names.</TD>
1209   </TR>
1210   <TR><TD><TT>INDEX</TT></TD>
1211      <TD>Create a <A HREF="#MAIND">master index file</A>.</TD>
1212   </TR>
1213   <TR><TD><TT>INTERNAL</TT></TD>
1214      <TD>Also include headers that are marked internal.</TD>
1215   </TR>
1216   <TR><TD><TT>INTERNALONLY</TT></TD>
1217       <TD>Only extract the headers marked internal.</TD>
1218   </TR>
1219   <TR><TD><TT>NOSOURCE</TT></TD>
1220       <TD>Do not include the source items in the documentation.</TD>
1221   </TR>
1222   <TR><TD><TT>SORT</TT></TD>
1223       <TD>Sort the headers alphabetically.</TD>
1224   </TR>
1225   <TR><TD><TT>SINGLEDOC</TT></TD>
1226       <TD>Do not create a document header and footer when creating
1227           documentation in LaTeX format.  This allows you to include
1228           the generated documents into big document or
1229           <A HREF="#MAIND">master index file</A>.</TD>
1230   </TR>
1231   <TR><TD><TT>TITLE &lt;title&gt;</TT></TD>
1232       <TD>Sets the title that is used for the
1233          <A HREF="#MAIND">master index file</A>.</TD>
1234   </TR>
1235   <TR><TD><TT>TOC</TT></TD>
1236       <TD>Generate a table of contents.  It is only useful when you select
1237       ASCII as output mode.  With all other output modes the
1238       table of contents is generated anyway.</TD>
1239   </TR>
1240   <TR><TD><TT>TABSIZE &lt;n&gt;</TT></TD>
1241       <TD>Convert each tab into <TT>n</TT> spaces.</TD>
1242   </TR>
1243   <TR><TD><TT>-v</TT></TD>
1244       <TD>Verbose option, ROBODoc will tell you what it is doing.</TD>
1245   </TR>
1246 </TABLE>
1247
1248 <P>If you wonder why all the odd ALL CAPS flags are used instead
1249 of for instance "-x"; this was how it was done on the Amiga.</P>
1250
1251 <P>The following abbreviations are also allowed:</P>
1252 <TABLE >
1253 <TR><TD><TT>-s </TT></TD><TD><TT>SORT</TT></TD></TR>
1254 <TR><TD><TT>-t </TT></TD><TD><TT>TOC</TT></TD></TR>
1255 <TR><TD><TT>-x </TT></TD><TD><TT>XREF</TT></TD></TR>
1256 <TR><TD><TT>-g </TT></TD><TD><TT>GENXREF</TT></TD></TR>
1257 <TR><TD><TT>-i </TT></TD><TD><TT>INTERNAL</TT></TD></TR>
1258 <TR><TD><TT>-io</TT></TD><TD><TT>INTERNALONLY</TT></TD></TR>
1259 <TR><TD><TT>-ts</TT></TD><TD><TT>TABSIZE</TT></TD></TR>
1260 </TABLE>
1261
1262
1263  <H2><font color="red">13  </font><A NAME="ADV">Adding New Languages</A></H2>
1264
1265 <P>To add a new programming language to ROBODoc you have to edit
1266 <TT>headers.c</TT>.  Here you find three variables:
1267 <TT>header_markers</TT>, <TT>remark_markers</TT>, and
1268 <TT>end_markers</TT>.  There are all arrays, and you have to add
1269 an new entry to each of these three arrays.</P>
1270
1271 <P>Say your programming language uses the following type of remarks:</P>
1272 <PRE>
1273    $%% This is a remark with some text
1274        and some more and some more  %%$
1275 </PRE>
1276
1277 <P>That is is starts with three spaces and then <TT>$%%</TT>, and
1278 has to end with <TT>%%$</TT>. Then you would add to <TT>header_markers</TT>
1279 </P>
1280 <PRE>
1281    "   $%%****",
1282 </PRE>
1283 <P>To <TT>remark_markers</TT> you would add</P>
1284 <PRE>
1285    "   *",
1286 </PRE>
1287 <P>And to <TT>end_markers</TT> you would add</P>
1288 <PRE>
1289    "   $%%***",
1290 </PRE>
1291 <P>You can then use the following kind of headers in your program:</P>
1292 <PRE>
1293    $%%****f* Test/afunction *****
1294    * NAME
1295    *   afunction
1296    * FUNCTION
1297    *   A test.
1298    * SOURCE
1299    *%%$
1300      afunction(test,test) [
1301        print hello world ;
1302      ]
1303    $%%***%%$
1304 </PRE>
1305
1306
1307
1308
1309
1310  <H2><font color="red">14  </font><A NAME="SAB">Suggestions and Bugs</A></H2>
1311
1312 <P>If you find any bugs, catch them, put them in a jar, and send
1313 them to:</P>
1314 <ADDRESS>fslothouber@acm.org</ADDRESS>
1315 <P>Suggestions are also welcome at this address.  Flames can be
1316 directed to the sun.</P>
1317
1318 </BODY>
1319 </HTML>
1320