doc/xsltproc.xml

   1 <?xml version="1.0"?>
   2 <?xml-stylesheet type="text/xsl"
   3    href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>
   4 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   5     "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
   6 ]>
   7
   8 <refentry>
   9   <refentryinfo>
  10     <title>xsltproc Manual</title>
  11     <copyright>
  12       <year>2001, 2002</year>
  13     </copyright>
  14     <author>
  15       <firstname>John</firstname>
  16       <surname>Fleck</surname>
  17     </author>
  18     <address><email>jfleck@inkstain.net</email></address>
  19
  20     <releaseinfo>This is release 0.4 of the xsltproc Manual.</releaseinfo>
  21   </refentryinfo>
  22
  23   <refmeta>
  24     <refentrytitle>xsltproc</refentrytitle>
  25     <manvolnum>1</manvolnum>
  26   </refmeta>
  27
  28   <refnamediv>
  29     <refname>xsltproc</refname>
  30     <refpurpose>command line xslt processor</refpurpose>
  31   </refnamediv>
  32
  33   <refsynopsisdiv>
  34     <cmdsynopsis>
  35       <command>xsltproc</command>
  36       <group>
  37         <arg>-V</arg>
  38         <arg>-v</arg>
  39         <arg>-o <replaceable>file</replaceable></arg>
  40         <arg>--timing</arg>
  41         <arg>--repeat</arg>
  42         <arg>--debug</arg>
  43         <arg>--novalid</arg>
  44         <arg>--noout</arg>
  45         <arg>--maxdepth <replaceable>val</replaceable></arg>
  46         <arg>--html</arg>
  47         <arg>--param <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
  48         <arg>--stringparam <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
  49         <arg>--nonet</arg>
  50         <arg>--path <replaceable>paths</replaceable></arg>
  51         <arg>--load-trace</arg>
  52         <arg>--catalogs</arg>
  53         <arg>--xinclude</arg>
  54         <arg>--profile</arg>
  55         <arg>--dumpextensions</arg>
  56         <arg>--nowrite</arg>
  57         <arg>--nomkdir</arg>
  58         <arg>--writesubtree</arg>
  59       </group>
  60       <arg><option><replaceable>stylesheet</replaceable></option></arg>
  61       <arg><replaceable>file1</replaceable></arg>
  62       <arg><replaceable>file2</replaceable></arg>
  63       <arg><replaceable>....</replaceable></arg>
  64     </cmdsynopsis>
  65   </refsynopsisdiv>
  66
  67
  68   <refsect1 id="introduction">
  69     <title>Introduction</title>
  70     <para>
  71       <application>xsltproc</application> is a command line tool for applying
  72       <acronym>XSLT</acronym> stylesheets to <acronym>XML</acronym>
  73       documents. It is part of <application>libxslt</application>, the XSLT C
  74       library for GNOME. While it was developed as part of the GNOME project, it
  75       can operate independently of the GNOME desktop.
  76    </para>
  77
  78     <para>
  79       <application>xsltproc</application> is invoked from the command line with
  80       the name of the stylesheet to be used followed by the name of the file or
  81       files to which the stylesheet is to be applied. It will use the standard
  82       input if a filename provided is - .
  83     </para>
  84
  85     <para>
  86       If a stylesheet is included in an <acronym>XML</acronym> document with a
  87       Stylesheet Processing Instruction, no stylesheet need be named at the
  88       command line. <application>xsltproc</application> will automatically
  89       detect the included stylesheet and use it.
  90     </para>
  91
  92     <para>
  93       By default, output is to stdout. You can specify a file for output using
  94       the <option>-o</option> option.
  95     </para>
  96   </refsect1>
  97
  98   <refsect1 id="options">
  99     <title>Command Line Options</title>
 100
 101     <variablelist>
 102       <varlistentry>
 103         <term><option>-V</option> or <option>--version</option></term>
 104         <listitem>
 105           <simpara>Show the version of
 106       <application>libxml</application> and <application>libxslt</application> used.
 107     </simpara>
 108         </listitem>
 109       </varlistentry>
 110
 111
 112       <varlistentry>
 113         <term>
 114       <option>-v</option> or <option>--verbose</option></term>
 115         <listitem>
 116           <simpara>Output each step taken
 117       by <application>xsltproc</application> in processing the stylesheet and the document.
 118     </simpara>
 119         </listitem>
 120       </varlistentry>
 121
 122
 123       <varlistentry>
 124         <term>
 125       <option>-o</option> or <option>--output</option> <replaceable>file</replaceable></term>
 126         <listitem>
 127           <simpara>Direct output to the file named
 128       <replaceable>file</replaceable>. For multiple outputs, also known as
 129       "chunking", <option>-o</option> <option>directory/</option> directs the
 130       output files to a specified directory. The directory must already exist.
 131     </simpara>
 132         </listitem>
 133       </varlistentry>
 134
 135
 136       <varlistentry>
 137         <term>
 138       <option>--timing</option></term>
 139         <listitem>
 140           <simpara>Display the time used for parsing the
 141       stylesheet, parsing the document and applying the stylesheet and saving
 142       the result. Displayed in milliseconds.
 143     </simpara>
 144         </listitem>
 145       </varlistentry>
 146
 147
 148       <varlistentry>
 149         <term>
 150       <option>--repeat</option></term>
 151         <listitem>
 152           <simpara>Run the transformation 20 times. Used for
 153       timing tests.
 154     </simpara>
 155         </listitem>
 156       </varlistentry>
 157
 158
 159       <varlistentry>
 160         <term>
 161       <option>--debug</option></term>
 162         <listitem>
 163           <simpara>Output an <acronym>XML</acronym> tree of the
 164       transformed document for debugging purposes.
 165     </simpara>
 166         </listitem>
 167       </varlistentry>
 168
 169
 170       <varlistentry>
 171         <term>
 172       <option>--novalid</option></term>
 173         <listitem>
 174           <simpara>Skip loading the document's <acronym>DTD</acronym>.
 175     </simpara>
 176         </listitem>
 177       </varlistentry>
 178
 179
 180       <varlistentry>
 181         <term>
 182       <option>--noout</option></term>
 183         <listitem>
 184           <simpara>Do not output the result.
 185     </simpara>
 186         </listitem>
 187       </varlistentry>
 188
 189
 190       <varlistentry>
 191         <term>
 192       <option>--maxdepth</option> <replaceable>value</replaceable></term>
 193         <listitem>
 194           <simpara>Adjust the
 195       maximum depth of the template stack before
 196       <application>libxslt</application> concludes it is in an infinite
 197       loop. The default is 500.
 198     </simpara>
 199         </listitem>
 200       </varlistentry>
 201
 202
 203       <varlistentry>
 204         <term>
 205       <option>--html</option></term>
 206         <listitem>
 207           <simpara>The input document is an <acronym>HTML</acronym>
 208       file.
 209     </simpara>
 210         </listitem>
 211       </varlistentry>
 212
 213       <varlistentry>
 214         <term>
 215       <option>--param</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term>
 216         <listitem>
 217           <simpara>Pass a parameter of name
 218       <replaceable>name</replaceable> and value
 219       <replaceable>value</replaceable> to the stylesheet. You may pass multiple
 220       name/value pairs up to a maximum of 32. If the value being passed is a
 221             string rather than a node identifier, use
 222             <option>--stringparam</option> instead.
 223           </simpara>
 224         </listitem>
 225       </varlistentry>
 226
 227       <varlistentry>
 228         <term>
 229           <option>--stringparam</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term>
 230         <listitem>
 231           <simpara>Pass a paramenter of name <replaceable>name</replaceable> and
 232             value <replaceable>value</replaceable> where
 233             <replaceable>value</replaceable> is a string rather than a node
 234             identifier. (Note: The string must be utf-8.) </simpara>
 235         </listitem>
 236       </varlistentry>
 237
 238       <varlistentry>
 239         <term>
 240       <option>--nonet</option></term>
 241         <listitem>
 242           <simpara>Do not use the Internet to fetch DTD's,
 243       entities or documents.
 244     </simpara>
 245         </listitem>
 246       </varlistentry>
 247
 248       <varlistentry>
 249         <term> <option>--path</option> <replaceable>paths</replaceable></term>
 250         <listitem>
 251           <simpara>
 252             Use the list (separated by space or column) of filesystem paths
 253         specified by <replaceable>paths</replaceable> to load
 254         <acronym>DTDs</acronym>, entities or documents.
 255           </simpara>
 256         </listitem>
 257       </varlistentry>
 258
 259       <varlistentry>
 260         <term><option>--load-trace</option></term>
 261         <listitem>
 262           <simpara>
 263             Display to stderr all the documents loaded during the processing.
 264           </simpara>
 265         </listitem>
 266       </varlistentry>
 267
 268       <varlistentry>
 269         <term>
 270       <option>--catalogs</option></term>
 271         <listitem>
 272           <simpara>Use the <acronym>SGML</acronym> catalog specified in
 273       <envar>SGML_CATALOG_FILES</envar> to resolve the location of
 274             external entities. By default, <application>xsltproc</application>
 275             looks for the catalog specified in
 276       <envar>XML_CATALOG_FILES</envar>. If that is not specified, it uses
 277       <filename>/etc/xml/catalog</filename>.
 278     </simpara>
 279         </listitem>
 280       </varlistentry>
 281
 282
 283       <varlistentry>
 284         <term>
 285       <option>--xinclude</option></term>
 286         <listitem>
 287           <simpara>Process the input document using the
 288       Xinclude specification. More details on this can be found in the Xinclude
 289       specification: <ulink
 290       url="http://www.w3.org/TR/xinclude/">http://www.w3.org/TR/xinclude/</ulink>
 291     </simpara>
 292         </listitem>
 293       </varlistentry>
 294
 295
 296       <varlistentry>
 297         <term>
 298       <option>--profile</option> or <option>--norman</option></term>
 299         <listitem>
 300           <simpara>Output profiling
 301       information detailing the amount of time spent in each part of the
 302       stylesheet. This is useful in optimizing stylesheet performance.
 303     </simpara>
 304         </listitem>
 305       </varlistentry>
 306
 307       <varlistentry>
 308         <term>
 309       <option>--dumpextensions</option></term>
 310         <listitem>
 311           <simpara>Dumps the list of all registered extensions on stdout.
 312     </simpara>
 313         </listitem>
 314       </varlistentry>
 315
 316       <varlistentry>
 317         <term>
 318       <option>--nowrite</option></term>
 319         <listitem>
 320           <simpara>Refuses to write to any file or resource.
 321     </simpara>
 322         </listitem>
 323       </varlistentry>
 324
 325       <varlistentry>
 326         <term>
 327       <option>--nomkdir</option></term>
 328         <listitem>
 329           <simpara>Refuses to create directories.
 330     </simpara>
 331         </listitem>
 332       </varlistentry>
 333
 334       <varlistentry>
 335         <term>
 336       <option>--writesubtree</option> <replaceable>path</replaceable></term>
 337         <listitem>
 338           <simpara>Allow file write only within the
 339           <replaceable>path</replaceable> subtree.
 340     </simpara>
 341         </listitem>
 342       </varlistentry>
 343
 344
 345     </variablelist>
 346   </refsect1>
 347
 348   <refsect1 id="return">
 349     <title>Return values</title>
 350     <para><application>xsltproc</application>'s return codes provide information
 351     that can be used when calling it from scripts.</para>
 352
 353     <para>0: normal</para>
 354     <para>1: no argument</para>
 355     <para>2: too many parameters</para>
 356     <para>3: unknown option</para>
 357     <para>4: failed to parse the stylesheet</para>
 358     <para>5: error in the stylesheet</para>
 359     <para>6: error in one of the documents</para>
 360     <para>7: unsupported xsl:output method</para>
 361     <para>8: string parameter contains both quote and double-quotes</para>
 362     <para>9: internal processing error</para>
 363     <para>10: processing was stopped by a terminating message</para>
 364   </refsect1>
 365
 366
 367
 368   <refsect1 id="moreinfo">
 369     <title>More Information</title>
 370
 371           <para><application>libxml web page: </application><ulink url="http://www.xmlsoft.org/">http://www.xmlsoft.org/</ulink></para>
 372
 373           <para>W3C <acronym>XSLT page: </acronym><ulink url="http://www.w3.org/TR/xslt">http://www.w3.org/TR/xslt</ulink></para>
 374
 375
 376   </refsect1>
 377 </refentry>