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

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

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