Stylesheet and source documents
The stylesheet and source documents can be written either as URIs or as names in the local file system.
Gexslt 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 gexslt to interpret it as a file name by writing it as --file=my/file.name.
If you want to ensure that gexslt 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 gexslt 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.
Gexslt recognizes the following media types:
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, gexslt 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.
Gexslt 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. This is a QName. If the name is qualified by a prefix within the
stylesheet, then prefix the local name with the namespace URI followed by #.
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. This is a QName. If the name is qualified by a prefix within the
stylesheet, then prefix the local name with the namespace URI followed by #.
If this parameter is omitted (the usual situation), then the initial template is the one
that matches the initial context node, normally the document node, of the source document. If this parameter is supplied,
then the source document may be omitted.
- --context=<name>=<XPath expression>
-
Specifies an XPath expression to be applied to the source document in order to determine the initial context node.
This
parameter must be omitted if a source document is not supplied. It is a non-recoverable error is the supplied expression
does not select a single node.
If this parameter is omitted (the usual situation), then the initial context node is the document node of the source
document.
- --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.
- --default-template-warning
-
Issues a warning message when a built-in template is invoked.
The default-template-warning and suppress-default-action options
are mutually exclusive. If both are selected, one will be arbitrarily ignored.
- --suppress-default-action
-
Suppresses all invocations of built-in templates.
Use of this option gives non-compliant behaviour.
The default-template-warning and suppress-default-action options
are mutually exclusive. If both are selected, one will be arbitrarily ignored.
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.
The intention is to save memory when processing very large files.
- --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 by the environment variable 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 often result
in slower execution. But with some tranformations, such as the
identity transform, it may actually improve execution speed.
- --report-document-statistics
-
Report statistics about the source document (and for each document read by the doc()
and document() functions). This only applies when the tiny-tree option is selected.
This option is useful for choosing values for the nodes, attributes, namespaces and characters options.
- --nodes=[estimated-node-count]
-
The estimated number of nodes (excluding attributes and namespaces) in the source document (and for each document read
by the doc()
and document() functions). This only applies when the tiny-tree option is selected.
If omitted, this defaults to 4000.
- --attributes=[estimated-attribute-count]
-
The estimated number of attributes in the source document (and for each document read by the doc()
and document() functions). This only applies when the tiny-tree option is selected.
If omitted, this defaults to 100.
- --namespaces=[estimated-namespace-count]
-
The estimated number of namespaces in the source document (and for each document read by the doc()
and document() functions). This only applies when the tiny-tree option is selected.
If omitted, this defaults to 20.
- --characters=[estimated-character-count]
-
The estimated number of content characters in the source document (and for each document read by the doc()
and document() functions). This only applies when the tiny-tree option is selected.
If omitted, this defaults to 4000.
Media types and URI fragment identifiers
The following options affect the mapping of URIs onto media-types, for interpretation of fragment identifies:
- --html-text-ok
-
By default, gexslt 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 as text/html.
The result is that this is a media type that the program chooses not to recognize, so you will
get recoverable error XTRE1160.
Without this option, it might be argued that gexslt is non-compliant. Apart from that,
it doesn't serve any useful purpose.
