Docs/tips.xml

   1 <section>
   2 <title>Tips and Tricks</title>
   3
   4 <section>
   5 <title>The SOURCE Item</title>
   6
   7     <para> With a little extra work you can include part of your
   8     source code into your documentation too.  The following example
   9     shows how this is done:</para>
  10
  11 <programlisting>
  12 /****f* Robodoc/RB_Panic [2.0d]
  13  * NAME
  14  *   RB_Panic - Shout panic, free resources, and shut down.
  15  * SYNOPSIS
  16  *   RB_Panic (cause, add_info)
  17  *   RB_Panic (char *, char *)
  18  * FUNCTION
  19  *   Prints an error message.
  20  *   Frees all resources used by robodoc.
  21  *   Terminates program.
  22  * INPUTS
  23  *   cause    - pointer to a string which describes the
  24  *              cause of the error.
  25  *   add_info - pointer to a string with additional information.
  26  * SEE ALSO
  27  *   RB_Close_The_Shop ()
  28  * SOURCE
  29  */
  30
  31   void RB_Panic (char *cause, char *add_info)
  32   {
  33     printf ("Robodoc: Error, %s\n",cause) ;
  34     printf ("         %s\n", add_info) ;
  35     printf ("Robodoc: Panic Fatal error, closing down..\n") ;
  36     RB_Close_The_Shop () ; /* Free All Resources */
  37     exit(100) ;
  38   }
  39
  40 /*******/
  41 </programlisting>
  42
  43 <para>You can add a SOURCE item as the last item of your header. Then
  44     instead of closing your header with an end marker, you close it
  45     normally.  The end marker is instead placed at the end of the
  46     fragment of source code that you want to include.  </para>
  47
  48 <para>SOURCE items are included by default.  If you want to create a
  49     document without the SOURCE items use the option
  50     <option>--nosource</option>.</para>
  51
  52 <para>You can also make normal items work like the source item,
  53     see <xref linkend="sourceitems" endterm="sourceitems.title" />.
  54 </para>
  55 </section>
  56
  57
  58 <section>
  59 <title>Minimizing Duplicate Information</title>
  60
  61 <para>It is always good to avoid having the same information in several different locations.
  62     It is easy to create headers that have a lot information duplication.  Take for instance
  63     the following header.
  64 </para>
  65
  66 <programlisting>
  67 /****f* Robodoc/RB_Panic [2.0d]
  68  * NAME
  69  *   RB_Panic - Shout panic, free resources, and shut down.
  70  * SYNOPSIS
  71  *   RB_Panic (cause, add_info)
  72  *   RB_Panic (char *, char *)
  73  * FUNCTION
  74  *   Prints an error message.
  75  *   Frees all resources used by robodoc.
  76  *   Terminates program.
  77  * INPUTS
  78  *   cause    - pointer to a string which describes the
  79  *              cause of the error.
  80  *   add_info - pointer to a string with additional information.
  81  * SEE ALSO
  82  *   RB_Close_The_Shop ()
  83  * SOURCE
  84  */
  85
  86   void RB_Panic (char *cause, char *add_info)
  87   {
  88     printf ("Robodoc: Error, %s\n",cause) ;
  89     printf ("         %s\n", add_info) ;
  90     printf ("Robodoc: Panic Fatal error, closing down..\n") ;
  91     RB_Close_The_Shop () ; /* Free All Resources */
  92     exit(100) ;
  93   }
  94
  95 /*******/
  96 </programlisting>
  97
  98 <para>
  99     The name <literal>RB_Panic</literal> occurs five times.  This is tedious to
 100     type and difficult to maintain.
 101     However with a the right <filename>robodoc.rc</filename> this can be changed
 102     to:
 103 </para>
 104
 105 <programlisting>
 106 /****f* Robodoc/RB_Panic [2.0d]
 107  * SUMMARY
 108  *   Shout panic, free resources, and shut down.
 109  * SYNOPSIS
 110  */
 111
 112 void RB_Panic (char* cause, char *add_info)
 113
 114 /*
 115  * FUNCTION
 116  *   Prints an error message.
 117  *   Frees all resources used by robodoc.
 118  *   Terminates program.
 119  * INPUTS
 120  *   cause    - pointer to a string which describes the
 121  *              cause of the error.
 122  *   add_info - pointer to a string with additional information.
 123  * SEE ALSO
 124  *   RB_Close_The_Shop ()
 125  * SOURCE
 126  */
 127   {
 128     printf ("Robodoc: Error, %s\n",cause) ;
 129     printf ("         %s\n", add_info) ;
 130     printf ("Robodoc: Panic Fatal error, closing down..\n") ;
 131     RB_Close_The_Shop () ; /* Free All Resources */
 132     exit(100) ;
 133   }
 134
 135 /*******/
 136 </programlisting>
 137
 138 <para><literal>RB_Panic</literal> occurs only twice now. In addition changes
 139 to the function definition only have to be done once.</para>
 140
 141 <para>The <filename>robodoc.rc</filename> required for this is: </para>
 142
 143 <programlisting>
 144 # robodoc.rc file
 145 items:
 146     SUMMARY
 147     SYNOPSIS
 148     INPUTS
 149     OUTPUTS
 150     SEE ALSO
 151     BUGS
 152 source items:
 153     SYNOPSIS
 154 remark begin markers:
 155     /*
 156 remark end markers:
 157     */
 158 </programlisting>
 159
 160 </section>
 161
 162 <!-- TODO explain about headers with more than one name -->
 163
 164 <section>
 165 <title>Advanced formatting with raw HTML and LaTeX code</title>
 166
 167     <para> By default an item's body shows up in your documentation in
 168     the same way as it is formatted in your source code.  All special
 169     characters for the output mode are escaped.  For instance an &lt;
 170     is translated to a &amp;lt; in HTML mode.  Sometimes however you
 171     like to have some more control of what goes into the
 172     documentation.  This is possible with the piping.  If a line of
 173     your item's body starts with one of the special piping markers, the
 174     text after this marker is copied verbatim into your documentation.
 175     The following example shows how this is done, and how to add
 176     equations to your documentation.
 177     </para>
 178
 179 <programlisting>
 180 /****m* pipe/pipetest
 181  * NAME
 182  *   pipetest
 183  * DESCRIPTION
 184  *   Simple header to show "piping" features in items.
 185  * EXAMPLE
 186  *   Only "pipes" which match selected output style are picked up.
 187  *   |html &lt;CENTER&gt;This will be included in &lt;B&gt;HTML&lt;/B&gt; output.&lt;/CENTER&gt;
 188  *   |latex \centerline{This will be included in \LaTeX output}
 189  *   Space is mandatory following the pipe marker. The following is not a
 190  *   valid pipe marker:
 191  *   |html&lt;B&gt;Moi!&lt;/B&gt;
 192  *   You should see an equation on the following line:
 193  *   |html y = x^2 (sorry, plain HTML is not very powerful)
 194  *   |latex \centerline{$y = x^2$}
 195  *   How does this look like?
 196  *   Here comes a multi-line equation array:
 197  *    |latex \begin{eqnarray}
 198  *    |latex \frac{\partial u}{\partial \tau} &amp; = &amp; D_u {\nabla}^2 u +
 199  *    |latex \frac{1}{\epsilon}
 200  *    |latex \left ( \hat{u}-{\hat{u}}^2-f\, {v} \, \frac{\hat{u}-q}{\hat{u}+q}
 201  *    |latex \right ) \; ,  \label{diffspot:1} \\
 202  *    |latex \frac{\partial v}{\partial \tau} &amp; = &amp; \hat{u}-v \; ,
 203  *    |latex \label{diffspot:2} \\
 204  *    |latex \frac{\partial r}{\partial \tau} &amp; = &amp; D_r {\nabla}^2 r \; .
 205  *    |latex \label{diffspAot:3}
 206  *    |latex \end{eqnarray}
 207  *    |html &lt;I&gt;TODO: write this in html&lt;/I&gt;
 208  *   End of the example.
 209  ******
 210  */
 211 </programlisting>
 212 </section>
 213
 214 <section>
 215 <title>Linking to external documents (href, file, mailto, images)</title>
 216
 217     <para> In HTML mode ROBODoc recognizes the following links to
 218     external documents.  </para>
 219
 220     <itemizedlist>
 221
 222     <listitem><para><literal>href:body</literal> -- This is replaced with
 223       <literal>&lt;a href="body"&gt;body&lt;/A&gt;</literal>
 224     </para></listitem>
 225
 226     <listitem><para><literal>file:/body</literal> -- This is replaced with
 227     <literal>&lt;a href="file:/body"&gt;file:/body&lt;/A&gt;</literal>
 228     </para></listitem>
 229
 230     <listitem><para><literal>mailto:body</literal> -- This is replaced with
 231     <literal>&lt;a href="mailto:body"&gt;body&lt;/A&gt;</literal>
 232     </para></listitem>
 233
 234     <listitem><para><literal>http://body</literal> -- This is replaced with
 235     <literal>&lt;a href="http://body"&gt;http://body&lt;/A&gt;</literal>
 236     </para></listitem>
 237
 238     <listitem><para><literal>image:body</literal> -- This is replaced with
 239     <literal>&lt;image src="body"&gt;</literal>
 240     </para></listitem>
 241
 242     </itemizedlist>
 243 </section>
 244
 245
 246 <section>
 247 <title>Linking from an external document</title>
 248
 249     <para>To link from an external document to one of the HTML
 250     documents generated by ROBODoc you need a label.  ROBODoc creates
 251     two labels for each header. The first one starts with
 252     <literal>robo</literal> followed by a number.  You can not use
 253     this one because the numbers will change each time you run
 254     ROBODoc.  The second label is an escaped version of the whole
 255     header name.  In this label all the non alphanumeric characters of
 256     the name are replaced by their two digit hexadecimal code.</para>
 257
 258     <para>An example, if your header name is
 259     <literal>Analyser/RB_ToBeAdded</literal> the label is
 260     <literal>Analyser2fRB5fToBeAdded</literal>.  Here
 261     <literal>/</literal> was replaced by <literal>2f</literal> and
 262     <literal>_</literal> was replaced by <literal>5f</literal>.  As
 263     long as you do not change the header name, this label stays the
 264     same each time you run ROBODoc.</para>
 265
 266 </section>
 267
 268 <section id="tools">
 269 <title id="tools.title">Using external tools</title>
 270     <para>
 271     You can also execute external tools from <literal>ROBODoc</literal> and even
 272     pass data to them.
 273     The output of these tools can be included in your documentation for instance.
 274     </para>
 275     <para>
 276     There are several types of external tools you can use:
 277     </para>
 278     <orderedlist>
 279     <listitem>Arbitrary tool with passing data through stdin</listitem>
 280     <listitem>Arbitrary tool without passing data through stdin</listitem>
 281     <listitem>The <literal>DOT</literal> tool</listitem>
 282     </orderedlist>
 283     <para>
 284     The following example shows how to use each of them.
 285     </para>
 286
 287 <programlisting>
 288 /****m* tools/tooltest
 289  *
 290  * NAME
 291  *   Tooltest
 292  *
 293  * DESCRIPTION
 294  *   Example showing how to invoke external tools.
 295  *
 296  * EXAMPLE
 297  * This one sorts elements into the file href:nexus-6.txt
 298  * The input data is passed through stdin.
 299  *
 300  * |tool sort &gt; nexus-6.txt
 301  * Zhora
 302  * Pris
 303  * Leon Kowalski
 304  * Roy Batty
 305  * Rachel
 306  * Rick Deckard?
 307  * |tool end
 308  *
 309  * We can also execute tools without having any stdin data.
 310  * In the following example the output is simply redirected into href:tears.txt
 311  *
 312  * |exec echo "All those moments will be lost in time like tears in rain." &gt; tears.txt
 313  *
 314  * You can also include neat DOT graphs in your documentation.
 315  * This one shows a hash table.
 316  *
 317  * |dot start
 318  * digraph G {
 319  *   nodesep=.05;
 320  *   rankdir=LR;
 321  *   node [shape=record,width=.1,height=.1];
 322  *
 323  *   node0 [label = "&lt;f0&gt; |&lt;f1&gt; |&lt;f2&gt; |&lt;f3&gt; |&lt;f4&gt; |&lt;f5&gt; |&lt;f6&gt; | ",height=2.0];
 324  *   node [width = 1.5];
 325  *   node1 [label = "{&lt;n&gt; n14 | 719 |&lt;p&gt; }"];
 326  *   node2 [label = "{&lt;n&gt; a1  | 805 |&lt;p&gt; }"];
 327  *   node3 [label = "{&lt;n&gt; i9  | 718 |&lt;p&gt; }"];
 328  *   node4 [label = "{&lt;n&gt; e5  | 989 |&lt;p&gt; }"];
 329  *   node5 [label = "{&lt;n&gt; t20 | 959 |&lt;p&gt; }"] ;
 330  *   node6 [label = "{&lt;n&gt; o15 | 794 |&lt;p&gt; }"] ;
 331  *   node7 [label = "{&lt;n&gt; s19 | 659 |&lt;p&gt; }"] ;
 332  *
 333  *   node0:f0 -&gt; node1:n;
 334  *   node0:f1 -&gt; node2:n;
 335  *   node0:f2 -&gt; node3:n;
 336  *   node0:f5 -&gt; node4:n;
 337  *   node0:f6 -&gt; node5:n;
 338  *   node2:p -&gt; node6:n;
 339  *   node4:p -&gt; node7:n;
 340  * }
 341  * |dot end
 342  *
 343  ******
 344  */
 345 </programlisting>
 346
 347     <para>
 348     If you want to use the <literal>DOT</literal> tool you need the
 349     <literal>Graphviz</literal> package.
 350     More information and the binaries can be found at
 351     <ulink url="http://www.graphviz.org/">
 352         <citetitle>http://www.graphviz.org/
 353     </citetitle></ulink>.
 354     The created graphs are automatically included in the documentation
 355     (<literal>HTML</literal> and <literal>LaTeX</literal> only).
 356     If you generate <literal>PDF</literal> output from your <literal>LaTeX</literal>
 357     file and you want to include <literal>DOT</literal> graphs in it, you will also
 358     need the <command>epstopdf</command> utility.
 359     <literal>ROBODoc</literal> lets <literal>DOT</literal> generate
 360     <literal>PNG</literal> images for <literal>HTML</literal> output and
 361     <literal>PS</literal> and <literal>PDF</literal> images for
 362     <literal>LaTeX</literal> output.
 363     </para>
 364 </section>
 365
 366 <section>
 367 <title>ROBODoc-ing an existing project</title>
 368
 369   <para>
 370   The ROBODoc package includes also a standalone binary named
 371   <literal>robohdrs</literal>.
 372   This helper program can take clean source file and insert
 373   ROBODoc headers to functions, global variables, and macros.
 374   There are issues with this tool but it saves lots of cumbersome typing
 375   when starting on documenting an existing code-base with ROBODoc.
 376   Type
 377 <command>
 378 man robohdrs
 379 </command>
 380   or
 381 <command>
 382 robohdrs -h
 383 </command>
 384   for help.
 385   Example:
 386 <command>
 387 robohdrs -s -p testproj -i "MODIFICATION HISTORY" -i IDEAS testproj.c
 388 </command>
 389 </para>
 390
 391   <para>
 392   Note that <literal>robohdrs</literal> is supported on UNIX-like platforms only.
 393   It requires <literal>fork()</literal> and  Exuberant Ctags 5.3.1 or newer.
 394   </para>
 395
 396 </section>
 397
 398
 399 <section>
 400 <title>Using ROBODoc under Windows</title>
 401     <para>When you use ROBODoc under windows, don't forget that it is
 402     a command line tool.  ROBODoc relies on the console window to
 403     inform you about problems and errors.</para>
 404
 405     <para>An easy mistake to make is to create a shortcut to
 406     <literal>robodoc.exe</literal> and then click on the icon to
 407     generate the documentation each time you made some changes to your
 408     source code.  If you have a fast machine a console window pops up
 409     quickly and after that your documentation is ready.</para>
 410
 411     <para>This works very fine until you make a mistake in one of your
 412     headers.  The console window still pops up, but before you have a chance
 413     to read any of the error messages it is gone again.  Most likely
 414     you won't even have noticed there were error messages.  You will
 415     end up with empty documentation or old documentation.  </para>
 416
 417     <para>It is Better to create a batch file with the following commands
 418     and to store all the options in a <filename>robodoc.rc</filename>
 419     file:</para>
 420 <programlisting>
 421 robodoc.exe
 422 pause
 423 </programlisting>
 424     <para>Now the console window stays open and you have the
 425     opportunity to read the error messages.</para>
 426
 427     <para>While the window is open, right click on the title bar,
 428     go to properties->layout and set the buffer size to something
 429     like 2500. That way, the next time you run it, you can scroll back
 430     and view all error messages.
 431     </para>
 432
 433 </section>
 434
 435 </section>
 436