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

Last change on this file since 3268 was 3268, checked in by Martin Svensson, 16 years ago

References #555. Started to list the elements that are used in the documentation source.
File size: 23.0 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id$
7 
8  Copyright (C) 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 an explanation 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 put 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 formatting the text. Later in this chapter is a
40    reference, over those docbook elements that are recommended to use when writing BASE2
41    documentation. Further information about docbook can be found in the online 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 user in
72            BASE2. More or less should everything that a power user role or an user role needs
73            to know be documented 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 put 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 about participation in the 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 is 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 docbook 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 each one
115        of the folders contains one index file and one file for each chapter in that part. The
116        index file joins the chapters, in current part/folder, together and doesn't really contain
117        any text. The documentation root directory also contains an <filename class='headerfile'>index.xml</filename> file which joins the
118        index files from the different parts together.
119      </para>     
120      <figure id="write_docbook_doc.figures.fileorganization">
121        <title>The organization of documentation files</title>
122        <screenshot>
123          <mediaobject>
124            <imageobject>
125              <imagedata fileref="figures/fileorganization.png" format="PNG"></imagedata>
126            </imageobject>
127          </mediaobject>
128        </screenshot>
129      </figure>
130      <sect3 id="write_docbook_doc.begin.sourcefiles.newfile">
131        <title>Create new chapter/file</title>
132        <para>
133          Each file in the documentation, except the index files, represents a chapter.
134          How to create a new chapter and include it in the text is described in
135          following items.
136          <orderedlist numeration='arabic' spacing='compact'>
137            <listitem>
138              <para>
139                Create a new XML-file in the folder of which part the new chapter
140                should be included. Give it a name that is quite similar to the
141                new chapter's title but use <userinput>_</userinput> instead of
142                blank space and keep it down to one or few words.
143              </para>
144            </listitem>
145            <listitem>
146              <para>
147                Begin to write the chapter's body, it should look like
148                <xref linkend="write_docbook_doc.examples.chapterbody"/>
149                <example id="write_docbook_doc.examples.chapterbody">
150                  <title>Body of a chapter</title>
151                  <programlisting>
152&lt;?xml version="1.0" encoding="UTF-8"?&gt;
153&lt;!DOCTYPE chapter PUBLIC
154    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
155    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd"&gt;
156
157&lt;chapter id="example_chapter"&gt;
158   &lt;title&gt;Example of a chapter &lt;/title&gt;
159   &lt;sect1 id="example_chapter.sect1_title"&gt;
160      .
161      .
162   &lt;/sect1&gt;
163   .
164   .
165   .
166&lt;/chapter&gt;
167                  </programlisting>
168                </example>
169              </para>
170            </listitem>
171            <listitem>
172              <para>
173                Next and last step is to get the new chapter included in the right part
174                 of documentation. This is done by including the file's name in
175                 the file <filename>index.xml</filename> that's located in the current part's folder.
176                 <xref linkend="write_docbook_doc.examples.include_chapter"/> 
177                 shows how the chapter that was created above is included in
178                 the user documentation part.
179                 <example id="write_docbook_doc.examples.include_chapter">
180                  <title>Include a chapter</title>
181                    <programlisting>
182&lt;part id="userdoc"&gt;
183   &lt;title&gt;User documentation&lt;/title&gt;
184   &lt;include file= "about.xml"/&gt;
185   &lt;include file="webclient.xml"/&gt;
186   &lt;include file="project_permission.xml"/&gt;
187   &lt;include file="trashcan.xml"/&gt;
188   &lt;include file="file_system.xml"/&gt;
189   &lt;include file="jobs.xml"/&gt;
190   &lt;include file="reporters.xml"/&gt;
191   &lt;include file="annotations.xml"/&gt;
192   &lt;include file="protocols.xml"/&gt;
193   &lt;include file="hardware.xml"/&gt;
194   <userinput>&lt;include file="example_chapter.xml"/&gt;</userinput>
195   &lt;include file="software.xml"/&gt;
196   &lt;include file="array_lims.xml"/&gt;
197   &lt;include file="biomaterials.xml"/&gt;
198   &lt;include file="experiments_analysis.xml"/&gt;
199   &lt;include file="import_export_data.xml"/&gt;
200&lt;/part&gt;
201                    </programlisting>
202                  </example>
203                   <note>
204                  <title>Order of chapters</title>
205                  <para>
206                    The chapters will come in the same order as they are included in the index file
207                  </para>
208                </note>
209              </para>
210            </listitem>     
211          </orderedlist>
212          Now it's only to go ahead with the writing of this new chapter.
213        </para>
214      </sect3>
215    </sect2>
216    <sect2 id="write_docbook_doc.begin.id">
217      <title>
218        The
219        <sgmltag class="attribute">id</sgmltag>
220        attribute
221      </title>
222      <para>
223        All elements has an id attribute that can have an unique value to identify the
224        element with. Most of the elements that are used inside BASE2 documentation don't
225        need to have an id if they don't are used in any cross references from other part of
226        the text.
227      </para>
228      <para>
229        There are however some elements that always should have an
230        <sgmltag class="attribute">id</sgmltag>
231        . Which these elements are and how the
232        <sgmltag class="attribute">id</sgmltag>
233        should look like for each one of those is described below. All ids should be as
234        short as possible and associated to the current element. The
235        <sgmltag class="attribute">id</sgmltag>
236        shouldn't consist of other characters then lowercase a-z,
237        <userinput>_</userinput>
238        instead of blank spaces and
239        <userinput>.</userinput>
240        to symbolize the different levels in the document.
241        <variablelist>
242          <varlistentry>
243            <term>chapter</term>
244            <listitem>
245              <para>
246                The chapter should have an
247                <sgmltag class="attribute">id</sgmltag>
248                that is identical or almost identical to the chapter's title.
249                <synopsis>chapter_title</synopsis>
250              </para>
251            </listitem>
252          </varlistentry>
253          <varlistentry>
254            <term>sect1-sect5</term>
255            <listitem>
256              <para>
257                The creation of a section's id is done by using the upper level's id
258                and add the section's title or a part of the title. For
259                &lt;sect2&gt; it should be like
260                <synopsis>chapter_title.sect1_title.sect2_title</synopsis>
261                .
262              </para>
263            </listitem>
264          </varlistentry>
265          <varlistentry>
266            <term>examples</term>
267            <listitem>
268              <para>
269                The naming of an example's
270                <sgmltag class="attribute">id</sgmltag>
271                is a bit different compare to the chapter's and section's id. It
272                should begin with the chapter's id followed by
273                <userinput>examples</userinput>
274                and the caption of the example.
275                <synopsis>chapter_title.examples.example_caption</synopsis>
276              </para>
277            </listitem>
278          </varlistentry>
279          <varlistentry>
280            <term>figures</term>
281            <listitem>
282              <para>
283                The figure's
284                <sgmltag class="attribute">id</sgmltag>
285                should have the following layout
286                <synopsis>chapter_title.figures.figure_name</synopsis>
287              </para>
288            </listitem>
289          </varlistentry>
290        </variablelist>
291      </para>
292    </sect2>
293    <sect2 id="write_docbook_doc.begin.helptext">
294      <title>Mark help texts</title>
295      <para>
296        It is possible to tag those parts of the text in documentation source that also
297        should be used as help texts in the web client.The tagged parts will be
298        exported to a XML-file at the same time as the html-documentation is generated.This
299        generated XML-file is compatible with the help text importer in BASE2 and will be
300        imported when running the update script or installation script.
301      </para>
302      <note>
303      <para>
304        The
305        <sgmltag class="starttag">helptext</sgmltag>
306        must be outside the
307        <sgmltag>para</sgmltag>
308        tag but inside a
309        <sgmltag>sect1</sgmltag>
310        tag to work properly.
311      </para>
312      </note>
313      <para>
314        Each tag requires two different attributes
315        <variablelist>
316          <varlistentry>
317            <term>
318              <sgmltag class="attribute">id</sgmltag>
319            </term>
320            <listitem>
321              <para>
322                is used to identify and find a help text in the web client. BASE2's
323                web client already has a several of help texts that are defined, it
324                could therefore be a good idea to have a look in the program to see if
325                there already is an external id to use.
326              </para>
327            </listitem>
328          </varlistentry>
329          <varlistentry>
330            <term>
331              <sgmltag class="attribute">id</sgmltag>
332            </term>
333            <listitem>
334              <para>
335                is directly connected to the name/title property for a help text
336                item in BASE2.
337              </para>
338            </listitem>
339          </varlistentry>
340        </variablelist>
341      </para>
342      <example id="write_docbook_doc.examples.helptexttag">
343        <title>How to use the help text tag</title>
344        <programlisting>
345&lt;sect1&gt;
346  &lt;helptext external_id="<replaceable>helptexts.external.id</replaceable>" title="<replaceable>The title</replaceable>"&gt;
347    <replaceable>The text that should also be used as a helptext in the program</replaceable>
348  &lt;/helptext&gt;
349&lt;/sect1&gt;
350        </programlisting>
351      </example>
352      <para>
353        Import the generated XML-file manually by uploading it from the
354        <filename class="directory">data</filename>
355        directory to the BASE-server's file system and then use the help text importer
356        plugin to import the help text items from that file.
357      </para>
358    </sect2>
359    <sect2 id="write_docbook_doc.begin.generate">
360      <title>Generate the document</title>
361      <para>
362        There are two different types of format that is generated from the documentation
363        source. The format to view the documentation online will be the one with chunked
364        HTML pages where each chapter and section of first level are on separate
365        pages/files. The other format is a PDF-file that are most useful for printing and
366        distribution. Those two types of output are generated with the ant-target:
367        <userinput>ant docbook</userinput>
368        .
369      </para>
370    </sect2>
371  </sect1>
372
373  <sect1 id="write_docbook_doc.usedtags">
374    <title>Elements to use</title>
375    <para>Which docbook tags are used in the documentation and when to use what......</para>
376    <para>
377      There will not be any detailed explanation of the tags, instead the reader is
378      recommended to get more information from
379      <ulink url="http://www.docbook.org/tdg/en/html/docbook.html">
380        docbook's documentation
381      </ulink>
382      or other references.
383    </para>
384    <sect2 id="write_docbook_doc.usedtags.text">
385      <title>Text</title>
386      <para>
387        Here are the most common elements that are used in the current documentation source
388        to give the text a layout in some kind.
389      </para>
390      <variablelist>
391        <varlistentry>
392          <term>
393            <sgmltag class="starttag">chapter</sgmltag>
394          </term>
395          <listitem>
396            <para>
397              Define a chapter. Read more about chapters in this document in the
398              <xref linkend="write_docbook_doc.begin" />
399            </para>
400          </listitem>
401        </varlistentry>
402        <varlistentry>
403          <term>
404            <sgmltag class="starttag">sect1</sgmltag>
405            ,
406            <sgmltag class="starttag">sect2</sgmltag>
407            ,
408            <sgmltag class="starttag">sect3</sgmltag>
409          </term>
410          <listitem>
411            <para>
412              Different levels of subsections in the document, see
413              <xref linkend="write_docbook_doc.begin" />
414              for more information how to implement them right.
415            </para>
416          </listitem>
417        </varlistentry>
418        <varlistentry>
419          <term>
420            <sgmltag class="starttag">title</sgmltag>
421          </term>
422          <listitem>
423            <para>
424              Define title-node in those elements that can have a title.
425            </para>
426          </listitem>
427        </varlistentry>
428        <varlistentry>
429          <term>
430            <sgmltag class="starttag">para</sgmltag>
431          </term>
432          <listitem>
433            <para>
434              Define a paragraph in the text. Required as a child node in many
435              different elements.
436            </para>
437          </listitem>
438        </varlistentry>
439        <varlistentry>
440          <term>
441            <sgmltag class="starttag">ulink</sgmltag>
442          </term>
443          <listitem>
444            <para>
445              Define an external link to the URL that is set in it's
446              <sgmltag class="attribute">url</sgmltag>
447              attribute.
448            </para>
449          </listitem>
450        </varlistentry>
451        <varlistentry>
452          <term>
453            <sgmltag class="starttag">xref</sgmltag>
454          </term>
455          <listitem>
456            <para>
457              Define a link inside this document. The
458              <sgmltag class="attribute">linkend</sgmltag>
459              attribute holds the id to the target element.
460            </para>
461          </listitem>
462        </varlistentry>
463      </variablelist>
464
465      <sect3 id="write_docbook_doc.usedtags.text.keywords">
466        <title>Markup special words and phrases</title>
467        <para>
468          These elements should be used to mark up words and phrases that have a special
469          meaning, like method names, class names and user inputs just to mention some
470          examples.
471        </para>
472        <variablelist><varlistentry><term><sgmltag class="starttag">methodsynopsis</sgmltag></term><listitem><para></para></listitem></varlistentry>
473        <varlistentry><term><sgmltag class="starttag">modifier</sgmltag></term><listitem><para></para></listitem></varlistentry>
474        <varlistentry><term><sgmltag class="starttag">methodname</sgmltag></term><listitem><para></para></listitem></varlistentry>       
475        <varlistentry><term><sgmltag class="starttag">methodparam</sgmltag></term><listitem><para></para></listitem></varlistentry>
476        <varlistentry><term><sgmltag class="starttag">type</sgmltag></term><listitem><para></para></listitem></varlistentry>
477        <varlistentry><term><sgmltag class="starttag">parameter</sgmltag></term><listitem><para></para></listitem></varlistentry>
478        <varlistentry><term><sgmltag class="starttag">classname</sgmltag></term><listitem><para></para></listitem></varlistentry>
479        <varlistentry><term><sgmltag class="starttag">userinput</sgmltag></term><listitem><para></para></listitem></varlistentry>
480        <varlistentry><term><sgmltag class="starttag">varname</sgmltag></term><listitem><para></para></listitem></varlistentry>
481        <varlistentry><term><sgmltag class="starttag">constant</sgmltag></term><listitem><para></para></listitem></varlistentry></variablelist>
482      </sect3>
483      <sect3 id="write_docbook_doc.usedtags.text.gui">
484        <title>Gui elements</title>
485        <para>
486          There are alot of elements that symbolize the gui in a program. Following
487          list contains those which are used in this document.
488        </para>
489        <variablelist><varlistentry><term><sgmltag class="starttag">guibutton</sgmltag></term><listitem><para></para></listitem></varlistentry>
490        <varlistentry><term><sgmltag class="starttag">guilabel</sgmltag></term><listitem><para></para></listitem></varlistentry>
491        <varlistentry><term><sgmltag class="starttag">menuchoice</sgmltag></term><listitem><para></para></listitem></varlistentry>
492        <varlistentry><term><sgmltag class="starttag">guimenu</sgmltag></term><listitem><para></para></listitem></varlistentry>
493        <varlistentry><term><sgmltag class="starttag">guisubmenu</sgmltag></term><listitem><para></para></listitem></varlistentry>
494        <varlistentry><term><sgmltag class="starttag">guimenuitem</sgmltag></term><listitem><para></para></listitem></varlistentry>
495        <varlistentry><term><sgmltag class="starttag">guicon</sgmltag></term><listitem><para></para></listitem></varlistentry>
496        </variablelist> 
497      </sect3>
498    </sect2>
499    <sect2 id="write_docbook_doc.usedtags.images">
500      <title>Images and figures</title>
501      <para>
502        Images and figures are normally implemented like the following example. The image-file must be located in
503        <filename class="directory">doc/src/docbook/figures</filename>
504        ,otherwise the image won't be visible in the generated output files.
505      </para>
506    </sect2>
507    <sect2 id="write_docbook_doc.usedtags.examples">
508      <title>Examples and programlisting</title>
509      <para>
510        Following describes how to insert an example and programlisting. In this
511        documentation the examples are often some kind of programlisting but they can still
512        be examples of something else.
513      </para>
514      <example id="write_docbook_doc.examples.example">
515        <title>How to insert an example of program listing</title>
516        <programlisting>
517&lt;example id="<replaceable>chapterId</replaceable>.examples.<replaceable>exampleId</replaceable>"&gt;
518  &lt;title&gt;<replaceable>The title of the example</replaceable>&lt;/title&gt;
519  &lt;programlisting&gt;
520<replaceable>The example code. Can not be indented like the source code that surrounds it
521  if the layout should have a correct look.</replaceable>
522  &lt;/programlisting&gt;
523&lt;/example&gt;       
524        </programlisting>
525      </example>
526    </sect2>
527    <sect2 id="write_docbook_doc.usedtags.admonitions">
528      <title>Admonitions</title>
529      <para></para>
530      <variablelist>
531        <varlistentry>
532          <term>
533            <sgmltag class="starttag">note</sgmltag>
534          </term>
535          <listitem>
536            <para>Define a notification for the reader.</para>
537          </listitem>
538        </varlistentry>
539        <varlistentry>
540          <term>
541            <sgmltag class="starttag">warning</sgmltag>
542          </term>
543          <listitem>
544            <para>Define the text as a warning for the reader look up with.</para>
545          </listitem>
546        </varlistentry>
547        <varlistentry>
548          <term>
549            <sgmltag class="starttag">tip</sgmltag>
550          </term>
551          <listitem>
552            <para>Define something that can be useful for the reader to know.</para>
553          </listitem>
554        </varlistentry>
555        <varlistentry>
556          <term>
557            <sgmltag class="starttag">important</sgmltag>
558          </term>
559          <listitem>
560            <para>
561              Define a text to be important, something the reader should pay certain
562              attention to.
563            </para>
564          </listitem>
565        </varlistentry>
566        <varlistentry>
567          <term>
568            <sgmltag class="starttag">caution</sgmltag>
569          </term>
570          <listitem>
571            <para>
572              Define a text about something the reader should be cautious with.
573            </para>
574          </listitem>
575        </varlistentry>
576      </variablelist>
577    </sect2>
578    <sect2 id="write_docbook_doc.usedtags.lists">
579      <title>Lists</title>
580      <para>
581        Following items can be used to define different kind of lists in the documentation.
582        Some common elements for the lists are also described here.
583      </para>
584      <variablelist>
585        <varlistentry>
586          <term>
587            <sgmltag class="starttag">listitem</sgmltag>
588          </term>
589          <listitem>
590            <para>Define an item in one of the three lists below.</para>
591          </listitem>
592        </varlistentry>
593        <varlistentry>
594          <term>
595            <sgmltag class="starttag">itemizedlist</sgmltag>
596          </term>
597          <listitem>
598            <para>Define a list where each item is marked with a bullet.</para>
599          </listitem>
600        </varlistentry>
601        <varlistentry>
602          <term>
603            <sgmltag class="starttag">varlist</sgmltag>
604          </term>
605          <listitem>
606            <para>
607              Define a variable list. Beside variables, this type is also being used
608              to describe different kind of items.This list type needs to have some
609              more child items to work correctly.See the
610              <ulink url="http://www.docbook.org/tdg/en/html/variablelist.html">
611                docbook documentation
612              </ulink>
613              for more information.
614            </para>
615          </listitem>
616        </varlistentry>
617        <varlistentry>
618          <term>
619            <sgmltag class="starttag">orderedlist</sgmltag>
620          </term>
621          <listitem>
622            <para>
623              Define an ordered list with each item marked with an incremented label.
624            </para>
625          </listitem>
626        </varlistentry>
627      </variablelist>
628    </sect2>
629  </sect1>
630</chapter>
Note: See TracBrowser for help on using the repository browser.