Chapter 2. XSL stylesheets.

If you need to convert pilot-qof data into other formats, take a look at the example stylesheets installed with datafreedom-qsfxsl. You are welcome to contribute new or amended stylesheets - just post them on the QOF-devel mailing list or use the Wiki. A few simple bash scripts are also included to show how to reference the installed XSL stylesheets.

These stylesheets convert all data in the QSF XML file. Use the query support within pilot-qof to filter out unwanted records before conversion.

Referencing datafreedom XSL stylesheets. The examples in this manual reference datafreedom XSL stylesheets by a unique resource identifier (URI) as opposed to a location (URL) on the local filesystem or the internet. This identifier serves to ensure that datafreedom XSL is distinguishable from other XSL files with the same name on the system and, more importantly, to provide a more memorable and system-independent identifier. i.e. the URI will work on any system, no matter how the package maintainer configures the installation directories. To use these URI's (which in the case of pilot-qof refer to XSL at you need to install not just xsltproc but also xml-core or "recursion errors" will occur. Both xsltproc and xml-core are recommended by datafreedom-qsfxsl and should be installed by anyone wanting to use the XSL examples in this manual.

It could be considered rude to require network access for XSL conversions so although the examples use the site as an identifier, the examples also specify the xsltproc option --nonet which prevents xsltproc from attempting to get the XSL from the internet. Currently, the stylesheets are not actually available online because the string is used as an identifier, not a location, although it can be used as both.

Whilst some stylesheet content can be converted back into XML (and thence into QSF XML), this is not always possible. If two way conversions are important to you, please look at the datafreedom-perl package and ask on the QOF-devel mailing list.

Depending on your package manager, catalog.xml, the XSL stylesheets and scripts should be installed in /usr/share/xml/datafreedom/xsl/, or on Fink /sw/share/xml/datafreedom/xsl/.

Chunking - writing separate files to a directory

xsltproc is not particularly graceful in handling output errors involving "chunking". Take note of the examples for each stylesheet. Where an example only specifies a directory, the directory must exist before running xsltproc and multiple files will be created in that directory, overwriting files with the same name in that directory. i.e. these stylesheets chunk the output.

Where an example specifies a file all results from xsltproc will be written to the one file. The file does not have to exist and will be overwritten if it does exist (unless the stylesheet notes state otherwise). These stylesheets do not chunk the output. If the file is not in the current directory, the specified directory must exist.

XSL stylesheets included with pilot-qof. When XML_CATALOG_FILES is exported correctly:

export XML_CATALOG_FILES="/usr/share/xml/datafreedom/xsl/catalog.xml"

stylesheets can be referenced by the URI in combination with the --nonet option to xsltproc. For clarity, examples only include the filenames of input and output files, not the full path. Where specific data filenames are required for certain external programs (like calcurse and dlume), these are given in the example. Ensure the full paths are specified wherever necessary. Current stylesheets are works in progress, but include:

You are free to copy and modify these stylesheets to your own requirements, including translations and customised formats. Depending on your package manager, this is often best done by copying the installed file to a local directory before modifying it. pilot-qof does not reference these stylesheets directly. If your modifications could be useful to others, please contribute them to pilot-qof via the QOF-devel mailing list or pilot-qof Wiki.