758 lines
32 KiB
Plaintext
758 lines
32 KiB
Plaintext
|
=encoding utf8
|
|||
|
|
|||
|
=head1 NAME
|
|||
|
|
|||
|
saxon10 - Saxon XSLT 3.0 processor
|
|||
|
|
|||
|
=head1 SYNOPSIS
|
|||
|
|
|||
|
saxon10 [I<options>] [I<params>]
|
|||
|
|
|||
|
=head1 DESCRIPTION
|
|||
|
|
|||
|
An XSLT processor, which can be used from the command line, or invoked from an
|
|||
|
application, using a supplied API. Saxon implements the XSLT 3.0
|
|||
|
Recommendation. The product can also be used to run XSLT 2.0 stylesheets, or
|
|||
|
XSLT 1.0 stylesheets in backwards compatibility mode.
|
|||
|
|
|||
|
=head1 OPTIONS
|
|||
|
|
|||
|
=over
|
|||
|
|
|||
|
=item B<-a>[:(C<on>|C<off>)]
|
|||
|
|
|||
|
Use the xml-stylesheet processing instruction in the source document to
|
|||
|
identify the stylesheet to be used. The stylesheet argument must not be present
|
|||
|
on the command line. For more details see L<Using the B<-a>
|
|||
|
option|https://www.saxonica.com/documentation10/index.html#!using-xsl/commandline/aoption>.
|
|||
|
|
|||
|
=item B<-catalog>:I<filenames>
|
|||
|
|
|||
|
|
|||
|
I<filenames> is either a file name or a list of file names separated by
|
|||
|
semicolons; the files are OASIS XML catalogs used to define how public
|
|||
|
identifiers and system identifiers (URIs) used in a source document,
|
|||
|
stylesheet, or schema are to be redirected, typically to resources available
|
|||
|
locally. For more details see L<Using XML
|
|||
|
Catalogs|https://www.saxonica.com/documentation10/index.html#!sourcedocs/xml-catalogs>.
|
|||
|
|
|||
|
=item B<-config>:I<filename>
|
|||
|
|
|||
|
Indicates that configuration information should be taken from the supplied
|
|||
|
L<configuration
|
|||
|
file|https://www.saxonica.com/documentation10/index.html#!configuration/configuration-file>.
|
|||
|
Any options supplied on the command line override options specified in the
|
|||
|
configuration file.
|
|||
|
|
|||
|
=item B<-dtd>:(C<on>|C<off>|C<recover>)
|
|||
|
|
|||
|
Setting B<-dtd>:C<on> requests DTD-based validation of the source file and of
|
|||
|
any files read using the C<document()> function. Requires an XML parser that
|
|||
|
supports validation. The setting B<-dtd>:C<off> (which is the default)
|
|||
|
suppresses DTD validation. The setting B<-dtd>:C<recover> performs DTD
|
|||
|
validation but treats the error as non-fatal if it fails. Note that any
|
|||
|
external DTD is likely to be read even if not used for validation, because DTDs
|
|||
|
can contain definitions of entities.
|
|||
|
|
|||
|
=item B<-ea>:(C<on>|C<off>)
|
|||
|
|
|||
|
Setting B<-ea>:C<on> enables assertions both at compile time and at run time.
|
|||
|
Assertions (defined using the XSLT 3.0 C<xsl:assert> instruction) are disabled
|
|||
|
by default at compile time, and enabled by default at run-time provided they
|
|||
|
were enabled at compile time.
|
|||
|
|
|||
|
=item B<-expand>:(C<on>|C<off>)
|
|||
|
|
|||
|
Normally, if validation using a DTD or schema is requested, any fixed or
|
|||
|
default values defined in the DTD or schema will be expanded. Specifying
|
|||
|
B<-expand>:C<off> suppresses this. (In the case of DTD-defined defaults, this
|
|||
|
might not work with all XML parsers. It does work with the Xerces parser
|
|||
|
(default for Java) and the Microsoft parser (default for .NET).)
|
|||
|
|
|||
|
=item B<-explain>[:I<filename>]
|
|||
|
|
|||
|
Display an execution plan and other diagnostic information for the stylesheet.
|
|||
|
This is a representation of the expression tree after rewriting by the
|
|||
|
optimizer. It combines the XSLT instructions and the XPath expressions into a
|
|||
|
single tree. If no file name is specified the output is sent to the standard
|
|||
|
error stream. The output is in XML format.
|
|||
|
|
|||
|
=item B<-export>:I<filename>
|
|||
|
|
|||
|
Export the compiled stylesheet, in a form suitable for subsequent execution.
|
|||
|
For more details, see L<Compiling a
|
|||
|
Stylesheet|https://www.saxonica.com/documentation10/index.html#!using-xsl/compiling>.
|
|||
|
|
|||
|
=item B<-ext>:(C<on>|C<off>)
|
|||
|
|
|||
|
If B<-ext>:C<off> is specified, suppress calls on dynamically-loaded external
|
|||
|
Java functions. This does not affect calls on integrated extension functions,
|
|||
|
including Saxon and EXSLT extension functions. This option is useful when
|
|||
|
loading an untrusted stylesheet, perhaps from a remote site using an C<http://>
|
|||
|
URL; it ensures that the stylesheet cannot call arbitrary Java methods and
|
|||
|
thereby gain privileged access to resources on your machine.
|
|||
|
|
|||
|
=item B<-im>:I<modename>
|
|||
|
|
|||
|
Selects the initial mode for the transformation. If this is namespaced, it can
|
|||
|
be written as {I<uri>}I<localname>.
|
|||
|
|
|||
|
=item B<-init>:I<initializer>
|
|||
|
|
|||
|
The value is the name of a user-supplied class that implements the interface
|
|||
|
C<Initializer>; this initializer will be called during the initialization
|
|||
|
process, and may be used to set any options required on the C<Configuration>
|
|||
|
programmatically.
|
|||
|
|
|||
|
=item B<-it>[:I<template-name>]
|
|||
|
|
|||
|
Selects the initial named template to be executed. If this is namespaced, it
|
|||
|
can be written as {uri}localname. If the template name is omitted, the default
|
|||
|
is C<xsl:initial-template>. When this option is used, you do not need to supply
|
|||
|
a source file, but if you do, you must supply it using the B<-s> option.
|
|||
|
|
|||
|
=item B<-jit>:(C<on>|C<off>)
|
|||
|
|
|||
|
Determines whether just-in-time compilation of template rules is in force. The
|
|||
|
default is on, unless the nogo or explain option is set. When JIT is enabled,
|
|||
|
the body of a template rule is not compiled until the rule first fires. This
|
|||
|
gives faster compilation when a stylesheet has been written to handle a large
|
|||
|
XML vocabulary, but the source document only uses a fraction of the vocabulary.
|
|||
|
The drawback is that static errors in the stylesheet may go undetected.
|
|||
|
|
|||
|
=item B<-l>[:(C<on>|C<off>)]
|
|||
|
|
|||
|
If B<-l> or B<-l>:C<on> is specified, causes line and column numbers to be
|
|||
|
maintained for source documents. These are accessible using the extension
|
|||
|
functions C<saxon:line-number()> and C<saxon:column-number()>. Line numbers are
|
|||
|
useful when the purpose of the stylesheet is to find errors or anomalies in the
|
|||
|
source XML file. Without this option, line numbers are available while source
|
|||
|
documents are being parsed and validated, but they are not retained in the tree
|
|||
|
representation of the document.
|
|||
|
|
|||
|
=item B<-lib>:I<filenames>
|
|||
|
|
|||
|
A list of filenames containing library packages. The filenames are separated by
|
|||
|
“C<;>” on Windows systems, or “C<:>” on Linux and Mac. Each filename must
|
|||
|
identify either (a) a top-level module in a source XSLT package, or (b) a SEF
|
|||
|
file containing an exported library package. There is no constraint on the
|
|||
|
order of the packages.
|
|||
|
|
|||
|
=item B<-license>:(C<on>|C<off>)
|
|||
|
|
|||
|
Relevant only when SaxonJ-PE or SaxonJ-EE software is loaded. By default, Saxon
|
|||
|
will look for a license and report a warning if none is found, which escalates
|
|||
|
to a fatal error if licenseable features (such as schema-awareness) are used.
|
|||
|
If B<-license>:C<off> is specified, Saxon will not look for a license unless it
|
|||
|
is needed, and will fall back silently if none is found (this means that the
|
|||
|
transformation might succeed, but without taking advantage of Saxon-EE
|
|||
|
optimizations). The option B<-license>:C<off> is useful to suppress warnings in
|
|||
|
the case where it is known that a compiled stylesheet containing an embedded
|
|||
|
license key is being executed.
|
|||
|
|
|||
|
=item B<-m>:I<classname>
|
|||
|
|
|||
|
Use the specified C<Receiver> to process the output from C<xsl:message>. The
|
|||
|
class must implement the C<Receiver> interface, and it must have a public
|
|||
|
zero-argument constructor. This interface is similar to a SAX ContentHandler,
|
|||
|
it takes a stream of events to generate output. In general the content of a
|
|||
|
message is an XML fragment. By default the standard XML emitter is used,
|
|||
|
configured to write to the standard error stream, and to include no XML
|
|||
|
declaration.
|
|||
|
|
|||
|
Each message is output as a new document. The sequence of calls to this
|
|||
|
Receiver is as follows: there is a single C<open()> call at the start of the
|
|||
|
transformation, and a single C<close()> call at the end; and each evaluation of
|
|||
|
an C<xsl:message> instruction starts with a C<startDocument()> call and ends
|
|||
|
with C<endDocument()>. The C<startDocument()> event has a properties argument
|
|||
|
indicating whether C<terminate="yes"> was specified, and the locationId on
|
|||
|
calls such as C<startElement()> and C<characters()> can be used to identify the
|
|||
|
location in the stylesheet where the message data originated (this is achieved
|
|||
|
by passing the supplied C<locationId> in a call to
|
|||
|
C<getPipelineConfiguration().getLocator().getSystemId(locationId)>, or to
|
|||
|
C<getLineNumber()> on the same object).
|
|||
|
|
|||
|
Select the class C<MessageWarner> to have C<xsl:message> output notified to the
|
|||
|
JAXP ErrorListener, as described in the JAXP documentation.
|
|||
|
|
|||
|
=item B<-nogo>
|
|||
|
|
|||
|
If set, the stylesheet is analysed for errors, and any requested B<-explain> or
|
|||
|
B<-export> output is generated, but the stylesheet is not executed.
|
|||
|
|
|||
|
=item B<-now>:I<yyyy-mm-ddThh:mm:ss+hh:mm>
|
|||
|
|
|||
|
Sets the value of C<current-dateTime()> (and C<implicit-timezone()>) for the
|
|||
|
transformation. This is designed for testing, to enable repeatable results to
|
|||
|
be obtained for comparison with reference results, or to test that stylesheets
|
|||
|
can handle significant dates and times such as end-of-year processing.
|
|||
|
|
|||
|
=item B<-ns>:(C<uri>|C<##any>|C<##html5>)
|
|||
|
|
|||
|
Defines the handling of unprefixed element names appearing as name tests in
|
|||
|
path expressions and match patterns in the stylesheet.
|
|||
|
|
|||
|
=over
|
|||
|
|
|||
|
=item ·
|
|||
|
|
|||
|
Supplying a URI sets the default namespace for elements and types (effectively
|
|||
|
a default value for C<xpath-default-namespace> — note that an explicit value
|
|||
|
for this attribute takes precedence).
|
|||
|
|
|||
|
=item ·
|
|||
|
|
|||
|
The value C<##any> declares that unprefixed names are treated as a test on the
|
|||
|
local name of the element only: they will match regardless of namespace.
|
|||
|
|
|||
|
=item ·
|
|||
|
|
|||
|
The value C<##html5> declares that an unprefixed element name will match either
|
|||
|
a name in the XHTML namespace, or a name in no namespace. This option is
|
|||
|
intended primarily for use when generating stylesheets to run under Saxon-JS in
|
|||
|
the browser, since the resulting behavior is close to that defined by the
|
|||
|
special rules in the HTML5 specification for XSLT and XPath running against an
|
|||
|
HTML5 DOM.
|
|||
|
|
|||
|
=back
|
|||
|
|
|||
|
=item B<-o>:I<filename>
|
|||
|
|
|||
|
Send output to named file.
|
|||
|
|
|||
|
If the source (B<-s>) argument identifies a directory, this option is mandatory
|
|||
|
and must also identify a directory; on completion it will contain one output
|
|||
|
file for each file in the source directory.
|
|||
|
|
|||
|
In other cases, this option has two effects: it defines the file where the
|
|||
|
principal output of the transformation will be written, and it defines the base
|
|||
|
URI used for resolving the value of the C<xsl:result-document/@href> attribute
|
|||
|
when secondary result documents are written.
|
|||
|
|
|||
|
In the absence of this option, (a) the principal output is written to the
|
|||
|
standard output stream, and (b) secondary output file locations are resolved
|
|||
|
relative to the current working directory.
|
|||
|
|
|||
|
Output files are created if they do not already exist; any necessary
|
|||
|
directories will also be created. If a file does already exist, it is generally
|
|||
|
overwritten, though this will not necessarily happen if the transformation
|
|||
|
fails.
|
|||
|
|
|||
|
=item B<-opt>:[C<->]I<flags>
|
|||
|
|
|||
|
Allows individual optimizations to be enabled or disabled selectively. There is
|
|||
|
a set of single-letter flags identifying particular optimizations:
|
|||
|
|
|||
|
=over
|
|||
|
|
|||
|
=item C<c>:
|
|||
|
|
|||
|
generate bytecode
|
|||
|
|
|||
|
=item C<d>:
|
|||
|
|
|||
|
detect void path expressions
|
|||
|
|
|||
|
=item C<e>:
|
|||
|
|
|||
|
cache regular expressions
|
|||
|
|
|||
|
=item C<f>:
|
|||
|
|
|||
|
inline functions
|
|||
|
|
|||
|
=item C<g>:
|
|||
|
|
|||
|
extract global variables
|
|||
|
|
|||
|
=item C<j>:
|
|||
|
|
|||
|
just-in-time compilation of template rules
|
|||
|
|
|||
|
=item C<k>:
|
|||
|
|
|||
|
create keys
|
|||
|
|
|||
|
=item C<l>:
|
|||
|
|
|||
|
loop lifting
|
|||
|
|
|||
|
=item C<m>:
|
|||
|
|
|||
|
miscellaneous
|
|||
|
|
|||
|
=item C<n>:
|
|||
|
|
|||
|
constant folding
|
|||
|
|
|||
|
=item C<r>:
|
|||
|
|
|||
|
template rule-sets
|
|||
|
|
|||
|
=item C<s>:
|
|||
|
|
|||
|
extract common subexpressions
|
|||
|
|
|||
|
=item C<t>:
|
|||
|
|
|||
|
tail call optimization
|
|||
|
|
|||
|
=item C<v>:
|
|||
|
|
|||
|
inline variables
|
|||
|
|
|||
|
=item C<w>:
|
|||
|
|
|||
|
create switch statements
|
|||
|
|
|||
|
=item C<x>:
|
|||
|
|
|||
|
index predicates
|
|||
|
|
|||
|
=back
|
|||
|
|
|||
|
A value such as B<-opt>:C<gs> runs with only the selected optimizations;
|
|||
|
B<-opt>:C<-gs> runs with the selected optimizations disabled and all others
|
|||
|
enabled. The value B<-opt>:C<0> suppresses all optimizations. The default is
|
|||
|
full optimization; this feature allows optimization to be suppressed in cases
|
|||
|
where reducing compile time is important, or where optimization gets in the way
|
|||
|
of debugging, or causes extension functions with side-effects to behave
|
|||
|
unpredictably. (Note however, that even with no optimization, lazy evaluation
|
|||
|
may still cause the evaluation order to be not as expected.) Disabling
|
|||
|
optimizations may in some cases prevent streamed evaluation. For example, some
|
|||
|
expressions only become streamable because the optimizer is able to work out
|
|||
|
that sorting nodes into document order is unnecessary. Most of these flags
|
|||
|
enable optimizations that cause extra work at compile time to improve run-time
|
|||
|
performance. The C<j> option is an exception: enabling this option shifts work
|
|||
|
from compile time to run time.
|
|||
|
|
|||
|
=item B<-or>:I<classname>
|
|||
|
|
|||
|
Use the specified C<OutputURIResolver> to process output URIs appearing in the
|
|||
|
href attribute of C<xsl:result-document>. The C<OutputURIResolver> is a
|
|||
|
user-defined class that implements the C<net.sf.saxon.lib.OutputURIResolver>
|
|||
|
interface.
|
|||
|
|
|||
|
=item B<-outval>:(C<recover>|C<fatal>)
|
|||
|
|
|||
|
Normally, if validation of result documents is requested, a validation error is
|
|||
|
fatal. Setting the option B<-outval>:C<recover> causes such validation failures
|
|||
|
to be treated as warnings. The validation message is written both to the
|
|||
|
standard error stream, and (where possible) as a comment in the result document
|
|||
|
itself.
|
|||
|
|
|||
|
This option does not by itself cause result documents to be validated; that
|
|||
|
happens only as a consequence of the type or validation attribute on an
|
|||
|
C<xsl:result-document> instruction. The only effect of the option is to
|
|||
|
determine what happens when validation fails.
|
|||
|
|
|||
|
Validating result documents can be very useful while debugging a stylesheet,
|
|||
|
because it provides instant feedback when the output is incorrect. However, it
|
|||
|
can sometimes be frustrating during development when you know that parts of the
|
|||
|
code have not yet been written. The option B<-outval>:C<recover> is designed to
|
|||
|
give you the best of both worlds: it tells you that the output is wrong, but
|
|||
|
still enables you to see the complete result document that your code is
|
|||
|
producing.
|
|||
|
|
|||
|
=item B<-p>[:(C<on>|C<off>)]
|
|||
|
|
|||
|
Enable recognition of query parameters (such as C<xinclude=yes>) in the
|
|||
|
C<StandardURIResolver>. This option is available in Saxon-PE and Saxon-EE only.
|
|||
|
It cannot be used in conjunction with the B<-r> option, and it automatically
|
|||
|
switches on the B<-u> and B<-sa> options. The effect is that Saxon-specific
|
|||
|
query parameters are recognized in a URI. One query parameter that is
|
|||
|
recognized is C<val>. This may take the values C<strict>, C<lax>, or C<strip>.
|
|||
|
For example, C<source.xml?val=strict> loads a document with strict schema
|
|||
|
validation.
|
|||
|
|
|||
|
=item B<-quit>:(C<on>|C<off>)
|
|||
|
|
|||
|
With the default setting, on, the command will quit the Java VM and return an
|
|||
|
exit code if a failure occurs. This is useful when running from an operating
|
|||
|
system shell. With the setting B<-quit>:C<off> the command instead throws a
|
|||
|
C<RunTimeException>, which is more useful when the command is invoked from
|
|||
|
another Java application such as Ant.
|
|||
|
|
|||
|
=item B<-r>:I<classname>
|
|||
|
|
|||
|
Use the specified C<URIResolver> to process all URIs. The C<URIResolver> is a
|
|||
|
user-defined class, that implements the C<javax.xml.transform.URIResolver>
|
|||
|
interface, whose function is to take a URI supplied as a string, and return a
|
|||
|
SAX Source object. It is invoked to process URIs used in the C<document()>
|
|||
|
function, in the C<xsl:include> and C<xsl:import> elements, and (if B<-u> is
|
|||
|
also specified) to process the URIs of the source file and stylesheet file
|
|||
|
provided on the command line.
|
|||
|
|
|||
|
=item B<-relocate>:(C<on>|C<off>)
|
|||
|
|
|||
|
Used with B<-export> to produce an export package which can be deployed to a
|
|||
|
different location, with a different base URI. If on, then C<static-base-uri()>
|
|||
|
represents the deployed location of the package, rather than its compile time
|
|||
|
location. The default is off.
|
|||
|
|
|||
|
The practical effect of this is that if B<-relocate:>C<off> (the default) is
|
|||
|
specified, then the generated SEF file will contain references to the
|
|||
|
stylesheet’s original location as its static base URI, and run-time operations
|
|||
|
that are relative to this base URI (for example, calling C<doc()> with a
|
|||
|
relative URI) will retrieve resources exactly as if the stylesheet had not been
|
|||
|
exported. By contrast, if B<-relocate>:C<on> is specified, the SEF file will
|
|||
|
contain no reference to the original location of the source stylesheet, and
|
|||
|
operations such as C<doc()> will be relative to the location from which the SEF
|
|||
|
file was loaded.
|
|||
|
|
|||
|
=item B<-repeat>:I<integer>
|
|||
|
|
|||
|
Performs the transformation I<N> times, where I<N> is the specified integer.
|
|||
|
This option is useful for performance measurement, since timings for the first
|
|||
|
transformation are often dominated by Java warm-up time.
|
|||
|
|
|||
|
=item B<-s>:I<filename>
|
|||
|
|
|||
|
Identifies the source file or directory. Mandatory unless the B<-it> option is
|
|||
|
used. The source file is parsed to create a tree, and the document node of this
|
|||
|
tree acts as the initial context item for the transformation.
|
|||
|
|
|||
|
The filename can be given as “C<->” to take the source from standard input,
|
|||
|
in which case the base URI is taken from that of the current directory.
|
|||
|
|
|||
|
If the name identifies a directory, all the files in the directory will be
|
|||
|
processed individually. In this case the B<-o> option is mandatory, and must
|
|||
|
also identify a directory, to contain the corresponding output files. A
|
|||
|
directory must be specified as a filename, not as a URL.
|
|||
|
|
|||
|
For backwards compatibility the source filename can also be specified
|
|||
|
immediately before the stylesheet filename, without the B<-s> flag, provided
|
|||
|
that the B<-it> option is not present.
|
|||
|
|
|||
|
=item B<-sa>
|
|||
|
|
|||
|
Invoke a schema-aware transformation. Requires Saxon-EE to be installed. This
|
|||
|
option is not needed if either (a) another option implying schema-awareness is
|
|||
|
present (for example B<-val>:C<strict>) or (b) the stylesheet contains an
|
|||
|
C<xsl:import-schema> declaration.
|
|||
|
|
|||
|
=item B<-scmin>:I<filename>
|
|||
|
|
|||
|
Loads a precompiled schema component model from the given file. The file should
|
|||
|
be generated in a previous run of C<com.saxonica.Validate> using the B<-export>
|
|||
|
option. When this option is used, the B<-xsd> option should not be present.
|
|||
|
Schemas loaded from an SCM file are assumed to be valid, without checking.
|
|||
|
|
|||
|
This option is retained for compatibility. From Saxon 9.7, SCM files can also
|
|||
|
be supplied in the B<-xsd> option.
|
|||
|
|
|||
|
=item B<-strip>:(C<all>|C<none>|C<ignorable>)
|
|||
|
|
|||
|
Specifies what whitespace is to be stripped from source documents (applies both
|
|||
|
to the principal source document and to any documents loaded for example using
|
|||
|
the C<document()> function). The default is ignorable: all ignorable whitespace
|
|||
|
is stripped. Whitespace text nodes are ignorable if they appear in elements
|
|||
|
defined in the DTD or schema as having element-only content. Specifying all
|
|||
|
strips all whitespace text nodes from source documents before any further
|
|||
|
processing, regardless of any C<xsl:strip-space> declarations in the
|
|||
|
stylesheet, or any C<xml:space> attributes in the source document. Specifying
|
|||
|
ignorable strips all ignorable whitespace text nodes from source documents
|
|||
|
before any further processing, regardless of any C<xsl:strip-space>
|
|||
|
declarations in the stylesheet, or any C<xml:space> attributes in the source
|
|||
|
document. Specifying none suppresses all whitespace stripping unless requested
|
|||
|
elsewhere, for example using C<xsl:strip-space>.
|
|||
|
|
|||
|
=item B<-t>
|
|||
|
|
|||
|
Display version and timing information to the standard error output. The output
|
|||
|
also traces the files that are read and written, and extension modules that are
|
|||
|
loaded.
|
|||
|
|
|||
|
=item B<-T>[:I<classname>]
|
|||
|
|
|||
|
Display stylesheet tracing information. This traces execution of each
|
|||
|
instruction in the stylesheet, so the output can be quite voluminous. Also
|
|||
|
switches line numbering on for the source document. If a classname is
|
|||
|
specified, it is a user-defined class, which must implement C<TraceListener>.
|
|||
|
If the classname is omitted, a system-supplied trace listener is used. For
|
|||
|
performance profiling, set classname to
|
|||
|
C<net.sf.saxon.trace.TimingTraceListener>. This creates an output file giving
|
|||
|
timings for each instruction executed. This output file can subsequently be
|
|||
|
analyzed to give an execution time profile for the stylesheet. See
|
|||
|
L<Performance
|
|||
|
Analysis|https://www.saxonica.com/documentation10/index.html#!using-xsl/performanceanalysis>.
|
|||
|
|
|||
|
=item B<-target>:(C<EE>|C<PE>|C<HE>|C<JS>)
|
|||
|
|
|||
|
Relevant only when B<-export> is specified, identifies the target platform on
|
|||
|
which the exported stylesheet is to run. When exporting for Saxon-JS, the value
|
|||
|
“C<JS>” must be specified, because this adds information to the SEF file that
|
|||
|
is required by Saxon-JS. Specifying “C<JS>” means the SEF is produced in JSON
|
|||
|
format for use with Saxon-JS 2.x. (To generate SEF files for Saxon-JS 1.x, you
|
|||
|
need to revert to Saxon-EE 9.9). In principle, specifying “C<HE>” or “C<PE>”
|
|||
|
will inhibit optimizations that generate code which Saxon-HE/Saxon-PE cannot
|
|||
|
execute; however, this is not fully tested.
|
|||
|
|
|||
|
=item B<-TB>:I<filename>
|
|||
|
|
|||
|
Monitors generation of hot-spot bytecode and produces an XML report on the
|
|||
|
given filename giving, for each expression that was a candidate for bytecode
|
|||
|
generation and that was actually executed, data about the number of times and
|
|||
|
speed of execution in the interpreter, the number of times and speed of
|
|||
|
execution in compiled form, and the cost of compilation.
|
|||
|
|
|||
|
=item B<-threads>:I<N>
|
|||
|
|
|||
|
Used only when the B<-s> option specifies a directory. Controls the number of
|
|||
|
threads used to process the files in the directory. Each transformation runs in
|
|||
|
a single thread.
|
|||
|
|
|||
|
=item B<-TJ>
|
|||
|
|
|||
|
Switches on tracing of the binding of calls to external Java methods. This is
|
|||
|
useful when analyzing why Saxon fails to find a Java method to match an
|
|||
|
extension function call in the stylesheet, or why it chooses one method over
|
|||
|
another when several are available.
|
|||
|
|
|||
|
=item B<-Tlevel>:(C<none>|C<low>|C<normal>|C<high>)
|
|||
|
|
|||
|
Controls the level of detail of the tracing produced by the B<-T> option. The
|
|||
|
values are:
|
|||
|
|
|||
|
=over
|
|||
|
|
|||
|
=item C<none>
|
|||
|
|
|||
|
effectively switches tracing off.
|
|||
|
|
|||
|
=item C<low>
|
|||
|
|
|||
|
traces function and template calls.
|
|||
|
|
|||
|
=item C<normal>
|
|||
|
|
|||
|
traces execution of instructions.
|
|||
|
|
|||
|
=item C<high>
|
|||
|
|
|||
|
traces execution of finer-grained expressions.
|
|||
|
|
|||
|
=back
|
|||
|
|
|||
|
=item B<-Tout>:I<filename>
|
|||
|
|
|||
|
Directs the output of tracing to a specified file (assuming that B<-T> is
|
|||
|
enabled).
|
|||
|
|
|||
|
=item B<-TP>:I<filename>
|
|||
|
|
|||
|
This is equivalent to setting B<-T>:C<net.sf.saxon.trace.TimedTraceListener>
|
|||
|
and B<-traceout>:I<filename>; that is, it causes trace profile information to
|
|||
|
be set to the specified file. This output file can subsequently be analyzed to
|
|||
|
give an execution time profile for the stylesheet. See L<Performance
|
|||
|
Analysis|https://www.saxonica.com/documentation10/index.html#!using-xsl/performanceanalysis>.
|
|||
|
|
|||
|
=item B<-traceout>:I<filename>
|
|||
|
|
|||
|
Indicates that the output of the C<trace()> function should be directed to a
|
|||
|
specified file. Alternatively, specify C<#out> to direct the output to
|
|||
|
C<System.out>, C<#err> to send it to C<System.err> (the default), or C<#null>
|
|||
|
to have it discarded. This option is ignored when a trace listener is in use:
|
|||
|
in that case, C<trace()> output goes to the registered trace listener.
|
|||
|
|
|||
|
=item B<-tree>:(C<linked>|C<tiny>|C<tinyc>)
|
|||
|
|
|||
|
Selects the implementation of the internal tree model: C<tiny> selects the
|
|||
|
“tiny tree” model (the default), C<linked> selects the linked tree model,
|
|||
|
C<tinyc> selects the “condensed tiny tree” model. See L<Choosing a tree
|
|||
|
model|https://www.saxonica.com/documentation10/index.html#!sourcedocs/choosingmodel>.
|
|||
|
|
|||
|
=item B<-u>
|
|||
|
|
|||
|
Indicates that the names of the source document and the stylesheet document are
|
|||
|
URLs; otherwise they are taken as filenames, unless they start with C<http:>,
|
|||
|
C<https:>, C<file:> or C<classpath:>, in which case they are taken as URLs.
|
|||
|
|
|||
|
=item B<-val>[:(C<strict>|C<lax>)]
|
|||
|
|
|||
|
Requests schema-based validation of the source file and of any files read using
|
|||
|
the C<document()> or similar functions. Validation is available only with
|
|||
|
Saxon-EE, and this flag automatically switches on the B<-sa> option. Specify
|
|||
|
B<-val> or B<-val>:C<strict> to request strict validation, or B<-val>:C<lax>
|
|||
|
for lax validation.
|
|||
|
|
|||
|
=item B<-warnings>:(C<silent>|C<recover>|C<fatal>)
|
|||
|
|
|||
|
Indicates the policy for handling recoverable errors in the stylesheet:
|
|||
|
C<silent> means recover silently, C<recover> means recover after writing a
|
|||
|
warning message to the system error output, C<fatal> means signal the error and
|
|||
|
do not attempt recovery. (Note, this does not currently apply to all errors
|
|||
|
that the XSLT recommendation describes as recoverable). The default is
|
|||
|
recover.
|
|||
|
|
|||
|
=item B<-x>:I<classname>
|
|||
|
|
|||
|
Use the specified SAX parser for the source file and any files loaded using the
|
|||
|
C<document()> function. The parser must be the fully-qualified class name of a
|
|||
|
Java class that implements the C<org.xml.sax.XMLReader> or
|
|||
|
C<javax.xml.parsers.SAXParserFactory> interface, and it must be instantiable
|
|||
|
using a zero-argument public constructor. One use of this option is to select
|
|||
|
an HTML parser such as John Cowan’s TagSoup rather than an XML parser. In this
|
|||
|
case, the TagSoup JAR file must be on the classpath, and the class name to use
|
|||
|
is C<org.ccil.cowan.tagsoup.Parser>. Another common use is to specify
|
|||
|
C<org.apache.xml.resolver.tools.ResolvingXMLReader>. This parser is provided by
|
|||
|
the Apache commons project, and it customizes the default parser by using an
|
|||
|
C<EntityResolver> that resolves external entity references (note the reference
|
|||
|
to an external DTD in a DOCTYPE declaration) by reference to an OASIS catalog
|
|||
|
file. This can be used to avoid repeated calls to external web servers (such as
|
|||
|
the W3C server) for commonly used DTDs such as the XHTML DTD. The option to
|
|||
|
supply a C<SAXParserFactory> was introduced in 9.6 for the benefit of the Aalto
|
|||
|
parser, whose C<XMLReader> implementation cannot be directly instantiated; this
|
|||
|
parser can therefore be requested by nominating its factory class,
|
|||
|
C<com.fasterxml.aalto.sax.SAXParserImpl>.
|
|||
|
|
|||
|
=item B<-xi>:(C<on>|C<off>)
|
|||
|
|
|||
|
Apply XInclude processing to all source XML documents (but not to schema and
|
|||
|
stylesheet modules). This currently only works when documents are parsed using
|
|||
|
the Xerces parser, which is the default on the SaxonJ platform (but not on .NET).
|
|||
|
|
|||
|
=item B<-xmlversion>:(C<1.0>|C<1.1>)
|
|||
|
|
|||
|
If B<-xmlversion>:C<1.1> is specified, allows XML 1.1 and XML Namespaces 1.1
|
|||
|
constructs. This option must be set if source documents using XML 1.1 are to be
|
|||
|
read, or if result documents are to be serialized as XML 1.1. This option also
|
|||
|
enables use of XML 1.1 constructs within the stylesheet itself.
|
|||
|
|
|||
|
=item B<-xsd>:I<file1>;I<file2>;I<file3>…
|
|||
|
|
|||
|
Loads additional schema documents. The declarations in these schema documents
|
|||
|
are available when validating source documents (or for use by the C<validate{}>
|
|||
|
expression). This option may also be used to supply the locations of schema
|
|||
|
documents that are imported into the stylesheet, in the case where the
|
|||
|
C<xsl:import-schema> declaration gives the target namespace of the schema but
|
|||
|
not its location.
|
|||
|
|
|||
|
=item B<-xsdversion>:(C<1.0>|C<1.1>)
|
|||
|
|
|||
|
If B<-xsdversion>:C<1.1> is specified (the default), allows schema documents
|
|||
|
using XML Schema 1.1 to be read, and XML Schema 1.1 constructs such as
|
|||
|
assertions.
|
|||
|
|
|||
|
=item B<-xsiloc>:(C<on>|C<off>)
|
|||
|
|
|||
|
If set to C<on> (the default) the schema processor attempts to load any schema
|
|||
|
documents referenced in C<xsi:schemaLocation> and
|
|||
|
C<xsi:noNamespaceSchemaLocation> attributes in the instance document, unless a
|
|||
|
schema for the specified namespace (or non-namespace) is already available. If
|
|||
|
set to C<off>, these attributes are ignored.
|
|||
|
|
|||
|
=item B<-xsl>:I<filename>
|
|||
|
|
|||
|
Specifies the file containing the principal stylesheet module. Mandatory unless
|
|||
|
the B<-a> option is used. The value “C<->” identifies the standard input
|
|||
|
stream, in which case the static base URI is taken from that of the current
|
|||
|
directory. If the B<-u> option is specified then the value must be a URI rather
|
|||
|
than a filename.
|
|||
|
|
|||
|
The selected file can contain either XSLT source code, or a compiled version of
|
|||
|
the stylesheet (a SEF file) as produced using the B<-export> option.
|
|||
|
|
|||
|
=item B<-y>:I<classname>
|
|||
|
|
|||
|
Use the specified SAX parser for stylesheet files, including any loaded using
|
|||
|
C<xsl:include> or C<xsl:import>. The supplied classname must be the
|
|||
|
fully-qualified class name of a Java class that implements the
|
|||
|
C<org.xml.sax.XMLReader> or C<javax.xml.parsers.SAXParserFactory> interface,
|
|||
|
and it must be instantiable using a zero-argument public constructor.
|
|||
|
|
|||
|
=item B<--feature>:I<value>
|
|||
|
|
|||
|
Set a feature defined in the C<Configuration> interface. The names of features
|
|||
|
are defined in the Javadoc for class Feature (alternatively see L<Configuration
|
|||
|
Features|https://www.saxonica.com/documentation10/index.html#!configuration/config-features>):
|
|||
|
the value used here is the part of the name after the last “C</>”, for example
|
|||
|
B<--allow-external-functions>:C<off>. Only features accepting a string or
|
|||
|
boolean may be set; for booleans the values C<true>/C<false>, C<on>/C<off>,
|
|||
|
C<yes>/C<no>, and C<1>/C<0> are recognized.
|
|||
|
|
|||
|
=item B<-?>
|
|||
|
|
|||
|
Display command syntax.
|
|||
|
|
|||
|
=item B<--?>
|
|||
|
|
|||
|
Display a list of features that are available using the B<--feature>:I<value>
|
|||
|
syntax.
|
|||
|
|
|||
|
=back
|
|||
|
|
|||
|
=head2 COMMAND LINE PARAMETERS
|
|||
|
|
|||
|
A param takes the form I<name>=I<value>, name being the name of the parameter,
|
|||
|
and value the value of the parameter. These parameters are accessible within
|
|||
|
the stylesheet as normal variables, using the C<$>I<name> syntax, provided they
|
|||
|
are declared using a top-level C<xsl:param> element. If there is no such
|
|||
|
declaration, the supplied parameter value is silently ignored. If the
|
|||
|
C<xsl:param> element has an as attribute indicating the required type, then the
|
|||
|
string value supplied on the command line is cast to this type: this may result
|
|||
|
in an error, for example if an integer is required and the supplied value
|
|||
|
cannot be converted to an integer. If the parameter is declared with the option
|
|||
|
C<static="yes"> (new in XSLT 3.0) then the value is supplied as a static
|
|||
|
parameter value.
|
|||
|
|
|||
|
A param preceded by a leading question mark (C<?>) is interpreted as an XPath
|
|||
|
expression. For example, C<?time=current-dateTime()> sets the value of the
|
|||
|
stylesheet parameter $time to the value of the current date and time, as an
|
|||
|
instance of C<xs:dateTime>, while C<?debug=false()> sets the value of the
|
|||
|
parameter C<$debug> to the boolean value false. If the parameter has a required
|
|||
|
type (for example C<E<lt>xsl:param name="p" as="xs:date"/E<gt>>), then the
|
|||
|
supplied value must be compatible with this type according to the standard
|
|||
|
rules for converting variable values and function arguments. The static context
|
|||
|
for this XPath expression includes only the standard namespaces conventionally
|
|||
|
bound to the prefixes C<xs>, C<fn>, C<xsi>, and C<saxon>. The static base URI
|
|||
|
(used when calling the C<doc()> function) is the current directory. The dynamic
|
|||
|
context contains no context item, position, or size, and no variables.
|
|||
|
|
|||
|
A param preceded by a leading exclamation mark (C<!>) is interpreted as an
|
|||
|
output parameter. For example, C<!indent=yes> requests indented output. This is
|
|||
|
equivalent to specifying the attribute C<indent="yes"> on an C<xsl:output>
|
|||
|
declaration in the stylesheet. An output parameter specified on the command
|
|||
|
line overrides one specified within the stylesheet. For parameters
|
|||
|
C<doctype-system>, C<doctype-public>, and C<saxon:next-in-chain>, a zero-length
|
|||
|
value is treated as “absent”, that is, the effect is to cancel any value that
|
|||
|
was set within the stylesheet. If you are using the bash shell, you will need
|
|||
|
to escape “C<!>” as “C<\!>”.
|
|||
|
|
|||
|
A param preceded by a leading plus sign (C<+>) is interpreted as a filename or
|
|||
|
directory. The content of the file is parsed as XML, and the resulting document
|
|||
|
node is passed to the stylesheet as the value of the parameter. If the
|
|||
|
parameter value is a directory, then all the immediately contained files are
|
|||
|
parsed as XML, and the resulting sequence of document nodes is passed as the
|
|||
|
value of the parameter. For example, C<+lookup=lookup.xml> sets the value of
|
|||
|
the stylesheet parameter lookup to the document node at the root of the tree
|
|||
|
representing the parsed contents of the file F<lookup.xml>.
|
|||
|
|
|||
|
Under most operating systems it is possible to supply a value containing spaces
|
|||
|
by enclosing it in double quotes, for example C<name="John Smith">. This is a
|
|||
|
feature of the operating system shell, not something Saxon does, so it may not
|
|||
|
work the same way under every operating system or command processor. (In the
|
|||
|
jEdit console plugin, for example, it has to be written as C<"name=John
|
|||
|
Smith">.)
|
|||
|
|
|||
|
If the parameter name is in a non-null namespace, the parameter can be given a
|
|||
|
value using the syntax C<{>I<uri>C<}>I<localname>=I<value>. Here uri is the
|
|||
|
namespace URI of the parameter’s name, and localname is the local part of the
|
|||
|
name.
|
|||
|
|
|||
|
This applies also to output parameters. For example, you can set the
|
|||
|
indentation level to 4 by using the parameter
|
|||
|
C<!{http://saxon.sf.net/}indent-spaces=4>. In this case, however, lexical
|
|||
|
QNames using the prefix saxon are also recognized, for example
|
|||
|
C<!saxon:indent-spaces=4>. See also L<Additional serialization
|
|||
|
parameters|https://www.saxonica.com/documentation10/index.html#!extensions/output-extras>.
|
|||
|
|
|||
|
=head1 SEE ALSO
|
|||
|
|
|||
|
L<https://www.saxonica.com/documentation10/index.html>, L<gizmo10(1)>,
|
|||
|
L<saxon10q(1)>, L<xsltproc(1)>.
|
|||
|
|
|||
|
=head1 AUTHOR
|
|||
|
|
|||
|
Michael H. Kay E<lt>L<mike@saxonica.com>E<gt>
|