Changeset 3268


Ignore:
Timestamp:
Apr 24, 2007, 5:37:11 PM (16 years ago)
Author:
Martin Svensson
Message:

References #555. Started to list the elements that are used in the documentation source.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r3265 r3268  
    5454    </para>
    5555    <variablelist>
    56       <title>Parts of the documentation</title>
    5756      <varlistentry>
    5857        <term>Overview documentation</term>
    … …  
    218217      <title>
    219218        The
    220         <varname>id</varname>
     219        <sgmltag class="attribute">id</sgmltag>
    221220        attribute
    222221      </title>
    … …  
    229228      <para>
    230229        There are however some elements that always should have an
    231         <varname>id</varname>
     230        <sgmltag class="attribute">id</sgmltag>
    232231        . Which these elements are and how the
    233         <varname>id</varname>
     232        <sgmltag class="attribute">id</sgmltag>
    234233        should look like for each one of those is described below. All ids should be as
    235234        short as possible and associated to the current element. The
    236         <varname>id</varname>
     235        <sgmltag class="attribute">id</sgmltag>
    237236        shouldn't consist of other characters then lowercase a-z,
    238237        <userinput>_</userinput>
    … …  
    246245              <para>
    247246                The chapter should have an
    248                 <varname>id</varname>
     247                <sgmltag class="attribute">id</sgmltag>
    249248                that is identical or almost identical to the chapter's title.
    250249                <synopsis>chapter_title</synopsis>
    … …  
    269268              <para>
    270269                The naming of an example's
    271                 <varname>id</varname>
     270                <sgmltag class="attribute">id</sgmltag>
    272271                is a bit different compare to the chapter's and section's id. It
    273272                should begin with the chapter's id followed by
    … …  
    283282              <para>
    284283                The figure's
    285                 <varname>id</varname>
     284                <sgmltag class="attribute">id</sgmltag>
    286285                should have the following layout
    287286                <synopsis>chapter_title.figures.figure_name</synopsis>
    … …  
    317316          <varlistentry>
    318317            <term>
    319               <varname>external_id</varname>
     318              <sgmltag class="attribute">id</sgmltag>
    320319            </term>
    321320            <listitem>
    … …  
    330329          <varlistentry>
    331330            <term>
    332               <varname>title</varname>
     331              <sgmltag class="attribute">id</sgmltag>
    333332            </term>
    334333            <listitem>
    … …  
    375374    <title>Elements to use</title>
    376375    <para>Which docbook tags are used in the documentation and when to use what......</para>
     376    <para>
     377      There will not be any detailed explanation of the tags, instead the reader is
     378      recommended to get more information from
     379      <ulink url="http://www.docbook.org/tdg/en/html/docbook.html">
     380        docbook's documentation
     381      </ulink>
     382      or other references.
     383    </para>
    377384    <sect2 id="write_docbook_doc.usedtags.text">
    378385      <title>Text</title>
    379386      <para>
    380         Here is described which tag to use for different kinds of format and text layout.
    381         There will not be any detailed explanation of the tags, the reader is recommended to
    382         get more information from
    383         <ulink url="http://www.docbook.org/tdg/en/html/docbook.html">
    384           docbook's documentation
    385         </ulink>
    386         or other references instead.
    387       </para>
    388      
     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>
     464
    389465      <sect3 id="write_docbook_doc.usedtags.text.keywords">
    390         <title>Markup special words</title>
    391         <para></para>
     466        <title>Markup special words and phrases</title>
     467        <para>
     468          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.
     471        </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>
     482      </sect3>
     483      <sect3 id="write_docbook_doc.usedtags.text.gui">
     484        <title>Gui elements</title>
     485        <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.
     488        </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>
    392497      </sect3>
    393498    </sect2>
    394499    <sect2 id="write_docbook_doc.usedtags.images">
    395500      <title>Images and figures</title>
    396       <para></para>
     501      <para>
     502        Images and figures are normally implemented like the following example. The image-file must be located in
     503        <filename class="directory">doc/src/docbook/figures</filename>
     504        ,otherwise the image won't be visible in the generated output files.
     505      </para>
    397506    </sect2>
    398507    <sect2 id="write_docbook_doc.usedtags.examples">
    399       <title>Examples</title>
    400       <para></para>
     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>
     516        <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;       
     524        </programlisting>
     525      </example>
    401526    </sect2>
    402527    <sect2 id="write_docbook_doc.usedtags.admonitions">
    … …  
    409534          </term>
    410535          <listitem>
    411             <para></para>
     536            <para>Define a notification for the reader.</para>
    412537          </listitem>
    413538        </varlistentry>
    … …  
    417542          </term>
    418543          <listitem>
    419             <para></para>
     544            <para>Define the text as a warning for the reader look up with.</para>
    420545          </listitem>
    421546        </varlistentry>
    … …  
    425550          </term>
    426551          <listitem>
    427             <para></para>
     552            <para>Define something that can be useful for the reader to know.</para>
    428553          </listitem>
    429554        </varlistentry>
    … …  
    433558          </term>
    434559          <listitem>
    435             <para></para>
     560            <para>
     561              Define a text to be important, something the reader should pay certain
     562              attention to.
     563            </para>
    436564          </listitem>
    437565        </varlistentry>
    … …  
    441569          </term>
    442570          <listitem>
    443             <para></para>
     571            <para>
     572              Define a text about something the reader should be cautious with.
     573            </para>
    444574          </listitem>
    445575        </varlistentry>
    … …  
    448578    <sect2 id="write_docbook_doc.usedtags.lists">
    449579      <title>Lists</title>
    450       <para></para>
     580      <para>
     581        Following items can be used to define different kind of lists in the documentation.
     582        Some common elements for the lists are also described here.
     583      </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>
    451628    </sect2>
    452629  </sect1>
Note: See TracChangeset for help on using the changeset viewer.