Changeset 3352


Ignore:
Timestamp:
May 21, 2007, 11:42:25 AM (16 years ago)
Author:
Nicklas Nordborg
Message:

Fixes #555

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

Legend:

Unmodified
Added
Removed

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

    r3348 r3352  
    102102    <title>Getting started</title>
    103103    <para>
    104       Before start writing any documentation in BASE2 there are a couple of things, some
     104      Before writing any documentation in BASE2 there are a couple of things, some
    105105      rules and standards, to have in mind.
    106106    </para>
    … …  
    109109      <para>
    110110        The source files of the documentation are located in
    111         <filename class='directory'>base2root/doc/src/docbook</filename>
    112         which is showed in
    113         <xref linkend="write_docbook_doc.figures.fileorganization" />
    114         . The different parts of the documentation are organized into separate folders and
     111        <filename class='directory'>&lt;base-dir&gt;/doc/src/docbook</filename>.
     112        The different parts of the documentation are organized into separate folders and
    115113        each one of the folders contains one index file and one file for each chapter in
    116114        that part. The index file joins the chapters, in current part/folder, together and
    … …  
    124122          <mediaobject>
    125123            <imageobject>
    126               <imagedata contentwidth="15cm" width="15cm" fileref="figures/fileorganization.png" format="PNG"></imagedata>
     124              <imagedata fileref="figures/fileorganization.png" format="PNG" />
    127125            </imageobject>
    128126          </mediaobject>
    … …  
    132130        <title>Create new chapter/file</title>
    133131        <para>
    134           Each file in the documentation, except the index files, represents a chapter.
    135           How to create a new chapter and include it in the text is described in
    136           following items.
     132          Most files in the documentation, except the index files, represents a chapter.
     133          Here is how to create a new chapter and include it in the main documentation:
    137134          <orderedlist numeration='arabic' spacing='compact'>
    138135            <listitem>
    139136              <para>
    140                 Create a new XML-file in the folder of which part the new chapter
     137                Create a new XML-file in the folder for the part where the new chapter
    141138                should be included. Give it a name that is quite similar to the
    142139                new chapter's title but use <userinput>_</userinput> instead of
    143                 blank space and keep it down to one or few words.
     140                blank space and keep it down to one or a few words.
    144141              </para>
    145142            </listitem>
    146143            <listitem>
    147144              <para>
    148                 Begin to write the chapter's body, it should look like
    149                 <xref linkend="write_docbook_doc.examples.chapterbody"/>
     145                Begin to write the chapter's body, here is an example:
    150146                <example id="write_docbook_doc.examples.chapterbody">
    151147                  <title>Example of a chapter</title>
    … …  
    153149&lt;?xml version="1.0" encoding="UTF-8"?&gt;
    154150&lt;!DOCTYPE chapter PUBLIC
    155     "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
    156     "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd"&gt;
     151  "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
     152  "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd"&gt;
    157153
    158154&lt;chapter id="<replaceable>example_chapter</replaceable>"&gt;
    … …  
    181177   &lt;/sect1&gt;
    182178&lt;/chapter&gt;
    183                   </programlisting>
     179</programlisting>
    184180                </example>
    185181              </para>
    … …  
    197193            <listitem>
    198194              <para>
    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
     195                The last step is to get the new chapter included in the documentation. This is done by including the file's name in
    200196                the file
    201197                <filename>index.xml</filename>
    202198                that's located in the current part's folder.
    203                 <xref linkend="write_docbook_doc.examples.include_chapter" />
     199                The following example
    204200                shows how the chapter that was created above is included in the user
    205201                documentation part.
    … …  
    246242      <title>Controlling chunking</title>
    247243      <para>
    248         We have configured docbook to create a new output file for
    249         each new <sgmltag class="starttag">chapter</sgmltag>
    250         and <sgmltag class="starttag">sect1</sgmltag>. In most cases this
     244        We have configured docbook to create a new subdirectory for each
     245        <sgmltag class="starttag">chapter</sgmltag> and a new output file for each
     246        <sgmltag class="starttag">sect1</sgmltag> tag. In most cases this
    251247        gives each page a relatively good size. Not too long and not too short.
    252248        However, if a chapter contains many small <sgmltag class="starttag">sect1</sgmltag>
    253249        sections (for example, <xref linkend="resources"/>), you end up with many
    254250        pages with just a few lines of text on each page. This is not so
    255         good and can be avoided by adding a <sgmltag class="attribute">chunked = "0"</sgmltag>
    256         attribute to the chapter, for example:
     251        good and can be avoided by adding <sgmltag class="attribute">chunked="0"</sgmltag>
     252        as an attribute to the <sgmltag class="starttag">chapter</sgmltag> tag, for example:
    257253      </para>
    258254      <programlisting>
    … …  
    261257      <para>
    262258        This will stop the chunking of <sgmltag class="starttag">sect1</sgmltag>
    263         sections in this chapter. On the other
     259        sections in this chapter.
     260      </para>
     261     
     262      <para>
     263        On the other
    264264        hand, if you have a <sgmltag class="starttag">sect1</sgmltag>
    265265        that contains many long <sgmltag class="starttag">sect2</sgmltag>
    266266        sections you might want to put each <sgmltag class="starttag">sect2</sgmltag>
    267         section in a separate chunk. If you want to do this:
     267        section in a separate chunk:
    268268      </para>
    269269      <programlisting>
    … …  
    280280      </title>
    281281      <para>
    282         Common to all elements is that they have an id attribute that can have an unique value to identify the
    283         element with. Most of the elements that are used inside the BASE2 documentation don't
     282        Common to all elements is that they have an <sgmltag class="attribute">id</sgmltag>
     283        attribute that can be used to identify the
     284        element with. The value must be unique for the entire documentation.
     285        Most of the elements that are used inside the BASE2 documentation don't
    284286        need to have an id if they don't are used in any cross references from other part of
    285287        the text.
    286288      </para>
    287289      <para>
    288         There are however some elements that always should have the
     290        There are some elements that always should have the
    289291        <sgmltag class="attribute">id</sgmltag>
    290292        set. Which these elements are and how the
    291293        <sgmltag class="attribute">id</sgmltag>
    292         should look like for each one of those is described below. All ids should be as
     294        should look like for each one of those is described below. All values should be as
    293295        short as possible and associated to the current element. The
    294296        <sgmltag class="attribute">id</sgmltag>
    … …  
    349351      <title>Mark help texts</title>
    350352      <para>
     353        This documentation is also use to create the help texts that show up
     354        in the web client when clicking on the question mark icons.
    351355        The parts of the text that also should be used as help texts in the web must be
    352356        inside
    … …  
    362366        <sgmltag class="starttag">helptext</sgmltag>
    363367        must be outside the
    364         <sgmltag>para</sgmltag>
     368        <sgmltag class="starttag">para</sgmltag>
    365369        tag but inside a
    366         <sgmltag>sect1</sgmltag>
    367         tag to work properly.
     370        <sgmltag class="starttag">sect</sgmltag>
     371        tag to work properly. Don't put any <sgmltag class="starttag">sect</sgmltag>
     372        tags inside the helptext. This will make the automatic chapter and section
     373        numbering confused.
    368374      </para>
    369375      </note>
    … …  
    416422        <programlisting>
    417423&lt;sect1&gt;
    418   &lt;helptext external_id="<replaceable>helptexts.external.id</replaceable>" title="<replaceable>The title</replaceable>"&gt;
    419     <replaceable>The text that also should be used as a helptext in the program.</replaceable>
    420     &lt;seeother&gt;
    421     &lt;other external_id="<replaceable>other.external.id</replaceable>"&gt;
    422       <replaceable>Related info here...</replaceable>&lt;/other&gt;
    423     &lt;/seeother&gt;
    424   &lt;/helptext&gt;
     424   &lt;helptext external_id="<replaceable>helptexts.external.id</replaceable>" title="<replaceable>The title</replaceable>"&gt;
     425      <replaceable>The text that also should be used as a helptext in the program.</replaceable>
     426      &lt;seeother&gt;
     427         &lt;other external_id="<replaceable>other.external.id</replaceable>"&gt;
     428            <replaceable>Related info here...</replaceable>&lt;/other&gt;
     429      &lt;/seeother&gt;
     430   &lt;/helptext&gt;
    425431&lt;/sect1&gt;
    426         </programlisting>
     432</programlisting>
    427433      </example>
    428434     
    … …  
    465471          </varlistentry>
    466472        </variablelist>
     473       
     474<programlisting>
     475&lt;seeother&gt;
     476  &lt;other external_id="userpreferences.password"&gt;Change password&lt;/other&gt;
     477  &lt;other external_id="userpreferences.other"&gt;Other information&lt;/other&gt;
     478&lt;/seeother&gt;
     479</programlisting>
     480       
     481        <para>
     482          We recommend that you place the links at the end of the
     483          help text section. The links will not show up in the HTML or PDF version.
     484        </para>
    467485      </sect3>
    468486     
    469487      <sect3 id="write_docbook_doc.begin.helptext.import">
    470488      <title>Import help texts into BASE</title>
     489
    471490      <para>
    472491        Import the generated XML-file manually by uploading it from the
    … …  
    498517        <para>
    499518          Those who have checked out the documentation source from repository or got the
    500           source from a distribution package needs to compile it to get the pdf and html
     519          source from a distribution package needs to compile it to get the PDF and HTML
    501520          documentation files. The compilation of the documentation source requires, beside Ant, that the XML-parser
    502           Xsltproc is installed on the local computer. XsltProc and how it is installed, can
    503           be found at
     521          Xsltproc is installed on the local computer. More information about
     522          XsltProc and how it is installed, can be found at
    504523          <ulink url="http://xmlsoft.org/XSLT/index.html"></ulink>.
    505524        </para>
    … …  
    521540          pages/files. The other format is a PDF-file that are most useful for printing
    522541          and distribution. Those two types of output are generated with the ant-target:
    523           <command>ant docbook</command>
    524           . This documentation is also generated with
    525           <command>ant dist</command>
    526           , which will put the output files in the right location for distribution with
     542          <command>ant docbook</command>. This documentation is also generated with
     543          <command>ant dist</command>, which will put the output files in the right location for distribution with
    527544          BASE 2.
    528545        </para>
    … …  
    588605                <sgmltag class="starttag">para</sgmltag>
    589606              </entry>
    590               <entry></entry>
     607              <entry>Used almost everywhere around real text.</entry>
    591608            </row>
    592609            <row>
    … …  
    623640              <entry>Fourth level section</entry>
    624641              <entry>
    625                 <sgmltag class="starttag">sect3</sgmltag>
     642                <sgmltag class="starttag">sect4</sgmltag>
    626643              </entry>
    627644              <entry></entry>
    … …  
    630647              <entry>Fith level section</entry>
    631648              <entry>
    632                 <sgmltag class="starttag">sect3</sgmltag>
     649                <sgmltag class="starttag">sect5</sgmltag>
    633650              </entry>
    634651              <entry></entry>
    … …  
    639656
    640657      <sect3 id="write_docbook_doc.usedtags.text.keywords">
    641         <title>Markup special words and phrases</title>
     658        <title>Code elements</title>
    642659        <para>
    643660          These elements should be used to mark up words and phrases that have a special
    644           meaning, like method names, class names and user inputs just to mention some.
     661          meaning in a coding environment, like method names, class names and
     662          user inputs, etc.
    645663        </para>
    646664        <informaltable frame="none">
    … …  
    662680                  <sgmltag class="starttag">classname</sgmltag>
    663681                </entry>
    664                 <entry></entry>
     682                <entry>The name of a (Java) class.</entry>
    665683              </row>
    666684              <row>
    … …  
    669687                  <sgmltag class="starttag">userinput</sgmltag>
    670688                </entry>
    671                 <entry></entry>
     689                <entry>Text that is entered by a user.</entry>
    672690              </row>
    673691              <row>
    … …  
    676694                  <sgmltag class="starttag">varname</sgmltag>
    677695                </entry>
    678                 <entry></entry>
     696                <entry>The name of a variable in a program.</entry>
    679697              </row>
    680698              <row>
    … …  
    683701                  <sgmltag class="starttag">constant</sgmltag>
    684702                </entry>
    685                 <entry></entry>
     703                <entry>The name of a variable in a program.</entry>
    686704              </row>
    687705              <row>
    … …  
    778796&hellip;
    779797&lt;methodsynopsis language="java"&gt;
    780   &lt;modifier&gt;public&lt;/modifier&gt;
    781   &lt;type&gt;Plugin.MainType&lt;/type&gt;
    782   &lt;methodname&gt;getMainType&lt;/methodname&gt;
    783   &lt;void /&gt;
     798   &lt;modifier&gt;public&lt;/modifier&gt;
     799   &lt;type&gt;Plugin.MainType&lt;/type&gt;
     800   &lt;methodname&gt;getMainType&lt;/methodname&gt;
     801   &lt;void /&gt;
    784802&lt;/methodsynopsis&gt;
    785803&hellip;
    786           </programlisting>
     804</programlisting>
    787805        </example>
    788806        <example id="write_docbook_doc.examples.methodimpl1">
    … …  
    793811&hellip;
    794812&lt;methodsynopsis language="java"&gt;
    795   &lt;modifier&gt;public&lt;/modifier&gt;
    796   &lt;void /&gt;
    797   &lt;methodname&gt;init&lt;/methodname&gt;
    798   &lt;methodparam&gt;
    799     &lt;type&gt;SessionControl&lt;/type&gt;
    800     &lt;parameter&gt;sc&lt;/parameter&gt;
    801   &lt;/methodparam&gt;
    802   &lt;methodparam&gt;
    803     &lt;type&gt;ParameterValues&lt;/type&gt;
    804     &lt;parameter&gt;configuration&lt;/parameter&gt;
    805   &lt;/methodparam&gt;
    806   &lt;methodparam&gt;
    807     &lt;type&gt;ParameterValues&lt;/type&gt;
    808     &lt;parameter&gt;job&lt;/parameter&gt;
    809   &lt;/methodparam&gt;
     813   &lt;modifier&gt;public&lt;/modifier&gt;
     814   &lt;void /&gt;
     815   &lt;methodname&gt;init&lt;/methodname&gt;
     816   &lt;methodparam&gt;
     817      &lt;type&gt;SessionControl&lt;/type&gt;
     818      &lt;parameter&gt;sc&lt;/parameter&gt;
     819   &lt;/methodparam&gt;
     820   &lt;methodparam&gt;
     821      &lt;type&gt;ParameterValues&lt;/type&gt;
     822      &lt;parameter&gt;configuration&lt;/parameter&gt;
     823   &lt;/methodparam&gt;
     824   &lt;methodparam&gt;
     825      &lt;type&gt;ParameterValues&lt;/type&gt;
     826      &lt;parameter&gt;job&lt;/parameter&gt;
     827   &lt;/methodparam&gt;
    810828&lt;/methodsynopsis&gt;
    811829&hellip;
    812           </programlisting>
     830</programlisting>
    813831        </example>
    814832       
    … …  
    897915              <imageobject>
    898916                <imagedata
    899                   scalefit="1"
    900                   width="100%"
    901917                  fileref="figures/menuchoice.png" format="PNG"
    902918                />
    … …  
    910926&hellip;         
    911927&lt;menuchoice&gt;
    912   &lt;guimenu&gt;Administrate&lt;/guimenu&gt;
    913   &lt;guisubmenu&gt;Plugins&lt;/guisubmenu&gt;
    914   &lt;guimenuitem&gt;Types&lt;/guimenuitem&gt;
     928   &lt;guimenu&gt;Administrate&lt;/guimenu&gt;
     929   &lt;guisubmenu&gt;Plugins&lt;/guisubmenu&gt;
     930   &lt;guimenuitem&gt;Types&lt;/guimenuitem&gt;
    915931&lt;/menuchoice&gt;
    916932&hellip;
    … …  
    935951        otherwise the image won't be visible in the generated output files.
    936952      </para>
    937       <warning>
    938         <para>
    939           When using images in docbook you will always have problems with scaling.
    940           Since we are generating output for both HTML and PDF it is even worse.
    941           What we have found to work is this:
    942          
    943           <itemizedlist>
    944           <listitem>
    945             <para>
    946             Scaling in HTML has been disabled. The images will always be the
    947             same size as they actually are. Please, don't make the screenshots
    948             too wide!
    949             </para>
    950           </listitem>
    951          
    952           <listitem>
    953             <para>
    954             For small images, less than the width of the PDF page,
    955             do not specify scaling factors or widths. We have configured PDF to
    956             use 96dpi instead of 72dpi, so the images will appear almost
    957             exactly as they do in the HTML version.
    958             </para>
    959           </listitem>
    960          
    961           <listitem>
    962             <para>
    963             Images that are wider than the PDF page will be clipped. To
    964             prevent this you must add the following attributes to the
    965             <sgmltag class="starttag">imagedata</sgmltag> tag:
    966             <code>scalefit="1" width="100%"</code>
    967             </para>
    968           </listitem>
    969          
    970           <listitem>
    971             <para>
    972             If you still need to scale the image differently in the PDF use
    973             the <sgmltag>width</sgmltag> and <sgmltag>depth</sgmltag>
    974             attributes.
    975             </para>
    976           </listitem>
    977           </itemizedlist>
    978         </para>
    979       </warning>
     953
    980954      <example id="write_docbook_doc.examples.screenshot">
    981955        <title>Screen-shot in the documentation</title>
    … …  
    1001975        </programlisting>
    1002976      </example>
     977      <warning>
     978        <para>
     979          When using images in docbook you will always have problems with image
     980          resolution and scaling. Since we are generating output for both HTML
     981          and PDF it is even worse. What we have found to work is this:
     982         
     983          <itemizedlist>
     984          <listitem>
     985            <para>
     986            The screenshots must be saved without any resolution information
     987            in them, or with the resolution set to 96 dpi. We have configured PDF to
     988            use 96 dpi instead of 72 dpi to make the HTML and PDF output
     989            look as similar as possible.
     990            </para>
     991          </listitem>
     992         
     993          <listitem>
     994            <para>
     995            Scaling in HTML has been disabled. The images will always be the
     996            same size (number of pixels) as they actually are. Please, don't
     997            make the screenshots too wide!
     998            </para>
     999          </listitem>
     1000         
     1001          <listitem>
     1002            <para>
     1003            For small images, less than the width of the PDF page,
     1004            do not specify scaling factors or widths.
     1005            </para>
     1006          </listitem>
     1007         
     1008          <listitem>
     1009            <para>
     1010            Images that are wider than the PDF page will be clipped. To
     1011            prevent this you must add the following attributes to the
     1012            <sgmltag class="starttag">imagedata</sgmltag> tag:
     1013            <code>scalefit="1" width="100%"</code>. This will scale down
     1014            the image so that it fits the available width.
     1015            </para>
     1016          </listitem>
     1017         
     1018          <listitem>
     1019            <para>
     1020            If you still need to scale the image differently in the PDF use
     1021            the <sgmltag>width</sgmltag> and <sgmltag>depth</sgmltag>
     1022            attributes.
     1023            </para>
     1024          </listitem>
     1025          </itemizedlist>
     1026        </para>
     1027      </warning>
    10031028    </sect2>
    10041029    <sect2 id="write_docbook_doc.usedtags.examples">
    … …  
    10101035      </para>
    10111036      <warning>
    1012         <para>
    1013           More then 80 characters(including indention) in a row of program
    1014           listings or other verbatim elements will risk to put the end of the row outside
    1015           the text area.
     1037        <title>Use spaces instead of tabs for indentation</title>
     1038        <para>
     1039          More then 80 characters in a row of program listings or
     1040          other verbatim elements will risk to put the end of the
     1041          row outside the text area. A tab is usually displayed as 8 spaces
     1042          which will use up too much space.
    10161043        </para>
    10171044      </warning>
    … …  
    10241051        </para>
    10251052        <programlisting>
    1026   &hellip;
    1027   &lt;example id="net.sf.basedb.core.plugin.Plugin.getAbout"&gt;
    1028      &lt;title&gt;A typical implementation stores this information in a static field&lt;/title&gt;
    1029      &lt;programlisting&gt;
     1053&hellip;
     1054&lt;example id="net.sf.basedb.core.plugin.Plugin.getAbout"&gt;
     1055   &lt;title&gt;A typical implementation stores this information
     1056      in a static field&lt;/title&gt;
     1057   &lt;programlisting&gt;
    10301058private static final About about = new AboutImpl
    10311059(
    … …  
    10441072   return about;
    10451073}
    1046      &lt;/programlisting&gt;
    1047   &lt;/example&gt;
    1048   &hellip;
    1049         </programlisting>
     1074   &lt;/programlisting&gt;
     1075&lt;/example&gt;
     1076&hellip;
     1077</programlisting>
    10501078      </example>     
    10511079    </sect2>
    … …  
    11811209   &lt;/varlistentry&gt;
    11821210&lt;/variablelist&gt;
    1183         </programlisting>
     1211</programlisting>
    11841212      </example>
    11851213    </sect2>
    … …  
    12361264&lt;ulink url="http://base.thep.lu.se"&gt;Base2's homepage&lt;/ulink&gt;
    12371265&hellip;
    1238         </programlisting>
     1266</programlisting>
    12391267        <para>
    12401268          The first element will autogenerate the linked section's/chapter's title as a
Note: See TracChangeset for help on using the changeset viewer.