Changeset 3227


Ignore:
Timestamp:
Apr 4, 2007, 4:27:53 PM (14 years ago)
Author:
Martin Svensson
Message:

References #555.Added text to the chapter about docbook documentation.

Location:
trunk/doc/src/docbook
Files:
1 added
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/src/docbook/developerdoc/write_docbook_doc.xml

    r3225 r3227  
    44    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
    55<!--
    6   $Id: chapter_temp.xml 3192 2007-03-13 15:27:06Z martin $
    7 
     6  $Id$
     7 
    88  Copyright (C) Authors contributing to this file.
    9 
     9 
    1010  This file is part of BASE - BioArray Software Environment.
    1111  Available at http://base.thep.lu.se/
    12 
     12 
    1313  BASE is free software; you can redistribute it and/or
    1414  modify it under the terms of the GNU General Public License
    1515  as published by the Free Software Foundation; either version 2
    1616  of the License, or (at your option) any later version.
    17 
     17 
    1818  BASE is distributed in the hope that it will be useful,
    1919  but WITHOUT ANY WARRANTY; without even the implied warranty of
    2020  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    2121  GNU General Public License for more details.
    22 
     22 
    2323  You should have received a copy of the GNU General Public License
    2424  along with this program; if not, write to the Free Software
     
    2828
    2929<chapter id="write_docbook_doc">
    30   <title>How to write documentation with Docbook</title>
    31     <sect1>
    32       <title></title>
     30  <title>How to use docbook</title>
     31  <para>
     32    This chapter is for those who intent to contribute to the BASE2 documentation. The chapter
     33    contains an explanation of how the documentation is organized, what the different parts is
     34    about and other things that will make it easier to know where to put new text.
     35  </para>
     36  <para>
     37    The documentation is written with the docbook standard, which is a bunch of defined XML
     38    elements and XSLT stylesheets that are used to formating a text. Later in this chapter is a
     39    reference, over those docbook elements that are recommended to be used when writing BASE2
     40    documentation. Further information about docbook can be found in the online version of
     41    O'Reilly's
     42    <ulink url="http://www.docbook.org/tdg/en/html/">DocBook: The Definitive Guide</ulink>
     43    by Norman Walsh and Leonard Muellner
     44  </para>
     45
     46  <sect1 id="write_docbook_doc.layout">
     47    <title>Documentation layout</title>
     48    <para>
     49      The book, which is the main element in this docbook documentation, is devided into four
     50      seperated parts, depending on who the information is directed to. What kind of
     51      documentation each one of these parts contains or should contain is described here
     52      below.
     53    </para>
     54    <variablelist>
     55      <title>Parts of the documentation</title>
     56      <varlistentry>
     57        <term>Overview documentation</term>
     58        <listitem>
     59          <para>
     60            The overview part should contain, 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 wants/needs to know before exploring the program further on.
     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 of
     72            BASE2. More or less should anything that a power user- or user role can do
     73            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 should be put in this part. It
     82            can be how to install the program, how to configure the server for best
     83            performance or other administration related subjects.
     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 javadoc from the source code, how
     93            to develop a plugin e.t.c.
     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 starting to write any documentation to BASE2 there is a couple of things that can
     105      be good to know. This is to be able to follow those few rules and standards of BASE2
     106      documentation.
     107    </para>
     108    <sect2 id="write_docbook_doc.begin.sourcefiles">
     109      <title>Organization of source files</title>
     110      <para>
     111        The source files of docbook documentation are located in
     112        <filename class='directory'>base2root/doc/src/docbook</filename>
     113        which is showed in
     114        <xref linkend="write_docbook_doc.figures.fileorganization" />
     115        . The parts of the documentation are organized into separate folders and in each one
     116        of those folders is one index file and one file for each chapter in that part. The
     117        index file joins the chapters, in current part/folder, and doesn't really contain
     118        any text. An index file is also located in the documentation root and this file
     119        joins the other index files from the different parts.
     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      <para>
     132        Following items need to be done to create a new chapter in the documentation:
     133        <orderedlist numeration='arabic' spacing='compact'>
     134          <listitem>
     135            <para>
     136              Create a new file in the folder of which part the new chapter should be
     137              included. Give the new xml-file a name that is quite similar to the new
     138              chapter's title but use '_' instead of blank space and keep it down to one
     139              or few words.
     140            </para>
     141          </listitem>
     142          <listitem>
     143            <para>
     144              Begin to write the chapter's body, it should look like <xref linkend="write_docbook_doc.examples.chapterbody"/>
     145              <example id="write_docbook_doc.examples.chapterbody">
     146                <title>Body of a chapter</title>
     147                <programlisting>
     148&lt;?xml version="1.0" encoding="UTF-8"?&gt;
     149&lt;!DOCTYPE chapter PUBLIC
     150    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
     151    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd"&gt;
     152
     153&lt;chapter id="example_chapter"&gt;
     154   &lt;title&gt;Example of a chapter &lt;/title&gt;
     155   &lt;sect1 id="example_chapter.sect1_title"&gt;
     156      .
     157      .
     158   &lt;/sect1&gt;
     159   .
     160   .
     161   .
     162&lt;/chapter&gt;
     163                </programlisting>
     164              </example>
     165            </para>
     166          </listitem>
     167          <listitem>
     168            <para>
     169              Next and last step is to get the new chapter included in the right part
     170               of documentation. This is done by including the file's name in
     171               the file <filename>index.xml</filename> that's located in the current part's folder.
     172               <xref linkend="write_docbook_doc.examples.include_chapter"/>
     173               shows how the chapter that was created above is included in
     174               the user documentation part.
     175               <note>
     176                <title>Order of chapters</title>
     177                <para>
     178                  The chapters will come in the same order as they are included in the index file
     179                </para>
     180               </note>
     181               <example id="write_docbook_doc.examples.include_chapter">
     182                <title>Include a chapter</title>
     183                  <programlisting>
     184&lt;part id="userdoc"&gt;
     185   &lt;title&gt;User documentation&lt;/title&gt;
     186   &lt;include file= "about.xml"/&gt;
     187   &lt;include file="webclient.xml"/&gt;
     188   &lt;include file="project_permission.xml"/&gt;
     189   &lt;include file="trashcan.xml"/&gt;
     190   &lt;include file="file_system.xml"/&gt;
     191   &lt;include file="jobs.xml"/&gt;
     192   &lt;include file="reporters.xml"/&gt;
     193   &lt;include file="annotations.xml"/&gt;
     194   &lt;include file="protocols.xml"/&gt;
     195   &lt;include file="hardware.xml"/&gt;
     196   <userinput>&lt;include file="example_chapter.xml"/&gt;</userinput>
     197   &lt;include file="software.xml"/&gt;
     198   &lt;include file="array_lims.xml"/&gt;
     199   &lt;include file="biomaterials.xml"/&gt;
     200   &lt;include file="experiments_analysis.xml"/&gt;
     201   &lt;include file="import_export_data.xml"/&gt;
     202&lt;/part&gt;
     203                  </programlisting>
     204                </example>
     205            </para>
     206          </listitem>     
     207        </orderedlist>
     208        Now it's only to go ahead with the writting of this new chapter.
     209      </para>
     210    </sect2>
     211    <sect2 id="write_docbook_doc.begin.id">
     212      <title>The 'id' attribute</title>
     213      <para>
     214        All elements has an id attribute that can have an unique value to
     215        identify the element with. Most of the elements that are used inside
     216        BASE2 documentation don't need to have an id if they don't are used in
     217        any cross reference from other part of the text.
     218      </para>
     219      <para>
     220        But there are some elements that allways should have an <varname>id</varname>.
     221        Which these elements are and how the id should look like for each one of
     222        those is described below.
     223        <variablelist>
     224          <title>
     225            These elements should have an id
     226          </title>
     227          <para>
     228            All
     229            <varname>id</varname>s
     230            should be as short as possible and asocciate to the current element.
     231            The
     232            <varname>id</varname>
     233            shouldn't consist of other characters then lowercase of a-z,
     234            <userinput>_</userinput>
     235            instead of blank spaces and
     236            <userinput>.</userinput>
     237            to symbolize different levels in the document.
     238          </para>
     239          <varlistentry>
     240            <term>chapter</term>
     241            <listitem>
     242              <para>
     243                The chapter should have an <varname>id</varname> that is identical
     244                or almost identical to the file's name.
     245              </para>
     246            </listitem>
     247          </varlistentry>
     248          <varlistentry>
     249            <term>sect1-sect5</term>
     250            <listitem>
     251              <para>
     252                The creation of a section's id is done by using the upper level's id and
     253                add <synopsis>.section_title</synopsis>
     254              </para>
     255            </listitem>
     256          </varlistentry>
     257          <varlistentry>
     258            <term>examples</term>
     259            <listitem>
     260              <para>
     261                The naming of an example's <varname>id</varname> is a bit different
     262                compare to the chapter's and section's id. It should begin with the chapter's id
     263                followed by <synopsis>.examples.example_name.</synopsis>
     264              </para>
     265            </listitem>
     266          </varlistentry>
     267          <varlistentry>
     268            <term>figures</term>
     269            <listitem>
     270              <para>
     271                The figure's <varname>id</varname> should have the following layout
     272                <synopsis>chapter_id.figures.figure_name</synopsis>
     273              </para>
     274            </listitem>
     275          </varlistentry>     
     276        </variablelist>
     277      </para>
     278    </sect2>
     279    <sect2 id="write_docbook_doc.begin.helptext">
     280      <title>Markup helptexts</title>
    33281      <para></para>
    34     </sect1>
     282    </sect2>
     283    <sect2 id="write_docbook_doc.begin.generate">
     284      <title>Generate the document</title>
     285      <para></para>
     286      <variablelist>
     287        <title>Document types</title>
     288        <varlistentry>
     289          <term>Chunked html pages</term>
     290          <listitem>
     291            <para></para>
     292          </listitem>
     293        </varlistentry>
     294        <varlistentry>
     295          <term>Pdf-file</term>
     296          <listitem>
     297            <para></para>
     298          </listitem>
     299        </varlistentry>
     300        <varlistentry>
     301          <term>Helptext import file for BASE2</term>
     302          <listitem>
     303            <para></para>
     304          </listitem>
     305        </varlistentry>
     306      </variablelist>
     307    </sect2>
     308  </sect1>
     309
     310
     311  <sect1 id="write_docbook_doc.usedtags">
     312    <title>Elements to use</title>
     313    <para>Which docbook tags are used in the documentation and when to use what......</para>
     314  </sect1>
    35315</chapter>
Note: See TracChangeset for help on using the changeset viewer.