Changeset 3231


Ignore:
Timestamp:
Apr 6, 2007, 2:57:55 PM (14 years ago)
Author:
Martin Svensson
Message:

References #555. Added information on how to get started with writing the BASE2 documentation in docbook

Location:
trunk/doc/src/docbook
Files:
2 edited

Legend:

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

    r3227 r3231  
    3636  <para>
    3737    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
     38    elements and XSLT style sheets that are used to formatting the text. Later in this chapter is a
     39    reference, over those docbook elements that are recommended to use when writing BASE2
    4040    documentation. Further information about docbook can be found in the online version of
    4141    O'Reilly's
     
    4747    <title>Documentation layout</title>
    4848    <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
     49      The book, which is the main element in this docbook documentation, is divided into four
     50      separated parts, depending on who the information is directed to. What kind of
    5151      documentation each one of these parts contains or should contain is described here
    5252      below.
     
    5858        <listitem>
    5959          <para>
    60             The overview part should contain, like the name says, an overview of BASE2.
     60            The overview part contains, like the name says, an overview of BASE2.
    6161            For example an explanation about what the purpose with BASE2 is, the terms
    6262            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.
     63            interested in the program wants/needs to know before exploring it further.
    6464          </para>
    6565        </listitem>
     
    6969        <listitem>
    7070          <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.
     71            This part contains information that are relevant for the common user in
     72            BASE2. More or less should everything that a power user- or user role needs
     73            to know be documented here.
    7474          </para>
    7575        </listitem>
     
    7979        <listitem>
    8080          <para>
    81             Things that only an administrator-role can do should be put in this part. It
     81            Things that only an administrator-role can do is put in this part. It
    8282            can be how to install the program, how to configure the server for best
    83             performance or other administration related subjects.
     83            performance or other subjects that are related to the administration.
    8484          </para>
    8585        </listitem>
     
    9090          <para>
    9191            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
     92            in this part, e.g. coding standards, the java doc from the source code, how
    9393            to develop a plugin e.t.c.
    9494          </para>
     
    102102    <title>Getting started</title>
    103103    <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.
     104      Before start writing any documentation in BASE2 there is a couple of things, some
     105      rules and standards, to have in mind.
    107106    </para>
    108107    <sect2 id="write_docbook_doc.begin.sourcefiles">
     
    116115        of those folders is one index file and one file for each chapter in that part. The
    117116        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.
     117        any text. The documentation root contains also an index.xml file which joins the
     118        other index files from the different parts.
    120119      </para>     
    121120      <figure id="write_docbook_doc.figures.fileorganization">
     
    129128        </screenshot>
    130129      </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>
     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>
    148152&lt;?xml version="1.0" encoding="UTF-8"?&gt;
    149153&lt;!DOCTYPE chapter PUBLIC
     
    161165   .
    162166&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>
     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>
    184182&lt;part id="userdoc"&gt;
    185183   &lt;title&gt;User documentation&lt;/title&gt;
     
    201199   &lt;include file="import_export_data.xml"/&gt;
    202200&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>
     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>
    210215    </sect2>
    211216    <sect2 id="write_docbook_doc.begin.id">
    212       <title>The 'id' attribute</title>
     217      <title>The <varname>id</varname> attribute</title>
    213218      <para>
    214219        All elements has an id attribute that can have an unique value to
    215220        identify the element with. Most of the elements that are used inside
    216221        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.
     222        any cross references from other part of the text.
     223      </para>
     224      <para>
     225        But there are some elements that always should have an <varname>id</varname>.
     226        Which these elements are and how the <varname>id</varname> should look like for
     227        each one of those is described below.
    223228        <variablelist>
    224229          <title>
    225             These elements should have an id
     230            Where <varname>id</varname> is required
    226231          </title>
    227232          <para>
    228             All
    229             <varname>id</varname>s
    230             should be as short as possible and asocciate to the current element.
     233            All ids should be as short as possible and associated to the current element.
    231234            The
    232235            <varname>id</varname>
    233             shouldn't consist of other characters then lowercase of a-z,
     236            shouldn't consist of other characters then lowercase a-z,
    234237            <userinput>_</userinput>
    235238            instead of blank spaces and
     
    242245              <para>
    243246                The chapter should have an <varname>id</varname> that is identical
    244                 or almost identical to the file's name.
     247                or almost identical to the chapter's title.
     248                <synopsis>chapter_title</synopsis>
    245249              </para>
    246250            </listitem>
     
    251255              <para>
    252256                The creation of a section's id is done by using the upper level's id and
    253                 add <synopsis>.section_title</synopsis>
     257                add the section's title or a part of the title. For &lt;sect2&gt; it should
     258                be like <synopsis>chapter_title.sect1_title.sect2_title</synopsis>.
    254259              </para>
    255260            </listitem>
     
    261266                The naming of an example's <varname>id</varname> is a bit different
    262267                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>
     268                followed by <userinput>examples</userinput> and the caption of the
     269                example.
     270                <synopsis>chapter_title.examples.example_caption</synopsis>
    264271              </para>
    265272            </listitem>
     
    270277              <para>
    271278                The figure's <varname>id</varname> should have the following layout
    272                 <synopsis>chapter_id.figures.figure_name</synopsis>
     279                <synopsis>chapter_title.figures.figure_name</synopsis>
    273280              </para>
    274281            </listitem>
     
    278285    </sect2>
    279286    <sect2 id="write_docbook_doc.begin.helptext">
    280       <title>Markup helptexts</title>
    281       <para></para>
     287      <title>Tag help texts</title>
     288      <para>
     289        It's possible, in the document source, to tag those parts of text that also should be
     290        used as help texts inside the web client of BASE2. When running a specific ant-target the text
     291        inside help text tags are exported to a separate XML-file which then can be imported into
     292         BASE2 with the help text import plugin. How to generate the import file can be
     293         read in 
     294         <xref linkend="write_docbook_doc.begin.generate"/>
     295      </para>
     296      <para>
     297        The help text tag must be outside the <sgmltag>para</sgmltag> tag but inside
     298        a <sgmltag>sect1</sgmltag> to work properly. Each tag requires then two
     299        different attributes
     300        <variablelist>
     301          <varlistentry>
     302            <term>
     303              <varname>external_id</varname>
     304            </term>
     305            <listitem>
     306              <para>
     307                is used to identify help text in the web client.
     308                BASE2's web client already has several help texts that are defined,
     309                it could therefore be a good idea to look in program to see if
     310                there already is an external id to use.
     311              </para>
     312            </listitem>
     313          </varlistentry>
     314          <varlistentry>
     315            <term>
     316              <varname>title</varname>
     317            </term>
     318            <listitem>
     319              <para>
     320                is direct connected to the name/title property for a help text item in
     321                BASE2.
     322              </para>
     323            </listitem>
     324          </varlistentry>
     325        </variablelist>
     326      </para>
     327     
    282328    </sect2>
    283329    <sect2 id="write_docbook_doc.begin.generate">
    284330      <title>Generate the document</title>
    285       <para></para>
     331      <para>
     332        There are two different types of format that can be generated from the documentation
     333        source. The format to view the documentation online will be the one
     334        with chunked HTML pages where each chapter and section of first level are on
     335        separate pages. The other format is a PDF-file that are most useful for printing
     336        and distribution. Those two types of output are generated with different ant
     337        targets which are described below.
     338      </para>
     339      <para>
     340       
     341      </para>
    286342      <variablelist>
    287343        <title>Document types</title>
    288344        <varlistentry>
    289           <term>Chunked html pages</term>
     345          <term>Chunked HTML pages</term>
    290346          <listitem>
    291             <para></para>
     347            <para>
     348              Run <command>ant docbook</command> to generate the documentation in
     349              this format.
     350            </para>           
     351            <para>
     352              The generated files will be put in
     353              <filename class='directory'>base2root/doc/docbook/</filename>
     354              and the main file is
     355              <filename class='headerfile'>index.html</filename> which contains a
     356              table of content over the rest of the document and some navigation links.
     357            </para>
    292358          </listitem>
    293359        </varlistentry>
    294360        <varlistentry>
    295           <term>Pdf-file</term>
     361          <term>PDF-file</term>
    296362          <listitem>
    297             <para></para>
     363            <para>
     364              This is not implemented yet.
     365            </para>
    298366          </listitem>
    299367        </varlistentry>
    300368        <varlistentry>
    301           <term>Helptext import file for BASE2</term>
     369          <term>Help text import file for BASE2</term>
    302370          <listitem>
    303             <para></para>
     371            <para>
     372              The import file with help texts,
     373              <filename class='headerfile'>helptext_docbook.xml</filename>,
     374               is also generated with an ant target and can be found in
     375              <filename class='directory'>base2root/build/docbook</filename>.
     376              Use <command>ant helptext</command> to generate this file.
     377            </para>
    304378          </listitem>
    305379        </varlistentry>
     
    311385  <sect1 id="write_docbook_doc.usedtags">
    312386    <title>Elements to use</title>
    313     <para>Which docbook tags are used in the documentation and when to use what......</para>
     387    <para>
     388      Which docbook tags are used in the documentation and when to use what......
     389    </para>
    314390  </sect1>
    315391</chapter>
Note: See TracChangeset for help on using the changeset viewer.