Robodoc v3.0j
(c) 20 Dec 1997, Maverick Software Development
robodoc documentation for the;
Amiga systems
DEC Alpha systems
DEC VAX systems
UNIX systems
Windows NT systems
Original program and idea: Jacco van Weert
Versions 2.0 and up:
Frans Slothouber, Bernd Koesling, Anthon Pang, and Thomas Aglassinger
New versions of Robodoc are made available on AmiNet.
1.0 Preface
------------
The complete Robodoc archive is copyrighted by Jacco van Weert, and
Frans Slothouber of Maverick Software Development.
Robodoc can be freely distributed on FREEWARE base as long as all
files remains in their original state, no files may be added to the
archive, and also no files may be excluded.
This software is provided on an "AS IS" basis without warranty of any
kind. We are not responsible for any damage to your hardware,
software, or brain, caused by using this software.
You can use Robodoc with C, Assembler, Basic, Fortran, LaTex, and PS
programs. Additional languages can be used by a few modifications to
the source code.
2.0 Introduction
----------------
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 will extract those headers
from the source file and put them in a autodocs-file. This way you
can include the program documentation in the source code and is it not
necessary to maintain two documents.
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 can
fully automatically create links within the document, and to other
documents. It is also possible to include parts of the source in you
document, complete with links. For instance it is possible to include
a complete subroutine, and have the function names in this subroutine
point to their documentation.
If you never have used AutoDoc or Robodoc before you might take a look
at the example in the examples directory. These are two amigaguide
files that contain the documentation generated with Robodoc of the
Robodoc program itself.
Robodoc can generate the documentation in five different
formats:
o ASCII format;
The autodocs-file is just a plain ASCII text-file, this file
is very closely related to the one that the original
AutoDocs program would generated.
o AmigaGuide format;
This is a format used on the Amiga computers to view in a
HyperText way a text-file. The AmigaGuide program is
necessary to view the resulting autodocs-file.
o HTML format;
The autodocs-file will be written as a HTML-file (HyperText
Markup Language), this format is used on the WWW-Internet.
By using a Mosaic/Netscape program you view the
documentation.
o LaTex
o RTF
3.0 Hardware and software requirements
---------------------------------------
Robodoc was developed on a standard Amiga 1200. It is written in C,
and has been successfully compiled with SAS/C 6.50 and DICE C.
However it is written according to the ansi C standard and uses no
special functions, so it should run on every system with a C-compiler.
For instance it also has been successfully compiled with gcc on a Sun
system.
The complete source code consists of two files; Robodoc.c and
Robodoc.h.
4.0 This Version Of Robodoc
---------------------------
This is version 3.0j of Robodoc, containing a number of bug fixes, and
conforms to the DTD for HTML-3.2 (thanks to the work of Thomas
Aglassinger).
5.0 How to format your code so that you can use Robodoc.
---------------------------------------------------------
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.
/****h* AUTODOC/robodoc [2.0d]
*
* NAME
* robodoc -- AutoDoc formatter
* COPYRIGHT
* Maverick Software Development
* FUNCTION
* Robodoc is indented as a replacement for the original
* AutoDocs program Robodoc will extract from a source file
* the procedure comment headers and put them in a separate
* documentation file.
* CREATION DATE
* 20-Dec-94
* MODIFICATION HISTORY
* 25-Jan-94 - v0.92: First version
* 10-Mar-95 - v1.0 : Complete version
* 10-May-1995 - v2.0 : Major update.
* NOTES
* Has been successfully compiled with DICE and SAS.
*******
*/
It includes two special markers, and a number of items. There is
a marker that marks the beginning of a header and one that marks
the end of a header.
This header is intended for a program in C, a same header for
another languages would look a slightly different. However
Robodoc recognizes some other types markers to:
/**** C
;**** Assembler
**** Assembler
REM **** Basic
C **** Fortran
%**** LaTeX, TeX, Postscript
After which a "i", "*" or "h" (header type) should follow, then
another * and then:
<MOD>/<PROC><SP>[<VERSION>]<SP><REST>
Where:
<SP> - is any sequence of white characters (spaces of tabs),
excluding the empty string.
<TYPE> - The header type, this is one of the following characters,
'h' = MainProgram, '*' = Normal header, 'i' = Internal
header.
<MOD> - Module name, any sequence of non white characters, except
'/'.
<FUNC> - Function name, any sequence of non white characters.
<VERSION> - A version number, any sequence of non white characters,
except ']'.
<REST> - rest of the line, any sequence of characters.
This might look terribly complicated but here are some examples:
In C
/****h* programs/greatprogram.library [1.0] *
In Assembler
****** greatprogram.library/program_init
;****i* greatprogram.library/very_secret [2.0d] ***
In Fortran
C ****h* programs/greatprogram.library C
In Basic, (assuming you don't use basis that still needs line numbers).
REM ****h* programs/greatprogram.library
A header ends with at least three asterisks at the start of a
line ("***") right after the remark marker. In general Robodoc
will recognize anything of the that starts with:
C ***
REM ***
***/
;***
%***
5.1 Header Types
----------------
Robodoc handles three different type of headers;
o MainProgram header (optional);
These headers are placed at the start of a program and
containing some general information about the program.
These where not available in the original AutoDocs program.
o Normal header;
The normal header, available to the general public.
o Internal header;
The internal header not available to the general public,
mainly used by the programmer him/herself.
5.2 Header Items.
-----------------
When Robodoc has found a header it will try to identify items,
currently it looks for one of the following item names:
"NAME", "COPYRIGHT", "SYNOPSIS",
"FUNCTION", "DESCRIPTION", "AUTHOR",
"CREATION DATE", "MODIFICATION HISTORY", "HISTORY",
"INPUTS", "ARGUMENTS", "OPTIONS", "PARAMETERS", "SWITCHES",
"OUTPUT", "SIDE EFFECTS", "RESULT", "RETURN VALUE",
"EXAMPLE", "NOTES", "DIAGNOSTICS",
"WARNINGS", "ERRORS", "BUGS", "TODO", "IDEAS",
"PORTABILITY", "SEE ALSO", "SOURCE",
"BEAST METHODS", "NEW METHODS",
"BEAST ATTRIBUTES", "NEW ATTRIBUTES",
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.
To get an idea what the various items are meant for take a look
at the following header that was taken from the original AutoDoc
documentation (hope they don't object to this;)
/****** financial.library/StealMoney *****************************
*
* NAME
* StealMoney -- Steal money from the Federal Reserve Bank. (V77)
* SYNOPSIS
* 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
*
*******************************************************************/
5.2.1 The Source Item
-----------------------
New for version 2.0 is the source item. It allows you to include
part of the source in the documentation as is demonstrated by the
following example.
/****i* Robodoc.c/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 with the 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 () ;
exit(100) ;
}
/*******/
The source item is in an experimental stage at the moment. All
lines between the source item and the following item are copied
verbatim to the AutoDocs document. It might be possible that
certain expressions within the source conflict with the
amigaguide program or a HTML viewer. If so please report them
to me, that is <slothoub@xs4all.nl>, 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} <FONT SIZE=5>,</FONT>
SMALL FONT SIZE=-1>,</FONT>
NONPROP </PRE>,<PRE>
ITALICS @{i},@{ui} <I>,</I>
BOLD @{b},@{ub} <B>,</B>
UNDERLINE @{u},@{uu} <U>,</U>
SHINE @{fg shine},@{fg text} <EM>,</EM>
HIGHLIGHT @{fg highlight},@{fg text} <EM>,</EM>
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 <xreflist_filename> 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 <sourcefile> <autodocfile>
Here <sourcefile> is the file with the program source of which
you want to extract the documentation from and <autodocfile> 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 <xref_filename>
Generate a xref file, which then can be used to created
references within the documentation.
XREF <xreflist_filename>
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 <number>
Convert each tab into <number> 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....
|
aminet net>