<?xml version="1.0" encoding="UTF-8"?><!-- -*- indent-tabs-mode: nil -*- -->
<?db.chunk.max_depth 2?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article id="index" lang="en">
  <articleinfo>
    <title>GNOME Documentation XSLT Manual</title>
    
    <abstract role="description">
      <para>The GNOME Documentation XSLT stylesheets were created to provide fast DocBook to HTML
      conversion for real-time document viewing in GNOME's help browser, <application>Yelp.</application></para>
    </abstract>

    <copyright>
      <year>2004</year>

      <holder>Shaun McCance</holder>
    </copyright>

    <publisher>
      <publishername>GNOME Documentation Project</publishername>
    </publisher>

    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />

    <authorgroup>
      <author role="maintainer">
        <firstname>Shaun</firstname>

        <surname>McCance</surname>

        <affiliation>
          <orgname>GNOME Documentation Project</orgname>
        </affiliation>

        <email>shaunm@gnome.org</email>
      </author>

      <author>
        <firstname>Brent</firstname>

        <surname>Smith</surname>

        <affiliation>
          <orgname>GNOME Documentation Project</orgname>
        </affiliation>

        <email>gnome@nextreality.net</email>
      </author>
    </authorgroup>

    <revhistory>
      <revision>
        <revnumber>0.1</revnumber>

        <date>2004-03-31</date>
      </revision>

      <revision>
        <revnumber>0.2</revnumber>

        <date>2006-02-11</date>
      </revision>
    </revhistory>
  </articleinfo>

  <section id="intro">
    <title>Introduction</title>

    <para>The GNOME XSLT Stylesheets are used to generate HTML from DocBook
    files.</para>

    <para>Some of the goals of these stylesheets are:<itemizedlist>
        <listitem>
          <para>To provide real-time translation of DocBook into HTML. The
          GNOME Help Browser, <application>Yelp</application>, uses these
          stylesheets to format help documents.</para>
        </listitem>

        <listitem>
          <para>To provide a customized look and feel for GNOME's
          documentation.</para>
        </listitem>

        <listitem>
          <para>To provide translation support for GNOME documentation.</para>
        </listitem>
      </itemizedlist></para>
  </section>

  <section id="using">
    <title>Using the Stylesheets</title>

    <para>To use the stylesheets you should be familiar with the
    <application>xsltproc</application> application. The first argument is the
    location of the <filename>db2html.xsl</filename> stylesheet. The second
    argument is the top-level docbook file for which to generate the
    HTML.</para>

    <example id="example-db2html">
      <title>Generating HTML from a DocBook file</title>

      <para><screen><prompt>$</prompt> xsltproc /usr/share/xml/gnome/xslt/docbook/html/db2html.xsl &lt;docbook file&gt;</screen></para>
    </example>

    <para>For more information on <application>xsltproc</application> and the
    <application>libxslt</application> libraries, see <ulink
    url="http://www.xmlsoft.org/">http://xmlsoft.org/</ulink>.</para>

    <note>
      <title>XInclude Processing</title>

      <para>If you make use of <ulink
      url="http://www.w3.org/TR/xinclude/">XInclude</ulink> to include other
      files in your document, then you must use the 
      <parameter>--xinclude</parameter> parameter to generate the complete
      DocBook file before processing it with the
      <filename>db2html.xsl</filename> stylesheet(s).</para>
    </note>
  </section>

  <section id="parameters">
    <title>Specifying Parameters</title>

    <para>There are a number of parameters available in the stylesheets which
    you can set to customize the generated html. An exhaustive list is
    available in the following sections, but we will go over a few of the more
    commonly used ones in this section.</para>

    <para>To specify a parameter to the stylesheets, use the
    <parameter>--stringparam</parameter> option of the
    <application>xsltproc</application> application.</para>

    <variablelist>
      <varlistentry>
        <term>db.chunk.chunk_top</term>

        <listitem>
          <para>Set this parameter to <literal>1</literal> if you want the
          stylesheets to chunk<footnote>
              <para>Chunking refers to creating a separate output file for an
              element. For example, if there are three
              <literal>&lt;sect1&gt;</literal> elements within a document,
              (with no subsections) then there will be three files generated
              for each element. Incidentally, the name of the files will be
              the same as the element's <literal>id</literal>
              attribute.</para>
            </footnote> the top level element
          (<literal>&lt;article&gt;</literal> or
          <literal>&lt;book&gt;</literal>) into a file called
          <filename>index.xhtml</filename>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>db.chunk.max_depth</term>

        <listitem>
          <para>Specifies the maximum depth of chunked elements specified in
          <parameter>db.chunk.chunks</parameter> parameter.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>db.chunk.extension</term>

        <listitem>
          <para>Set this parameter to <literal>the extension</literal> you
          would like for the chunked output files.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <example id="example-parameters">
      <title>Example of specifying stylesheet parameters</title>

      <para><screen><prompt>$</prompt> xsltproc \
   --stringparam db.chunk.chunk_top 1        \
   --stringparam db.chunk.max_depth 1        \
   --stringparam db.chunk.extension '.html'  \
   /usr/share/xml/gnome/xslt/docbook/html/db2html.xsl \
   &lt;path to docbook file&gt;</screen><xref
      linkend="example-parameters" /> will chunk the top level element, chunk
      to a maximum depth of 1 and chunk the title page.</para>
    </example>
  </section>

  <section id="limitations">
    <title>Limitations</title>

    <para>Currently, the stylesheets require that there be an
    <literal>id</literal> attribute on each chunked element.</para>
  </section>

  <include href="translating.xml" xmlns="http://www.w3.org/2001/XInclude"/>

  <section id="reference">
    <title>Stylesheet Reference</title>

    <!--BEGIN-->
    <include href="db-chunk.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db-common.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db-label.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db-title.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db-xref.xml" xmlns="http://www.w3.org/2001/XInclude"/>

    <include href="db2html.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2xhtml.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-autotoc.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-bibliography.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-block.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-callout.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-classsynopsis.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-cmdsynopsis.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-css.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-division.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-ebnf.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-footnote.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-funcsynopsis.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-index.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-info.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-inline.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-l10n.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-list.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-media.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-qanda.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-refentry.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-table.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-title.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="db2html-xref.xml" xmlns="http://www.w3.org/2001/XInclude"/>

    <include href="db2omf.xml" xmlns="http://www.w3.org/2001/XInclude"/>

    <include href="theme.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="gettext.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <include href="l10n-numbers.xml" xmlns="http://www.w3.org/2001/XInclude"/>
    <!--END-->
  </section>

</article>
