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
|
<chapter id="doc-guidelines"><title>Documentation Guidelines</title>
<!--====== ENGLISH ============================================================ -->
<sect1 id="english"><title>Some antisocial English recommendations</title>
<para>Here are the most frequent mistakes once seen in user documentation.
A well written documentation makes the learning curve less steep for potential users and support the profesionnal look of the software.</para>
<para>Use a spellchecker. This finds words like "choosen", "choosed", "chosed" (the correct form is "chosen").</para>
<para>Do not repeat things when they are totally obvious. For instance, when there is a button "Add Server", do not write "To add a server, click on Add Server button." This is boring for the reader, who then pays less attention. Another example: "colorScale", documentation: "This is the color scale used". Here, the documentation brings no information.</para>
<para>English details (that the spellchecker will not find):
<itemizedlist>
<listitem>"mouse button pressed down" and variants -> "click"</listitem>
<listitem>no space before punctuations in two parts (i.e., as opposed to French, no space before ";:!?")</listitem>
</itemizedlist>
</para>
<para>Writing good documention is hard, it requires adopting the reader point of view: which question does she have? what is surprising for someone new to Tulip? what will she chafe at?</para>
</sect1>
<!--====== DEFINITIONS ======================================================== -->
<sect1 id="definitions"><title>Definitions</title>
<orderedlist>
<listitem id="docbook"><para>Docbook is a collection of standards and tools for technical publishing. A Docbook file is composed of SGML(<xref linkend="sgml"/>) tags and is also dependant of a Document Type Definition(<xref linkend="dtd"/>). Docbook has defined standard DTD that you can find in the docbook tools.
</para></listitem>
<listitem id="dtd"><para>DTD : Document Type Definition. The DTD defines the vocabulary of content elements that an author can use and how they relate to each other. For example, a book element can contain a title element, any number of para elements for paragraphs, and any number of chapter elements. </para></listitem>
<listitem id="sgml"><para>SGML : Standard Generalized Markup Language, XML : Extensible Markup Language</para></listitem>
<listitem id="xsl"><para>XSL (Extensible Stylesheet Language) is a language of description used for the transformation of the sgml file into formatted ouput: XSL processors like xsltproc, saxon or xalan, ... do that.</para></listitem>
<listitem id="cata"><para>Catalog : In XML, it provides a mapping from generic addresses to specific local directories on a given machine. A catalog can be used to locate the DocBook DTD, system entity files, and stylesheet files during processing.</para></listitem>
</orderedlist>
</sect1>
<!--============================================================================== -->
<!--======= Tools installation ================================================== -->
<sect1 id="tools-install"><title>Tools installation</title>
<sect2 id="duck-install"><title>Docbook XSL Stylesheet</title>
<para> There is a great reference for installing tools : <ulink url="http://www.sagehill.net/docbookxsl/ToolsSetup.html">Docbook XSL : the guide</ulink>.</para>
<para>To write a manual using Docbook and the XSL stylesheets, we need four tools :
<itemizedlist>
<listitem>
<para>Docbook DTD</para>
</listitem>
<listitem><para>Docbook XSL stylesheets</para></listitem>
<listitem><para>XSL processor</para></listitem>
<listitem><para>XSL-FO processor (optional)</para></listitem>
</itemizedlist>
There are RPM (docbook-dtds, docbook-style-xsl), Debian (docbook-xml, docbook-xsl) packages for Linux systems, Fink packages for Mac systems, and Cygwin and other packages for Windows systems. The installation of Docbook and the XSL stylesheet create a file named <filename>/etc/xml/catalog</filename>. It contains the informations about all others catalogs to resolve the path of the DTDs and the stylsheets from the URI.</para>
<sect3 id="xsl-install"><title>Manual Installation : Docbook XSL stylesheet</title>
<para>As we have some problems with the DTD provided by the distributions, Tulip gives the DTD 4.4 of Docbook XML and is located in <filename>$TULIPDIR/docs/common/dtd</filename>. So, this section is for informations. The XSL packages seem to have great catalog resolutions, but if you have problems, this section can help you.</para>
<para>If you need another solution or you have problems for the compilation, you can download the source package on oasis <ulink url="http://www.oasis-open.org/docbook/xml/">web site</ulink> for Docbook and on the <ulink url="http://sourceforge.net/projects/docbook/">SourceForge page</ulink> of XSL stylesheets. The Docbook sources are in a <code>zip</code> file. Unzip your package in a directory in the place you prefer. The Docbook XML DTD consists of a main file <filename>docbookx.dtd</filename>, several module files and a catalog file, named <filename>catalog.xml</filename>. To update the changes of location of your DTD, edit the file <filename>CatalogManager.properties</filename> in <filename>$TULIPDIR/docs/common/</filename>. Add the catalog file with its asbolute path to the <code>catalogs</code> variable.
<programlisting>
CatalogManager.properties :
catalogs=/etc/xml/catalog<emphasis>;/home/bardet/docbook-4.4/catalog.xml</emphasis>
relative-catalogs=false
static-catalog=yes
catalog-class-name=org.apache.xml.resolver.Resolver
verbosity=1
</programlisting>
Concerning the XSL stylesheet package, you just have to do the same thing. You can execute the script of intallation. You have to add the reference of the catalog too. Edit the file <filename>catalog.xml</filename> and complete the <code>catalogs</code> variable with the reference of the catalog of your XSL stylesheet.
This catalog resolution make sure that the path, the differences could be find in all Operation Systems. </para>
</sect3>
<sect3 id="xsl-proc"><title>XSL processor</title>
<para>Currently, there are three to do XSL Transform processing with the recommendations of XSL : saxon (<ulink url="http://saxon.sourceforge.net/"/>), xalan (<ulink url="http://xml.apache.org/xalan-j/"/>), and xsltproc (<ulink url="http://xmlsoft.org/XSLT/xsltproc2.html"/>). For the Tulip project, we have decides to use <application>Saxon</application> for the XSL processor. <application>Xsltproc</application> is the xslt c library for gnome. This program is a way to use the library <emphasis>libxslt</emphasis> with a command line tool for applying XSLT stylesheets to XML documents. This application runs quickly but does not include the implementation of the extensions. <application>Xalan</application> is an other solution but <application>Saxon</application> is the most recommanded.</para>
<para><application>Saxon</application> is a free processor written in Java, so it can be run on any operating system with a modern Java interpreter. To install it, you have to download on sourceforge the last release 6.5.4. for debian, it exists a deb package. This is the full version that implements the XSLT 1.0 standard. It runs on Java system and provides opportunities for extensions. For Windows, it exists the <application>Instant Saxon</application> a precompiled version that runs only on Microsoft Windows. Saxon is distributed as a zip package. You have to unzip it into a suitable location. It gives three <filename>.jar</filename> files ; <filename>saxon.jar</filename> contains the XSLT processor. In according to the location, you have to update your CLASSPATH. You need to include the full path to the necessary .jar files in the CLASSPATH environment variable. To update it :
<screen>
CLASSPATH=$CLASSPATH:/usr/saxon/saxon.jar:\
/usr/docbook-xsl/extensions/saxon653.jar
export CLASSPATH
</screen>
If your CLASSPATH is incorrect, you get an error message about <methodname>NoClassDefFoundError</methodname>. To generalize it, you have to change your <filename>.bashrc</filename> or <filename>.bash_profile</filename>. In this example, a second package is included : <filename>/usr/docbook-xsl/extensions/saxon653.jar</filename>, in Fedora Core 4, it is located in <filename>/usr/share/sgml/docbook/xsl-stylesheets/extensions/</filename>. It contains the implementation of the extensions of XSL Transformations. This extensions are necessary to manage some tags and are included in the docbook tools. The general syntax for compilation is like followed :
<cmdsynopsis><command>java com.icl.saxon.StyleSheet </command>
<arg><option>options</option></arg>
<arg>file.docbook</arg>
<arg>file.xsl</arg>
<arg><option>param=value</option></arg>
</cmdsynopsis>
However, Tulip provides the sources of saxon and you do not worry to this installation to avoid the complicated installation.</para>
<warning><para> This system of catalog resolution is made for finding located files. With the packages of Fedora and perhaps with others distribution, the catalogs include a declaration with URL adresses. So the catalog resolving processor try to connect on the Net.
<programlisting>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD XML Catalogs V1.0//EN"
"http://www.oasis-open.org/commitees/entity/release/1.0/catalog.dtd">
</programlisting>
It should be erased in all catalog files which blocks the offline compilation (/etc/xml/catalog, /usr/shar/sgml/docbook/xmlcatalog, ...).</para>
</warning>
</sect3>
<sect3 id="xsl-fo"><title>XSL-FO processor for PDF output</title>
<para>To transform the docbook sources in pdf documents, we need to use an other format FO. It is running with a stylesheet in docbook-xsl package. The role of the XSF-Fo processor is to transform FO files in printable files, like pdf. You have to install <application>passivetex</application>. Fedora and Debian includes this package, but you can download and install it with its web site, <ulink url="http://www.tei-c.org.uk/Software/passivetex/"/>. It exists a program named <code>pdfxmltex</code> giving tex macros for the XSL-Fo processing.</para>
</sect3>
</sect2>
<sect2 id="dox-install"><title>Doxygen</title>
<para>It can already be in your distribution. For distributions like Debian or Fedora Core, you can used : <cmdsynopsis><command>yum</command><arg><option>install</option> doxygen</arg></cmdsynopsis><cmdsynopsis><command>apt-get</command><arg><option>install</option> doxygen</arg></cmdsynopsis> For another solution, you can find source files and <application>CVS</application> repository in the web site of Doxygen (<ulink url="http://www.stack.nl/~dimitri/doxygen"/>).</para>
</sect2>
</sect1>
<!--============================================================================== -->
<!--======= Handwriting for the manuals ========================================= -->
<sect1 id="written"><title>Handwriting for the manuals</title>
<para>Some works on the Tulip project lead to make a part of a handbook for developer or users. Docbook utilities are used to create them. </para>
<para>Docbook is a DTD (Document Type Definition) for XML or SGML document that define elements. It is a kind of grammar of the source document. This is in relation with stylesheets (DSSSL [<xref linkend="dsssl"/>] or XSL) which allow you to publish on the Web ( in HTML, XHTML) on a printable documentation (PS, PDF, RTF...) with your Docbook documents. The main advantages of the docbook format is the possibility to seperate the contents of the forms. The tools which can transform the source documents are generic and can pratically run on all Operation Systems. Docbook is the successor of LinuxDoc.</para>
<para>For Tulip documentation, the source documents are in XML, because XML leads to take the place of SGML to alleviate compatibility problems with browser software. It's a new, easier version of the standard rules that govern the markup itself. To find all of the xml elements to composed your own document, you can see : <ulink url="http://www.docbook.org/tdg5/en/html/pt02.html">http://www.docbook.org/tdg5/en/html/pt02.html</ulink></para>
<para>For each document, a set of XML files should be created. To help the editing of the handbook, it is possible to use general editors like kate, emacs, quanta. See <ulink url="http://i18n.kde.org/doc/doc-primer/docbook-editors.html"> Docbook Editors</ulink>. To configure Kate, select <filename>Configure Kate</filename> -> <filename>Settings</filename> -> <filename>Configure Kate</filename>. Select the plugin item from the application tree and check the <filename>Kate XML Completion</filename>, and the <filename>Kate XML Validation</filename> boxes. </para>
<para>To compile the handbooks, you just have to type <code>make html</code>. If you want to test the validation of the sources of the handbooks, type <code>make check</code>. The last command is <code>make pdf</code>, it produces the printable output.</para>
<orderedlist>
<listitem id="dsssl"><para>DSSSL: Document Style Semantics and Specification Language. For more informations, you can visit the web site: <ulink url="http://www.jclark.com/dsssl/"/></para></listitem>
</orderedlist>
<sect2 id="tricks"><title>Some Tricks</title>
<para>
<programlistingco>
<areaspec>
<area id="xml" coords='2'/> <area id="comments" coords='3'/><area id="doctype" coords='4'/>
</areaspec>
<programlisting>
<?xml version='1.0'?>
<emphasis><!-- My first Docbook file --></emphasis>
<!DOCTYPE book PUBLIC "-//OASIS//DTD Docbook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
</programlisting>
<calloutlist>
<callout arearefs="xml"> <para>defined that it is a XML document</para></callout>
<callout arearefs="comments"> <para>the comments are writing between <!-- and --></para></callout>
<callout arearefs="doctype"> <para>DTD, Document Type Declaration with pulic identifier</para> </callout>
</calloutlist>
</programlistingco>
The identification of the DTD is used by the document to know which root element is. The declaration could have a different aspect if you use the system identifier : <code><!DOCTYPE book SYSTEM "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"></code> Here, <quote>OASIS</quote> is the owner, the declaration is <quote>DTD Docbook XML V4.4</quote> and the language is English <quote>EN</quote>. The keyword <quote>book</quote> specifies that the root element is <emphasis>book</emphasis>. An example of the structure of a Docbook file is like followed.
<programlisting> <!-- 84 caracters max -->
<!DOCTYPE book SYSTEM
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<book>
<bookinfo>
<title>My First Book</title>
<author><firstname>Jean-Pierre</firstname><surname>DUPONT
</surname></author>
<copyright><year>2005</year>
<holder>Jean-Pierre DUPONT</holder>
</copyright>
</bookinfo>
<preface> ... </preface>
<chapter> ... </chapter>
<sect1> <title>..</title>
<para> ...</para>
</sect1>
<chapter> ... </chapter>
<chapter> ... </chapter>
<appendix> ... </appendix>
<appendix> ... </appendix>
<index> ... </index>
</book>
</programlisting> Each blocks of text is in a <emphasis>para</emphasis> element.</para>
<sect3 id="valid"><title>Validation</title>
<para>
The validity of a document is very difficult to detect, so we use a program to do that. A validating parser is a program that can read the DTD and determine whether the exact order of elements in the document is valid according to the DTD. </para>
<para>To determinate if the XML code is valid, the program <application>xmllint</application> can be used with the option --valid. This program is a parser dependent of the library <emphasis>libxml2</emphasis>.<cmdsynopsis><command>xmllint</command><arg><option>--valid --noout</option> myfile.docbook</arg></cmdsynopsis>
When there are errors in the document, <application> xmllint </application> detects the number line and displays the form that it should be.
<screen>
index.docbook:485: element sect2: validity error : Element sect2
content does not follow the DTD, expecting (sect2info? , (title ,
subtitle? , titleabbrev?) , (toc | lot | index | glossary |
bibliography)* , (((calloutlist | glosslist | bibliolist | itemizedlist
| orderedlist | segmentedlist | simplelist | variablelist | caution |
important | note | tip | warning | literallayout | programlisting |
programlistingco | screen | screenco | screenshot | synopsis |
cmdsynopsis | funcsynopsis | classsynopsis | fieldsynopsis |
constructorsynopsis | destructorsynopsis | methodsynopsis | formalpara
| para | simpara | address | blockquote | graphic | graphicco |
mediaobject | mediaobjectco | informalequation | informalexample |
informalfigure | informaltable | equation | example | figure | table |
msgset | procedure | sidebar | qandaset | task | anchor | bridgehead |
remark | highlights | abstract | authorblurb | epigraph |indexterm |
beginpage)+ , (refentry* | sect3* | simplesect*)) | refentry+ | sect3+ |
simplesect+) , (toc | lot | index | glossary | bibliography)*), got (
refentry)
</sect2>
^
make: *** [check] Erreur 1
</screen>
It exists several attempts to produce an print or web publishing. Recently, the XML workgroup has made a standard Extensible Style Language (XSL). It provides a set of stylesheet able to transform the Docbook documents. DSSSL is an other possibility, but we use the XSL stylesheet for the Tulip project. This stylesheet is an argument for the compilation with an XSL processor for the XSL transformations.</para>
</sect3>
</sect2>
<sect2 id="duck-faq"><title>Docbook FAQ</title>
<qandaset>
<qandaentry>
<question><para>how to separate the work in several files ?</para></question>
<answer><para>
The first solution to write a part of a handbook is to complete the main document. To avoid that several persons work on the same file, it exists a solution to cut the docbook file. You can write a section or a chapter and you just have to include your part in the main file. To create a valid file for the compiler, you shoud modify the head of a docbook file and specify the kind of document you do. For a chapter, your file is like followed :
<programlisting>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD Docbook XML V4.4//EN">
<chapter>
<title>My personal Chapter</title>
<sect1> ... </sect1>
</chapter>
</programlisting>
The identification gives the kind of file you write. For including your work, you just have to complete the declaration of the main file and insert a special tag located at the place that you want the inclusion. Don't forget to erase the declaration of your work. The file must begin with the markup <quote>chapter</quote>.
<programlisting>
<!DOCTYPE book PUBLIC "-//OASIS//DTD Docbook V4.4//EN" [
<!ENTITY myPersonalFile SYSTEM "myFile.xml">
]>
<book>
...
</chapter>
&myPersonalFile;
<chapter>
...
</programlisting>
</para></answer>
</qandaentry>
<qandaentry>
<question><para>How to insert a figure ?</para></question>
<answer><para>the element uses for the insert of a figure is <quote><figure></quote>. It enables the numerotation of the figures. Warning, the width of the figures should not exceed a certain value to avoid that it is truncated in the pdf transform. You can specify a title and other parameter in the limits of the DTD.
<programlisting>
<figure> <title>Screenshot of the result</title>
<graphic fileref="doxygen-ex.png"/></figure></programlisting>
In order to insert a figure as <quote>inline</quote>, use the tag <code>inlinegraphics</code></para></answer>
</qandaentry>
<qandaentry>
<question><para>How to make annotation in a program listing (or in a console listing) ?</para></question>
<answer><para>See <ulink url="http://www.sagehill.net/docbookxsl/AnnotateListing.html#Callouts">DocBook XSL : the complete guide</ulink></para>
<para>To do that, you use the set of tags <code>programlisting, co, calloutlist, callout</code>.
<programlisting>
<programlisting>
class MyClasse{ <co id="myid" linkends="mylink"/>
};
</programlisting>
<calloutlist>
<callout arearefs="myid" id="mylink">
<para>... comments ...</para>
</callout>
</calloutlist>
</programlisting>
The <code>programlisting</code> contains the program that you want to display. It is a verbatim mode. Warning, special caracters could be not allow : <, for example. The <code>code</code> element represents the callout you want to place. The location of the insertion is important because it is the location on display. Two attributes are essential : <code>id</code> for the identification and <code>linkends</code> for indicate which comments is linked with the callout. After the <code>programlisting</code> element, we use a <code>calloutlist</code> element to define a list of comments. each comment is contained in a <code>callout</code> element. It has attributes whose <code>arearefs</code> to make a reference to callouts and id for the identification.</para>
<para>It exists an other solution but it is more difficult. You have to specify coordinates of place where you want a callout. This solution is an easy and quick way to comment your program listing.
<programlisting>
class MyClasse{ <co id="myid" linkends="mylink"/>
};
</programlisting>
<calloutlist>
<callout arearefs="myid" id="mylink"><para>... comments ...</para></callout>
</calloutlist>
To adapt the case to the console listing, you should use the <code>screenco, screen, callout, ...</code> elements.</para></answer>
</qandaentry>
</qandaset>
</sect2>
</sect1>
<!--============================================================================== -->
<!--======= Code documentation ================================================== -->
<sect1 id="doxygen"><title>Code documentation</title>
<sect2 id="presentation_dox"><title>Presentation</title>
<para><application>Doxygen</application> is a documentation system for several languages like C++. It can generate an on-line documentation browser (in HTML), a set of manpages, an off-line reference manual (in LaTeX) and/or others from the set of documented source files of your project. This kind of documentation is a necessary tool for developers to find informations about the code. It is not a way to explain how it is imagined but which possibilities you have. It is available for several distributions like Fedora Core, Debian, Gentoo and others,.. Windows, MacOs and Sun Solaris too.
</para>
<para>To create your first <application>Doxygen</application> documentation, you need a config file .cfg or .doxygen. To generate it :
<cmdsynopsis><command>doxygen</command><arg><option>-g</option> myfile.doxygen</arg></cmdsynopsis>
The file contains the options you can choose for the documentation generation. Comments indicates how to use this variables. The INPUT variable contains the files or directories to find the source files. When you have set all tags with good values, you can generate the documentation. <application>Doxygen</application> checks the source files to extract the informations in special comments and tags. See this page for the informations about the variables : <ulink url="http://www.stack.nl/~dimitri/doxygen/config.html">http://www.stack.nl/~dimitri/doxygen/config.html</ulink>. To create it :
<cmdsynopsis><command>doxygen</command><arg>myfile.doxygen</arg></cmdsynopsis>
By default, it creates directories : html, latex, and/or man, ...
</para>
<para>For the <application>Tulip</application> project, It exists two documentations. One is destinated for the Developer team and this other one is for the user of the librairies. The Configuration files are generated by the Makefile processing.</para>
</sect2>
<sect2 id="dx-comments"><title>Developer comments</title>
<para>The code documentation, generated by <application>Doxygen</application> is completely dependant of the developer comments. It is important that developers follow the grammar rules. </para>
<para>So the blocks of documentation in the sources files are the C++ comment blocks. For each item of code, there are two types of descriptions, which together form the documentation : a brief description and detailed description. A detailed description is used to explain generously the existence of an item.
<screen>
/**
* detailed description
*/
or
/*!
* detailed description
*/
or
/*!
detailed description
*/
or others ....
</screen>
To make a brief description, you can use the command <methodname>\brief</methodname>. This command ends at the end of a paragraph, so the detailed description follows after an empty line. An other option is to use a special C++ style comment which does not span more than one line.
<screen>
/*! \brief Brief description.............
* ...............
*
* Detailed description
*/
or
/// Brief description
/** Detailed description. */
or
//! Brief descripion.
//! Detailed description
//! starts here.
or others ....
</screen>
For more details, the web site of <ulink url="http://www.doxygen.org/docblocks.html">Doxygen</ulink> explains it.
In general, the comments must be before the declaration or definition of a type, a function or a member. If you want to putting the documention after, you have to add a marker <. Note that you can place your comment at other places using some tags like <code>\class, \union, \fn, \var,</code> ... or <code>@class, @union, @fn, @var, </code>...
</para>
<para>
It exists several tags to help you for commenting and writing a description : all of it begin with a backslash <code>\</code> or an at-sign <code>@</code>.
<itemizedlist>
<listitem><para><code>@author</code>, name of the author. </para></listitem>
<listitem><para><code>@param</code>, to write a special comment on a parameter of a method or function</para></listitem>
<listitem><para><code>@see</code>, to make a reference to an other object or function</para></listitem>
<listitem><para><code>@return</code>, to indicate the exit of a function</para></listitem>
<listitem><para><code>@date</code>, date of creation</para></listitem>
<listitem><para><code>@note</code>, describe a role</para></listitem>
<listitem><para><code>@attention</code>, write a caution</para></listitem>
<listitem><para><code>@warning</code>, write a warning</para></listitem>
<listitem><para><code>@pre</code>, write a prerequisite</para></listitem>
<listitem><para><code>@remark</code></para></listitem>
</itemizedlist>
The complete list is on this <ulink url="http://www.stack.nl/~dimitri/doxygen/commands.html">page</ulink> in the <application>Doxygen</application> web site.
</para>
<para><example><title>Doxygen : A simple source file</title>
<para><programlisting>
// ... comments not include ...
/// A example of class : MyClass.
/**
a more detail class description :
\author Me
\date 29/07/2005
*/
#include <string>
class MyClass
{
/* ... comments not include ... */
public:
/** the constructor of the class */
/** the detail description of the constructor. */
MyClass(){i=0;}
//! A destructor.
~MyClass(){}
/// drawing of a string
/**
\param s the string to display
\return there is no return
@sa MyClass(), ~MyClass()
*/
void draw(const char *s="Hello World");
/* exemple of doc comments not before the declaration */
unsigned int getI(){return i;} /**<@return the number
the value of i */
private:
unsigned int i;
/** @var i
@brief, you can put the comments where you want
with the special tags */
};
</programlisting>
</para></example></para>
<para>To update the Documentation of Tulip, you just have to use the makefile and so write : <filename>make docs</filename>.</para>
</sect2>
<sect2 id="dow-faqs"><title>Doxygen FAQ</title>
<qandaset>
<qandaentry>
<question><para>How to insert a block of code ?</para></question>
<answer><para> To illustrate your documentation, you can insert a block of code in a description between <code>\code</code> and <code>\endcode</code>. This code is written in the documentation with highlighting syntax. </para></answer>
</qandaentry>
<qandaentry>
<question><para>How to force an end of line ?</para></question>
<answer><para>Use the tag <methodname>\n</methodname>.</para></answer>
</qandaentry>
<qandaentry>
<question><para>How to make doxygen ignore code fragment ?</para></question>
<answer><para>It exists two ways to resolve this questions. The first one is to use the tags <code>\cond</code> and <code>\endcond</code> to skip the internal code. The second way is to use the preprocessor of Doxygen. In the configuration file, you specify the macros and you verify if the value of <code>PREPROCESSING</code> is to yes. Then, you set <code>MACROS_NAME</code> to <code>PREDEFINED</code>.
<programlisting>
#ifndef MACROS_NAME
/* code that must be skipped by Doxygen */
#endif /* MACROS_NAME */
</programlisting>
Two macros are defines for <emphasis>Tulip</emphasis> documentations.
<itemizedlist>
<listitem><para><code>DOXYGEN_NOTFOR_DEVEL</code> : use to skip the code for Developer and User documentations.</para></listitem>
<listitem><para><code>DOXYGEN_NOTFOR_USER</code> : use just for the User documentation.</para></listitem>
</itemizedlist>
</para></answer>
</qandaentry>
<qandaentry>
<question><para>How to insert a equation ?</para></question>
<answer><para>See the <ulink url="http://www.stack.nl/~dimitri/doxygen/formulas.html">Doxygen web site</ulink></para><para>Doxygen allows you to put Latex formulas in the ouput (just for HTML and latex format). Three ways are avaible. If you want to include formulas in-text, you have to put formulas between a pair of <quote>\f$</quote>
<screen>
\f$ AB = \sqrt{BC^2 + CA^2} \f$
</screen>
The second way is for a centered display on a seperate line. These formulas should be put between <code>\f[</code> and <code>\f]</code> commands.</para>
<para>The third way is to used formulas or other latex elements that are not in a math environment. It can be specified using <code>\f{</code><emphasis>environment</emphasis><code>}</code>, where <emphasis>environment</emphasis> is the latex environment, the corresponding end commands is <code>\f}</code></para></answer>
</qandaentry>
</qandaset>
</sect2>
</sect1>
<sect1 id="docs-ref"><title>References</title>
<para>Docbook XSL : the complete Guide <ulink url="http://www.sagehill.net/docbookxsl/index.html">http://www.sagehill.net/docbookxsl/index.html</ulink></para>
<para>The Duck Book - <ulink url="http://www.oreilly.com/catalog/docbook/chapter/book/docbook.html">Docbook : the Definitive Guide </ulink></para>
<para>The KDE documentation primer : recommandations to write correctly in Docbook - <ulink url="http://i18n.kde.org/doc/doc-primer/index.html">http://i18n.kde.org/doc/doc-primer/index.html</ulink></para>
<para>Doxygen web site - <ulink url="http://www.docbook.org/tdg/en/html/part2.html">http://www.docbook.org/tdg/en/html/part2.html </ulink></para>
</sect1>
</chapter>
|
