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

Last change on this file since 3838 was 3838, checked in by Nicklas Nordborg, 15 years ago

Fixes #805: Add syntax coloring to code examples in docbook

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