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

Last change on this file since 3679 was 3679, checked in by Jari Häkkinen, 14 years ago

Changing the pesky "a (ä) character to a.

File size: 41.2 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) 2007 Jari Hakkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson
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 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'>&lt;base-dir&gt;/doc/src/docbook</filename>.
112        The different parts of the documentation are organized into separate folders and
113        each one of the folders contains one index file and one file for each chapter in
114        that part. The index file joins the chapters, in current part/folder, together and
115        does not really contain any text. The documentation root directory also contains an
116        <filename class='headerfile'>index.xml</filename>
117        file which joins the index files from the different parts together.
118      </para>
119      <figure id="write_docbook_doc.figures.fileorganization">
120        <title>The organization of documentation files</title>
121        <screenshot>
122          <mediaobject>
123            <imageobject>
124              <imagedata fileref="figures/fileorganization.png" format="PNG" />
125            </imageobject>
126          </mediaobject>
127        </screenshot>
128      </figure>
129      <sect3 id="write_docbook_doc.begin.sourcefiles.newfile">
130        <title>Create new chapter/file</title>
131        <para>
132          Most files in the documentation, except the index files, represents a chapter.
133          Here is how to create a new chapter and include it in the main documentation:
134          <orderedlist numeration='arabic' spacing='compact'>
135            <listitem>
136              <para>
137                Create a new XML-file in the folder for the part where the new chapter
138                should be included. Give it a name that is quite similar to the
139                new chapter's title but use <userinput>_</userinput> instead of
140                blank space and keep it down to one or a few words.
141              </para>
142            </listitem>
143            <listitem>
144              <para>
145                Begin to write the chapter's body, here is an example:
146                <example id="write_docbook_doc.examples.chapterbody">
147                  <title>Example of a chapter</title>
148<programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
149&lt;!DOCTYPE chapter PUBLIC
150  "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
151  "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd"&gt;
152
153&lt;chapter id="<replaceable>example_chapter</replaceable>"&gt;
154   &lt;?dbhtml dir="<replaceable>folder name to put the chapter's files in</replaceable>"?&gt;
155   &lt;title&gt;Example of a chapter &lt;/title&gt;
156   &lt;para&gt;
157      &hellip;
158   &lt;/para&gt;
159   &lt;sect1 id="<replaceable>example_chapter.sect1</replaceable>"&gt;
160      &lt;title&gt;Example of top level section &lt;/title&gt;
161      &lt;para&gt;
162         &hellip;
163      &lt;/para&gt;
164      &lt;sect2 id="<replaceable>example_chapter.sect1.sect2</replaceable>"&gt;
165         &lt;title&gt;Example of second level section &lt;/title&gt;
166         &lt;para&gt;
167            &hellip;
168         &lt;/para&gt;
169         &lt;sect3 id="<replaceable>example_chapter.sect1.sect2.sect3</replaceable>"&gt;
170            &lt;title&gt;Example of third level section&lt;/title&gt;
171            &lt;para&gt;
172               &hellip;
173            &lt;/para&gt;
174         &lt;/sect3&gt;
175      &lt;/sect2&gt;     
176   &lt;/sect1&gt;
177&lt;/chapter&gt;</programlisting>
178                </example>
179              </para>
180              <note>
181                <para>
182                  Do not forget to include the
183                  <sgmltag>dbhtml</sgmltag>
184                  tag with the attribute
185                  <sgmltag class="attribute">dir</sgmltag>
186                  set to the value that the chapter's output folder should have as a
187                  name.
188                </para>
189              </note>
190            </listitem>
191            <listitem>
192              <para>
193                The last step is to get the new chapter included in the documentation. This is done by including the file's name in
194                the file
195                <filename>index.xml</filename>
196                that's located in the current part's folder.
197                The following example
198                shows how the chapter that was created above is included in the user
199                documentation part.
200              </para>
201              <example id="write_docbook_doc.examples.include_chapter">
202                <title>Include a chapter</title>
203<programlisting>&lt;part id="userdoc"&gt;
204   &lt;title&gt;User documentation&lt;/title&gt;
205   &lt;include file= "about.xml"/&gt;
206   &lt;include file="webclient.xml"/&gt;
207   &lt;include file="project_permission.xml"/&gt;
208   &lt;include file="trashcan.xml"/&gt;
209   &lt;include file="file_system.xml"/&gt;
210   &lt;include file="jobs.xml"/&gt;
211   &lt;include file="reporters.xml"/&gt;
212   &lt;include file="annotations.xml"/&gt;
213   &lt;include file="protocols.xml"/&gt;
214   &lt;include file="hardware.xml"/&gt;
215   <userinput>&lt;include file="example_chapter.xml"/&gt;</userinput>
216   &lt;include file="software.xml"/&gt;
217   &lt;include file="array_lims.xml"/&gt;
218   &lt;include file="biomaterials.xml"/&gt;
219   &lt;include file="experiments_analysis.xml"/&gt;
220   &lt;include file="import_export_data.xml"/&gt;
221&lt;/part&gt;</programlisting>
222                </example>
223              <note>
224                <title>Order of chapters</title>
225                <para>
226                  The chapters will come in the same order as they are included in
227                  the index file.
228                </para>
229              </note>
230            </listitem>     
231          </orderedlist>
232          Now it's only to go ahead with the documentation writing.
233        </para>
234      </sect3>
235    </sect2>
236   
237    <sect2 id="write_docbook_doc.begin.chunking">
238      <title>Controlling chunking</title>
239      <para>
240        We have configured docbook to create a new subdirectory for each
241        <sgmltag class="starttag">chapter</sgmltag> and a new output file for each
242        <sgmltag class="starttag">sect1</sgmltag> tag. In most cases this
243        gives each page a relatively good size. Not too long and not too short.
244        However, if a chapter contains many small <sgmltag class="starttag">sect1</sgmltag>
245        sections (for example, <xref linkend="resources"/>), you end up with many
246        pages with just a few lines of text on each page. This is not so
247        good and can be avoided by adding <sgmltag class="attribute">chunked="0"</sgmltag>
248        as an attribute to the <sgmltag class="starttag">chapter</sgmltag> tag, for example:
249      </para>
250      <programlisting>&lt;chapter id="resources" chunked="0"&gt;</programlisting>
251      <para>
252        This will stop the chunking of <sgmltag class="starttag">sect1</sgmltag>
253        sections in this chapter.
254      </para>
255     
256      <para>
257        On the other
258        hand, if you have a <sgmltag class="starttag">sect1</sgmltag>
259        that contains many long <sgmltag class="starttag">sect2</sgmltag>
260        sections you might want to put each <sgmltag class="starttag">sect2</sgmltag>
261        section in a separate chunk:
262      </para>
263      <programlisting>&lt;sect1 id="sect.with.large.sect2" chunked="1"&gt;</programlisting>
264   
265    </sect2>
266   
267    <sect2 id="write_docbook_doc.begin.id">
268      <title>
269        The
270        <sgmltag class="attribute">id</sgmltag>
271        attribute
272      </title>
273      <para>
274        Common to all elements is that they have an <sgmltag class="attribute">id</sgmltag>
275        attribute that can be used to identify the
276        element with. The value must be unique for the entire documentation.
277        Most of the elements that are used inside the BASE2 documentation do not
278        need to have an id if they do not are used in any cross references from other part of
279        the text.
280      </para>
281      <para>
282        There are some elements that always should have the
283        <sgmltag class="attribute">id</sgmltag>
284        set. Which these elements are and how the
285        <sgmltag class="attribute">id</sgmltag>
286        should look like for each one of those is described below. All values should be as
287        short as possible and associated to the current element. The
288        <sgmltag class="attribute">id</sgmltag>
289        value should only consist of the lowercase characters a-z, '_' instead of blank
290        spaces and '.' to symbolize the different levels in the document.
291        <variablelist>
292          <varlistentry>
293            <term>chapter</term>
294            <listitem>
295              <para>
296                The chapter should have an
297                <sgmltag class="attribute">id</sgmltag>
298                that is identical or almost identical to the chapter's title.
299                <synopsis>chapter_title</synopsis>
300              </para>
301            </listitem>
302          </varlistentry>
303          <varlistentry>
304            <term>sect1-sect5</term>
305            <listitem>
306              <para>
307                The creation of a section's id is done by using the upper level's id
308                and add the section's title or a part of the title. For
309                &lt;sect2&gt; it should be like this;
310                <synopsis>chapter_title.sect1_title.sect2_title</synopsis>
311              </para>
312            </listitem>
313          </varlistentry>
314          <varlistentry>
315            <term>examples</term>
316            <listitem>
317              <para>
318                The naming of an example's
319                <sgmltag class="attribute">id</sgmltag>
320                is a bit different compare to the chapter's and section's id. It
321                should begin with the chapter's id followed by
322                <userinput>examples</userinput>
323                and the caption of the example.
324                <synopsis>chapter_title.examples.example_caption</synopsis>
325              </para>
326            </listitem>
327          </varlistentry>
328          <varlistentry>
329            <term>figures</term>
330            <listitem>
331              <para>
332                The figure's
333                <sgmltag class="attribute">id</sgmltag>
334                should have the following layout
335                <synopsis>chapter_title.figures.figure_name</synopsis>
336              </para>
337            </listitem>
338          </varlistentry>
339        </variablelist>
340      </para>
341    </sect2>
342    <sect2 id="write_docbook_doc.begin.helptext">
343      <title>Mark help texts</title>
344      <para>
345        This documentation is also use to create the help texts that show up
346        in the web client when clicking on the question mark icons.
347        The parts of the text that also should be used as help texts in the web must be
348        inside
349        <sgmltag class="starttag">helptext</sgmltag>
350        tags. These texts will be exported to a XML-file at the same time as the
351        HTML-documentation is generated. The generated XML-file is compatible with the help
352        text importer in BASE2 and will be imported when running the update script or
353        installation script.
354      </para>
355      <note>
356      <para>
357        The
358        <sgmltag class="starttag">helptext</sgmltag>
359        must be outside the
360        <sgmltag class="starttag">para</sgmltag>
361        tag but inside a
362        <sgmltag class="starttag">sect</sgmltag> 
363        tag to work properly. Do not put any <sgmltag class="starttag">sect</sgmltag>
364        tags inside the helptext. This will make the automatic chapter and section
365        numbering confused.
366      </para>
367      </note>
368      <para>
369        The tag supports the following attributes
370        <variablelist>
371          <varlistentry>
372            <term>
373              <sgmltag class="attribute">external_id</sgmltag>
374            </term>
375            <listitem>
376              <para>
377                Is used to identify and to find a help text in the web client.
378                BASE2's web client already has several IDs to help texts defined,
379                it could therefore be a good idea to have a look in the
380                program to see if there already is an external id to use for the
381                particular help text.
382              </para>
383            </listitem>
384          </varlistentry>
385          <varlistentry>
386            <term>
387              <sgmltag class="attribute">title</sgmltag>
388            </term>
389            <listitem>
390              <para>
391                Is directly connected to the name/title property for a help text
392                item in BASE2.
393              </para>
394            </listitem>
395          </varlistentry>
396          <varlistentry>
397            <term>
398              <sgmltag class="attribute">webonly</sgmltag>
399            </term>
400            <listitem>
401              <para>
402                If set to a non-zero value, the contents of the tag
403                will not be outputted in the HTML or PDF documentation.
404                This is useful for minor functionality that is not
405                important enough to be mentioned in the documentation but has
406                a help icon in the web client.
407              </para>
408            </listitem>
409          </varlistentry>
410        </variablelist>
411      </para>
412      <example id="write_docbook_doc.examples.helptexttag">
413        <title>How to use the help text tag</title>
414<programlisting>&lt;sect1&gt;
415   &lt;helptext external_id="<replaceable>helptexts.external.id</replaceable>" title="<replaceable>The title</replaceable>"&gt;
416      <replaceable>The text that also should be used as a helptext in the program.</replaceable>
417      &lt;seeother&gt;
418         &lt;other external_id="<replaceable>other.external.id</replaceable>"&gt;
419            <replaceable>Related info here...</replaceable>&lt;/other&gt;
420      &lt;/seeother&gt;
421   &lt;/helptext&gt;
422&lt;/sect1&gt;</programlisting>
423      </example>
424     
425      <sect3 id="write_docbook_doc.begin.helptext.nohelp">
426        <title>Skip parts of a help text</title>
427        <para>
428          From time to time, it may happen that you find that
429          some parts of the text inside a <sgmltag class="starttag">helptext</sgmltag>
430          tag does not make sense. It may, for example, be a reference to
431          an image or an example, or a link to another chapter or
432          section. Put a <sgmltag class="starttag">nohelp</sgmltag>
433          tag around the problematic part to avoid it from beeing
434          outputted to the help texts.
435        </para>     
436        <programlisting>&lt;nohelp&gt;see &lt;xref linkend="chapter11" /&gt;&lt;/nohelp&gt;</programlisting>
437      </sect3>
438     
439      <sect3 id="write_docbook_doc.begin.helptext.link">
440      <title>Link to other help texts</title>
441     
442      <para>
443        You can use <sgmltag class="starttag">seeother</sgmltag> and
444        <sgmltag class="starttag">other</sgmltag>
445        to create links between different help texts. The
446        <sgmltag  class="starttag">seeother</sgmltag>
447        tag does not have any attributes and is just a container for one or more
448        <sgmltag  class="starttag">other</sgmltag> tags. Each tag requires a single attribute.
449      </para>
450        <variablelist>
451          <varlistentry>
452            <term>
453              <sgmltag class="attribute">external_id</sgmltag>
454            </term>
455            <listitem>
456              <para>
457                The external ID of the other help text to link to.
458              </para>
459            </listitem>
460          </varlistentry>
461        </variablelist>
462       
463<programlisting>&lt;seeother&gt;
464  &lt;other external_id="userpreferences.password"&gt;Change password&lt;/other&gt;
465  &lt;other external_id="userpreferences.other"&gt;Other information&lt;/other&gt;
466&lt;/seeother&gt;</programlisting>
467       
468        <para>
469          We recommend that you place the links at the end of the
470          help text section. The links will not show up in the HTML or PDF version.
471        </para>
472      </sect3>
473     
474      <sect3 id="write_docbook_doc.begin.helptext.import">
475      <title>Import help texts into BASE</title>
476
477      <para>
478        Import the generated XML-file manually by uploading it from the
479        <filename class="directory">data</filename>
480        directory to the BASE-server's file system and then use the help text importer
481        plugin to import the help text items from that file.
482      </para>
483     
484      <para>
485        The help texts can also be imported by running the TestHelp
486        test program. In short, here are the commands you need to
487        import the help texts:
488      </para>
489     
490<programlisting>ant docbook
491ant test
492cd build/test
493./run.sh TestHelp</programlisting>
494      </sect3>
495     
496    </sect2>
497    <sect2 id="write_docbook_doc.begin.generate">
498      <title>Generate output</title>
499
500      <sect3 id="write_docbook_doc.begin.generate.requirements">
501        <title>Requirements</title>
502        <para>
503          Those who have checked out the documentation source from repository or got the
504          source from a distribution package needs to compile it to get the PDF and HTML
505          documentation files. The compilation of the documentation source requires, beside Ant, that the XML-parser
506          Xsltproc is installed on the local computer. More information about
507          XsltProc and how it is installed, can be found at
508          <ulink url="http://xmlsoft.org/XSLT/index.html"></ulink>.
509        </para>
510        <note>
511          <para>
512            There is an xml-parser in newer java-versions that can be used instead of
513            XsltProc but the compilation will most likely take much much longer time.
514            Therefore it's not recommended to be used when generating/compiling the
515            documentation in BASE 2.
516          </para>
517        </note>
518      </sect3>
519      <sect3 id="write_docbook_doc.begin.generate.compile">
520        <title>Compile - generate output files</title>
521        <para>
522          There are two different types of format that is generated from the documentation
523          source. The format to view the documentation on-line will be the one with
524          chunked HTML pages where each chapter and section of first level are on separate
525          pages/files. The other format is a PDF-file that are most useful for printing
526          and distribution. Those two types of output are generated with the ant-target:
527          <command>ant docbook</command>. This documentation is also generated with
528          <command>ant dist</command>, which will put the output files in the right location for distribution with
529          BASE 2.
530        </para>
531      </sect3>
532    </sect2>
533  </sect1>
534
535  <sect1 id="write_docbook_doc.usedtags">
536    <title>Elements to use</title>
537    <para>
538      The purpose with this section is to give an overview of those docbook elements that are
539      most common in this documentation and to give some example on how they should be used.
540      There will not be any detailed explanation of the tags here, instead the reader is
541      recommended to get more information from
542      <ulink url="http://www.docbook.org/tdg/en/html/docbook.html">
543        Docbook's documentation
544      </ulink>
545      or other references.
546    </para>
547    <sect2 id="write_docbook_doc.usedtags.text">
548      <title>Text elements</title>
549      <para>
550       
551      </para>
552      <informaltable frame="none">
553        <tgroup cols="3" rowsep="1" colsep="1">
554          <colspec align="left" />
555          <colspec align="center" />
556          <colspec align="left" />
557          <thead>
558            <row>
559              <entry>Define</entry>
560              <entry>Element to use</entry>
561              <entry>Comments</entry>
562            </row>
563          </thead>
564          <tbody>
565            <row>
566              <entry>Chapter</entry>
567              <entry>
568                <sgmltag class="starttag">chapter</sgmltag>
569              </entry>
570              <entry>
571                <para>
572                  See
573                  <xref linkend="write_docbook_doc.examples.chapterbody" />
574                </para>
575              </entry>
576            </row>
577            <row>
578              <entry>Title</entry>
579              <entry>
580                <sgmltag class="starttag">title</sgmltag>
581              </entry>
582              <entry>
583                <xref linkend="write_docbook_doc.examples.chapterbody" />
584                shows how this can be implemented
585              </entry>
586            </row>
587            <row>
588              <entry>Paragraph</entry>
589              <entry>
590                <sgmltag class="starttag">para</sgmltag>
591              </entry>
592              <entry>Used almost everywhere around real text.</entry>
593            </row>
594            <row>
595              <entry>Top-level subsection</entry>
596              <entry>
597                <sgmltag class="starttag">sect1</sgmltag>
598              </entry>
599              <entry>
600                See
601                <xref linkend="write_docbook_doc.begin.id" />
602              </entry>
603            </row>
604            <row>
605              <entry>Second level section</entry>
606              <entry>
607                <sgmltag class="starttag">sect2</sgmltag>
608              </entry>
609              <entry>
610                See
611                <xref linkend="write_docbook_doc.begin.id" />
612              </entry>
613            </row>
614            <row>
615              <entry>Third level section</entry>
616              <entry>
617                <sgmltag class="starttag">sect3</sgmltag>
618              </entry>
619              <entry>
620                See
621                <xref linkend="write_docbook_doc.begin.id" />
622              </entry>
623            </row>
624            <row>
625              <entry>Fourth level section</entry>
626              <entry>
627                <sgmltag class="starttag">sect4</sgmltag>
628              </entry>
629              <entry></entry>
630            </row>
631            <row>
632              <entry>Fith level section</entry>
633              <entry>
634                <sgmltag class="starttag">sect5</sgmltag>
635              </entry>
636              <entry></entry>
637            </row>
638          </tbody>
639        </tgroup>
640      </informaltable>
641
642      <sect3 id="write_docbook_doc.usedtags.text.keywords">
643        <title>Code elements</title>
644        <para>
645          These elements should be used to mark up words and phrases that have a special
646          meaning in a coding environment, like method names, class names and
647          user inputs, etc.
648        </para>
649        <informaltable frame="none">
650          <tgroup cols="3" rowsep="1" colsep="1">
651            <colspec align="left" />
652            <colspec align="center" />
653            <colspec align="left" />
654            <thead>
655              <row>
656                <entry>Define</entry>
657                <entry>Element to use</entry>
658                <entry>Comment</entry>
659              </row>
660            </thead>
661            <tbody>
662              <row>
663                <entry>Class name</entry>
664                <entry>
665                  <sgmltag class="starttag">classname</sgmltag>
666                </entry>
667                <entry>The name of a (Java) class.</entry>
668              </row>
669              <row>
670                <entry>User input</entry>
671                <entry>
672                  <sgmltag class="starttag">userinput</sgmltag>
673                </entry>
674                <entry>Text that is entered by a user.</entry>
675              </row>
676              <row>
677                <entry>Variable name</entry>
678                <entry>
679                  <sgmltag class="starttag">varname</sgmltag>
680                </entry>
681                <entry>The name of a variable in a program.</entry>
682              </row>
683              <row>
684                <entry>Constant</entry>
685                <entry>
686                  <sgmltag class="starttag">constant</sgmltag>
687                </entry>
688                <entry>The name of a variable in a program.</entry>
689              </row>
690              <row>
691                <entry>Method definition</entry>
692                <entry>
693                  <sgmltag class="starttag">methodsynopsis</sgmltag>
694                </entry>
695                <entry>
696                  See
697                  <xref linkend="write_docbook_doc.examples.methodimpl" />
698                </entry>
699              </row>
700              <row>
701                <entry>Modifier of a method</entry>
702                <entry>
703                  <sgmltag class="starttag">modifier</sgmltag>
704                </entry>
705                <entry>
706                  See
707                  <xref linkend="write_docbook_doc.examples.methodimpl" />
708                </entry>
709              </row>
710              <row>
711                <entry>Classification of return value</entry>
712                <entry>
713                  <sgmltag class="starttag">type</sgmltag>
714                </entry>
715                <entry>
716                  See
717                  <xref linkend="write_docbook_doc.examples.methodimpl" />
718                </entry>
719              </row>
720              <row>
721                <entry>Method name</entry>
722                <entry>
723                  <sgmltag class="starttag">methodname</sgmltag>
724                </entry>
725                <entry>
726                  See
727                  <xref linkend="write_docbook_doc.examples.methodimpl" />
728                </entry>
729              </row>
730              <row>
731                <entry>No parameter/type</entry>
732                <entry>
733                  <sgmltag class="starttag">void</sgmltag>
734                </entry>
735                <entry>
736                  See
737                  <xref linkend="write_docbook_doc.examples.methodimpl" />
738                </entry>
739              </row>
740              <row>
741                <entry>Define a parameter</entry>
742                <entry>
743                  <sgmltag class="starttag">methodparam</sgmltag>
744                </entry>
745                <entry>
746                  See
747                  <xref linkend="write_docbook_doc.examples.methodimpl1" />
748                </entry>
749              </row>
750              <row>
751                <entry>Parameter type</entry>
752                <entry>
753                  <sgmltag class="starttag">type</sgmltag>
754                </entry>
755                <entry>
756                  See
757                  <xref linkend="write_docbook_doc.examples.methodimpl1" />
758                </entry>
759              </row>
760              <row>
761                <entry>Parameter name</entry>
762                <entry>
763                  <sgmltag class="starttag">parameter</sgmltag>
764                </entry>
765                <entry>
766                  See
767                  <xref linkend="write_docbook_doc.examples.methodimpl1" />
768                </entry>
769              </row>
770            </tbody>
771          </tgroup>
772        </informaltable>
773        <para>
774          Follow one of the examples below to insert a method definition in the document.
775        </para>
776        <example id="write_docbook_doc.examples.methodimpl">
777          <title>
778            Method with no arguments and a return value
779          </title>
780<programlisting>&hellip;
781&lt;methodsynopsis language="java"&gt;
782   &lt;modifier&gt;public&lt;/modifier&gt;
783   &lt;type&gt;Plugin.MainType&lt;/type&gt;
784   &lt;methodname&gt;getMainType&lt;/methodname&gt;
785   &lt;void /&gt;
786&lt;/methodsynopsis&gt;
787&hellip;</programlisting>
788        </example>
789        <example id="write_docbook_doc.examples.methodimpl1">
790          <title>
791            Method with arguments and no return value
792          </title>
793<programlisting>&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;</programlisting>
812        </example>
813       
814      </sect3>
815      <sect3 id="write_docbook_doc.usedtags.text.gui">
816        <title>Gui elements</title>
817        <para>
818          Docbook has some elements that can be used to symbolize gui items in a program.
819          Following list contains the ones that are most common in this document.
820        </para>
821        <informaltable frame="none">
822          <tgroup cols="3" rowsep="1" colsep="1">
823            <colspec align="left" />
824            <colspec align="center" />
825            <colspec align="left" />
826            <thead>
827              <row>
828                <entry>Define</entry>
829                <entry>Element to use</entry>
830                <entry>Comment</entry>
831              </row>
832            </thead>
833            <tbody>
834              <row>
835                <entry>Button</entry>
836                <entry>
837                  <sgmltag class="starttag">guibutton</sgmltag>
838                </entry>
839                <entry></entry>
840              </row>
841              <row>
842                <entry>Label</entry>
843                <entry>
844                  <sgmltag class="starttag">guilabel</sgmltag>
845                </entry>
846                <entry></entry>
847              </row>
848              <row>
849                <entry>Menu choice</entry>
850                <entry>
851                  <sgmltag class="starttag">menuchoice</sgmltag>
852                </entry>
853                <entry></entry>
854              </row>
855              <row>
856                <entry>Menu</entry>
857                <entry>
858                  <sgmltag class="starttag">guimenu</sgmltag>
859                </entry>
860                <entry></entry>
861              </row>
862              <row>
863                <entry>Submenu</entry>
864                <entry>
865                  <sgmltag class="starttag">guisubmenu</sgmltag>
866                </entry>
867                <entry></entry>
868              </row>
869              <row>
870                <entry>Menu item</entry>
871                <entry>
872                  <sgmltag class="starttag">guimenuitem</sgmltag>
873                </entry>
874                <entry></entry>
875              </row>
876              <row>
877                <entry>Icon</entry>
878                <entry>
879                  <sgmltag class="starttag">guiicon</sgmltag>
880                </entry>
881                <entry></entry>
882              </row>
883            </tbody>
884          </tgroup>
885        </informaltable>
886        <para>
887          <xref linkend="write_docbook_doc.examples.guielements" />
888          shows how the menu choice in figure
889          <xref linkend="write_docbook_doc.figures.menuchoice" />
890          can be described.
891        </para>
892        <figure id="write_docbook_doc.figures.menuchoice">
893          <title>Menu choice</title>
894          <screenshot>
895            <mediaobject>
896              <imageobject>
897                <imagedata 
898                  fileref="figures/menuchoice.png" format="PNG" 
899                />
900              </imageobject>
901            </mediaobject>
902          </screenshot>
903        </figure>
904        <example id="write_docbook_doc.examples.guielements">
905          <title>Describe a menu choice</title>
906<programlisting>&hellip;         
907&lt;menuchoice&gt;
908   &lt;guimenu&gt;Administrate&lt;/guimenu&gt;
909   &lt;guisubmenu&gt;Plugins&lt;/guisubmenu&gt;
910   &lt;guimenuitem&gt;Types&lt;/guimenuitem&gt;
911&lt;/menuchoice&gt;
912&hellip;</programlisting>
913          <para>
914            In the text it will look like this:
915            <menuchoice>
916              <guimenu>Administrate</guimenu>
917              <guisubmenu>Plugins</guisubmenu>
918              <guimenuitem>Types</guimenuitem>
919            </menuchoice>
920          </para>
921        </example>
922      </sect3>
923    </sect2>
924    <sect2 id="write_docbook_doc.usedtags.images">
925      <title>Images and figures</title>
926      <para>
927        Images and figures are normally implemented like the following example. The
928        image-file must be located in
929        <filename class="directory">doc/src/docbook/figures</filename>,
930        otherwise the image will not be visible in the generated output files.
931      </para>
932
933      <example id="write_docbook_doc.examples.screenshot">
934        <title>Screen-shot in the documentation</title>
935        <para>
936          <xref linkend="webclient.figures.homepage" />
937          is implemented with the following code
938        </para>
939<programlisting>&lt;figure id="write_docbook_doc.figures.menuchoice"&gt;
940  &lt;title&gt;The home page&lt;/title&gt;
941  &lt;screenshot&gt;
942    &lt;mediaobject&gt;
943      &lt;imageobject&gt;
944        &lt;imagedata
945          scalefit="1"
946          width="100%"
947          fileref="figures/homapage.png" format="PNG"
948        /&gt;
949      &lt;/imageobject&gt;
950    &lt;/mediaobject&gt;
951  &lt;/screenshot&gt;
952&lt;/figure&gt;</programlisting>
953      </example>
954      <warning>
955        <para>
956          When using images in docbook you will always have problems with image
957          resolution and scaling. Since we are generating output for both HTML
958          and PDF it is even worse. What we have found to work is this:
959         
960          <itemizedlist>
961          <listitem>
962            <para>
963            The screenshots must be saved without any resolution information
964            in them, or with the resolution set to 96 dpi. We have configured PDF to
965            use 96 dpi instead of 72 dpi to make the HTML and PDF output
966            look as similar as possible.
967            </para>
968          </listitem>
969         
970          <listitem>
971            <para>
972            Scaling in HTML has been disabled. The images will always be the
973            same size (number of pixels) as they actually are. Please, do not
974            make the screenshots too wide!
975           
976            <tip>
977              <para>
978              Change your BASE <link linkend="webclient.configuration.preferences"
979                >preferences</link> to a smaller font size or use
980              the zoom functionality in the web browser to make more information
981              fit in the same image width.
982              </para>
983            </tip>
984           
985            </para>
986          </listitem>
987         
988          <listitem>
989            <para>
990            For small images, less than the width of the PDF page,
991            do not specify scaling factors or widths.
992            </para>
993          </listitem>
994         
995          <listitem>
996            <para>
997            Images that are wider than the PDF page will be clipped. To
998            prevent this you must add the following attributes to the
999            <sgmltag class="starttag">imagedata</sgmltag> tag:
1000            <code>scalefit="1" width="100%"</code>. This will scale down
1001            the image so that it fits the available width.
1002            </para>
1003          </listitem>
1004         
1005          <listitem>
1006            <para>
1007            If you still need to scale the image differently in the PDF use
1008            the <sgmltag>width</sgmltag> and <sgmltag>depth</sgmltag>
1009            attributes.
1010            </para>
1011          </listitem>
1012          </itemizedlist>
1013        </para>
1014      </warning>
1015    </sect2>
1016    <sect2 id="write_docbook_doc.usedtags.examples">
1017      <title>Examples and program listing</title>
1018      <para>
1019        Following describes how to insert an example in the documentation.The examples in
1020        this document are often some kind of program listing but they can still be examples
1021        of something else.
1022      </para>
1023      <warning>
1024        <title>Use spaces instead of tabs for indentation</title>
1025        <para>
1026          Use spaces for indentation in program listing, this is because of the
1027          tab-indentations will sooner or later cause corrupt text.
1028        </para>
1029      </warning>
1030      <note>
1031        <itemizedlist>
1032          <listitem>
1033            <simpara>
1034              The verbatim text must begin on the same row as the start tag of a
1035              verbatim element if you do not want an empty line at the top of the
1036              text area.
1037            </simpara>
1038          </listitem>
1039          <listitem>
1040            <simpara>
1041              The verbatim text is splitted into several lines if the text contains
1042              more then 80 characters. This could give the text an unwanted look and
1043              it's therefore recommended to manually insert new lines to have controll
1044              over layout of the text
1045            </simpara>
1046          </listitem>
1047        </itemizedlist>
1048      </note>
1049      <example id="write_docbook_doc.examples.example">
1050        <title>Example in the documentation</title>
1051        <para>
1052          This shows how 
1053          <xref linkend="net.sf.basedb.core.plugin.Plugin.getAbout" />
1054          is written in the corresponding XML-file.
1055        </para>
1056<programlisting>&hellip;
1057&lt;example id="net.sf.basedb.core.plugin.Plugin.getAbout"&gt;
1058   &lt;title&gt;A typical implementation stores this information
1059      in a static field&lt;/title&gt;
1060   &lt;programlisting&gt;private static final About about = new AboutImpl
1061(
1062   "Spot images creator",
1063   "Converts a full-size scanned image into smaller preview jpg " +
1064   "images for each individual spot.",
1065   "2.0",
1066   "2006, Department of Theoretical Physics, Lund University",
1067   null,
1068   "base@thep.lu.se",
1069   "http://base.thep.lu.se"
1070);
1071 
1072public About getAbout()
1073{
1074   return about;
1075} &lt;/programlisting&gt;
1076&lt;/example&gt;
1077&hellip;</programlisting>
1078      </example>     
1079    </sect2>
1080    <sect2 id="write_docbook_doc.usedtags.admonitions">
1081      <title>Admonitions</title>
1082      <para>
1083        The admonitions that are used in this document can be found in the table below.
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 to use</entry>
1094              <entry>Comment</entry>
1095            </row>
1096          </thead>
1097          <tbody>
1098            <row>
1099              <entry>Warning text</entry>
1100              <entry>
1101                <sgmltag class="starttag">warning</sgmltag>
1102              </entry>
1103              <entry></entry>
1104            </row>
1105            <row>
1106              <entry>Notification text</entry>
1107              <entry>
1108                <sgmltag class="starttag">note</sgmltag>
1109              </entry>
1110              <entry></entry>
1111            </row>
1112            <row>
1113              <entry>A tip</entry>
1114              <entry>
1115                <sgmltag class="starttag">tip</sgmltag>
1116              </entry>
1117              <entry></entry>
1118            </row>
1119            <row>
1120              <entry>Important text</entry>
1121              <entry>
1122                <sgmltag class="starttag">important</sgmltag>
1123              </entry>
1124              <entry></entry>
1125            </row>
1126            <row>
1127              <entry>Something to be cautious about</entry>
1128              <entry>
1129                <sgmltag class="starttag">caution</sgmltag>
1130              </entry>
1131              <entry></entry>
1132            </row>
1133          </tbody>
1134        </tgroup>
1135      </informaltable>
1136    </sect2>
1137    <sect2 id="write_docbook_doc.usedtags.lists">
1138      <title>Lists</title>
1139      <para>
1140        Following items can be used to define different kind of lists in the documentation.
1141        Some common elements for the lists are also described here.
1142      </para>
1143      <informaltable frame="none">
1144        <tgroup cols="3" rowsep="1" colsep="1">
1145          <colspec align="left" />
1146          <colspec align="center" />
1147          <colspec align="left" />
1148          <thead>
1149            <row>
1150              <entry>Define</entry>
1151              <entry>Element</entry>
1152              <entry>Comment</entry>
1153            </row>
1154          </thead>
1155          <tbody>           
1156            <row>
1157              <entry>None-ordered list</entry>
1158              <entry>
1159                <sgmltag class="starttag">itemizedlist</sgmltag>
1160              </entry>
1161              <entry></entry>
1162            </row>
1163            <row>
1164              <entry>Term definition list</entry>
1165              <entry>
1166                <sgmltag class="starttag">variablelist</sgmltag>
1167              </entry>
1168              <entry></entry>
1169            </row>
1170            <row>
1171              <entry>Ordered list</entry>
1172              <entry>
1173                <sgmltag class="starttag">orderedlist</sgmltag>
1174              </entry>
1175              <entry></entry>
1176            </row>
1177            <row>
1178              <entry>List item</entry>
1179              <entry>
1180                <sgmltag class="starttag">listitem</sgmltag>
1181              </entry>
1182              <entry></entry>
1183            </row>
1184          </tbody>
1185        </tgroup>
1186      </informaltable>
1187      <para>The example below shows how to create a list for term definition in the text.</para>
1188      <example id="write_docbook_doc.examples.variablelist">
1189        <title>Example how to write a variable list</title>
1190<programlisting>&hellip;
1191&lt;variablelist&gt;
1192   &lt;varlistentry&gt;
1193      &lt;term&gt;Term1&lt;/term&gt;
1194      &lt;listitem&gt;
1195         &lt;para&gt;
1196            Definition/explanation of the term
1197         &lt;/para&gt;
1198      &lt;/listitem&gt;
1199   &lt;/varlistentry&gt;
1200   
1201   &lt;varlistentry&gt;
1202      &lt;term&gt;Term2&lt;/term&gt;
1203      &lt;listitem&gt;
1204         &lt;para&gt;
1205            Definition/explanation of the term
1206         &lt;/para&gt;
1207      &lt;/listitem&gt;
1208   &lt;/varlistentry&gt;
1209&lt;/variablelist&gt;</programlisting>
1210      </example>
1211    </sect2>
1212   
1213    <sect2 id="write_docbook_doc.usedtags.links">
1214      <title>Link elements</title>
1215      <para></para>
1216      <informaltable frame="none">
1217        <tgroup cols="3" rowsep="1" colsep="1">
1218          <colspec align="left" />
1219          <colspec align="center" />
1220          <colspec align="left" />
1221          <thead>
1222            <row>
1223              <entry>Define</entry>
1224              <entry>Element</entry>
1225              <entry>Comment</entry>
1226            </row>
1227          </thead>
1228          <tbody>
1229            <row>
1230              <entry>Cross reference</entry>
1231              <entry>
1232                <sgmltag class="starttag">xref linkend=""</sgmltag>
1233              </entry>
1234              <entry>Use this to linke to other parts of the document.</entry>
1235            </row>
1236            <row>
1237              <entry>Cross reference with own text</entry>
1238              <entry>
1239                <sgmltag class="starttag">link</sgmltag>
1240              </entry>
1241              <entry>
1242                Can be used as an alternative to
1243                <sgmltag>xref</sgmltag>
1244              </entry>
1245            </row>
1246            <row>
1247              <entry>External URLs</entry>
1248              <entry>
1249                <sgmltag class="starttag">ulink url=""</sgmltag>
1250              </entry>
1251              <entry></entry>
1252            </row>
1253          </tbody>
1254        </tgroup>
1255      </informaltable>
1256      <example id="write_docbook_doc.examples.links">
1257        <title>Links</title>
1258<programlisting>&hellip;
1259&lt;xref linkend="write_docbook_doc.usedtags.links" /&gt;
1260&lt;link linkend="write_docbook_doc.usedtags.links"&gt;Link to this section&lt;/link&gt;
1261&lt;ulink url="http://base.thep.lu.se"&gt;Base2's homepage&lt;/ulink&gt;
1262&hellip;</programlisting>
1263        <para>
1264          The first element will autogenerate the linked section's/chapter's title as a
1265          hyperlinked text. As an alternative to
1266          <sgmltag>xref</sgmltag>
1267          is
1268          <sgmltag>link</sgmltag>
1269          that lets you write your own hyperlinked text. The third and last one should be
1270          used to link to any URL outside the document.
1271        </para>
1272      </example>
1273    </sect2>
1274  </sect1>
1275</chapter>
Note: See TracBrowser for help on using the repository browser.