From 6dc174ded734e0b8b4eb08c6d4e20a4456833280 Mon Sep 17 00:00:00 2001
From: Linas Vepstas
-There are currently several different versions of GnuCash. The current
-stable, production release is gnucash-1.2.x and is Motif based. However,
-development has all but switched entirely over to Gnome; the Motif version
-will probably eventually fall to the wayside. (Note that other versions, such as KDE,
-Java or PalmPilot have been discussed and/or started. More about this below).
-The latest Gnome version, and any latest version in general, is currently
-available only via CVS. There are precompiled versions available, but these
-are usually only for the stable releases. Don't use the unstable versions
-unless you are looking for excitement and adventure.
-
-This document is divided into several sections.
-
-
-
-
-The View of the data is a subset or slice of the data described
-by the Model. The View may consist of only the transactions for the
-month of May, or only the account totals for certain accounts. The
-View is used in part to generate the reports and graphs, but it is
-also that which the Controller interacts with.
-
-However, GnuCash also needs to deal with multiple distributed data
-sources: stock quotations from the net or transaction confirmations
-from online banks and brokerage houses, or more mundane sources,
-such as file imports, or merger of data from several users. In this
-language, the concept of a global Model-View is dated, and somewhat
-inappropriate. Rather, one is worried about how data is represented
-in the local address space of the GUI, how the GUI manipulates it,
-how date is brought in and merged from external sources, and how that
-data is again output, whether to a file or a local or remote database.
-Thus, the View is essentially a local data cache: its the data that
-is immediately present and being displayed, reported, and manipulated.
-The Model is the abstraction of that data that the GUI (the controller)
-can act on.
-
-
-In particular, it should be possible to back the Engine onto an
-SQL database, and thereby enable multiple users and/or interface
-to more complex accounting systems. The engine should also be
-expandable to handle other sources of data, such as OFX,
-Integrion GOLD, the Open Trading Protocol, the OMG CORBA
-General Ledger submission, the IBM San Francisco business objects,
-or closer to home, Linux Kontor. In particular, it should
-be possible to use GnuCash not only to view data from these sources,
-but also to manipulate it and send it back.
-
-
-
-A personal finance system needs to be easy to use, have a simple
-'intuitive', yet powerful, menu system, and provide graphs, charts,
-net-worth reports, mortgage calculators, budget planners, and
-and interfaces to on-line banking, shopping and stock systems.
-
-A business system needs to run over the network, allowing multiple
-simultaneous users. It needs support for payroll, inventory control,
-shipping & receiving, billing, accounts payable & receivable.
-Pie-in-the-sky might include interfaces to on-line shopping carts,
-credit-card clearing interfaces, interfaces into ERP systems.
-
- Current status:
-
-
-
-
- Other output format possibilities include SGML and XML. In the
- long run, these are preferable to HTML, since DSSSL and
- Jade (James DSSSL Engine
- can be used to convert to RTF, Postscript, etc. XML is the wave
- of the future.
-
- The Report Generator should be a "dockable" subsystem of the
- whole. Thus, it should be possible to run the report generator
- in a stand-alone, read-only fashion without having to start up the main
- application.
-
- Graphs, charts, etc. too ...
- Asset allocation pie chart.
- Graph portfolio value vs. cost
-
- One hard part of reporting is designing a configurable interface,
- so that people can build custom reports.
-
- Stock portfolio tools should include a cost-averaging report.
- Market Index report. Stock Option values. Estimate capital gains taxes.
-
- Status:
-
-
-
-
- Question: how to most simply allow the user to enter loads and fees?
- Answer: through splits. However, some users may not understand splits,
- at least not initially. Thus, a little popup that allows the user to
- type in the sales load or fee, & etc, and then auto-creates the needed
- splits.
-
- Note the current transfer window does NOT allow a share price to
- be specified !! Needs fixin ...
-
-
-
-
-
-
-
-
-
-
-
-
-
- Current status:
+ The people behind GnuCash aim
+ to create a world-class GPL'ed Open Source Personal Financial
+ Application for GNU/Linux and other Unix's. This page aims to
+ review some of the technical and development issues surrounding
+ this product, representing a sort of FAQ for developers and
+ contributors, to suggest directions when developers are trying to
+ determine how to implement new functionality. To get a better idea of what
+ GnuCash is and what it does, visit its home page. There are currently several different versions of
+ GnuCash.
-
-
-
-
- The overall architecture is envisioned to be as so:
- All code, including the transaction engine, the file I/O routines,
- the menus, and the ledger, will be abstracted into
- compact modules that can function independently of each other.
- At the highest level, there will be a infrastructure with
- extension language interfaces that will "wire together" the
- various modules.
-
- Such "wiring together" will consist of a dispatch infrastructure
- that will allow arbitrary menu entries to be hooked to arbitrary
- modules. The configuration for menu entries, and their associated
- callbacks, will be specified in an ext-lang configuration file.
- At the final stages, it is hoped that new modules can be imported
- without requiring that the application itself be recompiled & relinked.
-
- Status:
+
+ The latest Gnome version, and latest versions in general,
+ are currently available only via CVS. Precompiled versions are available, but usually
+ only for the stable releases. Don't use the unstable versions
+ unless you are ready for excitement and adventure, and are
+ prepared to cope with a need to keep extensive backups. This document is divided into several sections. Thus, the Motif or Gnome GUIs are merely two possible
+ manipulators of the data; others, based on e.g.
+ Qt/KDE, emacs, Java applets or Java servlets ought to be
+ possible.
-
-
-
-
-
-
-
-
-
-
-
-
- Status:
+
+ GnuCash also needs to deal with multiple distributed data
+ sources: stock quotations from the net or transaction
+ confirmations from online banks and brokerage houses, or from
+ more mundane sources, such as file imports, or merger of data
+ from several users. Amongst these terms, the concept of a global Model-View is
+ dated, and somewhat inappropriate. Rather, we need to be
+ concerned about how data is represented in the local address
+ space of the GUI, how the GUI manipulates it, how data is
+ brought in and merged from external sources, and how that data
+ is again output, whether to a file or a local or remote
+ database. Thus, the View essentially represents a local data
+ cache of the data that is immediately present and being
+ displayed, reported, and manipulated. The Model is the
+ abstraction of that data that the GUI (the controller) can act
+ on. Currently, the Engine is fairly poor, and is tightly tied
+ to the data structures that the GUI manipulates. These data
+ structures include:
-
-
-
- Design/implementation for this is tricky. It should probably leverage
- crontab, but this can lead to difficulties & bugs.
- May need interfaces to email for emailed alerts. Interfaces into
- calendaring systems?
- Current status:
+ The Engine has a very simple apply/commit model, and a simple
+ query mechanism for generating reports and views.
+
+ The Engine currently handles only a small set of data
+ sources:
-
- However, since the Engine is meant to be the interface
+ between the GUI and the financial data, it is really intended
+ to be able to do much more. In particular, it should be possible to back the Engine
+ onto an SQL database, and thereby enable multiple users and/or
+ interface to more complex accounting systems. The engine should
+ also be expandable to handle other sources of data, such as
+ OFX, Integrion GOLD, the Open Trading Protocol, the OMG CORBA
+ General Ledger submission, the IBM San Francisco business
+ objects, or closer to home, Linux Kontor. In particular, it
+ should be possible to use GnuCash not only to view data from
+ these sources, but also to manipulate it and send it back. The above structure should leads us to view GnuCash not so
+ much as a tightly integrated application, but rather as a loose
+ confederation of component objects, libraries and
+ interfaces. In order to facilitate the gluing together of these parts,
+ as well as simplify the questions of customizability, change
+ and rapid development, GnuCash makes use of an extension
+ language to glue the pieces together. The extension language that is most central to Gnucash is
+
+ Scheme, and in particular, the FSF implementation, Guile,
+ although some of the interfaces are also available through Perl.
- Note that the above 'step-by-step' budgeters will have a very
- very different GUI than what e.g. a small-business budget might
- look like.
-
-
- Status:
+ They may use some of the same financial terminology, and
+ hopefully might share a fair bit of code, but have quite
+ different goals and requirements.
+
+ Important properties of a personal finance system
+ include:
-
-
-
-
-
-
- Status:
+
+
-
-
-
- There are two ways to build an OFX parser. One way is to build
- a compile-time DTD parser that treats the DTD as if it were an IDL,
- and generates C language stubs for a parser. This approach was
- attempted and abandoned because it leads to fragile C code and
- a very large binary. Its fragile because minor DTD non-compliances
- are hard to parse, handle and recover from. Its huge because the
- DTD results in hundreds of (C++) objects being generated.
- The other way is to perform run-time DTD parsing. This is nice
- because this is the more popular approach: there are a variety of
- XML tools available that provide this function. Its slower, but
- on the OFX client side, this is not a bottleneck.
-
- Status:
+
+ A seemingly contradictory factor is that the kinds of
+ sophistication that are required vary considerably.
+ Consider: Thus, home users don't need much of the
+ sophistication of an Accounts Receivable or Payable system,
+ or the bizarre depreciation policies that crop up
+ in Asset Management systems.
-
-
-
-
-
-
- Current status:
+
+ It may be that these will require completely
+ different systems, and that GnuCash cannot be "all things to
+ all people." This remains to be seen. The right hand column shows a sizing guesstimate. pm ==
+ person-months
-
-
- Current status: Other output format possibilities include SGML and Extensible
+ Markup Language - XML. In the long run, these are
+ preferable to HTML, since DSSSL tools such as Jade (James DSSSL
+ Engine) can be used to convert to RTF, Postscript,
+ etc. Add to this the consideration that XML is the basis for
+ the Document Object
+ Model, which is being integrated into many web-based
+ applications, and we can see that XML is an increasingly
+ significant format as we look to the future. The Report Generator should be a separate but
+ "dockable" subsystem of the whole. Thus, it should be possible to run the report generator
+ in a stand-alone, read-only fashion without having to start
+ up the main application. Graphs, charts, etc. too ... Asset allocation pie chart. Graph portfolio value vs. cost One difficult aspect of reporting is designing a
+ configurable interface, so that people can build custom
+ reports. The New
+ Reporting Infrastructure is seeking to build this up
+ using Guile. Stock portfolio tools should include a Cost Averaging
+ report, Market Index report, Stock Option values,
+ Estimation of capital gains tax liabilities. Status: Question: How to most simply allow the user to
+ enter loads and fees? Answer: Through splits. Unfortunately, some
+ users may not properly understand splits, at least not
+ initially. Thus, a little popup is needed to allow the user
+ to type in the sales load or fee and such, and then
+ auto-create the needed splits. Note the current transfer window does NOT
+ allow a share price to be specified !! Needs fixing ... A set of themes would be desirable for the Gnome
+ version. A user-configurable button-bar would be nice
+ too. Provide a default list of "Categories"
+ (Income/Expense Accounts). These are categories such as
+ "Automobile Expense", "Bank Interest Income", and
+ "Employment Income". The user should be able to select
+ a default set of accounts, and have those created
+ automatically. To actually implement this, it might be best to
+ simply create a file with these in them, and load that
+ file. A mechanism should be provided to allow the user
+ to weed out undesired accounts whilst not preventing
+ them from using them at a later date, if desired. Add an example showing how regular household assets
+ (house, car, jewelry, etc.) should be treated. In
+ particular, show how appreciation and depreciation
+ should be treated. Menu navigation using the keyboard should be
+ possible. Although menu mnemonics exist, they seem to be
+ broken. Similarly, tab-key navigation should be possible.
+ Currently, it is possible to use the tab key to
+ navigate from field to field in the register window, to
+ user arrow keys to navigate menus, and quick-fill to
+ automatically complete fields. However, it is not
+ possible to tab over to the "Commit" button. It should be. Currently, Income/Expense accounts can be shown or
+ hidden by selecting from a menu. It would be nice to be
+ able to examine different account types (Asset,
+ Liability, Income, Expense, Payables, Receivables,
+ Inventory) by selecting a tab folder. When the user pauses the mouse over a button,
+ "fly-over" pop-up help windows should appear. Create grayed out entries in the ledger, titled
+ "Memo", "Description", etc, helping users understand
+ what should be typed into each field. Make sure that text fields can handle the vi and
+ emacs key bindings, so that e.g. emacs-style
+ ctrl-a, ctrl-k does the right thing. i.e. Ability to permanently lock records as
+ non-editable. This should be straight-forward by using the
+ reconciled field to indicate a locked
+ value, and not allowing the GUI to edit locked records. Also need to report closed books slightly differently.
+ Need to bring balances forward too... Preferences include things like showing/not showing
+ categories, forcing double-entry, etc. Current status: The overall architecture is envisioned thus: All code, including the transaction engine, the file
+ I/O routines, the menus, and the ledger, will be abstracted
+ into compact modules that can function independently of
+ each other. At the highest level, there will be a
+ infrastructure with extension language interfaces that will
+ "wire together" the various modules. Such "wiring together" will consist of a dispatch
+ infrastructure that will allow arbitrary menu entries to be
+ hooked to arbitrary modules. The configuration for menu
+ entries, and their associated callbacks, will be specified
+ in an extension-language configuration file. At the final
+ stages, it is highly desirable to be able to, in
+ some manner, import new modules without requiring
+ that the application itself be recompiled and relinked. Status: This should be handled by having a way of bouncing out
+ to some Guile code to generate transactions with computed
+ values. Status: Add support for automatic, recurring transactions,
+ e.g. mortgage payments, fixed-interest bonds, bank
+ accounts, etc. Note that the design for this could be very different,
+ depending on whether the multi-user functions are available
+ or not. Design/implementation for this is tricky. It should
+ probably leverage crontab, but this can lead to
+ difficulties and bugs. May need interfaces to email for emailed alerts. Interfaces into calendaring systems? Current
+ status: Note that the above 'step-by-step' budgeters will have
+ a very very different GUI than what the budgeting system
+ required for a small-business might look like. Status: Status: Right now, this is a stand-alone perl script run
+ from crontab. OFX is an open spec from Microsoft, Intuit, and
+ Checkfree, and which will be supported by Integrion. The
+ OFX DTD's are included in the 1.1 distributions. See OFX Home Page for
+ details. There are two ways to build an OFX parser. One way is
+ to build a compile-time DTD parser that treats the DTD as
+ if it were an IDL, and generates C language stubs for a
+ parser. This approach was attempted and abandoned because it
+ leads to fragile C code and a very large binary. Run-time parsing may be slower, but on the OFX client
+ side, this should not be a bottleneck. Status: Note that the organizations developing OFX are looking
+ to use XML as their "formats of the future;" this may
+ encourage the use of one of the many XML parsers available
+ for UNIX. Double-entry is a powerful way of ensuring the
+ integrity of of the financial data. Currently, while
+ double-entry is supported, its use is not enforced: the
+ user can create dangling transactions, where only
+ one account is indicated. Although this is acceptable for home use (even
+ desirable, since it allows the casual user the simplicity
+ they desire), it is not acceptable for business use. It must be possible to enable forced-double entry, so
+ that a transaction cannot be completed until two accounts
+ have been specified. Current status: The tab-delimited format should be compatible with that
+ of /rdb, aka RAND/Hobbs /rdb or
+
+ NoSQL. (NoSQL is available as part of the Debian GNU/Linux distribution,
+ for instance.) The /rdb format is thus:
-
-
-
-
-
-
-
-
-
-
-
-
- The current engine is rather simple: it provides support for
- accounts, account hierarchies and transactions consisting of
- multiple entries. Many of the features described elsewhere
- need the engine to have a far richer, more sophisticated data
- model: parties (names, addresses), transaction id's & part numbers,
- budgets, interest rates, A/R, A/P, etc.
-
- Note: it makes no sense to make the engine API richer than what
- the GUI can currently support.
-
- Current Status:
- It is a very simple, very basic flat table format. The
+ use of /rdb with GnuCash should try to match with
+ SQL schemas as much as possible in order to minimize I/O
+ complexity and incompatibility. categorize items according to different tax
+ schedules The current engine is rather simple: it provides
+ support for accounts, account hierarchies and transactions
+ consisting of multiple entries. Many of the features described elsewhere will require
+ that the engine have a far richer, more sophisticated data
+ model, including such things as: Note: it makes no sense at this point to make the
+ engine API much richer than what the GUI can currently
+ support. In a business environment, the auditors may have
+ "signed off" on the validity of the data; at that
+ point, the ability to modify audited data should be
+ very tightly controlled, or even downright
+ forbidden. Current Status: These "Transaction processing constructs" should
+ simplify creation of an SQL back end, or some other
+ more sophisticated database engine. There has been much discussion about this on
+ mailing lists both for GnuCash and CBB. Major
+ points have included: This may be a minor cost to a business enterprise
+ that hires DataBase Administrators. It is not acceptable to require this of
+ naive users that may find "simple" things like Changing GnuCash to be suited to use a DBMS in
+ other than a "load-it-all" / "dump-it-all" manner, but
+ to rather update the database in a transactional
+ manner. That being said, it may be possible to recast the
+ GnuCash engine functionality so as to handle
+ storage in a transactional manner. The following industrial-strength features are
+ needed: While the GnuCash "engine" might remain free,
+ maintenance of payroll functionality would require
+ "subscribing" to an update scheme; it might be troublesome
+ to try to provide such a "subscription" free of charge.
-
-
-
-
-
-
- The following industrial-strength features are needed:
-
Mostly aimed at mainframes, middleware, high
+ transaction volumes and data integrity.
-
-
-
-
-
-
-
-
-GnuCash Project Goals
-
-The people behind GnuCash
-aim to create a world-class GPL'ed Open Source Personal Financial
-Application for GNU/Linux and other Unix's. This page aims to review
-some of the technical and development issues surrounding this product,
-to be a kind of 'FAQ' for developers and contributors.
-To get a better idea of what GnuCash
-is and what it does, visit it's home page.
-
-
-
-Architectural Goals
-There are some over-reaching design principles and philosophies that
-we hope to maintain. Some of these concepts and terms are introduced
-in this section.
-Separation of GUI and Data
-First, one must maintain a clean separation between the data structures
-and the GUI that manipulates them, along the lines of a
-Model-View-Controller
-paradigm. Lists of accounts and the transactions in
-them can be thought of as a representation of financial data,
-a Model. The GUI that adds, modifies and deletes these should
-be thought of as a manipulator of the data, a Controller.
-The Motif or Gnome GUI's are just two
-possible manipulators of the data; others, based on e.g. Qt/KDE,
-emacs, Java applets or Java servlets should be possible.
-The Financial Engine
-In GnuCash, the Model is implemented via the Engine API, and
-the View is the data that is currently in the Engine. Thus,
-the Engine is a set of programming API's that the GUI (or a script,
-or even a clever command-line-addict) can use to manipulate the data.
-Currently, the Engine is fairly poor, and matches the data types and
-formats that the GUI can manipulate. These include transactions,
-transaction entries (splits), accounts and account hierarchies.
-The Engine has a very simple apply/commit model, and a simple
-query mechanism for generating reports and views.
-The Engine currently handles only a small set of data sources:
-it can import and merge in QIF's, it can read and write its own
-binary byte stream, and can get stock quotes from the net.
-However, since the Engine is meant to be the interface between
-the GUI and the financial data, it is meant to be able to do much more.
-Modularity, Extensibility and Customization
-The above structure then leads one to view GnuCash not so much as
-a tightly integrated application, but a loose federation of parts
-objects, libraries and interfaces. In order to facilitate the
-gluing together of these parts, as well as simplify the questions
-of customizability, change and rapid development, GnuCash makes use
-of an extension language to glue the pieces together. The extension
-language that is most central to Gnucash is Scheme, although some
-of the interfaces are also available through Perl.
-Markets and Users
-Implicit in this desire for extensibility is the need to build
-two different types of financial applications: one for the home
-user, and one for the small business. These two types of systems
-use much of the same financial lingo, and can share a lot of code,
-but in fact are quite different.
-
-
-
-
- Feature
- Sizing
-
-
- Internationalization Small
- Graphs, Reports Medium
- Simplified Stock Ledger Small
- Themes, Icons, Glitz Medium
- Books, Accounting Periods Small
- Check Printing Small
- User Preferences Medium
- Extension Language Support Medium
- Bonds & Interest Bearing Instruments Small
- 401K etc. Small
- Annotate with Investment News Small
- Loan and Mortgage Calculators Small
- Budgeting Medium
- Alerts, Recurring Transactions Medium
- Quicken(TM) Export Small
- Stock Quotes, Price Quotes Small
- OFX, Online Banking, Trading, Billpay Large
- Multiple Currencies Medium
- Double Entry Accounting Small
- Tab-delimited ASCII export Small
- Tax Preparation Large
- Sync with Palm Pilot &c. organizers Medium
- Emergency Records Organizer Small
- Small Business Features
-Features that small/medium businesses expect.
-
-
-
-
-
-
-
-
-
-
-
-
- Feature
- Sizing
-
-
- Enhanced Engine, Financial Objects Large
- SQL I/O Medium
- Multi-User Support Medium
- A/R, A/P Accounts Payable, Receivable Medium
- Payroll Medium
- Invoicing Medium
- Job Costing Medium
- Expense Accounts Large
- Features and Functions
-
-
-
-
-
-
-
-
-
-
- GnuCash Project Goals
+
+
-
-
+
+
+
+
+
+
+
+ Architectural Goals
+ There are some over-reaching design principles
+ and philosophies that we intend to maintain. Some of these
+ concepts and terms are introduced in this section.
+
+ Separation of GUI and Data
+ First, we must maintain a clean separation between the data
+ structures and the GUI that manipulates them, along the lines
+ of the Model-View-Controller paradigm.
+
-
- The Financial Engine
+ In GnuCash, the Model is implemented via the Engine API,
+ and the View is the data that is currently in the
+ Engine. Thus, the Engine is a set of programming API's that
+ the GUI (or a script, or even a clever command-line-addict) can
+ use to manipulate the data.
+
+
-
-
-
- Modularity, Extensibility and Customization
+
+ Markets and Users
+ Implicit in this desire for extensibility is the need to build
+ financial applications supporting two major classes of users:
+
-
- Create a summary budget/track-record budget report that a
- professional financial planner/advisor could use.
- Personal Finance Needs
+
+
-
- Small Business Needs
+
-
-
+
+ Reconciling Those Needs
+
+
-
-
+
+ Feature Requirements
+
+
+ Personal Financial Application
+ Below are listed the technical work items needed to implement
+ the features that home users might hope to have. They are
+ listed in approximate order of priority.
+
+
-
- Small Business Features
+ Features that small/medium businesses expect.
+
+
+
+
+
+
+
+ Feature
+
+ Sizing
+
+
+
+
+
+
+
+
+ Enhanced Engine, Financial
+ Objects
+
+ Large
+
+
+
+ SQL I/O
+
+ Medium
+
+
+
+ Multi-User Support
+
+ Medium
+
+
+
+ A/R, A/P Accounts Payable,
+ Receivable
+
+ Medium
+
+
+
+ Payroll
+
+ Medium
+
+
+
+ Invoicing
+
+ Medium
+
+
+
+ Job Costing
+
+ Medium
+
+
+ Expense Accounts
+
+ Large
+ Features and Functions
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Create a summary budget/track-record budget report that a
+ professional financial planner/advisor could use.
+
+
+
+
+
+
+
+
+
+
+
+ The other method would be to perform run-time DTD parsing.
+ This is attractive particularly because it is a more
+ commonly-used approach; there are a variety of XML tools
+ available that provide this function.
+
+
+
+
+
+
+
+
+
- field-name tab fieldname tab fieldname \n
- ------------------------------------------ \n
- value tab value tab value \n
- value tab value tab value \n
- etc ...
+field-name tab fieldname tab fieldname \n
+------------------------------------------ \n
+value tab value tab value \n
+value tab value tab value \n
+etc ...
- Its a very simple, very basic flat table format. It should match
- the SQL schemas in order to minimize I/O complexity and incompatibility.
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+% su -
+Password:
+# cd /tmp
+# rpm -i gnucash-4.1.3.i386.rpm
+# exit
+
+ to be challenging.
+
+
+
+
+
+ References
-
-
-
-
-
-
Linas Vepstas
+ linas@linas.org
+
Christopher Browne
+ cbbrowne@ntlug.org
+