Ignore:
Timestamp:
Apr 26, 2007, 1:23:31 PM (16 years ago)
Author:
Martin Svensson
Message:

References #555. Document ready to be inspected

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/src/docbook/developerdoc/write_docbook_doc.xml

    r3268 r3274  
    3232  <para>
    3333    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.
     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.
    3636  </para>
    3737  <para>
    3838    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
     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
    4242    O'Reilly's
    4343    <ulink url="http://www.docbook.org/tdg/en/html/">DocBook: The Definitive Guide</ulink>
    … …  
    6969        <listitem>
    7070          <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.
     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.
    7474          </para>
    7575        </listitem>
    … …  
    7979        <listitem>
    8080          <para>
    81             Things that only an administrator-role can do is put in this part. It
     81            Things that only an administrator-role can do is documented in this part. It
    8282            can be how to install the program, how to configure the server for best
    8383            performance or other subjects that are related to the administration.
    … …  
    8989        <listitem>
    9090          <para>
    91             Documentation about participation in the BASE2 development should be placed
     91            Documentation concerning the participation of BASE2 development should be placed
    9292            in this part, e.g. coding standards, the java doc from the source code, how
    9393            to develop a plugin etc.
    … …  
    102102    <title>Getting started</title>
    103103    <para>
    104       Before start writing any documentation in BASE2 there is a couple of things, some
     104      Before start writing any documentation in BASE2 there are a couple of things, some
    105105      rules and standards, to have in mind.
    106106    </para>
    … …  
    108108      <title>Organization of source files</title>
    109109      <para>
    110         The source files of docbook documentation are located in
     110        The source files of the documentation are located in
    111111        <filename class='directory'>base2root/doc/src/docbook</filename>
    112112        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>     
     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>
    120121      <figure id="write_docbook_doc.figures.fileorganization">
    121122        <title>The organization of documentation files</title>
    … …  
    148149                <xref linkend="write_docbook_doc.examples.chapterbody"/>
    149150                <example id="write_docbook_doc.examples.chapterbody">
    150                   <title>Body of a chapter</title>
     151                  <title>Example of a chapter</title>
    151152                  <programlisting>
    152153&lt;?xml version="1.0" encoding="UTF-8"?&gt;
    … …  
    155156    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd"&gt;
    156157
    157 &lt;chapter id="example_chapter"&gt;
     158&lt;chapter id="<replaceable>example_chapter</replaceable>"&gt;
     159   &lt;?dbhtml dir="<replaceable>folder name to put the chapter's files in</replaceable>"?&gt;
    158160   &lt;title&gt;Example of a chapter &lt;/title&gt;
    159    &lt;sect1 id="example_chapter.sect1_title"&gt;
    160       .
    161       .
     161   &lt;para&gt;
     162      &hellip;
     163   &lt;/para&gt;
     164   &lt;sect1 id="<replaceable>example_chapter.sect1</replaceable>"&gt;
     165      &lt;title&gt;Example of top level section &lt;/title&gt;
     166      &lt;para&gt;
     167         &hellip;
     168      &lt;/para&gt;
     169      &lt;sect2 id="<replaceable>example_chapter.sect1.sect2</replaceable>"&gt;
     170         &lt;title&gt;Example of second level section &lt;/title&gt;
     171         &lt;para&gt;
     172            &hellip;
     173         &lt;/para&gt;
     174         &lt;sect3 id="<replaceable>example_chapter.sect1.sect2.sect3</replaceable>"&gt;
     175            &lt;title&gt;Example of third level section&lt;/title&gt;
     176            &lt;para&gt;
     177               &hellip;
     178            &lt;/para&gt;
     179         &lt;/sect3&gt;
     180      &lt;/sect2&gt;     
    162181   &lt;/sect1&gt;
    163    .
    164    .
    165    .
    166182&lt;/chapter&gt;
    167183                  </programlisting>
    168184                </example>
    169185              </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>
    170196            </listitem>
    171197            <listitem>
    172198              <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>
     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>
    182210&lt;part id="userdoc"&gt;
    183211   &lt;title&gt;User documentation&lt;/title&gt;
    … …  
    199227   &lt;include file="import_export_data.xml"/&gt;
    200228&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>
     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>
    210238            </listitem>     
    211239          </orderedlist>
    212           Now it's only to go ahead with the writing of this new chapter.
     240          Now it's only to go ahead with the documentation writing.
    213241        </para>
    214242      </sect3>
    … …  
    221249      </title>
    222250      <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
     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
    225253        need to have an id if they don't are used in any cross references from other part of
    226254        the text.
    227255      </para>
    228256      <para>
    229         There are however some elements that always should have an
     257        There are however some elements that always should have the
    230258        <sgmltag class="attribute">id</sgmltag>
    231         . Which these elements are and how the
     259        set. Which these elements are and how the
    232260        <sgmltag class="attribute">id</sgmltag>
    233261        should look like for each one of those is described below. All ids should be as
    234262        short as possible and associated to the current element. The
    235263        <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.
     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.
    241266        <variablelist>
    242267          <varlistentry>
    … …  
    257282                The creation of a section's id is done by using the upper level's id
    258283                and add the section's title or a part of the title. For
    259                 &lt;sect2&gt; it should be like
     284                &lt;sect2&gt; it should be like this;
    260285                <synopsis>chapter_title.sect1_title.sect2_title</synopsis>
    261                 .
    262286              </para>
    263287            </listitem>
    … …  
    294318      <title>Mark help texts</title>
    295319      <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.
     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.
    301327      </para>
    302328      <note>
    … …  
    316342          <varlistentry>
    317343            <term>
    318               <sgmltag class="attribute">id</sgmltag>
     344              <sgmltag class="attribute">external_id</sgmltag>
    319345            </term>
    320346            <listitem>
    321347              <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.
     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.
    326353              </para>
    327354            </listitem>
    … …  
    329356          <varlistentry>
    330357            <term>
    331               <sgmltag class="attribute">id</sgmltag>
     358              <sgmltag class="attribute">title</sgmltag>
    332359            </term>
    333360            <listitem>
    … …  
    345372&lt;sect1&gt;
    346373  &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>
     374    <replaceable>The text that also should be used as a helptext in the program.</replaceable>
    348375  &lt;/helptext&gt;
    349376&lt;/sect1&gt;
    … …  
    361388      <para>
    362389        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
     390        source. The format to view the documentation on-line will be the one with chunked
    364391        HTML pages where each chapter and section of first level are on separate
    365392        pages/files. The other format is a PDF-file that are most useful for printing and
    … …  
    373400  <sect1 id="write_docbook_doc.usedtags">
    374401    <title>Elements to use</title>
    375     <para>Which docbook tags are used in the documentation and when to use what......</para>
    376402    <para>
    377       There will not be any detailed explanation of the tags, instead the reader is
     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
    378406      recommended to get more information from
    379407      <ulink url="http://www.docbook.org/tdg/en/html/docbook.html">
    380         docbook's documentation
     408        Docbook's documentation
    381409      </ulink>
    382410      or other references.
    383411    </para>
    384412    <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>
     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>
    464506
    465507      <sect3 id="write_docbook_doc.usedtags.text.keywords">
    … …  
    467509        <para>
    468510          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.
     511          meaning, like method names, class names and user inputs just to mention some.
    471512        </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>
     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&hellip;
     646&lt;methodsynopsis language="java"&gt;
     647  &lt;modifier&gt;public&lt;/modifier&gt;
     648  &lt;type&gt;Plugin.MainType&lt;/type&gt;
     649  &lt;methodname&gt;getMainType&lt;/methodname&gt;
     650  &lt;void /&gt;
     651&lt;/methodsynopsis&gt;
     652&hellip;
     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&hellip;
     661&lt;methodsynopsis language="java"&gt;
     662  &lt;modifier&gt;public&lt;/modifier&gt;
     663  &lt;void /&gt;
     664  &lt;methodname&gt;init&lt;/methodname&gt;
     665  &lt;methodparam&gt;
     666    &lt;type&gt;SessionControl&lt;/type&gt;
     667    &lt;parameter&gt;sc&lt;/parameter&gt;
     668  &lt;/methodparam&gt;
     669  &lt;methodparam&gt;
     670    &lt;type&gt;ParameterValues&lt;/type&gt;
     671    &lt;parameter&gt;configuration&lt;/parameter&gt;
     672  &lt;/methodparam&gt;
     673  &lt;methodparam&gt;
     674    &lt;type&gt;ParameterValues&lt;/type&gt;
     675    &lt;parameter&gt;job&lt;/parameter&gt;
     676  &lt;/methodparam&gt;
     677&lt;/methodsynopsis&gt;
     678&hellip;
     679          </programlisting>
     680        </example>
     681       
    482682      </sect3>
    483683      <sect3 id="write_docbook_doc.usedtags.text.gui">
    484684        <title>Gui elements</title>
    485685        <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.
     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.
    488688        </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>
     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&hellip;         
     774&lt;menuchoice&gt;
     775  &lt;guimenu&gt;Administrate&lt;/guimenu&gt;
     776  &lt;guisubmenu&gt;Plugins&lt;/guisubmenu&gt;
     777  &lt;guimenuitem&gt;Types&lt;/guimenuitem&gt;
     778&lt;/menuchoice&gt;
     779&hellip;
     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>
    497790      </sect3>
    498791    </sect2>
    … …  
    500793      <title>Images and figures</title>
    501794      <para>
    502         Images and figures are normally implemented like the following example. The image-file must be located in
     795        Images and figures are normally implemented like the following example. The
     796        image-file must be located in
    503797        <filename class="directory">doc/src/docbook/figures</filename>
    504798        ,otherwise the image won't be visible in the generated output files.
    505799      </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>
     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>
    516806        <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;       
     807&lt;figure id="write_docbook_doc.figures.menuchoice"&gt;
     808  &lt;title&gt;Menu choice&lt;/title&gt;
     809  &lt;screenshot&gt;
     810    &lt;mediaobject&gt;
     811      &lt;imageobject&gt;
     812        &lt;imagedata fileref="figures/menuchoice.png" format="PNG" /&gt;
     813      &lt;/imageobject&gt;
     814    &lt;/mediaobject&gt;
     815  &lt;/screenshot&gt;
     816&lt;/figure&gt;
    524817        </programlisting>
    525818      </example>
    526819    </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  &hellip;
     836  &lt;example id="net.sf.basedb.core.plugin.Plugin.getAbout"&gt;
     837     &lt;title&gt;A typical implementation stores this information in a static field&lt;/title&gt;
     838     &lt;programlisting&gt;
     839private 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 
     851public About getAbout()
     852{
     853   return about;
     854}
     855     &lt;/programlisting&gt;
     856  &lt;/example&gt;
     857  &hellip;
     858        </programlisting>
     859      </example>     
     860    </sect2>
    527861    <sect2 id="write_docbook_doc.usedtags.admonitions">
    528862      <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>
     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>
    577917    </sect2>
    578918    <sect2 id="write_docbook_doc.usedtags.lists">
    … …  
    582922        Some common elements for the lists are also described here.
    583923      </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>
     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&hellip;
     973&lt;variablelist&gt;
     974   &lt;varlistentry&gt;
     975      &lt;term&gt;Term1&lt;/term&gt;
     976      &lt;listitem&gt;
     977         &lt;para&gt;
     978            Definition/explanation of the term
     979         &lt;/para&gt;
     980      &lt;/listitem&gt;
     981   &lt;/varlistentry&gt;
     982   
     983   &lt;varlistentry&gt;
     984      &lt;term&gt;Term2&lt;/term&gt;
     985      &lt;listitem&gt;
     986         &lt;para&gt;
     987            Definition/explanation of the term
     988         &lt;/para&gt;
     989      &lt;/listitem&gt;
     990   &lt;/varlistentry&gt;
     991&lt;/variablelist&gt;
     992        </programlisting>
     993      </example>
    628994    </sect2>
    629995  </sect1>
Note: See TracChangeset for help on using the changeset viewer.