util/robodoc/Docs/robodoc.1

   1 .de EX          \"Begin example
   2 .ne 5
   3 .if n .sp 1
   4 .if t .sp .5
   5 .nf
   6 .in +.5i
   7 ..
   8 .de EE
   9 .fi
  10 .in -.5i
  11 .if n .sp 1
  12 .if t .sp .5
  13 ..
  14
  15 .TH ROBODoc 1 "V3.2.1 June 1999"
  16
  17 .SH NAME
  18
  19 ROBODoc - Extract documentation from source code.
  20
  21 .SH SYNOPSIS
  22 .B robodoc
  23 .I source-file
  24 .I documentation-file
  25 .B [options]
  26
  27 .SH DESCRIPTION
  28
  29 ROBODoc extracts specially formated documentation from the source code.
  30 It allows you to maintain a program and its documentation in a single
  31 file.
  32
  33 .SH OPTIONS
  34
  35 .IP ASCII
  36 Generate documentation in ASCII format.
  37
  38 .IP -c
  39 Show warranty and copyright statement.
  40
  41 .IP C
  42 Use ANSI C grammar in source items (experimental, HTML only).
  43
  44 .IP FOLD
  45 Enable folding if HTML output is selected (experimental).
  46
  47 .IP "GENXREF xreffile"
  48 Generate a xreffile.
  49
  50 .IP GUIDE
  51 Generate documentation in Amiga Guide format.
  52
  53 .IP HTML
  54 Generate documentation in HTML format.
  55
  56 .IP INDEX
  57 Create a master index file. In this case call robodoc as
  58 robodoc <xrefsfile> <master index file> INDEX
  59
  60 .IP INTERNAL
  61 Also include headers that are marked internal.
  62
  63 .IP INTERNALONLY
  64 Only extract the headers that are marked internal (that start with ****i*).
  65
  66 .IP NOSOURCE
  67 Do not include the source items in the documentation.
  68
  69 .IP LATEX
  70 Generate documentation in LaTeX format.
  71
  72 .IP RTF
  73 Generate documentation in RTF format.
  74
  75 .IP SINGLEDOC
  76 Do not create a document header and footer when creating
  77 documentation in LaTeX format.  This allows you to include
  78 the generated documents into big document or
  79 master index file.
  80
  81 .IP SORT
  82 Sort the headers alphabetically.
  83
  84 .IP "TABSIZE <n>"
  85 Convert each tab into n spaces.
  86
  87 .IP TITLE
  88 Sets the title that is used for the master index file.
  89
  90 .IP TOC
  91 Generate a table of contents. Is only useful when you select ASCII as
  92 output mode. With all other output modes the Table of contents is
  93 generated anyway.
  94
  95 .IP -v
  96 Verbose mode, robodoc tells what it is doing.
  97
  98 .IP "XREF <xrefsfile>"
  99 Use the all xref files listed in the file xrefsfile to make
 100 cross links between documents.
 101
 102 The following abbreviations are also allowed: -s SORT, -t TOC, -x
 103 XREF, -g GENXREF, -i INTERNAL, -io INTERNALONLY, -ts TABSIZE.
 104
 105 .SH "ITEM NAMES SUPPORTED"
 106
 107 .IP NAME
 108 Item's name followed by --, then a short description.
 109
 110 .IP COPYRIGHT
 111 Who own the copyright.
 112
 113 .IP "SYNOPSIS, USAGE"
 114 How to use it.
 115
 116 .IP "FUNCTION, DESCRIPTION, PURPOSE"
 117 What does it do.
 118
 119 .IP AUTHOR
 120 Who wrote it.
 121
 122 .IP "CREATION DATE"
 123 When did the work start.
 124
 125 .IP "MODIFICATION HISTORY, HISTORY"
 126 Who has done which changes and when.
 127
 128 .IP "INPUTS, ARGUMENTS, OPTIONS, PARAMETERS, SWITCHES"
 129 What can we feed into it.
 130
 131 .IP "OUTPUT, SIDE EFFECTS"
 132 What output is made.
 133
 134 .IP "RESULT, RETURN VALUE"
 135 What do we get returned.
 136
 137 .IP "EXAMPLE"
 138 A clear example of the items use.
 139
 140 .IP "NOTES"
 141 Any annotations.
 142
 143 .IP "DIAGNOSTICS"
 144 Diagnostical output.
 145
 146 .IP "WARNINGS, ERRORS"
 147 Warning & error-messages.
 148
 149 .IP BUGS
 150 Known bugs.
 151
 152 .IP "TODO, IDEAS"
 153 What to implement next & ideas.
 154
 155 .IP PORTABILITY
 156 Where does it come from, where will it work.
 157
 158 .IP "SEE ALSO"
 159 References to other functions, man pages, other documentation.
 160
 161 .IP "METHODS, NEW METHODS"
 162 OOP methods.
 163
 164 .IP "ATTRIBUTES, NEW ATTRIBUTES"
 165 OOP attributes, could also be used for structures.
 166
 167 .IP TAGS
 168 Tagitem description.
 169
 170 .IP COMMANDS
 171 Command description.
 172
 173 .IP "DERIVED FROM"
 174 OOP super class.
 175
 176 .IP "DERIVED BY"
 177 OOP sub class.
 178
 179 .IP "USES, CHILDREN"
 180 What modules are used by this one.
 181
 182 .IP "USED BY, PARENTS"
 183 Which modules use this one.
 184
 185 .IP SOURCE
 186 Source code inclusion.
 187
 188 .SH "HEADER TYPES SUPPORTED"
 189
 190 .IP h
 191 Header that describes the project.
 192
 193
 194 .IP f
 195 Header for a function.
 196
 197 .IP s
 198 Header for a structure.
 199
 200 .IP c
 201 Header for a class.
 202
 203 .IP m
 204 Header for a method.
 205
 206 .IP v
 207 Header for a variable
 208
 209 .IP d
 210 Header for a constant (from define).
 211
 212 .IP i
 213 Internal header.
 214
 215 .IP *
 216 Generic header, for everything else.
 217
 218 .SH EXAMPLES
 219
 220 A simple example, you have one tcl source file and want to extract
 221 the documentation.
 222
 223 .EX
 224 robodoc wopr.tcl wopr.tcl.html HTML SORT
 225 .EE
 226
 227 Assume you have a program divided in two source files, gluify.c and
 228 gluify.h.  To generate the documentation for this program, complete
 229 with cross links, you would use:
 230
 231 .EX
 232 echo "gluify.c.xref" > gluify.xrefs
 233 echo "gluify.h.xref" >> gluify.xrefs
 234 robodoc gluify.c gluify.c.html HTML GENXREF gluify.c.xref
 235 robodoc gluify.h gluify.h.html HTML GENXREF gluify.h.xref
 236 robodoc gluify.c gluify.c.html HTML XREF gluify.xrefs
 237 robodoc gluify.h gluify.h.html HTML XREF gluify.xrefs
 238 .EE
 239
 240 .SH SEE ALSO
 241
 242 The documentation in HTML format that comes with ROBODoc.  Latest
 243 version can be found on http://www.xs4all.nl/~rfsber/Robo/ or on
 244 http://freshmeat.net/
 245
 246