Changeset 3263


Ignore:
Timestamp:
Apr 23, 2007, 2:38:11 PM (14 years ago)
Author:
Martin Svensson
Message:

References #555. Updated the documentation about adding helptext-tags and how to generated the output-files

File:
1 edited

Legend:

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

    r3246 r3263  
    113113        which is showed in
    114114        <xref linkend="write_docbook_doc.figures.fileorganization" />.
    115         The different parts of the documentation are organized into separate folders and in each one
    116         of those folders contain one index file and one file for each chapter for the part. The
    117         index file joins the chapters, in current part/folder, and doesn't really contain
    118         any text. The documentation root directory also contains an <filename class='file'>index.xml</filename> file which joins the
    119         index files from the different parts.
     115        The different parts of the documentation are organized into separate folders and each one
     116        of the folders contains one index file and one file for each chapter in that part. The
     117        index file joins the chapters, in current part/folder, together and doesn't really contain
     118        any text. The documentation root directory also contains an <filename class='headerfile'>index.xml</filename> file which joins the
     119        index files from the different parts together.
    120120      </para>     
    121121      <figure id="write_docbook_doc.figures.fileorganization">
     
    216216    </sect2>
    217217    <sect2 id="write_docbook_doc.begin.id">
    218       <title>The <varname>id</varname> attribute</title>
    219       <para>
    220         All elements has an id attribute that can have an unique value to
    221         identify the element with. Most of the elements that are used inside
    222         BASE2 documentation don't need to have an id if they don't are used in
    223         any cross references from other part of the text.
    224       </para>
    225       <para>
    226         But there are some elements that always should have an <varname>id</varname>.
    227         Which these elements are and how the <varname>id</varname> should look like for
    228         each one of those is described below.
     218      <title>
     219        The
     220        <varname>id</varname>
     221        attribute
     222      </title>
     223      <para>
     224        All elements has an id attribute that can have an unique value to identify the
     225        element with. Most of the elements that are used inside BASE2 documentation don't
     226        need to have an id if they don't are used in any cross references from other part of
     227        the text.
     228      </para>
     229      <para>
     230        There are however some elements that always should have an
     231        <varname>id</varname>
     232        . Which these elements are and how the
     233        <varname>id</varname>
     234        should look like for each one of those is described below. All ids should be as
     235        short as possible and associated to the current element. The
     236        <varname>id</varname>
     237        shouldn't consist of other characters then lowercase a-z,
     238        <userinput>_</userinput>
     239        instead of blank spaces and
     240        <userinput>.</userinput>
     241        to symbolize the different levels in the document.
    229242        <variablelist>
    230           <title>
    231             Where <varname>id</varname> is required
    232           </title>
    233           <para>
    234             All ids should be as short as possible and associated to the current element.
    235             The
    236             <varname>id</varname>
    237             shouldn't consist of other characters then lowercase a-z,
    238             <userinput>_</userinput>
    239             instead of blank spaces and
    240             <userinput>.</userinput>
    241             to symbolize different levels in the document.
    242           </para>
    243243          <varlistentry>
    244244            <term>chapter</term>
    245245            <listitem>
    246246              <para>
    247                 The chapter should have an <varname>id</varname> that is identical
    248                 or almost identical to the chapter's title.
     247                The chapter should have an
     248                <varname>id</varname>
     249                that is identical or almost identical to the chapter's title.
    249250                <synopsis>chapter_title</synopsis>
    250251              </para>
     
    255256            <listitem>
    256257              <para>
    257                 The creation of a section's id is done by using the upper level's id and
    258                 add the section's title or a part of the title. For &lt;sect2&gt; it should
    259                 be like <synopsis>chapter_title.sect1_title.sect2_title</synopsis>.
     258                The creation of a section's id is done by using the upper level's id
     259                and add the section's title or a part of the title. For
     260                &lt;sect2&gt; it should be like
     261                <synopsis>chapter_title.sect1_title.sect2_title</synopsis>
     262                .
    260263              </para>
    261264            </listitem>
     
    265268            <listitem>
    266269              <para>
    267                 The naming of an example's <varname>id</varname> is a bit different
    268                 compare to the chapter's and section's id. It should begin with the chapter's id
    269                 followed by <userinput>examples</userinput> and the caption of the
    270                 example.
     270                The naming of an example's
     271                <varname>id</varname>
     272                is a bit different compare to the chapter's and section's id. It
     273                should begin with the chapter's id followed by
     274                <userinput>examples</userinput>
     275                and the caption of the example.
    271276                <synopsis>chapter_title.examples.example_caption</synopsis>
    272277              </para>
     
    277282            <listitem>
    278283              <para>
    279                 The figure's <varname>id</varname> should have the following layout
     284                The figure's
     285                <varname>id</varname>
     286                should have the following layout
    280287                <synopsis>chapter_title.figures.figure_name</synopsis>
    281288              </para>
    282289            </listitem>
    283           </varlistentry>     
     290          </varlistentry>
    284291        </variablelist>
    285292      </para>
    286293    </sect2>
    287294    <sect2 id="write_docbook_doc.begin.helptext">
    288       <title>Tag help texts</title>
    289       <para>
    290         It is possible, in the document source, to tag those parts of text that also should be
    291         used as help texts in the web client of BASE2. When running a specific ant-target the text
    292         enclosed by help text tags are exported to a separate XML-file which then can be imported into
    293          BASE2 with the use of the text import plugin. How to generate the import file
    294          is described in
    295          <xref linkend="write_docbook_doc.begin.generate"/>
    296       </para>
    297       <para>
    298         The help text tag must be outside the <sgmltag>para</sgmltag> tag but inside
    299         a <sgmltag>sect1</sgmltag> to work properly. Each tag requires then two
    300         different attributes
     295      <title>Mark help texts</title>
     296      <para>
     297        It is possible to tag those parts of the text in documentation source that also
     298        should be used as help texts in the web client.The tagged parts will be
     299        exported to a XML-file at the same time as the html-documentation is generated.This
     300        generated XML-file is compatible with the help text importer in BASE2 and will be
     301        imported when running the update script or installation script.
     302      </para>
     303      <note>
     304      <para>
     305        The
     306        <sgmltag class="starttag">helptext</sgmltag>
     307        must be outside the
     308        <sgmltag>para</sgmltag>
     309        tag but inside a
     310        <sgmltag>sect1</sgmltag>
     311        tag to work properly.
     312      </para>
     313      </note>
     314      <para>
     315        Each tag requires two different attributes
    301316        <variablelist>
    302317          <varlistentry>
     
    306321            <listitem>
    307322              <para>
    308                 is used to identify help text in the web client.
    309                 BASE2's web client already has several help texts that are defined,
    310                 it could therefore be a good idea to look in program to see if
     323                is used to identify and find a help text in the web client. BASE2's
     324                web client already has a several of help texts that are defined, it
     325                could therefore be a good idea to have a look in the program to see if
    311326                there already is an external id to use.
    312327              </para>
     
    319334            <listitem>
    320335              <para>
    321                 is directly connected to the name/title property for a help text item in
    322                 BASE2.
     336                is directly connected to the name/title property for a help text
     337                item in BASE2.
    323338              </para>
    324339            </listitem>
     
    326341        </variablelist>
    327342      </para>
    328      
     343      <example id="write_docbook_doc.examples.helptexttag">
     344        <title>How to use the help text tag</title>
     345        <programlisting>
     346&lt;sect1&gt;
     347  &lt;helptext external_id="<replaceable>helptexts.external.id</replaceable>" title="<replaceable>The title</replaceable>"&gt;
     348    <replaceable>The text that should also be used as a helptext in the program</replaceable>
     349  &lt;/helptext&gt;
     350&lt;/sect1&gt;
     351        </programlisting>
     352      </example>
     353      <para>
     354        Import the generated XML-file manually by uploading it from the
     355        <filename class="directory">data</filename>
     356        directory to the BASE-server's file system and then use the help text importer
     357        plugin to import the help text items from that file.
     358      </para>
    329359    </sect2>
    330360    <sect2 id="write_docbook_doc.begin.generate">
    331361      <title>Generate the document</title>
    332362      <para>
    333         There are two different types of format that can be generated from the documentation
    334         source. The format to view the documentation online will be the one
    335         with chunked HTML pages where each chapter and section of first level are on
    336         separate pages. The other format is a PDF-file that are most useful for printing
    337         and distribution. Those two types of output are generated with different ant
    338         targets which are described below.
    339       </para>
    340       <para>
    341        
    342       </para>
    343       <variablelist>
    344         <title>Document types</title>
    345         <varlistentry>
    346           <term>Chunked HTML pages</term>
    347           <listitem>
    348             <para>
    349               Run <command>ant docbook</command> to generate the documentation in
    350               this format.
    351             </para>           
    352             <para>
    353               The generated files will be put in
    354               <filename class='directory'>base2root/doc/docbook/</filename>
    355               and the main file is
    356               <filename class='headerfile'>index.html</filename> which contains a
    357               table of content over the rest of the document and some navigation links.
    358             </para>
    359           </listitem>
    360         </varlistentry>
    361         <varlistentry>
    362           <term>PDF-file</term>
    363           <listitem>
    364             <para>
    365               This is not completely implemented yet, cf. <ulink url="http://base.thep.lu.se/ticket/521">http://base.thep.lu.se/ticket/521</ulink>
    366             </para>
    367             <para>
    368                For now the pdf document is generated  at the same time as the html-pages.
    369                The file, <filename class='headerfile'>base_{baseversion}.pdf</filename>
    370                can  be found in
    371               <filename class="directory">base2root/doc/docbook/</filename>, just
    372               like the main html-file.
    373             </para>
    374           </listitem>
    375         </varlistentry>
    376         <varlistentry>
    377           <term>Help text import file for BASE2</term>
    378           <listitem>
    379             <para>
    380               The import file with help texts,
    381               <filename class='headerfile'>helptext_docbook.xml</filename>,
    382                is also generated with an ant target and can be found in
    383               <filename class='directory'>base2root/build/docbook</filename>.
    384               Use <command>ant helptext</command> to generate this file.
    385             </para>
    386           </listitem>
    387         </varlistentry>
    388       </variablelist>
     363        There are two different types of format that is generated from the documentation
     364        source. The format to view the documentation online will be the one with chunked
     365        HTML pages where each chapter and section of first level are on separate
     366        pages/files. The other format is a PDF-file that are most useful for printing and
     367        distribution. Those two types of output are generated with the ant-target:
     368        <userinput>ant docbook</userinput>
     369        .
     370      </para>
    389371    </sect2>
    390372  </sect1>
Note: See TracChangeset for help on using the changeset viewer.