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

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

References #1590: Documentation cleanup

Moved "Internals of the Core API" to "The BASE API" section.

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