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

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

Allow parts of texts inside <helptext> tag to be skipped when generating help texts.
File size: 38.3 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      <sect3 id="write_docbook_doc.begin.helptext.nohelp">
430        <title>Skip parts of a help text</title>
431        <para>
432          From time to time, it may happen that you find that
433          some parts of the text inside a <sgmltag class="starttag">helptext</sgmltag>
434          tag doesn't make sense. It may, for example, be a reference to
435          an image or an example, or a link to another chapter or
436          section. Put a <sgmltag class="starttag">nohelp</sgmltag>
437          tag around the problematic part to avoid it from beeing
438          outputted to the help texts.
439        </para>     
440        <programlisting>
441&lt;nohelp&gt;see &lt;xref linkend="chapter11" /&gt;&lt;/nohelp&gt;</programlisting>
442      </sect3>
443     
444      <sect3 id="write_docbook_doc.begin.helptext.link">
445      <title>Link to other help texts</title>
446     
447      <para>
448        You can use <sgmltag class="starttag">seeother</sgmltag> and
449        <sgmltag class="starttag">other</sgmltag>
450        to create links between different help texts. The
451        <sgmltag  class="starttag">seeother</sgmltag>
452        tag doesn't have any attributes and is just a container for one or more
453        <sgmltag  class="starttag">other</sgmltag> tags. Each tag requires a single attribute.
454      </para>
455        <variablelist>
456          <varlistentry>
457            <term>
458              <sgmltag class="attribute">external_id</sgmltag>
459            </term>
460            <listitem>
461              <para>
462                The external ID of the other help text to link to.
463              </para>
464            </listitem>
465          </varlistentry>
466        </variablelist>
467      </sect3>
468     
469      <sect3 id="write_docbook_doc.begin.helptext.import">
470      <title>Import help texts into BASE</title>
471      <para>
472        Import the generated XML-file manually by uploading it from the
473        <filename class="directory">data</filename>
474        directory to the BASE-server's file system and then use the help text importer
475        plugin to import the help text items from that file.
476      </para>
477     
478      <para>
479        The help texts can also be imported by running the TestHelp
480        test program. In short, here are the commands you need to
481        import the help texts:
482      </para>
483     
484      <programlisting>
485ant docbook
486ant test
487cd build/test
488./run.sh TestHelp
489</programlisting>
490      </sect3>
491     
492    </sect2>
493    <sect2 id="write_docbook_doc.begin.generate">
494      <title>Generate output</title>
495
496      <sect3 id="write_docbook_doc.begin.generate.requirements">
497        <title>Requirements</title>
498        <para>
499          Those who have checked out the documentation source from repository or got the
500          source from a distribution package needs to compile it to get the pdf and html
501          documentation files. The compilation of the documentation source requires, beside Ant, that the XML-parser
502          Xsltproc is installed on the local computer. XsltProc and how it is installed, can
503          be found at
504          <ulink url="http://xmlsoft.org/XSLT/index.html"></ulink>.
505        </para>
506        <note>
507          <para>
508            There is an xml-parser in newer java-versions that can be used instead of
509            XsltProc but the compilation will most likely take much much longer time.
510            Therefore it's not recommended to be used when generating/compiling the
511            documentation in BASE 2.
512          </para>
513        </note>
514      </sect3>
515      <sect3 id="write_docbook_doc.begin.generate.compile">
516        <title>Compile - generate output files</title>
517        <para>
518          There are two different types of format that is generated from the documentation
519          source. The format to view the documentation on-line will be the one with
520          chunked HTML pages where each chapter and section of first level are on separate
521          pages/files. The other format is a PDF-file that are most useful for printing
522          and distribution. Those two types of output are generated with the ant-target:
523          <command>ant docbook</command>
524          . This documentation is also generated with
525          <command>ant dist</command>
526          , which will put the output files in the right location for distribution with
527          BASE 2.
528        </para>
529      </sect3>
530    </sect2>
531  </sect1>
532
533  <sect1 id="write_docbook_doc.usedtags">
534    <title>Elements to use</title>
535    <para>
536      The purpose with this section is to give an overview of those docbook elements that are
537      most common in this documentation and to give some example on how they should be used.
538      There will not be any detailed explanation of the tags here, instead the reader is
539      recommended to get more information from
540      <ulink url="http://www.docbook.org/tdg/en/html/docbook.html">
541        Docbook's documentation
542      </ulink>
543      or other references.
544    </para>
545    <sect2 id="write_docbook_doc.usedtags.text">
546      <title>Text elements</title>
547      <para>
548       
549      </para>
550      <informaltable frame="none">
551        <tgroup cols="3" rowsep="1" colsep="1">
552          <colspec align="left" />
553          <colspec align="center" />
554          <colspec align="left" />
555          <thead>
556            <row>
557              <entry>Define</entry>
558              <entry>Element to use</entry>
559              <entry>Comments</entry>
560            </row>
561          </thead>
562          <tbody>
563            <row>
564              <entry>Chapter</entry>
565              <entry>
566                <sgmltag class="starttag">chapter</sgmltag>
567              </entry>
568              <entry>
569                <para>
570                  See
571                  <xref linkend="write_docbook_doc.examples.chapterbody" />
572                </para>
573              </entry>
574            </row>
575            <row>
576              <entry>Title</entry>
577              <entry>
578                <sgmltag class="starttag">title</sgmltag>
579              </entry>
580              <entry>
581                <xref linkend="write_docbook_doc.examples.chapterbody" />
582                shows how this can be implemented
583              </entry>
584            </row>
585            <row>
586              <entry>Paragraph</entry>
587              <entry>
588                <sgmltag class="starttag">para</sgmltag>
589              </entry>
590              <entry></entry>
591            </row>
592            <row>
593              <entry>Top-level subsection</entry>
594              <entry>
595                <sgmltag class="starttag">sect1</sgmltag>
596              </entry>
597              <entry>
598                See
599                <xref linkend="write_docbook_doc.begin.id" />
600              </entry>
601            </row>
602            <row>
603              <entry>Second level section</entry>
604              <entry>
605                <sgmltag class="starttag">sect2</sgmltag>
606              </entry>
607              <entry>
608                See
609                <xref linkend="write_docbook_doc.begin.id" />
610              </entry>
611            </row>
612            <row>
613              <entry>Third level section</entry>
614              <entry>
615                <sgmltag class="starttag">sect3</sgmltag>
616              </entry>
617              <entry>
618                See
619                <xref linkend="write_docbook_doc.begin.id" />
620              </entry>
621            </row>
622            <row>
623              <entry>Fourth level section</entry>
624              <entry>
625                <sgmltag class="starttag">sect3</sgmltag>
626              </entry>
627              <entry></entry>
628            </row>
629            <row>
630              <entry>Fith level section</entry>
631              <entry>
632                <sgmltag class="starttag">sect3</sgmltag>
633              </entry>
634              <entry></entry>
635            </row>
636          </tbody>
637        </tgroup>
638      </informaltable>
639
640      <sect3 id="write_docbook_doc.usedtags.text.keywords">
641        <title>Markup special words and phrases</title>
642        <para>
643          These elements should be used to mark up words and phrases that have a special
644          meaning, like method names, class names and user inputs just to mention some.
645        </para>
646        <informaltable frame="none">
647          <tgroup cols="3" rowsep="1" colsep="1">
648            <colspec align="left" />
649            <colspec align="center" />
650            <colspec align="left" />
651            <thead>
652              <row>
653                <entry>Define</entry>
654                <entry>Element to use</entry>
655                <entry>Comment</entry>
656              </row>
657            </thead>
658            <tbody>
659              <row>
660                <entry>Class name</entry>
661                <entry>
662                  <sgmltag class="starttag">classname</sgmltag>
663                </entry>
664                <entry></entry>
665              </row>
666              <row>
667                <entry>User input</entry>
668                <entry>
669                  <sgmltag class="starttag">userinput</sgmltag>
670                </entry>
671                <entry></entry>
672              </row>
673              <row>
674                <entry>Variable name</entry>
675                <entry>
676                  <sgmltag class="starttag">varname</sgmltag>
677                </entry>
678                <entry></entry>
679              </row>
680              <row>
681                <entry>Constant</entry>
682                <entry>
683                  <sgmltag class="starttag">constant</sgmltag>
684                </entry>
685                <entry></entry>
686              </row>
687              <row>
688                <entry>Method definition</entry>
689                <entry>
690                  <sgmltag class="starttag">methodsynopsis</sgmltag>
691                </entry>
692                <entry>
693                  See
694                  <xref linkend="write_docbook_doc.examples.methodimpl" />
695                </entry>
696              </row>
697              <row>
698                <entry>Modifier of a method</entry>
699                <entry>
700                  <sgmltag class="starttag">modifier</sgmltag>
701                </entry>
702                <entry>
703                  See
704                  <xref linkend="write_docbook_doc.examples.methodimpl" />
705                </entry>
706              </row>
707              <row>
708                <entry>Classification of return value</entry>
709                <entry>
710                  <sgmltag class="starttag">type</sgmltag>
711                </entry>
712                <entry>
713                  See
714                  <xref linkend="write_docbook_doc.examples.methodimpl" />
715                </entry>
716              </row>
717              <row>
718                <entry>Method name</entry>
719                <entry>
720                  <sgmltag class="starttag">methodname</sgmltag>
721                </entry>
722                <entry>
723                  See
724                  <xref linkend="write_docbook_doc.examples.methodimpl" />
725                </entry>
726              </row>
727              <row>
728                <entry>No parameter/type</entry>
729                <entry>
730                  <sgmltag class="starttag">void</sgmltag>
731                </entry>
732                <entry>
733                  See
734                  <xref linkend="write_docbook_doc.examples.methodimpl" />
735                </entry>
736              </row>
737              <row>
738                <entry>Define a parameter</entry>
739                <entry>
740                  <sgmltag class="starttag">methodparam</sgmltag>
741                </entry>
742                <entry>
743                  See
744                  <xref linkend="write_docbook_doc.examples.methodimpl1" />
745                </entry>
746              </row>
747              <row>
748                <entry>Parameter type</entry>
749                <entry>
750                  <sgmltag class="starttag">type</sgmltag>
751                </entry>
752                <entry>
753                  See
754                  <xref linkend="write_docbook_doc.examples.methodimpl1" />
755                </entry>
756              </row>
757              <row>
758                <entry>Parameter name</entry>
759                <entry>
760                  <sgmltag class="starttag">parameter</sgmltag>
761                </entry>
762                <entry>
763                  See
764                  <xref linkend="write_docbook_doc.examples.methodimpl1" />
765                </entry>
766              </row>
767            </tbody>
768          </tgroup>
769        </informaltable>
770        <para>
771          Follow one of the examples below to insert a method definition in the document.
772        </para>
773        <example id="write_docbook_doc.examples.methodimpl">
774          <title>
775            Method with no arguments and a return value
776          </title>
777          <programlisting>
778&hellip;
779&lt;methodsynopsis language="java"&gt;
780  &lt;modifier&gt;public&lt;/modifier&gt;
781  &lt;type&gt;Plugin.MainType&lt;/type&gt;
782  &lt;methodname&gt;getMainType&lt;/methodname&gt;
783  &lt;void /&gt;
784&lt;/methodsynopsis&gt;
785&hellip;
786          </programlisting>
787        </example>
788        <example id="write_docbook_doc.examples.methodimpl1">
789          <title>
790            Method with arguments and no return value
791          </title>
792          <programlisting>
793&hellip;
794&lt;methodsynopsis language="java"&gt;
795  &lt;modifier&gt;public&lt;/modifier&gt;
796  &lt;void /&gt;
797  &lt;methodname&gt;init&lt;/methodname&gt;
798  &lt;methodparam&gt;
799    &lt;type&gt;SessionControl&lt;/type&gt;
800    &lt;parameter&gt;sc&lt;/parameter&gt;
801  &lt;/methodparam&gt;
802  &lt;methodparam&gt;
803    &lt;type&gt;ParameterValues&lt;/type&gt;
804    &lt;parameter&gt;configuration&lt;/parameter&gt;
805  &lt;/methodparam&gt;
806  &lt;methodparam&gt;
807    &lt;type&gt;ParameterValues&lt;/type&gt;
808    &lt;parameter&gt;job&lt;/parameter&gt;
809  &lt;/methodparam&gt;
810&lt;/methodsynopsis&gt;
811&hellip;
812          </programlisting>
813        </example>
814       
815      </sect3>
816      <sect3 id="write_docbook_doc.usedtags.text.gui">
817        <title>Gui elements</title>
818        <para>
819          Docbook has some elements that can be used to symbolize gui items in a program.
820          Following list contains the ones that are most common in this document.
821        </para>
822        <informaltable frame="none">
823          <tgroup cols="3" rowsep="1" colsep="1">
824            <colspec align="left" />
825            <colspec align="center" />
826            <colspec align="left" />
827            <thead>
828              <row>
829                <entry>Define</entry>
830                <entry>Element to use</entry>
831                <entry>Comment</entry>
832              </row>
833            </thead>
834            <tbody>
835              <row>
836                <entry>Button</entry>
837                <entry>
838                  <sgmltag class="starttag">guibutton</sgmltag>
839                </entry>
840                <entry></entry>
841              </row>
842              <row>
843                <entry>Label</entry>
844                <entry>
845                  <sgmltag class="starttag">guilabel</sgmltag>
846                </entry>
847                <entry></entry>
848              </row>
849              <row>
850                <entry>Menu choice</entry>
851                <entry>
852                  <sgmltag class="starttag">menuchoice</sgmltag>
853                </entry>
854                <entry></entry>
855              </row>
856              <row>
857                <entry>Menu</entry>
858                <entry>
859                  <sgmltag class="starttag">guimenu</sgmltag>
860                </entry>
861                <entry></entry>
862              </row>
863              <row>
864                <entry>Submenu</entry>
865                <entry>
866                  <sgmltag class="starttag">guisubmenu</sgmltag>
867                </entry>
868                <entry></entry>
869              </row>
870              <row>
871                <entry>Menu item</entry>
872                <entry>
873                  <sgmltag class="starttag">guimenuitem</sgmltag>
874                </entry>
875                <entry></entry>
876              </row>
877              <row>
878                <entry>Icon</entry>
879                <entry>
880                  <sgmltag class="starttag">guiicon</sgmltag>
881                </entry>
882                <entry></entry>
883              </row>
884            </tbody>
885          </tgroup>
886        </informaltable>
887        <para>
888          <xref linkend="write_docbook_doc.examples.guielements" />
889          shows how the menu choice in figure
890          <xref linkend="write_docbook_doc.figures.menuchoice" />
891          can be described.
892        </para>
893        <figure id="write_docbook_doc.figures.menuchoice">
894          <title>Menu choice</title>
895          <screenshot>
896            <mediaobject>
897              <imageobject>
898                <imagedata 
899                  contentwidth="7cm" 
900                  width="7cm" 
901                  fileref="figures/menuchoice.png" format="PNG" 
902                />
903              </imageobject>
904            </mediaobject>
905          </screenshot>
906        </figure>
907        <example id="write_docbook_doc.examples.guielements">
908          <title>Describe a menu choice</title>
909          <programlisting>
910&hellip;         
911&lt;menuchoice&gt;
912  &lt;guimenu&gt;Administrate&lt;/guimenu&gt;
913  &lt;guisubmenu&gt;Plugins&lt;/guisubmenu&gt;
914  &lt;guimenuitem&gt;Types&lt;/guimenuitem&gt;
915&lt;/menuchoice&gt;
916&hellip;
917          </programlisting>
918          <para>
919            In the text it will look like this:
920            <menuchoice>
921              <guimenu>Administrate</guimenu>
922              <guisubmenu>Plugins</guisubmenu>
923              <guimenuitem>Types</guimenuitem>
924            </menuchoice>
925          </para>
926        </example>
927      </sect3>
928    </sect2>
929    <sect2 id="write_docbook_doc.usedtags.images">
930      <title>Images and figures</title>
931      <para>
932        Images and figures are normally implemented like the following example. The
933        image-file must be located in
934        <filename class="directory">doc/src/docbook/figures</filename>
935        ,otherwise the image won't be visible in the generated output files.
936      </para>
937      <warning>
938        <para>
939          Images in the pdf-output are, unlike images in html-output, not scaled and can
940          therefore be out of proportion in the document. Avoid this by e.g. setting the
941          attributes
942          <sgmltag class="attribute">contentwidth</sgmltag>
943          and
944          <sgmltag class="attribute">width</sgmltag>
945          in
946          <sgmltag>imagedata</sgmltag>
947          to appropriate values.
948        </para>
949      </warning>
950      <example id="write_docbook_doc.examples.screenshot">
951        <title>Screen-shot in the documentation</title>
952        <para>
953          <xref linkend="write_docbook_doc.figures.menuchoice" />
954          is implemented with the following code
955        </para>
956        <programlisting>
957&lt;figure id="write_docbook_doc.figures.menuchoice"&gt;
958  &lt;title&gt;Menu choice&lt;/title&gt;
959  &lt;screenshot&gt;
960    &lt;mediaobject&gt;
961      &lt;imageobject&gt;
962        &lt;imagedata
963          contentwidth="7cm"
964          width="7cm"
965          fileref="figures/menuchoice.png" format="PNG"
966        /&gt;
967      &lt;/imageobject&gt;
968    &lt;/mediaobject&gt;
969  &lt;/screenshot&gt;
970&lt;/figure&gt;
971        </programlisting>
972      </example>
973    </sect2>
974    <sect2 id="write_docbook_doc.usedtags.examples">
975      <title>Examples and program listing</title>
976      <para>
977        Following describes how to insert an example in the documentation.The examples in
978        this document are often some kind of program listing but they can still be examples
979        of something else.
980      </para>
981      <warning>
982        <para>
983          More then 80 characters(including indention) in a row of program
984          listings or other verbatim elements will risk to put the end of the row outside
985          the text area.
986        </para>
987      </warning>
988      <example id="write_docbook_doc.examples.example">
989        <title>Example in the documentation</title>
990        <para>
991          This shows how 
992          <xref linkend="net.sf.basedb.core.plugin.Plugin.getAbout" />
993          is written in the corresponding XML-file.
994        </para>
995        <programlisting>
996  &hellip;
997  &lt;example id="net.sf.basedb.core.plugin.Plugin.getAbout"&gt;
998     &lt;title&gt;A typical implementation stores this information in a static field&lt;/title&gt;
999     &lt;programlisting&gt;
1000private static final About about = new AboutImpl
1001(
1002   "Spot images creator",
1003   "Converts a full-size scanned image into smaller preview jpg " +
1004   "images for each individual spot.",
1005   "2.0",
1006   "2006, Department of Theoretical Physics, Lund University",
1007   null,
1008   "base@thep.lu.se",
1009   "http://base.thep.lu.se"
1010);
1011 
1012public About getAbout()
1013{
1014   return about;
1015}
1016     &lt;/programlisting&gt;
1017  &lt;/example&gt;
1018  &hellip;
1019        </programlisting>
1020      </example>     
1021    </sect2>
1022    <sect2 id="write_docbook_doc.usedtags.admonitions">
1023      <title>Admonitions</title>
1024      <para>
1025        The admonitions that are used in this document can be found in the table below.
1026      </para>
1027      <informaltable frame="none">
1028        <tgroup cols="3" rowsep="1" colsep="1">
1029          <colspec align="left" />
1030          <colspec align="center" />
1031          <colspec align="left" />
1032          <thead>
1033            <row>
1034              <entry>Define</entry>
1035              <entry>Element to use</entry>
1036              <entry>Comment</entry>
1037            </row>
1038          </thead>
1039          <tbody>
1040            <row>
1041              <entry>Warning text</entry>
1042              <entry>
1043                <sgmltag class="starttag">warning</sgmltag>
1044              </entry>
1045              <entry></entry>
1046            </row>
1047            <row>
1048              <entry>Notification text</entry>
1049              <entry>
1050                <sgmltag class="starttag">note</sgmltag>
1051              </entry>
1052              <entry></entry>
1053            </row>
1054            <row>
1055              <entry>A tip</entry>
1056              <entry>
1057                <sgmltag class="starttag">tip</sgmltag>
1058              </entry>
1059              <entry></entry>
1060            </row>
1061            <row>
1062              <entry>Important text</entry>
1063              <entry>
1064                <sgmltag class="starttag">important</sgmltag>
1065              </entry>
1066              <entry></entry>
1067            </row>
1068            <row>
1069              <entry>Something to be cautious about</entry>
1070              <entry>
1071                <sgmltag class="starttag">caution</sgmltag>
1072              </entry>
1073              <entry></entry>
1074            </row>
1075          </tbody>
1076        </tgroup>
1077      </informaltable>
1078    </sect2>
1079    <sect2 id="write_docbook_doc.usedtags.lists">
1080      <title>Lists</title>
1081      <para>
1082        Following items can be used to define different kind of lists in the documentation.
1083        Some common elements for the lists are also described here.
1084      </para>
1085      <informaltable frame="none">
1086        <tgroup cols="3" rowsep="1" colsep="1">
1087          <colspec align="left" />
1088          <colspec align="center" />
1089          <colspec align="left" />
1090          <thead>
1091            <row>
1092              <entry>Define</entry>
1093              <entry>Element</entry>
1094              <entry>Comment</entry>
1095            </row>
1096          </thead>
1097          <tbody>           
1098            <row>
1099              <entry>None-ordered list</entry>
1100              <entry>
1101                <sgmltag class="starttag">itemizedlist</sgmltag>
1102              </entry>
1103              <entry></entry>
1104            </row>
1105            <row>
1106              <entry>Term definition list</entry>
1107              <entry>
1108                <sgmltag class="starttag">variablelist</sgmltag>
1109              </entry>
1110              <entry></entry>
1111            </row>
1112            <row>
1113              <entry>Ordered list</entry>
1114              <entry>
1115                <sgmltag class="starttag">orderedlist</sgmltag>
1116              </entry>
1117              <entry></entry>
1118            </row>
1119            <row>
1120              <entry>List item</entry>
1121              <entry>
1122                <sgmltag class="starttag">listitem</sgmltag>
1123              </entry>
1124              <entry></entry>
1125            </row>
1126          </tbody>
1127        </tgroup>
1128      </informaltable>
1129      <para>The example below shows how to create a list for term definition in the text.</para>
1130      <example id="write_docbook_doc.examples.variablelist">
1131        <title>Example how to write a variable list</title>
1132        <programlisting>
1133&hellip;
1134&lt;variablelist&gt;
1135   &lt;varlistentry&gt;
1136      &lt;term&gt;Term1&lt;/term&gt;
1137      &lt;listitem&gt;
1138         &lt;para&gt;
1139            Definition/explanation of the term
1140         &lt;/para&gt;
1141      &lt;/listitem&gt;
1142   &lt;/varlistentry&gt;
1143   
1144   &lt;varlistentry&gt;
1145      &lt;term&gt;Term2&lt;/term&gt;
1146      &lt;listitem&gt;
1147         &lt;para&gt;
1148            Definition/explanation of the term
1149         &lt;/para&gt;
1150      &lt;/listitem&gt;
1151   &lt;/varlistentry&gt;
1152&lt;/variablelist&gt;
1153        </programlisting>
1154      </example>
1155    </sect2>
1156   
1157    <sect2 id="write_docbook_doc.usedtags.links">
1158      <title>Link elements</title>
1159      <para></para>
1160      <informaltable frame="none">
1161        <tgroup cols="3" rowsep="1" colsep="1">
1162          <colspec align="left" />
1163          <colspec align="center" />
1164          <colspec align="left" />
1165          <thead>
1166            <row>
1167              <entry>Define</entry>
1168              <entry>Element</entry>
1169              <entry>Comment</entry>
1170            </row>
1171          </thead>
1172          <tbody>
1173            <row>
1174              <entry>Cross reference</entry>
1175              <entry>
1176                <sgmltag class="starttag">xref linkend=""</sgmltag>
1177              </entry>
1178              <entry>Use this to linke to other parts of the document.</entry>
1179            </row>
1180            <row>
1181              <entry>Cross reference with own text</entry>
1182              <entry>
1183                <sgmltag class="starttag">link</sgmltag>
1184              </entry>
1185              <entry>
1186                Can be used as an alternative to
1187                <sgmltag>xref</sgmltag>
1188              </entry>
1189            </row>
1190            <row>
1191              <entry>External URLs</entry>
1192              <entry>
1193                <sgmltag class="starttag">ulink url=""</sgmltag>
1194              </entry>
1195              <entry></entry>
1196            </row>
1197          </tbody>
1198        </tgroup>
1199      </informaltable>
1200      <example id="write_docbook_doc.examples.links">
1201        <title>Links</title>
1202        <programlisting>
1203&hellip;
1204&lt;xref linkend="write_docbook_doc.usedtags.links" /&gt;
1205&lt;link linkend="write_docbook_doc.usedtags.links"&gt;Link to this section&lt;/link&gt;
1206&lt;ulink url="http://base.thep.lu.se"&gt;Base2's homepage&lt;/ulink&gt;
1207&hellip;
1208        </programlisting>
1209        <para>
1210          The first element will autogenerate the linked section's/chapter's title as a
1211          hyperlinked text. As an alternative to
1212          <sgmltag>xref</sgmltag>
1213          is
1214          <sgmltag>link</sgmltag>
1215          that lets you write your own hyperlinked text. The third and last one should be
1216          used to link to any URL outside the document.
1217        </para>
1218      </example>
1219    </sect2>
1220  </sect1>
1221</chapter>
Note: See TracBrowser for help on using the repository browser.