, so they can perhaps be
solved in a next release a Robodoc.
5.3 The Robodoc Defaults file.
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
AUTHOR LARGE ITALICS BOLD UNDERLINE
Specifies that the AUTHOR item has the attributes LARGE,
ITALICS, BOLD, and UNDERLINE.
The effect of each attribute is listed in the following table.
Item Attributes GUIDE HTML
--------------------------------------------------------------
LARGE @{b},@{ub} ,
SMALL FONT SIZE=-1>,
NONPROP ,
ITALICS @{i},@{ui} ,
BOLD @{b},@{ub} ,
UNDERLINE @{u},@{uu} ,
SHINE @{fg shine},@{fg text} ,
HIGHLIGHT @{fg highlight},@{fg text} ,
5.4 Creating links within the document.
---------------------------------------
Creating links within the document 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.
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.
An example, assume you have the following function header in your
source:
/****** Airmail.c/ZM_xpr_fopen [2.0a]
* NAME
* ZM_xpr_fopen -- open a file.
* SYNOPSIS
* filehandle = ZM_xpr_fopen (filename, accessmode)
* long ZM_xpr_fopen (char *, char *)
* FUNCTION
* Open a file.
* INPUTS
* filename - pointer to a string containing the file name.
* accessmode - how the file should be opened (C compatible).
* RESULT
* a pointer to the opened file.
* 0 -- if the open failed
* SEE ALSO
* ZM_xpr_fread, ZM_xpr_fwrite, ZM_xpr_fclose.
******
*/
It will automatically turn "ZM_xpr_fread", "ZM_xpr_fwrite", and
"ZM_xpr_fclose" into links to the documentation of these
functions, (provided you have documented them of course).
6.0 The XREF files
------------------
The previous section described how to create links within a
document, it is also possible, however, to create links to other
files. This does require the use of some additional files,
called xref files, but these can also be generated with Robodoc.
These xref files contain information about were certain
references can be found and in which file.
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.
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.
When all the xref files are created the documentation can be
created. To do so you have to use the XREF option and
parameter. This parameter contains the name of the file in
which the names all xref files are defined (xreflist_filename).
Notice: this is a file with FILE NAMES, and you must created it
by hand.
Xref files can also be created by the user or by other means,
e.g. the Autodoc.xref. robodoc uses the same format as these
standard XREF files.
An Example will make thing more clearly:
In the robodoc.lha archive there are two example programs
prog1.C and prog2.C.
First create the xref files when want to create amigaguide
autodocs-files:
Robodoc prog1.c prog1.guide GENXREF prog1.c.xref GUIDE
Robodoc prog2.c prog2.guide GENXREF prog2.c.xref GUIDE
Now there are two xref files: prog1.xref and prog2.xref.
Now create a file.
This file will hold only two lines;
prog1.c.xref
prog2.c.xref
More xref files can be added. The name of this file can be
anything, say it is "xref_files".
Now generate the final documentation;
robodoc prog1.c prog1.c.guide XREF xref_files GUIDE
Robodoc prog2.c prog2.c.guide XREF xref_files GUIDE
7.0 Usage of Robodoc
--------------------
When you call Robodoc you should at least provide two parameters
Robodoc
Here is the file with the program source of which
you want to extract the documentation from and is
the file were you want the documentation to be stored.
In addition to this you can specify one of the following
options:
ASCII
The documentation will be in ASCII format (default).
GUIDE
The documentation will be in AmigaGuide format.
HTML
The documentation will be in HTML format.
LATEX
The documentation will be in LATEX format. (Experimental)
RTF
The documentation will be in RTF format.
GENXREF
Generate a xref file, which then can be used to created
references within the documentation.
XREF
Use a set of xref files to create references (links) to other
documents or within the document.
INTERNAL
Also include headers that are marked internal.
INTERNALONLY
Only extract the headers marked internal.
SORT
Sort the headers alphabetically.
TOC
Generate a table of contents. Is only useful when you select
ASCII as output mode. With all other output modes the Table of
contents is generated anyway.
TABSIZE
Convert each tab into spaces.
-v
Verbose option, Robodoc will tell you what it is doing.
The following abbreviations are also allowed:
SORT = -s
TOC = -t
XREF = -x
GENXREF = -g
INTERNAL = -i
INTERNALONLY = -io
TABSIZE = -ts
8.0 Suggestions or bugs
-----------------------
If you find any bugs, catch them, put them in a jar, and send
them to:
slothoub@xs4all.nl.
Suggestions are also welcome on this address.
Flames can be directed to the sun....