Docs/configuration.xml

   1 <!-- $Id: configuration.xml,v 1.9 2007/05/11 08:16:44 thuffir Exp $ -->
   2
   3 <section id="customizing">
   4 <title id="customizing.title">Customizing ROBODoc</title>
   5
   6 <para> ROBODoc can be configured with a configuration file called
   7     <filename>robodoc.rc</filename>.  With it you can define item
   8     names, frequently used options, and translations for English
   9     terms. One should note that if a configuration file is specified,
  10     its definitions over-ride ROBODoc internal (i.e. built-in) settings.
  11     This is a feature; some arbitrary language may include syntax
  12     which conflicts with ROBODoc's internal markers. By taking advantage
  13     of a configuration file, these sort of issues and conflicts
  14     can be circumvented.  An example is shown below.
  15 </para>
  16
  17 <programlisting>
  18 # Example robodoc.rc
  19 #
  20 items:
  21     NAME
  22     FUNCTION
  23     SYNOPSIS
  24     INPUTS
  25     OUTPUTS
  26     SIDE EFFECTS
  27     HISTORY
  28     BUGS
  29     EXAMPLE
  30 ignore items:
  31     HISTORY
  32     BUGS
  33 item order:
  34     FUNCTION
  35     SYNOPSIS
  36     INPUTS
  37     OUTPUTS
  38 source items:
  39     SYNOPSIS
  40 preformatted items:
  41     INPUTS
  42     OUTPUTS
  43 format items:
  44     FUNCTION
  45     SIDE EFFECTS
  46 options:
  47     --src ./source
  48     --doc ./doc
  49     --html
  50     --multidoc
  51     --index
  52     --tabsize 8
  53 headertypes:
  54     J  "Projects"          robo_projects    2
  55     F  "Files"             robo_files       1
  56     e  "Makefile Entries"  robo_mk_entries
  57     x  "System Tests"      robo_syst_tests
  58     q  Queries             robo_queries
  59 ignore files:
  60     README
  61     CVS
  62     *.bak
  63     *~
  64     "a test_*"
  65 accept files:
  66     *.c
  67     *.h
  68     *.pl
  69 header markers:
  70     /****
  71     #****
  72 remark markers:
  73     *
  74     #
  75 end markers:
  76     ****
  77     #****
  78 header separate characters:
  79     ,
  80 header ignore characters:
  81     [
  82 remark begin markers:
  83     /*
  84 remark end markers:
  85     */
  86 source line comments:
  87     //
  88 keywords:
  89     if
  90     do
  91     while
  92     for
  93 </programlisting>
  94
  95 <para>The configuration file consists of a number of blocks.
  96     Each block starts with a name followed by a
  97     <literal>:</literal>.
  98     In each block you define a number of values.  Each value must
  99     start with at least one space.
 100 </para>
 101
 102 <section><title>items block</title>
 103     <para>In this block you can define the names of items that
 104         ROBODoc should recognize.  Item names can consist of more than
 105         one word but should be written in all uppercase characters.
 106         Define one item name per line.  You do not need to put quotes
 107         around them if they contain spaces.
 108     </para>
 109
 110     <para>If you do not define an items block ROBODoc uses its
 111         default list of item names.  If you define an items block
 112         ROBODoc uses only those item names, any of the default items names
 113         (except SOURCE) are no longer recognized.</para>
 114 </section>
 115
 116 <section><title>ignore items block</title>
 117     <para>In this block you can define the names of items that
 118         ROBODoc should ignore when generating documentation.
 119         This can be useful if you want to create documentation
 120         for a client, but for instance do not want to include
 121         the history items and bugs items.</para>
 122 </section>
 123
 124 <section><title>item order block</title>
 125     <para>In this block you can define the order in which items
 126         are to appear in the generated documentation.
 127         The items listed here will appear in the given order in the
 128         generated documentation.  Any remaining items appear
 129         after these items in the order they were found in the header.
 130         This allows you to make the documentation look more uniform.
 131         </para>
 132 </section>
 133
 134 <section id="sourceitems">
 135 <title id="sourceitems.title">source items block</title>
 136     <para>In this block you can define the names of items that
 137         ROBODoc handles in the same way as the SOURCE item.
 138     </para>
 139 </section>
 140
 141 <section><title>preformatted items block</title>
 142   <para>
 143     In this block you can define the names of items that should be always
 144     preformatted. This is useful if you have the
 145     <option><xref linkend="nopre" endterm="nopre.term" /></option> option
 146     specified and want specific items (like input and output lists) to be
 147     automatically preformatted. See
 148     <xref linkend="formatting" endterm="formatting.title" /> for more
 149     information.
 150   </para>
 151 </section>
 152
 153 <section><title>format items block</title>
 154   <para>
 155     In this block you can define the names of items that should be formatted by
 156     the <xref linkend="formatting" endterm="formatting.title" /> feature
 157     (like function descriptions) even if the
 158     <option><xref linkend="nopre" endterm="nopre.term" /></option>
 159     option has not been specified.
 160   </para>
 161 </section>
 162
 163 <section><title>options block</title>
 164     <para>In this block you can define frequently used options.
 165         The options you specify here are added to any options you
 166         specify on the command line.</para>
 167     <para>
 168       See <xref linkend="options" endterm="options.title" />.
 169     </para>
 170 </section>
 171
 172 <section id="headertypes_block">
 173 <title id="headertypes_block.title">headertypes block</title>
 174     <para>In this block you can define your own header types.
 175         These are added to the existing header types.  Each new
 176         header type requires three parameters: the character used to
 177         indicate a header of this type, the title for this type as
 178         used in the master index and the name of the file in which the
 179         index of this type is stored.  If you use a character of an
 180         existing header type, this header type is overwritten.
 181     </para>
 182     <para>
 183         Additionally the sorting priority can also be specified for each header
 184         type. Headers with higher priority will appear earlier in the
 185         generated output. (For example you can make module definitions appear
 186         at the beginning of a page.) If this parameter is omitted, the header
 187         will have the priority 0 (lowest) by default. All pre-defined header
 188         types have zero priority, except
 189         "<xref linkend="header_type_h" endterm="header_type_h" />",
 190         which has the sorting priority 1.
 191         See <xref linkend="header_types" endterm="header_types.title" />.
 192     </para>
 193 </section>
 194
 195 <section><title>ignore files block</title>
 196     <para>In this block you can define the names of files or
 197         directories that ROBODoc should ignore while scanning
 198         the directory tree for source files.  You can use the
 199         wildcard symbols <literal>*</literal> and
 200         <literal>?</literal>.  If you use spaces in the expression
 201         enclose the expression in quotes.
 202     </para>
 203
 204     <para> For instance, the rc file above causes ROBODoc
 205         to skip all <filename>README</filename> files, all files with
 206         the name <filename>CVS</filename> (these are usually
 207         directories).  It also skips all files with a name that ends
 208         with <filename>.bak</filename> or <filename>~</filename> or
 209         that start with <filename>a test_</filename> </para>
 210
 211     <para>Normally you specify the names of directories here
 212         and do the filtering of file names with a accept files block.
 213     </para>
 214 </section>
 215
 216 <section><title>accept files block</title>
 217     <para>In this block you can define the names of files that
 218         robodoc should accept. This test is carried out after the
 219         'ignore files' filtering is performed.  Any files that do
 220         not match the patterns in this block are ignored by ROBODoc.
 221     </para>
 222
 223     <para>
 224         If there is no accept files block all files are accepted.
 225     </para>
 226 </section>
 227
 228 <section><title>header markers block</title>
 229     <para>
 230         In this block you define what ROBODoc will recognize
 231         as start of a header.  If you use this block ROBODoc only
 232         recognizes these markers, any of the inbuilt markers will
 233         be ignored.
 234     </para>
 235 </section>
 236
 237 <section><title>remark markers block</title>
 238     <para>
 239         In this block you define what ROBODoc will recognize
 240         as start of remark.  If you use this block ROBODoc only
 241         recognizes these markers, any of the inbuilt markers will
 242         be ignored.
 243     </para>
 244 </section>
 245
 246 <section><title>end markers block</title>
 247     <para>
 248         In this block you define what ROBODoc will recognize
 249         as end of a header.  If you use this block ROBODoc only
 250         recognizes these markers, any of the inbuilt markers will
 251         be ignored.
 252     </para>
 253 </section>
 254
 255 <section id="separate_characters_block">
 256 <title id="separate_characters_block.title">header separate characters block</title>
 257   <para>
 258     In this block you can specify the separation character(s) for multiple
 259     header names. The default character is "<literal>,</literal>" (comma) if
 260     this block is missing. See
 261     <xref linkend="preparing" endterm="preparing.title" />
 262     for more information.
 263   </para>
 264 </section>
 265
 266 <section id="header_ignore_characters_block">
 267 <title id="header_ignore_characters_block.title">header ignore characters block</title>
 268   <para>
 269     In this block you can specify character(s) where the evaluation of a header
 270     should stop. The default character is "<literal>[</literal>" if this block
 271     is missing. This is useful to supply additional information to the header
 272     that ROBODoc should not care about.
 273   </para>
 274   <para>
 275     For example one can include the version number of the function:
 276 <programlisting>
 277   ****f* financial.library/StealMoney [2.0]
 278 </programlisting>
 279   </para>
 280 </section>
 281
 282 <section id="remark_begin_end"><title id="remark_begin_end.title">
 283 remark begin markers and remark end markers block</title>
 284     <para>
 285         Some languages allow remarks to span more than one line. They
 286         start a remark with a begin marker and end it with another
 287         marker.  For instance in C you can have:
 288     </para>
 289 <programlisting>
 290    /* This is a
 291       multi-line remark.
 292     */
 293 </programlisting>
 294     <para>
 295         Here the markers are <literal>/*</literal> and <literal>*/</literal>.
 296         If you tell ROBODoc what these markers are in a remark begin
 297         markers block and remark end markers block. ROBODoc can skip
 298         them in source items.</para>
 299
 300         <para>We illustrate this with an example. Say we have a language
 301         that start a remark with <literal>|*</literal> and
 302         <literal>*|</literal>.  We define <literal>SYNOPSIS</literal>
 303         to be a source like item.  If we now run ROBODoc on the
 304         without a remark begin markers and
 305         end markers block on the following piece of source, </para>
 306
 307 <programlisting>
 308 |****f* Bar/foo
 309  * FUNCTION
 310  *   foo computes the foo factor.
 311  * SYNOPSIS
 312  *|
 313 int foo( float correction )
 314 |*
 315  * BUGS
 316  *   None
 317  * SOURCE
 318  *|  .
 319 {
 320     return correction * 42.0;
 321 }
 322 |*****|
 323 </programlisting>
 324
 325 <para>the extracted documentation will look like:</para>
 326
 327 <literallayout class="monospaced">
 328  FUNCTION
 329    foo computes the foo factor.
 330  SYNOPSIS
 331    *|
 332    int foo( float correction )
 333    |*
 334  BUGS
 335    None
 336  SOURCE
 337    *|  .
 338    {
 339       return correction * 42.0;
 340    }
 341 </literallayout>
 342
 343 <para>because ROBODoc considers
 344     <literal>|*</literal> and <literal>*|</literal>.to be part of the
 345     source, and not part of the begin or end of a header.</para>
 346
 347 <para> If you add</para>
 348 <programlisting>
 349 remark begin markers:
 350        |*
 351 remark end markers:
 352        *|
 353 </programlisting>
 354 <para>the output will look like:</para>
 355 <literallayout class="monospaced">
 356  FUNCTION
 357    foo computes the foo factor.
 358  SYNOPSIS
 359    int foo( float correction )
 360  BUGS
 361    None
 362  SOURCE
 363    {
 364       return correction * 42.0;
 365    }
 366 </literallayout>
 367
 368 <para>
 369     These markers will also be used to highlight block comments if the
 370     <option>
 371       <xref linkend="syntaxcolors_enable" endterm="syntaxcolors_enable.term" />
 372       <xref linkend="syntaxcolors_enable_block_comments" endterm="syntaxcolors_enable_block_comments.option" />
 373     </option>
 374     option (or the
 375     <option>
 376       <xref linkend="syntaxcolors" endterm="syntaxcolors.term" />
 377     </option>
 378     option) is specified (Similar to
 379     <xref linkend="linecomments" endterm="linecomments.title" />).
 380 </para>
 381
 382 </section>
 383
 384 <section id="linecomments"><title id="linecomments.title">source line comments block</title>
 385     <para>
 386         Here you can specify markers which start whole line comments.
 387         (Comments that span until the end of line like "<literal>//</literal>",
 388         "<literal>REM</literal>", "<literal>;</literal>", etc...)
 389         These lines will be highlighted in the generated <literal>HTML</literal>
 390         output if the
 391         <option>
 392           <xref linkend="syntaxcolors_enable" endterm="syntaxcolors_enable.term" />
 393           <xref linkend="syntaxcolors_enable_line_comments" endterm="syntaxcolors_enable_line_comments.option" />
 394         </option>
 395         option (or the
 396         <option>
 397           <xref linkend="syntaxcolors" endterm="syntaxcolors.term" />
 398         </option>
 399         option) has been specified.</para>
 400     <para>
 401         You don't need this if you have the
 402         <option>
 403           <xref linkend="cmode" endterm="cmode.term" />
 404         </option>
 405         option specified.
 406     </para>
 407     <para>
 408         The default highlighting color can be changed in the <literal>CSS</literal>
 409         file (<literal>span.comment</literal>).
 410     </para>
 411 </section>
 412
 413 <section id="keywords"><title id="keywords.title">keywords block</title>
 414     <para>
 415         Here you can specify the keywords in your <literal>SOURCE</literal> items.
 416         These keywords will be highlighted in the generated <literal>HTML</literal>
 417         output if the
 418         <option>
 419           <xref linkend="syntaxcolors_enable" endterm="syntaxcolors_enable.term" />
 420           <xref linkend="syntaxcolors_enable_keywords" endterm="syntaxcolors_enable_keywords.option" />
 421         </option>
 422         option (or the
 423         <option>
 424           <xref linkend="syntaxcolors" endterm="syntaxcolors.term" />
 425         </option>
 426         option) has been specified. Keywords meant to be the language native ones
 427         (<literal>for</literal>, <literal>if</literal>, etc...).
 428     </para>
 429     <para>
 430         You don't need this if you have the
 431         <option>
 432           <xref linkend="cmode" endterm="cmode.term" />
 433         </option>
 434         option specified.
 435     </para>
 436     <para>
 437         The default highlighting color can be changed in the <literal>CSS</literal>
 438         file (<literal>span.keyword</literal>).
 439     </para>
 440 </section>
 441
 442     <section><title>Configuration file location</title>
 443
 444     <para>ROBODoc searches the your current directory for the
 445     <filename>robodoc.rc</filename> file. If it can't find
 446     it there it will search in <literal>$HOME/</literal>, then
 447     <filename>$HOMEDRIVE$HOMEPATH/</filename>, and finally in
 448     <filename>/usr/share/robodoc/</filename>.</para>
 449
 450     <para>With the <option>--rc</option> option you can tell ROBODoc to
 451     use a different file than <filename>robodoc.rc</filename> as
 452     configuration file.  This is handy if you want to create
 453     documentation in different formats.  For instance: </para>
 454
 455 <programlisting>
 456 robodoc --rc  htmlsingle.rc
 457 robodoc --rc  rtfsingle.rc
 458 robodoc --rc  htmlmulti.rc
 459 </programlisting>
 460
 461     </section>
 462
 463 </section>
 464