util/robodoc/Docs/robodoc.m4

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