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

Last change on this file since 3305 was 3305, checked in by Nicklas Nordborg, 16 years ago

Added option to not include <helptext> sections in the HTML or PDF documentation.
File size: 37.4 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   
245    <sect2 id="write_docbook_doc.begin.chunking">
246      <title>Controlling chunking</title>
247      <para>
248        We have configured docbook to create a new output file for
249        each new <sgmltag class="starttag">chapter</sgmltag>
250        and <sgmltag class="starttag">sect1</sgmltag>. In most cases this
251        gives each page a relatively good size. Not too long and not too short.
252        However, if a chapter contains many small <sgmltag class="starttag">sect1</sgmltag>
253        sections (for example, <xref linkend="resources"/>), you end up with many
254        pages with just a few lines of text on each page. This is not so
255        good and can be avoided by adding a <sgmltag class="attribute">chunked = "0"</sgmltag>
256        attribute to the chapter, for example:
257      </para>
258      <programlisting>
259&lt;chapter id="resources" chunked="0"&gt;
260</programlisting>
261      <para>
262        This will stop the chunking of <sgmltag class="starttag">sect1</sgmltag>
263        sections in this chapter. On the other
264        hand, if you have a <sgmltag class="starttag">sect1</sgmltag>
265        that contains many long <sgmltag class="starttag">sect2</sgmltag>
266        sections you might want to put each <sgmltag class="starttag">sect2</sgmltag>
267        section in a separate chunk. If you want to do this:
268      </para>
269      <programlisting>
270&lt;sect1 id="sect.with.large.sect2" chunked="1"&gt;
271</programlisting>
272   
273    </sect2>
274   
275    <sect2 id="write_docbook_doc.begin.id">
276      <title>
277        The
278        <sgmltag class="attribute">id</sgmltag>
279        attribute
280      </title>
281      <para>
282        Common to all elements is that they have an id attribute that can have an unique value to identify the
283        element with. Most of the elements that are used inside the BASE2 documentation don't
284        need to have an id if they don't are used in any cross references from other part of
285        the text.
286      </para>
287      <para>
288        There are however some elements that always should have the
289        <sgmltag class="attribute">id</sgmltag>
290        set. Which these elements are and how the
291        <sgmltag class="attribute">id</sgmltag>
292        should look like for each one of those is described below. All ids should be as
293        short as possible and associated to the current element. The
294        <sgmltag class="attribute">id</sgmltag>
295        value should only consist of the lowercase characters a-z, '_' instead of blank
296        spaces and '.' to symbolize the different levels in the document.
297        <variablelist>
298          <varlistentry>
299            <term>chapter</term>
300            <listitem>
301              <para>
302                The chapter should have an
303                <sgmltag class="attribute">id</sgmltag>
304                that is identical or almost identical to the chapter's title.
305                <synopsis>chapter_title</synopsis>
306              </para>
307            </listitem>
308          </varlistentry>
309          <varlistentry>
310            <term>sect1-sect5</term>
311            <listitem>
312              <para>
313                The creation of a section's id is done by using the upper level's id
314                and add the section's title or a part of the title. For
315                &lt;sect2&gt; it should be like this;
316                <synopsis>chapter_title.sect1_title.sect2_title</synopsis>
317              </para>
318            </listitem>
319          </varlistentry>
320          <varlistentry>
321            <term>examples</term>
322            <listitem>
323              <para>
324                The naming of an example's
325                <sgmltag class="attribute">id</sgmltag>
326                is a bit different compare to the chapter's and section's id. It
327                should begin with the chapter's id followed by
328                <userinput>examples</userinput>
329                and the caption of the example.
330                <synopsis>chapter_title.examples.example_caption</synopsis>
331              </para>
332            </listitem>
333          </varlistentry>
334          <varlistentry>
335            <term>figures</term>
336            <listitem>
337              <para>
338                The figure's
339                <sgmltag class="attribute">id</sgmltag>
340                should have the following layout
341                <synopsis>chapter_title.figures.figure_name</synopsis>
342              </para>
343            </listitem>
344          </varlistentry>
345        </variablelist>
346      </para>
347    </sect2>
348    <sect2 id="write_docbook_doc.begin.helptext">
349      <title>Mark help texts</title>
350      <para>
351        The parts of the text that also should be used as help texts in the web must be
352        inside
353        <sgmltag class="starttag">helptext</sgmltag>
354        tags. These texts will be exported to a XML-file at the same time as the
355        HTML-documentation is generated. The generated XML-file is compatible with the help
356        text importer in BASE2 and will be imported when running the update script or
357        installation script.
358      </para>
359      <note>
360      <para>
361        The
362        <sgmltag class="starttag">helptext</sgmltag>
363        must be outside the
364        <sgmltag>para</sgmltag>
365        tag but inside a
366        <sgmltag>sect1</sgmltag>
367        tag to work properly.
368      </para>
369      </note>
370      <para>
371        The tag supports the following attributes
372        <variablelist>
373          <varlistentry>
374            <term>
375              <sgmltag class="attribute">external_id</sgmltag>
376            </term>
377            <listitem>
378              <para>
379                Is used to identify and to find a help text in the web client.
380                BASE2's web client already has several IDs to help texts defined,
381                it could therefore be a good idea to have a look in the
382                program to see if there already is an external id to use for the
383                particular help text.
384              </para>
385            </listitem>
386          </varlistentry>
387          <varlistentry>
388            <term>
389              <sgmltag class="attribute">title</sgmltag>
390            </term>
391            <listitem>
392              <para>
393                Is directly connected to the name/title property for a help text
394                item in BASE2.
395              </para>
396            </listitem>
397          </varlistentry>
398          <varlistentry>
399            <term>
400              <sgmltag class="attribute">webonly</sgmltag>
401            </term>
402            <listitem>
403              <para>
404                If set to a non-zero value, the contents of the tag
405                will not be outputted in the HTML or PDF documentation.
406                This is useful for minor functionality that is not
407                important enough to be mentioned in the documentation but has
408                a help icon in the web client.
409              </para>
410            </listitem>
411          </varlistentry>
412        </variablelist>
413      </para>
414      <example id="write_docbook_doc.examples.helptexttag">
415        <title>How to use the help text tag</title>
416        <programlisting>
417&lt;sect1&gt;
418  &lt;helptext external_id="<replaceable>helptexts.external.id</replaceable>" title="<replaceable>The title</replaceable>"&gt;
419    <replaceable>The text that also should be used as a helptext in the program.</replaceable>
420    &lt;seeother&gt;
421    &lt;other external_id="<replaceable>other.external.id</replaceable>"&gt;
422      <replaceable>Related info here...</replaceable>&lt;/other&gt;
423    &lt;/seeother&gt;
424  &lt;/helptext&gt;
425&lt;/sect1&gt;
426        </programlisting>
427      </example>
428     
429      <para>
430        You can use <sgmltag>seeother</sgmltag> and <sgmltag>other</sgmltag>
431        to create links between different help texts. The <sgmltag>seeother</sgmltag>
432        tag doesn't have any attributes and is just a container for one or more
433        <sgmltag>other</sgmltag> tags. Each tag requires a single attribute.
434      </para>
435        <variablelist>
436          <varlistentry>
437            <term>
438              <sgmltag class="attribute">external_id</sgmltag>
439            </term>
440            <listitem>
441              <para>
442                The external ID of the other help text to link to.
443              </para>
444            </listitem>
445          </varlistentry>
446        </variablelist>
447       
448     
449      <para>
450        Import the generated XML-file manually by uploading it from the
451        <filename class="directory">data</filename>
452        directory to the BASE-server's file system and then use the help text importer
453        plugin to import the help text items from that file.
454      </para>
455     
456      <para>
457        The help texts can also be imported by running the TestHelp
458        test program. In short, here are the commands you need to
459        import the help texts:
460      </para>
461     
462      <programlisting>
463ant docbook
464ant test
465cd build/test
466./run.sh TestHelp
467</programlisting>
468     
469    </sect2>
470    <sect2 id="write_docbook_doc.begin.generate">
471      <title>Generate output</title>
472
473      <sect3 id="write_docbook_doc.begin.generate.requirements">
474        <title>Requirements</title>
475        <para>
476          Those who have checked out the documentation source from repository or got the
477          source from a distribution package needs to compile it to get the pdf and html
478          documentation files. The compilation of the documentation source requires, beside Ant, that the XML-parser
479          Xsltproc is installed on the local computer. XsltProc and how it is installed, can
480          be found at
481          <ulink url="http://xmlsoft.org/XSLT/index.html"></ulink>.
482        </para>
483        <note>
484          <para>
485            There is an xml-parser in newer java-versions that can be used instead of
486            XsltProc but the compilation will most likely take much much longer time.
487            Therefore it's not recommended to be used when generating/compiling the
488            documentation in BASE 2.
489          </para>
490        </note>
491      </sect3>
492      <sect3 id="write_docbook_doc.begin.generate.compile">
493        <title>Compile - generate output files</title>
494        <para>
495          There are two different types of format that is generated from the documentation
496          source. The format to view the documentation on-line will be the one with
497          chunked HTML pages where each chapter and section of first level are on separate
498          pages/files. The other format is a PDF-file that are most useful for printing
499          and distribution. Those two types of output are generated with the ant-target:
500          <command>ant docbook</command>
501          . This documentation is also generated with
502          <command>ant dist</command>
503          , which will put the output files in the right location for distribution with
504          BASE 2.
505        </para>
506      </sect3>
507    </sect2>
508  </sect1>
509
510  <sect1 id="write_docbook_doc.usedtags">
511    <title>Elements to use</title>
512    <para>
513      The purpose with this section is to give an overview of those docbook elements that are
514      most common in this documentation and to give some example on how they should be used.
515      There will not be any detailed explanation of the tags here, instead the reader is
516      recommended to get more information from
517      <ulink url="http://www.docbook.org/tdg/en/html/docbook.html">
518        Docbook's documentation
519      </ulink>
520      or other references.
521    </para>
522    <sect2 id="write_docbook_doc.usedtags.text">
523      <title>Text elements</title>
524      <para>
525       
526      </para>
527      <informaltable frame="none">
528        <tgroup cols="3" rowsep="1" colsep="1">
529          <colspec align="left" />
530          <colspec align="center" />
531          <colspec align="left" />
532          <thead>
533            <row>
534              <entry>Define</entry>
535              <entry>Element to use</entry>
536              <entry>Comments</entry>
537            </row>
538          </thead>
539          <tbody>
540            <row>
541              <entry>Chapter</entry>
542              <entry>
543                <sgmltag class="starttag">chapter</sgmltag>
544              </entry>
545              <entry>
546                <para>
547                  See
548                  <xref linkend="write_docbook_doc.examples.chapterbody" />
549                </para>
550              </entry>
551            </row>
552            <row>
553              <entry>Title</entry>
554              <entry>
555                <sgmltag class="starttag">title</sgmltag>
556              </entry>
557              <entry>
558                <xref linkend="write_docbook_doc.examples.chapterbody" />
559                shows how this can be implemented
560              </entry>
561            </row>
562            <row>
563              <entry>Paragraph</entry>
564              <entry>
565                <sgmltag class="starttag">para</sgmltag>
566              </entry>
567              <entry></entry>
568            </row>
569            <row>
570              <entry>Top-level subsection</entry>
571              <entry>
572                <sgmltag class="starttag">sect1</sgmltag>
573              </entry>
574              <entry>
575                See
576                <xref linkend="write_docbook_doc.begin.id" />
577              </entry>
578            </row>
579            <row>
580              <entry>Second level section</entry>
581              <entry>
582                <sgmltag class="starttag">sect2</sgmltag>
583              </entry>
584              <entry>
585                See
586                <xref linkend="write_docbook_doc.begin.id" />
587              </entry>
588            </row>
589            <row>
590              <entry>Third level section</entry>
591              <entry>
592                <sgmltag class="starttag">sect3</sgmltag>
593              </entry>
594              <entry>
595                See
596                <xref linkend="write_docbook_doc.begin.id" />
597              </entry>
598            </row>
599            <row>
600              <entry>Fourth level section</entry>
601              <entry>
602                <sgmltag class="starttag">sect3</sgmltag>
603              </entry>
604              <entry></entry>
605            </row>
606            <row>
607              <entry>Fith level section</entry>
608              <entry>
609                <sgmltag class="starttag">sect3</sgmltag>
610              </entry>
611              <entry></entry>
612            </row>
613          </tbody>
614        </tgroup>
615      </informaltable>
616
617      <sect3 id="write_docbook_doc.usedtags.text.keywords">
618        <title>Markup special words and phrases</title>
619        <para>
620          These elements should be used to mark up words and phrases that have a special
621          meaning, like method names, class names and user inputs just to mention some.
622        </para>
623        <informaltable frame="none">
624          <tgroup cols="3" rowsep="1" colsep="1">
625            <colspec align="left" />
626            <colspec align="center" />
627            <colspec align="left" />
628            <thead>
629              <row>
630                <entry>Define</entry>
631                <entry>Element to use</entry>
632                <entry>Comment</entry>
633              </row>
634            </thead>
635            <tbody>
636              <row>
637                <entry>Class name</entry>
638                <entry>
639                  <sgmltag class="starttag">classname</sgmltag>
640                </entry>
641                <entry></entry>
642              </row>
643              <row>
644                <entry>User input</entry>
645                <entry>
646                  <sgmltag class="starttag">userinput</sgmltag>
647                </entry>
648                <entry></entry>
649              </row>
650              <row>
651                <entry>Variable name</entry>
652                <entry>
653                  <sgmltag class="starttag">varname</sgmltag>
654                </entry>
655                <entry></entry>
656              </row>
657              <row>
658                <entry>Constant</entry>
659                <entry>
660                  <sgmltag class="starttag">constant</sgmltag>
661                </entry>
662                <entry></entry>
663              </row>
664              <row>
665                <entry>Method definition</entry>
666                <entry>
667                  <sgmltag class="starttag">methodsynopsis</sgmltag>
668                </entry>
669                <entry>
670                  See
671                  <xref linkend="write_docbook_doc.examples.methodimpl" />
672                </entry>
673              </row>
674              <row>
675                <entry>Modifier of a method</entry>
676                <entry>
677                  <sgmltag class="starttag">modifier</sgmltag>
678                </entry>
679                <entry>
680                  See
681                  <xref linkend="write_docbook_doc.examples.methodimpl" />
682                </entry>
683              </row>
684              <row>
685                <entry>Classification of return value</entry>
686                <entry>
687                  <sgmltag class="starttag">type</sgmltag>
688                </entry>
689                <entry>
690                  See
691                  <xref linkend="write_docbook_doc.examples.methodimpl" />
692                </entry>
693              </row>
694              <row>
695                <entry>Method name</entry>
696                <entry>
697                  <sgmltag class="starttag">methodname</sgmltag>
698                </entry>
699                <entry>
700                  See
701                  <xref linkend="write_docbook_doc.examples.methodimpl" />
702                </entry>
703              </row>
704              <row>
705                <entry>No parameter/type</entry>
706                <entry>
707                  <sgmltag class="starttag">void</sgmltag>
708                </entry>
709                <entry>
710                  See
711                  <xref linkend="write_docbook_doc.examples.methodimpl" />
712                </entry>
713              </row>
714              <row>
715                <entry>Define a parameter</entry>
716                <entry>
717                  <sgmltag class="starttag">methodparam</sgmltag>
718                </entry>
719                <entry>
720                  See
721                  <xref linkend="write_docbook_doc.examples.methodimpl1" />
722                </entry>
723              </row>
724              <row>
725                <entry>Parameter type</entry>
726                <entry>
727                  <sgmltag class="starttag">type</sgmltag>
728                </entry>
729                <entry>
730                  See
731                  <xref linkend="write_docbook_doc.examples.methodimpl1" />
732                </entry>
733              </row>
734              <row>
735                <entry>Parameter name</entry>
736                <entry>
737                  <sgmltag class="starttag">parameter</sgmltag>
738                </entry>
739                <entry>
740                  See
741                  <xref linkend="write_docbook_doc.examples.methodimpl1" />
742                </entry>
743              </row>
744            </tbody>
745          </tgroup>
746        </informaltable>
747        <para>
748          Follow one of the examples below to insert a method definition in the document.
749        </para>
750        <example id="write_docbook_doc.examples.methodimpl">
751          <title>
752            Method with no arguments and a return value
753          </title>
754          <programlisting>
755&hellip;
756&lt;methodsynopsis language="java"&gt;
757  &lt;modifier&gt;public&lt;/modifier&gt;
758  &lt;type&gt;Plugin.MainType&lt;/type&gt;
759  &lt;methodname&gt;getMainType&lt;/methodname&gt;
760  &lt;void /&gt;
761&lt;/methodsynopsis&gt;
762&hellip;
763          </programlisting>
764        </example>
765        <example id="write_docbook_doc.examples.methodimpl1">
766          <title>
767            Method with arguments and no return value
768          </title>
769          <programlisting>
770&hellip;
771&lt;methodsynopsis language="java"&gt;
772  &lt;modifier&gt;public&lt;/modifier&gt;
773  &lt;void /&gt;
774  &lt;methodname&gt;init&lt;/methodname&gt;
775  &lt;methodparam&gt;
776    &lt;type&gt;SessionControl&lt;/type&gt;
777    &lt;parameter&gt;sc&lt;/parameter&gt;
778  &lt;/methodparam&gt;
779  &lt;methodparam&gt;
780    &lt;type&gt;ParameterValues&lt;/type&gt;
781    &lt;parameter&gt;configuration&lt;/parameter&gt;
782  &lt;/methodparam&gt;
783  &lt;methodparam&gt;
784    &lt;type&gt;ParameterValues&lt;/type&gt;
785    &lt;parameter&gt;job&lt;/parameter&gt;
786  &lt;/methodparam&gt;
787&lt;/methodsynopsis&gt;
788&hellip;
789          </programlisting>
790        </example>
791       
792      </sect3>
793      <sect3 id="write_docbook_doc.usedtags.text.gui">
794        <title>Gui elements</title>
795        <para>
796          Docbook has some elements that can be used to symbolize gui items in a program.
797          Following list contains the ones that are most common in this document.
798        </para>
799        <informaltable frame="none">
800          <tgroup cols="3" rowsep="1" colsep="1">
801            <colspec align="left" />
802            <colspec align="center" />
803            <colspec align="left" />
804            <thead>
805              <row>
806                <entry>Define</entry>
807                <entry>Element to use</entry>
808                <entry>Comment</entry>
809              </row>
810            </thead>
811            <tbody>
812              <row>
813                <entry>Button</entry>
814                <entry>
815                  <sgmltag class="starttag">guibutton</sgmltag>
816                </entry>
817                <entry></entry>
818              </row>
819              <row>
820                <entry>Label</entry>
821                <entry>
822                  <sgmltag class="starttag">guilabel</sgmltag>
823                </entry>
824                <entry></entry>
825              </row>
826              <row>
827                <entry>Menu choice</entry>
828                <entry>
829                  <sgmltag class="starttag">menuchoice</sgmltag>
830                </entry>
831                <entry></entry>
832              </row>
833              <row>
834                <entry>Menu</entry>
835                <entry>
836                  <sgmltag class="starttag">guimenu</sgmltag>
837                </entry>
838                <entry></entry>
839              </row>
840              <row>
841                <entry>Submenu</entry>
842                <entry>
843                  <sgmltag class="starttag">guisubmenu</sgmltag>
844                </entry>
845                <entry></entry>
846              </row>
847              <row>
848                <entry>Menu item</entry>
849                <entry>
850                  <sgmltag class="starttag">guimenuitem</sgmltag>
851                </entry>
852                <entry></entry>
853              </row>
854              <row>
855                <entry>Icon</entry>
856                <entry>
857                  <sgmltag class="starttag">guiicon</sgmltag>
858                </entry>
859                <entry></entry>
860              </row>
861            </tbody>
862          </tgroup>
863        </informaltable>
864        <para>
865          <xref linkend="write_docbook_doc.examples.guielements" />
866          shows how the menu choice in figure
867          <xref linkend="write_docbook_doc.figures.menuchoice" />
868          can be described.
869        </para>
870        <figure id="write_docbook_doc.figures.menuchoice">
871          <title>Menu choice</title>
872          <screenshot>
873            <mediaobject>
874              <imageobject>
875                <imagedata 
876                  contentwidth="7cm" 
877                  width="7cm" 
878                  fileref="figures/menuchoice.png" format="PNG" 
879                />
880              </imageobject>
881            </mediaobject>
882          </screenshot>
883        </figure>
884        <example id="write_docbook_doc.examples.guielements">
885          <title>Describe a menu choice</title>
886          <programlisting>
887&hellip;         
888&lt;menuchoice&gt;
889  &lt;guimenu&gt;Administrate&lt;/guimenu&gt;
890  &lt;guisubmenu&gt;Plugins&lt;/guisubmenu&gt;
891  &lt;guimenuitem&gt;Types&lt;/guimenuitem&gt;
892&lt;/menuchoice&gt;
893&hellip;
894          </programlisting>
895          <para>
896            In the text it will look like this:
897            <menuchoice>
898              <guimenu>Administrate</guimenu>
899              <guisubmenu>Plugins</guisubmenu>
900              <guimenuitem>Types</guimenuitem>
901            </menuchoice>
902          </para>
903        </example>
904      </sect3>
905    </sect2>
906    <sect2 id="write_docbook_doc.usedtags.images">
907      <title>Images and figures</title>
908      <para>
909        Images and figures are normally implemented like the following example. The
910        image-file must be located in
911        <filename class="directory">doc/src/docbook/figures</filename>
912        ,otherwise the image won't be visible in the generated output files.
913      </para>
914      <warning>
915        <para>
916          Images in the pdf-output are, unlike images in html-output, not scaled and can
917          therefore be out of proportion in the document. Avoid this by e.g. setting the
918          attributes
919          <sgmltag class="attribute">contentwidth</sgmltag>
920          and
921          <sgmltag class="attribute">width</sgmltag>
922          in
923          <sgmltag>imagedata</sgmltag>
924          to appropriate values.
925        </para>
926      </warning>
927      <example id="write_docbook_doc.examples.screenshot">
928        <title>Screen-shot in the documentation</title>
929        <para>
930          <xref linkend="write_docbook_doc.figures.menuchoice" />
931          is implemented with the following code
932        </para>
933        <programlisting>
934&lt;figure id="write_docbook_doc.figures.menuchoice"&gt;
935  &lt;title&gt;Menu choice&lt;/title&gt;
936  &lt;screenshot&gt;
937    &lt;mediaobject&gt;
938      &lt;imageobject&gt;
939        &lt;imagedata
940          contentwidth="7cm"
941          width="7cm"
942          fileref="figures/menuchoice.png" format="PNG"
943        /&gt;
944      &lt;/imageobject&gt;
945    &lt;/mediaobject&gt;
946  &lt;/screenshot&gt;
947&lt;/figure&gt;
948        </programlisting>
949      </example>
950    </sect2>
951    <sect2 id="write_docbook_doc.usedtags.examples">
952      <title>Examples and program listing</title>
953      <para>
954        Following describes how to insert an example in the documentation.The examples in
955        this document are often some kind of program listing but they can still be examples
956        of something else.
957      </para>
958      <warning>
959        <para>
960          More then 80 characters(including indention) in a row of program
961          listings or other verbatim elements will risk to put the end of the row outside
962          the text area.
963        </para>
964      </warning>
965      <example id="write_docbook_doc.examples.example">
966        <title>Example in the documentation</title>
967        <para>
968          This shows how 
969          <xref linkend="net.sf.basedb.core.plugin.Plugin.getAbout" />
970          is written in the corresponding XML-file.
971        </para>
972        <programlisting>
973  &hellip;
974  &lt;example id="net.sf.basedb.core.plugin.Plugin.getAbout"&gt;
975     &lt;title&gt;A typical implementation stores this information in a static field&lt;/title&gt;
976     &lt;programlisting&gt;
977private static final About about = new AboutImpl
978(
979   "Spot images creator",
980   "Converts a full-size scanned image into smaller preview jpg " +
981   "images for each individual spot.",
982   "2.0",
983   "2006, Department of Theoretical Physics, Lund University",
984   null,
985   "base@thep.lu.se",
986   "http://base.thep.lu.se"
987);
988 
989public About getAbout()
990{
991   return about;
992}
993     &lt;/programlisting&gt;
994  &lt;/example&gt;
995  &hellip;
996        </programlisting>
997      </example>     
998    </sect2>
999    <sect2 id="write_docbook_doc.usedtags.admonitions">
1000      <title>Admonitions</title>
1001      <para>
1002        The admonitions that are used in this document can be found in the table below.
1003      </para>
1004      <informaltable frame="none">
1005        <tgroup cols="3" rowsep="1" colsep="1">
1006          <colspec align="left" />
1007          <colspec align="center" />
1008          <colspec align="left" />
1009          <thead>
1010            <row>
1011              <entry>Define</entry>
1012              <entry>Element to use</entry>
1013              <entry>Comment</entry>
1014            </row>
1015          </thead>
1016          <tbody>
1017            <row>
1018              <entry>Warning text</entry>
1019              <entry>
1020                <sgmltag class="starttag">warning</sgmltag>
1021              </entry>
1022              <entry></entry>
1023            </row>
1024            <row>
1025              <entry>Notification text</entry>
1026              <entry>
1027                <sgmltag class="starttag">note</sgmltag>
1028              </entry>
1029              <entry></entry>
1030            </row>
1031            <row>
1032              <entry>A tip</entry>
1033              <entry>
1034                <sgmltag class="starttag">tip</sgmltag>
1035              </entry>
1036              <entry></entry>
1037            </row>
1038            <row>
1039              <entry>Important text</entry>
1040              <entry>
1041                <sgmltag class="starttag">important</sgmltag>
1042              </entry>
1043              <entry></entry>
1044            </row>
1045            <row>
1046              <entry>Something to be cautious about</entry>
1047              <entry>
1048                <sgmltag class="starttag">caution</sgmltag>
1049              </entry>
1050              <entry></entry>
1051            </row>
1052          </tbody>
1053        </tgroup>
1054      </informaltable>
1055    </sect2>
1056    <sect2 id="write_docbook_doc.usedtags.lists">
1057      <title>Lists</title>
1058      <para>
1059        Following items can be used to define different kind of lists in the documentation.
1060        Some common elements for the lists are also described here.
1061      </para>
1062      <informaltable frame="none">
1063        <tgroup cols="3" rowsep="1" colsep="1">
1064          <colspec align="left" />
1065          <colspec align="center" />
1066          <colspec align="left" />
1067          <thead>
1068            <row>
1069              <entry>Define</entry>
1070              <entry>Element</entry>
1071              <entry>Comment</entry>
1072            </row>
1073          </thead>
1074          <tbody>           
1075            <row>
1076              <entry>None-ordered list</entry>
1077              <entry>
1078                <sgmltag class="starttag">itemizedlist</sgmltag>
1079              </entry>
1080              <entry></entry>
1081            </row>
1082            <row>
1083              <entry>Term definition list</entry>
1084              <entry>
1085                <sgmltag class="starttag">variablelist</sgmltag>
1086              </entry>
1087              <entry></entry>
1088            </row>
1089            <row>
1090              <entry>Ordered list</entry>
1091              <entry>
1092                <sgmltag class="starttag">orderedlist</sgmltag>
1093              </entry>
1094              <entry></entry>
1095            </row>
1096            <row>
1097              <entry>List item</entry>
1098              <entry>
1099                <sgmltag class="starttag">listitem</sgmltag>
1100              </entry>
1101              <entry></entry>
1102            </row>
1103          </tbody>
1104        </tgroup>
1105      </informaltable>
1106      <para>The example below shows how to create a list for term definition in the text.</para>
1107      <example id="write_docbook_doc.examples.variablelist">
1108        <title>Example how to write a variable list</title>
1109        <programlisting>
1110&hellip;
1111&lt;variablelist&gt;
1112   &lt;varlistentry&gt;
1113      &lt;term&gt;Term1&lt;/term&gt;
1114      &lt;listitem&gt;
1115         &lt;para&gt;
1116            Definition/explanation of the term
1117         &lt;/para&gt;
1118      &lt;/listitem&gt;
1119   &lt;/varlistentry&gt;
1120   
1121   &lt;varlistentry&gt;
1122      &lt;term&gt;Term2&lt;/term&gt;
1123      &lt;listitem&gt;
1124         &lt;para&gt;
1125            Definition/explanation of the term
1126         &lt;/para&gt;
1127      &lt;/listitem&gt;
1128   &lt;/varlistentry&gt;
1129&lt;/variablelist&gt;
1130        </programlisting>
1131      </example>
1132    </sect2>
1133   
1134    <sect2 id="write_docbook_doc.usedtags.links">
1135      <title>Link elements</title>
1136      <para></para>
1137      <informaltable frame="none">
1138        <tgroup cols="3" rowsep="1" colsep="1">
1139          <colspec align="left" />
1140          <colspec align="center" />
1141          <colspec align="left" />
1142          <thead>
1143            <row>
1144              <entry>Define</entry>
1145              <entry>Element</entry>
1146              <entry>Comment</entry>
1147            </row>
1148          </thead>
1149          <tbody>
1150            <row>
1151              <entry>Cross reference</entry>
1152              <entry>
1153                <sgmltag class="starttag">xref linkend=""</sgmltag>
1154              </entry>
1155              <entry>Use this to linke to other parts of the document.</entry>
1156            </row>
1157            <row>
1158              <entry>Cross reference with own text</entry>
1159              <entry>
1160                <sgmltag class="starttag">link</sgmltag>
1161              </entry>
1162              <entry>
1163                Can be used as an alternative to
1164                <sgmltag>xref</sgmltag>
1165              </entry>
1166            </row>
1167            <row>
1168              <entry>External URLs</entry>
1169              <entry>
1170                <sgmltag class="starttag">ulink url=""</sgmltag>
1171              </entry>
1172              <entry></entry>
1173            </row>
1174          </tbody>
1175        </tgroup>
1176      </informaltable>
1177      <example id="write_docbook_doc.examples.links">
1178        <title>Links</title>
1179        <programlisting>
1180&hellip;
1181&lt;xref linkend="write_docbook_doc.usedtags.links" /&gt;
1182&lt;link linkend="write_docbook_doc.usedtags.links"&gt;Link to this section&lt;/link&gt;
1183&lt;ulink url="http://base.thep.lu.se"&gt;Base2's homepage&lt;/ulink&gt;
1184&hellip;
1185        </programlisting>
1186        <para>
1187          The first element will autogenerate the linked section's/chapter's title as a
1188          hyperlinked text. As an alternative to
1189          <sgmltag>xref</sgmltag>
1190          is
1191          <sgmltag>link</sgmltag>
1192          that lets you write your own hyperlinked text. The third and last one should be
1193          used to link to any URL outside the document.
1194        </para>
1195      </example>
1196    </sect2>
1197  </sect1>
1198</chapter>
Note: See TracBrowser for help on using the repository browser.