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

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

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