incubator-odf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From robw...@apache.org
Subject svn commit: r1161237 - in /incubator/odf/site/trunk/content/odftoolkit: conformance/ODFValidator.mdtext xsltrunner/Home.mdtext xsltrunner/ODFXSLTRunner.mdtext xsltrunner/ODFXSLTRunnerExamples.mdtext xsltrunner/ODFXSLTRunnerTask.mdtext
Date Wed, 24 Aug 2011 19:27:34 GMT
Author: robweir
Date: Wed Aug 24 19:27:34 2011
New Revision: 1161237

URL: http://svn.apache.org/viewvc?rev=1161237&view=rev
Log:
Checking in initial website files for Conformance and XSLT tools.   These are really media
wiki format, not mdtext, I will
expect to get many errors which I will then fix in-place via
the web interface.

Added:
    incubator/odf/site/trunk/content/odftoolkit/conformance/ODFValidator.mdtext   (with props)
    incubator/odf/site/trunk/content/odftoolkit/xsltrunner/Home.mdtext   (with props)
    incubator/odf/site/trunk/content/odftoolkit/xsltrunner/ODFXSLTRunner.mdtext   (with props)
    incubator/odf/site/trunk/content/odftoolkit/xsltrunner/ODFXSLTRunnerExamples.mdtext  
(with props)
    incubator/odf/site/trunk/content/odftoolkit/xsltrunner/ODFXSLTRunnerTask.mdtext   (with
props)

