Imported Upstream version 0.0.25upstream/0.0.25

2 files changed, 537 insertions, 0 deletions

diff --git a/doc/xmlif.xml b/doc/xmlif.xml
new file mode 100644
index 0000000..67062ab
--- /dev/null
+++ b/doc/xmlif.xml
@@ -0,0 +1,107 @@
+<?xml version='1.0'?> <!-- -*- xml -*- -->
+<!DOCTYPE refentry PUBLIC
+   "-//OASIS//DTD DocBook XML V4.2//EN"
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id='xmlif'>
+  <refentryinfo>
+    <title>xmlif</title>
+		<date>April 2009</date>
+		<productname>Linux</productname>
+    <author>
+      <firstname>Eric</firstname>
+      <othername role="initial">S.</othername>
+      <surname>Raymond</surname>
+			<affiliation>
+        <address><email>esr@snark.thyrsus.com</email></address>
+      </affiliation>
+      <contrib>Author of xmlif program</contrib>
+    </author>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>xmlif</refentrytitle>
+    <manvolnum>1</manvolnum>
+    <refmiscinfo class='date'>Sept 26 2002</refmiscinfo>
+  </refmeta>
+
+  <refnamediv id='name'>
+    <refname>xmlif</refname>
+    <refpurpose>conditional processing instructions for XML</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv id='synopsis'>
+    <cmdsynopsis>
+      <command>xmlif</command> <arg rep='repeat'>attrib=value</arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1 id='description'><title>DESCRIPTION</title>
+
+    <para><application>xmlif</application> filters XML according to
+      conditionalizing markup.  This can be useful for formatting one
+      of several versions of an XML document depending on conditions
+      passed to the command.</para>
+
+    <para>Attribute/value pairs from the command line are matched
+      against the attributes associated with certain processing
+      instructions in the document.  The instructions are
+      <sgmltag>&lt;?xmlif if?&gt;</sgmltag> and its inverse <sgmltag>&lt;?xmlif if
+      not?&gt;</sgmltag>, <sgmltag>&lt;?xmlif elif?&gt;</sgmltag> and its
+      inverse <sgmltag>&lt;?xmlif elif not?&gt;</sgmltag>,
+      <sgmltag>&lt;?xmlif else?&gt;</sgmltag>, and
+      <sgmltag>&lt;?xmlif fi?&gt;</sgmltag>.</para>
+
+    <para>Argument/value pairs given on the command line are checked
+      against the value of corresponding attributes in the conditional
+      processing instructions.  An `attribute match' happens if an
+      attribute occurs in both the command-line arguments and the tag,
+      and the values match.  An `attribute mismatch' happens if an
+      attribute occurs in both the command-line arguments and the tag,
+      but the values do not match.</para>
+
+    <para>Spans between <sgmltag>&lt;?xmlif if?&gt;</sgmltag> or
+      <sgmltag>&lt;?xmlif elif?&gt;</sgmltag> and the next conditional
+      processing instruction at the same nesting level are passed
+      through unaltered if there is at least one attribute match and
+      no attribute mismatch; spans between <sgmltag>&lt;?xmlif if
+      not?&gt;</sgmltag> and <sgmltag>&lt;?xmlif elif not?&gt;</sgmltag> and
+      the next conditional processing instruction are passed
+      otherwise.  Spans between <sgmltag>&lt;?xmlif else?&gt;</sgmltag> and
+      the next conditional-processing tag are passed through only if
+      no previous span at the same level has been passed
+      through. <sgmltag>&lt;?xmlif if?&gt;</sgmltag> and
+      <sgmltag>&lt;?xmlif fi?&gt;</sgmltag> (and their `not' variants) change
+      the current nesting level; <sgmltag>&lt;?xmlif else?&gt;</sgmltag> and
+      <sgmltag>&lt;?xmlif elif?&gt;</sgmltag> do not.</para>
+
+    <para>All these processing instructions will be removed from the
+      output produced. Aside from the conditionalization, all other
+      input is passed through untouched; in particular, entity
+      references are not resolved.</para>
+
+    <para>Value matching is by string equality, except that "|" in an
+      attribute value is interpreted as an alternation character.
+      Thus, saying foo='red|blue' on the command line enables
+      conditions red and blue.  Saying color='black|white' in a tag
+      matches command-line conditions color='black' and
+      color='white'.</para>
+
+    <para>Here is an example:
+
+<programlisting>
+Always issue this text.
+&lt;?xmlif if condition='html'?&gt;
+Issue this text if 'condition=html' is given on the command line.
+&lt;?xmlif elif condition='pdf|ps'?&gt;
+Issue this text if 'condition=pdf' or 'condition=ps'
+is given on the command line.
+&lt;?xmlif else?&gt;
+Otherwise issue this text.
+&lt;?xmlif fi?&gt;
+Always issue this text.
+</programlisting></para>
+
+  </refsect1>
+
+</refentry>
diff --git a/doc/xmlto.xml b/doc/xmlto.xml
new file mode 100644
index 0000000..1c34aff
--- /dev/null
+++ b/doc/xmlto.xml
@@ -0,0 +1,430 @@
+<?xml version='1.0'?> <!-- -*- xml -*- -->
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<article>
+  <articleinfo>
+    <title>xmlto</title>
+
+    <author>
+      <firstname>Tim</firstname>
+      <surname>Waugh</surname>
+      <affiliation>
+        <address><email>twaugh@redhat.com</email></address>
+      </affiliation>
+      <contrib>Original author, maintainer until 0.0.18</contrib>
+    </author>
+    <author>
+      <firstname>Ondřej</firstname>
+      <surname>Vašík</surname>
+      <affiliation>
+        <address><email>ovasik@redhat.com</email></address>
+      </affiliation>
+      <contrib>Maintainer since 0.0.19</contrib>
+    </author>
+
+
+    <copyright>
+      <year>2001-8</year>
+      <holder>Tim Waugh</holder>
+    </copyright>
+    <copyright>
+      <year>2008-9</year>
+      <holder>Ondřej Vašík</holder>
+    </copyright>
+  </articleinfo>
+
+  <section>
+    <title>Reference</title>
+
+    <refentry>
+      <refentryinfo>
+	<title>xmlto</title>
+	<date>November 2011</date>
+	<productname>xmlto 0.0.25</productname>
+      </refentryinfo>
+
+      <refmeta>
+	<refentrytitle>xmlto</refentrytitle>
+	<manvolnum>1</manvolnum>
+      </refmeta>
+
+      <refnamediv>
+	<refname>xmlto</refname>
+	<refpurpose>apply an XSL stylesheet to an XML document</refpurpose>
+      </refnamediv>
+
+      <refsynopsisdiv>
+	<cmdsynopsis>
+	  <command>xmlto</command>
+	  <arg choice="opt"><option>-o</option>
+            <replaceable>output_dir</replaceable></arg>
+	  <arg choice="opt"><option>-x</option>
+	    <replaceable>custom_xsl</replaceable></arg>
+	  <arg choice="opt"><option>-m</option>
+	    <replaceable>xsl_fragment</replaceable></arg>
+	  <arg choice="opt"><option>-v</option></arg>
+	  <arg choice="opt"><option>-p</option>
+	    <replaceable>postprocessor_opts</replaceable></arg>
+	  <arg choice="opt"><option>--extensions</option></arg>
+	  <arg choice="opt"><option>--searchpath</option>
+	    <replaceable>path</replaceable></arg>
+	  <arg choice="opt"><option>--skip-validation</option></arg>
+    <arg choice="opt"><option>--stringparam</option>
+      <replaceable>paramname</replaceable>=<replaceable>paramvalue</replaceable></arg>
+    <arg choice="opt"><option>--noclean</option></arg>
+    <arg choice="opt"><option>--noautosize</option></arg>
+    <arg choice="opt"><option>--noextensions</option></arg>
+    <arg choice="opt"><option>--with-fop</option></arg>
+    <arg choice="opt"><option>--with-dblatex</option></arg>
+	  <arg choice="req"><replaceable>format</replaceable></arg>
+	  <arg choice="req"><replaceable>file</replaceable></arg>
+	</cmdsynopsis>
+
+	<cmdsynopsis>
+	  <command>xmlto</command>
+	  <group choice="req">
+	    <arg>--help</arg>
+	    <arg>--version</arg>
+	  </group>
+	</cmdsynopsis>
+      </refsynopsisdiv>
+
+      <refsect1>
+	<title>Description</title>
+
+	<para>The purpose of <command>xmlto</command> is to convert an
+	 XML <replaceable>file</replaceable> to the desired
+	 <replaceable>format</replaceable> using whatever means
+	 necessary.  This may involve two steps:</para>
+
+	<procedure>
+	  <step>
+	    <para>The application of an appropriate XSL stylesheet
+	     using an XSL-T processor.</para>
+	  </step>
+
+	  <step>
+	    <para>Further processing with other tools.  This step may
+	     not be necessary.</para>
+	  </step>
+	</procedure>
+
+	<para>To decide which stylesheet to use and what, if any,
+	 needs to be done to post-process the output,
+	 <command>xmlto</command> makes use of <firstterm>format
+	 scripts</firstterm>, which are simple shell scripts that
+	 <command>xmlto</command> calls during the conversion.</para>
+
+	<para>The appropriate format script is selected based on the
+	 type of XML file and the desired output format.
+	 <command>xmlto</command> comes with some format scripts for
+	 converting DocBook XML files to a variety of formats.  You
+	 may specify your own format script by using an absolute
+	 filename for <replaceable>format</replaceable> on the command
+	 line.</para>
+
+	<para>Firstly, if <command>xmlto</command> has not been told
+	 explicitly which stylesheet to use (with the
+	 <option>-x</option> option), the format script will be called
+	 with <envar>$1</envar> set to <literal>stylesheet</literal>.
+	 The environment variable <envar>XSLT_PROCESSOR</envar>
+	 contains the base name of the executable that will be used to
+	 perform the XSL-T transformation (for example
+	 <literal>xsltproc</literal>). The format script should write
+   the name of the stylesheet to use to standard output and exit
+	 successfully, or exit with a non-zero return code if there is
+	 no appropriate stylesheet to use (for example, if the only
+	 available stylesheet is known not to work with the XSL-T
+	 processor that will be used).  If nothing is written to
+	 standard output but the script exits successfully, no XSL-T
+	 transformation will be performed.</para>
+
+	<para>Secondly, after an XSL-T processor has been run using
+	 the stylesheet, the format script will be called again, this
+	 time with <envar>$1</envar> set to
+	 <literal>post-process</literal>.  The format script should
+	 perform any necessary steps to translate the XSL-T processed
+	 output into the desired output format, including copying the
+	 output to the desired output directory.  For post-processing,
+	 the format script is run in a temporary directory containing
+	 just the processed output (whose name is stored in
+	 <envar>XSLT_PROCESSED</envar> and whose basename is that of
+	 the original XML file with any filename extension replaced
+	 with <literal>.proc</literal>).  <envar>INPUT_FILE</envar> is
+	 set to the name of the original XML file,
+	 <envar>OUTPUT_DIR</envar> is set to the name of the directory
+	 that the output (and only the output) must end up in, and
+	 <envar>SEARCHPATH</envar> is set to a colon-separate list of
+	 fallback directories in which to look for input (for images,
+	 for example).  If this step is unsuccessful the format script
+	 should exit with a non-zero return code.</para>
+
+      </refsect1>
+      <refsect1>
+	<title>Options</title>
+
+	<variablelist>
+	  <varlistentry>
+	    <term><option>-v</option></term>
+	    <listitem>
+	      <para>Be verbose (<option>-vv</option> for very
+	       verbose).</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>-x</option> <replaceable>stylesheet</replaceable></term>
+	    <listitem>
+	      <para>Use <replaceable>stylesheet</replaceable> instead
+	       of asking the format script to choose one.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>-m</option> <replaceable>fragment</replaceable></term>
+	    <listitem>
+	      <para>Use the provided XSL
+	       <replaceable>fragment</replaceable> to modify the
+	       stylesheet.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>-o</option> <replaceable>directory</replaceable></term>
+	    <listitem>
+	      <para>Put output in the specified
+	       <replaceable>directory</replaceable> instead of the
+	       current working directory.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>-p</option> <replaceable>postprocessor_opts</replaceable></term>
+	    <listitem>
+	      <para>Pass <replaceable>postprocessor_opts</replaceable>
+	       to processing stages after stylesheet application
+	       (e.g. <application>lynx</application> or
+	       <application>links</application> when going
+	       through HTML to text, or <application>xmltex</application>
+	       when going from through TeX to DVI).  If
+	       <option>-p</option> is specified a second time, the
+	       options specified will be passed to second-stage
+	       postprocessing; presently this is only applicable when
+	       going through <application>xmltex</application> and
+	       <application>dvips</application> to PostScript.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>--extensions</option></term>
+	    <listitem>
+	      <para>Turn on stylesheet extensions for the tool chain
+	       in use (<varname>use.extensions</varname> is turned on). 
+               The variables turned on are the ones used
+	       by Norman Walsh's DocBook XSL stylesheets.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>--searchpath</option> <replaceable>path</replaceable></term>
+	    <listitem>
+	      <para>Add the colon-separated list of directories in
+	        <replaceable>path</replaceable> as fallback
+	        directories for including input.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>--skip-validation</option></term>
+	    <listitem>
+	      <para>Skip the validation step that is normally
+	        performed.</para>
+	    </listitem>
+	  </varlistentry>
+
+    <varlistentry>
+	    <term><option>--stringparam</option> <replaceable>paramname</replaceable>=<replaceable>paramvalue</replaceable></term>
+	    <listitem>
+	      <para>Pass a named parameter <replaceable>paramname</replaceable>
+          with value <replaceable>paramvalue</replaceable>
+          to stylesheet from the command line.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>--noclean</option></term>
+	    <listitem>
+	      <para>Temporary files are not deleted(their names
+          are shown and kept in tmp directory). It could
+          help with analyzing problems.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>--noautosize</option></term>
+	    <listitem>
+	       <para> By default, some XSL variables are overriden
+         by autodetection (<varname>page.width</varname> and
+         <varname>page.height</varname> for <application>paperconf</application>
+         (libpaper) use, <varname>paper.type</varname> for locale-based
+         (<envar>LC_PAPER</envar>) selection). With this
+         option, <command>xmlto</command> doesn’t use this autodetection
+         and user is able to modify defaults himself (either via default
+         <filename>param.xsl</filename> modification or by user-defined
+          XSL fragment).
+	       </para>
+	    </listitem>
+	  </varlistentry>
+
+          <varlistentry>
+	    <term><option>--noextensions</option></term>
+	    <listitem>
+	       <para> By default, <command>xmlto</command> enables XSL params <varname>passivetex.extensions</varname> for
+               <application>passivetex</application> backend and <varname>fop.extensions</varname> and <varname>fop1.extensions</varname>
+               for <application>fop</application> backend.
+               This usually produces better results. If you for some reason don't want to use these parameters, just
+               disable them using this option.
+	       </para>
+	    </listitem>
+          </varlistentry>
+
+	  <varlistentry>
+	    <term><option>--with-fop</option></term>
+	    <listitem>
+	      <para>Use <application>fop</application> for formatting.
+          It is an experimental option, expects <application>fop</application>
+          in specific location(detected at configured time), could be changed
+          manually in <command>xmlto</command> script by modification
+          of <varname>FOP_PATH</varname></para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>--with-dblatex</option></term>
+	    <listitem>
+	      <para>Use <application>dblatex</application> for formatting.
+        It is an experimental option, expects <application>dblatex</application>
+        in specific location(detected at configured time), could be changed
+        manually in <command>xmlto</command> script by modification
+          of <varname>DBLATEX_PATH</varname></para>
+	    </listitem>
+	  </varlistentry>
+
+
+	  <varlistentry>
+	    <term><option>--help</option></term>
+	    <listitem>
+	      <para>Display a short usage message.  It will describe xmlto's
+                options, and the available output formats.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>--version</option></term>
+	    <listitem>
+	      <para>Display the version number of xmlto.</para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+      </refsect1>
+      <refsect1>
+	<title>Environment</title>
+	<variablelist>
+	  <varlistentry>
+	    <term><envar>XSLT_PROCESSOR</envar></term>
+	    <listitem>
+	      <para>Base name of the executable that will be used to
+	            perform the XSL-T transformation (default: <citerefentry>
+                 <refentrytitle>xsltproc</refentrytitle>
+                 <manvolnum>1</manvolnum>
+               </citerefentry>).
+         </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><envar>TMPDIR</envar></term>
+	    <listitem>
+	      <para>Directory, where to create temporary stylesheets
+	            (default: <filename>/tmp</filename>).
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+      </refsect1>
+      <refsect1>
+	<title>Diagnostics</title>
+	<variablelist>
+	  <varlistentry>
+    <term><errorcode>0</errorcode></term>
+	    <listitem>
+	      <para>Everything went fine. This is the expected exit code.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><errorcode>1</errorcode></term>
+	    <listitem>
+	      <para><command>xmlto</command> was called with insufficient
+	            arguments.
+         </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><errorcode>2</errorcode></term>
+	    <listitem>
+	      <para><citerefentry>
+             <refentrytitle>mktemp</refentrytitle>
+             <manvolnum>1</manvolnum>
+           </citerefentry> failed to create a file/directory. Make sure
+           <filename>/tmp</filename> or <envar>TMPDIR</envar> is
+           writable.
+         </para>
+	    </listitem>
+	  </varlistentry>
+          <varlistentry>
+	    <term><errorcode>3</errorcode></term>
+	    <listitem>
+	      <para><command>xmlto</command> failed to find some binary on
+	            configured location. Make sure that all required packages
+                    are installed and paths in <application>xmlto</application>
+                    script are set properly.
+         </para>
+	    </listitem>
+	  </varlistentry>
+        <varlistentry>
+	    <term><errorcode>10+(Validation non-zero error code)</errorcode></term>
+	    <listitem>
+	      <para><command>xmlto</command> tried to validate a xml document, but validation failed. For better diagnostic, validation output and <application>xmllint</application> exit code is provided. Consider either fixing your document or using <option>--skip-validation</option>.
+         </para>
+	    </listitem>
+	  </varlistentry>
+        </variablelist>
+      </refsect1>
+      <refsect1>
+	<title>Examples</title>
+
+	<para>To convert a DocBook XML document to PDF, use:
+
+	<screen><command>xmlto pdf mydoc.xml</command></screen></para>
+
+	<para>To convert a DocBook XML document to HTML and store the
+	 resulting HTML files in a separate directory use:
+
+	<screen><command>xmlto -o html-dir html mydoc.xml</command></screen></para>
+
+	<para>To convert a DocBook XML document to a single HTML file
+	 use:
+
+	<screen><command>xmlto html-nochunks mydoc.xml</command></screen></para>
+
+	<para>To modify the output using an XSL fragment use:
+
+	<screen><command>xmlto -m ulink.xsl pdf mydoc.xml</command></screen></para>
+
+	<para>To specify which stylesheet to use (overriding the one
+	 that the format script would choose) use:
+
+	<screen><command>xmlto -x mystylesheet.xsl pdf mydoc.xml</command></screen></para>
+      </refsect1>
+    </refentry>
+  </section>
+</article>