svndigest - svndigest

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'><base-dir>/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 & 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 & 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><![CDATA[ ... ]]></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><programlisting language="java:nogutter"></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><programlisting language="xml:gutter"></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><base-dir>/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"><base-dir>/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>