                QOF - Query Object Framework
                ----------------------------

Packagers and maintainers: Please see the HACKING file
for specific advice on building against and packaging QOF.

Please see the NEWS file and the ChangeLog for detailed
information on changes since 0.6.0.

0.6.0 final release - October 2005.
-----------------------------------

The logging subsystem has been overhauled to make it more
generic and easier to use with other applications.

The backends are now loaded using GModule which requires each
backend to use QofBackendProvider and install the .la file
alongside the backend library in the *main* package, not the
-dev or -devel package.

v0.6.0 introduces libqof1 which will remain API compatible
until all the changes below can be folded into libqof2:

	1. All gnucash-specific code to be removed. Most of this
		has been done in v0.6.0
	2. Filename and function name conventions to be made to 
		conform to a single method:
		filenames: qof<module>.c|h
		functions: qof_<module>_<function>_ ...
		e.g. gnc_date.h becomes qofdate.h
		qof_book_mergeInit becomes qof_book_merge_init
		gnc_numeric_zero becomes qof_numeric_zero
		gnc_set_logfile becomes qof_log_setfile.
		gnc-trace.c|h becomes qoflog.c|h
	3. These changes will be made by deprecating old names
		and making old files into placeholders. When libqof2
		is ready for pre-release, all deprecated elements will
		include compiler flags that will highlight the code that
		needs to be changed and placeholder files may be removed
		at this stage. All flags and deprecated code will
		then be removed in the final libqof2 release.
	4. To make this change easier, the qof.h header has been fixed
		in v0.6.0 and is now the only header file required to be
		included to use QOF. Using individual header files in 
		applications linked against QOF is now *deprecated*. All
		code that uses QOF should only use:
		#include <qof.h>
		// or
		#include "qof.h"
		This is the only file guaranteed to maintain access to the
		full QOF API during the entire life of libqof1 and libqof2.
		

0.6.0-pre1 release notes - Sept 05
----------------------------------

QOF v0.6.0 adds a lot of new code, including a new backend, book
merge support, new data types and improved methods for loading
other suitable backends. This pre-release is a test-bed and some
functions may require further work.

New this release:
-----------------
 o QofBook merge support with collision handling.
 o Support for partial books with references to linked objects.
 o XML backend available to all programs using QOF. A generic format
   to describe any object in XML.
 o Methods to convert objects between applications.

Brief Description:
------------------
QOF - Query Object Framework is a library for adding a query engine 
to C applications.  An SQL database is not needed; any collection
of C/C++ objects can act as 'tables' which can be 'joined' using 
an SQL-like programming interface.

Long Description:
-----------------
QOF is an offshoot of the GnuCash engine, consisting of those pieces 
unrelated to accounting.  The Query Engine allows C/C++ applications 
to treat random collections of objects as if they were SQL tables,
and perform table-join type queries across them.  In addition, the 
query engine can be backed by an actual database, so that instances
of local objects can act as a 'cache' to a much larger SQL database.

QOF also includes other utilities from GnuCash:
 o Key-Value Pair trees (KVP aka slots and frames), for providing 
   extensibility by associating arbitrary-format data with an object, 
   using a URL-like identifier.
 o Universally-unique 128-bit ID support, so that an instance of an 
   object can be obtained from its unique identifier, thus simplifying
   associations, cross-network operation, etc.
 o Rational Number Support, providing exact math for working with
   money or prices or other quantities.
 o Miscellaneous date & time utilities.
 o Program tracing infrastructure; handing for tracing/debugging
   complex applications.
 o QofBook merge support with collision handling.
 o Support for partial books with references to linked objects.
 o XML backend available to all programs using QOF. A generic format
   to describe any object in XML.
 o Methods to convert objects between applications.

The system consists of 15 KLOC of C code that has been ported to many
Unixes, including Mac OS X.  Although this code is in production use
in stable versions of GnuCash, the split-off into QOF is recent and
still under some flux in order to flesh it out.  In particular, the
subroutine naming convention is being resolved but is still inconsistent.

Examples:
--------
Example programs showing usage can be found in the "examples" subdirectory
but are becoming obsolete. Instead, generate your own objects:

Generating objects:
------------------
To generate your own QOF objects, including Makefiles and an outline
test application, see http://qof-gen.sourceforge.net/

Other applications:
-------------------
Pilot-QOF implements a QOF application conduit for pilot-link,
supporting Expenses, ToDo, Calendar and Contacts databases. Support
can be extended to FreeCoins and other Palm databases in time.

Documentation:
--------------
The QOF documentation is entirely embedded in the source code. You
can build an html version of the documentation by installing the
'doxygen' package, and then 'cd doc; make doc'.  Skim the doc/README
file for more info.

Linking/Building
----------------
This version of QOF uses the 'pkg' system of managing include files
and libraries.  To compile and link your program against QOF, see the
example in the HACKING file.

------------------------- END OF DOCUMENT -------------------------
