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 |
$Id$ |
3227 |
04 Apr 07 |
martin |
7 |
|
4889 |
06 Apr 09 |
nicklas |
Copyright (C) 2007 Jari Häkkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson |
3227 |
04 Apr 07 |
martin |
9 |
|
3225 |
02 Apr 07 |
martin |
This file is part of BASE - BioArray Software Environment. |
3225 |
02 Apr 07 |
martin |
Available at http://base.thep.lu.se/ |
3227 |
04 Apr 07 |
martin |
12 |
|
3225 |
02 Apr 07 |
martin |
BASE is free software; you can redistribute it and/or |
3225 |
02 Apr 07 |
martin |
modify it under the terms of the GNU General Public License |
4477 |
05 Sep 08 |
jari |
as published by the Free Software Foundation; either version 3 |
3225 |
02 Apr 07 |
martin |
of the License, or (at your option) any later version. |
3227 |
04 Apr 07 |
martin |
17 |
|
3225 |
02 Apr 07 |
martin |
BASE is distributed in the hope that it will be useful, |
3225 |
02 Apr 07 |
martin |
but WITHOUT ANY WARRANTY; without even the implied warranty of |
3225 |
02 Apr 07 |
martin |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
3225 |
02 Apr 07 |
martin |
GNU General Public License for more details. |
3227 |
04 Apr 07 |
martin |
22 |
|
3225 |
02 Apr 07 |
martin |
You should have received a copy of the GNU General Public License |
4509 |
11 Sep 08 |
jari |
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> |