Table of Contents
Limitations of XSL. XSL can only do so much. Converting to file formats of a similar structure and layout is relatively simple and problem-free. Converting to file formats or objects that require multiple calculations or associating data within objects of different types is less reliable. An example is the invoice XSL: It works OK for simple invoices (one client per day, one expense, one mileage claim per invoice) but fails with more complex invoices.
Modules. Data Freedom perl scripts use these Perl modules which might not be installed on your system:
These modules are dependencies of datafreedom-perl.
Currently, the perl scripts are not as complete as the XSL but work is progressing. Feel free to contribute any improvements via the QOF-devel mailing list http://lists.sourceforge.net/lists/listinfo/qof-devel, the wiki or the mantis bug tracker.
datafreedom-perl includes a variety of scripts to summarise or report on various types of supported data, including mileage claims (via gpe-expenses or pilot-qof) and invoices (pilot-qof). These scripts developed from the 'pilot-qof' package but now include support for other packages and formats and will continue to be extended along the lines of http://www.data-freedom.org/ - liberating user data from the application. Therefore, the datafreedom scripts use a 'df' prefix.
The scripts continue to be developed within the pilot-qof CVS until such time as the scripts are sufficiently cohesive to form a new source package. The scripts are part of the datafreedom-perl package in Debian/Ubuntu and are installed in your main system path. Please refer to the manpage for each script for full information.
dfxml-invoice
dfxml-invoice parses a QSF XML file output by pilot-qof
and prepares a simple invoice based on rates specified
in ~/.datafreedom/currency which will be
created for you.
Specify '-' as the filename to parse STDIN.
Example 7.1. Creating plain text invoices with perl
pilot-qof -x data.xml --invoice-city -t 2006-11-09 | dfxml-invoice -
Example 7.2. Creating invoices in a Gnome dialogue box
A more complex example using 'zenity' - a Gnome dialog generator.
$ pilot-qof -x data.xml --invoice-city -t 2006-11-08 | dfxml-invoice - > /tmp/zenity zenity --text-info --title="2006-11-08" --filename=/tmp/zenity --width=500 --height=300
dfxml-invoice, like pilot-qof,
is designed to be used in pipes like this. It is intended to provide support
for your own scripts where details like the date can be set as an option:
Example 7.3. Setting the date of the invoice as an option.
#!/bin/bash
DATE=$1
if [ ! $DATE ]; then
echo "$0: please specify the date of the invoice you want to view."
exit
fi
pilot-qof -x data.xml --invoice-city -t $DATE | dfxml-invoice - | \
zenity --text-info --title="$DATE" --width=500 --height=300
dfxml-mileage
dfxml-mileage parses a QSF XML file output
by pilot-qof and prepares a simple summary of the
mileage claims within the file.
Specify '-' as the filename to parse STDIN.
Example 7.4. Creating plain text mileage summaries
e.g.
pilot-qof -x data.xml -d pilot_expenses -t 2006-11 | dfxml-mileage -
dfvcard-pilotaddress
dfvcard-pilotaddress parses a vCard file and prepares a QSF XML file suitable for pilot-qof or datafreedom-qsfxsl.
Specify '-' as the filename to parse STDIN.
dfical-datebook
dfical-datebook parses an iCal file and prepares a QSF XML file suitable for pilot-qof or datafreedom-qsfxsl.
Specify '-' as the filename to parse STDIN.
dfvtodo-pilotttodo
dfvtodo-pilotttodo parses a vTodo file and prepares a QSF XML file suitable for pilot-qof or datafreedom-qsfxsl.
Specify '-' as the filename to parse STDIN.
dfsqlite-pilottodo
dfsqlite-pilottodo reads a gpe-todo
SQLite database and creates records suitable for pilot-qof
-d pilot_todo. Records can be inserted into a suitable SQLite
database (which can be created for you) or output to stdout as QSF XML.
Pass the filename for the pilot-qof SQLite
database. XML output does not use an export filename.
The gpe-todo input data file is set as
~/.gpe/todo.
Example scripts in /usr/share/doc/. To reduce dependencies, some scripts are provided as examples and are not installed to privileged system folders within your PATH.
zenity-invoice
zenity-invoice is an example script to provide
a simple GUI for invoice generation using dfxml-invoice.
zenity-invoice depends on
pilot-qof and zenity.
zenity-invoice needs a 'workdir: /path/' setting
to be added to ~/.datafreedom/currency. Specify a
path to your main pilot-qof data file - the file must contain records
suitable for pilot-qof --invoice-city,
i.e. records from pilot_address and pilot_datebook. Records from pilot_expenses
are handled, if present. pilot_todo records are omitted.
Currently the script also assumes that your main pilot-qof
data file is called offline.xml - feel free to tweak this.
zenity-invoice is part of
datafreedom-perl and is usually installed at
/usr/share/doc/datafreedom-perl/zenity-invoice.
If you want to create a panel applet to execute the script from
that location, use:
Example 7.5. Example script for GUI panel applets
"bash
/usr/share/doc/datafreedom-perl/zenity-invoice".
If you find this script useful or if you have improvements, please let me know so that I can justify making this into a part of the main package(s). Note that a usable icon will be needed too, 32x32 xpm preferably - any contributions welcome.
gtk-invoice
zenity-invoice is an example script to provide
a simple GUI for invoice generation using dfxml-invoice.
gtk-invoice improves on the zenity implementation using dfxml-invoice by supporting monospaced fonts. This allows table layouts to be clearer by putting the invoice item in the first column instead of the second, creating a more standard invoice format.
gtk-invoice is part of
datafreedom-perl and is usually installed at
/usr/share/doc/datafreedom-perl/gtk-invoice,
usually compressed. If you want to create a panel applet to execute
the script, copy the file to a usable location and uncompress the it with
gunzip, then use:
"bash
/path/gtk-invoice".
If you find this script useful or if you have improvements, please let me know so that I can justify making this into a part of the main package(s). Note that a usable icon will be needed too, 32x32 xpm preferably - any contributions welcome.
Subsequent scripts are planned to include methods to convert standard PIM formats into QSF XML for further processing.
Version 0.2.0 contains two new scripts, dfinvoice-future (summarises pending bookings and estimates the costs to be invoiced) and dfinvoice-month (displays the submitted invoices and can support matching invoices against payments.
Using a configuration file in the user home directory,
/home/user/.datafreedom/invoice.conf, the
script reads the Palm data synchronised using pilot-qof
--invoice-city, combines the data with location
and rate details in the configuration file and outputs a table
summarising the invoices and costs.
Example configuration:
[General]
mileage=0.30
default_rate=24
default_code=0
basefile=/home/user/pilot-qof/offline.xml
category=mybusiness
[Acacia Avenue]
rate=25
code=1234
This configuration sets a mileage rate (expenses charged
for personal transport for business purposes, per unit distance)
and a default hourly rate for the work itself. Other expenses are
read in from the pilot-qof data in the
basefile. If category value
is set, the string is passed to the --category
option of pilot-qof to isolate specific
categories of appointments, expenses and contacts from the rest
of your data. (Only one category is supported per user.)
The term mileage in the configuration file is a keyword (it is not interchangeable with other terms like distance etc.), but the Palm takes care of selecting the distance unit - miles or kilometres - and the scripts will use that value.
For places where the rates differ, location-specific sections can be added - the hourly rate overrides the default rate and the code is meant to be a shorthand for the location itself. e.g. if Head Office etc. puts a code in the invoice payment notice to represent the location or the cost code and similar, to help you identify the appropriate line of content in the notice itself.
The simple table formatting used in the output appears to have a minor issue with UTF-8 - if the currency symbol for your locale uses UTF-8, the rows using the symbol will be shortened by one character per use of the UTF-8 symbol, causing the column markers to be mis-aligned.
Payments can also be handled with a simple list in
~/.datafreedom/paid where each line refers
to one invoice (even if more than one invoice is paid with the
same reference). The list needs a simple format:
date : reference
where 'date' matches the date format used by the
pilot-qof -t option:
e.g. 2009-11-24 for the 24th day of the 11th month in the year
2009.
$ date +%Y-%m-%d
Whatever text occurs after the colon until the end of the line is used as the payment reference.
Only one reference can be supported for any one date.
If no invoice exists for the date for any given reference, that reference is ignored in the output but is still counted.
The design of the script and the structure of the data suits particular types of businesses (specifically mine) and might not suit others so well.
The main objective is to support "consultant" or "service" industries rather than "retail" or "commodity" industries - with a further assumption that work is performed and paid on the basis of single dates with not more than one invoice per day, although one payment can cover more than one date and therefore more than one invoice.