1SAXON8(1)                        User Commands                       SAXON8(1)
2
3
4

NAME

6       saxon8 - manual page for saxon8
7

SYNOPSIS

9       saxon8 [options] source-document stylesheet [ params...]
10

DESCRIPTION

12       saxon8 applies a given stylesheet to a given source XML document.
13
14

OPTIONS

16       For  a  schema-aware transformation, specify the option -sa, or (on the
17       Java platform only) use the alternate entry  point  com.saxonica.Trans‐
18       form. For more details see Schema-Aware Transformations.
19
20       The  options must come first, then the two file names, then the params.
21       The stylesheet is omitted if the -a option is present.
22
23       The options are as follows (in any order):
24
25       -a     Use the xml-stylesheet processing instruction in the source doc‐
26              ument  to  identify  the  stylesheet  to be used. The stylesheet
27              argument should be omitted.
28
29       -c     Indicates that the stylesheet  argument  identifies  a  compiled
30              stylesheet  rather than an XML source stylesheet. The stylesheet
31              must have been previously compiled as described in  Compiling  a
32              Stylesheet.
33
34       -cr classname
35              Use  the  specified  CollectionURIResolver to process collection
36              URIs passed to the collection() function.  The  CollectionURIRe‐
37              solver   is   a   user-defined   class   that   implements   the
38              net.sf.saxon.CollectionURIResolver interface.
39
40       -ds | -dt
41              Selects the implementation  of  the  internal  tree  model.  -dt
42              selects  the  tiny  tree  model  (the  default). -ds selects the
43              linked tree model. See Choosing a tree model.
44
45       -im modename
46              Selects the initial mode for  the  transformation.  If  this  is
47              namespaced, it can be written as {uri}localname
48
49       -it template
50              Selects  the  initial  named template to be executed. If this is
51              namespaced, it can  be  written  as  {uri}localname.  When  this
52              option is used, the source file should be omitted.
53
54       -l     Switches line numbering on for the source document. Line numbers
55              are accessible through the  extension  function  saxon:line-num‐
56              ber(), or from a trace listener.
57
58       -m classname
59              Use  the  specified  Emitter to process the output from xsl:mes‐
60              sage. The class must implement  the  net.sf.saxon.output.Emitter
61              class.  This  interface  is  similar to a SAX ContentHandler, it
62              takes a stream of events to generate output. In general the con‐
63              tent  of  a  message is an XML fragment. By default the standard
64              XML emitter is used, configured to write to the  standard  error
65              stream,  and to include no XML declaration. Each message is out‐
66              put as a new document.
67
68       -noext Suppress calls on extension functions,  other  than  system-sup‐
69              plied Saxon and EXSLT extension functions. This option is useful
70              when loading an untrusted stylesheet, perhaps from a remote site
71              using an http:// URL; it ensures that the stylesheet cannot call
72              Java methods and thereby gain privileged access to resources  on
73              your machine.
74
75       -novw  No version warnings. This suppresses the warning message that is
76              normally issued (as required by the W3C specification) when run‐
77              ning  an  XSLT 2.0 processor against a stylesheet that specifies
78              version=1.0.
79
80       -o filename
81              Send output to named file. In the absence of  this  option,  the
82              results go to standard output. If the source argument identifies
83              a directory, this option is mandatory and must also  identify  a
84              directory;  on  completion  it  will contain one output file for
85              each file in the source directory. If the stylesheet writes sec‐
86              ondary  output  files using the xsl:result-document instruction;
87              this filename acts as the base URI for  the  href  attribute  of
88              this  instruction. In the absence of this option, secondary out‐
89              put files are written relative to the current working directory.
90
91       -p     Use the PTreeURIResolver. This option is available  in  Saxon-SA
92              only.  It  cannot be used in conjunction with the -r option, and
93              it automatically switches on the -u and -sa options. The  effect
94              is  twofold.  Firstly, Saxon-specific file extensions are recog‐
95              nized in URIs (including the URI of the source document  on  the
96              command  line). Currently the only Saxon-specific file extension
97              is .ptree, which indicates that the source document is  supplied
98              in the form of a Saxon PTree. This is a binary representation of
99              an XML  document,  designed  for  speed  of  loading.  Secondly,
100              Saxon-specific  query  parameters  are recognized in a URI. Cur‐
101              rently the only query parameter that is recognized is val.  This
102              may  take  the  values  strict,  lax,  or  strip.  For  example,
103              source.xml?val=strict loads a document with strict schema  vali‐
104              dation.
105
106       -r classname
107              Use  the  specified  URIResolver to process all URIs. The URIRe‐
108              solver   is   a   user-defined   class,   that    extends    the
109              net.sf.saxon.URIResolver  class, whose function is to take a URI
110              supplied as a string,  and  return  a  SAX  InputSource.  It  is
111              invoked  to process URIs used in the document() function, in the
112              xsl:include and xsl:import elements, and (if -u is  also  speci‐
113              fied) to process the URIs of the source file and stylesheet file
114              provided on the command line.
115
116       -sa    Invoke a schema-aware transformation. Requires  Saxon-SA  to  be
117              installed.
118
119       -sall  Strips  all  whitespace  text nodes from source documents before
120              any further processing, regardless of any xsl:strip-space decla‐
121              rations  in  the  stylesheet, or any xml:space attributes in the
122              source document.
123
124       -signorable
125              Strips all ignorable whitespace text nodes from source documents
126              before any further processing, regardless of any xsl:strip-space
127              declarations in the stylesheet, or any xml:space  attributes  in
128              the source document. Whitespace text nodes are ignorable if they
129              appear in elements defined in the DTD or schema as  having  ele‐
130              ment-only content.
131
132       -snone Strips no whitespace before further processing. (However, white‐
133              space will still  be  stripped  if  this  is  specified  in  the
134              stylesheet using xsl:strip-space).
135
136       -t     Display  version  and  timing  information to the standard error
137              output. The output also traces the files that are read and writ‐
138              ing, and extension modules that are loaded.
139
140       -T     Display  stylesheet  tracing  information  to the standard error
141              output.  This  traces  execution  of  each  instruction  in  the
142              stylesheet, so the output can be quite voluminous. Also switches
143              line numbering on for the source document.
144
145       -TJ    Switches on tracing of the binding of  calls  to  external  Java
146              methods. This is useful when analyzing why Saxon fails to find a
147              Java  method  to  match  an  extension  function  call  in   the
148              stylesheet,  or why it chooses one method over another when sev‐
149              eral are available.
150
151       -TL classname
152              Run the stylesheet using the specified TraceListener. The class‐
153              name   names   a   user-defined   class,  which  must  implement
154              net.sf.saxon.trace.TraceListener
155
156       -TP    Run the stylesheet using the  TraceListener  TimedTraceListener.
157              This  creates an output file giving timings for each instruction
158              executed. This output file can subsequently be analyzed to  give
159              an  execution  time  profile for the stylesheet. See Performance
160              Analysis.
161
162       -u     Indicates that the names of the source document  and  the  style
163              document are URLs; otherwise they are taken as filenames, unless
164              they start with http: or file:, in which case they are taken  as
165              URLs
166
167       -v     Requests  DTD-based  validation  of  the  source file and of any
168              files read using the document() function. Requires an XML parser
169              that supports validation.
170
171       -val   Requests  schema-based  validation of the source file and of any
172              files read using the document() function. This option is  avail‐
173              able  only  with  Saxon-SA, and it automatically switches on the
174              -sa option.
175
176       -vlax  This option is available only with Saxon-SA,  and  it  automati‐
177              cally  switches on the -sa option. It requests lax validation of
178              source documents using an XML Schema. That is, the document will
179              be  validated if a suitable schema is available, and will not be
180              validated otherwise.
181
182       -vw    Indicates that  validation  errors  found  when  validating  the
183              result  tree  should be treated as warnings only. This option is
184              available  only  with  the  Saxon-SA  version  of  the  command,
185              com.saxonica.Transform.
186
187       -w0, w1, or w2
188              Indicates  the  policy  for  handling  recoverable errors in the
189              stylesheet: w0 means recover silently, w1  means  recover  after
190              writing  a  warning message to the system error output, w2 means
191              signal the error and do not attempt recovery. (Note,  this  does
192              not  currently  apply to all errors that the XSLT recommendation
193              describes as recoverable). The default is w1.
194
195       -x classname
196              Use specified SAX parser for source file and  any  files  loaded
197              using   the   document()   function.  The  parser  must  be  the
198              fully-qualified class name of a Java class that  implements  the
199              org.xml.sax.Parser or org.xml.sax.XMLReader interface
200
201       -y classname
202              Use  specified  SAX  parser  for  stylesheet file, including any
203              loaded using xsl:include or xsl:import. The parser must  be  the
204              fully-qualified  class  name of a Java class that implements the
205              org.xml.sax.Parser or org.xml.sax.XMLReader interface
206
207       -1.1   Allow XML 1.1 and XML Namespaces  1.1  constructs.  This  option
208              must be set if source documents using XML 1.1 are to be read, or
209              if result documents are to be serialized as XML 1.1. This option
210              also  enables  use  of  XML 1.1 constructs within the stylesheet
211              itself.
212
213       -?     Display command syntax
214
215       source-document
216              Identifies the source file or directory. Mandatory. If this is a
217              directory,  all  the  files  in  the directory will be processed
218              individually. In this case the -o option is mandatory, and  must
219              also  identify  a directory, to contain the corresponding output
220              files. A directory must be specified as a  filename,  not  as  a
221              URL.  The  source-document  can  be  specified  as - to take the
222              source from standard input.
223
224       stylesheet
225              Identifies the stylesheet. Mandatory unless  the  -a  option  is
226              used.  If the -c option is used, this argument identifies a com‐
227              piled stylesheet. The stylesheet argument can be specified as  -
228              to read the stylesheet from standard input.
229
230              A  param  takes  the form name=value, name being the name of the
231              parameter, and value the value of the parameter.  These  parame‐
232              ters  are  accessible within the stylesheet as normal variables,
233              using the  syntax, provided they are declared using a  top-level
234              xsl:param element. If there is no such declaration, the supplied
235              parameter value is silently ignored. If  the  xsl:param  element
236              has  an  as   attribute  indicating  the required type, then the
237              string value supplied on the command line is cast to this  type:
238              this  may  result  in  an  error,  for  example if an integer is
239              required and the supplied value cannot be converted to an  inte‐
240              ger.
241
242       A param preceded by a leading exclamation mark (!) is interpreted as an
243       output parameter. For example, !indent=yes  requests  indented  output.
244       This  is  equivalent  to  specifying  the  attribute  indent=yes  on an
245       xsl:output declaration in the stylesheet. An output parameter specified
246       on the command line overrides one specified within the stylesheet.
247
248       A  param  preceded by a leading plus sign (+) is interpreted as a file‐
249       name or directory. The content of the file is parsed as  XML,  and  the
250       resulting document node is passed to the stylesheet as the value of the
251       parameter. If the parameter value is a directory, then all the  immedi‐
252       ately  contained files are parsed as XML, and the resulting sequence of
253       document nodes is passed as the value of the  parameter.  For  example,
254       +lookup=lookup.xml sets the value of the stylesheet parameter lookup to
255       the document node at the root of the tree representing the parsed  con‐
256       tents of the file lookup.xml.
257
258       Under Windows, and some other operating systems, it is possible to sup‐
259       ply a value containing spaces by enclosing it  in  double  quotes,  for
260       example  name=John  Smith.  This  is  a feature of the operating system
261       shell, not something Saxon does, so it may not work the same way  under
262       every operating system. (In the jEdit console plugin it has to be writ‐
263       ten as name=John Smith)
264
265       If the parameter name is in a non-null namespace, the parameter can  be
266       given  a  value  using the syntax {uri}localname=value. Here uri is the
267       namespace URI of the parameter's name, and localname is the local  part
268       of the name.
269
270       This  applies  also  to output parameters. For example, you can set the
271       indentation    level    to     4     by     using     the     parameter
272       !{http://saxon.sf.net/}indent-spaces=4.  See also Additional attributes
273       for xsl:output.
274
275       If the -a option is used, the name of the stylesheet  is  omitted.  The
276       source  document  must contain a <?xml-stylesheet?> processing instruc‐
277       tion before the first element start tag;  this  processing  instruction
278       must have a pseudo-attribute href that identifies the relative or abso‐
279       lute URL of the stylsheet document, and a pseudo-attribute  type  whose
280       value is text/xml, application/xml, or text/xsl. For example:
281
282       <?xml-stylesheet type=text/xsl href=../style3.xsl ?>
283
284       It is also possible to refer to a stylesheet embedded within the source
285       document, provided it has an id  attribute  and  the  id  attribute  is
286       declared in the DTD as being of type ID.
287

FILES

289       /etc/java/resolver/CatalogManager.properties
290              The central catalog manager configuration file used by saxon for
291              resolving XML  entities  and  URIs  if  xml-commons-resolver  is
292              available.
293

SEE ALSO

295       xsltproc(1)
296

AUTHOR

298       Michael H. Kay <mike@saxonica.com>
299
300
301
3028.7                               March 2006                         SAXON8(1)
Impressum