2004
Colin Adams and others
Colin
Adams
colin@colina.demon.co.uk Sunday, September 5th, 2004

# &title;

# How to invoke &program_name;

&program_name_cased; is invoked from the command line. The general form is:

- &program_name; --help

- &program_name; --version

- &program_name; [--file=|--uri=]stylesheet [--file=|--uri=]source-document (--options)* (string-parameter)*

- &program_name; stylesheet --template=template-name (--options)* (string-parameter)*

- &program_name; --use-pi [(--pi-options)*] [--file=|--uri=]source-document (--options)* (string-parameter)*

# Stylesheet and source documents

The stylesheet and source documents can be written either as URIs or as names in the local file system. &program_name_cased; will attempt to convert a local file name into a URI, if it detects such a name is not already a URI.

If you want to use a file name that starts with --, or includes = as a character in the name, or might look to the system like a URI (e.g. if http://foo/bar is a valid file name on your system), then you can force &program_name; to interpret it as a file name by writing it as --file=my/file.name.

If you want to ensure that &program_name; treats a name as a URI (necessary if it starts with -- or includes =), then you can write it as --uri=my:strange=uri.

## Fragment identifiers

If the URI for a source document includes a fragment identifier, then &program_name; will parse the document as normal, but will attempt to set the initial context node to be that specified by the fragment (according to the semantics for the particular media type). Note, that in this case, the initial context node will not necessarily match the pattern /, so the initial template may vary according to the fragment identifier. Note also, that the document root and document element are exactly the same nodes as they would be if no fragment identifier is supplied.

&program_name_cased; recognizes the following media types:

- application/xhtml+xml

- application/xslt+xml

- application/xml

- application/xml-external-parsed-entity

- application/*+xml

  This is treated according to the rules for application/xml, if no more specific rule is present.

- text/xml

- text/xml-external-parsed-entity

If the resolver is unable to supply the media type, then application/xml is assumed, except for stylesheet modules, where application/xslt+xml is assumed (since the latter is defined to have identical fragment identifier semantics to the former, there is no significance to this difference).

Only shorthand pointers are supported for stylesheets. In this case, the shorthand pointer must point to an ID attribute (and the DTD must be available), or an xml:id attribute, on the xsl:transform or xsl:stylesheet element.

# Parameters

To set a global parameter on a stylesheet (as defined by a top-level xsl:param declaration), you may set it via an option. However, &program_name; provides a more convenient syntax for the most common usage pattern, string-valued parameters:

- name=value

- name='value with embedded blanks'

Note that single quotes are only needed to avoid mis-interpretation by the command shell.

These string parameters may, in principle, appear anywhere within the command line, although it is conventional to put them at the end.

If you wish to pass general XPath expressions to the stylesheet, you have to use the --xpath-param option.

# Options

The following is a list of the options that can be given on the command-line:

## Stylesheet control

The following options control stylesheet execution:

--use-pi

  Interpret the first file or URI argument as a source document, rather than a stylesheet. Search for one or more xml-stylesheet processing instructions within that source document, and use them to find the stylesheet.

  &program_name_cased; has to parse the source document twice. Once to find the processing instruction, and again, after the stylesheet has been compiled (as it may contain xsl:preserve-space or xsl:strip-space commands). Although the first parse is quick (as the processing instruction must occur in the prolog of the XML document), this does mean that a stream that can only be read once may not be used with this option.

  There are additional options that further control the interpretation of the xml-stylesheet processing instructions:

  --medium={medium-name}

    The target medium. This must be a single word, consisting solely of the characters [a-z][A-z][0-9][-]. Only processing instructions that contain this medium name (or the special name "all") within their media pseudo-attribute will be selected. The default is "screen", both for this parameter and the processing instruction media pseudo-attribute. Case is significant. The word "all" is not permitted.

  --title={preference}

    The preferred style. This may be any text string (leading and trailing double quotes will be removed, so you may include spaces). Only processing instructions that have this style name for their title pseudo-attribute will be selected, along with any persistent stylesheets (those that do not specify the title pseudo-attribute). If this parameter is omitted, then the first preferred stylesheet for the medium (that is, one that supplies the title pseudo-attribute and does not supply the alternate pseudo-attribute with a value of "yes") will also be selected. Case is significant.

--output=<local-file-name>

  Names the destination for the transformation results. If omitted, the results are written to the standard output stream.

--mode=[{<namespace-uri>}]<local-name>

  Specifies an initial mode. If the name is not in the default namespace, then enclose the namespace URI in curly brackets, preceding the local name.

  If this parameter is omitted (the usual situation), then the default mode is used.

--template=[{<namespace-uri>}]<local-name>

  Specifies a named template to be invoked. If the name is not in the default namespace, then enclose the namespace URI in curly brackets, preceding the local name.

  If this parameter is omitted (the usual situation), then the initial template is the one that matches the document node of the source document. If this parameter is supplied, then the source document may be omitted.

--param=<name>=<string-value>

  Sets a string-valued global parameter on the stylesheet. Enclose the value in single quotes if it includes embedded blanks.

--xpath-param=<name>=<XPath expression>

  Sets a global parameter on the stylesheet, passing an XPath expression as the value. Enclose the value in single quotes if it includes embedded blanks.

  You cannot use this option if you also supply the --template=<initial-template-name> option, and omit the source document, as then the XPath expression will have no context.

## Tracing

The following options control stylesheet execution tracing:

--trace[=<trace-file>]

  Turn on stylesheet tracing.

  Set the destination for trace output to be "trace-file". If "trace-file" is omitted, then trace output is sent to the standard output stream.

  If neither this option nor the timed-trace option is given, then no trace output is produced.

--timed-trace[=<trace-file>]

  Turn on stylesheet tracing with timings.

  Set the destination for trace output to be "trace-file". If "trace-file" is omitted, then trace output is sent to the standard output stream.

--suppress-xpath-tracing

  Suppress output from the XPath fn:trace() function.

## Errors and warnings

The following options control issuing of error and warning messages:

--secure

  Operate in secure mode. Any attempt by an xsl:document instruction to write to any destination other than the standard output stream or an in-memory string will result in a fatal error.

--warnings=[<warning-file>]

  Set the destination for warnings to be "warning-file". If "warning-file" is omitted, then all warning messages are ignored.

  If this parameter is not given, then warnings are sent to the standard error stream.

--errors=[<error-file>]

  Set the destination for error messages to be "error-file". If "error-file" is omitted, then all error messages are ignored.

  If this parameter is not given, then error messages are sent to the standard error stream.

--errors-and-warnings=[<error-file>]

  Set the destination for both error and warning messages to be "error-file". If "error-file" is omitted, then all such messages are ignored.

--no-line-numbers

  By default, diagnostics will include the line number where the error was detected. This option turns off this facility.

--warning-threshold=<number>

  Do not display any warning messages once more than <number> warnings have been displayed. The default value is 25.

  Setting this value to a negative number means that all warning messages will be displayed. Setting it to zero means that no warning messages will ever be displayed.

--treat-warnings-as-errors

  Treat warnings as if they were recoverable errors.

--recover-silently

  When a recoverable error occurs, take the appropriate recovery action, but do not issue any diagnostic message.

  The default is to take the appropriate recovery action and issue a diagnostic message.

--do-not-recover

  Treat all recoverable errors as fatal errors.

  The default is to take the appropriate recovery action and issue a diagnostic message.

--error-threshold=<number>

  Do not display any messages for recoverable errors once more than <number> recoverable errors have been displayed. The default value is 25.

  Setting this value to a negative number means that all recoverable error messages will be displayed.

## OASIS Entity Resolution Technical Committee XML catalogs

The following options control the use of OASIS ETRC XML catalogs

--no-catalogs

  Do not use OASIS ERTC XML catalogs for entity resolution or URI reference resolution.

--no-default-catalog

  Do not use the system default catalog.

  In this case, only catalogs specified in `XM_CATALOG_FILES`, plus any per-document-catalogs named in oasis-xml-catalog processing instructions, are searched.

--prefer-system

  Prefer SYSTEM ids to PUBLIC ids when both are given. The catalog resolver only attempts to match on PUBLIC ids when there is either no SYSTEM id given, or else the catalog resolver fails to find a match for the SYSTEM id.

  In the latter case, when this option is given, PUBLIC entries are only considered for a match if they were defined when prefer="system" was in effect.

  The default is to always consider PUBLIC ids, when no match is found for the SYSTEM id.

  If no SYSTEM id is given, then this option has no effect.

--no-catalog-pi

  Ignore any oasis-xml-catalog processing instructions in source documents and stylesheets.

--catalog-debug-level=<0-10>

  Set the level of debugging messages produced by the catalog resolver. 0 means no messages. 10 Means maximum verbosity.

## Performance

The following options are available for performance tuning:

--no-gc

  Disables garbage collection. This might improve performance under some circumstances. Or it might make it worse.

--tiny-tree

  The source document is built using the tiny-tree model, rather than the standard tree model. This saves on memory, but will usually result in slower execution, except for very simple tranformations, such as the identity transform, where it may actually improve execution speed.

  This seems to have a memory leak at the moment, so it is probably best to avoid using it.

## Media types and URI fragment identifiers

The following options affect the mapping of URIs onto media-types, for interpretation of fragment identifies:

--no-xpointer

  Don't use XPointer for XML media types.

  In the case of application/xhtml+xml, this will result in fragment identifiers being interpreted as the value of any ID-valued attribute.

  For other XML media types, this will result in recoverable error XT1160, as RFC 2376 does not assign a meaning to the fragment identifier.

--html-text-ok

  By default, &program_name; assumes that a web server is serving up XHTML documents as media type text/html (to get round the fact that MSIE does not recognize application/xhtml+xml). So if it sees a media type of text/html, it pretends that it is actually application/xhtml+xml. Using this option means it respects the media type is really text/html. The result is that this is a media type that the program chooses not to recognize, so you will get recoverable error XT1160.

  Without this option, it might be argued that &program_name; is non-compliant. Apart from that, it doesn't serve any useful purpose.

# Extensions

The following options control the availability of extensions:

--no-output-extensions

  Disables use of QNames for the value of the xsl:output method attribute.

# Miscellaneous

--no-network-protocols

  Disables use of any URI schemes that imply access to the outside world (e.g. `http`, `ftp` and `telnet`) that might otherwise be registered.

&additional_options;