home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / share / gnome / help / gnome-doc-xslt / C / gnome-doc-xslt.xml < prev    next >
Encoding:
Extensible Markup Language  |  2006-08-07  |  6.9 KB  |  206 lines
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!-- -*- indent-tabs-mode: nil -*- -->
  3. <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
  4. "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
  5. <article id="index" lang="en">
  6.   <articleinfo>
  7.     <title>GNOME Documentation XSLT Manual</title>
  8.     
  9.     <abstract role="description">
  10.       <para>The GNOME Documentation XSLT stylesheets were created to provide fast DocBook to HTML
  11.       conversion for real-time document viewing in GNOME's help browser, <application>Yelp.</application></para>
  12.     </abstract>
  13.  
  14.     <copyright>
  15.       <year>2004</year>
  16.  
  17.       <holder>Shaun McCance</holder>
  18.     </copyright>
  19.  
  20.     <publisher>
  21.       <publishername>GNOME Documentation Project</publishername>
  22.     </publisher>
  23.  
  24.     <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
  25.  
  26.     <authorgroup>
  27.       <author role="maintainer">
  28.         <firstname>Shaun</firstname>
  29.  
  30.         <surname>McCance</surname>
  31.  
  32.         <affiliation>
  33.           <orgname>GNOME Documentation Project</orgname>
  34.         </affiliation>
  35.  
  36.         <email>shaunm@gnome.org</email>
  37.       </author>
  38.  
  39.       <author>
  40.         <firstname>Brent</firstname>
  41.  
  42.         <surname>Smith</surname>
  43.  
  44.         <affiliation>
  45.           <orgname>GNOME Documentation Project</orgname>
  46.         </affiliation>
  47.  
  48.         <email>gnome@nextreality.net</email>
  49.       </author>
  50.     </authorgroup>
  51.  
  52.     <revhistory>
  53.       <revision>
  54.         <revnumber>0.1</revnumber>
  55.  
  56.         <date>2004-03-31</date>
  57.       </revision>
  58.  
  59.       <revision>
  60.         <revnumber>0.2</revnumber>
  61.  
  62.         <date>2006-02-11</date>
  63.       </revision>
  64.     </revhistory>
  65.   </articleinfo>
  66.  
  67.   <section id="intro">
  68.     <title>Introduction</title>
  69.  
  70.     <para>The GNOME XSLT Stylesheets are used to generate HTML from DocBook
  71.     files.</para>
  72.  
  73.     <para>Some of the goals of these stylesheets are:<itemizedlist>
  74.         <listitem>
  75.           <para>To provide real-time translation of DocBook into HTML. The
  76.           GNOME Help Browser, <application>Yelp</application>, uses these
  77.           stylesheets to format help documents.</para>
  78.         </listitem>
  79.  
  80.         <listitem>
  81.           <para>To provide a customized look and feel for GNOME's
  82.           documentation.</para>
  83.         </listitem>
  84.  
  85.         <listitem>
  86.           <para>To provide translation support for GNOME documentation.</para>
  87.         </listitem>
  88.       </itemizedlist></para>
  89.   </section>
  90.  
  91.   <section id="using">
  92.     <title>Using the Stylesheets</title>
  93.  
  94.     <para>To use the stylesheets you should be familiar with the
  95.     <application>xsltproc</application> application. The first argument is the
  96.     location of the <filename>db2html.xsl</filename> stylesheet. The second
  97.     argument is the top-level docbook file for which to generate the
  98.     HTML.</para>
  99.  
  100.     <example id="example-db2html">
  101.       <title>Generating HTML from a DocBook file</title>
  102.  
  103.       <para><screen><prompt>$</prompt> xsltproc /usr/share/xml/gnome/xslt/docbook/html/db2html.xsl <docbook file></screen></para>
  104.     </example>
  105.  
  106.     <para>For more information on <application>xsltproc</application> and the
  107.     <application>libxslt</application> libraries, see <ulink
  108.     url="http://www.xmlsoft.org/">http://xmlsoft.org/</ulink>.</para>
  109.  
  110.     <note>
  111.       <title>XInclude Processing</title>
  112.  
  113.       <para>If you make use of <ulink
  114.       url="http://www.w3.org/TR/xinclude/">XInclude</ulink> to include other
  115.       files in your document, then you must use the 
  116.       <parameter>--xinclude</parameter> parameter to generate the complete
  117.       DocBook file before processing it with the
  118.       <filename>db2html.xsl</filename> stylesheet(s).</para>
  119.     </note>
  120.   </section>
  121.  
  122.   <section id="parameters">
  123.     <title>Specifying Parameters</title>
  124.  
  125.     <para>There are a number of parameters available in the stylesheets which
  126.     you can set to customize the generated html. An exhaustive list is
  127.     available in the following sections, but we will go over a few of the more
  128.     commonly used ones in this section.</para>
  129.  
  130.     <para>To specify a parameter to the stylesheets, use the
  131.     <parameter>--stringparam</parameter> option of the
  132.     <application>xsltproc</application> application.</para>
  133.  
  134.     <variablelist>
  135.       <varlistentry>
  136.         <term>db.chunk.chunk_top</term>
  137.  
  138.         <listitem>
  139.           <para>Set this parameter to <literal>1</literal> if you want the
  140.           stylesheets to chunk<footnote>
  141.               <para>Chunking refers to creating a separate output file for an
  142.               element. For example, if there are three
  143.               <literal><sect1></literal> elements within a document,
  144.               (with no subsections) then there will be three files generated
  145.               for each element. Incidentally, the name of the files will be
  146.               the same as the element's <literal>id</literal>
  147.               attribute.</para>
  148.             </footnote> the top level element
  149.           (<literal><article></literal> or
  150.           <literal><book></literal>) into a file called
  151.           <filename>index.xhtml</filename>.</para>
  152.         </listitem>
  153.       </varlistentry>
  154.  
  155.       <varlistentry>
  156.         <term>db.chunk.max_depth</term>
  157.  
  158.         <listitem>
  159.           <para>Specifies the maximum depth of chunked elements specified in
  160.           <parameter>db.chunk.chunks</parameter> parameter.</para>
  161.         </listitem>
  162.       </varlistentry>
  163.  
  164.       <varlistentry>
  165.         <term>db.chunk.extension</term>
  166.  
  167.         <listitem>
  168.           <para>Set this parameter to <literal>the extension</literal> you
  169.           would like for the chunked output files.</para>
  170.         </listitem>
  171.       </varlistentry>
  172.     </variablelist>
  173.  
  174.     <example id="example-parameters">
  175.       <title>Example of specifying stylesheet parameters</title>
  176.  
  177.       <para><screen><prompt>$</prompt> xsltproc \
  178.    --stringparam db.chunk.chunk_top 1        \
  179.    --stringparam db.chunk.max_depth 1        \
  180.    --stringparam db.chunk.extension '.html'  \
  181.    /usr/share/xml/gnome/xslt/docbook/html/db2html.xsl \
  182.    <path to docbook file></screen><xref
  183.       linkend="example-parameters" /> will chunk the top level element, chunk
  184.       to a maximum depth of 1 and chunk the title page.</para>
  185.     </example>
  186.   </section>
  187.  
  188.   <section id="limitations">
  189.     <title>Limitations</title>
  190.  
  191.     <para>Currently, the stylesheets require that there be an
  192.     <literal>id</literal> attribute on each chunked element.</para>
  193.   </section>
  194.  
  195.   <include href="db2html.xml" xmlns="http://www.w3.org/2001/XInclude"/>
  196.   <include href="db-chunk.xml" xmlns="http://www.w3.org/2001/XInclude"/>
  197.   <include href="db-common.xml" xmlns="http://www.w3.org/2001/XInclude"/>
  198.   <include href="db-label.xml" xmlns="http://www.w3.org/2001/XInclude"/>
  199.   <include href="db-title.xml" xmlns="http://www.w3.org/2001/XInclude"/>
  200.   <include href="db-xref.xml" xmlns="http://www.w3.org/2001/XInclude"/>
  201.   <include href="db2omf.xml" xmlns="http://www.w3.org/2001/XInclude"/>
  202.   <include href="gettext.xml" xmlns="http://www.w3.org/2001/XInclude"/>
  203.   <include href="translating.xml" xmlns="http://www.w3.org/2001/XInclude"/>
  204.  
  205. </article>
  206.