doc/src/docbook/developer/documentation.xml

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