Created some documentation for the xslt stylesheets

2006-02-18  Brent Smith  <gnome@nextreality.net>
        * doc/xslt/C/gnome-doc-xslt.xml:
        Created some documentation for the xslt stylesheets

2 files changed, 168 insertions, 9 deletions

diff --git a/ChangeLog b/ChangeLog
index b790f0b..4d6a528 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,10 @@
 2006-02-18  Brent Smith  <gnome@nextreality.net>
 
+	* doc/xslt/C/gnome-doc-xslt.xml:
+	Created some documentation for the xslt stylesheets
+
+2006-02-18  Brent Smith  <gnome@nextreality.net>
+
 	* xslt/docbook/common/db-chunk.xsl:
 	- fix an expression in db.chunk.info_chunk param that didn't make
 	sense anymore.
diff --git a/doc/xslt/C/gnome-doc-xslt.xml b/doc/xslt/C/gnome-doc-xslt.xml
index 2f60c0f..a61f478 100644
--- a/doc/xslt/C/gnome-doc-xslt.xml
+++ b/doc/xslt/C/gnome-doc-xslt.xml
@@ -1,41 +1,195 @@
-<?xml version='1.0' encoding='utf-8'?><!-- -*- indent-tabs-mode: nil -*- -->
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- -*- indent-tabs-mode: nil -*- -->
 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
-]>
-
+"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"/>
+
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
+
     <authorgroup>
       <author role="maintainer">
         <firstname>Shaun</firstname>
+
         <surname>McCance</surname>
-	<affiliation>
+
+        <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>shaunm@gnome.org</email>
+        </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>Foo</para>
+    <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="db2html.xml" xmlns="http://www.w3.org/2001/XInclude"/>