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>
|