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     <!ENTITY xsltproc "<command>xsltproc</command>">
   8 ]>
   9
  10 <refentry>
  11
  12 <refentryinfo>
  13         <title>xsltproc Manual</title>
  14         <productname>libxslt</productname>
  15         <copyright>
  16                 <year>2001</year>
  17                 <year>2002</year>
  18         </copyright>
  19         <author>
  20                 <firstname>John</firstname>
  21                 <surname>Fleck</surname>
  22                 <affiliation>
  23                         <address>
  24                                 <email>jfleck@inkstain.net</email>
  25                         </address>
  26                 </affiliation>
  27         </author>
  28         <!-- date should be the date of the latest change or the release version -->
  29         <date>$Date$</date>
  30         <!-- still a bit buggy output, will talk to docbook-xsl upstream to fix this -->
  31         <!-- <releaseinfo>This is release 0.4 of the xsltproc Manual.</releaseinfo> -->
  32         <!-- <edition>0.4</edition> -->
  33 </refentryinfo>
  34
  35 <refmeta>
  36         <refentrytitle>xsltproc</refentrytitle>
  37         <manvolnum>1</manvolnum>
  38 </refmeta>
  39
  40 <refnamediv>
  41         <refname>xsltproc</refname>
  42         <refpurpose>command line XSLT processor</refpurpose>
  43 </refnamediv>
  44
  45 <refsynopsisdiv>
  46         <cmdsynopsis>
  47                 <command>xsltproc</command>
  48                 <group choice="opt">
  49                         <group choice="opt">
  50                                 <arg choice="plain"><option>-V</option></arg>
  51                                 <arg choice="plain"><option>--version</option></arg>
  52                         </group>
  53                         <group choice="opt">
  54                                 <arg choice="plain"><option>-v</option></arg>
  55                                 <arg choice="plain"><option>--verbose</option></arg>
  56                         </group>
  57                         <group choice="opt">
  58                                 <group choice="req">
  59                                         <arg choice="plain"><option>-o</option></arg>
  60                                         <arg choice="plain"><option>--output</option></arg>
  61                                 </group>
  62                                 <group choice="req">
  63                                         <arg choice="plain"><replaceable class="option">FILE</replaceable></arg>
  64                                         <arg choice="plain"><replaceable class="option">DIRECTORY</replaceable></arg>
  65                                 </group>
  66                         </group>
  67                         <arg choice="plain"><option>--timing</option></arg>
  68                         <arg choice="plain"><option>--repeat</option></arg>
  69                         <arg choice="plain"><option>--debug</option></arg>
  70                         <arg choice="plain"><option>--novalid</option></arg>
  71                         <arg choice="plain"><option>--noout</option></arg>
  72                         <arg choice="plain"><option>--maxdepth <replaceable class="option">VALUE</replaceable></option></arg>
  73                         <arg choice="plain"><option>--html</option></arg>
  74                         <arg choice="plain"><option>--encoding
  75                          <replaceable class="option">ENCODING</replaceable>
  76                         </option></arg>
  77                         <arg choice="plain"><option>--param
  78                          <replaceable class="option">PARAMNAME</replaceable>
  79                          <replaceable class="option">PARAMVALUE</replaceable>
  80                         </option></arg>
  81                         <arg choice="plain"><option>--stringparam
  82                          <replaceable class="option">PARAMNAME</replaceable>
  83                          <replaceable class="option">PARAMVALUE</replaceable>
  84                         </option></arg>
  85                         <arg choice="plain"><option>--nonet</option></arg>
  86                         <arg choice="plain"><option>--path "<replaceable class="option">PATH(S)</replaceable>"</option></arg>
  87                         <arg choice="plain"><option>--load-trace</option></arg>
  88                         <arg choice="plain"><option>--catalogs</option></arg>
  89                         <arg choice="plain"><option>--xinclude</option></arg>
  90                         <arg choice="plain">
  91                                 <group choice="opt">
  92                                         <arg choice="plain"><option>--profile</option></arg>
  93                                         <arg choice="plain"><option>--norman</option></arg>
  94                                 </group>
  95                         </arg>
  96                         <arg choice="plain"><option>--dumpextensions</option></arg>
  97                         <arg choice="plain"><option>--nowrite</option></arg>
  98                         <arg choice="plain"><option>--nomkdir</option></arg>
  99                         <arg choice="plain"><option>--writesubtree <replaceable>PATH</replaceable></option></arg>
 100                         <arg choice="plain"><option>--nodtdattr</option></arg>
 101                 </group>
 102                 <arg choice="opt"><replaceable>STYLESHEET</replaceable></arg>
 103                 <group choice="req">
 104                         <arg choice="plain" rep="norepeat"><replaceable>XML-FILE</replaceable></arg>
 105                         <arg choice="plain" rep="norepeat">-</arg>
 106                 </group>
 107         </cmdsynopsis>
 108 </refsynopsisdiv>
 109
 110 <refsect1 id="description">
 111         <title>DESCRIPTION</title>
 112         <para>
 113                 &xsltproc; is a command line tool for applying <acronym>XSLT</acronym>
 114                 stylesheets to <acronym>XML</acronym> documents. It is part
 115                 of <citerefentry>
 116                         <refentrytitle>libxslt</refentrytitle>
 117                         <manvolnum>3</manvolnum>
 118                 </citerefentry>, the XSLT C library for GNOME.
 119                 While it was developed as part of the GNOME project, it can operate
 120                 independently of the GNOME desktop.
 121         </para>
 122         <para>
 123                 &xsltproc; is invoked from the command line with the name of the
 124                 stylesheet to be used followed by the name of the file or files to which
 125                 the stylesheet is to be applied. It will use the standard input if a
 126                 filename provided is <emphasis role="bold">-</emphasis> .
 127         </para>
 128         <para>
 129                 If a stylesheet is included in an <acronym>XML</acronym> document with a
 130                 Stylesheet Processing Instruction, no stylesheet need to be named at the
 131                 command line. &xsltproc; will automatically detect the included stylesheet
 132                 and use it.
 133         </para>
 134         <para>
 135                 By default, output is to <filename class="devicefile">stdout</filename>.
 136                 You can specify a file for output using
 137                 the <option>-o</option> or <option>--output</option> option.
 138         </para>
 139 </refsect1>
 140
 141 <refsect1 id="options">
 142         <title>OPTIONS</title>
 143         <para>
 144                 &xsltproc; accepts the following options (in alphabetical order):
 145         </para>
 146         <variablelist>
 147
 148                 <varlistentry>
 149         <term><option>--catalogs</option></term>
 150         <listitem>
 151                 <para>
 152                         Use the <acronym>SGML</acronym> catalog specified
 153                         in <envar>SGML_CATALOG_FILES</envar> to resolve the location of
 154                         external entities. By default, &xsltproc; looks for the catalog
 155                         specified in <envar>XML_CATALOG_FILES</envar>. If that is not
 156                         specified, it uses <filename>/etc/xml/catalog</filename>.
 157                 </para>
 158         </listitem>
 159                 </varlistentry>
 160
 161                 <varlistentry>
 162         <term><option>--debug</option></term>
 163         <listitem>
 164                 <para>
 165                         Output an <acronym>XML</acronym> tree of the transformed document
 166                         for debugging purposes.
 167                 </para>
 168         </listitem>
 169                 </varlistentry>
 170
 171                 <varlistentry>
 172         <term><option>--dumpextensions</option></term>
 173         <listitem>
 174                 <para>
 175                         Dumps the list of all registered extensions
 176                         on <filename class="devicefile">stdout</filename>.
 177                 </para>
 178         </listitem>
 179                 </varlistentry>
 180
 181                 <varlistentry>
 182         <term><option>--html</option></term>
 183         <listitem>
 184                 <para>The input document is an <acronym>HTML</acronym> file.</para>
 185         </listitem>
 186                 </varlistentry>
 187
 188                 <varlistentry>
 189         <term><option>--load-trace</option></term>
 190         <listitem>
 191                 <para>
 192                         Display all the documents loaded during the processing
 193                         to <filename class="devicefile">stderr</filename>.
 194                 </para>
 195         </listitem>
 196                 </varlistentry>
 197
 198                 <varlistentry>
 199         <term><option>--maxdepth <replaceable>VALUE</replaceable></option></term>
 200         <listitem>
 201                 <para>
 202                         Adjust the maximum depth of the template stack
 203                         before <citerefentry>
 204                         <refentrytitle>libxslt</refentrytitle>
 205                         <manvolnum>3</manvolnum>
 206                 </citerefentry> concludes it is in an infinite loop. The default is 3000.
 207                 </para>
 208         </listitem>
 209                 </varlistentry>
 210
 211                 <varlistentry>
 212         <term><option>--nodtdattr</option></term>
 213         <listitem>
 214                 <para>
 215                         Do not apply default attributes from the
 216                         document's <acronym>DTD</acronym>.
 217                 </para>
 218         </listitem>
 219                 </varlistentry>
 220
 221                 <varlistentry>
 222         <term><option>--nomkdir</option></term>
 223         <listitem>
 224                 <para>Refuses to create directories.</para>
 225         </listitem>
 226                 </varlistentry>
 227
 228                 <varlistentry>
 229         <term><option>--nonet</option></term>
 230         <listitem>
 231                 <para>
 232                         Do not use the Internet to fetch <acronym>DTD</acronym>s, entities
 233                         or documents.
 234                 </para>
 235         </listitem>
 236                 </varlistentry>
 237
 238                 <varlistentry>
 239         <term><option>--noout</option></term>
 240         <listitem>
 241                 <para>Do not output the result.</para>
 242         </listitem>
 243                 </varlistentry>
 244
 245                 <varlistentry>
 246         <term><option>--novalid</option></term>
 247         <listitem>
 248                 <para>Skip loading the document's <acronym>DTD</acronym>.</para>
 249         </listitem>
 250                 </varlistentry>
 251
 252                 <varlistentry>
 253         <term><option>--nowrite</option></term>
 254         <listitem>
 255                 <para>Refuses to write to any file or resource.</para>
 256         </listitem>
 257                 </varlistentry>
 258
 259                 <varlistentry>
 260         <term>
 261                 <option>-o</option> or <option>--output</option>
 262                  <replaceable>FILE</replaceable> | <replaceable>DIRECTORY</replaceable>
 263         </term>
 264         <listitem>
 265                 <para>
 266                         Direct output to the given <replaceable>FILE</replaceable>. Using
 267                         the option with a <replaceable>DIRECTORY</replaceable> directs the
 268                         output files to the specified directory. This can be
 269                         useful for multiple outputs (also known as "chunking") or manpage
 270                         processing.
 271                 </para>
 272                 <important>
 273                         <para>
 274                                 The given directory <emphasis role="bold">must</emphasis> already exist.
 275                         </para>
 276                 </important>
 277                 <note>
 278                         <para>
 279                                 Make sure that <replaceable>FILE</replaceable>
 280                                 and <replaceable>DIRECTORY</replaceable> follow the <quote>URI reference
 281                                 computation</quote> as described in RFC 2396 and laters. This means, that
 282                                 e.g. <option>-o directory</option> will maybe not work,
 283                                 but <option>-o directory/</option> will.
 284                         </para>
 285                 </note>
 286         </listitem>
 287                 </varlistentry>
 288
 289                 <varlistentry>
 290         <term>
 291                 <option>--encoding <replaceable>ENCODING</replaceable></option>
 292         </term>
 293         <listitem>
 294                 <para>
 295                         Allow to specify the encoding for the input.
 296                 </para>
 297         </listitem>
 298                 </varlistentry>
 299                 <varlistentry>
 300         <term>
 301                 <option>--param <replaceable>PARAMNAME</replaceable> <replaceable>PARAMVALUE</replaceable></option>
 302         </term>
 303         <listitem>
 304                 <para>
 305 Pass a parameter of name <replaceable>PARAMNAME</replaceable> and value
 306 <replaceable>PARAMVALUE</replaceable> to the stylesheet. You may pass
 307 multiple name/value pairs up to a maximum of 32. If the value being passed
 308 is a string, you can use <option>--stringparam</option> instead, to avoid
 309 additional quote characters that appear in string expressions. Note:
 310 the XPath expression must be UTF-8 encoded.
 311                 </para>
 312         </listitem>
 313                 </varlistentry>
 314
 315                 <varlistentry>
 316         <term><option>--path "<replaceable>PATH(S)</replaceable>"</option></term>
 317         <listitem>
 318                 <para>
 319                         Use the (space- or colon-separated) list of filesystem paths specified
 320                         by <replaceable>PATHS</replaceable> to load <acronym>DTD</acronym>s,
 321                         entities or documents. Enclose space-separated lists by quotation marks.
 322                 </para>
 323         </listitem>
 324                 </varlistentry>
 325
 326                 <varlistentry>
 327         <term><option>--profile</option> or <option>--norman</option></term>
 328         <listitem>
 329                 <para>
 330                         Output profiling information detailing the amount of time spent in
 331                         each part of the stylesheet. This is useful in optimizing stylesheet
 332                         performance.
 333                 </para>
 334         </listitem>
 335                 </varlistentry>
 336
 337                 <varlistentry>
 338         <term><option>--repeat</option></term>
 339         <listitem>
 340                 <para>Run the transformation 20 times. Used for timing tests.</para>
 341         </listitem>
 342                 </varlistentry>
 343
 344                 <varlistentry>
 345         <term>
 346                 <option>--stringparam <replaceable>PARAMNAME</replaceable> <replaceable>PARAMVALUE</replaceable></option>
 347         </term>
 348         <listitem>
 349                 <para>
 350                         Pass a parameter of name <replaceable>PARAMNAME</replaceable> and
 351                         value <replaceable>PARAMVALUE</replaceable>
 352                         where <replaceable>PARAMVALUE</replaceable> is a string rather than a
 353                         node identifier. <emphasis role="bold">Note:</emphasis> The string
 354                         must be UTF-8 encoded.
 355                 </para>
 356         </listitem>
 357                 </varlistentry>
 358
 359                 <varlistentry>
 360         <term><option>--timing</option></term>
 361         <listitem>
 362                 <para>
 363                         Display the time used for parsing the stylesheet, parsing the document
 364                         and applying the stylesheet and saving the result. Displayed in
 365                         milliseconds.
 366                 </para>
 367         </listitem>
 368                 </varlistentry>
 369
 370                 <varlistentry>
 371         <term><option>-v</option> or <option>--verbose</option></term>
 372         <listitem>
 373                 <para>
 374                         Output each step taken by &xsltproc; in processing the stylesheet
 375                         and the document.
 376                 </para>
 377         </listitem>
 378                 </varlistentry>
 379
 380                 <varlistentry>
 381         <term><option>-V</option> or <option>--version</option></term>
 382         <listitem>
 383                 <para>
 384                         Show the version of <citerefentry>
 385                         <refentrytitle>libxml</refentrytitle>
 386                         <manvolnum>3</manvolnum>
 387                 </citerefentry> and <citerefentry>
 388                         <refentrytitle>libxslt</refentrytitle>
 389                         <manvolnum>3</manvolnum>
 390                 </citerefentry> used.
 391                 </para>
 392         </listitem>
 393                 </varlistentry>
 394
 395                 <varlistentry>
 396         <term><option>--writesubtree <replaceable>PATH</replaceable></option></term>
 397         <listitem>
 398                 <para>
 399                         Allow file write only within the <replaceable>PATH</replaceable>
 400                         subtree.
 401                 </para>
 402         </listitem>
 403                 </varlistentry>
 404
 405                 <varlistentry>
 406         <term><option>--xinclude</option></term>
 407         <listitem>
 408                 <para>
 409                         Process the input document using the XInclude specification. More
 410                         details on this can be found in the XInclude
 411                         specification: <ulink url="http://www.w3.org/TR/xinclude/"/>
 412                 </para>
 413         </listitem>
 414                 </varlistentry>
 415
 416         </variablelist>
 417 </refsect1>
 418
 419 <refsect1 id="environment">
 420         <title>ENVIRONMENT</title>
 421         <variablelist>
 422
 423                 <varlistentry>
 424         <term><envar>SGML_CATALOG_FILES</envar></term>
 425         <listitem>
 426                 <para><acronym>SGML</acronym> catalog behavior can be changed by redirecting
 427                         queries to the user's own set of catalogs. This can be done by setting
 428                         the <envar>SGML_CATALOG_FILES</envar> environment variable to a list
 429                         of catalogs. An empty one should deactivate loading the
 430                         default <filename>/etc/sgml/catalog</filename> catalog.
 431                 </para>
 432         </listitem>
 433                 </varlistentry>
 434
 435                 <varlistentry>
 436         <term><envar>XML_CATALOG_FILES</envar></term>
 437         <listitem>
 438                 <para><acronym>XML</acronym> catalog behavior can be changed by redirecting
 439                         queries to the user's own set of catalogs. This can be done by setting
 440                         the <envar>XML_CATALOG_FILES</envar> environment variable to a list
 441                         of catalogs. An empty one should deactivate loading the
 442                         default <filename>/etc/xml/catalog</filename> catalog.
 443                 </para>
 444         </listitem>
 445                 </varlistentry>
 446
 447         </variablelist>
 448 </refsect1>
 449
 450 <refsect1 id="diagnostics">
 451         <title>DIAGNOSTICS</title>
 452         <para>
 453                 &xsltproc; return codes provide information that can be used when
 454                 calling it from scripts.
 455         </para>
 456         <variablelist>
 457
 458                 <varlistentry>
 459         <term><errorcode>0</errorcode></term>
 460         <listitem>
 461                 <para>No error (normal operation)</para>
 462         </listitem>
 463                 </varlistentry>
 464
 465                 <varlistentry>
 466         <term><errorcode>1</errorcode></term>
 467         <listitem>
 468                 <para>No argument</para>
 469         </listitem>
 470                 </varlistentry>
 471
 472                 <varlistentry>
 473         <term><errorcode>2</errorcode></term>
 474         <listitem>
 475                 <para>Too many parameters</para>
 476         </listitem>
 477                 </varlistentry>
 478
 479                 <varlistentry>
 480         <term><errorcode>3</errorcode></term>
 481         <listitem>
 482                 <para>Unknown option</para>
 483         </listitem>
 484                 </varlistentry>
 485
 486                 <varlistentry>
 487         <term><errorcode>4</errorcode></term>
 488         <listitem>
 489                 <para>Failed to parse the stylesheet</para>
 490         </listitem>
 491                 </varlistentry>
 492
 493                 <varlistentry>
 494         <term><errorcode>5</errorcode></term>
 495         <listitem>
 496                 <para>Error in the stylesheet</para>
 497         </listitem>
 498                 </varlistentry>
 499
 500                 <varlistentry>
 501         <term><errorcode>6</errorcode></term>
 502         <listitem>
 503                 <para>Error in one of the documents</para>
 504         </listitem>
 505                 </varlistentry>
 506
 507                 <varlistentry>
 508         <term><errorcode>7</errorcode></term>
 509         <listitem>
 510                 <para>Unsupported xsl:output method</para>
 511         </listitem>
 512                 </varlistentry>
 513
 514                 <varlistentry>
 515         <term><errorcode>8</errorcode></term>
 516         <listitem>
 517                 <para>String parameter contains both quote and double-quotes</para>
 518         </listitem>
 519                 </varlistentry>
 520
 521                 <varlistentry>
 522         <term><errorcode>9</errorcode></term>
 523         <listitem>
 524                 <para>Internal processing error</para>
 525         </listitem>
 526                 </varlistentry>
 527
 528                 <varlistentry>
 529         <term><errorcode>10</errorcode></term>
 530         <listitem>
 531                 <para>Processing was stopped by a terminating message</para>
 532         </listitem>
 533                 </varlistentry>
 534
 535                 <varlistentry>
 536         <term><errorcode>11</errorcode></term>
 537         <listitem>
 538                 <para>Could not write the result to the output file</para>
 539         </listitem>
 540                 </varlistentry>
 541
 542         </variablelist>
 543 </refsect1>
 544
 545 <refsect1 id="seealso">
 546         <title>SEE ALSO</title>
 547         <para><citerefentry>
 548                         <refentrytitle>libxml</refentrytitle>
 549                         <manvolnum>3</manvolnum>
 550                 </citerefentry>, <citerefentry>
 551                         <refentrytitle>libxslt</refentrytitle>
 552                         <manvolnum>3</manvolnum>
 553                 </citerefentry>
 554         </para>
 555         <para>
 556                 More information can be found at
 557                 <itemizedlist>
 558                         <listitem>
 559                                 <para><citerefentry>
 560                                                 <refentrytitle>libxml</refentrytitle>
 561                                                 <manvolnum>3</manvolnum>
 562                                         </citerefentry> web page <ulink url="http://www.xmlsoft.org/"/>
 563                                 </para>
 564                         </listitem>
 565                         <listitem>
 566                                 <para>W3C <acronym>XSLT</acronym> page <ulink url="http://www.w3.org/TR/xslt"/>
 567                                 </para>
 568                         </listitem>
 569                 </itemizedlist>
 570         </para>
 571 </refsect1>
 572
 573 </refentry>