Added: incubator/odf/site/trunk/content/odftoolkit/conformance/ODFValidator.mdtext
URL: http://svn.apache.org/viewvc/incubator/odf/site/trunk/content/odftoolkit/conformance/ODFValidator.mdtext?rev=1161237&view=auto
==============================================================================
--- incubator/odf/site/trunk/content/odftoolkit/conformance/ODFValidator.mdtext (added)
+++ incubator/odf/site/trunk/content/odftoolkit/conformance/ODFValidator.mdtext Wed Aug 24
19:27:34 2011
@@ -0,0 +1,212 @@
+__TOC__
+
+'''ODF Validator''' is a tool that validates OpenDocument files and checks them for certain
conformance criteria.
+
+'''ODF Validator''' is available as an [http://tools.odftoolkit.org/odfvalidator online service]
and as a command line tool. This page primarily describes the command line tool. Please visit
the [http://tools.odftoolkit.org/odfvalidator ODF Online Validator] web page for details regarding
the online tool.
+
+== How to start ==
+To use the '''ODF Validator''', the following steps are required:
+
+* Get the [[#Source_Code |'''ODF Validator''' source code]].
+* Add the jar files listed under [[#Requirements|Requirements]] to the project's libraries.
+* Get the ODF 1.0, 1,1 and 1.2 [[#Where_do_I_get_the_schemas|schemas]], and add the directories
where your local copies of the schemas are stored to the '''schema.user.properties''' file.
+* Get the MathML 1.01 DTD and the MathML 2.0 [[#Where_do_I_get_the_schemas|schemas]], and
add the directories where you local copies of the schemas are stored to the '''schema.user.properties'''
file.
+* Build the project.
+* Choose an arbitray OpenDocument file '''<odffile>'''. 
+* If you are using JRE 1.5, call the '''ODF Validator''' with
+
+ java -jar "<path>/odfvalidator.jar" <odffile>
+
+* If you are using JRE 1.6, call the '''ODF Validator''' with
+
+ java 
+  -Djavax.xml.validation.SchemaFactory:http://relaxng.org/ns/structure/1.0=org.iso_relax.verifier.jaxp.validation.RELAXNGSchemaFactoryImpl
+  -Dorg.iso_relax.verifier.VerifierFactoryLoader=com.sun.msv.verifier.jarv.FactoryLoaderImpl
+  -jar "<path>/odfvalidator.jar"  <odffile>
+
+== Usage ==
+
+=== Usage Summary ===
+
+In an Java 1.5 environment, '''ODF Validator''' is invoked by the following command:
+
+ java -jar "<path>/odfvalidator.jar"
+
+In an Java 1.6 environment, the following command line has to be used:
+
+ java
+  -Djavax.xml.validation.SchemaFactory:http://relaxng.org/ns/structure/1.0=org.iso_relax.verifier.jaxp.validation.RELAXNGSchemaFactoryImpl
+  -Dorg.iso_relax.verifier.VerifierFactoryLoader=com.sun.msv.verifier.jarv.FactoryLoaderImpl
+  -jar "<path>/odfvalidator.jar"
+
+These command lines are abbreviated ''odfvalidator'' from now on.
+
+The '''ODF Validator''' may be called with the following options:
+
+ odfvalidator [-r] [-c|-e|-s] [-d] [-v|-w] [-x <expclude pattern>] 
+              [-o outputfile] [-1.0|-1.1|-1.2] <odffiles>
+ odfvalidator [-r] [-c|-e|-s] [-d] [-v|-w] [-x <expclude pattern>]
+              [-o outputfile] -S <schemafile> <odffiles>
+ odfvalidator [-c|-s] [-v|-w] [-d] [-o outputfile] -C <configfile>
+ odfvalidator -g <odffiles>
+ odfvalidator -h
+ odfvalidator -V
+
+If no parameters are specified, the files '''<odffiles>''' are validated using
the schema that belongs to the ODF version of the file. For ODF 1.0 files the ODF 1.0 schema
is used, for ODF 1.1 files the ODF 1.1 schema is used, and so on. The version of an ODF file
is detected for each file separately.
+
+The options have the following meaning:
+
+'''-1.0''': Use the ODF 1.0 schemas regardless of the version specified by the validated
document.
+
+'''-1.1''': Use the ODF 1.0 schemas regardless of the version specified by the validated
document.
+
+'''-1.2''': Use the ODF 1.0 schemas regardless of the version specified by the validated
document.
+
+'''-c''': Apply ODF conformance rules (ODF 1.0 and 1.1 documents only): Unknown markup is
ignored during validation. For ODF 1.2 documents this option does not have any effect.
+
+'''-e''': Apply extended ODF conformance rules (ODF 1.2 documents only): Unknown markup is
ignored during validation. For ODF 1.0/1.1 documents this option does not have any effect.
+
+'''-d''': Use MathML 1.01 DTD rather than MathML 2.0 schema for content.xml of formula documents.
+
+'''-g''': Show the generator information of the specified '''<odffiles>'''
without validation.
+
+'''-h''': Print a short help.
+
+'''-o''': Print output into specified file rather than standard output.
+
+'''-r''': Process directories recursively.
+
+'''-s''': Use the strict schema for validation (ODF 1.0/1.1 documents only). 
+
+'''-v''': Verbose: print information like the generator or the documents that are processed.
+
+'''-w''': Print warnings.
+
+'''-x''': Exclude files that match the specified [http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html#sum
regular expression] from validation.
+
+'''-C''': Validate using configuration file '''<configfile>'''.
+
+'''-S''': Use the specified '''<schemafile>''' for validation.
+
+'''-V''': Print version information.
+
+=== Validation using default schemas ===
+
+The ODF 1.0, ODF 1.1, ODF 1.2 schemas as well as the MathML 1.01 DTD and the MathML 2.0 schema
are included in the '''ODFValidator.jar''' file. If the ODFValidator is called without the
'''-S''' or '''-C''' options, these schemas are used for validation.
+
+ odfvalidator [-r] [-c|-e|-s] [-d] [-v|-w] [-x <expclude pattern>]
+              [-o outputfile] [-1.0|-1.1|-1.2] <odffiles>
+
+'''<odffiles>''' is the list of files and directories that should be validated.
If a directory is specified, all files that have an OpenDocument extension (like '''odt''',
'''ods''' or '''ott''') are validated. If '''-r''' is specified additionally, all directories
are processed recursively.
+
+By default, the '''ODF Validator''' detects the version of the files that shall be validated
and chooses the corresponding schema. The command line options '''-1.0''', '''-1.1''' and
'''-1.2''' can be used to specify that the schemas of a particular ODF version should be used
for all files, regardless of the version they specify themselves.
+
+The command line option '''-d''' specifies that the MathML 1.01 DTD should be used for the
validation of the '''content.xml''' of formula documents. Default is to use the MathML 2.0
schema.
+
+If the '''-c''' command line option is specified and if the validated document is an ODF
1.0 or ODF 1.1 document, unknown markup is ignored as specified in the conformance rules for
ODF 1.0/1.1.  If the '''-s''' command line option is specified and if the validated document
is an ODF 1.0 or ODF 1.1 document, the strict schema is used for validation. If the '''-e'''
command line option is specified and if the validated document is an ODF 1.2 document, unknown
markup is ignored as specified in the extended conformance class rules for ODF 1.2. If neither
'''-c''' nor '''-e'''  nor '''-s''' are specified, the regular ODF schemas are used and errors
are reported for unknown markup, unless it appears in styles or metadata of ODF 1.0/1.1 documents.
+
+The optional '''-x''' switch allows to exclude certain files or directories from the validation.
The files that shall be excluded are specified by a [http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html#sum
regular expression]. Please note that the full absolute path names of directories and files
are matched against this pattern. This means that the regular expression either must include
the absolute path of the files and directories that shall be excluded, or must start with
'''.*'''. The '''-x''' option can be specified only once. If several paths shall be excluded,
these paths have to be specified in a single regular expression using the '''|''' operator.
+
+If '''-w''' is specified additionally, not only validation errors are reported, but also
warnings.
+
+If '''-v''' is specified additionally, not only validation errors and warnings are reported,
but also the generator stored in the manifest, MIME types, the files that are processed, etc.
+
+If the '''-o''' option is present, all messages go into the specified file. Otherwise, they
are printed to standard out.
+
+=== Validation using a non-default schema ===
+
+To specify the schema that is used for '''meta-xml''', '''content.xml''', '''styles.xml'''
and '''settings.xml''' on the command line, '''ODF Validator''' has to be called with the
following parameters:
+
+ odfvalidator [-r] [-c|-e|-s] [-d] [-v|-w] [-x <expclude pattern>]
+ [-o outputfile] -S <schemafile> <odffiles>
+
+'''<schemafile>''' is the schema that shall be used.
+
+All other command line option are as described in [[#Validation_using_default_schemas|Validation
using default schemas]].
+
+=== Validation using a configuration file ===
+
+The schemas and the files that should be validated can be specified in a configuration file.
A configuration file is a Java XML properties file as described in the [http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html
Java 2 API documentation]. The following properties are supported:
+
+* '''strict-schema''': Specifies the strict schema to be used.
+* '''manifest-schema''': Specifies the manifest schema to be used.
+* '''mathml-schema''': Specifies the MathML 1.01 schema to be used.
+* '''mathml2-schema''': Specifies the MathML 2 schema to be used.
+* '''path*''': All properties whose names start with "path" are considered to be files or
directories that shall be validated. 
+* '''recursive''': This boolean property specifies whether directories are scanned recursively.
It takes the values '''true''' and '''false'''.
+* '''exclude''': Specifies files and directories that shall be excluded as a [http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html#sum
regular expression]. See description of [[#Specifying_the_schema_on_the_command_line|'''-x'''
option]].
+
+A sample configuration file looks like this:
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
+ <properties>
+  <entry key="strict-schema">/home/odf11-cd2/msv/OpenDocument-strict-schema-v1.1-cd2.rng</entry>
+  <entry key="manifest-schema">/home/odf11-cd2/msv/OpenDocument-manifest-schema-v1.1-cd2.rng</entry>
+  <entry key="mathml-schema">/home/odf11-cd2/msv/mathml2.xsd</entry>
+  <entry key="path1">/home/testdocs</entry>
+  <entry key="path2">/home/temp</entry>
+ </properties>
+
+== What is checked? ==
+
+The following items are checked:
+* OpenDocument v1.2 documents:
+** If the test type is <b>conformance test</b> (default, or if '''-c''' is provided)
, and if the file is not a formula file, then the sub files <i>content.xml</i>,
<i>styles.xml</i>, <i>meta.xml</i> and <i>settings.xml</i>
are  validated with respect to the OpenDocument v1.2 schema.
+** If the test type is <b>extended conformance test</b> ('''-e''' is provided),
and if the file is not a formula file, then the sub files <i>content.xml</i>,
<i>styles.xml</i>, <i>meta.xml</i> and <i>settings.xml</i>
are pre-processed as described in section 1.4.2.1 of the OpenDocument v1.2 specification (that
is <i>foreign elements and attributes</i> are removed), and are then validated
with respect to the OpenDocument v1.2 schema.
+* OpenDocument v1.1/1.0 documents:
+** If the test type is <b>conformance test</b> ('''-c''' is provided), and if
the file is not a formula file, then the sub files <i>content.xml</i>, <i>styles.xml</i>,
<i>meta.xml</i> and <i>settings.xml</i> are pre-processed as described
in section 1.5 of the <a href="http://docs.oasis-open.org/office/v1.1/OS/OpenDocument-v1.1.odt">OpenDocument
specification</a> (that is <i>foreign elements and attributes</i> are removed),
and are then validated with respect to the schema of the selected OpenDocument version.
+** If the test type is <b>validation</b> (default), and if the file is not a
formula file, then the sub files <i>content.xml</i>, <i>styles.xml</i>,
<i>meta.xml</i> and <i>settings.xml</i> are validated with respect
to the schema of the selected OpenDocument version. Pre-processing of <i>foreign elements
and attributes</i> is not applied.
+** If the test type is <b>strict validation</b> ('''-s''' is provided), and if
the file is not a formula file, then the sub files <i>content.xml</i>, <i>styles.xml</i>,
<i>meta.xml</i> and <i>settings.xml</i> are validated with respect
to the strict schema of the selected OpenDocument version. Pre-processing of <i>foreign
elements and attributes</i> is not applied.
+* All versions:
+** If the file is a formula file, then the sub file <i>content.xml</i> is validated
with respect to the MathML 2.0 W3C XSD schema.  The sub files <i>styles.xml</i>,
<i>meta.xml</i> and <i>settings.xml</i> are checked as described for
other document types.
+** The file <i>META-INF/manifest.xml</i> is validated with respect to the manifest
schema of the selected ODF specification.
+** If the file is an ODF 1.2 file, then the <i>META-INF/documentsignatures.xml</i>
and <i>META-INF/macrosignatures.xml</i> sub files are validated with respect to
the digital signatures schema of the ODF 1.2 specification.
+** For all embedded objects in ODF format, the <i>content.xml</i>, <i>styles.xml</i>,
<i>meta.xml</i> and <i>settings.xml</i> are validated as described
for the main document above.
+** It is checked whether the file itself ans all embedded objects in ODF format contain at
least a <i>content.xml</i> or <i>styles.xml</i> sub file.
+
+The following actions take place before or during the validation:
+* A DTD document declaration within a <i>manifest.xml</i> file is ignored. For
the logging level <b>all</b>, an information is displayed if this happens. <br/><b>Note:</b>
Very early ODF implementations in OpenOffice.org wrongly included a document type declaration.
Ignoring the document type enables the validation of the manifest despite of this error.
+* A namespace &quot;http://openoffice.org/2001/manifest&quot; within a <i>manifest.xml</i>
file is changed to &quot;urn:oasis:names:tc:opendocument:xmlns:manifest:1.0&quot;.
For the logging level <b>all</b>, an information is displayed if this happens.
<br/><b>Note:</b> Early ODF implementations in OpenOffice.org used the wrong
namespace. Changing it to the correct one enables the validation of the manifest despite the
wrong namespace.
+* Namespaces defined in the <a href="http://www.oasis-open.org/committees/download.php/10765/office-spec-1.0-cd-2.pdf">ODF
v1.0 Committee Draft 2</a> are replaced with those of the <a href="http://www.oasis-open.org/specs/index.php#opendocumentv1.0">ODF
v1.0 OASIS Standard</a>. For the logging level <b>all</b>, an information
is displayed if this happens.<br/><b>Note:</b> Changing the namespaces enables
the validation of documents that conform to the ODF v1.0 CD2. Such documents have been saved
by OpenOffice.org 1.0 beta versions.
+* The value of <i>draw:points</i> attributes is truncated to 2048 characters.
For the logging level <b>all</b>, an information is displayed if this happens.<br/><b>Note:</b>
The truncation of this attribute value avoids a stack overflow in MSV while validating the
attribute value against a regular expression.
+* A namespace &quot;http://openoffice.org/2004/database&quot; within a <i>content.xml</i>
file is changed to &quot;urn:oasis:names:tc:opendocument:xmlns:database:1.0&quot;,
and a namespace &quot;http://openoffice.org/2004/office&quot; within a <i>content.xml</i>
file is changed to &quot;urn:oasis:names:tc:opendocument:xmlns:office:1.0&quot;. For
the logging level <b>all</b>, an information is displayed if this happens.<br/><b>Note:</b>
These namespaces were used in OpenOffice.org 2.x database documents, because database documents
are included in OpenDocument since version 1.2 only. Changing them enables the validation
of  OpenOffice.org 2.x database documents.
+
+
+== Where do I get the schemas? ==
+
+<span id="Where_do_I_get_the_schemas"></span>The OpenDocument schemas are available
on the [http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=office OASIS OpenDocument
technical Committee] page. The ODF 1.0 and 1.1 schemas can be downloaded directly from that
[http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=office#technical page]. A zip
file containing the most recent ODF 1.2 schemas is available in the [http://www.oasis-open.org/committees/documents.php?wg_abbrev=office
document section].
+
+The MathML DTD that is included in the ODFValidator us the one that is included in the '''/share/dtd/math/1_01/'''
folder of each OpenOffice.org/Oracle Open Office installation.
+
+== Requirements ==
+
+'''ODF Validator''' requires J2RE 1.5 or J2RE 1.6. For J2RE 1.6, the following options have
to be included into the '''java''' command line:
+
+ -Djavax.xml.validation.SchemaFactory:http://relaxng.org/ns/structure/1.0=org.iso_relax.verifier.jaxp.validation.RELAXNGSchemaFactoryImpl
 
+ -Dorg.iso_relax.verifier.VerifierFactoryLoader=com.sun.msv.verifier.jarv.FactoryLoaderImpl
+
+'''ODF Validator''' further requires the following packages:
+
+* [https://msv.dev.java.net/ MSV]. '''msv.jar''', '''isorelax.jar''', '''relaxngDatatype.jar'''
and '''xsdlib.jar''' included in the MSV distribution must be added to the project's libraries
and must be in the classpath or a folder called '''lib''' that is next to the '''odfvalidator.jar'''
at runtime. 
+* [https://isorelax-jaxp-bridge.dev.java.net/ ISORELAX JARV -&gt; JAXP 1.3 Xml Validation
Engine Adaptor].  '''isorelax-jaxp-bridge-1.0.jar''' must be added to the project's libraries
and must be in the classpath or a folder called '''lib''' that is next to the '''odfvalidator.jar'''
 at runtime. 
+* ''' odfdom.jar''' from the <a href="{{project odfdom page Home}}">ODFDOM project
</a>  must be added to the project's libraries and must be in the classpath or a folder
called '''lib''' that is next to the '''odfvalidator.jar'''  at runtime. 
+
+The NetBeans project is pre-configured to build ODFDOM while building '''ODF Validator'''.
This requires that the ODFDOM sources are located in a folder '''odfdom''' next to the folder
of the '''ODF Validator''' project.
+
+Alternatively, the reference to the ODFDOM project in the compile time classpath of the '''ODF
Validator''' project may be replaced with a reference to an already compiled '''odfdom.jar'''.
+
+The references to all other jar files must be updated manually before building ''' ODF Validator'''.
+
+'''Note:''' <a href="{{project odfdom page Home}}">ODFDOM</a> requires [http://xml.apache.org/dist/xerces-j/
Apache's xerces]. The jar file '''xercesImpl.jar''' also must exist in a folder '''lib'''
next to '''odvalidator.jar''' file, or it must be in the classpath. The '''ODF Validator'''
NetBeans projects includes a reference to '''xersesImpl.jar''' in the runtime classpath which
has to be adapted after checking out the project.
+
+'''Note:''' <a href="{{project odfdom page Home}}">ODFDOM</a> requires at least
Xerces 2.8.0. Please note that MSV distribution contains an xercesImpl.jar which is older.

+
+== Source Code ==
+
+The '''ODF Validator''' [http://odftoolkit.org/projects/conformancetools/sources/odf-validator-src/show
source code] is located [http://odftoolkit.org/projects/conformancetools/sources/odf-validator-src/show
here]. '''ODF Validator''' uses Mercurial for source control. Please check the 
+<a href="{{project help page SourceControl}}">help</a> for instruction how to
use Mercurial.
+
+The '''ODFValidator''' ia a NetBeans project. To work with the project, just open the project
folder.
+
+<p style="margin: 15px 0px"><center>Back to: [[Home|ODF Conformance and other
Tools Wiki Home]]</center></p>

Propchange: incubator/odf/site/trunk/content/odftoolkit/conformance/ODFValidator.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/odf/site/trunk/content/odftoolkit/xsltrunner/Home.mdtext
URL: http://svn.apache.org/viewvc/incubator/odf/site/trunk/content/odftoolkit/xsltrunner/Home.mdtext?rev=1161237&view=auto
==============================================================================
--- incubator/odf/site/trunk/content/odftoolkit/xsltrunner/Home.mdtext (added)
+++ incubator/odf/site/trunk/content/odftoolkit/xsltrunner/Home.mdtext Wed Aug 24 19:27:34
2011
@@ -0,0 +1,16 @@
+<a href="http://www.oasis-open.org/committees/office" target="_blank">[[image: oasis_odf_logo.png
|right]]</a>
+= <span style="color:#E86F00;font-style:italic;font-weight:bold;">ODF Conformance and
other Tools Wiki</span> =
+
+This project develops tools for checking [http://www.oasis-open.org/committees/office ODF]
conformance as well as tools that simplify the processing of ODF documents.
+
+= Conformance Tools =
+Tools for validating and checking conformance of of ODF documents.
+
+* [[ODFValidator]]: A validating for ODF documents.
+* [http://tools.odftoolkit.org/odfvalidator Online ODF Validator]: An online validator for
ODF documents.
+
+= Application and Tools =
+Other tools for processing ODF documents.
+
+* [[ODFXSLTRunner|ODF XSLT Runner]]: A tools that simplifies the application of XSLT stylesheets
to ODF documents.
+* [[ODFXSLTRunnerTask|ODF XSLT Runner Task]]: An Ant task for the application of XSLT stylesheets
to ODF documents.

Propchange: incubator/odf/site/trunk/content/odftoolkit/xsltrunner/Home.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/odf/site/trunk/content/odftoolkit/xsltrunner/ODFXSLTRunner.mdtext
URL: http://svn.apache.org/viewvc/incubator/odf/site/trunk/content/odftoolkit/xsltrunner/ODFXSLTRunner.mdtext?rev=1161237&view=auto
==============================================================================
--- incubator/odf/site/trunk/content/odftoolkit/xsltrunner/ODFXSLTRunner.mdtext (added)
+++ incubator/odf/site/trunk/content/odftoolkit/xsltrunner/ODFXSLTRunner.mdtext Wed Aug 24
19:27:34 2011
@@ -0,0 +1,82 @@
+__TOC__
+
+== Simplify the application of XSLT stylesheets to ODF documents ==
+'''ODF XSLT Runner''' is a small Java application that allows you to apply XSLT stylesheets
to XML streams included in ODF packages without extracting them from the package. It can be
used from the command line. A driver to use it within Ant buildfiles is also [[ODFXSLTRunnerTask|available]].
+
+== Getting and building ODF XSLT Runner ==
+
+'''ODF XSLT Runner''' is build by a NetBeans project. After you have <a href="{{project
help page SourceControl}}">checked out</a> the [http://odftoolkit.org/projects/conformancetools/sources/odf-xslt-runner-src/show
sources] from the Mercurial repository, you can open the project in [http://www.netbeans.info/downloads/index.php
NetBeans] and build '''odfxsltrunner'''.
+
+A binary release of '''odfxsltrunner.jar''' is available in the [http://odftoolkit.org/projects/conformancetools/downloads
download section].
+
+Building and running '''odfxsltrunner.jar''' requires additional jar files. Please see [[#Requirements|Requirements]]
for details.
+
+== Command Line Options ==
+
+'''ODF XSLT Runner''' is called by one of the below command lines:
+
+ java -jar odfxsltrunner.jar &lt;style sheet&gt; [-v] [-f &lt;factory&gt;]
[-p &lt;path in package&gt;]
+  [-l log file] &lt;input package&gt; [&lt;output package&gt; [name=value
...]
+ 
+ java -jar odfxsltrunner.jar &lt;style sheet&gt; [-v] [-f &lt;factory&gt;]
[-p &lt;path in package&gt;]
+ [-l log file] -t &lt;input package&gt; &lt;output package&gt; [name=value
...]
+ 
+ java -jar odfxsltrunner.jar &lt;style sheet&gt; [-v] [-f &lt;factory&gt;]
[-p &lt;path in package&gt;]
+  [-l log file] -r &lt;package&gt; [name=value ...]
+ 
+ java -jar odfxsltrunner.jar &lt;style sheet&gt; [-v] [-f &lt;factory&gt;]
[-p &lt;path in package&gt;]
+  [-l log file] [-x &lt;extract path&gt; ...] -o &lt;input package&gt; &lt;output
file&gt; [name=value ...]
+ 
+ java -jar odfxsltrunner.jar &lt;style sheet&gt; [-v] [-f &lt;factory&gt;]
[-p &lt;path in package&gt;]
+  [-l log file] -i &lt;input file&gt; &lt;output package&gt; [name=value
...]
+
+The default is to apply the XSLT stylesheet '''&lt;style-sheet&gt;''' to the stream
'''content.xml''' of the ODF file '''&lt;input package&gt;'''. If no '''&lt;output
package&gt;''' parameter is specified, then the result of the transformation will be printed
to the standard output. If an '''&lt;output package&gt;''' is specified, the '''&lt;input
package&gt;''' is copied to the '''&lt;output package&gt;''', and the steam '''content.xml'''
of the '''&lt;output package&gt;''' is replaced with the result of the transformation.
+
+The '''-p''' option allows to specify another stream in the package as source of the transformation
than '''content.xml'''.
+
+The '''-t''' options allows to specify a template for the output package. If it is used,
the result of the transformation is stored in the '''content.xml''' stream (or the stream
specified by the '''-p''' option) of the '''&lt;output package&gt;''', but other streams
of '''&lt;output package&gt;''' than that are not modified. This option can be used
together with the '''-i''' option to create an ODF file from a plain XML file.
+
+The '''-i''' option allows to specify a plain XML file '''&lt;input file&gt;''' as
source of the transformation. 
+
+If the '''-o''' option is specified, the result of the transformation is stored in the plain
'''&lt;output file&gt;''' rather than in a ODF package. This is for instance of interest
if the result of the transformation is HTML. The '''-x''' option can be used to extract further
files from the input package. A file or directory specified by this option is extracted from
the package into the directory of the output file. The '''-x''' option can be specified multiple
times.
+
+The '''-r''' option allows to modify the '''content.xml''' stream (or the stream specified
by the '''-p''' option) in place. If it is specified, the result of the transformation just
replaces the stream that was the source of the transformation. This option should be used
with care, because it modifies the original input ODF file.
+
+The '''-v''' option enables a verbose mode.
+
+The '''-f''' option specifies the ''javax.xml.transform.TransformerFactory'' to use. '''Note:'''
When calling ''java'' with the ''-jar'' option, the user class path is ignored. If a transformer
factory is used which is not contained in the JRE, like Saxon, '''odfxsltrunner''' has to
be called without the ''-jar'' option:
+
+ java -cp odfxsltrunner.jar:&lt;factory jar&gt; org.odftoolkit.odfxsltrunner.Main
...
+
+The '''-l''' option can be used to redirect diagnostic messages into a log file. By default
they are printed on standard error.
+
+XSLT [http://www.w3.org/TR/1999/REC-xslt-19991116#top-level-variables Parameters] can be
passed to the transformation by specifying them as name=value pairs. They must appear behind
all other command line parameters.
+
+== URI resolution/document() function ==
+If the source of a transformation is an ODF package, the XSLT ''[http://www.w3.org/TR/1999/REC-xslt-19991116#document
document()]'' function can be used to access other files in the package than the one that
is the source of the transformation. To do so, the first parameter of the ''document()'' function
must be a relative URI that references the file that shall be accessed. The reference must
be relative to the source file. The second parameter of the ''document()'' function must be
a node within the source file.
+
+'''Note:''' The second parameter specifies the base URI for the resolution of the URI that
is specified by the first parameter. This base URI is the base URI of the file that contains
the node that is passed as second parameter. If the second parameter is omitted, the base
URI is the one of the XSLT stylesheet containing the ''document()'' function itself. '''odfxsltrunner'''
runner uses the rules ODF defines for resolving relative URIs only for URIs that are relative
to a file within an ODF package.
+
+'''Example:''' When transforming a content.xml file contained in an ODF package, the following
rule applies templates to the style elements contained in the style.xml file:
+
+ <xsl:apply-templates select="document('styles.xml',.)//office:styles/style:style"/>
+
+
+== Requirements ==
+
+'''ODF XSLT Runner''' requires [http://java.sun.com/javase/downloads/index.jsp J2RE 5], or
a later version of Java.
+
+It further requires <a href="{{project odfdom page home}}">ODFDOM</a>. The NetBeans
project is pre-configured to build ODFDOM while building '''ODF XSLT Runner'''. This requires
that the ODFDOM sources are located in a folder '''odfdom''' next to the folder of the '''ODF
XSLT Runner''' project.
+
+Alternatively, the reference to the ODFDOM project in the compile time classpath of the '''ODF
XSLT Runner''' project may be replaced with a reference to an already compiled '''odfdom.jar'''.
+
+At run time, the '''odfdom.jar''' file must be either located in folder called '''lib'''
next to the '''odfxsltrunner.jar''' file, or it must be in the classpath. 
+
+'''Note:''' <a href="{{project odfdom page home}}">ODFDOM</a> requires [http://xml.apache.org/dist/xerces-j/
Apache's xerces]. The jar file '''xercesImpl.jar''' also must exist in a folder '''lib'''
next to '''odfxsltrunner.jar''' file, or it must be in the classpath. The '''ODF XSLT Runner'''
NetBeans projects includes a reference to '''xersesImpl.jar''' in the runtime classpath which
has to be adapted after checking out the project.
+
+== Examples ==
+
+Example stylesheets can be found on the [[ODFXSLTRunner Examples]] page.
+
+<p style="margin: 15px 0px"><center>Back to: [[Home|ODF Conformance and other
Tools Wiki Home]]</center></p>
+

Propchange: incubator/odf/site/trunk/content/odftoolkit/xsltrunner/ODFXSLTRunner.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/odf/site/trunk/content/odftoolkit/xsltrunner/ODFXSLTRunnerExamples.mdtext
URL: http://svn.apache.org/viewvc/incubator/odf/site/trunk/content/odftoolkit/xsltrunner/ODFXSLTRunnerExamples.mdtext?rev=1161237&view=auto
==============================================================================
--- incubator/odf/site/trunk/content/odftoolkit/xsltrunner/ODFXSLTRunnerExamples.mdtext (added)
+++ incubator/odf/site/trunk/content/odftoolkit/xsltrunner/ODFXSLTRunnerExamples.mdtext Wed
Aug 24 19:27:34 2011
@@ -0,0 +1,41 @@
+= ODF XSLT Runner and ODF XSLT Runner Task Examples =
+
+__TOC__
+
+== XHTML ==
+
+The XHTML transformation contained in [http://www.openoffice.org OpenOffice.org] can be used
to transform ODF documents into XHTML. Using '''ODFXSLTRunner''' it is not even required to
extract the ODF package.
+
+The XHTML style sheet runs only with the [http://saxon.sourceforge.net/ SAXON XSLT Processor].
Using version 9.1 is recommended.
+
+The following command converts an ODF text document ''&lt;ODT&gt;'' into an XHTML
document ''&lt;XHTML&gt;'':
+
+ java -cp odfxsltrunner.jar:&lt;saxon.jar&gt; org.odftoolkit.odfxsltrunner.Main
+   -f net.sf.saxon.TransformerFactoryImpl  -x Pictures/ 
+  &lt;ooo-xslt&gt;/export/xhtml/opendoc2xhtml.xsl &lt;ODT&gt; -o &lt;XHTML&gt;
+
+''&lt;saxon.jar&gt;'' is the jar of the [http://saxon.sourceforge.net/ SAXON XSLT
Processor].  &lt;ooo-xslt&gt; is the location of the OpenOffice.org XSLT stylesheets
within an OpenOffice.org installation. In a typical OpenOffice.org installation, this is <tt>openoffice.org/basis3.3/share/xslt</tt>
(Linux) or <tt>Basis/share/xslt</tt> (Windows).
+
+'''Note:''' A few changes are necessary to use OpenOffice.org's XHTML transformation with
'''ODFXSLTRunner'''. These are available as patch in the OpenOffice.org issue [http://qa.openoffice.org/issues/show_bug.cgi?id=115881
i115881].
+
+== XHTML with referenced images only ==
+The XHTML  transformation in the above example extracts all images from the ODF document,
regardless whether these are referenced in the XHTML document. To extract only the images
that are referenced a list of referenced images may be created by  the '''create-html-img-list.xsl'''
style sheet that is contained in the '''sample-xslt''' folder of '''ODFXSLTRunner'''. It is
applied to the XHTML file, and the target is a text file that contains the references images.
Although the input file is an XHTML rather than a ODF file, '''ODFXSLTRunner''' may be used
to apply the style sheet.
+
+ java -jar odfxsltrunner.jar create-html-img-list.xsl -i &lt;XHTML&gt; -o &lt;img-list&gt;

+ unzip &lt;ODT&gt; `&lt;img-list&gt;`
+
+== Replace embedded objects with bitmap images ===
+Unlike [http://www.openoffice.org OpenOffice.org]'s HTML filter, the XSLT-based XHTML filter
does not convert embedded objects into bitmap images. It is however possible to replace the
embedded objects of ODF document with the images that the HTML filter has exported by applying
the '''replace-object.xsl''' style sheet that is contained in the '''sample-xslt''' folder
of '''ODFXSLTRunner''' to the ODF document.
+
+The following steps are required:
+* Load the ODT document into OpenOffice.org and save it with the HTML filter. The file may
have an arbitrary name. ''&lt;ooo-html-file&gt;'' is used as a placeholder here.
+* Convert the HTML file into an XHTML file. You may use '''xmllint''' for this purpose, which
is part of [http://xmlsoft.org/ libxml2], or any other tools that converts HTML into XHTML.
The command line for '''xmllint''' is:
+ xmllint --html --xmlout --dropdtd -o &lt;ooo-xhtml-file&gt; &lt;ooo-html-file&gt;
+* Apply the '''replace-object.xsl''' style sheet to the ODF document. The style sheet requires
the name of the XHTML file converted in the previous step as '''hrml-ref''' parameter.
+ java -jar odfxsltrunner.jar replace-objects.xsl &lt;input odf&gt; &lt;output
odf&gt; 
+  ref-html=&lt;ooo-xhtml-file&gt;
+* Zip the images that OpenOffice.org has saved next to the HTML document into the output
ODF file.
+The new ODF file now can be transformed to XHTML with OpenOffice.org's XHTML transformation.
+
+
+

Propchange: incubator/odf/site/trunk/content/odftoolkit/xsltrunner/ODFXSLTRunnerExamples.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/odf/site/trunk/content/odftoolkit/xsltrunner/ODFXSLTRunnerTask.mdtext
URL: http://svn.apache.org/viewvc/incubator/odf/site/trunk/content/odftoolkit/xsltrunner/ODFXSLTRunnerTask.mdtext?rev=1161237&view=auto
==============================================================================
--- incubator/odf/site/trunk/content/odftoolkit/xsltrunner/ODFXSLTRunnerTask.mdtext (added)
+++ incubator/odf/site/trunk/content/odftoolkit/xsltrunner/ODFXSLTRunnerTask.mdtext Wed Aug
24 19:27:34 2011
@@ -0,0 +1,88 @@
+__TOC__
+
+== Apply XSLT stylesheets to ODF documents with Ant ==
+'''ODFXSLTRunnerTask''' is a task definition for [http://ant.apache.org/ Ant] which allows
to apply XSLT stylesheets to ODF documents similar to Ant's build-in <tt>&lt;xslt&gt;</tt>
[http://ant.apache.org/manual/CoreTasks/style.html task]. It is based on  [[ODFXSLTRunner]].
Please see [[ODFXSLTRunner]] for further details of its operation.
+
+
+== Getting and building ODFXSLTRunnerTask ==
+
+'''odfxsltrunnertask''' is build by a NetBeans project. After you have checked out the [http://odftoolkit.org/projects/conformancetools/sources/odf-xslt-runner-task-src/show],
you can open the project in [http://www.netbeans.info/downloads/index.php NetBeans] and build
'''odfxsltrunnertask'''.
+
+A binary release of '''odfxsltrunnertask.jar''' is available in the [http://odftoolkit.org/projects/conformancetools/downloads
download section].
+
+Building and running '''odfxsltrunner.jar''' requires additional jar files. Please see [[#Requirements|Requirements]]
for details.
+
+== Usage ==
+
+To use '''odfxsltrunner.jar''' with Ant, you have to include the following [http://ant.apache.org/manual/CoreTasks/taskdef.html
task definition] into your buildfile, where ''<tt>&lt;path&gt;</tt>''
has to be replaced with the path where you have stored the '''odfxsltrunnertask.jar''' and
'''odfxsltrunner.jar''' files:
+
+ 
+ &lt;taskdef name="odfxslt" classname="odfxsltrunnertask.ODFXSLTRunnerTask" 
+          classpath="''&lt;path&gt;''/odfxsltrunnertak.jar:''&lt;path&gt;''/odfxsltrunner.jar"/&gt;
+ 
+
+You can use this task definition on the top level (that is as a child element of the <tt>&lt;project&gt;</tt>
element or locally within a single <tt>&lt;target&gt;</tt> element. It
defines a new task <tt>&lt;odfxslt&gt;</tt> which allows to process ODF
documents with XSLT stylesheets.
+
+The new task supports the use of nested <tt>&lt;param&gt;</tt> and <tt>&lt;factory&gt;</tt>elements
which have the same meaning as the <tt>&lt;param&gt;</tt> and <tt>&lt;factory&gt;</tt>
child elements of the <tt>&lt;xslt&gt;</tt> [http://ant.apache.org/manual/CoreTasks/style.html
task].
+
+== Parameters ==
+
+<table border="border">
+<tr><th>Attribute</th><th>Description</th><th>Required</th></tr>
+<tr><td valign="top">in</td><td valign="top">specifies an ODF document
to which the stylesheet is applied.</td><td valign="top">Yes, unless infile has
been specified</td></tr>
+<tr><td valign="top">infile</td><td valign="top">specifies a plain
XML document to which the stylesheet is applied.</td><td valign="top">Yes, unless
in has been specified</td></tr>
+<tr><td valign="top">out</td><td valign="top">specifies an ODF document
to which the result of the transformation is stored.<br/>
+Unless template has been specified, the package specified by in is copied to out, and the
stream specified by path is replaced with the result of the transformation.</td><td
valign="top">Yes, unless outfile has been specified</td></tr>
+<tr><td valign="top">outfile</td><td valign="top">specifies a plain
XML document to which the result of the transformation is stored.</td><td valign="top">Yes,
unless out has been specified</td></tr>
+<tr><td valign="top">path</td><td valign="top">Specifies the stream
within the ODF packages specified by in and out, which is the source or target of the transformation.</td><td
valign="top">No</td></tr>
+<tr><td valign="top">template</td><td valign="top">Specifies that
the specified stream within the out ODF package is replaced with the result of the transformation,
without previously copying the package specified by in. The specified out package must exist.</td><td
valign="top">No:  Default is "content.xml"</td></tr>
+<tr><td valign="top">force</td><td valign="top">Specifies that the
target file shall be recreated, even if it is newer than the source file or the stylesheet.</td><td
valign="top">No: Default is false</td></tr>
+</table>
+
+== Parameters specified as nested elements ==
+
+=== Param ===
+
+Param specifies a parameter that is passed as [http://www.w3.org/TR/1999/REC-xslt-19991116#top-level-variables
XSLT parameter] to the XSL stylesheet.
+
+==== Parameters ====
+
+<table border="border">
+<tr><th>Attribute</th><th>Description</th><th>Required</th></tr>
+<tr><td valign="top">name</td><td valign="top">name of the parameter.</td><td
valign="top">Yes</td></tr>
+<tr><td valign="top">expression</td><td>value of the parameter.
+'''Note:''' All parameter values are passed as string values to the XSLT parameters specified
by <tt>&lt;xslt:param&gt;</tt> elements within the stylesheet.
+</td><td valign="top">Yes</td></tr>
+</table>
+
+'''Note:''' The parameters <tt>if</tt> and <tt>unless</tt> which
are supported by the <tt>&lt;xslt&gt;</tt> task are (not yet) supported.
+
+=== Factory ===
+
+Factory specifies Java TransformerFactory class to use.
+
+==== Parameters ====
+
+<table border="border">
+<tr><th>Attribute</th><th>Description</th><th>Required</th></tr>
+<tr><td valign="top">name</td><td valign="top">full qualified TransformerFactory
class name.</td><td valign="top">Yes</td></tr>
+</table>
+
+== Requirements ==
+
+'''odfxsltrunnertask''' requires [http://java.sun.com/javase/downloads/index.jsp J2RE 5],
or a later version of Java. 
+
+It further requires [[ODFXSLTRunner]] and [http://odftoolkit.openoffice.org/servlets/ProjectDocumentList?folderID=759&expandFolder=759&folderID=771
ODFDOM] (at least version  v0.6.1). 
+
+'''Note:''' When building '''odfxsltrunertask''', the '''odfxsltrunner''' project has be
checked out, too. It is build automatically.
+
+In the Ant task definition, the '''classpth''' attribute must include the '''odfxsltrunnertask.jar'''
and '''odfxsltrunner.jar''' files. The  ODFDOM jar file is found automatically if it is located
in a folder called '''lib''' next to the '''odfxsltrunner.jar''' file. 
+
+'''Note:''' <a href="{{project odfdom page home}}">ODFDOM</a> v0.6.1  requires
[http://xml.apache.org/dist/xerces-j/ Apache's xerces]. The jar file '''xercesImpl.jar'''
also must exist in a folder '''lib''' next to '''odfxsltrunner.jar''' file.
+
+== Background Information ==
+
+[http://blogs.sun.com/GullFOSS/entry/applying_xslt_stylesheets_to_odf Applying XSLT stylesheets
to ODF documents with Ant]
+
+<p style="margin: 15px 0px"><center>Back to: [[Home|ODF Conformance and other
Tools Wiki Home]]</center></p> 
+

Propchange: incubator/odf/site/trunk/content/odftoolkit/xsltrunner/ODFXSLTRunnerTask.mdtext
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message