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