source: trunk/doc/src/docbook/developerdoc/documentation.xml @ 5071

Last change on this file since 5071 was 5071, checked in by Nicklas Nordborg, 14 years ago

References #108: Logging the change history of an item

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