GnuCash, XSL and QSF.
====================

       If you need to convert gnucash QSF data into other formats, take a look at the example
       stylesheets  installed  with  gnucash.  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/gnucash/xsl/, or on Fink /sw/share/xml/gnucash/xsl/.

       Current stylesheets are works in progress, but include:

       · gnucash-gnccustomer-vcard2.xsl 

          This  stylesheet  converts  QSF  export  gnucash  customer  data into a brief Vcard, 
          suitable  for  upload  to  Kaddressbook. 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.

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

       Also included is a perl script: 

       ·  vcard-gnccustomer.pl

          The  script  uses  the Text::vCard::Addressbook  CPAN  module  to parse VCard files, 
          including those from other applications,  into QSF XML that  could  be imported into 
          gnucash and merged into your gnucash customer list. With a  few  tweaks,  this could
          also be configured to create QSF XML suitable for gnucash vendor or employee records.

       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.
       GnuCash  does  not reference these  stylesheets directly. If your modifications could be
       useful to others, please contribute them to  gnucash via the QOF-devel mailing  list  or
       gnucash-devel mailing list. Submitted stylesheets should be licenced under the GNU GPL.


LOCALISATION (l10N) OF STYLESHEET OUTPUT.
========================================

       Later HTML  stylesheets  will  support 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  get-
       text 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, get-
       text  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 gnucash QSF data.

       When  providing translated strings, the same constraints apply as if you were using get-
       text 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  gnucash-std.xsl  stylesheet  and  are
       available in all HTML stylesheets by using the string parameters html_lang and encoding.

       For more information, please ask on the gnucash-devel mailing list, the QOF-devel mailing
       list or see the pilot-qof source: http://pilot-qof.sourceforge.net/

EXAMPLES
========

       Convert a QSF XML file containing gncCustomer records,  into  individual VCard .vcf files
       in  the vcards/ directory - which must already exist. Files are named according to either
       the company or name of the gncAddress record.

        $ xsltproc -o vcards/ gnucash-gnccustomer-vcard2.xsl addresses.xml

       This example is based on an "in-progress" QSF invoice stylesheet for gnucash that is based
       on the existing pilot-qof HTML invoice stylesheet. It 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.  The  example  is here just to
       indicate how --stringparam would be used.

        $  xsltproc  --stringparam  mileage-rate  0.45 --stringparam hourly-rate 21 -o invoices/
       pilot-qof-invoice-xhtml.xsl invoice.xml

