QSF - QOF Serialization Format - lays out a QOF object in a series of XML tags. The format will consist of two component formats:
qof-qsf for the QSF object data and
qsf-map to map sets of QSF objects between QOF applications.
QSF object files will contain user data and are to be exported from QOF applications under user control or they can be hand-edited. QSF maps contain application data and can be created by application developers from application source code. Tools may be created later to generate maps interactively but maps require application support as well as an understanding of QOF objects in the import and output applications and are intended to remain within the scope of application developers rather than users.
A QSF file written by one QOF application will need an appropriate QSF map before the data can be accessed by a different application using QOF. Any QSF objects that are not defined in the map will be ignored. QSF files written and accessed by the same application can use maps if necessary or can simply import the QSF data as a whole.
If you need to convert pilot-qof data into other formats, take a look at the example stylesheets installed with pilot-qof. You are welcome to contribute new or amended stylesheets - just post them on the QOF-devel mailing list.
http://lists.sourceforge.net/lists/listinfo/qof-devel
Depending on your package manager, the XSL stylesheets should be installed in /usr/share/xml/pilot-qof/xsl/, or on Fink /sw/share/xml/pilot-qof/xsl/.
Current stylesheets are works in progress, but include:
pilot-qof-address-vcard1.xsl
This stylesheet converts the output from pilot-qof -d pilot_address into a very brief Vcard, suitable for upload to mobile phones. Tested with a Motorola E1/ROKR using Bluetooth. Ensure that the file uses the .vcf extension to enable the phone to understand the file type. This stylesheet is deceptively simple but surprisingly practical. It allows users to create mobile phone phonebook entries from existing Palm data - there is no point in re-entering existing data. Each VCard is written into a separate .vcf file, named after the contact described in the pilot_address records. Spaces are replaced with underscores. Specify the '-o dir/' option to xsltproc to output all vcards into a directory.
pilot-qof-invoice-xhtml.xsl
This stylesheet is a prototype - it is intended to provide a method to convert
QSF output using the --invoice-city or
--invoice-vendor options into valid HTML. It includes CSS hooks
to customise the output and will accept user-specified parameters to indicate the
mileage rate or hourly rate for the invoice calculations. Each invoice is written into
a separate .html file, named after the contact described in the pilot_address records.
Spaces are replaced with underscores. Specify the '-o dir/' option to xsltproc to
output all invoices into a directory.
Others
Stylesheets for ICS, vcal and possibly LDAP are planned. Any plain text, XML or HTML format can be generated, theoretically. If you have a request for an XSL stylesheet or if you have a stylesheet you would like to make available to others, mention it on the QOF-devel mailing list.
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 SourceForge project site.
http://sourceforge.net/projects/pilot-qof/
Where possible, each stylesheet supports providing translatable strings and user-specific encodings via external parameters. This can make the command line very long so is best performed using a script. Each descriptive word in the output is configured as a string parameter for the stylesheet and can be replaced with a translated version. HTML output supports setting the HTML language (as would be specified in the <html> lang attribute) and the encoding (as would be specified in the <meta> charset value in the content attribute). If you use these stylesheets via a scripting language - like bash, PHP or Perl - you could automate the translation by passing values obtained from a normal gettext PO file. Copy the translatable strings into your script file as normal variables then mark up those variables for translation by gettext. When the script is called, gettext will assign the translated values to the variables and your script can simply echo those values to the calls to the XSL parser routines.
It is important that the HTML language and the encoding match each other AND the expected content of the HTML output generated from the pilot-qof data.
When providing translated strings, the same constraints apply as if you were using gettext and a normal PO file: the context and format of the translation should match the intention expressed in the default value of the parameter. If the default is plural, the translation should be plural. If the default is capitalised, the translation should be capitalised - subject to grammatical rules for that language - even if the parameter name itself is not capitalised.
Each stylesheet specifies the translatable strings in a block near the top of the file, marked as for the attention of translators. Common settings, like the HTML language parameter and the encoding support, are in the pilot-qof-std.xsl stylesheet and are available in all HTML stylesheets by using the string parameters html_lang and encoding.
Convert a QSF XML file containing pilot_address records, into individual VCard .vcf files in the vcards/ directory - which must already exist. Files are named according to either the Company or FirstName_LastName of the pilot_address record.
$ xsltproc -o vcards/ pilot-qof-address-vcard1.xsl addresses.xml
Convert the output from pilot-qof --invoice-city or
--invoice-vendor options into an HTML invoice. The invoice uses
CSS in the invoice.css file.
$ xsltproc -o invoices/ pilot-qof-invoice-xhtml.xsl invoice.xml
This example overrides the default mileage-rate (0.30 currency units per unit distance) and the default hourly-rate (20 currency units per hour) provided by the stylesheet with user specific values.
$ xsltproc --stringparam mileage-rate 0.45 --stringparam hourly-rate 21 -o invoices/ pilot-qof-invoice-xhtml.xsl invoice.xml
The stylesheet currently defaults to Pounds Sterling and - depending on support in your shell - the currency-symbol can also be overridden:
$ xsltproc --stringparam currency-symbol $ -o invoices/ pilot-qof-invoice-xhtml.xsl invoice.xml
If your shell complains about using a currency-symbol on the command line, e.g. when trying to use Euro (€), copy the stylesheet to somewhere below your /home/ directory and edit the currency-symbol in the file. Wikipedia has a reasonably complete list of entity references:
http://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references
Although it is fine to pipe pilot-qof output to other processes like xsltproc, (note the terminal dash - to denote that xsltproc should expect the XML content on stdin) :
$ pilot-qof -x whole_year.xml --invoice-city -t 2006-03-01 | xsltproc pilot-qof-invoice-xhtml.xsl -
Just remember that it might not be so wise to do this:
$ pilot-qof -a --invoice-city -t 2006-03-01 | xsltproc pilot-qof-invoice-xhtml.xsl -
Why? Because using -a means that your Palm data is
not being backed up in this process (because the XML sent to xsltproc by the
pipe is not saved and cannot be recreated from the HTML). Now, of course, you
can sync your Palm twice but reading from the backup file is a lot faster.
In general, the best advice is:
"If the Palm data has changed, use -a to backup to file. If the Palm data has not changed, use -x to read the backup file."
pilot-qof was written
by Neil Williams <linux@codehelp.co.uk>.
This manual page was written by Neil Williams
<linux@codehelp.co.uk>
Please do NOT report bugs in pilot-QOF to pilot-link or GnuCash. Report bugs via the QOF-devel mailing list.
http://lists.sourceforge.net/lists/listinfo/qof-devel
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.