1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
|
<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"><title>ROBODoc 4.0.18 User Manual</title><meta name="generator" content="DocBook XSL Stylesheets V1.49"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article"><div class="titlepage"><div><h1 class="title"><a name="id2746724"></a>ROBODoc 4.0.18 User Manual</h1></div><div><h3 class="author">Frans Slothouber</h3>
and
<h3 class="author">Petteri Kettunen</h3></div><div><p class="copyright">Copyright 1994-2004 Frans Slothouber, Petteri Kettunen, Jacco van Weert</p></div><div><p class="pubdate">January 2004</p></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="#id2749753">Preface</a></dt><dt><a href="#installing">Installing ROBODoc</a></dt><dt><a href="#preparing">Preparing your source code for ROBODoc</a></dt><dd><dl><dt><a href="#id2749946">Headers</a></dt><dt><a href="#id2750133">Header Types</a></dt><dt><a href="#id2750297">Items</a></dt><dt><a href="#sections">Sections</a></dt></dl></dd><dt><a href="#id2750418">Extracting Documentation with ROBODoc</a></dt><dd><dl><dt><a href="#id2750434">Single document or many smaller documents</a></dt><dt><a href="#id2750479">multidoc</a></dt><dt><a href="#id2750553">singledoc</a></dt><dt><a href="#id2750637">singlefile</a></dt><dt><a href="#id2750702">Output formats</a></dt><dt><a href="#id2750766">Options</a></dt><dd><dl><dt><a href="#id2750778">-c</a></dt><dt><a href="#id2750789">--cmode</a></dt><dt><a href="#id2750803">--css</a></dt><dt><a href="#id2750824">--dbxml</a></dt><dt><a href="#id2750837">--doc</a></dt><dt><a href="#id2750878">--folds</a></dt><dt><a href="#id2750891">--html</a></dt><dt><a href="#id2750903">--internal</a></dt><dt><a href="#id2750915">--internalonly</a></dt><dt><a href="#id2750927">--index</a></dt><dt><a href="#id2750940">--lock</a></dt><dt><a href="#id2750511">--multidoc</a></dt><dt><a href="#id2750592">--nosource</a></dt><dt><a href="#id2750671">--nodesc</a></dt><dt><a href="#id2750982">--rc</a></dt><dt><a href="#id2750994">--rtf</a></dt><dt><a href="#id2751004">--sections</a></dt><dt><a href="#id2751014">--singledoc</a></dt><dt><a href="#id2751024">--singlefile</a></dt><dt><a href="#id2751033">--src</a></dt><dt><a href="#id2751053">--tabsize</a></dt><dt><a href="#id2751063">--toc</a></dt><dt><a href="#id2751073">--latex</a></dt><dt><a href="#id2751084">--tell</a></dt></dl></dd></dl></dd><dt><a href="#customizing">Customizing ROBODoc</a></dt><dd><dl><dt><a href="#id2751158">items block</a></dt><dt><a href="#id2751183">ignore items block</a></dt><dt><a href="#id2751200">options block</a></dt><dt><a href="#id2751214">headertypes block</a></dt><dt><a href="#id2751234">ignore files block</a></dt><dt><a href="#id2751286">Configuration file location</a></dt></dl></dd><dt><a href="#id2751326">Examples</a></dt><dd><dl><dt><a href="#id2751332">HTML Example</a></dt><dt><a href="#id2751362">RTF Example</a></dt><dt><a href="#id2751416">LaTeX Example</a></dt><dt><a href="#id2751450">XML DocBook Example</a></dt></dl></dd><dt><a href="#id2751495">Tips and Tricks</a></dt><dd><dl><dt><a href="#id2751502">Using ROBODoc under Windows</a></dt><dt><a href="#id2751570">The SOURCE Item</a></dt><dt><a href="#id2751624">Advanced formating with raw HTML and LaTeX code</a></dt><dt><a href="#id2751718">Linking to external documents (href, file, mailto, images)</a></dt><dt><a href="#id2751804">Linking from an external document.</a></dt></dl></dd><dt><a href="#id2751873">Suggestions and Bugs</a></dt></dl></div><div class="section"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="id2749753"></a>Preface</h2></div></div><p>ROBODoc is a API documentation tool for C, C++, Java,
Assembler, Basic, Fortran, LaTeX, Postscript, Tcl/Tk, LISP, Forth,
Perl, Shell Scripts, Makefiles, Occam, COBOL, DCL, Visual Basic,
HTML, DB/C, and many other languages. It can be made to work with
any language that supports comments.</p><p>ROBODoc works by extracting specially formated headers from
your source code and writes these to documentation files. These
files can be formatted in HTML, ASCII, XML DocBook, or RTF; and
indirect to PDF.</p><p>ROBODoc is similar to JavaDoc, though the idea is much
older than JavaDoc. ROBODoc allows you to maintain a program and
its documentation in a single file. This makes it easier to keep
your documentation up-to-date.</p><p>ROBODoc can be used to document anything you like,
functions, methods, variables, definitions, test cases, makefile
entries, and anything else you can think of.</p><p>It can create documentation consisting of many small files.
For instance in HTML format for easy browsing and publication on
the web. It can also create a single file in LaTeX or RTF format
for inclusion into bigger design documents. The RTF format is
suited to be included in Word documents.</p><p>ROBODoc allows you to separate internal documentation from
external documentation. In singledoc mode it can create a section
layout based on the hierarchy of your modules.</p><p>ROBODoc is designed to work with a lot of different
programming languages. It has no knowledge of the syntax of a
programming languages. It only has some knowledge about how
remarks start and end in a lot of 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></div><div class="section"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="installing"></a>Installing ROBODoc</h2></div></div><p>The easiest way to install ROBODoc is to use one of the
packages. There are package for RedHat, OSX, and a precompiled
executable for Windows.</p><p>You can also compile robodoc from the sources. On a system
with <b>autoconfig</b> it is as simple as:</p><pre class="programlisting">
./configure
make
make install
</pre><p>On a Windows system with VC++ you have two options. Either
use the following commands in the source directory (tested under
NT):</p><pre class="programlisting">
vcvars32
nmake -f makefile.win32
</pre><p>Or use the supplied project file
<tt>robodoc.dws</tt> in the <tt>Win32</tt>
directory. This only works if the <tt>.dsp</tt> and
<tt>.dws</tt> have the right format. Both files should
use the windows convention for line-endings (cr/lf). Sometimes
these get lost while zipping or unzipping the ROBODoc archive, and
in that case the project will turn op empty.</p><p>There is also a makefile for Borland C, as well as for MINGW.
For other compilers you might want to try
<tt>makefile.pain</tt>. </p><p>You can test your executable, by going to the
<tt>Examples/PerlExample</tt> directory in the
archive, and running robodoc. This should create a directory
called <tt>Doc</tt>. In there you should now
find a file called <tt>masterindex.html</tt>.
</p></div><div class="section"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="preparing"></a>Preparing your source code for ROBODoc</h2></div></div><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. There are
three key concepts: headers, items, and sections. </p><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2749946"></a>Headers</h3></div></div><p>Headers are the building blocks of the documentation. Lets
look at an example. The following header was taken from the
documentation of the predecessor of ROBODoc, AutoDoc.</p><pre class="screen">
/****f* financial.library/StealMoney
* NAME
* StealMoney -- Steal money from the Federal Reserve Bank. (V77)
* SYNOPSIS
* error = StealMoney( userName, amount, destAccount, 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).
* 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
******
* You can use this space for remarks that should not be included
* in the documentation.
*/
</pre><p>A header consists of three different elements. A
begin marker, a number of items, and an end marker. The begin marker
in the example is example is:</p><pre class="screen">
****f* financial.library/StealMoney
</pre><p>It marks the that marks the begin of a header. It also
tells ROBODoc the name of the element that is being documented,
StealMoney, the module it is part of, financial.library, and the
kind of element, <tt>f</tt>, which stands for function.
ROBODoc always expects a module name and an element name separated
by a <tt>/</tt>. So <tt>ModFoo/funcBar</tt>
is a valid name, but <tt>funcBar</tt> is not.
See <a href="#sections">Sections</a> for more
information.</p><p>
The end marker:
</p><pre class="screen">
******
</pre><p>
marks the end of a header.
</p><p>Items begin with an item name and are followed by the
item's body. An example: </p><pre class="screen">
* FUNCTION
* Transfer money from the Federal Reserve Bank into the
* specified interest-earning checking account. No records of
* the transaction will be retained.
</pre><p>
In this case the item's name is FUNCTION.
</p><p>
Each line of an item starts with a remark marker. In this case
<tt>*</tt>.
</p><p>
The above example is a C example. ROBODoc supports many more
languages though. The following table shows all the markers that
ROBODoc supports by default.
</p><pre class="screen">
/**** C, C++
*
***/
//**** C++
//
//***
(**** Pascal, Modula-2
*
***
*)
{**** Pascal
*
***
*}
;**** M68K assembler
;
;***
**** M68K assembler, COBOL
*
***
C **** Fortran
C
C ***
REM **** BASIC
REM *
REM ***
%**** LaTeX, TeX, Postscript
%
%***
#**** Tcl/Tk
#
#***
--**** Occam
--
--***
<!--**** HTML Code
*
***
<!---**** HTML Code
*
***
|**** GNU Assembler
|
|***
$!**** DCL
$!
$!***
'**** Visual Basic, Lotus script
'*
'***
.**** DB/C
.*
.***
!!**** FORTRAN 90
!!
!!***
!**** FORTRAN 90
!
!***
</pre><p> Any of these markers can be mixed, and they are not limited
to the languages listed. So if you have a language that is not
listed but that has remarks that start with a <tt>#</tt>
you can use the Tcl/Tk markers, and create headers such as:
</p><pre class="screen">
#****f* Foo/Bar
# FUNCTION
# Bar snarfs the Foo input and mangles it. Given the right settings
# it might also do a bit of snu snu.
#***
</pre></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2750133"></a>Header Types</h3></div></div><p> ROBODoc defines a number of header types. You don't need
to use them but they can be useful for sorting information. The
headertype tells ROBODoc what kind of object you are documenting.
This information allows ROBODoc to create more useful index
tables.</p><p>The type is identified by one or two characters. ROBODoc
expects to find them after the fourth <tt>*</tt> in the
begin marker. So <tt>#****f</tt> is a valid marker,
but <tt>#**f**</tt> is not.</p><p>If a single character is given, the type is defined as
listed in the following table</p><div class="itemizedlist"><ul type="disc"><li> c -- Header for a class. </li><li> d -- Header for a constant (from define). </li><li> f -- Header for a function. </li><li> h -- Header for a module in a project. </li><li> m -- Header for a method. </li><li> s -- Header for a structure. </li><li> t -- Header for a types. </li><li> u -- Header for a unittest. </li><li> v -- Header for a variable. </li><li> * -- Generic header for every thing else. </li></ul></div><p>If two characters are given, the first character should be
<tt>i</tt> and the second can be any of the other
characters from the table above. This creates an internal header
of the type specified by the second character. Internal headers
are special. They can be used to hide certain headers. They are
only extracted if requested. You can use them to document internal
functions, classes, etc. that you do not want clients to see,
creating what might be a programmer's manual as opposed to a
user's manual.</p><p>So <tt>/****if* Module/func1</tt> defines an
internal function called <tt>func1</tt>.
</p><p>Headers marked internal are by default not included in the
generated documentation. If you want to include them use the
option <tt>--internal</tt>. You can also generate the
documentation from only the internal headers with the option
<tt>--internalonly</tt>.
</p><p>You can define your own headertypes using the ROBODoc
configuration file, <tt>robodoc.rc</tt>.
See <a href="#customizing">Customizing ROBODoc</a>.
This way you can document anything you like, for instance makefile
entries, system tests, or exceptions.
</p></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2750297"></a>Items</h3></div></div><p> By default ROBODoc recognizes the following items: </p><div class="itemizedlist"><ul type="disc"><li> NAME -- Item name plus a short description. </li><li> COPYRIGHT -- Who own the copyright : "(c) <year>-<year> by
<company/person>" </li><li> SYNOPSIS, USAGE -- How to use it. </li><li> FUNCTION, DESCRIPTION, PURPOSE -- What does it do. </li><li> AUTHOR -- Who wrote it. </li><li> CREATION DATE -- When did the work start. </li><li> MODIFICATION HISTORY, HISTORY -- Who has done which changes and when. </li><li> INPUTS, ARGUMENTS, OPTIONS, PARAMETERS, SWITCHES -- What can we feed into it. </li><li> OUTPUT, SIDE EFFECTS -- What output is made. </li><li> RESULT, RETURN VALUE -- What do we get returned. </li><li> EXAMPLE -- A clear example of the items use. </li><li> NOTES -- Any annotations </li><li> DIAGNOSTICS -- Diagnostic output </li><li> WARNINGS, ERRORS -- Warning and error-messages. </li><li> BUGS -- Known bugs. </li><li> TODO, IDEAS -- What to implement next and ideas. </li><li> PORTABILITY -- Where does it come from, where will it work. </li><li> SEE ALSO -- References to other functions, man pages, other documentation. </li><li> METHODS, NEW METHODS -- OOP methods. </li><li> ATTRIBUTES, NEW ATTRIBUTES -- OOP attributes </li><li> TAGS -- Tag-item description. </li><li> COMMANDS -- Command description. </li><li> DERIVED FROM -- OOP super class. </li><li> DERIVED BY -- OOP sub class. </li><li> USES, CHILDREN -- What modules are used by this one. </li><li> USED BY, PARENTS -- Which modules do use this one. </li><li> SOURCE -- Source code inclusion. </li></ul></div><p>You can define your own items using the ROBODoc
configuration file, <tt>robodoc.rc</tt>. See <a href="#customizing">Customizing ROBODoc</a>. </p></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="sections"></a>Sections</h3></div></div><p>The structure of source code for an project is usually
hierarchical. A project might consists of several applications,
an application of several modules, a module of several functions
or even submodules. ROBODoc allows you to show this hierarchy in
your documentation. For this you specify the hierarchy in the
header name. For instance, you have a project that is going to
create a new language called D. The D Language project might
consists of three applications: a preprocessor, a compiler, and a
linker. The compiler consists of two modules, a parser and a
generator. The parser module consists of several
functions.</p><p>The following three headers show how this hierarchy can be
defined in the header name.</p><pre class="screen">
#****h* D-Language/Compiler
# FUNCTION
# The compiler takes a preprocessed source file and
# turns it into an object file.
#***
</pre><pre class="screen">
#****h* D-Language/Linker
# FUNCTION
# The linker module contains functions that scan a
# object file and build the executable.
#***
</pre><pre class="screen">
#****h* Compiler/Parser
# FUNCTION
# The parser module contains functions that scan a
# preprocessed source file and build the syntax tree.
#***
</pre><pre class="screen">
#****f* Parser/ReadToken
# FUNCTION
# ReadToken reads the next token from the input
# file.
#***
</pre><p>When you generate documentation with the option
<tt>--section</tt>, ROBODoc uses the hierarchical
information when generating the table of content and document
section information. For instance in HTML sections are started
with <H1>, <H2>, <H3> depending on the level
in the hierarchy. The table of will also contain levels. The
table of contents for the above example will be: </p><pre class="screen">
1. D-Language/Compiler
1.1 Compiler/Parser
1.1.1 Parser/ReadToken
2. D-Language/Linker
</pre></div></div><div class="section"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="id2750418"></a>Extracting Documentation with ROBODoc</h2></div></div><p>Now that you have prepared your source code for use with
ROBODoc you are ready to extract the documentation. There are
several choices to be made.</p><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2750434"></a>Single document or many smaller documents</h3></div></div><p>First of all, ROBODoc can be used in three modes.</p><div class="itemizedlist"><ul type="disc"><li>multidoc -- in this mode ROBODoc scans
all the source files in your source directory and creates a
separate document file for each of these in a document directory.
The document directory is created automatically. Its structure is
a mirror of the structure of your source directory.</li><li>singledoc -- in this mode ROBODoc scans all the source
files in your source directory and creates a single documentation
file that contains all the documentation extracted from your
source files. </li><li>singlefile -- in this mode ROBODoc scans a single source
file and creates a single documentation file.</li></ul></div></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2750479"></a>multidoc</h3></div></div><p>The multidoc mode is useful to create browsable documents.
For instance many small HTML files that can be viewed with a
web-browser. This mode requires the following arguments:</p><div class="cmdsynopsis"><p><tt>robodoc</tt> {--src <i><tt>source directory</tt></i>} {--doc <i><tt>document directory</tt></i>} {--multidoc} [other options]</p></div><p>An additional option that is useful with this mode is
<tt>--index</tt>, this creates a series of index files,
one for each header type.</p></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2750553"></a>singledoc</h3></div></div><p> The singledoc mode is useful to create bulk documentation
that can be incorporated in other documents, or that can be
delivered to a client as a single document. For instance a file
created in RTF format can be included into a larger design
document written in Word format. This mode requires the following
arguments:</p><div class="cmdsynopsis"><p><tt>robodoc</tt> {--src <i><tt>source directory</tt></i>} {--doc <i><tt>document file without extension</tt></i>} {--singledoc} [other options]</p></div><p>An additional option that is useful with this mode is
<tt>--sections</tt>, this causes the headers to follow a
section layout based on the module element hierarchy defined in the
header name.</p></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2750637"></a>singlefile</h3></div></div><p>The singlefile mode is not very useful. It is mainly used
for debugging purposes. This mode requires the following
arguments:</p><div class="cmdsynopsis"><p><tt>robodoc</tt> {--src <i><tt>source file</tt></i>} {--doc <i><tt>document file</tt></i>} {--singlefile} [other options]</p></div></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2750702"></a>Output formats</h3></div></div><p>Your next choice is the output format. ROBODoc can create
documentation in several formats:</p><div class="itemizedlist"><ul type="disc"><li>HTML, option <tt>--html</tt></li><li>RTF, option <tt>--rtf</tt></li><li>LaTeX, option <tt>--latex</tt></li><li>XML DocBook, option <tt>--dbxml</tt></li></ul></div><p>What format to use depends on your wishes. If you want a
single printable document, use LaTeX or XML DocBook. If you want
a document that can be included into a larger (Word) document use
RTF. If you want something that is browsable use HTML, or use XML
DocBook and then convert it to HTML.</p></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2750766"></a>Options</h3></div></div><p>The behavior of ROBODoc can be further fine-tune with a large number of
options.</p><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2750778"></a>-c</h4></div></div><p>Show the copyright message.</p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2750789"></a>--cmode</h4></div></div><p>Use ANSI C grammar in SOURCE items and use this
for some syntax highlighting (HTML only).</p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2750803"></a>--css</h4></div></div><p> Use to content of the specified file to create the
<tt>robodoc.css</tt>. The content of the file is
copied into <tt>robodoc.css</tt>. </p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2750824"></a>--dbxml</h4></div></div><p>Generate documentation in XML DocBook format.</p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2750837"></a>--doc</h4></div></div><p>Define the path to the documentation directory or
documentation file. A path can start with
<tt>./</tt> or <tt>/</tt>. Do not use
<tt>..</tt> in the path. The documentation
directory can be a subdirectory of the source directory,
or be parallel to the source directory,
however they can not be equal. So
<b>--src ./sources</b>
together with
<b>--doc ./documents</b>
is fine,
but
<b>--src ./Everything</b>
together with
<b>--doc ./Everything</b>
is not.
</p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2750878"></a>--folds</h4></div></div><p>Use fold marks to split a big document into smaller ones.</p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2750891"></a>--html</h4></div></div><p>Generate documentation in HTML format.</p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2750903"></a>--internal</h4></div></div><p>Also include headers marked internal.</p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2750915"></a>--internalonly</h4></div></div><p>Only include headers marked internal.</p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2750927"></a>--index</h4></div></div><p>Also create a master index file.</p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2750940"></a>--lock</h4></div></div><p> Per source file robodoc locks on the first headermarker
it finds and will recognize only that particular headermarker
for the remaining part of the file. In addition it locks on
the first remark marker in each header and will recognize only
that particular remark marker for the remaining part of the
header. </p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2750511"></a>--multidoc</h4></div></div><p>Generate one document per source file, and copy the
directory hierarchy.</p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2750592"></a>--nosource</h4></div></div><p>Do not include the SOURCE items.</p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2750671"></a>--nodesc</h4></div></div><p>Do not scan any subdirectories, scan only the top level
directory of the source tree.</p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2750982"></a>--rc</h4></div></div><p>Use the specified file instead of <tt>robodoc.rc</tt>.
</p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2750994"></a>--rtf</h4></div></div><p>Generate documentation in RTF format.</p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2751004"></a>--sections</h4></div></div><p>Create sections based on the module hierarchy.</p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2751014"></a>--singledoc</h4></div></div><p> Define the documentation directory or documentation
file.</p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2751024"></a>--singlefile</h4></div></div><p> Generate a single document from a single file </p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2751033"></a>--src</h4></div></div><p> Define the path for the source directory or source
file. The path can start with <tt>./</tt> or
<tt>/</tt>. Do not use <tt>..</tt> in the
path. </p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2751053"></a>--tabsize</h4></div></div><p>Lets you specify the tabsize.</p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2751063"></a>--toc</h4></div></div><p>Add a table of contents. This works in multidoc mode as
well as singledoc mode.</p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2751073"></a>--latex</h4></div></div><p>Generate documentation in LaTeX format.</p></div><div class="section"><div class="titlepage"><div><h4 class="title"><a name="id2751084"></a>--tell</h4></div></div><p>ROBODoc tells you what steps it is taking.</p></div></div></div><div class="section"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="customizing"></a>Customizing ROBODoc</h2></div></div><p> ROBODoc can be configured with a configuration file called
<tt>robodoc.rc</tt>. With it you can define item
names, frequently used options, and translations for English
terms. An example is shown below.
</p><pre class="programlisting">
# Example robodoc.rc
#
items:
NAME
SYNOPSIS
INPUTS
OUTPUTS
SIDE EFFECTS
HISTORY
BUGS
ignore items:
HISTORY
BUGS
options:
--src ./source
--doc ./doc
--html
--multidoc
--index
--tabsize 8
headertypes:
e "Makefile Entries" robo_mk_entries
x "System Tests" robo_syst_tests
q Queries robo_queries
ignore files:
README
CVS
*.bak
*~
test_*
</pre><p>The configuration file consists of a number of blocks.
Each block starts with a name followed by a
<tt>:</tt>. There are currently four blocks:
items, ignore items, options, header types, and ignore files.
In each block you define a number of values. Each value must
start with at least one space.
</p><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2751158"></a>items block</h3></div></div><p>In this block you can define the names of items that
ROBODoc should recognize. Item names can consist of more than
one word but should be written in all uppercase characters.
Define one item name per line. You do not need to put quotes
around them if they contain spaces.
</p><p>If you do not define an items block ROBODoc uses its
default list of item names. If you define an items block
ROBODoc uses only those item names, any of the default items names
(except SOURCE) are no longer recognized.</p></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2751183"></a>ignore items block</h3></div></div><p>In this block you can define the names of items that
ROBODoc should ignore when generating documentation.
This can be useful if you want to create documentation
for a client, but for instance do not want to include
the history items and bugs items.</p></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2751200"></a>options block</h3></div></div><p>In this block you can define frequently used options.
The options you specify here are added to any options you
specify on the command line.</p></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2751214"></a>headertypes block</h3></div></div><p>In this block you can define your own headertypes.
These are added to the existing headertypes. Each new
headertype requires three parameters: the character used to
indicate a header of this type, the title for this type as
used in the master index, the name of the file in which the
index this type is stored. If you use a character of an
existing headertype, this headertype is overwritten.
</p></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2751234"></a>ignore files block</h3></div></div><p>In this block you can define the names of files or
directories that ROBODoc should ignore while scanning
the directory tree for source files. You can use the
wildcard symbols <tt>*</tt> and
<tt>?</tt>.
</p><p> For instance, the example rc file above causes ROBODoc
to skip all <tt>README</tt> files, all files with
the name <tt>CVS</tt> (these are usually
directories). It also skips all files with a name that ends
with <tt>.bak</tt> or <tt>~</tt> or
that start with <tt>test_</tt> </p></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2751286"></a>Configuration file location</h3></div></div><p>ROBODoc searches the your current directory for the
<tt>robodoc.rc</tt> file. With the
<tt>--rc</tt> option can tell ROBODoc to use a different
file then <tt>robodoc.rc</tt> as configuration file.
The is handy if you want to create documentation in different
formats. For instance: </p><pre class="programlisting">
robodoc --rc htmlsingle.rc
robodoc --rc rtfsingle.rc
robodoc --rc htmlmulti.rc
</pre></div></div><div class="section"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="id2751326"></a>Examples</h2></div></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2751332"></a>HTML Example</h3></div></div><p> For this you need a web browser, say mozilla. You can try
this in the robodoc root directory. It creates a document called
<tt>HDocs/masterindex.html</tt> plus a lot of smaller
documents from all the source files in the directory
<tt>Source</tt>.</p><pre class="programlisting">
robodoc --src ./Source --doc ./HDocs --multidoc --index --html
</pre></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2751362"></a>RTF Example</h3></div></div><p>For this you need an rtf reader, for instance
<b>Word</b>. You can try this in the robodoc root
directory.</p><pre class="programlisting">
robodoc --src ./Source --doc api --singledoc --rtf --sections
</pre><p>This will create a document called
<tt>api.rtf</tt>.</p><p>By default the document looks pretty plain. There is no
chapter numbering or a table of contents, even if you asked for
it. All the information for this is included but not visible.
This is because chapter numbering and a table of contents are
generated by Word based on formatting information that is part of
a Word document but not part of a RTF document. </p><p>To make it visible you include the generated document into a
bigger document with the right formatting options. This is best
done with a cut-and-paste operation. Use the cut-past-paste
special menu, and paste it as RTF formatted text into your Word
document.</p></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2751416"></a>LaTeX Example</h3></div></div><p> For this you need <b>latex</b> and
<b>makeindex</b>. You can try this in the robodoc root
directory. It creates a single document called
<tt>api.dvi</tt> from all the source files in the
directory Source.</p><pre class="programlisting">
robodoc --src ./Source --doc api --singledoc --latex --sections
latex api.tex
latex api.tex
makeindex api.idx
latex api.tex
xdvi api.dvi
</pre></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2751450"></a>XML DocBook Example</h3></div></div><p> For this you need <b>xmlto</b> You can try this
in the robodoc root directory. It creates a single document called
<tt>api.xml</tt> from all the source files in the
directory Source. The <b>xmlto</b> then creates
a browsable HTML document from this.</p><pre class="programlisting">
robodoc --src ./Source --doc api --singledoc --dbxml --sections
xmlto html api.xml
</pre><p>To create a PDF document use:</p><pre class="programlisting">
xmlto pdf api.xml
</pre></div></div><div class="section"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="id2751495"></a>Tips and Tricks</h2></div></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2751502"></a>Using ROBODoc under Windows</h3></div></div><p>When you use ROBODoc under windows, don't forget that it is
a command line tool. ROBODoc relies on the console window to
inform you about problems and errors.</p><p>An easy mistake to make it to create a shortcut to
<tt>robodoc.exe</tt> and then click on the icon to
generate the documentation each time you made some changes to your
source code. If you have a fast machine a console window pops up
quickly and after that your documentation is ready.</p><p>This works very fine until you make a mistake in one of your
headers. The console window still pops up, but before you have a chance
to read any of the error messages it is gone again. Most likely
you won't even have noticed there were error messages. You will
end up with empty documentation or old documentation. </p><p>Better is to create a batch file with the following commands
and to store all the options in a <tt>robodoc.rc</tt>
file:</p><pre class="programlisting">
robodoc.exe
pause
</pre><p>Now the console window stays open and you have the
opportunity to read the error messages.</p><p>While the window is open, right click on the title bar,
go to properties->layout and set the buffer size to something
like 2500. That way you can scroll back too the next time
you run it.</p></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2751570"></a>The SOURCE Item</h3></div></div><p> With a little extra work you can include part of your
source code into your documentation to. The following example
shows how this is done:</p><pre class="programlisting">
/****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><p>You add a SOURCE item as the last item of your header. Then
instead of closing your header with an end marker, you close it
normally. The end marker is instead placed at the end of the
fragment of source code that you want to include. </p><p>SOURCE items are included by default. If want to create a
document without the SOURCE items use the option
<tt>--nosource</tt>.</p></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2751624"></a>Advanced formating with raw HTML and LaTeX code</h3></div></div><p> By default an item's body shows up in your documentation in
the same way as it is formatted in your source code. All special
characters for the output mode are escaped. For instance an <
is translated to a &lt; in HTML mode. Sometimes however you
like to have some more control of what goes into the
documentation. This is possible with the piping. If a line of
your item's body starts with on of the special piping markers, the
text after this marker is copied verbatim into your documentation.
The following example shows how this is done, and how to add
equations to your documentation.
</p><pre class="programlisting">
/****m* pipe/pipetest
* NAME
* pipetest
* NAME
* Simple header to show "piping" features in items.
* EXAMPLE
* Only "pipes" which match selected output style are picked up.
* |html <CENTER>This will be included in <B>HTML</B> output.</CENTER>
* |latex \centerline{This will be included in \LaTeX output}
* Space is mandatory following the pipe marker. The following is not a
* valid pipe marker:
* |html<B>Moi!</B>
* You should see an equation on the following line:
* |html y = x^2 (sorry, plain HTML is not very powerful)
* |latex \centerline{$y = x^2$}
* How does this look like?
* Here comes a multi-line equation array:
* |latex \begin{eqnarray}
* |latex \frac{\partial u}{\partial \tau} & = & D_u {\nabla}^2 u +
* |latex \frac{1}{\epsilon}
* |latex \left ( \hat{u}-{\hat{u}}^2-f\, {v} \, \frac{\hat{u}-q}{\hat{u}+q}
* |latex \right ) \; , \label{diffspot:1} \\
* |latex \frac{\partial v}{\partial \tau} & = & \hat{u}-v \; ,
* |latex \label{diffspot:2} \\
* |latex \frac{\partial r}{\partial \tau} & = & D_r {\nabla}^2 r \; .
* |latex \label{diffspAot:3}
* |latex \end{eqnarray}
* |html <I>TODO: write this in html</I>
* End of the example.
******
*/
</pre></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2751718"></a>Linking to external documents (href, file, mailto, images)</h3></div></div><p> In HTML mode ROBODoc recognizes the following links to
external documents. </p><div class="itemizedlist"><ul type="disc"><li><tt>href:body</tt> -- This is replaced with
<tt><a href="body">body</A></tt></li><li><tt>file:/body</tt> -- This is replaced with
<tt><a href="file:/body">file:/body</A></tt></li><li><tt>mailto:body</tt> -- This is replaced with
<tt><a href="mailto:body">body</A></tt></li><li><tt>http://body</tt> -- This is replaced with
<tt><a href="http://body">http://body</A></tt></li><li><tt>image:body</tt> -- This is replaced with
<tt><image src="body"></tt></li></ul></div></div><div class="section"><div class="titlepage"><div><h3 class="title"><a name="id2751804"></a>Linking from an external document.</h3></div></div><p>To link from an external document to one of the HTML
documents generated by ROBODoc you need a label. ROBODoc creates
two labels for each header. The first one starts with
<tt>robo</tt> followed by a number. You can not use
this one because the numbers will change each time you run
ROBODoc. The second label is an escaped version of the whole
header name. In this label all the non alphanumeric characters of
the name are replaced by their two digit hexadecimal code.</p><p>An example, if your header name is
<tt>Analyser/RB_ToBeAdded</tt> the label is
<tt>Analyser2fRB5fToBeAdded</tt>. Here
<tt>/</tt> was replaced by <tt>2f</tt> and
<tt>_</tt> was replaced by <tt>5f</tt>. As
long as you do not change the header name, this label stays the
same each time you run ROBODoc.</p></div></div><div class="section"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="id2751873"></a>Suggestions and Bugs</h2></div></div><p>If you find any bugs, catch them, put them in a jar, and
send them to: rfsber {at} xs4all.nl. Suggestions are also welcome at
this address. Flames can be directed to the sun.</p></div></div></body></html>
|
