2 <title>Tips and Tricks</title>
5 <title>The SOURCE Item</title>
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>
12 /****f* Robodoc/RB_Panic [2.0d]
14 * RB_Panic - Shout panic, free resources, and shut down.
16 * RB_Panic (cause, add_info)
17 * RB_Panic (char *, char *)
19 * Prints an error message.
20 * Frees all resources used by robodoc.
23 * cause - pointer to a string which describes the
25 * add_info - pointer to a string with additional information.
27 * RB_Close_The_Shop ()
31 void RB_Panic (char *cause, char *add_info)
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 */
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>
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>
52 <para>You can also make normal items work like the source item,
53 see <xref linkend="sourceitems" endterm="sourceitems.title" />.
59 <title>Minimizing Duplicate Information</title>
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
67 /****f* Robodoc/RB_Panic [2.0d]
69 * RB_Panic - Shout panic, free resources, and shut down.
71 * RB_Panic (cause, add_info)
72 * RB_Panic (char *, char *)
74 * Prints an error message.
75 * Frees all resources used by robodoc.
78 * cause - pointer to a string which describes the
80 * add_info - pointer to a string with additional information.
82 * RB_Close_The_Shop ()
86 void RB_Panic (char *cause, char *add_info)
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 */
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
106 /****f* Robodoc/RB_Panic [2.0d]
108 * Shout panic, free resources, and shut down.
112 void RB_Panic (char* cause, char *add_info)
116 * Prints an error message.
117 * Frees all resources used by robodoc.
118 * Terminates program.
120 * cause - pointer to a string which describes the
121 * cause of the error.
122 * add_info - pointer to a string with additional information.
124 * RB_Close_The_Shop ()
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 */
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>
141 <para>The <filename>robodoc.rc</filename> required for this is: </para>
154 remark begin markers:
162 <!-- TODO explain about headers with more than one name -->
165 <title>Advanced formatting with raw HTML and LaTeX code</title>
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 <
170 is translated to a &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.
180 /****m* pipe/pipetest
184 * Simple header to show "piping" features in items.
186 * Only "pipes" which match selected output style are picked up.
187 * |html <CENTER>This will be included in <B>HTML</B> output.</CENTER>
188 * |latex \centerline{This will be included in \LaTeX output}
189 * Space is mandatory following the pipe marker. The following is not a
191 * |html<B>Moi!</B>
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} & = & 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} & = & \hat{u}-v \; ,
203 * |latex \label{diffspot:2} \\
204 * |latex \frac{\partial r}{\partial \tau} & = & D_r {\nabla}^2 r \; .
205 * |latex \label{diffspAot:3}
206 * |latex \end{eqnarray}
207 * |html <I>TODO: write this in html</I>
208 * End of the example.
215 <title>Linking to external documents (href, file, mailto, images)</title>
217 <para> In HTML mode ROBODoc recognizes the following links to
218 external documents. </para>
222 <listitem><para><literal>href:body</literal> -- This is replaced with
223 <literal><a href="body">body</A></literal>
226 <listitem><para><literal>file:/body</literal> -- This is replaced with
227 <literal><a href="file:/body">file:/body</A></literal>
230 <listitem><para><literal>mailto:body</literal> -- This is replaced with
231 <literal><a href="mailto:body">body</A></literal>
234 <listitem><para><literal>http://body</literal> -- This is replaced with
235 <literal><a href="http://body">http://body</A></literal>
238 <listitem><para><literal>image:body</literal> -- This is replaced with
239 <literal><image src="body"></literal>
247 <title>Linking from an external document</title>
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>
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>
269 <title id="tools.title">Using external tools</title>
271 You can also execute external tools from <literal>ROBODoc</literal> and even
273 The output of these tools can be included in your documentation for instance.
276 There are several types of external tools you can use:
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>
284 The following example shows how to use each of them.
288 /****m* tools/tooltest
294 * Example showing how to invoke external tools.
297 * This one sorts elements into the file href:nexus-6.txt
298 * The input data is passed through stdin.
300 * |tool sort > nexus-6.txt
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
312 * |exec echo "All those moments will be lost in time like tears in rain." > tears.txt
314 * You can also include neat DOT graphs in your documentation.
315 * This one shows a hash table.
321 * node [shape=record,width=.1,height=.1];
323 * node0 [label = "<f0> |<f1> |<f2> |<f3> |<f4> |<f5> |<f6> | ",height=2.0];
324 * node [width = 1.5];
325 * node1 [label = "{<n> n14 | 719 |<p> }"];
326 * node2 [label = "{<n> a1 | 805 |<p> }"];
327 * node3 [label = "{<n> i9 | 718 |<p> }"];
328 * node4 [label = "{<n> e5 | 989 |<p> }"];
329 * node5 [label = "{<n> t20 | 959 |<p> }"] ;
330 * node6 [label = "{<n> o15 | 794 |<p> }"] ;
331 * node7 [label = "{<n> s19 | 659 |<p> }"] ;
333 * node0:f0 -> node1:n;
334 * node0:f1 -> node2:n;
335 * node0:f2 -> node3:n;
336 * node0:f5 -> node4:n;
337 * node0:f6 -> node5:n;
338 * node2:p -> node6:n;
339 * node4:p -> node7:n;
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.
367 <title>ROBODoc-ing an existing project</title>
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.
387 robohdrs -s -p testproj -i "MODIFICATION HISTORY" -i IDEAS testproj.c
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.
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>
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>
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>
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>
424 <para>Now the console window stays open and you have the
425 opportunity to read the error messages.</para>
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.