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.
  82     </para>
  83
  84     <para>
  85       If a stylesheet is included in an <acronym>XML</acronym> document with a
  86       Stylesheet Processing Instruction, no stylesheet need be named at the
  87       command line. <application>xsltproc</application> will automatically
  88       detect the included stylesheet and use it.
  89     </para>
  90
  91     <para>
  92       By default, output is to stdout. You can specify a file for output using
  93       the <option>-o</option> option.
  94     </para>
  95   </refsect1>
  96
  97   <refsect1 id="options">
  98     <title>Command Line Options</title>
  99
 100     <variablelist>
 101       <varlistentry>
 102         <term><option>-V</option> or <option>--version</option></term>
 103         <listitem>
 104           <simpara>Show the version of
 105       <application>libxml</application> and <application>libxslt</application> used.
 106     </simpara>
 107         </listitem>
 108       </varlistentry>
 109
 110
 111       <varlistentry>
 112         <term>
 113       <option>-v</option> or <option>--verbose</option></term>
 114         <listitem>
 115           <simpara>Output each step taken
 116       by <application>xsltproc</application> in processing the stylesheet and the document.
 117     </simpara>
 118         </listitem>
 119       </varlistentry>
 120
 121
 122       <varlistentry>
 123         <term>
 124       <option>-o</option> or <option>--output</option> <replaceable>file</replaceable></term>
 125         <listitem>
 126           <simpara>Direct output to the file named
 127       <replaceable>file</replaceable>. For multiple outputs, also known as
 128       "chunking", <option>-o</option> <option>directory/</option> directs the
 129       output files to a specified directory. The directory must already exist.
 130     </simpara>
 131         </listitem>
 132       </varlistentry>
 133
 134
 135       <varlistentry>
 136         <term>
 137       <option>--timing</option></term>
 138         <listitem>
 139           <simpara>Display the time used for parsing the
 140       stylesheet, parsing the document and applying the stylesheet and saving
 141       the result. Displayed in milliseconds.
 142     </simpara>
 143         </listitem>
 144       </varlistentry>
 145
 146
 147       <varlistentry>
 148         <term>
 149       <option>--repeat</option></term>
 150         <listitem>
 151           <simpara>Run the transformation 20 times. Used for
 152       timing tests.
 153     </simpara>
 154         </listitem>
 155       </varlistentry>
 156
 157
 158       <varlistentry>
 159         <term>
 160       <option>--debug</option></term>
 161         <listitem>
 162           <simpara>Output an <acronym>XML</acronym> tree of the
 163       transformed document for debugging purposes.
 164     </simpara>
 165         </listitem>
 166       </varlistentry>
 167
 168
 169       <varlistentry>
 170         <term>
 171       <option>--novalid</option></term>
 172         <listitem>
 173           <simpara>Skip loading the document's <acronym>DTD</acronym>.
 174     </simpara>
 175         </listitem>
 176       </varlistentry>
 177
 178
 179       <varlistentry>
 180         <term>
 181       <option>--noout</option></term>
 182         <listitem>
 183           <simpara>Do not output the result.
 184     </simpara>
 185         </listitem>
 186       </varlistentry>
 187
 188
 189       <varlistentry>
 190         <term>
 191       <option>--maxdepth</option> <replaceable>value</replaceable></term>
 192         <listitem>
 193           <simpara>Adjust the
 194       maximum depth of the template stack before
 195       <application>libxslt</application> concludes it is in an infinite
 196       loop. The default is 500.
 197     </simpara>
 198         </listitem>
 199       </varlistentry>
 200
 201
 202       <varlistentry>
 203         <term>
 204       <option>--html</option></term>
 205         <listitem>
 206           <simpara>The input document is an <acronym>HTML</acronym>
 207       file.
 208     </simpara>
 209         </listitem>
 210       </varlistentry>
 211
 212       <varlistentry>
 213         <term>
 214       <option>--param</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term>
 215         <listitem>
 216           <simpara>Pass a parameter of name
 217       <replaceable>name</replaceable> and value
 218       <replaceable>value</replaceable> to the stylesheet. You may pass multiple
 219       name/value pairs up to a maximum of 32. If the value being passed is a
 220             string rather than a node identifier, use
 221             <option>--stringparam</option> instead.
 222           </simpara>
 223         </listitem>
 224       </varlistentry>
 225
 226       <varlistentry>
 227         <term>
 228           <option>--stringparam</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term>
 229         <listitem>
 230           <simpara>Pass a paramenter of name <replaceable>name</replaceable> and
 231             value <replaceable>value</replaceable> where
 232             <replaceable>value</replaceable> is a string rather than a node
 233             identifier. (Note: The string must be utf-8.) </simpara>
 234         </listitem>
 235       </varlistentry>
 236
 237       <varlistentry>
 238         <term>
 239       <option>--nonet</option></term>
 240         <listitem>
 241           <simpara>Do not use the Internet to fetch DTD's,
 242       entities or documents.
 243     </simpara>
 244         </listitem>
 245       </varlistentry>
 246
 247       <varlistentry>
 248         <term> <option>--path</option> <replaceable>paths</replaceable></term>
 249         <listitem>
 250           <simpara>
 251             Use the list (separated by space or column) of filesystem paths
 252         specified by <replaceable>paths</replaceable> to load
 253         <acronym>DTDs</acronym>, entities or documents.
 254           </simpara>
 255         </listitem>
 256       </varlistentry>
 257
 258       <varlistentry>
 259         <term><option>--load-trace</option></term>
 260         <listitem>
 261           <simpara>
 262             Display to stderr all the documents loaded during the processing.
 263           </simpara>
 264         </listitem>
 265       </varlistentry>
 266
 267       <varlistentry>
 268         <term>
 269       <option>--catalogs</option></term>
 270         <listitem>
 271           <simpara>Use the <acronym>SGML</acronym> catalog specified in
 272       <envar>SGML_CATALOG_FILES</envar> to resolve the location of
 273             external entities. By default, <application>xsltproc</application>
 274             looks for the catalog specified in
 275       <envar>XML_CATALOG_FILES</envar>. If that is not specified, it uses
 276       <filename>/etc/xml/catalog</filename>.
 277     </simpara>
 278         </listitem>
 279       </varlistentry>
 280
 281
 282       <varlistentry>
 283         <term>
 284       <option>--xinclude</option></term>
 285         <listitem>
 286           <simpara>Process the input document using the
 287       Xinclude specification. More details on this can be found in the Xinclude
 288       specification: <ulink
 289       url="http://www.w3.org/TR/xinclude/">http://www.w3.org/TR/xinclude/</ulink>
 290     </simpara>
 291         </listitem>
 292       </varlistentry>
 293
 294
 295       <varlistentry>
 296         <term>
 297       <option>--profile</option> or <option>--norman</option></term>
 298         <listitem>
 299           <simpara>Output profiling
 300       information detailing the amount of time spent in each part of the
 301       stylesheet. This is useful in optimizing stylesheet performance.
 302     </simpara>
 303         </listitem>
 304       </varlistentry>
 305
 306       <varlistentry>
 307         <term>
 308       <option>--dumpextensions</option></term>
 309         <listitem>
 310           <simpara>Dumps the list of all registered extensions on stdout.
 311     </simpara>
 312         </listitem>
 313       </varlistentry>
 314
 315       <varlistentry>
 316         <term>
 317       <option>--nowrite</option></term>
 318         <listitem>
 319           <simpara>Refuses to write to any file or resource.
 320     </simpara>
 321         </listitem>
 322       </varlistentry>
 323
 324       <varlistentry>
 325         <term>
 326       <option>--nomkdir</option></term>
 327         <listitem>
 328           <simpara>Refuses to create directories.
 329     </simpara>
 330         </listitem>
 331       </varlistentry>
 332
 333       <varlistentry>
 334         <term>
 335       <option>--writesubtree</option> <replaceable>path</replaceable></term>
 336         <listitem>
 337           <simpara>Allow file write only within the
 338           <replaceable>path</replaceable> subtree.
 339     </simpara>
 340         </listitem>
 341       </varlistentry>
 342
 343
 344     </variablelist>
 345   </refsect1>
 346
 347   <refsect1 id="return">
 348     <title>Return values</title>
 349     <para><application>xsltproc</application>'s return codes provide information
 350     that can be used when calling it from scripts.</para>
 351
 352     <para>0: normal</para>
 353     <para>1: no argument</para>
 354     <para>2: too many parameters</para>
 355     <para>3: unknown option</para>
 356     <para>4: failed to parse the stylesheet</para>
 357     <para>5: error in the stylesheet</para>
 358     <para>6: error in one of the documents</para>
 359     <para>7: unsupported xsl:output method</para>
 360     <para>8: string parameter contains both quote and double-quotes</para>
 361     <para>9: internal processing error</para>
 362     <para>10: processing was stopped by a terminating message</para>
 363   </refsect1>
 364
 365
 366
 367   <refsect1 id="moreinfo">
 368     <title>More Information</title>
 369
 370           <para><application>libxml web page: </application><ulink url="http://www.xmlsoft.org/">http://www.xmlsoft.org/</ulink></para>
 371
 372           <para>W3C <acronym>XSLT page: </acronym><ulink url="http://www.w3.org/TR/xslt">http://www.w3.org/TR/xslt</ulink></para>
 373
 374
 375   </refsect1>
 376 </refentry>