--- /dev/null
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"><HTML>
+<HEAD><LINK rel=stylesheet href="main.css"><TITLE>ROBODoc Manual</TITLE></HEAD>
+<BODY>
+<H1>ROBODoc 3.2.3 Manual</H1>
+
+<P><STRONG>Updated July 2000</STRONG></P>
+
+<P>ROBODoc is a documentation tool for C, C++, Java, Assembler, Basic,
+Fortran, LaTeX, Postscript, Tcl/Tk, LISP, Forth, Perl, Shell
+Scripts, Occam, COBOL, HTML and many other languages. Additional
+languages can be supported by a few modifications to the source
+code.</P>
+
+<P>Copyright (C) 1994-2000 Frans Slothouber and Jacco van Weert.</P>
+
+<P>This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License as
+published by the Free Software Foundation; either version 2 of
+the License, or (at your option) any later version.</P>
+
+<P>This program is distributed in the hope that it will be
+useful, but WITHOUT ANY WARRANTY; without even the implied
+warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+See the GNU General Public License for more details.</P>
+
+<P>You should have received a copy of the GNU General Public
+License along with this program; if not, write to the Free
+Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA</P>
+
+
+
+ <H2><font color="red">1 </font><A NAME="creds">Credits</A></H2>
+
+<UL>
+
+ <LI>Original program and idea: Jacco van Weert</LI>
+
+ <LI>Versions 2.0 and up: Frans Slothouber, Petteri Kettunen,
+ Bernd Koesling, Anthon Pang, Thomas Aglassinger,
+ and Stefan Kost, Guillaume Etorre, Simo Muinonen,
+ Petter Reinholdtsen.
+ </LI>
+
+ <LI>Maintainer: Frans Slothouber (fslothouber@acm.org),
+ The Netherlands.</LI>
+
+</UL>
+
+
+ <H2><font color="red">2 </font><A NAME="toc">Table of Contents</A></H2>
+
+<STRONG><FONT COLOR="red">01</FONT>......... <A HREF="#creds">Credits</A></STRONG><BR>
+<STRONG><FONT COLOR="red">02</FONT>......... <A HREF="#toc">Table of Contents</A></STRONG><BR>
+<STRONG><FONT COLOR="red">03</FONT>......... <A HREF="#INTRO">Introduction</A></STRONG><BR>
+<STRONG><FONT COLOR="red">04</FONT>......... <A HREF="#HSR">Hardware and software requirements</A></STRONG><BR>
+<STRONG><FONT COLOR="red">05</FONT>......... <A HREF="#LMT">Goals and Limitations</A></STRONG><BR>
+<STRONG><FONT COLOR="red">06</FONT>......... <A HREF="#HFCWR">How to Format Your Code for use with ROBODoc</A></STRONG><BR>
+<STRONG><font color="red">06.01</font>.......... <A HREF="#hname">Header Names</A></STRONG><BR>
+<STRONG><font color="red">06.02</font>.......... <A HREF="#htypes">Header Types</A></STRONG><BR>
+<STRONG><font color="red">06.03</font>.......... <A HREF="#bmar">Begin Marker</A></STRONG><BR>
+<STRONG><font color="red">06.04</font>.......... <A HREF="#rmarker">Remark Marker</A></STRONG><BR>
+<STRONG><font color="red">06.05</font>.......... <A HREF="#emar">End Marker</A></STRONG><BR>
+<STRONG><font color="red">06.06</font>.......... <A HREF="#hitem">Header Items</A></STRONG><BR>
+<STRONG><font color="red">06.07</font>.......... <A HREF="#inlimits">Item Name Limitations</A></STRONG><BR>
+<STRONG><font color="red">06.08</font>.......... <A HREF="#SI">Source Item</A></STRONG><BR>
+<STRONG><FONT COLOR="red">07</FONT>......... <A HREF="#CLD">Creating Cross Links</A></STRONG><BR>
+<STRONG><font color="red">07.01</font>.......... <A HREF="#limits">Limitations</A></STRONG><BR>
+<STRONG><FONT COLOR="red">08</FONT>......... <A HREF="#MAIND">Master Index File</A></STRONG><BR>
+<STRONG><font color="red">08.01</font>.......... <A HREF="#MIEXM">examples</A></STRONG><BR>
+<STRONG><FONT COLOR="red">09</FONT>......... <A HREF="#makefile">Automation with <TT>make</TT></A></STRONG><BR>
+<STRONG><FONT COLOR="red">10</FONT>......... <A HREF="#MDSO">What to do if You have Sources in Multiple Directories</A></STRONG><BR>
+<STRONG><FONT COLOR="red">11</FONT>......... <A HREF="#RDF">The ROBODoc Defaults File</A></STRONG><BR>
+<STRONG><FONT COLOR="red">12</FONT>......... <A HREF="#UOB">ROBODoc Command Line Options</A></STRONG><BR>
+<STRONG><FONT COLOR="red">13</FONT>......... <A HREF="#ADV">Adding New Languages</A></STRONG><BR>
+<STRONG><FONT COLOR="red">14</FONT>......... <A HREF="#SAB">Suggestions and Bugs</A></STRONG><BR>
+
+
+
+
+ <H2><font color="red">3 </font><A NAME="INTRO">Introduction</A></H2>
+
+<P>ROBODoc is based on the AutoDocs program written some time ago
+by Commodore. The idea is to include for every function a
+standard header containing all sorts of information about that
+procedure/function. An AutoDocs program extracts these headers
+from the source file and puts them in an autodocs file. This
+allows you to include the program documentation in the source
+code and makes it unnecessary to maintain two documents.</P>
+
+
+<P>ROBODoc is such a program, however ROBODoc has several
+additions. For one it can generate the documentation in
+different formats, ASCII, HTML, RTF, LaTeX, and AmigaGuide.
+Another feature is that it automatically creates links within the
+document, and to other documents. It is also possible to include
+parts of the source in you documentation, complete with links.
+For instance it is possible to include the complete source code
+of a function, and have the function names in the source point to
+their documentation. Besides documenting functions, you can also
+document classes, methods, structures, variables, and
+constants.</P>
+
+
+<P>If you never have used AutoDoc or ROBODoc before you might
+take a look at the example in the <TT>Source/</TT>. Run the
+command:</P>
+
+<PRE>
+ make xhtml
+ make example
+</PRE>
+
+
+<P>This creates the ROBODoc
+<A HREF="../Source/ROBODoc_mi.html">documentation</A> for the
+ROBODoc program itself and then starts netscape to view the
+documentation. Also have a look at the source files, they
+illustrates the use of headers.</P>
+
+<P>ROBODoc can generate documentation in five different
+formats:</P>
+
+<UL>
+ <LI>HTML format complete with hyperlinks and mark-ups.</LI>
+
+ <LI>LaTeX, based on D. Knuth excellent typesetting system.</LI>
+
+ <LI>Plain ASCII text file, this file is very close to what the
+ original AutoDocs program would generate.</LI>
+
+ <LI>RTF, Rich Text Format, mostly used on Windows machines
+ before WWW revolution.</LI>
+
+ <LI>AmigaGuide format, it is the Amiga computer's equivalent
+ HTML. The AmigaGuide program is necessary to view the
+ resulting autodocs-file. (This was the preferred format when the
+ program was written in 1994.)</LI>
+
+</UL>
+
+
+ <H2><font color="red">4 </font><A NAME="HSR">Hardware and software requirements</A></H2>
+
+<P>ROBODoc was developed in 1994 on a standard Amiga 1200, a
+system with a 20MHz 68020 processor and 2 Mbyte of RAM. It should
+therefore be no problem to run it on any of the currently
+available systems :) The complete source code consists of a
+series of file that can be found in the <TT>Source</TT>
+directory. It is written according (hopefully) to the ANSI C
+standard and uses no special functions, so it should run on every
+system with an ANSI C-compiler.</P>
+
+
+ <H2><font color="red">5 </font><A NAME="LMT">Goals and Limitations</A></H2>
+
+<P>ROBODoc is intended for small to medium sized projects
+that have a relatively flat structure and especially projects
+that use a mix of different programming languages.</P>
+
+<P>
+ROBODoc was designed to be easy to use and to work with a lot of
+different programming languages. It has no knowledge of the
+syntax of a programming languages. It just some knowledge about
+how remarks start and end in some programming languages. This
+means that you sometimes have to do a little more work compared
+to other tools that have detailed knowledge of the syntax of a
+particular language. They can use that knowledge to figure out
+some of the information automatically. This usually also means
+that they work only with one or two languages.
+</P>
+
+<P>ROBODoc operates on one file at a time. It has no mechanism to
+process whole sets of source files. Makefiles should be used for
+this. How to do this is explained in this document with various
+example makefiles. Have a look at them.
+</P>
+
+<P>ROBODoc can work with projects where the source code is located
+in different subdirectories. However the generated documentation is
+expected to go into one single directory.</P>
+
+
+ <H2><font color="red">6 </font><A NAME="HFCWR">How to Format Your Code for use with ROBODoc</A></H2>
+
+<P>ROBODoc allows you to mix the program documentation with the
+source code. It does require though that this documentation has
+a particular layout so ROBODoc can recognize it. The following
+header was taken from the original ROBODoc program (many versions
+back).</P>
+
+<TABLE>
+<TR>
+<TD>
+<PRE>
+ <FONT COLOR="red">------------------------------- Header Name</FONT>
+ <FONT COLOR="red">/ \</FONT>
+ /****f* financial.library/StealMoney <FONT COLOR="red"><---- Begin Marker</FONT>
+ * <FONT COLOR="red">^------- Header Type</FONT>
+ *
+ * <FONT COLOR="red"><---- Remark Marker</FONT>
+ * NAME
+ * StealMoney -- Steal money from the Federal Reserve Bank. (V77)
+ * SYNOPSIS <FONT COLOR="red"><---- Item Name</FONT>
+ * error = StealMoney( userName,amount,destAccount,falseTrail )
+ * D0,Z D0 D1.W A0 [A1]
+ *
+ * BYTE StealMoney
+ * ( STRPTR,UWORD,struct AccountSpec *,struct falseTrail *);
+ * FUNCTION
+ * Transfer money from the Federal Reserve Bank into the
+ * specified interest-earning checking account. No records of
+ * the transaction will be retained.
+ * INPUTS
+ * userName - name to make the transaction under. Popular
+ * favorites include "Ronald Reagan" and
+ * "Mohamar Quadaffi".
+ * amount - Number of dollars to transfer (in thousands).
+ * destAccount - A filled-in AccountSpec structure detailing the
+ * destination account (see financial/accounts.h).
+ * If NULL, a second Great Depression will be
+ * triggered.
+ * falseTrail - If the DA_FALSETRAIL bit is set in the
+ * destAccount, a falseTrail structure must be
+ * provided.
+ * RESULT
+ * error - zero for success, else an error code is returned
+ * (see financial/errors.h). The Z condition code
+ * is guaranteed.
+ * EXAMPLE
+ * Federal regulations prohibit a demonstration of this function.
+ * NOTES
+ * Do not run on Tuesdays!
+ * BUGS
+ * Before V88, this function would occasionally print the
+ * address and home phone number of the caller on local police
+ * 976 terminals. We are confident that this problem has been
+ * resolved.
+ * SEE ALSO
+ * CreateAccountSpec(),security.device/SCMD_DESTROY_EVIDENCE,
+ * financial/misc.h
+ *
+ ****** <FONT COLOR="red"><---- End Marker</FONT>
+ *
+ * You can use this space for remarks that should not be included
+ * in the documentation.
+ *
+ */
+</PRE>
+</TD>
+</TR>
+</TABLE>
+
+<P>You would place this headers in front of functions, classes,
+methods, structure definitions, or any of the major components in
+your program. The header itself contains a number of items that
+provide structured information about the component. </P>
+
+<P>There are a number of special markers in a header (indicated
+in red above). There are two special markers that mark the begin
+and end of a header. Each line in a header should start with a
+remark marker. The starts of each item is marked by an Item Name
+(in all capitals).</P>
+
+
+<H3><font color="red">6.1 </font><A NAME="hname">Header Names</A></H3>
+
+<P>ROBODoc makes some assumptions about the structure a project.
+It assumes that a project consists of a number of modules, and
+that each module consists of a number of components. These
+components can be anything that you care to document; functions,
+variables, structures, classes, methods etc.</P>
+
+<P> Projects, modules, and components all have names. The names
+allow ROBODoc to structure the documentation and create
+cross-links. Names are defined in the header name. It is either
+of the form <TT> <project name>/<module name></TT>
+for a module header, or of the form <TT><module
+name>/<component name></TT> for all other headers.</P>
+
+<H3><font color="red">6.2 </font><A NAME="htypes">Header Types</A></H3>
+
+<P>You can provide ROBODoc with some additional information
+by specifying the header type. The header type tells ROBODoc
+what kind of component you are documenting. This information
+allows ROBODoc to create more useful index tables.</P>
+
+<P>The type is identified by a single character, as listed in the
+following table</P>
+
+<TABLE>
+<TR><TD>h</TD><TD>Header for a module in a project.</TD></TR>
+<TR><TD>f</TD><TD>Header for a function.</TD></TR>
+<TR><TD>s</TD><TD>Header for a structure.</TD></TR>
+<TR><TD>c</TD><TD>Header for a class.</TD></TR>
+<TR><TD>m</TD><TD>Header for a method.</TD></TR>
+<TR><TD>v</TD><TD>Header for a variable.</TD></TR>
+<TR><TD>d</TD><TD>Header for a constant
+(from <STRONG>d</STRONG>efine).</TD></TR>
+<TR><TD>*</TD><TD>Generic header for every thing else.</TD></TR>
+<TR><TD>i</TD><TD>Internal header.</TD></TR>
+</TABLE>
+
+<P>Internal headers are special. They can be used to hide certain
+headers. They are only extracted if requested. You could use to
+document internal functions that you do now want clients to
+see.</P>
+
+
+<H3><font color="red">6.3 </font><A NAME="bmar">Begin Marker</A></H3>
+
+<P>The beginning of a header is marked with a special marker.
+The above header is intended for a program in C. In other
+programming languages the marker looks slightly different, since
+each language has its own convention for starting remarks.
+ROBODoc recognizes the following begin markers:</P>
+
+<TABLE >
+<TR><TD><TT>"/****"</TT>
+ <TD>C, C++</TD>
+</TR>
+<TR><TD><TT>"//****"</TT></TD>
+ <TD>C++</TD>
+</TR>
+<TR><TD><TT>";****"</TT></TD>
+ <TD>Assembler</TD>
+</TR>
+<TR><TD><TT>"****"</TT></TD>
+ <TD>Assembler</TD>
+</TR>
+<TR><TD><TT>"{****"</TT></TD>
+ <TD>Pascal</TD>
+</TR>
+<TR><TD><TT>"REM ****"</TT></TD>
+ <TD>Basic (Rem, rem, or even rEM also works)</TD>
+</TR>
+<TR><TD><TT>"C ****"</TT></TD>
+ <TD>Fortran (c **** also works)</TD>
+</TR>
+<TR><TD><TT>"%****"</TT></TD>
+ <TD>LaTeX, TeX, Postscript.</TD>
+</TR>
+<TR><TD><TT>"#****"</TT></TD>
+ <TD>Tcl/Tk, Perl, makefiles, gnuplot etc.</TD>
+</TR>
+<TR><TD><TT>"(****"</TT></TD>
+ <TD>Pascal, Modula-2, LISP</TD>
+</TR>
+<TR><TD><TT>"--****"</TT></TD>
+ <TD>Occam</TD>
+</TR>
+<TR><TD><TT>"<!--****"</TT></TD>
+ <TD>HTML</TD>
+</TR>
+<TR><TD><TT>"<!---****"</TT></TD>
+ <TD>HTML</TD>
+</TR>
+<TR><TD><TT>"|****"</TT></TD>
+ <TD>GNU Assembler</TD>
+</TR>
+<TR><TD><TT>"!!****"</TT></TD>
+ <TD>Fortran 90</TD>
+</TR>
+</TABLE>
+
+<P>After these initial four asterisks, there is the character to
+identify the kind of header, then another asterisks, and then
+header name. After this you can specify a version number
+surrounded by "[]". The version number is stored but not used for
+anything at the moment. All characters after that are
+ignored.</P>
+
+<P>This might sound terribly complicated, it is not. Here are
+some examples:</P>
+
+<P>A header for a module called analyser in a project called ChessMaster
+for C, is has version number 1.0</P>
+<PRE>
+ /****h* ChessMaster/analyser [1.0] *
+</PRE>
+
+<P>In Assembler, a function header, for the function init() in the
+ module finance.library:</P>
+<PRE>
+ ****f* finance.library/init *
+</PRE>
+
+<P>In C++, a class header for class Puppet, for the module puppetmaster,
+version v2.12</P>
+<PRE>
+ /****c* puppetMaster/Puppet [v2.12] ******
+</PRE>
+
+<P>For the same class a method called Puppet::Talk</P>
+<PRE>
+ /****m* puppetMaster/Puppet::Talk [v2.12] ******
+</PRE>
+
+<P>A project header, in Fortran</P>
+<PRE>
+ C ****h* ChessMaster/analyser C
+</PRE>
+
+<P>In Basic</P>
+<PRE>
+ REM ****h* ChessMaster/analyser
+</PRE>
+
+
+
+<H3><font color="red">6.4 </font><A NAME="rmarker">Remark Marker</A></H3>
+
+<P>Each line in the body of a header should start with a remark
+marker. This marker is stripped from the line and the remaining
+part is used to generated the documentation. The following
+markers are recognized by ROBODoc.</P>
+
+<TABLE >
+<TR><TD><TT>"*"</TT></TD>
+ <TD>C, C++, Pascal, Modula-2</TD>
+</TR>
+<TR><TD><TT>"//"</TT></TD>
+ <TD>C++</TD>
+</TR>
+<TR><TD><TT>" *"</TT></TD>
+ <TD>C, C++, M68K assembler, Pascal, Modula-2, HTML</TD>
+</TR>
+<TR><TD><TT>";*"</TT></TD>
+ <TD>M68K assembler</TD>
+</TR>
+<TR><TD><TT>";"</TT></TD>
+ <TD>M68K assembler</TD>
+</TR>
+<TR><TD><TT>"C "</TT></TD>
+ <TD>Fortran</TD>
+</TR>
+<TR><TD><TT>"REM "</TT></TD>
+ <TD>BASIC</TD>
+</TR>
+<TR><TD><TT>"%"</TT></TD>
+ <TD>LaTeX, TeX, Postscript</TD>
+</TR>
+<TR><TD><TT>"#"</TT></TD>
+ <TD>Tcl/Tk, shell scripts, makefiles</TD>
+</TR>
+<TR><TD><TT>" *"</TT></TD>
+ <TD>COBOL</TD>
+</TR>
+<TR><TD><TT>"--"</TT></TD>
+ <TD>Occam</TD>
+</TR>
+<TR><TD><TT>"|"</TT></TD>
+ <TD>GNU Assembler</TD>
+</TR>
+<TR><TD><TT>"!!"</TT></TD>
+ <TD>Fortan 90</TD>
+</TR>
+</TABLE>
+
+
+
+
+<H3><font color="red">6.5 </font><A NAME="emar">End Marker</A></H3>
+
+<P>A header ends with an end marker. An end marker is a remark
+marker followed by three asterisks. ROBODoc recognizes following
+strings as end markers:</P>
+
+<TABLE >
+<TR><TD><TT>"/***"</TT></TD>
+ <TD> C, C++ </TD></TR>
+<TR><TD><TT>"//***"</TT></TD>
+ <TD> C++ </TD></TR>
+<TR><TD><TT>" ****"</TT></TD>
+ <TD> C, C++, Pascal, Modula-2 </TD></TR>
+<TR><TD><TT>"{***"</TT></TD>
+ <TD> Pascal </TD></TR>
+<TR><TD><TT>"(***"</TT></TD>
+ <TD> Pascal, Modula-2, B52 LISP</TD></TR>
+<TR><TD><TT>";***"</TT></TD>
+ <TD> M68K assembler </TD></TR>
+<TR><TD><TT>"****"</TT></TD>
+ <TD> M68K assembler </TD></TR>
+<TR><TD><TT>"C ***"</TT></TD>
+ <TD> Fortran </TD></TR>
+<TR><TD><TT>"REM ***"</TT></TD>
+ <TD> BASIC </TD></TR>
+<TR><TD><TT>"%***"</TT></TD>
+ <TD> LaTeX, TeX, Postscript </TD></TR>
+<TR><TD><TT>"#***"</TT></TD>
+ <TD> Tcl/Tk, Perl, Makefiles, Shell scripts </TD></TR>
+<TR><TD><TT>" ****"</TT></TD>
+ <TD> COBOL </TD></TR>
+<TR><TD><TT>"--***"</TT></TD>
+ <TD> Occam </TD></TR>
+<TR><TD><TT>"<!--***"</TT></TD>
+ <TD> HTML </TD></TR>
+<TR><TD><TT>"<!---***"</TT></TD>
+ <TD> HTML </TD></TR>
+<TR><TD><TT>"|***"</TT></TD>
+ <TD>GNU Assembler</TD></TR>
+<TR><TD><TT>"!!***"</TT></TD>
+ <TD>Fortan 90</TD></TR>
+</TABLE>
+
+
+
+
+<H3><font color="red">6.6 </font><A NAME="hitem">Header Items</A></H3>
+
+<P>When ROBODoc has found a header it will try to identify the
+items in this header. It does this by looking for the item name. The following
+item names are currently supported:</P>
+
+<TABLE >
+<TR><TD> NAME </TD>
+ <TD> Item name plus a short description. </TD>
+<TR><TD> COPYRIGHT </TD>
+ <TD> Who own the copyright : "(c) <year>-<year> by
+ <company/person>" </TD>
+<TR><TD> SYNOPSIS, USAGE </TD>
+ <TD> How to use it. </TD>
+<TR><TD> FUNCTION, DESCRIPTION, PURPOSE </TD>
+ <TD> What does it do. </TD>
+<TR><TD> AUTHOR </TD>
+ <TD>Who wrote it. </TD>
+<TR><TD> CREATION DATE </TD>
+ <TD> When did the work start. </TD>
+<TR><TD> MODIFICATION HISTORY, HISTORY </TD>
+ <TD> Who has done which changes and when. </TD>
+<TR><TD> INPUTS, ARGUMENTS, OPTIONS, PARAMETERS, SWITCHES </TD>
+ <TD> What can we feed into it. </TD>
+<TR><TD> OUTPUT, SIDE EFFECTS </TD>
+ <TD> What output is made. </TD>
+<TR><TD> RESULT, RETURN VALUE </TD>
+ <TD> What do we get returned. </TD>
+<TR><TD> EXAMPLE </TD>
+ <TD> A clear example of the items use. </TD>
+<TR><TD> NOTES </TD>
+ <TD> Any annotations </TD>
+<TR><TD> DIAGNOSTICS </TD>
+ <TD>Diagnostical output </TD>
+<TR><TD> WARNINGS, ERRORS </TD>
+ <TD> Warning & error-messages. </TD>
+<TR><TD> BUGS </TD>
+ <TD> Known bugs. </TD>
+<TR><TD> TODO, IDEAS </TD>
+ <TD> What to implement next & ideas. </TD>
+<TR><TD> PORTABILITY </TD>
+ <TD> Where does it come from, where will it work. </TD>
+<TR><TD> SEE ALSO </TD>
+ <TD> References to other functions, man pages, other documentation. </TD>
+<TR><TD> METHODS, NEW METHODS </TD>
+ <TD> OOP methods. </TD>
+<TR><TD> ATTRIBUTES, NEW ATTRIBUTES </TD>
+ <TD> OOP attributes </TD>
+<TR><TD> TAGS </TD>
+ <TD> Tag-item description. </TD>
+<TR><TD> COMMANDS </TD>
+ <TD> Command description. </TD>
+<TR><TD> DERIVED FROM </TD>
+ <TD> OOP super class. </TD>
+<TR><TD> DERIVED BY </TD>
+ <TD> OOP sub class. </TD>
+<TR><TD> USES, CHILDREN </TD>
+ <TD> What modules are used by this one. </TD>
+<TR><TD> USED BY, PARENTS </TD>
+ <TD> Which modules do use this one. </TD>
+<TR><TD> SOURCE </TD>
+ <TD> Source code inclusion. </TD>
+</TABLE>
+
+<P>ROBODoc does this so that it can format each item with a
+different style (colour, font, etc.) if the user want it. These
+can be specified in the robodoc.defaults file, see the next
+section more information.</P>
+
+
+<H3><font color="red">6.7 </font><A NAME="inlimits">Item Name Limitations</A></H3>
+
+<P>If you happen to have a function which name is in all uppercase,
+this sometimes conflicts with where ROBODoc thinks an item name
+starts and where the item body starts.
+Bernhard Roessmann suggest the following workaround:
+Example header producing this error:</P>
+<PRE>
+/***** basic.c/RETURN
+* NAME
+* RETURN : Return from subroutine
+* SYNOPSIS
+* RETURN
+* FUNCTION
+* Return from subroutine
+******/
+</PRE>
+<P>Here the item name "FUNCTION" will be interpreted as ordinary text,
+not as an item name. Workaround: Add an empty line:</P>
+<PRE>
+/***** basic.c/RETURN
+* NAME
+* RETURN : Return from subroutine
+* SYNOPSIS
+* RETURN
+*
+* FUNCTION
+* Return from subroutine
+******/
+</PRE>
+
+
+
+<H3><font color="red">6.8 </font><A NAME="SI">Source Item</A></H3>
+
+<P>The source item allows you to include part of the source in
+the documentation as is demonstrated by the following
+example.</P>
+
+<TABLE><TR><TD><PRE>
+/****f* Robodoc/RB_Panic [2.0d]
+ * NAME
+ * RB_Panic -- Shout panic, free resources, and shut down.
+ * SYNOPSIS
+ * RB_Panic (cause, add_info)
+ * RB_Panic (char *, char *)
+ * FUNCTION
+ * Prints an error message.
+ * Frees all resources used by robodoc.
+ * Terminates program.
+ * INPUTS
+ * cause - pointer to a string which describes the
+ * cause of the error.
+ * add_info - pointer to a string with additional information.
+ * SEE ALSO
+ * RB_Close_The_Shop ()
+ * SOURCE
+ */
+
+ void RB_Panic (char *cause, char *add_info)
+ {
+ printf ("Robodoc: Error, %s\n",cause) ;
+ printf (" %s\n", add_info) ;
+ printf ("Robodoc: Panic Fatal error, closing down...\n") ;
+ RB_Close_The_Shop () ; /* Free All Resources */
+ exit(100) ;
+ }
+
+/*******/
+
+</PRE></TD></TABLE>
+
+<P>This would create the following documentation</P>
+
+<TABLE><TR><TD>
+<FONT SIZE="+1">NAME</FONT>
+<PRE><EM> <B>RB_Panic</B> -- Shout panic, free resources, and shut down.
+</EM></PRE><FONT SIZE="+1">SYNOPSIS</FONT>
+<PRE> <B>RB_Panic</B> (cause, add_info)
+ <B>RB_Panic</B> (char *, char *)
+</PRE><FONT SIZE="+1">FUNCTION</FONT>
+<PRE> Prints an error message.
+ Frees all resources used by robodoc.
+ Terminates program.
+</PRE><FONT SIZE="+1">INPUTS</FONT>
+<PRE> cause - pointer to a string which describes the
+ cause of the error.
+ add_info - pointer to a string with additional information.
+</PRE><FONT SIZE="+1">SEE ALSO</FONT>
+<PRE> RB_Close_The_Shop ()
+</PRE><FONT SIZE="+1">SOURCE</FONT>
+<PRE> void <B>RB_Panic</B> (char *cause, char *add_info)
+ {
+ printf ("Robodoc: Error, %s\n",cause) ;
+ printf (" %s\n", add_info) ;
+ printf ("Robodoc: Panic Fatal error, closing down...\n") ;
+ RB_Close_The_Shop () ; <FONT COLOR = "#FF0000">/* Free All Resources */</FONT>
+ exit(100) ;
+ }
+</PRE></TD></TR></TABLE>
+
+
+
+
+ <H2><font color="red">7 </font><A NAME="CLD">Creating Cross Links</A></H2>
+
+<P>Creating hyper links within a document and across documents
+is the most interesting feature of ROBODoc. A document with such
+links is much more easier to read. If your source code consists
+of just one file, creating links is easy. Just tell ROBODoc that
+you want to have the output in HTML or AmigaGuide format, and it
+will automatically generate the links. That is, at the beginning
+of the document it will create a table of contents that consists
+of links to all your function headers.</P>
+
+<P>ROBODoc will also search the complete text of you
+documentation for reference to function names, and it will create
+a link to the documentation of that function.</P>
+
+<P>In most cases, however, your source code does not consists of
+a single file. It is also possible, however, to create links to
+other files. This does require the use of some additional files,
+called xref files. These files can be generated with ROBODoc.
+These files contain information about in which file and where in
+the file references can be found.</P>
+
+<P>Lets assume your project is split up in five different source
+files, and you want to generate links between these five files.
+What you have to do to accomplish this is to create a xref file
+for each of those five files.</P>
+
+<P>With the GENXREF option ROBODoc will generate such a xref file
+from the a source-file. When you use this option, only the xref
+file is created not the autodocs-file, however you still have to
+specify the name of the autodocs file because this name is needed
+for the creation of the xref file.</P>
+
+<P>When all xref files are created you are ready to create the
+documentation. To do so you use ROBODOC with the XREF option. It
+needs a parameter which is the name of the file in which the
+names of all xref files are defined. Notice: this is a file with
+file names, it has to be created it by hand.</P>
+
+<P>An example will make things more clear. In the ROBODoc
+archive, under <TT>examples/C</TT> there are two source files
+<A HREF="../Examples/C/prog1.c">prog1.c</A> and
+<A HREF="../Examples/C/prog2.c">prog2.c</A>. We can create
+documentation with hyper links from these two files as follows:
+</P>
+
+<P>First create the xref files:</P>
+
+<TABLE>
+<TR>
+<TD>
+<PRE>
+ robodoc prog1.c prog1.c.html GENXREF prog1.c.xref HTML INTERNAL
+ robodoc prog2.c prog2.c.html GENXREF prog2.c.xref HTML INTERNAL
+</PRE>
+</TD>
+</TR>
+</TABLE>
+
+<P>Now there are two xref files: prog1.c.xref and prog2.c.xref.
+Note that ROBODoc did not create any HTML files, just the xref
+files. The name prog1.c.html is needed to create the correct xref
+files. For prog1.c internal headers were also included. </P>
+
+<P>Now create a file with the xref file names. This file will
+hold only two lines. You can give it any name, say
+<TT>xref_files</TT>.</P>
+<TABLE>
+<TR>
+<TD>
+<PRE>
+ echo prog1.c.xref > xref_files
+ echo prog2.c.xref >> xref_files
+</PRE>
+</TD>
+</TR>
+</TABLE>
+<P>Now generate the final documentation:</P>
+<TABLE>
+<TR>
+<TD>
+<PRE>
+ robodoc prog1.c prog1.c.html XREF xref_files HTML INTERNAL
+ robodoc prog2.c prog2.c.html XREF xref_files HTML INTERNAL
+</PRE>
+</TD>
+</TR>
+</TABLE>
+
+<P>Have a look the the documentation generated:</P>
+<OL>
+ <LI><A HREF="../Examples/C/prog1.c.html">prog1.c.html</A></LI>
+ <LI><A HREF="../Examples/C/prog2.c.html">prog2.c.html</A></LI>
+</OL>
+
+
+
+<H3><font color="red">7.1 </font><A NAME="limits">Limitations</A></H3>
+
+<P> ROBODoc knows very little about the grammar of programming
+languages. Links are created by looking up words in a table.
+This means that it sometimes creates links where there should be
+none. For instance if you have a function called usage(); every
+time you use the word usage in any of your documentation a link
+will show up. It also means that sometimes is does not create
+links where you would like it to create a link. Say you include
+the source code of a method using the source item. Your method
+uses other methods of the class. You would like to have links
+pointing to the documentation of these methods each time you use
+one. They will not appear though. Since to ROBODoc stores the
+whole name of a method, ie, <TT>someClass::MethodName</TT>. In
+the method source you will use just <TT>MethodName()</TT>. </P>
+
+
+
+ <H2><font color="red">8 </font><A NAME="MAIND">Master Index File</A></H2>
+
+<P>If your project consists of many source files you might want
+to create a master index file.</P>
+
+<P>For HTML output this file contains links to the documentation
+generated from each of your source files as well as a list of all
+"objects" that you documented. All "objects" are listed according
+to header type, using the following order: Projects, Classes,
+Methods, Stuctures, Functions, Variables, Constants, Generic,
+Internal.</P>
+
+<P>For LaTeX output this file is one big document that contains
+the documentation generated from all your source files. It also
+includes a table of contents and an index section. This index
+lists the page number of the page a function's documentation.
+</P>
+
+<P>This index file is generated based on the information found in
+your xrefs file. That is the file with the names of all your xref
+files. So before you can create the master index file you have to
+create all your xref files.</P>
+
+<P>To generate a master index file use:</P>
+<PRE>
+ robodoc <xrefs file> <master index file> INDEX HTML TITLE "Master Index"
+</PRE>
+<P>or</P>
+<PRE>
+ robodoc <xrefs file> <master index file> INDEX LATEX TITLE "ROBODoc API Documentation"
+</PRE>
+<P>The master index file can currently only be generated in HTML or LaTeX.</P>
+
+<P>If you use if for LaTeX documentation you need to use the option
+<TT>SINGLEDOC</TT> when you generate the documentation from your various
+source files. This ensures that no document preambles are generated.
+The master index file contains command that includes all your documentation
+files and make it into one single document.</P>
+
+
+<H3><font color="red">8.1 </font><A NAME="MIEXM">examples</A></H3>
+
+<P>Here are some examples of master index files</P>
+<UL>
+
+ <LI><A HREF="../Examples/CPP/masterindex.html">Master index for a C++ project</A> to be found in
+ <TT>Examples/CPP/</TT></LI>
+
+ <LI><A HREF="../Source/ROBODoc_mi.html">Master index for ROBODoc</A> to be found in
+ <TT>Source/</TT>.
+ </LI>
+
+</UL>
+
+
+
+ <H2><font color="red">9 </font><A NAME="makefile">Automation with <TT>make</TT></A></H2>
+
+<P>The whole process of creating documentation with ROBODoc is of
+course best automated with <TT>make</TT>.
+Have a look at the following makefile.</P>
+
+<TABLE><TR><TD><PRE>
+SHELL = /bin/sh
+.SUFFIXES:
+
+ROBODOC=robodoc
+ROBOOPTS=C SORT
+
+# Your source files.
+#
+SOURCES=analyser.c generator.c items.c util.c \
+ folds.c headers.c links.c robodoc.c \
+ analyser.h generator.h items.h util.h \
+ folds.h headers.h links.h robodoc.h
+
+# The name of your Project
+#
+PROJECT=robodoc
+
+# The various documentation files, derived from the source files.
+# HTML
+#
+HTMLDOCS=$(SOURCES:=.html)
+HTMLXREFS=$(HTMLDOCS:.html=.html.xref)
+HTMLXREFSFILE=$(PROJECT)_html.xrefs
+# LATEX
+#
+LATEXDOCS=$(SOURCES:=.tex)
+LATEXXREFS=$(LATEXDOCS:.tex=.tex.xref)
+LATEXXREFSFILE=$(PROJECT)_tex.xrefs
+# ASCII
+#
+ASCIIDOCS=$(SOURCES:=.txt)
+# RTF
+#
+RTFDOCS=$(SOURCES:=.rtf)
+RTFXREFS=$(RTFDOCS:.rtf=.rtf.xref)
+RTFXREFSFILE=$(PROJECT)_rtf.xrefs
+
+# Some common targets
+xrefall: xrefhtml xreftex xrefrtf
+docall: html tex ascii rtf
+
+# Create the xref files for the various formats.
+xhtml: $(HTMLXREFSFILE)
+xtex: $(LATEXXREFSFILE)
+xrtf: $(RTFXREFSFILE)
+
+# Create the documentation files for the various formats.
+html: $(HTMLDOCS) $(PROJECT)_mi.html
+tex: $(LATEXDOCS) $(PROJECT)_mi.tex
+rtf: $(RTFDOCS)
+ascii: $(ASCIIDOCS)
+
+# master index file, currently works only for html and latex documentation.
+# Note that you can define the title of the document.
+$(PROJECT)_mi.html: $(HTMLXREFSFILE)
+ $(ROBODOC) $< $@ INDEX HTML TITLE "$(PROJECT) Master Index"
+
+$(PROJECT)_mi.tex: $(LATEXXREFSFILE)
+ $(ROBODOC) $< $@ INDEX LATEX TITLE "$(PROJECT) API Reference"
+
+# create xrefs file (file with the names of all .xref files).
+$(HTMLXREFSFILE) : $(HTMLXREFS)
+ /bin/ls $(HTMLXREFS) > $@
+$(LATEXXREFSFILE) : $(LATEXXREFS)
+ /bin/ls $(LATEXXREFS) > $@
+$(RTFXREFSFILE) : $(RTFXREFS)
+ /bin/ls $(RTFXREFS) > $@
+
+# Rule to create an .xref file from a source file for the various formats.
+%.html.xref : %
+ $(ROBODOC) $< $(@:.xref=) $(ROBOOPTS) INTERNAL GENXREF $@
+%.tex.xref : %
+ $(ROBODOC) $< $(@:.xref=) $(ROBOOPTS) INTERNAL GENXREF $@
+%.rtf.xref : %
+ $(ROBODOC) $< $(@:.xref=) $(ROBOOPTS) INTERNAL GENXREF $@
+
+# Rule to create html documentation from a source file.
+%.html : %
+ $(ROBODOC) $< $@ HTML $(ROBOOPTS) XREF $(HTMLXREFSFILE)
+
+# Rule to create latex documentation from a source file.
+# We do not include source items, and generate laxtex documents
+# than can be included in a master document.
+%.tex : %
+ $(ROBODOC) $< $@ LATEX $(ROBOOPTS) NOSOURCE SINGLEDOC XREF $(LATEXXREFSFILE)
+
+# Rule to create ascii documentation from a source file.
+%.txt : %
+ $(ROBODOC) $< $@ ASCII
+
+# Rule to create rtf documentation from a source file.
+%.rtf : %
+ $(ROBODOC) $< $@ RTF $(ROBOOPTS) XREF $(RTFXREFSFILE)
+
+# Use netscape to view the master index file for our project.
+htmlview: html
+ netscape $(PROJECT)_mi.html
+
+# Use the latex programs to generate a .dvi from the master index file
+# for our prokect. View this .dvi file with xdvi
+texview: tex
+ latex $(PROJECT)_mi
+ makeindex $(PROJECT)_mi
+ latex $(PROJECT)_mi
+ latex $(PROJECT)_mi
+ xdvi $(PROJECT)_mi.dvi
+
+# Clean-up the mess we made
+#
+clean:
+ rm -f $(HTMLXREFS)
+ rm -f $(HTMLDOCS)
+ rm -f $(LATEXXREFS)
+ rm -f $(LATEXDOCS)
+ rm -f $(PROJECT)_mi.* *.aux
+ rm -f $(RTFXREFS)
+ rm -f $(RTFDOCS)
+ rm -f $(ASCIIDOCS)
+ rm -f $(HTMLXREFSFILE)
+ rm -f $(LATEXXREFSFILE)
+ rm -f $(RTFXREFSFILE)
+</PRE></TD></TR></TABLE>
+
+<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.
+For instance to create documentation in html format use:</P>
+<TABLE><TR><TD><PRE>
+ make xhtml
+ make html
+</PRE></TD></TR></TABLE>
+<P>To make documentation in LaTeX format use:</P>
+<TABLE><TR><TD><PRE>
+ make xtex
+ make tex
+</PRE></TD></TR></TABLE>
+<P>To view your documentation use:</P>
+<TABLE><TR><TD><PRE>
+ make xhtml
+ make texview
+</PRE></TD></TR></TABLE>
+<P>or</P>
+<TABLE><TR><TD><PRE>
+ make xtex
+ make texview
+</PRE></TD></TR></TABLE>
+
+
+<P>To clean up all the documentation files use:</P>
+<PRE>
+ make clean
+</PRE>
+
+<P>To use this make file in project set the variable
+<TT>SOURCE</TT> to the names of your source files and set the
+variable <TT>PROJECT</TT> to the name of your project.</P>
+
+<P>You can find a copy of the above makefile
+<TT>Docs/example_makefile</TT>. This should get you started in
+no time.</P>
+
+ <H2><font color="red">10 </font><A NAME="MDSO">What to do if You have Sources in Multiple Directories</A></H2>
+
+<P>It is possible to have your sources in multiple
+subdirectories. However the generated documentation is expected
+to be in one single directory. If not the cross references will
+be wrong, at least in the HTML documentation.</P>
+
+<P>Say you have the following directory structure:</P>
+<TABLE><TR><TD><PRE>
+ Project/
+ Dir1/
+ program1.c
+ Dir2/
+ program2.c
+</PRE></TD></TR></TABLE>
+
+<P>You can create the documentation for that as follows (assuming
+you are in Project):
+</P>
+<TABLE><TR><TD><PRE>
+ robodoc Dir1/prog1.c prog1.c.html HTML GENXREF Dir1/prog1.xref
+ robodoc Dir2/prog2.c prog2.c.html HTML GENXREF Dir2/prog2.xref
+ echo "Dir1/prog1.xref" > xreffiles
+ echo "Dir2/prog2.xref" >> xreffiles
+ robodoc Dir1/prog1.c prog1.c.html HTML XREF xreffiles
+ robodoc Dir2/prog2.c prog2.c.html HTML XREF xreffiles
+ robodoc xreffiles master_index.html INDEX HTML
+</PRE></TD></TR></TABLE>
+<P>
+This generates the following files:
+</P>
+<TABLE><TR><TD><PRE>
+ prog1.c.html
+ prog2.c.html
+ master_index.html
+</PRE></TD></TR></TABLE>
+
+
+<P>With some version of make (for instance the gnu version) you
+can strip the directory part of a filename with $(notdir NAME)
+How this can be used is shown in the following example
+makefile. Here we have the sources for robodoc, the <TT>.c</TT> files are
+in the directory <TT>Sources/</TT> and <TT>.h</TT> files are in the
+directory <TT>Headers/</TT>.</P>
+
+<TABLE><TR><TD><PRE>
+SHELL = /bin/sh
+.SUFFIXES:
+
+ROBODOC=./robodoc
+ROBOOPTS=C SORT
+
+# Your source files.
+#
+SOURCES=Sources/analyser.c Sources/generator.c Sources/items.c Sources/util.c \
+ Sources/folds.c Sources/headers.c Sources/links.c Sources/robodoc.c \
+ Headers/analyser.h Headers/generator.h Headers/items.h Headers/util.h \
+ Headers/folds.h Headers/headers.h Headers/links.h Headers/robodoc.h
+
+# The name of your Project
+#
+PROJECT=ROBODoc
+
+# The various documentation files, derived from the source files.
+#
+HTMLDOCS=$(SOURCES:=.html)
+HTMLXREFS=$(HTMLDOCS:.html=.html.xref)
+HTMLXREFSFILE=$(PROJECT)_html.xrefs
+
+# Create the xref files for the various formats.
+xhtml: $(HTMLXREFSFILE)
+
+# Create the documentation
+html: $(HTMLDOCS) $(PROJECT)_mi.html
+
+# Create master index file.
+$(PROJECT)_mi.html: $(HTMLXREFSFILE)
+ $(ROBODOC) $< $@ INDEX HTML TITLE "$(PROJECT) Master Index"
+
+# Create the file with the names of all xref files.
+$(HTMLXREFSFILE) : $(HTMLXREFS)
+ /bin/ls $(HTMLXREFS) > $@
+
+# Rule to create an .xref file from a source file
+%.html.xref : %
+ $(ROBODOC) $< $(notdir $(@:.xref=)) $(ROBOOPTS) INTERNAL GENXREF $@
+
+# Rule to create html documentation from a source file.
+%.html : %
+ $(ROBODOC) $< $(notdir ${@}) HTML $(ROBOOPTS) XREF $(HTMLXREFSFILE)
+</PRE></TD></TR></TABLE>
+
+
+
+ <H2><font color="red">11 </font><A NAME="RDF">The ROBODoc Defaults File</A></H2>
+
+<P>The robodoc.default file can be used to change the appearance
+of the documentation. For each item type you can define how the
+corresponding text should be rendered. Each line in the default
+file consists of two parts, the item type and the item
+attributes. For instance</P>
+
+<PRE>
+AUTHOR LARGE ITALICS BOLD UNDERLINE
+</PRE>
+
+<P>Specifies that the AUTHOR item has the attributes LARGE,
+ITALICS, BOLD, and UNDERLINE. The effect of each attribute is
+listed in the following table.</P>
+
+<TABLE>
+<TR><TD>Item Attributes</TD>
+ <TD>Effect in HTML</TD>
+</TR>
+<TR><TD>LARGE</TD>
+ <TD><FONT SIZE=5>,</FONT></TD>
+</TR>
+<TR><TD>SMALL</TD>
+ <TD><FONT SIZE=-1>,</FONT></TD>
+</TR>
+<TR><TD>ITALICS</TD>
+ <TD><I>,</I></TD>
+</TR>
+<TR><TD>BOLD</TD>
+ <TD><B>,</B></TD>
+</TR>
+<TR><TD>UNDERLINE</TD>
+ <TD><U>,</U></TD>
+</TR>
+<TR><TD>HIGHLIGHT</TD>
+ <TD><EM>,</EM></TD>
+</TR>
+</TABLE>
+
+
+ <H2><font color="red">12 </font><A NAME="UOB">ROBODoc Command Line Options</A></H2>
+
+<P>When using ROBODoc you should provide at least two
+parameters</P>
+
+<PRE>
+ robodoc <source file> <documentation file> [options]
+</PRE>
+
+<P>Here sourcefile is the file with the program source from which
+the documentation is to be extracted. The documentation file is
+the file that will contain the extracted documentation. </P>
+
+<P>In case you are creating a master index file you have to
+specify three parameters</P>
+<PRE>
+ robodoc <xrefs file> <master index file> INDEX [options]
+</PRE>
+
+
+<P>In addition to this you can specify one or more of the
+following options:</P>
+
+<TABLE >
+ <TR><TD><TT>ASCII</TT></TD>
+ <TD>Generate documentation in ASCII format (default)</TD>
+ </TR>
+ <TR><TD><TT>GUIDE</TT></TD>
+ <TD>Generate documentation in AmigaGuide format.</TD>
+ </TR>
+ <TR><TD><TT>HTML</TT></TD>
+ <TD>Generate documentation in HTML format.</TD>
+ </TR>
+ <TR><TD><TT>LATEX</TT></TD>
+ <TD>Generate documentation in LaTeX format. (Experimental)</TD>
+ </TR>
+ <TR><TD><TT>RTF</TT></TD>
+ <TD>Generate documentation in RTF format.</TD>
+ </TR>
+ <TR><TD><TT>C</TT></TD>
+ <TD>Use ANSI C grammar in source items (test, HTML only)</TD>
+ </TR>
+ <TR><TD><TT>FOLD</TT></TD>
+ <TD>Enable folding. (Experimental)</TD>
+ </TR>
+ <TR><TD><TT>GENXREF <xref file></TT></TD>
+ <TD>Generate a xref file, which can be used to create
+ <A HREF="#CLD">cross links</A> between documents.</TD>
+ </TR>
+ <TR><TD><TT>XREF <xrefs file></TT></TD>
+ <TD>Use a set of xref files to create references (links) to other
+ documents or within the document. <TT><xrefs file></TT>
+ is a file with xref file names.</TD>
+ </TR>
+ <TR><TD><TT>INDEX</TT></TD>
+ <TD>Create a <A HREF="#MAIND">master index file</A>.</TD>
+ </TR>
+ <TR><TD><TT>INTERNAL</TT></TD>
+ <TD>Also include headers that are marked internal.</TD>
+ </TR>
+ <TR><TD><TT>INTERNALONLY</TT></TD>
+ <TD>Only extract the headers marked internal.</TD>
+ </TR>
+ <TR><TD><TT>NOSOURCE</TT></TD>
+ <TD>Do not include the source items in the documentation.</TD>
+ </TR>
+ <TR><TD><TT>SORT</TT></TD>
+ <TD>Sort the headers alphabetically.</TD>
+ </TR>
+ <TR><TD><TT>SINGLEDOC</TT></TD>
+ <TD>Do not create a document header and footer when creating
+ documentation in LaTeX format. This allows you to include
+ the generated documents into big document or
+ <A HREF="#MAIND">master index file</A>.</TD>
+ </TR>
+ <TR><TD><TT>TITLE <title></TT></TD>
+ <TD>Sets the title that is used for the
+ <A HREF="#MAIND">master index file</A>.</TD>
+ </TR>
+ <TR><TD><TT>TOC</TT></TD>
+ <TD>Generate a table of contents. It is only useful when you select
+ ASCII as output mode. With all other output modes the
+ table of contents is generated anyway.</TD>
+ </TR>
+ <TR><TD><TT>TABSIZE <n></TT></TD>
+ <TD>Convert each tab into <TT>n</TT> spaces.</TD>
+ </TR>
+ <TR><TD><TT>-v</TT></TD>
+ <TD>Verbose option, ROBODoc will tell you what it is doing.</TD>
+ </TR>
+</TABLE>
+
+<P>If you wonder why all the odd ALL CAPS flags are used instead
+of for instance "-x"; this was how it was done on the Amiga.</P>
+
+<P>The following abbreviations are also allowed:</P>
+<TABLE >
+<TR><TD><TT>-s </TT></TD><TD><TT>SORT</TT></TD></TR>
+<TR><TD><TT>-t </TT></TD><TD><TT>TOC</TT></TD></TR>
+<TR><TD><TT>-x </TT></TD><TD><TT>XREF</TT></TD></TR>
+<TR><TD><TT>-g </TT></TD><TD><TT>GENXREF</TT></TD></TR>
+<TR><TD><TT>-i </TT></TD><TD><TT>INTERNAL</TT></TD></TR>
+<TR><TD><TT>-io</TT></TD><TD><TT>INTERNALONLY</TT></TD></TR>
+<TR><TD><TT>-ts</TT></TD><TD><TT>TABSIZE</TT></TD></TR>
+</TABLE>
+
+
+ <H2><font color="red">13 </font><A NAME="ADV">Adding New Languages</A></H2>
+
+<P>To add a new programming language to ROBODoc you have to edit
+<TT>headers.c</TT>. Here you find three variables:
+<TT>header_markers</TT>, <TT>remark_markers</TT>, and
+<TT>end_markers</TT>. There are all arrays, and you have to add
+an new entry to each of these three arrays.</P>
+
+<P>Say your programming language uses the following type of remarks:</P>
+<PRE>
+ $%% This is a remark with some text
+ and some more and some more %%$
+</PRE>
+
+<P>That is is starts with three spaces and then <TT>$%%</TT>, and
+has to end with <TT>%%$</TT>. Then you would add to <TT>header_markers</TT>
+</P>
+<PRE>
+ " $%%****",
+</PRE>
+<P>To <TT>remark_markers</TT> you would add</P>
+<PRE>
+ " *",
+</PRE>
+<P>And to <TT>end_markers</TT> you would add</P>
+<PRE>
+ " $%%***",
+</PRE>
+<P>You can then use the following kind of headers in your program:</P>
+<PRE>
+ $%%****f* Test/afunction *****
+ * NAME
+ * afunction
+ * FUNCTION
+ * A test.
+ * SOURCE
+ *%%$
+ afunction(test,test) [
+ print hello world ;
+ ]
+ $%%***%%$
+</PRE>
+
+
+
+
+
+ <H2><font color="red">14 </font><A NAME="SAB">Suggestions and Bugs</A></H2>
+
+<P>If you find any bugs, catch them, put them in a jar, and send
+them to:</P>
+<ADDRESS>fslothouber@acm.org</ADDRESS>
+<P>Suggestions are also welcome at this address. Flames can be
+directed to the sun.</P>
+
+</BODY>
+</HTML>
+
projects / silc.git / blobdiff