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>--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 </refsect1>
 137
 138 <refsect1 id="options">
 139         <title>OPTIONS</title>
 140         <para>
 141                 &xsltproc; accepts the following options (in alphabetical order):
 142         </para>
 143         <variablelist>
 144
 145                 <varlistentry>
 146         <term><option>--catalogs</option></term>
 147         <listitem>
 148                 <para>
 149                         Use the <acronym>SGML</acronym> catalog specified
 150                         in <envar>SGML_CATALOG_FILES</envar> to resolve the location of
 151                         external entities. By default, &xsltproc; looks for the catalog
 152                         specified in <envar>XML_CATALOG_FILES</envar>. If that is not
 153                         specified, it uses <filename>/etc/xml/catalog</filename>.
 154                 </para>
 155         </listitem>
 156                 </varlistentry>
 157
 158                 <varlistentry>
 159         <term><option>--debug</option></term>
 160         <listitem>
 161                 <para>
 162                         Output an <acronym>XML</acronym> tree of the transformed document
 163                         for debugging purposes.
 164                 </para>
 165         </listitem>
 166                 </varlistentry>
 167
 168                 <varlistentry>
 169         <term><option>--dumpextensions</option></term>
 170         <listitem>
 171                 <para>
 172                         Dumps the list of all registered extensions
 173                         on <filename class="devicefile">stdout</filename>.
 174                 </para>
 175         </listitem>
 176                 </varlistentry>
 177
 178                 <varlistentry>
 179         <term><option>--html</option></term>
 180         <listitem>
 181                 <para>The input document is an <acronym>HTML</acronym> file.</para>
 182         </listitem>
 183                 </varlistentry>
 184
 185                 <varlistentry>
 186         <term><option>--load-trace</option></term>
 187         <listitem>
 188                 <para>
 189                         Display all the documents loaded during the processing
 190                         to <filename class="devicefile">stderr</filename>.
 191                 </para>
 192         </listitem>
 193                 </varlistentry>
 194
 195                 <varlistentry>
 196         <term><option>--maxdepth <replaceable>VALUE</replaceable></option></term>
 197         <listitem>
 198                 <para>
 199                         Adjust the maximum depth of the template stack
 200                         before <citerefentry>
 201                         <refentrytitle>libxslt</refentrytitle>
 202                         <manvolnum>3</manvolnum>
 203                 </citerefentry> concludes it is in an infinite loop. The default is 500.
 204                 </para>
 205         </listitem>
 206                 </varlistentry>
 207
 208                 <varlistentry>
 209         <term><option>--nodtdattr</option></term>
 210         <listitem>
 211                 <para>
 212                         Do not apply default attributes from the
 213                         document's <acronym>DTD</acronym>.
 214                 </para>
 215         </listitem>
 216                 </varlistentry>
 217
 218                 <varlistentry>
 219         <term><option>--nomkdir</option></term>
 220         <listitem>
 221                 <para>Refuses to create directories.</para>
 222         </listitem>
 223                 </varlistentry>
 224
 225                 <varlistentry>
 226         <term><option>--nonet</option></term>
 227         <listitem>
 228                 <para>
 229                         Do not use the Internet to fetch <acronym>DTD</acronym>s, entities
 230                         or documents.
 231                 </para>
 232         </listitem>
 233                 </varlistentry>
 234
 235                 <varlistentry>
 236         <term><option>--noout</option></term>
 237         <listitem>
 238                 <para>Do not output the result.</para>
 239         </listitem>
 240                 </varlistentry>
 241
 242                 <varlistentry>
 243         <term><option>--novalid</option></term>
 244         <listitem>
 245                 <para>Skip loading the document's <acronym>DTD</acronym>.</para>
 246         </listitem>
 247                 </varlistentry>
 248
 249                 <varlistentry>
 250         <term><option>--nowrite</option></term>
 251         <listitem>
 252                 <para>Refuses to write to any file or resource.</para>
 253         </listitem>
 254                 </varlistentry>
 255
 256                 <varlistentry>
 257         <term>
 258                 <option>-o</option> or <option>--output</option>
 259                  <replaceable>FILE</replaceable> | <replaceable>DIRECTORY</replaceable>
 260         </term>
 261         <listitem>
 262                 <para>
 263                         Direct output to the given <replaceable>FILE</replaceable>. Using
 264                         the option with a <replaceable>DIRECTORY</replaceable> directs the
 265                         output files to the specified directory. This can be
 266                         useful for multiple outputs (also known as "chunking") or manpage
 267                         processing.
 268                 </para>
 269                 <important>
 270                         <para>
 271                                 The given directory <emphasis role="bold">must</emphasis> already exist.
 272                         </para>
 273                 </important>
 274                 <note>
 275                         <para>
 276                                 Make sure that <replaceable>FILE</replaceable>
 277                                 and <replaceable>DIRECTORY</replaceable> follow the <quote>URI reference
 278                                 computation</quote> as described in RFC 2396 and laters. This means, that
 279                                 e.g. <option>-o directory</option> will maybe not work,
 280                                 but <option>-o directory/</option> will.
 281                         </para>
 282                 </note>
 283         </listitem>
 284                 </varlistentry>
 285
 286                 <varlistentry>
 287         <term>
 288                 <option>--param <replaceable>PARAMNAME</replaceable> <replaceable>PARAMVALUE</replaceable></option>
 289         </term>
 290         <listitem>
 291                 <para>
 292                         Pass a parameter of name <replaceable>PARAMNAME</replaceable> and
 293                         value <replaceable>PARAMVALUE</replaceable> to the stylesheet. You
 294                         may pass multiple name/value pairs up to a maximum of 32. If the
 295                         value being passed is a string rather than a node identifier,
 296                         use <option>--stringparam</option> instead.
 297                 </para>
 298         </listitem>
 299                 </varlistentry>
 300
 301                 <varlistentry>
 302         <term><option>--path "<replaceable>PATH(S)</replaceable>"</option></term>
 303         <listitem>
 304                 <para>
 305                         Use the (space- or colon-separated) list of filesystem paths specified
 306                         by <replaceable>PATHS</replaceable> to load <acronym>DTD</acronym>s,
 307                         entities or documents. Enclose space-separated lists by quotation marks.
 308                 </para>
 309         </listitem>
 310                 </varlistentry>
 311
 312                 <varlistentry>
 313         <term><option>--profile</option> or <option>--norman</option></term>
 314         <listitem>
 315                 <para>
 316                         Output profiling information detailing the amount of time spent in
 317                         each part of the stylesheet. This is useful in optimizing stylesheet
 318                         performance.
 319                 </para>
 320         </listitem>
 321                 </varlistentry>
 322
 323                 <varlistentry>
 324         <term><option>--repeat</option></term>
 325         <listitem>
 326                 <para>Run the transformation 20 times. Used for timing tests.</para>
 327         </listitem>
 328                 </varlistentry>
 329
 330                 <varlistentry>
 331         <term>
 332                 <option>--stringparam <replaceable>PARAMNAME</replaceable> <replaceable>PARAMVALUE</replaceable></option>
 333         </term>
 334         <listitem>
 335                 <para>
 336                         Pass a parameter of name <replaceable>PARAMNAME</replaceable> and
 337                         value <replaceable>PARAMVALUE</replaceable>
 338                         where <replaceable>PARAMVALUE</replaceable> is a string rather than a
 339                         node identifier. <emphasis role="bold">Note:</emphasis> The string
 340                         must be UTF-8 encoded.
 341                 </para>
 342         </listitem>
 343                 </varlistentry>
 344
 345                 <varlistentry>
 346         <term><option>--timing</option></term>
 347         <listitem>
 348                 <para>
 349                         Display the time used for parsing the stylesheet, parsing the document
 350                         and applying the stylesheet and saving the result. Displayed in
 351                         milliseconds.
 352                 </para>
 353         </listitem>
 354                 </varlistentry>
 355
 356                 <varlistentry>
 357         <term><option>-v</option> or <option>--verbose</option></term>
 358         <listitem>
 359                 <para>
 360                         Output each step taken by &xsltproc; in processing the stylesheet
 361                         and the document.
 362                 </para>
 363         </listitem>
 364                 </varlistentry>
 365
 366                 <varlistentry>
 367         <term><option>-V</option> or <option>--version</option></term>
 368         <listitem>
 369                 <para>
 370                         Show the version of <citerefentry>
 371                         <refentrytitle>libxml</refentrytitle>
 372                         <manvolnum>3</manvolnum>
 373                 </citerefentry> and <citerefentry>
 374                         <refentrytitle>libxslt</refentrytitle>
 375                         <manvolnum>3</manvolnum>
 376                 </citerefentry> used.
 377                 </para>
 378         </listitem>
 379                 </varlistentry>
 380
 381                 <varlistentry>
 382         <term><option>--writesubtree <replaceable>PATH</replaceable></option></term>
 383         <listitem>
 384                 <para>
 385                         Allow file write only within the <replaceable>PATH</replaceable>
 386                         subtree.
 387                 </para>
 388         </listitem>
 389                 </varlistentry>
 390
 391                 <varlistentry>
 392         <term><option>--xinclude</option></term>
 393         <listitem>
 394                 <para>
 395                         Process the input document using the XInclude specification. More
 396                         details on this can be found in the XInclude
 397                         specification: <ulink url="http://www.w3.org/TR/xinclude/"/>
 398                 </para>
 399         </listitem>
 400                 </varlistentry>
 401
 402         </variablelist>
 403 </refsect1>
 404
 405 <refsect1 id="environment">
 406         <title>ENVIRONMENT</title>
 407         <variablelist>
 408
 409                 <varlistentry>
 410         <term><envar>SGML_CATALOG_FILES</envar></term>
 411         <listitem>
 412                 <para><acronym>SGML</acronym> catalog behavior can be changed by redirecting
 413                         queries to the user's own set of catalogs. This can be done by setting
 414                         the <envar>SGML_CATALOG_FILES</envar> environment variable to a list
 415                         of catalogs. An empty one should deactivate loading the
 416                         default <filename>/etc/sgml/catalog</filename> catalog.
 417                 </para>
 418         </listitem>
 419                 </varlistentry>
 420
 421                 <varlistentry>
 422         <term><envar>XML_CATALOG_FILES</envar></term>
 423         <listitem>
 424                 <para><acronym>XML</acronym> catalog behavior can be changed by redirecting
 425                         queries to the user's 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> 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; 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><citerefentry>
 527                         <refentrytitle>libxml</refentrytitle>
 528                         <manvolnum>3</manvolnum>
 529                 </citerefentry>, <citerefentry>
 530                         <refentrytitle>libxslt</refentrytitle>
 531                         <manvolnum>3</manvolnum>
 532                 </citerefentry>
 533         </para>
 534         <para>
 535                 More information can be found at
 536                 <itemizedlist>
 537                         <listitem>
 538                                 <para><citerefentry>
 539                                                 <refentrytitle>libxml</refentrytitle>
 540                                                 <manvolnum>3</manvolnum>
 541                                         </citerefentry> web page <ulink url="http://www.xmlsoft.org/"/>
 542                                 </para>
 543                         </listitem>
 544                         <listitem>
 545                                 <para>W3C <acronym>XSLT</acronym> page <ulink url="http://www.w3.org/TR/xslt"/>
 546                                 </para>
 547                         </listitem>
 548                 </itemizedlist>
 549         </para>
 550 </refsect1>
 551
 552 </refentry>