source: trunk/doc/src/docbook/developerdoc/write_docbook_doc.xml @ 3280

Last change on this file since 3280 was 3280, checked in by Martin Svensson, 16 years ago

References #580. Added some instructions to get a nice output. Updated some images to have a fixed size.
File size: 32.8 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id$
7 
8  Copyright (C) Authors contributing to this file.
9 
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12 
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 2
16  of the License, or (at your option) any later version.
17 
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22 
23  You should have received a copy of the GNU General Public License
24  along with this program; if not, write to the Free Software
25  Foundation, Inc., 59 Temple Place - Suite 330,
26  Boston, MA  02111-1307, USA.
27-->
28
29<chapter id="write_docbook_doc">
30  <?dbhtml dir="write_doc"?>
31  <title>Write documentation</title>
32  <para>
33    This chapter is for those who intent to contribute to the BASE2 documentation. The chapter
34    contains explanations of how the documentation is organized, what the different parts is
35    about and other things that will make it easier to know where to insert new text.
36  </para>
37  <para>
38    The documentation is written with the docbook standard, which is a bunch of defined XML
39    elements and XSLT style sheets that are used to format the text. Later on in this chapter
40    is a reference, over those docbook elements that are recommended to use when writing BASE2
41    documentation. Further information about docbook can be found in the on-line version of
42    O'Reilly's
43    <ulink url="http://www.docbook.org/tdg/en/html/">DocBook: The Definitive Guide</ulink>
44    by Norman Walsh and Leonard Muellner.
45  </para>
46
47  <sect1 id="write_docbook_doc.layout">
48    <title>Documentation layout</title>
49    <para>
50      The book, which is the main element in this docbook documentation, is divided into four
51      separated parts, depending on who the information is directed to. What kind of
52      documentation each one of these parts contains or should contain is described here
53      below.
54    </para>
55    <variablelist>
56      <varlistentry>
57        <term>Overview documentation</term>
58        <listitem>
59          <para>
60            The overview part contains, like the name says, an overview of BASE2.
61            For example an explanation about what the purpose with BASE2 is, the terms
62            that are used in the program and other general things that anyone that is
63            interested in the program wants/needs to know before exploring it further.
64          </para>
65        </listitem>
66      </varlistentry>
67      <varlistentry>
68        <term>User documentation</term>
69        <listitem>
70          <para>
71            This part contains information that are relevant for the common BASE2-user.
72            More or less should everything that a power user role or an user role needs
73            to know be included here.
74          </para>
75        </listitem>
76      </varlistentry>
77      <varlistentry>
78        <term>Administrator documentation</term>
79        <listitem>
80          <para>
81            Things that only an administrator-role can do is documented in this part. It
82            can be how to install the program, how to configure the server for best
83            performance or other subjects that are related to the administration.
84          </para>
85        </listitem>
86      </varlistentry>
87      <varlistentry>
88        <term>Developer documentation</term>
89        <listitem>
90          <para>
91            Documentation concerning the participation of BASE2 development should be placed
92            in this part, e.g. coding standards, the java doc from the source code, how
93            to develop a plugin etc.
94          </para>
95        </listitem>
96      </varlistentry>
97    </variablelist>
98  </sect1>
99
100
101  <sect1 id="write_docbook_doc.begin">
102    <title>Getting started</title>
103    <para>
104      Before start writing any documentation in BASE2 there are a couple of things, some
105      rules and standards, to have in mind.
106    </para>
107    <sect2 id="write_docbook_doc.begin.sourcefiles">
108      <title>Organization of source files</title>
109      <para>
110        The source files of the documentation are located in
111        <filename class='directory'>base2root/doc/src/docbook</filename>
112        which is showed in
113        <xref linkend="write_docbook_doc.figures.fileorganization" />
114        . The different parts of the documentation are organized into separate folders and
115        each one of the folders contains one index file and one file for each chapter in
116        that part. The index file joins the chapters, in current part/folder, together and
117        doesn't really contain any text. The documentation root directory also contains an
118        <filename class='headerfile'>index.xml</filename>
119        file which joins the index files from the different parts together.
120      </para>
121      <figure id="write_docbook_doc.figures.fileorganization">
122        <title>The organization of documentation files</title>
123        <screenshot>
124          <mediaobject>
125            <imageobject>
126              <imagedata contentwidth="15cm" width="15cm" fileref="figures/fileorganization.png" format="PNG"></imagedata>
127            </imageobject>
128          </mediaobject>
129        </screenshot>
130      </figure>
131      <sect3 id="write_docbook_doc.begin.sourcefiles.newfile">
132        <title>Create new chapter/file</title>
133        <para>
134          Each file in the documentation, except the index files, represents a chapter.
135          How to create a new chapter and include it in the text is described in
136          following items.
137          <orderedlist numeration='arabic' spacing='compact'>
138            <listitem>
139              <para>
140                Create a new XML-file in the folder of which part the new chapter
141                should be included. Give it a name that is quite similar to the
142                new chapter's title but use <userinput>_</userinput> instead of
143                blank space and keep it down to one or few words.
144              </para>
145            </listitem>
146            <listitem>
147              <para>
148                Begin to write the chapter's body, it should look like
149                <xref linkend="write_docbook_doc.examples.chapterbody"/>
150                <example id="write_docbook_doc.examples.chapterbody">
151                  <title>Example of a chapter</title>
152                  <programlisting>
153&lt;?xml version="1.0" encoding="UTF-8"?&gt;
154&lt;!DOCTYPE chapter PUBLIC
155    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
156    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd"&gt;
157
158&lt;chapter id="<replaceable>example_chapter</replaceable>"&gt;
159   &lt;?dbhtml dir="<replaceable>folder name to put the chapter's files in</replaceable>"?&gt;
160   &lt;title&gt;Example of a chapter &lt;/title&gt;
161   &lt;para&gt;
162      &hellip;
163   &lt;/para&gt;
164   &lt;sect1 id="<replaceable>example_chapter.sect1</replaceable>"&gt;
165      &lt;title&gt;Example of top level section &lt;/title&gt;
166      &lt;para&gt;
167         &hellip;
168      &lt;/para&gt;
169      &lt;sect2 id="<replaceable>example_chapter.sect1.sect2</replaceable>"&gt;
170         &lt;title&gt;Example of second level section &lt;/title&gt;
171         &lt;para&gt;
172            &hellip;
173         &lt;/para&gt;
174         &lt;sect3 id="<replaceable>example_chapter.sect1.sect2.sect3</replaceable>"&gt;
175            &lt;title&gt;Example of third level section&lt;/title&gt;
176            &lt;para&gt;
177               &hellip;
178            &lt;/para&gt;
179         &lt;/sect3&gt;
180      &lt;/sect2&gt;     
181   &lt;/sect1&gt;
182&lt;/chapter&gt;
183                  </programlisting>
184                </example>
185              </para>
186              <note>
187                <para>
188                  Don't forget to include the
189                  <sgmltag>dbhtml</sgmltag>
190                  tag with the attribute
191                  <sgmltag class="attribute">dir</sgmltag>
192                  set to the value that the chapter's output folder should have as a
193                  name.
194                </para>
195              </note>
196            </listitem>
197            <listitem>
198              <para>
199                Next and last step is to get the new chapter included in the documentation. This is done by including the file's name in
200                the file
201                <filename>index.xml</filename>
202                that's located in the current part's folder.
203                <xref linkend="write_docbook_doc.examples.include_chapter" />
204                shows how the chapter that was created above is included in the user
205                documentation part.
206              </para>
207              <example id="write_docbook_doc.examples.include_chapter">
208                <title>Include a chapter</title>
209                  <programlisting>
210&lt;part id="userdoc"&gt;
211   &lt;title&gt;User documentation&lt;/title&gt;
212   &lt;include file= "about.xml"/&gt;
213   &lt;include file="webclient.xml"/&gt;
214   &lt;include file="project_permission.xml"/&gt;
215   &lt;include file="trashcan.xml"/&gt;
216   &lt;include file="file_system.xml"/&gt;
217   &lt;include file="jobs.xml"/&gt;
218   &lt;include file="reporters.xml"/&gt;
219   &lt;include file="annotations.xml"/&gt;
220   &lt;include file="protocols.xml"/&gt;
221   &lt;include file="hardware.xml"/&gt;
222   <userinput>&lt;include file="example_chapter.xml"/&gt;</userinput>
223   &lt;include file="software.xml"/&gt;
224   &lt;include file="array_lims.xml"/&gt;
225   &lt;include file="biomaterials.xml"/&gt;
226   &lt;include file="experiments_analysis.xml"/&gt;
227   &lt;include file="import_export_data.xml"/&gt;
228&lt;/part&gt;
229                  </programlisting>
230                </example>
231              <note>
232                <title>Order of chapters</title>
233                <para>
234                  The chapters will come in the same order as they are included in
235                  the index file.
236                </para>
237              </note>
238            </listitem>     
239          </orderedlist>
240          Now it's only to go ahead with the documentation writing.
241        </para>
242      </sect3>
243    </sect2>
244    <sect2 id="write_docbook_doc.begin.id">
245      <title>
246        The
247        <sgmltag class="attribute">id</sgmltag>
248        attribute
249      </title>
250      <para>
251        Common to all elements is that they have an id attribute that can have an unique value to identify the
252        element with. Most of the elements that are used inside the BASE2 documentation don't
253        need to have an id if they don't are used in any cross references from other part of
254        the text.
255      </para>
256      <para>
257        There are however some elements that always should have the
258        <sgmltag class="attribute">id</sgmltag>
259        set. Which these elements are and how the
260        <sgmltag class="attribute">id</sgmltag>
261        should look like for each one of those is described below. All ids should be as
262        short as possible and associated to the current element. The
263        <sgmltag class="attribute">id</sgmltag>
264        value should only consist of the lowercase characters a-z, '_' instead of blank
265        spaces and '.' to symbolize the different levels in the document.
266        <variablelist>
267          <varlistentry>
268            <term>chapter</term>
269            <listitem>
270              <para>
271                The chapter should have an
272                <sgmltag class="attribute">id</sgmltag>
273                that is identical or almost identical to the chapter's title.
274                <synopsis>chapter_title</synopsis>
275              </para>
276            </listitem>
277          </varlistentry>
278          <varlistentry>
279            <term>sect1-sect5</term>
280            <listitem>
281              <para>
282                The creation of a section's id is done by using the upper level's id
283                and add the section's title or a part of the title. For
284                &lt;sect2&gt; it should be like this;
285                <synopsis>chapter_title.sect1_title.sect2_title</synopsis>
286              </para>
287            </listitem>
288          </varlistentry>
289          <varlistentry>
290            <term>examples</term>
291            <listitem>
292              <para>
293                The naming of an example's
294                <sgmltag class="attribute">id</sgmltag>
295                is a bit different compare to the chapter's and section's id. It
296                should begin with the chapter's id followed by
297                <userinput>examples</userinput>
298                and the caption of the example.
299                <synopsis>chapter_title.examples.example_caption</synopsis>
300              </para>
301            </listitem>
302          </varlistentry>
303          <varlistentry>
304            <term>figures</term>
305            <listitem>
306              <para>
307                The figure's
308                <sgmltag class="attribute">id</sgmltag>
309                should have the following layout
310                <synopsis>chapter_title.figures.figure_name</synopsis>
311              </para>
312            </listitem>
313          </varlistentry>
314        </variablelist>
315      </para>
316    </sect2>
317    <sect2 id="write_docbook_doc.begin.helptext">
318      <title>Mark help texts</title>
319      <para>
320        The parts of the text that also should be used as help texts in the web must be
321        inside
322        <sgmltag>helptext</sgmltag>
323        tags.These texts will be exported to a XML-file at the same time as the
324        HTML-documentation is generated.The generated XML-file is compatible with the help
325        text importer in BASE2 and will be imported when running the update script or
326        installation script.
327      </para>
328      <note>
329      <para>
330        The
331        <sgmltag class="starttag">helptext</sgmltag>
332        must be outside the
333        <sgmltag>para</sgmltag>
334        tag but inside a
335        <sgmltag>sect1</sgmltag>
336        tag to work properly.
337      </para>
338      </note>
339      <para>
340        Each tag requires two different attributes
341        <variablelist>
342          <varlistentry>
343            <term>
344              <sgmltag class="attribute">external_id</sgmltag>
345            </term>
346            <listitem>
347              <para>
348                is used to identify and to find a help text in the web client.
349                BASE2's web client already has a several of IDs to help texts that
350                are defined, it could therefore be a good idea to have a look in the
351                program to see if there already is an external id to use for the
352                particular help text.
353              </para>
354            </listitem>
355          </varlistentry>
356          <varlistentry>
357            <term>
358              <sgmltag class="attribute">title</sgmltag>
359            </term>
360            <listitem>
361              <para>
362                is directly connected to the name/title property for a help text
363                item in BASE2.
364              </para>
365            </listitem>
366          </varlistentry>
367        </variablelist>
368      </para>
369      <example id="write_docbook_doc.examples.helptexttag">
370        <title>How to use the help text tag</title>
371        <programlisting>
372&lt;sect1&gt;
373  &lt;helptext external_id="<replaceable>helptexts.external.id</replaceable>" title="<replaceable>The title</replaceable>"&gt;
374    <replaceable>The text that also should be used as a helptext in the program.</replaceable>
375    &lt;seeother&gt;
376    &lt;other external_id="<replaceable>other.external.id</replaceable>"&gt;
377      <replaceable>Related info here...</replaceable>&lt;/other&gt;
378    &lt;/seeother&gt;
379  &lt;/helptext&gt;
380&lt;/sect1&gt;
381        </programlisting>
382      </example>
383     
384      <para>
385        You can use <sgmltag>seeother</sgmltag> and <sgmltag>other</sgmltag>
386        to create links between different help texts. The <sgmltag>seeother</sgmltag>
387        tag doesn't have any attributes and is just a container for one or more
388        <sgmltag>other</sgmltag> tags. Each tag requires a single attribute.
389      </para>
390        <variablelist>
391          <varlistentry>
392            <term>
393              <sgmltag class="attribute">external_id</sgmltag>
394            </term>
395            <listitem>
396              <para>
397                The external ID of the other help text to link to.
398              </para>
399            </listitem>
400          </varlistentry>
401        </variablelist>
402       
403     
404      <para>
405        Import the generated XML-file manually by uploading it from the
406        <filename class="directory">data</filename>
407        directory to the BASE-server's file system and then use the help text importer
408        plugin to import the help text items from that file.
409      </para>
410     
411      <para>
412        The help texts can also be imported by running the TestHelp
413        test program. In short, here are the commands you need to
414        import the help texts:
415      </para>
416     
417      <programlisting>
418ant docbook
419ant test
420cd build/test
421./run.sh TestHelp
422</programlisting>
423     
424    </sect2>
425    <sect2 id="write_docbook_doc.begin.generate">
426      <title>Generate the document</title>
427      <para>
428        There are two different types of format that is generated from the documentation
429        source. The format to view the documentation on-line will be the one with chunked
430        HTML pages where each chapter and section of first level are on separate
431        pages/files. The other format is a PDF-file that are most useful for printing and
432        distribution. Those two types of output are generated with the ant-target:
433        <userinput>ant docbook</userinput>
434        . This documentation is also generated with
435        <command>ant dist</command>
436        , which will put the output files in the right location for distribution.
437      </para>
438    </sect2>
439  </sect1>
440
441  <sect1 id="write_docbook_doc.usedtags">
442    <title>Elements to use</title>
443    <para>
444      The purpose with this section is to give an overview of those docbook elements that are
445      most common in this documentation and to give some example on how they should be used.
446      There will not be any detailed explanation of the tags here, instead the reader is
447      recommended to get more information from
448      <ulink url="http://www.docbook.org/tdg/en/html/docbook.html">
449        Docbook's documentation
450      </ulink>
451      or other references.
452    </para>
453    <sect2 id="write_docbook_doc.usedtags.text">
454      <title>Text elements</title>
455      <para>
456       
457      </para>
458      <informaltable frame="none">
459        <tgroup cols="3" rowsep="1" colsep="1">
460          <colspec align="left" />
461          <colspec align="center" />
462          <colspec align="left" />
463          <thead>
464            <row>
465              <entry>Define</entry>
466              <entry>Element to use</entry>
467              <entry>Comments</entry>
468            </row>
469          </thead>
470          <tbody>
471            <row>
472              <entry>Chapter</entry>
473              <entry>
474                <sgmltag class="starttag">chapter</sgmltag>
475              </entry>
476              <entry>
477                <para>
478                  See
479                  <xref linkend="write_docbook_doc.examples.chapterbody" />
480                </para>
481              </entry>
482            </row>
483            <row>
484              <entry>Title</entry>
485              <entry>
486                <sgmltag class="starttag">title</sgmltag>
487              </entry>
488              <entry>
489                <xref linkend="write_docbook_doc.examples.chapterbody" />
490                shows how this can be implemented
491              </entry>
492            </row>
493            <row>
494              <entry>Paragraph</entry>
495              <entry>
496                <sgmltag class="starttag">para</sgmltag>
497              </entry>
498              <entry></entry>
499            </row>
500            <row>
501              <entry>Top-level subsection</entry>
502              <entry>
503                <sgmltag class="starttag">sect1</sgmltag>
504              </entry>
505              <entry>
506                See
507                <xref linkend="write_docbook_doc.begin.id" />
508              </entry>
509            </row>
510            <row>
511              <entry>Second level section</entry>
512              <entry>
513                <sgmltag class="starttag">sect2</sgmltag>
514              </entry>
515              <entry>
516                See
517                <xref linkend="write_docbook_doc.begin.id" />
518              </entry>
519            </row>
520            <row>
521              <entry>Third level section</entry>
522              <entry>
523                <sgmltag class="starttag">sect3</sgmltag>
524              </entry>
525              <entry>
526                See
527                <xref linkend="write_docbook_doc.begin.id" />
528              </entry>
529            </row>
530            <row>
531              <entry>Fourth level section</entry>
532              <entry>
533                <sgmltag class="starttag">sect3</sgmltag>
534              </entry>
535              <entry></entry>
536            </row>
537            <row>
538              <entry>Fith level section</entry>
539              <entry>
540                <sgmltag class="starttag">sect3</sgmltag>
541              </entry>
542              <entry></entry>
543            </row>
544          </tbody>
545        </tgroup>
546      </informaltable>
547
548      <sect3 id="write_docbook_doc.usedtags.text.keywords">
549        <title>Markup special words and phrases</title>
550        <para>
551          These elements should be used to mark up words and phrases that have a special
552          meaning, like method names, class names and user inputs just to mention some.
553        </para>
554        <informaltable frame="none">
555          <tgroup cols="3" rowsep="1" colsep="1">
556            <colspec align="left" />
557            <colspec align="center" />
558            <colspec align="left" />
559            <thead>
560              <row>
561                <entry>Define</entry>
562                <entry>Element to use</entry>
563                <entry>Comment</entry>
564              </row>
565            </thead>
566            <tbody>
567              <row>
568                <entry>Class name</entry>
569                <entry>
570                  <sgmltag class="starttag">classname</sgmltag>
571                </entry>
572                <entry></entry>
573              </row>
574              <row>
575                <entry>User input</entry>
576                <entry>
577                  <sgmltag class="starttag">userinput</sgmltag>
578                </entry>
579                <entry></entry>
580              </row>
581              <row>
582                <entry>Variable name</entry>
583                <entry>
584                  <sgmltag class="starttag">varname</sgmltag>
585                </entry>
586                <entry></entry>
587              </row>
588              <row>
589                <entry>Constant</entry>
590                <entry>
591                  <sgmltag class="starttag">constant</sgmltag>
592                </entry>
593                <entry></entry>
594              </row>
595              <row>
596                <entry>Method definition</entry>
597                <entry>
598                  <sgmltag class="starttag">methodsynopsis</sgmltag>
599                </entry>
600                <entry>
601                  See
602                  <xref linkend="write_docbook_doc.examples.methodimpl" />
603                </entry>
604              </row>
605              <row>
606                <entry>Modifier of a method</entry>
607                <entry>
608                  <sgmltag class="starttag">modifier</sgmltag>
609                </entry>
610                <entry>
611                  See
612                  <xref linkend="write_docbook_doc.examples.methodimpl" />
613                </entry>
614              </row>
615              <row>
616                <entry>Classification of return value</entry>
617                <entry>
618                  <sgmltag class="starttag">type</sgmltag>
619                </entry>
620                <entry>
621                  See
622                  <xref linkend="write_docbook_doc.examples.methodimpl" />
623                </entry>
624              </row>
625              <row>
626                <entry>Method name</entry>
627                <entry>
628                  <sgmltag class="starttag">methodname</sgmltag>
629                </entry>
630                <entry>
631                  See
632                  <xref linkend="write_docbook_doc.examples.methodimpl" />
633                </entry>
634              </row>
635              <row>
636                <entry>No parameter/type</entry>
637                <entry>
638                  <sgmltag class="starttag">void</sgmltag>
639                </entry>
640                <entry>
641                  See
642                  <xref linkend="write_docbook_doc.examples.methodimpl" />
643                </entry>
644              </row>
645              <row>
646                <entry>Define a parameter</entry>
647                <entry>
648                  <sgmltag class="starttag">methodparam</sgmltag>
649                </entry>
650                <entry>
651                  See
652                  <xref linkend="write_docbook_doc.examples.methodimpl1" />
653                </entry>
654              </row>
655              <row>
656                <entry>Parameter type</entry>
657                <entry>
658                  <sgmltag class="starttag">type</sgmltag>
659                </entry>
660                <entry>
661                  See
662                  <xref linkend="write_docbook_doc.examples.methodimpl1" />
663                </entry>
664              </row>
665              <row>
666                <entry>Parameter name</entry>
667                <entry>
668                  <sgmltag class="starttag">parameter</sgmltag>
669                </entry>
670                <entry>
671                  See
672                  <xref linkend="write_docbook_doc.examples.methodimpl1" />
673                </entry>
674              </row>
675            </tbody>
676          </tgroup>
677        </informaltable>
678        <para>
679          Follow one of the examples below to insert a method definition in the document.
680        </para>
681        <example id="write_docbook_doc.examples.methodimpl">
682          <title>
683            Method with no arguments and a return value
684          </title>
685          <programlisting>
686&hellip;
687&lt;methodsynopsis language="java"&gt;
688  &lt;modifier&gt;public&lt;/modifier&gt;
689  &lt;type&gt;Plugin.MainType&lt;/type&gt;
690  &lt;methodname&gt;getMainType&lt;/methodname&gt;
691  &lt;void /&gt;
692&lt;/methodsynopsis&gt;
693&hellip;
694          </programlisting>
695        </example>
696        <example id="write_docbook_doc.examples.methodimpl1">
697          <title>
698            Method with arguments and no return value
699          </title>
700          <programlisting>
701&hellip;
702&lt;methodsynopsis language="java"&gt;
703  &lt;modifier&gt;public&lt;/modifier&gt;
704  &lt;void /&gt;
705  &lt;methodname&gt;init&lt;/methodname&gt;
706  &lt;methodparam&gt;
707    &lt;type&gt;SessionControl&lt;/type&gt;
708    &lt;parameter&gt;sc&lt;/parameter&gt;
709  &lt;/methodparam&gt;
710  &lt;methodparam&gt;
711    &lt;type&gt;ParameterValues&lt;/type&gt;
712    &lt;parameter&gt;configuration&lt;/parameter&gt;
713  &lt;/methodparam&gt;
714  &lt;methodparam&gt;
715    &lt;type&gt;ParameterValues&lt;/type&gt;
716    &lt;parameter&gt;job&lt;/parameter&gt;
717  &lt;/methodparam&gt;
718&lt;/methodsynopsis&gt;
719&hellip;
720          </programlisting>
721        </example>
722       
723      </sect3>
724      <sect3 id="write_docbook_doc.usedtags.text.gui">
725        <title>Gui elements</title>
726        <para>
727          Docbook has some elements that can be used to symbolize gui items in a program.
728          Following list contains the ones that are most common in this document.
729        </para>
730        <informaltable frame="none">
731          <tgroup cols="3" rowsep="1" colsep="1">
732            <colspec align="left" />
733            <colspec align="center" />
734            <colspec align="left" />
735            <thead>
736              <row>
737                <entry>Define</entry>
738                <entry>Element to use</entry>
739                <entry>Comment</entry>
740              </row>
741            </thead>
742            <tbody>
743              <row>
744                <entry>Button</entry>
745                <entry>
746                  <sgmltag class="starttag">guibutton</sgmltag>
747                </entry>
748                <entry></entry>
749              </row>
750              <row>
751                <entry>Label</entry>
752                <entry>
753                  <sgmltag class="starttag">guilabel</sgmltag>
754                </entry>
755                <entry></entry>
756              </row>
757              <row>
758                <entry>Menu choice</entry>
759                <entry>
760                  <sgmltag class="starttag">menuchoice</sgmltag>
761                </entry>
762                <entry></entry>
763              </row>
764              <row>
765                <entry>Menu</entry>
766                <entry>
767                  <sgmltag class="starttag">guimenu</sgmltag>
768                </entry>
769                <entry></entry>
770              </row>
771              <row>
772                <entry>Submenu</entry>
773                <entry>
774                  <sgmltag class="starttag">guisubmenu</sgmltag>
775                </entry>
776                <entry></entry>
777              </row>
778              <row>
779                <entry>Menu item</entry>
780                <entry>
781                  <sgmltag class="starttag">guimenuitem</sgmltag>
782                </entry>
783                <entry></entry>
784              </row>
785              <row>
786                <entry>Icon</entry>
787                <entry>
788                  <sgmltag class="starttag">guiicon</sgmltag>
789                </entry>
790                <entry></entry>
791              </row>
792            </tbody>
793          </tgroup>
794        </informaltable>
795        <para>
796          <xref linkend="write_docbook_doc.examples.guielements" />
797          shows how the menu choice in figure
798          <xref linkend="write_docbook_doc.figures.menuchoice" />
799          can be described.
800        </para>
801        <figure id="write_docbook_doc.figures.menuchoice">
802          <title>Menu choice</title>
803          <screenshot>
804            <mediaobject>
805              <imageobject>
806                <imagedata 
807                  contentwidth="7cm" 
808                  width="7cm" 
809                  fileref="figures/menuchoice.png" format="PNG" 
810                />
811              </imageobject>
812            </mediaobject>
813          </screenshot>
814        </figure>
815        <example id="write_docbook_doc.examples.guielements">
816          <title>Describe a menu choice</title>
817          <programlisting>
818&hellip;         
819&lt;menuchoice&gt;
820  &lt;guimenu&gt;Administrate&lt;/guimenu&gt;
821  &lt;guisubmenu&gt;Plugins&lt;/guisubmenu&gt;
822  &lt;guimenuitem&gt;Types&lt;/guimenuitem&gt;
823&lt;/menuchoice&gt;
824&hellip;
825          </programlisting>
826          <para>
827            In the text it will look like this:
828            <menuchoice>
829              <guimenu>Administrate</guimenu>
830              <guisubmenu>Plugins</guisubmenu>
831              <guimenuitem>Types</guimenuitem>
832            </menuchoice>
833          </para>
834        </example>
835      </sect3>
836    </sect2>
837    <sect2 id="write_docbook_doc.usedtags.images">
838      <title>Images and figures</title>
839      <para>
840        Images and figures are normally implemented like the following example. The
841        image-file must be located in
842        <filename class="directory">doc/src/docbook/figures</filename>
843        ,otherwise the image won't be visible in the generated output files.
844      </para>
845      <warning>
846        <para>
847          Images in the pdf-output are, unlike images in html-output, not scaled and can
848          therefore be out of proportion in the document. Avoid this by e.g. setting the
849          attributes
850          <sgmltag class="attribute">contentwidth</sgmltag>
851          and
852          <sgmltag class="attribute">width</sgmltag>
853          in
854          <sgmltag>imagedata</sgmltag>
855          to appropriate values.
856        </para>
857      </warning>
858      <example id="write_docbook_doc.examples.screenshot">
859        <title>Screen-shot in the documentation</title>
860        <para>
861          <xref linkend="write_docbook_doc.figures.menuchoice" />
862          is implemented with the following code
863        </para>
864        <programlisting>
865&lt;figure id="write_docbook_doc.figures.menuchoice"&gt;
866  &lt;title&gt;Menu choice&lt;/title&gt;
867  &lt;screenshot&gt;
868    &lt;mediaobject&gt;
869      &lt;imageobject&gt;
870        &lt;imagedata
871          contentwidth="7cm"
872          width="7cm"
873          fileref="figures/menuchoice.png" format="PNG"
874        /&gt;
875      &lt;/imageobject&gt;
876    &lt;/mediaobject&gt;
877  &lt;/screenshot&gt;
878&lt;/figure&gt;
879        </programlisting>
880      </example>
881    </sect2>
882    <sect2 id="write_docbook_doc.usedtags.examples">
883      <title>Examples and program listing</title>
884      <para>
885        Following describes how to insert an example in the documentation.The examples in
886        this document are often some kind of program listing but they can still be examples
887        of something else.
888      </para>
889      <warning>
890        <para>
891          More then 80 characters(including indention) in a row of program
892          listings or other verbatim elements will risk to put the end of the row outside
893          the text area.
894        </para>
895      </warning>
896      <example id="write_docbook_doc.examples.example">
897        <title>Example in the documentation</title>
898        <para>
899          This shows how 
900          <xref linkend="net.sf.basedb.core.plugin.Plugin.getAbout" />
901          is written in the corresponding XML-file.
902        </para>
903        <programlisting>
904  &hellip;
905  &lt;example id="net.sf.basedb.core.plugin.Plugin.getAbout"&gt;
906     &lt;title&gt;A typical implementation stores this information in a static field&lt;/title&gt;
907     &lt;programlisting&gt;
908private static final About about = new AboutImpl
909(
910   "Spot images creator",
911   "Converts a full-size scanned image into smaller preview jpg " +
912   "images for each individual spot.",
913   "2.0",
914   "2006, Department of Theoretical Physics, Lund University",
915   null,
916   "base@thep.lu.se",
917   "http://base.thep.lu.se"
918);
919 
920public About getAbout()
921{
922   return about;
923}
924     &lt;/programlisting&gt;
925  &lt;/example&gt;
926  &hellip;
927        </programlisting>
928      </example>     
929    </sect2>
930    <sect2 id="write_docbook_doc.usedtags.admonitions">
931      <title>Admonitions</title>
932      <para>
933        The admonitions that are used in this document can be found in the table below.
934      </para>
935      <informaltable frame="none">
936        <tgroup cols="3" rowsep="1" colsep="1">
937          <colspec align="left" />
938          <colspec align="center" />
939          <colspec align="left" />
940          <thead>
941            <row>
942              <entry>Define</entry>
943              <entry>Element to use</entry>
944              <entry>Comment</entry>
945            </row>
946          </thead>
947          <tbody>
948            <row>
949              <entry>Warning text</entry>
950              <entry>
951                <sgmltag class="starttag">warning</sgmltag>
952              </entry>
953              <entry></entry>
954            </row>
955            <row>
956              <entry>Notification text</entry>
957              <entry>
958                <sgmltag class="starttag">note</sgmltag>
959              </entry>
960              <entry></entry>
961            </row>
962            <row>
963              <entry>A tip</entry>
964              <entry>
965                <sgmltag class="starttag">tip</sgmltag>
966              </entry>
967              <entry></entry>
968            </row>
969            <row>
970              <entry>Important text</entry>
971              <entry>
972                <sgmltag class="starttag">important</sgmltag>
973              </entry>
974              <entry></entry>
975            </row>
976            <row>
977              <entry>Something to be cautious about</entry>
978              <entry>
979                <sgmltag class="starttag">caution</sgmltag>
980              </entry>
981              <entry></entry>
982            </row>
983          </tbody>
984        </tgroup>
985      </informaltable>
986    </sect2>
987    <sect2 id="write_docbook_doc.usedtags.lists">
988      <title>Lists</title>
989      <para>
990        Following items can be used to define different kind of lists in the documentation.
991        Some common elements for the lists are also described here.
992      </para>
993      <informaltable frame="none">
994        <tgroup cols="3" rowsep="1" colsep="1">
995          <colspec align="left" />
996          <colspec align="center" />
997          <colspec align="left" />
998          <thead>
999            <row>
1000              <entry>Define</entry>
1001              <entry>Element</entry>
1002              <entry>Comment</entry>
1003            </row>
1004          </thead>
1005          <tbody>           
1006            <row>
1007              <entry>None-ordered list</entry>
1008              <entry>
1009                <sgmltag class="starttag">itemizedlist</sgmltag>
1010              </entry>
1011              <entry></entry>
1012            </row>
1013            <row>
1014              <entry>Term definition list</entry>
1015              <entry>
1016                <sgmltag class="starttag">variablelist</sgmltag>
1017              </entry>
1018              <entry></entry>
1019            </row>
1020            <row>
1021              <entry>Ordered list</entry>
1022              <entry>
1023                <sgmltag class="starttag">orderedlist</sgmltag>
1024              </entry>
1025              <entry></entry>
1026            </row>
1027            <row>
1028              <entry>List item</entry>
1029              <entry>
1030                <sgmltag class="starttag">listitem</sgmltag>
1031              </entry>
1032              <entry></entry>
1033            </row>
1034          </tbody>
1035        </tgroup>
1036      </informaltable>
1037      <para>The example below shows how to create a list for term definition in the text.</para>
1038      <example id="write_docbook_doc.examples.variablelist">
1039        <title>Example how to write a variable list</title>
1040        <programlisting>
1041&hellip;
1042&lt;variablelist&gt;
1043   &lt;varlistentry&gt;
1044      &lt;term&gt;Term1&lt;/term&gt;
1045      &lt;listitem&gt;
1046         &lt;para&gt;
1047            Definition/explanation of the term
1048         &lt;/para&gt;
1049      &lt;/listitem&gt;
1050   &lt;/varlistentry&gt;
1051   
1052   &lt;varlistentry&gt;
1053      &lt;term&gt;Term2&lt;/term&gt;
1054      &lt;listitem&gt;
1055         &lt;para&gt;
1056            Definition/explanation of the term
1057         &lt;/para&gt;
1058      &lt;/listitem&gt;
1059   &lt;/varlistentry&gt;
1060&lt;/variablelist&gt;
1061        </programlisting>
1062      </example>
1063    </sect2>
1064  </sect1>
1065</chapter>
Note: See TracBrowser for help on using the repository browser.