adding doc/xsltproc.xml - user manual for xsltproc

Mon Aug 27 08:21:47 MDT 2001 John Fleck <jfleck@inkstain.net>

	* adding doc/xsltproc.xml - user manual for xsltproc

1 files changed, 233 insertions, 0 deletions

diff --git a/doc/xsltproc.xml b/doc/xsltproc.xml
new file mode 100644
index 00000000..21e3fb23
--- /dev/null
+++ b/doc/xsltproc.xml
@@ -0,0 +1,233 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+
+<refentry>
+  <refentryinfo>
+    <title>xsltproc Manual</title>
+    <copyright>
+      <year>2001</year>
+    </copyright>
+    <author>
+      <firstname>John</firstname>
+      <surname>Fleck</surname>
+    </author>
+    <address><email>jfleck@inkstain.net</email></address>
+    <legalnotice id="legalnotice">
+      <para>Permission is granted to copy, distribute and/or modify this document
+	under the terms of the <ulink type="help" url="gnome-help:fdl"><citetitle>GNU Free Documentation
+	    License</citetitle></ulink>, Version 1.1 or any later version 
+	published by the Free Software Foundation with no Invariant Sections, 
+	no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+	can be found <ulink type="help" url="gnome-help:fdl">here</ulink>.
+      </para>
+      <para>Many of the names used by companies to distinguish their products and
+	services are claimed as trademarks. Where those names appear in any
+	GNOME documentation, and those trademarks are made aware to the members
+	of the GNOME Documentation Project, the names have been printed in caps
+	or initial caps.
+      </para>
+    </legalnotice>
+    <releaseinfo>This is release 0.1 of the xsltproc Manual.</releaseinfo>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>xsltproc</refentrytitle>
+    <manvolnum>1</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>xsltproc</refname>
+    <refpurpose>command line xslt processor</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>xsltproc</command>
+      <group>
+	<arg>-V</arg>
+	<arg>-v</arg>
+	<arg>-o <replaceable>file</replaceable></arg>
+	<arg>--timing</arg>
+	<arg>--repeat</arg>
+	<arg>--debug</arg>
+	<arg>--novalid</arg>
+	<arg>--noout</arg>
+	<arg>--maxdepth <replaceable>val</replaceable></arg>
+	<arg>--html</arg>
+	<arg>--docbook</arg>
+	<arg>--param <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
+	<arg>--nonet</arg>
+	<arg>--warnnet</arg>
+	<arg>--catalogs</arg>
+	<arg>--xinclude</arg>
+	<arg>--profile</arg>
+      </group>
+      <arg><option><replaceable>stylesheet</replaceable></option></arg>
+      <arg><replaceable>file1</replaceable></arg>
+      <arg><replaceable>file2</replaceable></arg>
+      <arg><replaceable>....</replaceable></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+
+  <refsect1 id="introduction">
+    <title>Introduction</title>
+    <para>
+      <application>xsltproc</application> is a command line tool for applying
+      <acronym>XSLT</acronym> stylesheets to <acronym>XML</acronym>
+      documents. It is part of <application>libxslt</application>, the XSLT C
+      library for GNOME. While it was developed as part of the GNOME project, it
+      can operate independently of the GNOME desktop.
+   </para>
+
+    <para>
+      <application>xsltproc</application> is invoked from the command line with
+      the name of the stylesheet to be used followed by the name of the file or
+      files to which the stylesheet is to be applied.
+    </para>
+
+    <para>
+      If a stylesheet is included in an <acronym>XML</acronym> document with a
+      Stylesheet Processing Instruction, no stylesheet need be named at the
+      command line. <application>xsltproc</application> will automatically
+      detect the included stylesheet and use it.
+    </para>
+
+    <para>
+      By default, output is to stdout. You can specify a file for output using
+      the <option>-o</option> option.
+    </para>
+  </refsect1>
+
+  <refsect1 id="options">
+    <title>Options</title>
+    
+    <para>
+      <option>-V</option> or <option>--version</option> - Show the version of
+      <application>libxml</application> and <application>libxslt</application> used.
+    </para>
+
+    <para>
+      <option>-v</option> or <option>--verbose</option> - Output each step taken
+      by <application>xsltproc</application> in processing the stylesheet and the document.
+    </para>
+
+    <para>
+      <option>-o</option> or <option>--output</option>
+      <replaceable>file</replaceable> - Direct output to the file named
+      <replaceable>file</replaceable>. For multiple outputs, also known as
+      "chunking", <option>-o</option> <option>directory/</option> directs the
+      output files to a specified directory. The directory must already exist.
+    </para>
+
+    <para>
+      <option>--timing</option> - Display the time used for parsing the
+      stylesheet, parsing the document and applying the stylesheet and saving
+      the result. Displayed in milliseconds.
+    </para>
+
+    <para>
+      <option>--repeat</option> - Run the transformation 20 times. Used for
+      timing tests.
+    </para>
+
+    <para>
+      <option>--debug</option> - Output an <acronym>XML</acronym> tree of the
+      transformed document for debugging purposes.
+    </para>
+
+    <para>
+      <option>--novalid</option> - Skip loading the document's <acronym>DTD</acronym>.
+    </para>
+
+    <para>
+      <option>--noout</option> - Do not output the result.
+    </para>
+
+    <para>
+      <option>--maxdepth</option> <replaceable>value</replaceable> - Adjust the
+      maximum depth of the template stack before
+      <application>libxslt</application> concludes it is in an infinite
+      loop. The default is 500.
+    </para>
+
+    <para>
+      <option>--html</option> - The input document is an <acronym>HTML</acronym>
+      file.
+    </para>
+
+    <para>
+      <option>--docbook</option> - The input document is DocBook
+      <acronym>SGML</acronym>.
+    </para>
+
+    <para>
+      <option>--param</option> <replaceable>name</replaceable>
+      <replaceable>value</replaceable> - Pass a parameter of name
+      <replaceable>name</replaceable> and value
+      <replaceable>value</replaceable> to the stylesheet. You may pass multiple
+      name/value pairs up to a maximum of 8.
+
+      <note>
+	<para>
+	  If the value being passed is a string rather than a node identifier,
+	  it must be escaped in quotes, as follows:
+	</para>
+	<para>
+	  xsltproc --param rootid '"introduction"'
+	  <replaceable>stylesheet</replaceable> <replaceable>file</replaceable>
+
+	</para>
+      </note>
+    </para>
+
+    <para>
+      <option>--nonet</option> - Do not use the Internet to fetch DTD's or
+      entities.
+    </para>
+
+    <para>
+      <option>--warnnet</option> - Output notification when DTD's or entities
+      are fetched over the Internet.
+    </para>
+
+    <para>
+      <option>--catalogs</option> - Use catalogs to resolve the location of
+      external entities. This speeds DTD resolution. By having a
+      catalog file point to a local version of the DTD,
+      <application>xsltproc</application> does not have to use the
+      Internet to fetch the DTD. <application>xsltproc</application>
+      uses the catalog identified by the environmental variable
+      <envar>SGML_CATALOG_FILES</envar>.
+    </para>
+
+    <para>
+      <option>--xinclude</option> - Process the input document using the
+      Xinclude specification. More details on this can be found in the Xinclude
+      specification: <ulink
+      url="http://www.w3.org/TR/xinclude/">http://www.w3.org/TR/xinclude/</ulink>
+    </para>
+    
+    <para>
+      <option>--profile</option> or <option>--norman</option> - Output profiling
+      information detailing the amount of time spent in each part of the
+      stylesheet. This is useful in optimizing stylesheet performance.
+    </para>
+  </refsect1>
+
+  <refsect1 id="moreinfo">
+    <title>More Information</title>
+    <para>
+      <itemizedlist>
+	<listitem>
+	  <para><application>libxml web page: </application><ulink url="http://www.xmlsoft.org/">http://www.xmlsoft.org/</ulink></para>
+	</listitem>
+	<listitem>
+	  <para>W3C <acronym>XSLT page: </acronym><ulink url="http://www.w3.org/TR/xslt">http://www.w3.org/TR/xslt</ulink></para>
+	</listitem>
+      </itemizedlist>
+    </para>
+  </refsect1>
+</refentry>