Context Navigation

source: trunk/doc/src/docbook/developerdoc/write_docbook_doc.xml @ 3274

Visit:

Last change on this file since 3274 was 3274, checked in by Martin Svensson, 16 years ago
References #555. Document ready to be inspected
File size: 30.8 KB

Line
1	<?xml version="1.0" encoding="UTF-8"?>
2	<!DOCTYPE chapter PUBLIC
3	"-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4	"../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5	<!--
6	$Id$
7
8	Copyright (C) Authors contributing to this file.
9
10	This file is part of BASE - BioArray Software Environment.
11	Available at http://base.thep.lu.se/
12
13	BASE is free software; you can redistribute it and/or
14	modify it under the terms of the GNU General Public License
15	as published by the Free Software Foundation; either version 2
16	of the License, or (at your option) any later version.
17
18	BASE is distributed in the hope that it will be useful,
19	but WITHOUT ANY WARRANTY; without even the implied warranty of
20	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21	GNU General Public License for more details.
22
23	You should have received a copy of the GNU General Public License
24	along with this program; if not, write to the Free Software
25	Foundation, Inc., 59 Temple Place - Suite 330,
26	Boston, MA 02111-1307, USA.
27	-->
28
29	<chapter id="write_docbook_doc">
30	<?dbhtml dir="write_doc"?>
31	<title>Write documentation</title>
32	<para>
33	This chapter is for those who intent to contribute to the BASE2 documentation. The chapter
34	contains explanations of how the documentation is organized, what the different parts is
35	about and other things that will make it easier to know where to insert new text.
36	</para>
37	<para>
38	The documentation is written with the docbook standard, which is a bunch of defined XML
39	elements and XSLT style sheets that are used to format the text. Later on in this chapter
40	is a reference, over those docbook elements that are recommended to use when writing BASE2
41	documentation. Further information about docbook can be found in the on-line version of
42	O'Reilly's
43	<ulink url="http://www.docbook.org/tdg/en/html/">DocBook: The Definitive Guide</ulink>
44	by Norman Walsh and Leonard Muellner.
45	</para>
46
47	<sect1 id="write_docbook_doc.layout">
48	<title>Documentation layout</title>
49	<para>
50	The book, which is the main element in this docbook documentation, is divided into four
51	separated parts, depending on who the information is directed to. What kind of
52	documentation each one of these parts contains or should contain is described here
53	below.
54	</para>
55	<variablelist>
56	<varlistentry>
57	<term>Overview documentation</term>
58	<listitem>
59	<para>
60	The overview part contains, like the name says, an overview of BASE2.
61	For example an explanation about what the purpose with BASE2 is, the terms
62	that are used in the program and other general things that anyone that is
63	interested in the program wants/needs to know before exploring it further.
64	</para>
65	</listitem>
66	</varlistentry>
67	<varlistentry>
68	<term>User documentation</term>
69	<listitem>
70	<para>
71	This part contains information that are relevant for the common BASE2-user.
72	More or less should everything that a power user role or an user role needs
73	to know be included here.
74	</para>
75	</listitem>
76	</varlistentry>
77	<varlistentry>
78	<term>Administrator documentation</term>
79	<listitem>
80	<para>
81	Things that only an administrator-role can do is documented in this part. It
82	can be how to install the program, how to configure the server for best
83	performance or other subjects that are related to the administration.
84	</para>
85	</listitem>
86	</varlistentry>
87	<varlistentry>
88	<term>Developer documentation</term>
89	<listitem>
90	<para>
91	Documentation concerning the participation of BASE2 development should be placed
92	in this part, e.g. coding standards, the java doc from the source code, how
93	to develop a plugin etc.
94	</para>
95	</listitem>
96	</varlistentry>
97	</variablelist>
98	</sect1>
99
100
101	<sect1 id="write_docbook_doc.begin">
102	<title>Getting started</title>
103	<para>
104	Before start writing any documentation in BASE2 there are a couple of things, some
105	rules and standards, to have in mind.
106	</para>
107	<sect2 id="write_docbook_doc.begin.sourcefiles">
108	<title>Organization of source files</title>
109	<para>
110	The source files of the documentation are located in
111	<filename class='directory'>base2root/doc/src/docbook</filename>
112	which is showed in
113	<xref linkend="write_docbook_doc.figures.fileorganization" />
114	. The different parts of the documentation are organized into separate folders and
115	each one of the folders contains one index file and one file for each chapter in
116	that part. The index file joins the chapters, in current part/folder, together and
117	doesn't really contain any text. The documentation root directory also contains an
118	<filename class='headerfile'>index.xml</filename>
119	file which joins the index files from the different parts together.
120	</para>
121	<figure id="write_docbook_doc.figures.fileorganization">
122	<title>The organization of documentation files</title>
123	<screenshot>
124	<mediaobject>
125	<imageobject>
126	<imagedata fileref="figures/fileorganization.png" format="PNG"></imagedata>
127	</imageobject>
128	</mediaobject>
129	</screenshot>
130	</figure>
131	<sect3 id="write_docbook_doc.begin.sourcefiles.newfile">
132	<title>Create new chapter/file</title>
133	<para>
134	Each file in the documentation, except the index files, represents a chapter.
135	How to create a new chapter and include it in the text is described in
136	following items.
137	<orderedlist numeration='arabic' spacing='compact'>
138	<listitem>
139	<para>
140	Create a new XML-file in the folder of which part the new chapter
141	should be included. Give it a name that is quite similar to the
142	new chapter's title but use <userinput>_</userinput> instead of
143	blank space and keep it down to one or few words.
144	</para>
145	</listitem>
146	<listitem>
147	<para>
148	Begin to write the chapter's body, it should look like
149	<xref linkend="write_docbook_doc.examples.chapterbody"/>
150	<example id="write_docbook_doc.examples.chapterbody">
151	<title>Example of a chapter</title>
152	<programlisting>
153	<?xml version="1.0" encoding="UTF-8"?>
154	<!DOCTYPE chapter PUBLIC
155	"-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
156	"../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
157
158	<chapter id="<replaceable>example_chapter</replaceable>">
159	<?dbhtml dir="<replaceable>folder name to put the chapter's files in</replaceable>"?>
160	<title>Example of a chapter </title>
161	<para>
162	…
163	</para>
164	<sect1 id="<replaceable>example_chapter.sect1</replaceable>">
165	<title>Example of top level section </title>
166	<para>
167	…
168	</para>
169	<sect2 id="<replaceable>example_chapter.sect1.sect2</replaceable>">
170	<title>Example of second level section </title>
171	<para>
172	…
173	</para>
174	<sect3 id="<replaceable>example_chapter.sect1.sect2.sect3</replaceable>">
175	<title>Example of third level section</title>
176	<para>
177	…
178	</para>
179	</sect3>
180	</sect2>
181	</sect1>
182	</chapter>
183	</programlisting>
184	</example>
185	</para>
186	<note>
187	<para>
188	Don't forget to include the
189	<sgmltag>dbhtml</sgmltag>
190	tag with the attribute
191	<sgmltag class="attribute">dir</sgmltag>
192	set to the value that the chapter's output folder should have as a
193	name.
194	</para>
195	</note>
196	</listitem>
197	<listitem>
198	<para>
199	Next and last step is to get the new chapter included in the documentation. This is done by including the file's name in
200	the file
201	<filename>index.xml</filename>
202	that's located in the current part's folder.
203	<xref linkend="write_docbook_doc.examples.include_chapter" />
204	shows how the chapter that was created above is included in the user
205	documentation part.
206	</para>
207	<example id="write_docbook_doc.examples.include_chapter">
208	<title>Include a chapter</title>
209	<programlisting>
210	<part id="userdoc">
211	<title>User documentation</title>
212	<include file= "about.xml"/>
213	<include file="webclient.xml"/>
214	<include file="project_permission.xml"/>
215	<include file="trashcan.xml"/>
216	<include file="file_system.xml"/>
217	<include file="jobs.xml"/>
218	<include file="reporters.xml"/>
219	<include file="annotations.xml"/>
220	<include file="protocols.xml"/>
221	<include file="hardware.xml"/>
222	<userinput><include file="example_chapter.xml"/></userinput>
223	<include file="software.xml"/>
224	<include file="array_lims.xml"/>
225	<include file="biomaterials.xml"/>
226	<include file="experiments_analysis.xml"/>
227	<include file="import_export_data.xml"/>
228	</part>
229	</programlisting>
230	</example>
231	<note>
232	<title>Order of chapters</title>
233	<para>
234	The chapters will come in the same order as they are included in
235	the index file.
236	</para>
237	</note>
238	</listitem>
239	</orderedlist>
240	Now it's only to go ahead with the documentation writing.
241	</para>
242	</sect3>
243	</sect2>
244	<sect2 id="write_docbook_doc.begin.id">
245	<title>
246	The
247	<sgmltag class="attribute">id</sgmltag>
248	attribute
249	</title>
250	<para>
251	Common to all elements is that they have an id attribute that can have an unique value to identify the
252	element with. Most of the elements that are used inside the BASE2 documentation don't
253	need to have an id if they don't are used in any cross references from other part of
254	the text.
255	</para>
256	<para>
257	There are however some elements that always should have the
258	<sgmltag class="attribute">id</sgmltag>
259	set. Which these elements are and how the
260	<sgmltag class="attribute">id</sgmltag>
261	should look like for each one of those is described below. All ids should be as
262	short as possible and associated to the current element. The
263	<sgmltag class="attribute">id</sgmltag>
264	value should only consist of the lowercase characters a-z, '_' instead of blank
265	spaces and '.' to symbolize the different levels in the document.
266	<variablelist>
267	<varlistentry>
268	<term>chapter</term>
269	<listitem>
270	<para>
271	The chapter should have an
272	<sgmltag class="attribute">id</sgmltag>
273	that is identical or almost identical to the chapter's title.
274	<synopsis>chapter_title</synopsis>
275	</para>
276	</listitem>
277	</varlistentry>
278	<varlistentry>
279	<term>sect1-sect5</term>
280	<listitem>
281	<para>
282	The creation of a section's id is done by using the upper level's id
283	and add the section's title or a part of the title. For
284	<sect2> it should be like this;
285	<synopsis>chapter_title.sect1_title.sect2_title</synopsis>
286	</para>
287	</listitem>
288	</varlistentry>
289	<varlistentry>
290	<term>examples</term>
291	<listitem>
292	<para>
293	The naming of an example's
294	<sgmltag class="attribute">id</sgmltag>
295	is a bit different compare to the chapter's and section's id. It
296	should begin with the chapter's id followed by
297	<userinput>examples</userinput>
298	and the caption of the example.
299	<synopsis>chapter_title.examples.example_caption</synopsis>
300	</para>
301	</listitem>
302	</varlistentry>
303	<varlistentry>
304	<term>figures</term>
305	<listitem>
306	<para>
307	The figure's
308	<sgmltag class="attribute">id</sgmltag>
309	should have the following layout
310	<synopsis>chapter_title.figures.figure_name</synopsis>
311	</para>
312	</listitem>
313	</varlistentry>
314	</variablelist>
315	</para>
316	</sect2>
317	<sect2 id="write_docbook_doc.begin.helptext">
318	<title>Mark help texts</title>
319	<para>
320	The parts of the text that also should be used as help texts in the web must be
321	inside
322	<sgmltag>helptext</sgmltag>
323	tags.These texts will be exported to a XML-file at the same time as the
324	HTML-documentation is generated.The generated XML-file is compatible with the help
325	text importer in BASE2 and will be imported when running the update script or
326	installation script.
327	</para>
328	<note>
329	<para>
330	The
331	<sgmltag class="starttag">helptext</sgmltag>
332	must be outside the
333	<sgmltag>para</sgmltag>
334	tag but inside a
335	<sgmltag>sect1</sgmltag>
336	tag to work properly.
337	</para>
338	</note>
339	<para>
340	Each tag requires two different attributes
341	<variablelist>
342	<varlistentry>
343	<term>
344	<sgmltag class="attribute">external_id</sgmltag>
345	</term>
346	<listitem>
347	<para>
348	is used to identify and to find a help text in the web client.
349	BASE2's web client already has a several of IDs to help texts that
350	are defined, it could therefore be a good idea to have a look in the
351	program to see if there already is an external id to use for the
352	particular help text.
353	</para>
354	</listitem>
355	</varlistentry>
356	<varlistentry>
357	<term>
358	<sgmltag class="attribute">title</sgmltag>
359	</term>
360	<listitem>
361	<para>
362	is directly connected to the name/title property for a help text
363	item in BASE2.
364	</para>
365	</listitem>
366	</varlistentry>
367	</variablelist>
368	</para>
369	<example id="write_docbook_doc.examples.helptexttag">
370	<title>How to use the help text tag</title>
371	<programlisting>
372	<sect1>
373	<helptext external_id="<replaceable>helptexts.external.id</replaceable>" title="<replaceable>The title</replaceable>">
374	<replaceable>The text that also should be used as a helptext in the program.</replaceable>
375	</helptext>
376	</sect1>
377	</programlisting>
378	</example>
379	<para>
380	Import the generated XML-file manually by uploading it from the
381	<filename class="directory">data</filename>
382	directory to the BASE-server's file system and then use the help text importer
383	plugin to import the help text items from that file.
384	</para>
385	</sect2>
386	<sect2 id="write_docbook_doc.begin.generate">
387	<title>Generate the document</title>
388	<para>
389	There are two different types of format that is generated from the documentation
390	source. The format to view the documentation on-line will be the one with chunked
391	HTML pages where each chapter and section of first level are on separate
392	pages/files. The other format is a PDF-file that are most useful for printing and
393	distribution. Those two types of output are generated with the ant-target:
394	<userinput>ant docbook</userinput>
395	.
396	</para>
397	</sect2>
398	</sect1>
399
400	<sect1 id="write_docbook_doc.usedtags">
401	<title>Elements to use</title>
402	<para>
403	The purpose with this section is to give an overview of those docbook elements that are
404	most common in this documentation and to give some example on how they should be used.
405	There will not be any detailed explanation of the tags here, instead the reader is
406	recommended to get more information from
407	<ulink url="http://www.docbook.org/tdg/en/html/docbook.html">
408	Docbook's documentation
409	</ulink>
410	or other references.
411	</para>
412	<sect2 id="write_docbook_doc.usedtags.text">
413	<title>Text elements</title>
414	<para>
415
416	</para>
417	<informaltable frame="none">
418	<tgroup cols="3" rowsep="1" colsep="1">
419	<colspec align="left" />
420	<colspec align="center" />
421	<colspec align="left" />
422	<thead>
423	<row>
424	<entry>Define</entry>
425	<entry>Element to use</entry>
426	<entry>Comments</entry>
427	</row>
428	</thead>
429	<tbody>
430	<row>
431	<entry>Chapter</entry>
432	<entry>
433	<sgmltag class="starttag">chapter</sgmltag>
434	</entry>
435	<entry>
436	<para>
437	See
438	<xref linkend="write_docbook_doc.examples.chapterbody" />
439	</para>
440	</entry>
441	</row>
442	<row>
443	<entry>Title</entry>
444	<entry>
445	<sgmltag class="starttag">title</sgmltag>
446	</entry>
447	<entry>
448	<xref linkend="write_docbook_doc.examples.chapterbody" />
449	shows how this can be implemented
450	</entry>
451	</row>
452	<row>
453	<entry>Paragraph</entry>
454	<entry>
455	<sgmltag class="starttag">para</sgmltag>
456	</entry>
457	<entry></entry>
458	</row>
459	<row>
460	<entry>Top-level subsection</entry>
461	<entry>
462	<sgmltag class="starttag">sect1</sgmltag>
463	</entry>
464	<entry>
465	See
466	<xref linkend="write_docbook_doc.begin.id" />
467	</entry>
468	</row>
469	<row>
470	<entry>Second level section</entry>
471	<entry>
472	<sgmltag class="starttag">sect2</sgmltag>
473	</entry>
474	<entry>
475	See
476	<xref linkend="write_docbook_doc.begin.id" />
477	</entry>
478	</row>
479	<row>
480	<entry>Third level section</entry>
481	<entry>
482	<sgmltag class="starttag">sect3</sgmltag>
483	</entry>
484	<entry>
485	See
486	<xref linkend="write_docbook_doc.begin.id" />
487	</entry>
488	</row>
489	<row>
490	<entry>Fourth level section</entry>
491	<entry>
492	<sgmltag class="starttag">sect3</sgmltag>
493	</entry>
494	<entry></entry>
495	</row>
496	<row>
497	<entry>Fith level section</entry>
498	<entry>
499	<sgmltag class="starttag">sect3</sgmltag>
500	</entry>
501	<entry></entry>
502	</row>
503	</tbody>
504	</tgroup>
505	</informaltable>
506
507	<sect3 id="write_docbook_doc.usedtags.text.keywords">
508	<title>Markup special words and phrases</title>
509	<para>
510	These elements should be used to mark up words and phrases that have a special
511	meaning, like method names, class names and user inputs just to mention some.
512	</para>
513	<informaltable frame="none">
514	<tgroup cols="3" rowsep="1" colsep="1">
515	<colspec align="left" />
516	<colspec align="center" />
517	<colspec align="left" />
518	<thead>
519	<row>
520	<entry>Define</entry>
521	<entry>Element to use</entry>
522	<entry>Comment</entry>
523	</row>
524	</thead>
525	<tbody>
526	<row>
527	<entry>Class name</entry>
528	<entry>
529	<sgmltag class="starttag">classname</sgmltag>
530	</entry>
531	<entry></entry>
532	</row>
533	<row>
534	<entry>User input</entry>
535	<entry>
536	<sgmltag class="starttag">userinput</sgmltag>
537	</entry>
538	<entry></entry>
539	</row>
540	<row>
541	<entry>Variable name</entry>
542	<entry>
543	<sgmltag class="starttag">varname</sgmltag>
544	</entry>
545	<entry></entry>
546	</row>
547	<row>
548	<entry>Constant</entry>
549	<entry>
550	<sgmltag class="starttag">constant</sgmltag>
551	</entry>
552	<entry></entry>
553	</row>
554	<row>
555	<entry>Method definition</entry>
556	<entry>
557	<sgmltag class="starttag">methodsynopsis</sgmltag>
558	</entry>
559	<entry>
560	See
561	<xref linkend="write_docbook_doc.examples.methodimpl" />
562	</entry>
563	</row>
564	<row>
565	<entry>Modifier of a method</entry>
566	<entry>
567	<sgmltag class="starttag">modifier</sgmltag>
568	</entry>
569	<entry>
570	See
571	<xref linkend="write_docbook_doc.examples.methodimpl" />
572	</entry>
573	</row>
574	<row>
575	<entry>Classification of return value</entry>
576	<entry>
577	<sgmltag class="starttag">type</sgmltag>
578	</entry>
579	<entry>
580	See
581	<xref linkend="write_docbook_doc.examples.methodimpl" />
582	</entry>
583	</row>
584	<row>
585	<entry>Method name</entry>
586	<entry>
587	<sgmltag class="starttag">methodname</sgmltag>
588	</entry>
589	<entry>
590	See
591	<xref linkend="write_docbook_doc.examples.methodimpl" />
592	</entry>
593	</row>
594	<row>
595	<entry>No parameter/type</entry>
596	<entry>
597	<sgmltag class="starttag">void</sgmltag>
598	</entry>
599	<entry>
600	See
601	<xref linkend="write_docbook_doc.examples.methodimpl" />
602	</entry>
603	</row>
604	<row>
605	<entry>Define a parameter</entry>
606	<entry>
607	<sgmltag class="starttag">methodparam</sgmltag>
608	</entry>
609	<entry>
610	See
611	<xref linkend="write_docbook_doc.examples.methodimpl1" />
612	</entry>
613	</row>
614	<row>
615	<entry>Parameter type</entry>
616	<entry>
617	<sgmltag class="starttag">type</sgmltag>
618	</entry>
619	<entry>
620	See
621	<xref linkend="write_docbook_doc.examples.methodimpl1" />
622	</entry>
623	</row>
624	<row>
625	<entry>Parameter name</entry>
626	<entry>
627	<sgmltag class="starttag">parameter</sgmltag>
628	</entry>
629	<entry>
630	See
631	<xref linkend="write_docbook_doc.examples.methodimpl1" />
632	</entry>
633	</row>
634	</tbody>
635	</tgroup>
636	</informaltable>
637	<para>
638	Follow one of the examples below to insert a method definition in the document.
639	</para>
640	<example id="write_docbook_doc.examples.methodimpl">
641	<title>
642	Method with no arguments and a return value
643	</title>
644	<programlisting>
645	…
646	<methodsynopsis language="java">
647	<modifier>public</modifier>
648	<type>Plugin.MainType</type>
649	<methodname>getMainType</methodname>
650	<void />
651	</methodsynopsis>
652	…
653	</programlisting>
654	</example>
655	<example id="write_docbook_doc.examples.methodimpl1">
656	<title>
657	Method with arguments and no return value
658	</title>
659	<programlisting>
660	…
661	<methodsynopsis language="java">
662	<modifier>public</modifier>
663	<void />
664	<methodname>init</methodname>
665	<methodparam>
666	<type>SessionControl</type>
667	<parameter>sc</parameter>
668	</methodparam>
669	<methodparam>
670	<type>ParameterValues</type>
671	<parameter>configuration</parameter>
672	</methodparam>
673	<methodparam>
674	<type>ParameterValues</type>
675	<parameter>job</parameter>
676	</methodparam>
677	</methodsynopsis>
678	…
679	</programlisting>
680	</example>
681
682	</sect3>
683	<sect3 id="write_docbook_doc.usedtags.text.gui">
684	<title>Gui elements</title>
685	<para>
686	Docbook has some elements that can be used to symbolize gui items in a program.
687	Following list contains the ones that are most common in this document.
688	</para>
689	<informaltable frame="none">
690	<tgroup cols="3" rowsep="1" colsep="1">
691	<colspec align="left" />
692	<colspec align="center" />
693	<colspec align="left" />
694	<thead>
695	<row>
696	<entry>Define</entry>
697	<entry>Element to use</entry>
698	<entry>Comment</entry>
699	</row>
700	</thead>
701	<tbody>
702	<row>
703	<entry>Button</entry>
704	<entry>
705	<sgmltag class="starttag">guibutton</sgmltag>
706	</entry>
707	<entry></entry>
708	</row>
709	<row>
710	<entry>Label</entry>
711	<entry>
712	<sgmltag class="starttag">guilabel</sgmltag>
713	</entry>
714	<entry></entry>
715	</row>
716	<row>
717	<entry>Menu choice</entry>
718	<entry>
719	<sgmltag class="starttag">menuchoice</sgmltag>
720	</entry>
721	<entry></entry>
722	</row>
723	<row>
724	<entry>Menu</entry>
725	<entry>
726	<sgmltag class="starttag">guimenu</sgmltag>
727	</entry>
728	<entry></entry>
729	</row>
730	<row>
731	<entry>Submenu</entry>
732	<entry>
733	<sgmltag class="starttag">guisubmenu</sgmltag>
734	</entry>
735	<entry></entry>
736	</row>
737	<row>
738	<entry>Menu item</entry>
739	<entry>
740	<sgmltag class="starttag">guimenuitem</sgmltag>
741	</entry>
742	<entry></entry>
743	</row>
744	<row>
745	<entry>Icon</entry>
746	<entry>
747	<sgmltag class="starttag">guiicon</sgmltag>
748	</entry>
749	<entry></entry>
750	</row>
751	</tbody>
752	</tgroup>
753	</informaltable>
754	<para>
755	<xref linkend="write_docbook_doc.examples.guielements" />
756	shows how the menu choice in figure
757	<xref linkend="write_docbook_doc.figures.menuchoice" />
758	can be described.
759	</para>
760	<figure id="write_docbook_doc.figures.menuchoice">
761	<title>Menu choice</title>
762	<screenshot>
763	<mediaobject>
764	<imageobject>
765	<imagedata fileref="figures/menuchoice.png" format="PNG" />
766	</imageobject>
767	</mediaobject>
768	</screenshot>
769	</figure>
770	<example id="write_docbook_doc.examples.guielements">
771	<title>Describe a menu choice</title>
772	<programlisting>
773	…
774	<menuchoice>
775	<guimenu>Administrate</guimenu>
776	<guisubmenu>Plugins</guisubmenu>
777	<guimenuitem>Types</guimenuitem>
778	</menuchoice>
779	…
780	</programlisting>
781	<para>
782	In the text it will look like this:
783	<menuchoice>
784	<guimenu>Administrate</guimenu>
785	<guisubmenu>Plugins</guisubmenu>
786	<guimenuitem>Types</guimenuitem>
787	</menuchoice>
788	</para>
789	</example>
790	</sect3>
791	</sect2>
792	<sect2 id="write_docbook_doc.usedtags.images">
793	<title>Images and figures</title>
794	<para>
795	Images and figures are normally implemented like the following example. The
796	image-file must be located in
797	<filename class="directory">doc/src/docbook/figures</filename>
798	,otherwise the image won't be visible in the generated output files.
799	</para>
800	<example id="write_docbook_doc.examples.screenshot">
801	<title>Screen-shot in the documentation</title>
802	<para>
803	<xref linkend="write_docbook_doc.figures.menuchoice" />
804	is implemented with the following code
805	</para>
806	<programlisting>
807	<figure id="write_docbook_doc.figures.menuchoice">
808	<title>Menu choice</title>
809	<screenshot>
810	<mediaobject>
811	<imageobject>
812	<imagedata fileref="figures/menuchoice.png" format="PNG" />
813	</imageobject>
814	</mediaobject>
815	</screenshot>
816	</figure>
817	</programlisting>
818	</example>
819	</sect2>
820	<sect2 id="write_docbook_doc.usedtags.examples">
821	<title>Examples and program listing</title>
822	<para>
823	Following describes how to insert an example in the documentation.The examples in
824	this document are often some kind of program listing but they can still be examples
825	of something else.
826	</para>
827	<example id="write_docbook_doc.examples.example">
828	<title>Example in the documentation</title>
829	<para>
830	This shows how
831	<xref linkend="net.sf.basedb.core.plugin.Plugin.getAbout" />
832	is written in the corresponding XML-file.
833	</para>
834	<programlisting>
835	…
836	<example id="net.sf.basedb.core.plugin.Plugin.getAbout">
837	<title>A typical implementation stores this information in a static field</title>
838	<programlisting>
839	private static final About about = new AboutImpl
840	(
841	"Spot images creator",
842	"Converts a full-size scanned image into smaller preview jpg " +
843	"images for each individual spot.",
844	"2.0",
845	"2006, Department of Theoretical Physics, Lund University",
846	null,
847	"base@thep.lu.se",
848	"http://base.thep.lu.se"
849	);
850
851	public About getAbout()
852	{
853	return about;
854	}
855	</programlisting>
856	</example>
857	…
858	</programlisting>
859	</example>
860	</sect2>
861	<sect2 id="write_docbook_doc.usedtags.admonitions">
862	<title>Admonitions</title>
863	<para>
864	The admonitions that are used in this document can be found in the table below.
865	</para>
866	<informaltable frame="none">
867	<tgroup cols="3" rowsep="1" colsep="1">
868	<colspec align="left" />
869	<colspec align="center" />
870	<colspec align="left" />
871	<thead>
872	<row>
873	<entry>Define</entry>
874	<entry>Element to use</entry>
875	<entry>Comment</entry>
876	</row>
877	</thead>
878	<tbody>
879	<row>
880	<entry>Warning text</entry>
881	<entry>
882	<sgmltag class="starttag">warning</sgmltag>
883	</entry>
884	<entry></entry>
885	</row>
886	<row>
887	<entry>Notification text</entry>
888	<entry>
889	<sgmltag class="starttag">note</sgmltag>
890	</entry>
891	<entry></entry>
892	</row>
893	<row>
894	<entry>A tip</entry>
895	<entry>
896	<sgmltag class="starttag">tip</sgmltag>
897	</entry>
898	<entry></entry>
899	</row>
900	<row>
901	<entry>Important text</entry>
902	<entry>
903	<sgmltag class="starttag">important</sgmltag>
904	</entry>
905	<entry></entry>
906	</row>
907	<row>
908	<entry>Something to be cautious about</entry>
909	<entry>
910	<sgmltag class="starttag">caution</sgmltag>
911	</entry>
912	<entry></entry>
913	</row>
914	</tbody>
915	</tgroup>
916	</informaltable>
917	</sect2>
918	<sect2 id="write_docbook_doc.usedtags.lists">
919	<title>Lists</title>
920	<para>
921	Following items can be used to define different kind of lists in the documentation.
922	Some common elements for the lists are also described here.
923	</para>
924	<informaltable frame="none">
925	<tgroup cols="3" rowsep="1" colsep="1">
926	<colspec align="left" />
927	<colspec align="center" />
928	<colspec align="left" />
929	<thead>
930	<row>
931	<entry>Define</entry>
932	<entry>Element</entry>
933	<entry>Comment</entry>
934	</row>
935	</thead>
936	<tbody>
937	<row>
938	<entry>None-ordered list</entry>
939	<entry>
940	<sgmltag class="starttag">itemizedlist</sgmltag>
941	</entry>
942	<entry></entry>
943	</row>
944	<row>
945	<entry>Term definition list</entry>
946	<entry>
947	<sgmltag class="starttag">variablelist</sgmltag>
948	</entry>
949	<entry></entry>
950	</row>
951	<row>
952	<entry>Ordered list</entry>
953	<entry>
954	<sgmltag class="starttag">orderedlist</sgmltag>
955	</entry>
956	<entry></entry>
957	</row>
958	<row>
959	<entry>List item</entry>
960	<entry>
961	<sgmltag class="starttag">listitem</sgmltag>
962	</entry>
963	<entry></entry>
964	</row>
965	</tbody>
966	</tgroup>
967	</informaltable>
968	<para>The example below shows how to create a list for term definition in the text.</para>
969	<example id="write_docbook_doc.examples.variablelist">
970	<title>Example how to write a variable list</title>
971	<programlisting>
972	…
973	<variablelist>
974	<varlistentry>
975	<term>Term1</term>
976	<listitem>
977	<para>
978	Definition/explanation of the term
979	</para>
980	</listitem>
981	</varlistentry>
982
983	<varlistentry>
984	<term>Term2</term>
985	<listitem>
986	<para>
987	Definition/explanation of the term
988	</para>
989	</listitem>
990	</varlistentry>
991	</variablelist>
992	</programlisting>
993	</example>
994	</sect2>
995	</sect1>
996	</chapter>

Note: See TracBrowser for help on using the repository browser.

Download in other formats: