Changeset 5819


Ignore:
Timestamp:
Oct 21, 2011, 2:48:15 PM (12 years ago)
Author:
Nicklas Nordborg
Message:

References #1590: Documentation cleanup

The chapter about writing docbook documentation has been updated.

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

Legend:

Unmodified
Added
Removed

  • trunk/doc/src/docbook/developer/documentation.xml

    r5782 r5819  
    3434
    3535    <para>
    36       This chapter is for those who intent to contribute to the BASE user documentation.
     36      This chapter is for those who intend to contribute to the BASE user documentation.
    3737      The chapter contains explanations of how the documentation is organized, what the
    3838      different parts is about and other things that will make it easier to know
    … …  
    101101      </varlistentry>
    102102    </variablelist>
     103   
     104    <para>
     105      In addition to the four main parts, there is also a FAQ part and an
     106      Appendix part.
     107    </para>
     108   
    103109  </sect2>
    104110
    … …  
    122128        file which joins the index files from the different parts together.
    123129      </para>
    124       <figure id="docbook.figures.fileorganization">
    125         <title>The organization of documentation files</title>
    126         <screenshot>
    127           <mediaobject>
    128             <imageobject>
    129               <imagedata fileref="figures/fileorganization.png" format="PNG" />
    130             </imageobject>
    131           </mediaobject>
    132         </screenshot>
    133       </figure>
    134       <sect4 id="docbook.begin.sourcefiles.newfile">
     130    </sect3>
     131    <sect3 id="docbook.begin.newchapter">
    135132        <title>Create new chapter/file</title>
    136133        <para>
    … …  
    151148                <example id="docbook.examples.chapterbody">
    152149                  <title>Example of a chapter</title>
    153 <programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
    154 &lt;!DOCTYPE chapter PUBLIC
     150<programlisting language="xml"><![CDATA[
     151<?xml version="1.0" encoding="UTF-8"?>
     152<!DOCTYPE chapter PUBLIC
    155153  "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
    156   "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd"&gt;
    157 
    158 &lt;chapter id="example_chapter"&gt;
    159    &lt;?dbhtml dir="folder name to put the chapter's files in"?&gt;
    160    &lt;title&gt;Example of a chapter &lt;/title&gt;
    161    &lt;para&gt;
    162       &hellip;
    163    &lt;/para&gt;
    164    &lt;sect1 id="example_chapter.sect1"&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="example_chapter.sect1.sect2"&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="example_chapter.sect1.sect2.sect3"&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;     
    181    &lt;/sect1&gt;
    182 &lt;/chapter&gt;</programlisting>
     154  "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
     155
     156<chapter id="example_chapter">
     157   <?dbhtml dir="example" filename="index.html" ?>
     158   <title>Example of a chapter </title>
     159   <para>
     160      ...
     161   </para>
     162   <sect1 id="example_chapter.sect1">
     163      <title>Example of top level section </title>
     164      <para>
     165         ...
     166      </para>
     167      <sect2 id="example_chapter.sect1.sect2">
     168         <title>Example of second level section </title>
     169         <para>
     170            ...
     171         </para>
     172         <sect3 id="example_chapter.sect1.sect2.sect3">
     173            <title>Example of third level section</title>
     174            <para>
     175               ...
     176            </para>
     177         </sect3>
     178      </sect2>     
     179   </sect1>
     180</chapter>
     181]]></programlisting>
    183182                </example>
    184183              </para>
    185184              <note>
    186185                <para>
    187                   Do not forget to include the
    188                   <sgmltag>dbhtml</sgmltag>
    189                   tag with the attribute
    190                   <sgmltag class="attribute">dir</sgmltag>
    191                   set to the value that the chapter's output folder should have as a
    192                   name.
     186                  Do not forget to include the <sgmltag class="pi">dbhtml</sgmltag>
     187                  tag with the <sgmltag class="attribute">dir</sgmltag>
     188                  and/or <sgmltag class="attribute">filename</sgmltag>
     189                  attributes set to target folder and filename for the chapter.
    193190                </para>
    194191              </note>
    … …  
    202199                The following example
    203200                shows how the chapter that was created above is included in the user
    204                 documentation part.
     201                documentation part (as the last chapter).
    205202              </para>
    206203              <example id="docbook.examples.include_chapter">
    207204                <title>Include a chapter</title>
    208 <programlisting language="xml:nogutter:nocontrols">&lt;part id="userdoc"&gt;
    209    &lt;title&gt;User documentation&lt;/title&gt;
    210    &lt;include file= "about.xml"/&gt;
    211    &lt;include file="webclient.xml"/&gt;
    212    &lt;include file="project_permission.xml"/&gt;
    213    &lt;include file="trashcan.xml"/&gt;
    214    &lt;include file="file_system.xml"/&gt;
    215    &lt;include file="jobs.xml"/&gt;
    216    &lt;include file="reporters.xml"/&gt;
    217    &lt;include file="annotations.xml"/&gt;
    218    &lt;include file="protocols.xml"/&gt;
    219    &lt;include file="hardware.xml"/&gt;
    220    &lt;include file="example_chapter.xml"/&gt;
    221    &lt;include file="software.xml"/&gt;
    222    &lt;include file="array_lims.xml"/&gt;
    223    &lt;include file="biomaterials.xml"/&gt;
    224    &lt;include file="experiments_analysis.xml"/&gt;
    225    &lt;include file="import_export_data.xml"/&gt;
    226 &lt;/part&gt;</programlisting>
     205<programlisting language="xml:nogutter:nocontrols"><![CDATA[
     206<part id="user">
     207   <?dbhtml dir="user" filename="index.html" ?>
     208   <title>User documentation</title>
     209   <include file="overview.xml"/>
     210   <include file="webclient.xml"/>
     211   <include file="project_permission.xml"/>
     212   <include file="file_system.xml"/>
     213   <include file="jobs.xml"/>
     214   <include file="reporters.xml"/>
     215   <include file="annotations.xml"/>
     216   <include file="platforms.xml" />
     217   <include file="subtypes.xml" />
     218   <include file="protocols.xml"/>
     219   <include file="wares.xml"/>
     220   <include file="array_lims.xml"/>
     221   <include file="biomaterials.xml"/>
     222   <include file="experiments_analysis.xml"/>
     223   <include file="import_data.xml"/>
     224   <include file="export_data.xml"/>
     225   <include file="example_chapter.xml"/>
     226</part>
     227]]></programlisting>
    227228                </example>
    228229              <note>
    … …  
    235236            </listitem>     
    236237          </orderedlist>
    237           Now it's only to go ahead with the documentation writing.
    238238        </para>
    239       </sect4>
    240239    </sect3>
    241240   
    … …  
    253252        as an attribute to the <sgmltag class="starttag">chapter</sgmltag> tag, for example:
    254253      </para>
    255       <programlisting language="xml">&lt;chapter id="resources" chunked="0"&gt;</programlisting>
     254      <programlisting language="xml"><![CDATA[
     255<chapter id="resources" chunked="0">
     256]]></programlisting>
    256257      <para>
    257258        This will stop the chunking of <sgmltag class="starttag">sect1</sgmltag>
    … …  
    266267        section in a separate chunk:
    267268      </para>
    268       <programlisting language="xml">&lt;sect1 id="sect.with.large.sect2" chunked="1"&gt;</programlisting>
     269      <programlisting language="xml"><![CDATA[
     270<sect1 id="sect.with.large.sect2" chunked="1">
     271]]></programlisting>
    269272   
    270273    </sect3>
    … …  
    310313            <listitem>
    311314              <para>
    312                 The creation of a section's id is done by using the upper level's id
     315                The creation of a section's id is done by combining an
     316                appropriate part of the parent chapter and/or section
     317                id with the current section's title (or part of the title).
     318                This rule may seem a little "fuzzy" but the aim is to
     319                not create too long id's yet they must still be unique.
     320               
     321                using the upper level's id
    313322                and add the section's title or a part of the title. For
    314                 &lt;sect2&gt; it should be like this;
    315                 <synopsis>chapter_title.sect1_title.sect2_title</synopsis>
    316               </para>
     323                a <sgmltag class="starttag">sect2</sgmltag> the id could
     324                for example be created like this:
     325                <synopsis>sect1_title.sect2_title</synopsis>
     326              </para>         
    317327            </listitem>
    318328          </varlistentry>
    … …  
    346356    </sect3>
    347357    <sect3 id="docbook.begin.helptext">
    348       <title>Mark help texts</title>
     358      <title>Help text for the BASE web client</title>
    349359      <para>
    350360        This documentation is also use to create the help texts that show up
    351         in the web client when clicking on the question mark icons.
    352         The parts of the text that also should be used as help texts in the web must be
    353         inside
     361        in the BASE web client when clicking on the question mark icons.
     362        The parts of the text that also should be used as help texts in the web client
     363        must be inside
    354364        <sgmltag class="starttag">helptext</sgmltag>
    355365        tags. These texts will be exported to a XML-file at the same time as the
    … …  
    417427      <example id="docbook.examples.helptexttag">
    418428        <title>How to use the help text tag</title>
    419 <programlisting language="xml">&lt;sect1&gt;
    420    &lt;helptext external_id="helptexts.external.id" title="The title"&gt;
     429<programlisting language="xml"><![CDATA[
     430<sect1 id="....">
     431   <helptext external_id="helptexts.external.id" title="The title">
    421432      The text that also should be used as a helptext in the program.
    422       &lt;seeother&gt;
    423          &lt;other external_id="other.external.id"&gt;
    424             Related info here...&lt;/other&gt;
    425       &lt;/seeother&gt;
    426    &lt;/helptext&gt;
    427 &lt;/sect1&gt;</programlisting>
     433      <seeother>
     434         <other external_id="other.external.id">Related info here...</other>
     435      </seeother>
     436   </helptext>
     437</sect1>
     438]]></programlisting>
    428439      </example>
    429440     
    … …  
    439450          outputted to the help texts.
    440451        </para>     
    441         <programlisting language="xml">&lt;nohelp&gt;see &lt;xref linkend="chapter11" /&gt;&lt;/nohelp&gt;</programlisting>
     452        <programlisting language="xml"><![CDATA[
     453<nohelp>See <xref linkend="chapter11" /></nohelp>
     454]]></programlisting>
    442455      </sect4>
    443456     
    … …  
    466479        </variablelist>
    467480       
    468 <programlisting language="xml">&lt;seeother&gt;
    469   &lt;other external_id="userpreferences.password"&gt;Change password&lt;/other&gt;
    470   &lt;other external_id="userpreferences.other"&gt;Other information&lt;/other&gt;
    471 &lt;/seeother&gt;</programlisting>
     481<programlisting language="xml"><![CDATA[
     482<seeother>
     483  <other external_id="userpreferences.password">Change password</other>
     484  <other external_id="userpreferences.other">Other information</other>
     485</seeother>]]></programlisting>
    472486       
    473487        <para>
    … …  
    501515    </sect3>
    502516    <sect3 id="docbook.begin.generate">
    503       <title>Generate output</title>
    504 
    505       <sect4 id="docbook.begin.generate.requirements">
    506         <title>Requirements</title>
     517      <title>Build the documentation</title>
     518
    507519        <para>
    508520          Those who have checked out the documentation source from repository or got the
    … …  
    521533          </para>
    522534        </note>
    523       </sect4>
    524       <sect4 id="docbook.begin.generate.compile">
    525         <title>Compile - generate output files</title>
     535       
    526536        <para>
    527537          There are two different types of format that is generated from the documentation
    … …  
    534544          BASE.
    535545        </para>
    536       </sect4>
    537546    </sect3>
    538547  </sect2>
    … …  
    576585                <para>
    577586                  See
    578                   <xref linkend="docbook.examples.chapterbody" />
     587                  <xref linkend="docbook.examples.chapterbody" />.
    579588                </para>
    580589              </entry>
    … …  
    586595              </entry>
    587596              <entry>
    588                 <xref linkend="docbook.examples.chapterbody" />
    589                 shows how this can be implemented
     597                See <xref linkend="docbook.examples.chapterbody" />.
    590598              </entry>
    591599            </row>
    … …  
    604612              <entry>
    605613                See
    606                 <xref linkend="docbook.begin.id" />
     614                <xref linkend="docbook.begin.id" />.
    607615              </entry>
    608616            </row>
    … …  
    614622              <entry>
    615623                See
    616                 <xref linkend="docbook.begin.id" />
     624                <xref linkend="docbook.begin.id" />.
    617625              </entry>
    618626            </row>
    … …  
    624632              <entry>
    625633                See
    626                 <xref linkend="docbook.begin.id" />
    627               </entry>
    628             </row>
    629             <row>
    630               <entry>Fourth level section</entry>
    631               <entry>
    632                 <sgmltag class="starttag">sect4</sgmltag>
    633               </entry>
    634               <entry></entry>
    635             </row>
    636             <row>
    637               <entry>Fifth level section</entry>
    638               <entry>
    639                 <sgmltag class="starttag">sect5</sgmltag>
    640               </entry>
    641               <entry></entry>
     634                <xref linkend="docbook.begin.id" />.
     635              </entry>
    642636            </row>
    643637          </tbody>
    644638        </tgroup>
    645639      </informaltable>
    646 
    647       <sect4 id="docbook.usedtags.text.keywords">
     640    </sect3>
     641
     642    <sect3 id="docbook.usedtags.code">
    648643        <title>Code elements</title>
    649644        <para>
    … …  
    671666                </entry>
    672667                <entry>
    673                   The name of a (Java) class.
    674                   <sgmltag class="attribute">docapi</sgmltag>-attribute
    675                   can be used to link the class to it's Javadoc (only
    676                   HTML-version). This is done by setting the attribute to the
     668                  The name of a (Java) class. The
     669                  <sgmltag class="attribute">docapi</sgmltag> attribute
     670                  can be used to link the class to it's Javadoc (for the
     671                  BASE API). This is done by setting the attribute to the
    677672                  package name of the class, like
    678                   <synopsis>net.sf.basedb.core</synopsis>
     673                  <programlisting language="xml"><![CDATA[<classname docapi="net.sf.baseb.core">DbControl</classname>]]></programlisting>
    679674                </entry>
    680675              </row>
    … …  
    710705                  <sgmltag class="starttag">constant</sgmltag>
    711706                </entry>
    712                 <entry>The name of a variable in a program.</entry>
     707                <entry>The name of a constant in a program.</entry>
    713708              </row>
    714709              <row>
    … …  
    719714                <entry>
    720715                  See
    721                   <xref linkend="docbook.examples.methodimpl" />
     716                  <xref linkend="docbook.examples.methodimpl" />.
    722717                </entry>
    723718              </row>
    … …  
    728723                </entry>
    729724                <entry>
     725                  - " -
     726                </entry>
     727              </row>
     728              <row>
     729                <entry>Classification of return value</entry>
     730                <entry>
     731                  <sgmltag class="starttag">type</sgmltag>
     732                </entry>
     733                <entry>
     734                  - " -
     735                </entry>
     736              </row>
     737              <row>
     738                <entry>Method name</entry>
     739                <entry>
     740                  <sgmltag class="starttag">methodname</sgmltag>
     741                </entry>
     742                <entry>
     743                  - " -
     744                </entry>
     745              </row>
     746              <row>
     747                <entry>No parameter/type</entry>
     748                <entry>
     749                  <sgmltag class="starttag">void</sgmltag>
     750                </entry>
     751                <entry>
     752                  - " -
     753                </entry>
     754              </row>
     755              <row>
     756                <entry>Define a parameter</entry>
     757                <entry>
     758                  <sgmltag class="starttag">methodparam</sgmltag>
     759                </entry>
     760                <entry>
    730761                  See
    731                   <xref linkend="docbook.examples.methodimpl" />
    732                 </entry>
    733               </row>
    734               <row>
    735                 <entry>Classification of return value</entry>
     762                  <xref linkend="docbook.examples.methodimpl1" />.
     763                </entry>
     764              </row>
     765              <row>
     766                <entry>Parameter type</entry>
    736767                <entry>
    737768                  <sgmltag class="starttag">type</sgmltag>
    738769                </entry>
    739770                <entry>
    740                   See
    741                   <xref linkend="docbook.examples.methodimpl" />
    742                 </entry>
    743               </row>
    744               <row>
    745                 <entry>Method name</entry>
    746                 <entry>
    747                   <sgmltag class="starttag">methodname</sgmltag>
    748                 </entry>
    749                 <entry>
    750                   See
    751                   <xref linkend="docbook.examples.methodimpl" />
    752                 </entry>
    753               </row>
    754               <row>
    755                 <entry>No parameter/type</entry>
    756                 <entry>
    757                   <sgmltag class="starttag">void</sgmltag>
    758                 </entry>
    759                 <entry>
    760                   See
    761                   <xref linkend="docbook.examples.methodimpl" />
    762                 </entry>
    763               </row>
    764               <row>
    765                 <entry>Define a parameter</entry>
    766                 <entry>
    767                   <sgmltag class="starttag">methodparam</sgmltag>
    768                 </entry>
    769                 <entry>
    770                   See
    771                   <xref linkend="docbook.examples.methodimpl1" />
    772                 </entry>
    773               </row>
    774               <row>
    775                 <entry>Parameter type</entry>
    776                 <entry>
    777                   <sgmltag class="starttag">type</sgmltag>
    778                 </entry>
    779                 <entry>
    780                   See
    781                   <xref linkend="docbook.examples.methodimpl1" />
     771                  - " -
    782772                </entry>
    783773              </row>
    … …  
    788778                </entry>
    789779                <entry>
    790                   See
    791                   <xref linkend="docbook.examples.methodimpl1" />
     780                  - " -
    792781                </entry>
    793782              </row>
    … …  
    802791            Method with no arguments and a return value
    803792          </title>
    804 <programlisting language="xml">
    805 &lt;methodsynopsis language="java"&gt;
    806    &lt;modifier&gt;public&lt;/modifier&gt;
    807    &lt;type&gt;Plugin.MainType&lt;/type&gt;
    808    &lt;methodname&gt;getMainType&lt;/methodname&gt;
    809    &lt;void /&gt;
    810 &lt;/methodsynopsis&gt;
    811 </programlisting>
     793<programlisting language="xml"><![CDATA[
     794<methodsynopsis language="java">
     795   <modifier>public</modifier>
     796   <type>Plugin.MainType</type>
     797   <methodname>getMainType</methodname>
     798   <void />
     799</methodsynopsis>]]></programlisting>
     800
     801        which is rendered as:
     802       
     803          <methodsynopsis language="java"> 
     804             <modifier>public</modifier> 
     805             <type>Plugin.MainType</type> 
     806             <methodname>getMainType</methodname> 
     807             <void /> 
     808          </methodsynopsis>
    812809        </example>
     810       
    813811        <example id="docbook.examples.methodimpl1">
    814812          <title>
    815813            Method with arguments and no return value
    816814          </title>
    817 <programlisting language="xml">
    818 &lt;methodsynopsis language="java"&gt;
    819    &lt;modifier&gt;public&lt;/modifier&gt;
    820    &lt;void /&gt;
    821    &lt;methodname&gt;init&lt;/methodname&gt;
    822    &lt;methodparam&gt;
    823       &lt;type&gt;SessionControl&lt;/type&gt;
    824       &lt;parameter&gt;sc&lt;/parameter&gt;
    825    &lt;/methodparam&gt;
    826    &lt;methodparam&gt;
    827       &lt;type&gt;ParameterValues&lt;/type&gt;
    828       &lt;parameter&gt;configuration&lt;/parameter&gt;
    829    &lt;/methodparam&gt;
    830    &lt;methodparam&gt;
    831       &lt;type&gt;ParameterValues&lt;/type&gt;
    832       &lt;parameter&gt;job&lt;/parameter&gt;
    833    &lt;/methodparam&gt;
    834 &lt;/methodsynopsis&gt;
    835 </programlisting>
     815<programlisting language="xml"><![CDATA[
     816<methodsynopsis language="java">
     817   <modifier>public</modifier>
     818   <void />
     819   <methodname>init</methodname>
     820   <methodparam>
     821      <type>SessionControl</type>
     822      <parameter>sc</parameter>
     823   </methodparam>
     824   <methodparam>
     825      <type>ParameterValues</type>
     826      <parameter>configuration</parameter>
     827   </methodparam>
     828   <methodparam>
     829      <type>ParameterValues</type>
     830      <parameter>job</parameter>
     831   </methodparam>
     832</methodsynopsis>
     833]]></programlisting>
     834
     835        which is rendered as:     
     836          <methodsynopsis language="java"> 
     837             <modifier>public</modifier> 
     838             <void /> 
     839             <methodname>init</methodname> 
     840             <methodparam> 
     841                <type>SessionControl</type> 
     842                <parameter>sc</parameter> 
     843             </methodparam> 
     844             <methodparam> 
     845                <type>ParameterValues</type> 
     846                <parameter>configuration</parameter> 
     847             </methodparam> 
     848             <methodparam> 
     849                <type>ParameterValues</type> 
     850                <parameter>job</parameter> 
     851             </methodparam> 
     852          </methodsynopsis> 
    836853        </example>
    837854       
    838       </sect4>
    839       <sect4 id="docbook.usedtags.text.gui">
     855    </sect3>
     856   
     857    <sect3 id="docbook.usedtags.gui">
    840858        <title>Gui elements</title>
    841859        <para>
    … …  
    908926          </tgroup>
    909927        </informaltable>
    910         <para>
    911           <xref linkend="docbook.examples.guielements" />
    912           shows how the menu choice in figure
    913           <xref linkend="docbook.figures.menuchoice" />
    914           can be described.
    915         </para>
    916         <figure id="docbook.figures.menuchoice">
    917           <title>Menu choice</title>
    918           <screenshot>
    919             <mediaobject>
    920               <imageobject>
    921                 <imagedata
    922                   fileref="figures/menuchoice.png" format="PNG"
    923                 />
    924               </imageobject>
    925             </mediaobject>
    926           </screenshot>
    927         </figure>
    928928        <example id="docbook.examples.guielements">
    929929          <title>Describe a menu choice</title>
    930 <programlisting language="xml">
    931 &lt;menuchoice&gt;
    932    &lt;guimenu&gt;Administrate&lt;/guimenu&gt;
    933    &lt;guisubmenu&gt;Plugins&lt;/guisubmenu&gt;
    934    &lt;guimenuitem&gt;Types&lt;/guimenuitem&gt;
    935 &lt;/menuchoice&gt;
    936 </programlisting>
     930<programlisting language="xml"><![CDATA[
     931<menuchoice>
     932   <guimenu>Administrate</guimenu>
     933   <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
     934   <guimenuitem>Overview</guimenuitem>
     935</menuchoice>]]></programlisting>
    937936          <para>
    938937            In the text it will look like this:
    939938            <menuchoice>
    940939              <guimenu>Administrate</guimenu>
    941               <guisubmenu>Plugins</guisubmenu>
    942               <guimenuitem>Types</guimenuitem>
     940              <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
     941              <guimenuitem>Overview</guimenuitem>
    943942            </menuchoice>
    944943          </para>
    945944        </example>
    946       </sect4>
    947945    </sect3>
     946   
    948947    <sect3 id="docbook.usedtags.images">
    949948      <title>Images and figures</title>
    … …  
    957956      <example id="docbook.examples.screenshot">
    958957        <title>Screen-shot in the documentation</title>
    959         <para>
    960           <xref linkend="webclient.figures.homepage" />
    961           is implemented with the following code
    962         </para>
    963 <programlisting language="xml">&lt;figure id="docbook.figures.menuchoice"&gt;
    964   &lt;title&gt;The home page&lt;/title&gt;
    965   &lt;screenshot&gt;
    966     &lt;mediaobject&gt;
    967       &lt;imageobject&gt;
    968         &lt;imagedata
     958<programlisting language="xml"><![CDATA[
     959<figure id="docbook.figures.homepage">
     960  <title>The home page</title>
     961  <screenshot>
     962    <mediaobject>
     963      <imageobject>
     964        <imagedata
    969965          scalefit="1"
    970966          width="100%"
    971967          fileref="figures/homapage.png" format="PNG"
    972         /&gt;
    973       &lt;/imageobject&gt;
    974     &lt;/mediaobject&gt;
    975   &lt;/screenshot&gt;
    976 &lt;/figure&gt;</programlisting>
     968        />
     969      </imageobject>
     970    </mediaobject>
     971  </screenshot>
     972</figure>]]></programlisting>
     973        <para>
     974        which will generate an image like
     975        <xref linkend="webclient.figures.homepage" />.
     976        </para>
    977977      </example>
    978978      <warning>
    … …  
    10701070            <constant>xml</constant> or <constant>sql</constant>. The highlighting engine
    10711071            support more languages. To add support for those in docbook, change
    1072             the <filename>customized.chunked.xsl</filename> file. The syntax highlighting
    1073             engine doesn't handle markup inside the <sgmltag class="starttag">programlisting</sgmltag>
    1074             tag very well. You should avoid that. By default, java program examples
    1075             include line numbering, but not xml examples. To disable line numbering
    1076             for java add <constant>:nogutter</constant> to the <sgmltag>language</sgmltag>
     1072            the <filename>customized.chunked.xsl</filename> file.
     1073            The syntax highlighting engine doesn't handle docbook markup inside the <sgmltag
     1074            class="starttag">programlisting</sgmltag> tag very well. You should avoid that,
     1075            by using text-only examples withing a <code>&lt;![CDATA[ ... ]]&gt;</code>
     1076            section. By default, Java program examples
     1077            include line numbering, but XML examples don't. To disable line numbering
     1078            for Java add <constant>:nogutter</constant> to the <sgmltag>language</sgmltag>
    10771079            attribute: <constant>&lt;programlisting language="java:nogutter"&gt;</constant>.
    1078             To enable line numbering for xml add <constant>:gutter</constant> to the <sgmltag>language</sgmltag>
     1080            To enable line numbering for xml add <constant>:gutter</constant>
     1081            to the <sgmltag>language</sgmltag>
    10791082            attribute: <constant>&lt;programlisting language="xml:gutter"&gt;</constant>.
    10801083          </simpara>
    … …  
    10851088        <title>Example in the documentation</title>
    10861089        <para>
    1087           This shows how 
    1088           <xref linkend="net.sf.basedb.core.plugin.Plugin.getAbout" />
    1089           is written in the corresponding XML-file.
     1090          The code below is used to create 
     1091          <xref linkend="net.sf.basedb.core.plugin.Plugin.getMainType" />.
    10901092        </para>
    1091 <programlisting language="xml">
    1092 &lt;example id="net.sf.basedb.core.plugin.Plugin.getAbout"&gt;
    1093    &lt;title&gt;A typical implementation stores this information
    1094       in a static field&lt;/title&gt;
    1095    &lt;programlisting language="java"&gt;
    1096 private static final About about = new AboutImpl
    1097 (
    1098    "Spot images creator",
    1099    "Converts a full-size scanned image into smaller preview jpg " +
    1100    "images for each individual spot.",
    1101    "2.0",
    1102    "2006, Department of Theoretical Physics, Lund University",
    1103    null,
    1104    "base@thep.lu.se",
    1105    "http://base.thep.lu.se"
    1106 );
    1107  
    1108 public About getAbout()
     1093<programlisting language="xml"><![CDATA[
     1094<example id="net.sf.basedb.core.plugin.Plugin.getMainType">
     1095   <title>A typical implementation just return one of the values</title>
     1096<programlisting language="java">
     1097public Plugin.MainType getMainType()
    11091098{
    1110    return about;
    1111 }
    1112 &lt;/programlisting&gt;
    1113 &lt;/example&gt;
     1099   return Plugin.MainType.OTHER;
     1100}
    11141101</programlisting>
    1115       </example>     
     1102</example>]]></programlisting>
     1103      </example>
    11161104    </sect3>
    11171105    <sect3 id="docbook.usedtags.admonitions">
    … …  
    12251213      <example id="docbook.examples.variablelist">
    12261214        <title>Example how to write a variable list</title>
    1227 <programlisting language="xml">
    1228 &lt;variablelist&gt;
    1229    &lt;varlistentry&gt;
    1230       &lt;term&gt;Term1&lt;/term&gt;
    1231       &lt;listitem&gt;
    1232          &lt;para&gt;
     1215<programlisting language="xml"><![CDATA[
     1216<variablelist>
     1217   <varlistentry>
     1218      <term>Term1</term>
     1219      <listitem>
     1220         <para>
    12331221            Definition/explanation of the term
    1234          &lt;/para&gt;
    1235       &lt;/listitem&gt;
    1236    &lt;/varlistentry&gt;
     1222         </para>
     1223      </listitem>
     1224   </varlistentry>
    12371225   
    1238    &lt;varlistentry&gt;
    1239       &lt;term&gt;Term2&lt;/term&gt;
    1240       &lt;listitem&gt;
    1241          &lt;para&gt;
     1226   <varlistentry>
     1227      <term>Term2</term>
     1228      <listitem>
     1229         <para>
    12421230            Definition/explanation of the term
    1243          &lt;/para&gt;
    1244       &lt;/listitem&gt;
    1245    &lt;/varlistentry&gt;
    1246 &lt;/variablelist&gt;</programlisting>
     1231         </para>
     1232      </listitem>
     1233   </varlistentry>
     1234</variablelist>
     1235]]></programlisting>
     1236     
     1237        <para>
     1238        which is rendered as:
     1239        </para>
     1240       
     1241        <variablelist>
     1242           <varlistentry>
     1243              <term>Term1</term>
     1244              <listitem>
     1245                 <para>
     1246                    Definition/explanation of the term
     1247                 </para>
     1248              </listitem>
     1249           </varlistentry>
     1250           
     1251           <varlistentry>
     1252              <term>Term2</term>
     1253              <listitem>
     1254                 <para>
     1255                    Definition/explanation of the term
     1256                 </para>
     1257              </listitem>
     1258           </varlistentry>
     1259        </variablelist>
     1260
    12471261      </example>
    12481262    </sect3>
    … …  
    12931307      <example id="docbook.examples.links">
    12941308        <title>Links</title>
    1295 <programlisting language="xml">
    1296 &lt;xref linkend="docbook.usedtags.links" /&gt;
    1297 &lt;link linkend="docbook.usedtags.links"&gt;Link to this section&lt;/link&gt;
    1298 &lt;ulink url="http://base.thep.lu.se"&gt;Base2's homepage&lt;/ulink&gt;
     1309<programlisting language="xml"><![CDATA[
     1310<xref linkend="docbook.usedtags.links" />
     1311<link linkend="docbook.usedtags.links">Link to this section</link>
     1312<ulink url="http://base.thep.lu.se">Base2's homepage</ulink>
     1313]]>
    12991314</programlisting>
    13001315        <para>
Note: See TracChangeset for help on using the changeset viewer.