source: trunk/doc/src/docbook/developer/documentation.xml @ 5782

Last change on this file since 5782 was 5782, checked in by Nicklas Nordborg, 10 years ago

References #1590: Documentation cleanup

Restructured documentation to generate shorter filenames.

File size: 64.4 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id$
7 
8  Copyright (C) 2007 Jari Häkkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson
9 
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12 
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 3
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 BASE. If not, see <http://www.gnu.org/licenses/>.
25-->
26
27<chapter id="documentation">
28  <?dbhtml dir="documentation" filename="index.html" ?>
29  <title>Write documentation</title>
30
31  <sect1 id="documentation.docbook">
32    <?dbhtml filename="docbook.html" ?>
33    <title>User, administrator and developer documentation with Docbook</title>
34
35    <para>
36      This chapter is for those who intent to contribute to the BASE user documentation.
37      The chapter contains explanations of how the documentation is organized, what the
38      different parts is about and other things that will make it easier to know
39      where to insert new text.
40    </para>
41    <para>
42      The documentation is written with the docbook standard, which is a bunch of defined XML
43      elements and XSLT style sheets that are used to format the text. Later on in this chapter
44      is a reference, over those docbook elements that are recommended to use when writing BASE
45      documentation. Further information about docbook can be found in the on-line version of
46      O'Reilly's
47      <ulink url="http://www.docbook.org/tdg/en/html/">DocBook: The Definitive Guide</ulink>
48      by Norman Walsh and Leonard Muellner.
49    </para>
50   
51
52  <sect2 id="docbook.layout">
53    <title>Documentation layout</title>
54    <para>
55      The book, which is the main element in this docbook documentation, is divided into four
56      separated parts, depending on who the information is directed to. What kind of
57      documentation each one of these parts contains or should contain is described here
58      below.
59    </para>
60    <variablelist>
61      <varlistentry>
62        <term>Overview documentation</term>
63        <listitem>
64          <para>
65            The overview part contains, like the name says, an overview of BASE.
66            For example an explanation about what the purpose with BASE is, the terms
67            that are used in the program and other general things that anyone that is
68            interested in the program wants/needs to know before exploring it further.
69          </para>
70        </listitem>
71      </varlistentry>
72      <varlistentry>
73        <term>User documentation</term>
74        <listitem>
75          <para>
76            This part contains information that are relevant for the common BASE-user.
77            More or less should everything that a power user role or an user role needs
78            to know be included here.
79          </para>
80        </listitem>
81      </varlistentry>
82      <varlistentry>
83        <term>Administrator documentation</term>
84        <listitem>
85          <para>
86            Things that only an administrator-role can do is documented in this part. It
87            can be how to install the program, how to configure the server for best
88            performance or other subjects that are related to the administration.
89          </para>
90        </listitem>
91      </varlistentry>
92      <varlistentry>
93        <term>Developer documentation</term>
94        <listitem>
95          <para>
96            Documentation concerning the participation of BASE development should be placed
97            in this part, e.g. coding standards, the java doc from the source code, how
98            to develop a plug-in etc.
99          </para>
100        </listitem>
101      </varlistentry>
102    </variablelist>
103  </sect2>
104
105
106  <sect2 id="docbook.begin">
107    <title>Getting started</title>
108    <para>
109      Before writing any documentation in BASE there are a couple of things, some
110      rules and standards, to have in mind.
111    </para>
112    <sect3 id="docbook.begin.sourcefiles">
113      <title>Organization of source files</title>
114      <para>
115        The source files of the documentation are located in
116        <filename class='directory'>&lt;base-dir&gt;/doc/src/docbook</filename>.
117        The different parts of the documentation are organized into separate folders and
118        each one of the folders contains one index file and one file for each chapter in
119        that part. The index file joins the chapters, in current part/folder, together and
120        does not really contain any text. The documentation root directory also contains an
121        <filename class='headerfile'>index.xml</filename>
122        file which joins the index files from the different parts together.
123      </para>
124      <figure id="docbook.figures.fileorganization">
125        <title>The organization of documentation files</title>
126        <screenshot>
127          <mediaobject>
128            <imageobject>
129              <imagedata fileref="figures/fileorganization.png" format="PNG" />
130            </imageobject>
131          </mediaobject>
132        </screenshot>
133      </figure>
134      <sect4 id="docbook.begin.sourcefiles.newfile">
135        <title>Create new chapter/file</title>
136        <para>
137          Most files in the documentation, except the index files, represents a chapter.
138          Here is how to create a new chapter and include it in the main documentation:
139          <orderedlist numeration='arabic' spacing='compact'>
140            <listitem>
141              <para>
142                Create a new XML-file in the folder for the part where the new chapter
143                should be included. Give it a name that is quite similar to the
144                new chapter's title but use <userinput>_</userinput> instead of
145                blank space and keep it down to one or a few words.
146              </para>
147            </listitem>
148            <listitem>
149              <para>
150                Begin to write the chapter's body, here is an example:
151                <example id="docbook.examples.chapterbody">
152                  <title>Example of a chapter</title>
153<programlisting language="xml">&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="example_chapter"&gt;
159   &lt;?dbhtml dir="folder name to put the chapter's files in"?&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="example_chapter.sect1"&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="example_chapter.sect1.sect2"&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="example_chapter.sect1.sect2.sect3"&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;</programlisting>
183                </example>
184              </para>
185              <note>
186                <para>
187                  Do not forget to include the
188                  <sgmltag>dbhtml</sgmltag>
189                  tag with the attribute
190                  <sgmltag class="attribute">dir</sgmltag>
191                  set to the value that the chapter's output folder should have as a
192                  name.
193                </para>
194              </note>
195            </listitem>
196            <listitem>
197              <para>
198                The last step is to get the new chapter included in the documentation. This is done by including the file's name in
199                the file
200                <filename>index.xml</filename>
201                that's located in the current part's folder.
202                The following example
203                shows how the chapter that was created above is included in the user
204                documentation part.
205              </para>
206              <example id="docbook.examples.include_chapter">
207                <title>Include a chapter</title>
208<programlisting language="xml:nogutter:nocontrols">&lt;part id="userdoc"&gt;
209   &lt;title&gt;User documentation&lt;/title&gt;
210   &lt;include file= "about.xml"/&gt;
211   &lt;include file="webclient.xml"/&gt;
212   &lt;include file="project_permission.xml"/&gt;
213   &lt;include file="trashcan.xml"/&gt;
214   &lt;include file="file_system.xml"/&gt;
215   &lt;include file="jobs.xml"/&gt;
216   &lt;include file="reporters.xml"/&gt;
217   &lt;include file="annotations.xml"/&gt;
218   &lt;include file="protocols.xml"/&gt;
219   &lt;include file="hardware.xml"/&gt;
220   &lt;include file="example_chapter.xml"/&gt;
221   &lt;include file="software.xml"/&gt;
222   &lt;include file="array_lims.xml"/&gt;
223   &lt;include file="biomaterials.xml"/&gt;
224   &lt;include file="experiments_analysis.xml"/&gt;
225   &lt;include file="import_export_data.xml"/&gt;
226&lt;/part&gt;</programlisting>
227                </example>
228              <note>
229                <title>Order of chapters</title>
230                <para>
231                  The chapters will come in the same order as they are included in
232                  the index file.
233                </para>
234              </note>
235            </listitem>     
236          </orderedlist>
237          Now it's only to go ahead with the documentation writing.
238        </para>
239      </sect4>
240    </sect3>
241   
242    <sect3 id="docbook.begin.chunking">
243      <title>Controlling chunking</title>
244      <para>
245        We have configured docbook to create a new sub-directory for each
246        <sgmltag class="starttag">chapter</sgmltag> and a new output file for each
247        <sgmltag class="starttag">sect1</sgmltag> tag. In most cases this
248        gives each page a relatively good size. Not too long and not too short.
249        However, if a chapter contains many small <sgmltag class="starttag">sect1</sgmltag>
250        sections (for example, <xref linkend="resources"/>), you end up with many
251        pages with just a few lines of text on each page. This is not so
252        good and can be avoided by adding <sgmltag class="attribute">chunked="0"</sgmltag>
253        as an attribute to the <sgmltag class="starttag">chapter</sgmltag> tag, for example:
254      </para>
255      <programlisting language="xml">&lt;chapter id="resources" chunked="0"&gt;</programlisting>
256      <para>
257        This will stop the chunking of <sgmltag class="starttag">sect1</sgmltag>
258        sections in this chapter.
259      </para>
260     
261      <para>
262        On the other
263        hand, if you have a <sgmltag class="starttag">sect1</sgmltag>
264        that contains many long <sgmltag class="starttag">sect2</sgmltag>
265        sections you might want to put each <sgmltag class="starttag">sect2</sgmltag>
266        section in a separate chunk:
267      </para>
268      <programlisting language="xml">&lt;sect1 id="sect.with.large.sect2" chunked="1"&gt;</programlisting>
269   
270    </sect3>
271   
272    <sect3 id="docbook.begin.id">
273      <title>
274        The
275        <sgmltag class="attribute">id</sgmltag>
276        attribute
277      </title>
278      <para>
279        Common to all elements is that they have an <sgmltag class="attribute">id</sgmltag>
280        attribute that can be used to identify the
281        element with. The value must be unique for the entire documentation.
282        Most of the elements that are used inside the BASE documentation do not
283        need to have an id if they do not are used in any cross references from other part of
284        the text.
285      </para>
286      <para>
287        There are some elements that always should have the
288        <sgmltag class="attribute">id</sgmltag>
289        set. Which these elements are and how the
290        <sgmltag class="attribute">id</sgmltag>
291        should look like for each one of those is described below. All values should be as
292        short as possible and associated to the current element. The
293        <sgmltag class="attribute">id</sgmltag>
294        value should only consist of the lowercase characters a-z, '_' instead of blank
295        spaces and '.' to symbolize the different levels in the document.
296        <variablelist>
297          <varlistentry>
298            <term>chapter</term>
299            <listitem>
300              <para>
301                The chapter should have an
302                <sgmltag class="attribute">id</sgmltag>
303                that is identical or almost identical to the chapter's title.
304                <synopsis>chapter_title</synopsis>
305              </para>
306            </listitem>
307          </varlistentry>
308          <varlistentry>
309            <term>sect1-sect5</term>
310            <listitem>
311              <para>
312                The creation of a section's id is done by using the upper level's id
313                and add the section's title or a part of the title. For
314                &lt;sect2&gt; it should be like this;
315                <synopsis>chapter_title.sect1_title.sect2_title</synopsis>
316              </para>
317            </listitem>
318          </varlistentry>
319          <varlistentry>
320            <term>examples</term>
321            <listitem>
322              <para>
323                The naming of an example's
324                <sgmltag class="attribute">id</sgmltag>
325                is a bit different compare to the chapter's and section's id. It
326                should begin with the chapter's id followed by
327                <userinput>examples</userinput>
328                and the caption of the example.
329                <synopsis>chapter_title.examples.example_caption</synopsis>
330              </para>
331            </listitem>
332          </varlistentry>
333          <varlistentry>
334            <term>figures</term>
335            <listitem>
336              <para>
337                The figure's
338                <sgmltag class="attribute">id</sgmltag>
339                should have the following layout
340                <synopsis>chapter_title.figures.figure_name</synopsis>
341              </para>
342            </listitem>
343          </varlistentry>
344        </variablelist>
345      </para>
346    </sect3>
347    <sect3 id="docbook.begin.helptext">
348      <title>Mark help texts</title>
349      <para>
350        This documentation is also use to create the help texts that show up
351        in the web client when clicking on the question mark icons.
352        The parts of the text that also should be used as help texts in the web must be
353        inside
354        <sgmltag class="starttag">helptext</sgmltag>
355        tags. These texts will be exported to a XML-file at the same time as the
356        HTML-documentation is generated. The generated XML-file is compatible with the help
357        text importer in BASE and will be imported when running the update script or
358        installation script.
359      </para>
360      <note>
361      <para>
362        The
363        <sgmltag class="starttag">helptext</sgmltag>
364        must be outside the
365        <sgmltag class="starttag">para</sgmltag>
366        tag but inside a
367        <sgmltag class="starttag">sect</sgmltag> 
368        tag to work properly. Do not put any <sgmltag class="starttag">sect</sgmltag>
369        tags inside the helptext. This will make the automatic chapter and section
370        numbering confused.
371      </para>
372      </note>
373      <para>
374        The tag supports the following attributes
375        <variablelist>
376          <varlistentry>
377            <term>
378              <sgmltag class="attribute">external_id</sgmltag>
379            </term>
380            <listitem>
381              <para>
382                Is used to identify and to find a help text in the web client.
383                The BASE web client already has several IDs to help texts defined,
384                it could therefore be a good idea to have a look in the
385                program to see if there already is an external id to use for the
386                particular help text.
387              </para>
388            </listitem>
389          </varlistentry>
390          <varlistentry>
391            <term>
392              <sgmltag class="attribute">title</sgmltag>
393            </term>
394            <listitem>
395              <para>
396                Is directly connected to the name/title property for a help text
397                item in BASE.
398              </para>
399            </listitem>
400          </varlistentry>
401          <varlistentry>
402            <term>
403              <sgmltag class="attribute">webonly</sgmltag>
404            </term>
405            <listitem>
406              <para>
407                If set to a non-zero value, the contents of the tag
408                will not be outputted in the HTML or PDF documentation.
409                This is useful for minor functionality that is not
410                important enough to be mentioned in the documentation but has
411                a help icon in the web client.
412              </para>
413            </listitem>
414          </varlistentry>
415        </variablelist>
416      </para>
417      <example id="docbook.examples.helptexttag">
418        <title>How to use the help text tag</title>
419<programlisting language="xml">&lt;sect1&gt;
420   &lt;helptext external_id="helptexts.external.id" title="The title"&gt;
421      The text that also should be used as a helptext in the program.
422      &lt;seeother&gt;
423         &lt;other external_id="other.external.id"&gt;
424            Related info here...&lt;/other&gt;
425      &lt;/seeother&gt;
426   &lt;/helptext&gt;
427&lt;/sect1&gt;</programlisting>
428      </example>
429     
430      <sect4 id="docbook.begin.helptext.nohelp">
431        <title>Skip parts of a help text</title>
432        <para>
433          From time to time, it may happen that you find that
434          some parts of the text inside a <sgmltag class="starttag">helptext</sgmltag>
435          tag does not make sense. It may, for example, be a reference to
436          an image or an example, or a link to another chapter or
437          section. Put a <sgmltag class="starttag">nohelp</sgmltag>
438          tag around the problematic part to avoid it from being
439          outputted to the help texts.
440        </para>     
441        <programlisting language="xml">&lt;nohelp&gt;see &lt;xref linkend="chapter11" /&gt;&lt;/nohelp&gt;</programlisting>
442      </sect4>
443     
444      <sect4 id="docbook.begin.helptext.link">
445      <title>Link to other help texts</title>
446     
447      <para>
448        You can use <sgmltag class="starttag">seeother</sgmltag> and
449        <sgmltag class="starttag">other</sgmltag>
450        to create links between different help texts. The
451        <sgmltag  class="starttag">seeother</sgmltag>
452        tag does not have any attributes and is just a container for one or more
453        <sgmltag  class="starttag">other</sgmltag> tags. Each tag requires a single attribute.
454      </para>
455        <variablelist>
456          <varlistentry>
457            <term>
458              <sgmltag class="attribute">external_id</sgmltag>
459            </term>
460            <listitem>
461              <para>
462                The external ID of the other help text to link to.
463              </para>
464            </listitem>
465          </varlistentry>
466        </variablelist>
467       
468<programlisting language="xml">&lt;seeother&gt;
469  &lt;other external_id="userpreferences.password"&gt;Change password&lt;/other&gt;
470  &lt;other external_id="userpreferences.other"&gt;Other information&lt;/other&gt;
471&lt;/seeother&gt;</programlisting>
472       
473        <para>
474          We recommend that you place the links at the end of the
475          help text section. The links will not show up in the HTML or PDF version.
476        </para>
477      </sect4>
478     
479      <sect4 id="docbook.begin.helptext.import">
480      <title>Import help texts into BASE</title>
481
482      <para>
483        Import the generated XML-file manually by uploading it from the
484        <filename class="directory">data</filename>
485        directory to the BASE-server's file system and then use the help text importer
486        plug-in to import the help text items from that file.
487      </para>
488     
489      <para>
490        The help texts can also be imported by running the TestHelp
491        test program. In short, here are the commands you need to
492        import the help texts:
493      </para>
494     
495<programlisting>ant docbook
496ant test
497cd build/test
498./run.sh TestHelp</programlisting>
499      </sect4>
500     
501    </sect3>
502    <sect3 id="docbook.begin.generate">
503      <title>Generate output</title>
504
505      <sect4 id="docbook.begin.generate.requirements">
506        <title>Requirements</title>
507        <para>
508          Those who have checked out the documentation source from repository or got the
509          source from a distribution package needs to compile it to get the PDF and HTML
510          documentation files. The compilation of the documentation source requires, beside Ant, that the XML-parser
511          Xsltproc is installed on the local computer. More information about
512          XsltProc and how it is installed, can be found at
513          <ulink url="http://xmlsoft.org/XSLT/index.html"></ulink>.
514        </para>
515        <note>
516          <para>
517            There is an xml-parser in newer java-versions that can be used instead of
518            XsltProc but the compilation will most likely take much much longer time.
519            Therefore it's not recommended to be used when generating/compiling the
520            documentation in BASE.
521          </para>
522        </note>
523      </sect4>
524      <sect4 id="docbook.begin.generate.compile">
525        <title>Compile - generate output files</title>
526        <para>
527          There are two different types of format that is generated from the documentation
528          source. The format to view the documentation on-line will be the one with
529          chunked HTML pages where each chapter and section of first level are on separate
530          pages/files. The other format is a PDF-file that are most useful for printing
531          and distribution. Those two types of output are generated with the ant-target:
532          <command>ant docbook</command>. This documentation is also generated with
533          <command>ant dist</command>, which will put the output files in the right location for distribution with
534          BASE.
535        </para>
536      </sect4>
537    </sect3>
538  </sect2>
539
540  <sect2 id="docbook.usedtags">
541    <title>Docbook tags to use</title>
542    <para>
543      The purpose with this section is to give an overview of those docbook elements that are
544      most common in this documentation and to give some example on how they should be used.
545      There will not be any detailed explanation of the tags here, instead the reader is
546      recommended to get more information from
547      <ulink url="http://www.docbook.org/tdg/en/html/docbook.html">
548        Docbook's documentation
549      </ulink>
550      or other references.
551    </para>
552    <sect3 id="docbook.usedtags.text">
553      <title>Text elements</title>
554      <para>
555       
556      </para>
557      <informaltable frame="none">
558        <tgroup cols="3" rowsep="1" colsep="1">
559          <colspec align="left" />
560          <colspec align="center" />
561          <colspec align="left" />
562          <thead>
563            <row>
564              <entry>Define</entry>
565              <entry>Element to use</entry>
566              <entry>Comments</entry>
567            </row>
568          </thead>
569          <tbody>
570            <row>
571              <entry>Chapter</entry>
572              <entry>
573                <sgmltag class="starttag">chapter</sgmltag>
574              </entry>
575              <entry>
576                <para>
577                  See
578                  <xref linkend="docbook.examples.chapterbody" />
579                </para>
580              </entry>
581            </row>
582            <row>
583              <entry>Title</entry>
584              <entry>
585                <sgmltag class="starttag">title</sgmltag>
586              </entry>
587              <entry>
588                <xref linkend="docbook.examples.chapterbody" />
589                shows how this can be implemented
590              </entry>
591            </row>
592            <row>
593              <entry>Paragraph</entry>
594              <entry>
595                <sgmltag class="starttag">para</sgmltag>
596              </entry>
597              <entry>Used almost everywhere around real text.</entry>
598            </row>
599            <row>
600              <entry>Top-level subsection</entry>
601              <entry>
602                <sgmltag class="starttag">sect1</sgmltag>
603              </entry>
604              <entry>
605                See
606                <xref linkend="docbook.begin.id" />
607              </entry>
608            </row>
609            <row>
610              <entry>Second level section</entry>
611              <entry>
612                <sgmltag class="starttag">sect2</sgmltag>
613              </entry>
614              <entry>
615                See
616                <xref linkend="docbook.begin.id" />
617              </entry>
618            </row>
619            <row>
620              <entry>Third level section</entry>
621              <entry>
622                <sgmltag class="starttag">sect3</sgmltag>
623              </entry>
624              <entry>
625                See
626                <xref linkend="docbook.begin.id" />
627              </entry>
628            </row>
629            <row>
630              <entry>Fourth level section</entry>
631              <entry>
632                <sgmltag class="starttag">sect4</sgmltag>
633              </entry>
634              <entry></entry>
635            </row>
636            <row>
637              <entry>Fifth level section</entry>
638              <entry>
639                <sgmltag class="starttag">sect5</sgmltag>
640              </entry>
641              <entry></entry>
642            </row>
643          </tbody>
644        </tgroup>
645      </informaltable>
646
647      <sect4 id="docbook.usedtags.text.keywords">
648        <title>Code elements</title>
649        <para>
650          These elements should be used to mark up words and phrases that have a special
651          meaning in a coding environment, like method names, class names and
652          user inputs, etc.
653        </para>
654        <informaltable frame="none">
655          <tgroup cols="3" rowsep="1" colsep="1">
656            <colspec align="left" />
657            <colspec align="center" />
658            <colspec align="left" />
659            <thead>
660              <row>
661                <entry>Define</entry>
662                <entry>Element to use</entry>
663                <entry>Comment</entry>
664              </row>
665            </thead>
666            <tbody>
667              <row>
668                <entry>Class name</entry>
669                <entry>
670                  <sgmltag class="starttag">classname</sgmltag>
671                </entry>
672                <entry>
673                  The name of a (Java) class.
674                  <sgmltag class="attribute">docapi</sgmltag>-attribute
675                  can be used to link the class to it's Javadoc (only
676                  HTML-version). This is done by setting the attribute to the
677                  package name of the class, like
678                  <synopsis>net.sf.basedb.core</synopsis> 
679                </entry>
680              </row>
681              <row>
682                <entry>Interface name</entry>
683                <entry>
684                  <sgmltag class="starttag">interfacename</sgmltag>
685                </entry>
686                <entry>
687                  The name of an (Java) interface. Has a
688                  <sgmltag class="attribute">docapi</sgmltag>-attribute
689                  which has the same functionality as in
690                  <sgmltag>classname</sgmltag> above.                 
691                </entry>
692              </row>
693              <row>
694                <entry>User input</entry>
695                <entry>
696                  <sgmltag class="starttag">userinput</sgmltag>
697                </entry>
698                <entry>Text that is entered by a user.</entry>
699              </row>
700              <row>
701                <entry>Variable name</entry>
702                <entry>
703                  <sgmltag class="starttag">varname</sgmltag>
704                </entry>
705                <entry>The name of a variable in a program.</entry>
706              </row>
707              <row>
708                <entry>Constant</entry>
709                <entry>
710                  <sgmltag class="starttag">constant</sgmltag>
711                </entry>
712                <entry>The name of a variable in a program.</entry>
713              </row>
714              <row>
715                <entry>Method definition</entry>
716                <entry>
717                  <sgmltag class="starttag">methodsynopsis</sgmltag>
718                </entry>
719                <entry>
720                  See
721                  <xref linkend="docbook.examples.methodimpl" />
722                </entry>
723              </row>
724              <row>
725                <entry>Modifier of a method</entry>
726                <entry>
727                  <sgmltag class="starttag">modifier</sgmltag>
728                </entry>
729                <entry>
730                  See
731                  <xref linkend="docbook.examples.methodimpl" />
732                </entry>
733              </row>
734              <row>
735                <entry>Classification of return value</entry>
736                <entry>
737                  <sgmltag class="starttag">type</sgmltag>
738                </entry>
739                <entry>
740                  See
741                  <xref linkend="docbook.examples.methodimpl" />
742                </entry>
743              </row>
744              <row>
745                <entry>Method name</entry>
746                <entry>
747                  <sgmltag class="starttag">methodname</sgmltag>
748                </entry>
749                <entry>
750                  See
751                  <xref linkend="docbook.examples.methodimpl" />
752                </entry>
753              </row>
754              <row>
755                <entry>No parameter/type</entry>
756                <entry>
757                  <sgmltag class="starttag">void</sgmltag>
758                </entry>
759                <entry>
760                  See
761                  <xref linkend="docbook.examples.methodimpl" />
762                </entry>
763              </row>
764              <row>
765                <entry>Define a parameter</entry>
766                <entry>
767                  <sgmltag class="starttag">methodparam</sgmltag>
768                </entry>
769                <entry>
770                  See
771                  <xref linkend="docbook.examples.methodimpl1" />
772                </entry>
773              </row>
774              <row>
775                <entry>Parameter type</entry>
776                <entry>
777                  <sgmltag class="starttag">type</sgmltag>
778                </entry>
779                <entry>
780                  See
781                  <xref linkend="docbook.examples.methodimpl1" />
782                </entry>
783              </row>
784              <row>
785                <entry>Parameter name</entry>
786                <entry>
787                  <sgmltag class="starttag">parameter</sgmltag>
788                </entry>
789                <entry>
790                  See
791                  <xref linkend="docbook.examples.methodimpl1" />
792                </entry>
793              </row>
794            </tbody>
795          </tgroup>
796        </informaltable>
797        <para>
798          Follow one of the examples below to insert a method definition in the document.
799        </para>
800        <example id="docbook.examples.methodimpl">
801          <title>
802            Method with no arguments and a return value
803          </title>
804<programlisting language="xml">
805&lt;methodsynopsis language="java"&gt;
806   &lt;modifier&gt;public&lt;/modifier&gt;
807   &lt;type&gt;Plugin.MainType&lt;/type&gt;
808   &lt;methodname&gt;getMainType&lt;/methodname&gt;
809   &lt;void /&gt;
810&lt;/methodsynopsis&gt;
811</programlisting>
812        </example>
813        <example id="docbook.examples.methodimpl1">
814          <title>
815            Method with arguments and no return value
816          </title>
817<programlisting language="xml">
818&lt;methodsynopsis language="java"&gt;
819   &lt;modifier&gt;public&lt;/modifier&gt;
820   &lt;void /&gt;
821   &lt;methodname&gt;init&lt;/methodname&gt;
822   &lt;methodparam&gt;
823      &lt;type&gt;SessionControl&lt;/type&gt;
824      &lt;parameter&gt;sc&lt;/parameter&gt;
825   &lt;/methodparam&gt;
826   &lt;methodparam&gt;
827      &lt;type&gt;ParameterValues&lt;/type&gt;
828      &lt;parameter&gt;configuration&lt;/parameter&gt;
829   &lt;/methodparam&gt;
830   &lt;methodparam&gt;
831      &lt;type&gt;ParameterValues&lt;/type&gt;
832      &lt;parameter&gt;job&lt;/parameter&gt;
833   &lt;/methodparam&gt;
834&lt;/methodsynopsis&gt;
835</programlisting>
836        </example>
837       
838      </sect4>
839      <sect4 id="docbook.usedtags.text.gui">
840        <title>Gui elements</title>
841        <para>
842          Docbook has some elements that can be used to symbolize GUI items in a program.
843          Following list contains the ones that are most common in this document.
844        </para>
845        <informaltable frame="none">
846          <tgroup cols="3" rowsep="1" colsep="1">
847            <colspec align="left" />
848            <colspec align="center" />
849            <colspec align="left" />
850            <thead>
851              <row>
852                <entry>Define</entry>
853                <entry>Element to use</entry>
854                <entry>Comment</entry>
855              </row>
856            </thead>
857            <tbody>
858              <row>
859                <entry>Button</entry>
860                <entry>
861                  <sgmltag class="starttag">guibutton</sgmltag>
862                </entry>
863                <entry></entry>
864              </row>
865              <row>
866                <entry>Label</entry>
867                <entry>
868                  <sgmltag class="starttag">guilabel</sgmltag>
869                </entry>
870                <entry></entry>
871              </row>
872              <row>
873                <entry>Menu choice</entry>
874                <entry>
875                  <sgmltag class="starttag">menuchoice</sgmltag>
876                </entry>
877                <entry></entry>
878              </row>
879              <row>
880                <entry>Menu</entry>
881                <entry>
882                  <sgmltag class="starttag">guimenu</sgmltag>
883                </entry>
884                <entry></entry>
885              </row>
886              <row>
887                <entry>Submenu</entry>
888                <entry>
889                  <sgmltag class="starttag">guisubmenu</sgmltag>
890                </entry>
891                <entry></entry>
892              </row>
893              <row>
894                <entry>Menu item</entry>
895                <entry>
896                  <sgmltag class="starttag">guimenuitem</sgmltag>
897                </entry>
898                <entry></entry>
899              </row>
900              <row>
901                <entry>Icon</entry>
902                <entry>
903                  <sgmltag class="starttag">guiicon</sgmltag>
904                </entry>
905                <entry></entry>
906              </row>
907            </tbody>
908          </tgroup>
909        </informaltable>
910        <para>
911          <xref linkend="docbook.examples.guielements" />
912          shows how the menu choice in figure
913          <xref linkend="docbook.figures.menuchoice" />
914          can be described.
915        </para>
916        <figure id="docbook.figures.menuchoice">
917          <title>Menu choice</title>
918          <screenshot>
919            <mediaobject>
920              <imageobject>
921                <imagedata 
922                  fileref="figures/menuchoice.png" format="PNG" 
923                />
924              </imageobject>
925            </mediaobject>
926          </screenshot>
927        </figure>
928        <example id="docbook.examples.guielements">
929          <title>Describe a menu choice</title>
930<programlisting language="xml">
931&lt;menuchoice&gt;
932   &lt;guimenu&gt;Administrate&lt;/guimenu&gt;
933   &lt;guisubmenu&gt;Plugins&lt;/guisubmenu&gt;
934   &lt;guimenuitem&gt;Types&lt;/guimenuitem&gt;
935&lt;/menuchoice&gt;
936</programlisting>
937          <para>
938            In the text it will look like this:
939            <menuchoice>
940              <guimenu>Administrate</guimenu>
941              <guisubmenu>Plugins</guisubmenu>
942              <guimenuitem>Types</guimenuitem>
943            </menuchoice>
944          </para>
945        </example>
946      </sect4>
947    </sect3>
948    <sect3 id="docbook.usedtags.images">
949      <title>Images and figures</title>
950      <para>
951        Images and figures are normally implemented like the following example. The
952        image-file must be located in
953        <filename class="directory">doc/src/docbook/figures</filename>,
954        otherwise the image will not be visible in the generated output files.
955      </para>
956
957      <example id="docbook.examples.screenshot">
958        <title>Screen-shot in the documentation</title>
959        <para>
960          <xref linkend="webclient.figures.homepage" />
961          is implemented with the following code
962        </para>
963<programlisting language="xml">&lt;figure id="docbook.figures.menuchoice"&gt;
964  &lt;title&gt;The home page&lt;/title&gt;
965  &lt;screenshot&gt;
966    &lt;mediaobject&gt;
967      &lt;imageobject&gt;
968        &lt;imagedata
969          scalefit="1"
970          width="100%"
971          fileref="figures/homapage.png" format="PNG"
972        /&gt;
973      &lt;/imageobject&gt;
974    &lt;/mediaobject&gt;
975  &lt;/screenshot&gt;
976&lt;/figure&gt;</programlisting>
977      </example>
978      <warning>
979        <para>
980          When using images in docbook you will always have problems with image
981          resolution and scaling. Since we are generating output for both HTML
982          and PDF it is even worse. What we have found to work is this:
983         
984          <itemizedlist>
985          <listitem>
986            <para>
987            The screenshots must be saved without any resolution information
988            in them, or with the resolution set to 96 dpi. We have configured PDF to
989            use 96 dpi instead of 72 dpi to make the HTML and PDF output
990            look as similar as possible.
991            </para>
992          </listitem>
993         
994          <listitem>
995            <para>
996            Scaling in HTML has been disabled. The images will always be the
997            same size (number of pixels) as they actually are. Please, do not
998            make the screenshots too wide!
999           
1000            <tip>
1001              <para>
1002                Change your BASE preferences, see
1003                <xref linkend="webclient.configuration.preferences" />,
1004                to a smaller font size or use the zoom functionality in the web
1005                browser to make more information fit in the same image width.
1006              </para>
1007            </tip>
1008           
1009            </para>
1010          </listitem>
1011         
1012          <listitem>
1013            <para>
1014            For small images, less than the width of the PDF page,
1015            do not specify scaling factors or widths.
1016            </para>
1017          </listitem>
1018         
1019          <listitem>
1020            <para>
1021            Images that are wider than the PDF page will be clipped. To
1022            prevent this you must add the following attributes to the
1023            <sgmltag class="starttag">imagedata</sgmltag> tag:
1024            <code>scalefit="1" width="100%"</code>. This will scale down
1025            the image so that it fits the available width.
1026            </para>
1027          </listitem>
1028         
1029          <listitem>
1030            <para>
1031            If you still need to scale the image differently in the PDF use
1032            the <sgmltag>width</sgmltag> and <sgmltag>depth</sgmltag>
1033            attributes.
1034            </para>
1035          </listitem>
1036          </itemizedlist>
1037        </para>
1038      </warning>
1039    </sect3>
1040    <sect3 id="docbook.usedtags.examples">
1041      <title>Examples and program listing</title>
1042      <para>
1043        Following describes how to insert an example in the documentation.The examples in
1044        this document are often some kind of program listing but they can still be examples
1045        of something else.
1046      </para>
1047      <warning>
1048        <title>Use spaces instead of tabs for indentation</title>
1049        <para>
1050          Use spaces for indentation in program listing, this is because of the
1051          tab-indentations will sooner or later cause corrupt text.
1052        </para>
1053      </warning>
1054
1055      <itemizedlist>
1056        <listitem>
1057          <simpara>
1058            The verbatim text is split into several lines if the text contains
1059            more then 80 characters. This could give the text an unwanted look and
1060            it's therefore recommended to manually insert new lines to have control
1061            over layout of the text
1062          </simpara>
1063        </listitem>
1064        <listitem>
1065          <simpara>
1066            We have added support for syntax highlighting of program
1067            examples in the HTML version. To enable it add a
1068            <sgmltag class="attribute">language</sgmltag>
1069            attribute with one of the following values: <constant>java</constant>,
1070            <constant>xml</constant> or <constant>sql</constant>. The highlighting engine
1071            support more languages. To add support for those in docbook, change
1072            the <filename>customized.chunked.xsl</filename> file. The syntax highlighting
1073            engine doesn't handle markup inside the <sgmltag class="starttag">programlisting</sgmltag>
1074            tag very well. You should avoid that. By default, java program examples
1075            include line numbering, but not xml examples. To disable line numbering
1076            for java add <constant>:nogutter</constant> to the <sgmltag>language</sgmltag> 
1077            attribute: <constant>&lt;programlisting language="java:nogutter"&gt;</constant>.
1078            To enable line numbering for xml add <constant>:gutter</constant> to the <sgmltag>language</sgmltag> 
1079            attribute: <constant>&lt;programlisting language="xml:gutter"&gt;</constant>.
1080          </simpara>
1081        </listitem>
1082      </itemizedlist>
1083
1084      <example id="docbook.examples.example">
1085        <title>Example in the documentation</title>
1086        <para>
1087          This shows how 
1088          <xref linkend="net.sf.basedb.core.plugin.Plugin.getAbout" />
1089          is written in the corresponding XML-file.
1090        </para>
1091<programlisting language="xml">
1092&lt;example id="net.sf.basedb.core.plugin.Plugin.getAbout"&gt;
1093   &lt;title&gt;A typical implementation stores this information
1094      in a static field&lt;/title&gt;
1095   &lt;programlisting language="java"&gt;
1096private static final About about = new AboutImpl
1097(
1098   "Spot images creator",
1099   "Converts a full-size scanned image into smaller preview jpg " +
1100   "images for each individual spot.",
1101   "2.0",
1102   "2006, Department of Theoretical Physics, Lund University",
1103   null,
1104   "base@thep.lu.se",
1105   "http://base.thep.lu.se"
1106);
1107 
1108public About getAbout()
1109{
1110   return about;
1111}
1112&lt;/programlisting&gt;
1113&lt;/example&gt;
1114</programlisting>
1115      </example>     
1116    </sect3>
1117    <sect3 id="docbook.usedtags.admonitions">
1118      <title>Admonitions</title>
1119      <para>
1120        The admonitions that are used in this document can be found in the table below.
1121      </para>
1122      <informaltable frame="none">
1123        <tgroup cols="3" rowsep="1" colsep="1">
1124          <colspec align="left" />
1125          <colspec align="center" />
1126          <colspec align="left" />
1127          <thead>
1128            <row>
1129              <entry>Define</entry>
1130              <entry>Element to use</entry>
1131              <entry>Comment</entry>
1132            </row>
1133          </thead>
1134          <tbody>
1135            <row>
1136              <entry>Warning text</entry>
1137              <entry>
1138                <sgmltag class="starttag">warning</sgmltag>
1139              </entry>
1140              <entry></entry>
1141            </row>
1142            <row>
1143              <entry>Notification text</entry>
1144              <entry>
1145                <sgmltag class="starttag">note</sgmltag>
1146              </entry>
1147              <entry></entry>
1148            </row>
1149            <row>
1150              <entry>A tip</entry>
1151              <entry>
1152                <sgmltag class="starttag">tip</sgmltag>
1153              </entry>
1154              <entry></entry>
1155            </row>
1156            <row>
1157              <entry>Important text</entry>
1158              <entry>
1159                <sgmltag class="starttag">important</sgmltag>
1160              </entry>
1161              <entry></entry>
1162            </row>
1163            <row>
1164              <entry>Something to be cautious about</entry>
1165              <entry>
1166                <sgmltag class="starttag">caution</sgmltag>
1167              </entry>
1168              <entry></entry>
1169            </row>
1170          </tbody>
1171        </tgroup>
1172      </informaltable>
1173    </sect3>
1174    <sect3 id="docbook.usedtags.lists">
1175      <title>Lists</title>
1176      <para>
1177        Following items can be used to define different kind of lists in the documentation.
1178        Some common elements for the lists are also described here.
1179      </para>
1180      <informaltable frame="none">
1181        <tgroup cols="3" rowsep="1" colsep="1">
1182          <colspec align="left" />
1183          <colspec align="center" />
1184          <colspec align="left" />
1185          <thead>
1186            <row>
1187              <entry>Define</entry>
1188              <entry>Element</entry>
1189              <entry>Comment</entry>
1190            </row>
1191          </thead>
1192          <tbody>           
1193            <row>
1194              <entry>None-ordered list</entry>
1195              <entry>
1196                <sgmltag class="starttag">itemizedlist</sgmltag>
1197              </entry>
1198              <entry></entry>
1199            </row>
1200            <row>
1201              <entry>Term definition list</entry>
1202              <entry>
1203                <sgmltag class="starttag">variablelist</sgmltag>
1204              </entry>
1205              <entry></entry>
1206            </row>
1207            <row>
1208              <entry>Ordered list</entry>
1209              <entry>
1210                <sgmltag class="starttag">orderedlist</sgmltag>
1211              </entry>
1212              <entry></entry>
1213            </row>
1214            <row>
1215              <entry>List item</entry>
1216              <entry>
1217                <sgmltag class="starttag">listitem</sgmltag>
1218              </entry>
1219              <entry></entry>
1220            </row>
1221          </tbody>
1222        </tgroup>
1223      </informaltable>
1224      <para>The example below shows how to create a list for term definition in the text.</para>
1225      <example id="docbook.examples.variablelist">
1226        <title>Example how to write a variable list</title>
1227<programlisting language="xml">
1228&lt;variablelist&gt;
1229   &lt;varlistentry&gt;
1230      &lt;term&gt;Term1&lt;/term&gt;
1231      &lt;listitem&gt;
1232         &lt;para&gt;
1233            Definition/explanation of the term
1234         &lt;/para&gt;
1235      &lt;/listitem&gt;
1236   &lt;/varlistentry&gt;
1237   
1238   &lt;varlistentry&gt;
1239      &lt;term&gt;Term2&lt;/term&gt;
1240      &lt;listitem&gt;
1241         &lt;para&gt;
1242            Definition/explanation of the term
1243         &lt;/para&gt;
1244      &lt;/listitem&gt;
1245   &lt;/varlistentry&gt;
1246&lt;/variablelist&gt;</programlisting>
1247      </example>
1248    </sect3>
1249   
1250    <sect3 id="docbook.usedtags.links">
1251      <title>Link elements</title>
1252      <para></para>
1253      <informaltable frame="none">
1254        <tgroup cols="3" rowsep="1" colsep="1">
1255          <colspec align="left" />
1256          <colspec align="center" />
1257          <colspec align="left" />
1258          <thead>
1259            <row>
1260              <entry>Define</entry>
1261              <entry>Element</entry>
1262              <entry>Comment</entry>
1263            </row>
1264          </thead>
1265          <tbody>
1266            <row>
1267              <entry>Cross reference</entry>
1268              <entry>
1269                <sgmltag class="starttag">xref linkend=""</sgmltag>
1270              </entry>
1271              <entry>Use this to Link to other parts of the document.</entry>
1272            </row>
1273            <row>
1274              <entry>Cross reference with own text</entry>
1275              <entry>
1276                <sgmltag class="starttag">link</sgmltag>
1277              </entry>
1278              <entry>
1279                Can be used as an alternative to
1280                <sgmltag>xref</sgmltag>
1281              </entry>
1282            </row>
1283            <row>
1284              <entry>External URLs</entry>
1285              <entry>
1286                <sgmltag class="starttag">ulink url=""</sgmltag>
1287              </entry>
1288              <entry></entry>
1289            </row>
1290          </tbody>
1291        </tgroup>
1292      </informaltable>
1293      <example id="docbook.examples.links">
1294        <title>Links</title>
1295<programlisting language="xml">
1296&lt;xref linkend="docbook.usedtags.links" /&gt;
1297&lt;link linkend="docbook.usedtags.links"&gt;Link to this section&lt;/link&gt;
1298&lt;ulink url="http://base.thep.lu.se"&gt;Base2's homepage&lt;/ulink&gt;
1299</programlisting>
1300        <para>
1301          The first element will autogenerate the linked section's/chapter's title as a
1302          hyperlinked text. As an alternative to
1303          <sgmltag>xref</sgmltag>
1304          is
1305          <sgmltag>link</sgmltag>
1306          that lets you write your own hyperlinked text. The third and last one should be
1307          used to link to any URL outside the document.
1308        </para>
1309      </example>
1310    </sect3>
1311  </sect2>
1312 
1313  </sect1>
1314 
1315  <sect1 id="documentation.magicdraw">
1316    <?dbhtml filename="magicdraw.html" ?>
1317    <title>Create UML diagrams with MagicDraw</title>
1318
1319    <para>
1320      UML or UML-like diagrams are used to document the relationship of
1321      classes in the Core API. To create the diagrams we use the community edition (version 12.5)
1322      of a program called MagicDraw. This is a Java program and it should be possible
1323      to run it on any platform which has at least a Java 1.5 run-time.
1324      To get more information about MagicDraw and to download the program
1325      go to their website:
1326      <ulink url="http://www.magicdraw.com/">http://www.magicdraw.com/</ulink>
1327    </para>
1328   
1329
1330    <sect2 id="magicdraw.organisation">
1331      <title>Organisation</title>
1332     
1333      <para>
1334        All classes and diagrams are in a single UML file. It can be
1335        found at <filename>&lt;base-dir&gt;/doc/src/uml/base.mdzip</filename>
1336      </para>
1337     
1338      <para>
1339        Everything in MagicDraw has been organised into packages and
1340        modules. At the top we have the <code>Core layer</code> and
1341        the <code>Data layer</code>. The <code>Java</code> module is
1342        for classes that related to the Java programming language, such
1343        as <code>Map</code> and <code>Set</code> that are not pre-defined
1344        by MagicDraw.
1345      </para>
1346     
1347      <figure id="magicdraw.figures.organisation">
1348        <title>MagicDraw organisation</title>
1349        <screenshot>
1350          <mediaobject>
1351            <imageobject>
1352              <imagedata 
1353                fileref="figures/magicdraw/organisation.png" format="PNG" />
1354            </imageobject>
1355          </mediaobject>
1356        </screenshot>
1357      </figure>
1358    </sect2>
1359   
1360    <sect2 id="magicdraw.classes">
1361      <title>Classes</title>
1362        <para>
1363          New classes should be added to one of the sub-packages inside
1364          the <code>Data layer/Classes</code> or <code>Core layer/Classes</code>
1365          modules. It is very simple:
1366        </para>
1367         
1368        <orderedlist>
1369        <listitem>
1370          <para>
1371          Select the sub-package in the overview and click with the right mouse button.
1372          </para>
1373        </listitem>
1374        <listitem>
1375          <para>
1376          Select the
1377          <menuchoice>
1378            <guimenu>New element</guimenu>
1379            <guimenuitem>Class</guimenuitem>
1380          </menuchoice>
1381          menu item in the menu that pops up.
1382          </para>
1383        </listitem>
1384        <listitem>
1385          <para>
1386          The overview will expand to add a new class. Enter the name of the class
1387          and press enter.
1388          </para>
1389        </listitem>
1390        </orderedlist>
1391       
1392        <sect3 id="magicdraw.classes.data">
1393          <title>Data layer classes</title>
1394         
1395          <para>
1396            If you added a class to the data layer you also need to
1397            record some important information.
1398          </para>
1399
1400          <itemizedlist>
1401          <listitem>
1402            <para>
1403            The database table the data is stored in
1404            </para>
1405          </listitem>
1406          <listitem>
1407            <para>
1408            If the second-level cache is enabled or not
1409            </para>
1410          </listitem>
1411          <listitem>
1412            <para>
1413            If proxies are enabled or not
1414            </para>
1415          </listitem>
1416          <listitem>
1417            <para>
1418            The superclass
1419            </para>
1420          </listitem>
1421          <listitem>
1422            <para>
1423            Implemented interfaces
1424            </para>
1425          </listitem>
1426          <listitem>
1427            <para>
1428            Simple properties, ie. strings, numbers, dates
1429            </para>
1430          </listitem>
1431          <listitem>
1432            <para>
1433            Associations to other classes
1434            </para>
1435          </listitem>
1436          </itemizedlist>
1437
1438          <para>
1439            To achieve this we have slightly altered the meaning of some UML symbols.
1440            For example we use the access modified symbols (+, ~ and -) to indicate
1441            if a property is updatable or not.
1442          </para>
1443
1444          <sect4 id="magicdraw.classes.data.tags">
1445            <title>Setting tagged values</title>
1446           
1447            <para>
1448              Some of the information needed is specified as <emphasis>tagged values</emphasis>
1449              that can be attached to a class.
1450              Double-click on the new class to bring up it's properties dialog
1451              box. Switch to the <guilabel>Tags</guilabel> configuration page.
1452              We have defined the following tags:
1453            </para>
1454             
1455            <variablelist>
1456            <varlistentry>
1457              <term><guilabel>table</guilabel></term>
1458              <listitem>
1459                <para>
1460                The name of the database table where the items should be stored.
1461                </para>
1462              </listitem>
1463            </varlistentry>
1464            <varlistentry>
1465              <term><guilabel>cache</guilabel></term>
1466              <listitem>
1467                <para>
1468                The number of items to store in the second-level cache of Hibernate.
1469                Only specify a value if caching should be enabled.
1470                </para>
1471              </listitem>
1472            </varlistentry>
1473            <varlistentry>
1474              <term><guilabel>proxy</guilabel></term>
1475              <listitem>
1476                <para>
1477                A boolean flag to indicate if proxies should be used or not.
1478                </para>
1479              </listitem>
1480            </varlistentry>
1481            <varlistentry>
1482              <term><guilabel>extends</guilabel></term>
1483              <listitem>
1484                <para>
1485                Select the superclass of this class.
1486                </para>
1487              </listitem>
1488            </varlistentry>
1489            <varlistentry>
1490              <term><guilabel>implements</guilabel></term>
1491              <listitem>
1492                <para>
1493                Specify which interfaces the class implements. To save space
1494                we use the following one-letter abbreviations:
1495                </para>
1496               
1497                <itemizedlist>
1498                <listitem><para>A = AnnotatableData</para></listitem>
1499                <listitem><para>B = BatchableData</para></listitem>
1500                <listitem><para>D = DiskConsumableData</para></listitem>
1501                <listitem><para>E = ExtendableData</para></listitem>
1502                <listitem><para>F = FileAttachableData</para></listitem>
1503                <listitem><para>G = RegisteredData</para></listitem>
1504                <listitem><para>L = LoggableData</para></listitem>
1505                <listitem><para>N = NameableData</para></listitem>
1506                <listitem><para>O = OwnableData</para></listitem>
1507                <listitem><para>R = RemoveableData</para></listitem>
1508                <listitem><para>S = ShareableData</para></listitem>
1509                <listitem><para>T = SystemData</para></listitem>
1510                </itemizedlist>
1511              </listitem>
1512            </varlistentry>
1513            </variablelist>
1514           
1515            <figure id="magicdraw.figures.classtags">
1516              <title>Setting tagged values</title>
1517              <screenshot>
1518                <mediaobject>
1519                  <imageobject>
1520                    <imagedata 
1521                      scalefit="1" width="100%"
1522                      fileref="figures/magicdraw/classtags.png" format="PNG" />
1523                  </imageobject>
1524                </mediaobject>
1525              </screenshot>
1526            </figure>
1527          </sect4>
1528         
1529          <sect4 id="magicdraw.classes.data.properties">
1530            <title>Specifying simple properties for a class</title>
1531            <para>
1532              Simple properties are strings, numbers, dates, etc. that are part of an object.
1533              Properties are entered as attributes of the class. The easiest way to enter
1534              properties are by typing directly in a diagram. It can also be done
1535              from the <guilabel>Attributes</guilabel> configuration page.
1536            </para>
1537           
1538            <para>
1539              Each attribute must have information about:
1540            </para>
1541           
1542            <itemizedlist>
1543            <listitem>
1544              <para>
1545              The name of the attribute, ie. the name of the get/set method without the
1546              get or set part and starting with a lowercase letter.
1547              </para>
1548            </listitem>
1549            <listitem>
1550              <para>
1551              The data type: enter or select the Java object type in the
1552              <guilabel>Type</guilabel> selection list.
1553              </para>
1554            </listitem>
1555            <listitem>
1556              <para>
1557              If null values are allowed or not: specify a multiplicity of 1 if a
1558              non-null value is required.
1559              </para>
1560            </listitem>
1561            <listitem>
1562              <para>
1563              If it is modifiable or not. From the <guilabel>Visibility</guilabel> 
1564              list, select one of the following:
1565              </para>
1566             
1567              <itemizedlist>
1568              <listitem>
1569                <para>
1570                public (+): the attribute is modifiable. This translates to public get and set methods.
1571                </para>
1572              </listitem>
1573              <listitem>
1574                <para>
1575                package (~): the attribute can only be set once. This translates to public get and set methods
1576                and an <code>update="false"</code> tag in the Hibernate mapping.
1577                </para>
1578              </listitem>
1579              <listitem>
1580                <para>
1581                private (-): the attribute is private (will this ever be used?).
1582                This translates to package private get and set methods.
1583                </para>
1584              </listitem>
1585              </itemizedlist>
1586             
1587            </listitem>
1588            </itemizedlist>
1589     
1590            <figure id="magicdraw.figures.attributes">
1591              <title>Class attributes</title>
1592              <screenshot>
1593                <mediaobject>
1594                  <imageobject>
1595                    <imagedata 
1596                      scalefit="1" width="100%"
1597                      fileref="figures/magicdraw/attributes.png" format="PNG" />
1598                  </imageobject>
1599                </mediaobject>
1600              </screenshot>
1601            </figure>         
1602          </sect4>
1603         
1604          <sect4 id="magicdraw.classes.data.associations">
1605            <title>Associations to other classes</title>
1606
1607            <para>
1608              Associations to other classes are easiest created from
1609              a diagram view by drawing an <guilabel>Association</guilabel>
1610              link between the two classes. The ends should be given a name,
1611              multiplicity and visibility should be selected. For the visibility
1612              we use the same options as for attributes, but with a slightly different
1613              interpretation.
1614            </para>
1615           
1616            <itemizedlist>
1617            <listitem>
1618              <para>
1619              public (+): the association is modifiable. This translates to public get and
1620              set methods for many-to-one associations. Many-to-many associations must have a
1621              package private set method since the set or map must never be replaced.
1622              </para>
1623            </listitem>
1624 
1625            <listitem>
1626              <para>
1627              package (~): same as public but the association cannot be changed once it has
1628              been created. For many-to-one associations an <code>update="false"</code> tag in
1629              the Hibernate mapping should be used. For many-to-many association there is
1630              no corresponding tag. It will be the responsibility of the core to make sure
1631              no modifications are done.
1632              </para>
1633            </listitem>
1634           
1635            <listitem>
1636              <para>
1637              private (-): this is the inverse end of an association. Only used for one-to-many
1638              and many-to-many associations and translates to package private get and set
1639              methods.
1640              </para>
1641            </listitem>
1642            </itemizedlist>
1643           
1644            <para>
1645              If the association involves a join table (many-to-many) the name of that
1646              table should be entered as a tagged value to the association.
1647            </para>
1648           
1649            <para>
1650              If the association have values attached to it, use the
1651              <guilabel>Association class</guilabel> link type and enter information about
1652              the values in the attached class.
1653            </para>         
1654
1655          </sect4>
1656
1657          <para>
1658            A lot more can be said about this, but
1659            it is probably better to have a look at already existing diagrams if you have
1660            any questions. The authentication overview shown below is one of the most
1661            complex diagrams that involves many different links.
1662          </para>
1663         
1664          <figure id="magicdraw.figures.realexample">
1665            <title>Authentication UML diagram</title>
1666            <screenshot>
1667              <mediaobject>
1668                <imageobject>
1669                  <imagedata 
1670                    scalefit="1" width="100%"
1671                    fileref="figures/uml/datalayer.authentication.png" format="PNG" />
1672                </imageobject>
1673              </mediaobject>
1674            </screenshot>
1675          </figure>
1676         
1677        </sect3>
1678       
1679        <sect3 id="magicdraw.classes.core">
1680          <title>Core layer classes</title>
1681          <para>
1682          TODO
1683          </para>
1684        </sect3>
1685       
1686      </sect2>
1687     
1688      <sect2 id="magicdraw.diagrams">
1689        <title>Diagrams</title>
1690
1691        <sect3 id="magicdraw.diagrams.create">
1692          <title>Create a new diagram</title>
1693         
1694          <para>
1695            New diagrams should be added to one of the sub-packages inside
1696            the <code>Data layer/Diagrams</code> or <code>Core layer/Diagrams</code>
1697            modules. It is very simple:
1698          </para>
1699 
1700          <orderedlist>
1701          <listitem>
1702            <para>
1703            Select the sub-package in the overview and click with the right mouse button.
1704            </para>
1705          </listitem>
1706          <listitem>
1707            <para>
1708            Select the
1709            <menuchoice>
1710              <guimenu>New diagram</guimenu>
1711              <guimenuitem>Class diagram</guimenuitem>
1712            </menuchoice>
1713            menu item in the menu that pops up.
1714            </para>
1715          </listitem>
1716          <listitem>
1717            <para>
1718            The overview will expand to add a new diagram. A new empty diagram
1719            frame is also opened on the right part of the screen. Enter the name of the diagram
1720            and press enter.
1721            </para>
1722          </listitem>
1723          </orderedlist>
1724 
1725          <note>
1726            <title>Only class diagrams are fully supported</title>
1727            <para>
1728              The community edition of MagicDraw only has full support for
1729              class diagrams. The other diagram types has limitations, in the number of
1730              objects that can be created.
1731            </para>
1732          </note>
1733         
1734          <para>
1735            To display a class in a diagram, simply select the class in the overview
1736            and drag it into to the diagram.
1737          </para>
1738        </sect3>
1739
1740        <sect3 id="magicdraw.diagrams.appearance">
1741          <title>Visual appearance and style</title>
1742           
1743          <para>
1744            We have defined several different display style for classes. To set a
1745            style for a class right click on it in a diagram and select the
1746            <menuchoice><guimenuitem>Symbol properties</guimenuitem></menuchoice>
1747            menu item. In the bottom of the
1748            pop-up, use the <guilabel>Apply style</guilabel> selection list to select
1749            one of the predefined styles.
1750          </para>
1751           
1752          <itemizedlist>
1753          <listitem>
1754            <para>
1755            Data class: Use this style for all primary data classes in a diagram. It will
1756            display all info that we are interested in.
1757            </para>
1758          </listitem>
1759          <listitem>
1760            <para>
1761            External class: Use this style for related classes that are actually part of
1762            another diagram. This style will hide all information except the class name.
1763            This style can be used for both data layer and core layer classes.
1764            </para>
1765          </listitem>
1766          <listitem>
1767            <para>
1768            Association class: Use this style for classes that hold information
1769            related to an association between two other classes. Classes with this
1770            style are displayed in a different color. This style can be used for both
1771            data layer and core layer classes.
1772            </para>
1773          </listitem>
1774          </itemizedlist>     
1775        </sect3>
1776
1777        <sect3 id="magicdraw.diagrams.save">
1778          <title>Save diagram as image</title>
1779          <para>
1780            When the diagram is complete, save it as a PNG image in the
1781            <filename class="directory">&lt;base-dir&gt;/doc/src/docbook/figures/uml</filename>
1782            directory.
1783          </para>
1784        </sect3>
1785      </sect2>     
1786     
1787  </sect1>
1788 
1789  <sect1 id="documentation.javadoc">
1790    <?dbhtml filename="javadoc.html" ?>
1791    <title>Javadoc</title>
1792
1793    <para>
1794      Existing Javadoc documentation is available on-line at:
1795      <ulink url="http://base.thep.lu.se/chrome/site/doc/api/index.html"
1796        >http://base.thep.lu.se/chrome/site/doc/api/index.html</ulink>.
1797    </para>
1798   
1799    <para>
1800      The BASE API is divided into four different parts on the package level.
1801    </para>
1802   
1803    <itemizedlist>
1804    <listitem>
1805      <para>
1806      Public API - All classes and methods in the package are public. May be
1807      used by client applications and plug-ins. In general, backwards compatibility
1808      will be maintained.
1809      </para>
1810    </listitem>
1811   
1812    <listitem>
1813      <para>
1814      Extension API - All classes and methods in the package intended for
1815      internal extensions only. Not part of the public API and should not be used
1816      by client applications or plug-in.
1817      </para>
1818    </listitem>
1819
1820    <listitem>
1821      <para>
1822      Internal API - All classes and methods in the package are internal. Should
1823      never be used by client application or plug-ins.
1824      </para>
1825    </listitem>
1826
1827    <listitem>
1828      <para>
1829      Mixed Public and Internal API - Contains a mix of public and internal
1830      classes. Check the Javadoc for each class/method before using it.
1831      </para>
1832    </listitem>
1833
1834    </itemizedlist>
1835    <para>
1836      Introduction to the Base API and it's parts can be
1837      found on the start page of Base Javadoc. Plugin developers and other external developers
1838      should pay most attention to the public API. What we consider to be the public part of the API is discussed in
1839      <xref linkend="base_api.public" />.
1840    </para>
1841
1842    <sect2 id="javadoc.writing">
1843      <title>Writing Javadoc</title>
1844      <para>
1845        This section only covers Javadoc comments, how to write proper none-Javadoc comments
1846        are described in
1847        <xref linkend="core_ref.rules.style" />
1848      </para>
1849      <para>
1850        General information about Javadoc and how it is written in a proper way can be found
1851        at
1852        <ulink url="http://java.sun.com/j2se/javadoc/writingdoccomments/index.html">
1853          http://java.sun.com/j2se/javadoc/writingdoccomments/index.html</ulink>.
1854        The rule when coding in Base is that all packages, classes, interfaces, public
1855        methods and public attributes must be commented in Javadoc style. It is also
1856        recommended that private and protected methods has some comments, but maybe not as
1857        detailed as the public ones. Below follow more specific details what to have in mind
1858        when writing Javadoc in the Base project.
1859      </para>
1860      <variablelist>
1861        <varlistentry>
1862          <term>General</term>
1863          <listitem>
1864            <para>
1865              General things that are common for all Javadoc comments in Base.
1866            </para>
1867            <itemizedlist>
1868              <listitem>
1869                <para>All comments should be in English.</para>
1870              </listitem>
1871              <listitem>
1872                <para>Do not start each new line of comment with a star.</para>
1873              </listitem>
1874              <listitem>
1875                <para>
1876                  If a comment only should be shown in the internal documentation
1877                  and not in the public, it should be tagged with
1878                  <synopsis>@base.internal</synopsis>
1879                </para>
1880              </listitem>
1881            </itemizedlist>
1882          </listitem>
1883        </varlistentry>
1884       
1885        <varlistentry>
1886          <term>Package comments</term>
1887          <listitem>
1888            <para>
1889              Package comments should be placed in a file named <filename>package.html</filename>
1890              in the source code directory.
1891            </para>
1892           
1893            <important>
1894              <title>Is the package public or internal?</title>
1895              <para>
1896                This information should be added in the <filename>package.html</filename>
1897                file. You must also modify the <filename>build.xml</filename> file.
1898                The <emphasis>doc.javadoc</emphasis> target contains
1899                <sgmltag class="starttag">group</sgmltag> tags which lists all
1900                packages that are part of each group.
1901              </para>
1902            </important>
1903           
1904          </listitem>
1905        </varlistentry>
1906       
1907        <varlistentry>
1908          <term>Class and interface comments</term>
1909          <listitem>
1910            <para>
1911              A comment for a class or interface should start with a general
1912              description. The class comment should then give information about what
1913              the class can be used for, while an interface comment more should inform
1914              which kinds of classes that are supposed to implement the interface.
1915            </para>
1916            <variablelist>
1917              <varlistentry>
1918                <term><synopsis>@author</synopsis></term>
1919                <listitem>
1920                  <para>The first name of the author(s) of the class.</para>
1921                </listitem>
1922              </varlistentry>
1923              <varlistentry>
1924                <term><synopsis>@version</synopsis></term>
1925                <listitem>
1926                  <para>From which version of Base the class is available.</para>
1927                </listitem>
1928              </varlistentry>
1929              <varlistentry>
1930                <term><synopsis>@see</synopsis></term>
1931                <listitem>
1932                  <para>Optional. Links to some related subjects.</para>
1933                </listitem>
1934              </varlistentry>
1935              <varlistentry>
1936                <term><synopsis>@base.modified</synopsis></term>
1937                <listitem>
1938                  <para>
1939                    Optional. Some classes has this tag too. This is for give the
1940                    class-file a time stamp when it is checked in to subversion.
1941                  </para>
1942                </listitem>
1943              </varlistentry>
1944            </variablelist>
1945          </listitem>
1946        </varlistentry>
1947       
1948        <varlistentry>
1949          <term>Method comments</term>
1950          <listitem>
1951            <para>
1952              A method comment should start with a general description of the method
1953              and what it does. The following tags must be present in this order:
1954            </para>
1955            <variablelist>
1956              <varlistentry>
1957                <term>
1958                  <synopsis>@param</synopsis></term>
1959                <listitem>
1960                  <para>
1961                    One tag for each parameter of the method. Make sure to tell
1962                    what values are allowed and what will happen if a disallowed
1963                    value is passed.
1964                  </para>
1965                </listitem>
1966              </varlistentry>
1967              <varlistentry>
1968                <term><synopsis>@return</synopsis></term>
1969                <listitem>
1970                  <para>
1971                    What is returned by the method. Make sure to tell what
1972                    values can be returned (ie. if it can be null).
1973                  </para>
1974                </listitem>
1975              </varlistentry>
1976              <varlistentry>
1977                <term><synopsis>@throws</synopsis></term>
1978                <listitem>
1979                  <para>
1980                    One tag for each exception that the method can throw and
1981                    describe when and why it will be thrown.
1982                  </para>
1983                </listitem>
1984              </varlistentry>
1985              <varlistentry>
1986                <term>
1987                  <synopsis>@since</synopsis>
1988                </term>
1989                <listitem>
1990                  <para>
1991                    Use only this tag together with methods added in a later
1992                    version then the one the class was created in. It holds which
1993                    version the method first was available in.
1994                  </para>
1995                </listitem>
1996              </varlistentry>                           
1997              <varlistentry>
1998                <term>
1999                  <synopsis>@see</synopsis></term>
2000                <listitem>
2001                  <para>
2002                    Optional. Link to relevant information, one tag for each
2003                    link.
2004                  </para>
2005                </listitem>
2006              </varlistentry>
2007            </variablelist>
2008          </listitem>
2009        </varlistentry>
2010       
2011        <varlistentry>
2012          <term>Attribute comments</term>
2013          <listitem>
2014            <para>
2015              If the attribute is a static final, describe what the attribute is for
2016              an where it is typically used. Other attributes can often be explained
2017              through their getter and setter methods.
2018            </para>
2019          </listitem>
2020        </varlistentry>
2021      </variablelist>
2022    </sect2>
2023  </sect1>
2024</chapter>
Note: See TracBrowser for help on using the repository browser.