Difference between revisions of "Project and Design Documentation"

From GnuCash
Jump to: navigation, search
(→‎Features and Functions)
(→‎Features and Functions)
Line 859: Line 859:
 
</p>
 
</p>
  
 +
<dt><b>User Preferences, Session Management</b></dt>
 +
<dd>
 +
A dialog system and file format for manipulating user preferences. Preferences include things like default currency, register layout and colors, etc.
 +
 +
        <p>What are some of the competitive preference-handling
 +
        technologies? Lets get some URL's here ... Following the
 +
        Unix tradition, there is no global preferences registry.
 +
        Note that session management and preferences are related
 +
        things ... sort-of. Right now, we don't treat them as such
 +
        ...</p>
 +
 +
        <p><b>Status:</b></p>
 +
Done, more or less, version 1.6.0.
 +
 +
        <ul>
 +
          <li>Works real good; lots of preferences in the GUI.
 +
              Implemented in home-grown scheme. (version 1.4.0,
 +
      rlb)</li>
 +
 +
          <li>These are saved in the '.gnucash/config.auto' file.
 +
              The current file format is raw scheme code, rather
 +
              delicate to tweak by hand ...</li>
 +
 
 +
          <li>Session management mostly works, but doesn't use the
 +
      sawmill/gnome/X ICCCM system.  GnuCash remembers MDI
 +
      based reports, restart reopens in same state. Sizes
 +
      and shapes and positions are remembered.
 +
      Done in version 1.6.0
 +
              </li>
 +
 +
          <li>Independently of session management, the register
 +
              windows should remember how big they were last time they
 +
              were popped up, and they should pop up the same size, again.
 +
              The app should remember these sizes from invocation to
 +
              invocation. Done in version 1.6.0, but seems a bit buggy.
 +
      </li>
 +
 +
        </ul>
 +
        <br>
 +
        <br>
 +
      </dd>
 +
 +
<dt><b>Architecture Review</b></dt>
 +
<dd>
 +
The application is wired together partly with C, partly with Scheme. The architecture of the wiring and how scheme is fit in needs to be reviewed, with a general overview created so that additional extensions may be added in a straightforward manner.
 +
 +
        <p>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.</p>
 +
 +
        <p>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 <em>highly</em> desirable to be able to, in
 +
        some manner, import new modules <em>without</em> requiring
 +
        that the application itself be recompiled and relinked.</p>
 +
 +
        <p><b>Status:</b></p>
 +
 +
        <ul>
 +
          <li>
 +
            Scheme/Guile is the central extension language.  Guile
 +
            interfaces auto-generated using g-wrap.
 +
          </li>
 +
          <li>
 +
            Optional interfaces to the data engine (for, e.g.
 +
            perl) can be generated using SWIG.
 +
          </li>
 +
          <li>
 +
            Dave to collate & edit architecture documents.
 +
            RLB to provide diagrams.
 +
          </li>
 +
        </ul>
 +
        <br>
 +
        <br>
 +
      </dd>
 
</dl>
 
</dl>
  

Revision as of 09:31, 20 September 2014

General

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 documents the technical issues and development directives surrounding this project. It is a kind of an FAQ for developers and contributors, providing status, and guidance.

If you simply want to get a better idea of what GnuCash is and what it does, visit its GnuCash home page or browse the GnuCash Wiki page. The home page contains screen shots, news items, and mailing list archives.

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.

Model 
Lists of accounts and the transactions in them can be thought of as a representation of financial data, a Model.
Controller 
The GUI that adds, modifies and deletes these should be thought of as a manipulator of the data, a Controller. Thus, the Motif or Gnome GUI's are merely two possible manipulators of the data; others, based on e.g. web/cgi-bin, Qt/KDE, emacs, Java applets or Java servlets ought to be possible.
View 
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. Views are generated by queries to the data store.

GnuCash also needs to deal with multiple distributed datasources: 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.

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 provides basic accounting structures. These include:

Transactions 
consist of a set of splits or journal entries (JE's) whose values sum to zero. The transaction includes several date fields, a description, and a common-currency field, and a universal unique id (uuid/guid). It also provides hooks to store arbitrary data associated with the transaction (using a URL-based key-value tree).
Split 
(or journal entry) is an amount in the account on which it is drawn. Splits also store reconcile status, dates, a memo field, and also a key-value based hook for arbitrary data.
Accounts 
include a name, a type, a description field, and the type of commodity they store. In principle, the account consists of a list of splits.
Chart of Accounts 
is a hierarchical tree of accounts.

The Engine has a basic two-phase commit model, and a query mechanism for finding the data needed for reports and views. The goal of the two-phase commit and query model is allow the creation of multi-user server based backends, such as an SQL backend, and RPC client-server backend, or an XML-based HTTP/web backend. This design seems to work for the above-named backends.

The Engine currently handles only a basic set of data sources:

  • It can import and merge in QIF's (actually, this function has been moved into the GUI, and is no longer part of the engine)
  • It can read and write its own XML byte stream; This ability has been used to provide a multi-user client-server demo (which is currently broken).
  • It can use a Postgress SQL database as a datastore, thereby enabling multi-user and auditing functions.
  • It can talk, via RPC, to a gnucash server. (This code is 'alpha' and incomplete/broken).
  • It can get stock quotes from the net (actually, this function is provided by a separate module, the Finance::Quote perl module.)

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 create a peer-to-peer network model, where gnucash peers can synchronize data between themselves. The engine should also be expandable to handle other sources of data, such as OFX/IFX, the Open Trading Protocol, or the OMG CORBA General Ledger submission. 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.

Modularity, Extensibility and Customization

The above structure should lead us to view GnuCash not so much as a tightly integrated application, but rather as a loose confederation of component objects, libraries and interfaces. This has a number of advantages for both the developer and the user. For the developer, it allows parts to evolve semi-independently of one-another, and to be used in other, non-gnucash projects. For the user, a good extensibility allows the use of #arrangements": a way of broadly customizing the appearence and behaviour of gnucash, and then allowing users to very easily share these customizations with one another. Such arrangements might be collections of canned reports, e.g. for business or home user. Or they might be the menu contents: one menu arrangement is for beginners, another for 'power users', a third for business owners. The goal is that broad areas should be not only customizable, but it should be possible, even easy, to trade these customizations between users.

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 the Scheme extension language (as implemented in the FSF Guile interpreter), to glue the pieces together. (Note that the engine interface is also available with Perl interfaces, thanks to a SWIG wrapper.

A Web Browser for Financial Data

More and more finacial data is moving onto the web. People shop on-line. They pay bills on-line. There are even some promising e-wallet systems (such as WebFunds). For GnuCash to be relevent in this on-line world, it must be able to interact with these systems. There are several steps that can be taken along this path. First, it must be possible to simply and transparently import financial data off the web. Click on a QIF file, mime-type application/x-qif? Gnucash sucks it in without burping. But, in a more distant future, can GnuCash originate transactions? It should be able to!

GnuCash can be and should be "The Sophisticated Financial Web Browser". All GnuCash reports and the help system are HTML-based. In fact, GnuCash has a built-in web browser that can view ordinary web sites. Interactive gnucash components such as the bar and pie charts, or the graphs and reports, can all be served up by a remote web server, as well as locally through the GnuCash application. This allows GnuCash to blur the line between web browser and financial application, and offer the best of both worlds.

Why is this a good thing? One can always have a pure web-based accounting solution (such as SQL-Ledger) that uses ordinary web browsers to view the financial data. But there are problems: dynamically-generated html and cgi-bins aren't as pretty or easy to use, or as fast, responsive or sophisticated, as what you can do with a custom client. That is, GnuCash can be more interactive, easier to user, slicker and more professional looking in style and presentation than a plain-old dynamic website. Financial ASP's simply cannot currently offer the kind of utility, flexibility, responsiveness and integration that GnuCash can offer.

In theory, the 'Java revolution' was supposed to provide this function, with downloadable Java applets providing the 'fancier- than-plain-html' interface. But a Java applet that is this sophisticated would also be large and slow to download: it offers no inherent advantages over native code. Another problem with Java is the inherent propreitary fragmentation: no two Java applets are alike: every site has thier own; there is no standardization.

In order to solve the 'no gui standardization between websites' problem, there are a number of businesses that have arisen to provide "financial aggregation". You sign up with these sites, and let them get all of your credit-card, bank and investment info, and they can provide a unified interface for your bank statements, with graphs and reports (all for a monthly fee). The existance of these services highlights a problem: the inability to aggregate the same data on the users desktop, in a simple, coherent fashion. Let us posit that GnuCash, with the right on-line interfaces, would be a natural for this. For the paranoid, this has the added advantage that no one business has access to all of your financial records.

To put it another way, GnuCash can provide a centralized, trusted store for financial data that no other application can provide. The convenience factor: if you have trading accounts at e*trade and charles schwab, then GnuCash can be the central place where you can oversee all of your investments. The trust factor: maybe you can trust your web bank. Maybe you can trust your web stock account. But can you trust a single web entity with *all* of your financial data? Someone who won't treat you as 'just another consumer' and sell your 'consumer profile' to anyone who cares to stalk (ahem, target) your financial activity (ahem, purchasing) patterns? Didn't think so. Of course, you

  • could* use some proprietary financial software. Assuming, of course, that you trust it not to have any built-in covert channels:

nothing that might send back the make and model of your CPU and the last ten transactions 'home to mommy' for 'diagnostic purposes'. Because open source software, such as GnuCash, can be audited it can be trusted in ways that no proprietary software can be. In an increasingly net-connected world, the ability to build trust through audits will be increasingly important.

Looking Into the Future

Things like support for OFX, and small-business features are hopefully in the near term future of gnucash. Lets take a look at some more far-out possibilities.

E-Wallet 
An e-wallet, just like a real wallet, stores cash. You can use that cash to pay freinds or businesses. Just like a real wallet, an e-wallet should not charge you monthly fees. It should provide you with some measure of anonymity and privacy. An e-wallet should also do something no ordinary wallet can do: show you a monthly report of expenditures. GnuCash should get e-wallet features.
Authentication, Authorization and Access Control 
How does an on-line merchant know that you are who you say you are? How can you use GnuCash to authorize a bill payment? Sooner or later, smart-cards will provide the sort of authentication and access control that is only groped for with PGP/GPG, keyrings, x.509 certificates, and Microsoft Passport/Hailstorm. Of all the electronic things in the electronic world where access control and authentication are important, real money is the most so.
Bill Presentment, Bill Pay 
These magic keywords just mean that a merchant wants to send you a bill, and wants you to go to thier website to pay that bill (they want your eyeballs). Of course, for the user, it would be more convenient to have the bill show up on the desktop, inside of gnucash, and get authenticated and paid out from the desktop (by gnucash), as you would do with all of your other bills.

Requirements

Lets take a look at who the current and potential future users of GnuCash are, and how they might use it.

The classes:

  • Basic Household Accounting/Budgeting
  • Personal Stock Portfolio Management
  • Personal On-line Trading (Day-Trading)
  • On-line shopping and bill-pay
  • Small Business Users

These different applications may use some of the same financial terminology, and hopefully might share a fair bit of code, but have quite different goals and requirements.

Basic Household Accounting and Budgeting 

Important properties of a personal finance system include:

  • Approachable and usable by occasional users who are not knowledgeable about accounting.
  • Ease of use and simplicity is critical.
  • A reasonable selection of reports, graphs, charts, and tools for personal finance, such as mortgage calculations.
  • Budgeting support needs to be targeted at native users.
  • Interfaces to on-line banking, shopping, stock systems. Bank and credit-card statements should arrive 'automatically' and always be up-to-date.
Personal Portfolio Management 
  • Support for management of stock portfolios that may involve considerable sophistication, since individuals commonly have retirement plans that hold mutual funds, stocks, options, bonds, and the like.
  • Reporting infrastructure needs to simplify handling of tax issues (long-term vs. short-term capital gains/losses, cost-basis FIFO accounting, simplfied cost-basis spinoff/merger handling). Need on-line updates of prices, simple portfolio overview, ability to link to websites for additional research.
  • Integration with on-line trading systems. This could save time typing.
  • Basic Audit features. There's a problem with blindly allowing on-line data (prices, transactions) to enter GnuCash. It may not be clear where it came from, and even if the source is beleived to be 'reputable', there still may be factual errors in the data. Thus, there must be a way of audting newly-arrived (or even old) on-line data, and mark it as 'reconciled', i.e. manually reviewed and checked for accuracy. That is, incoming on-line data must be auditable, and audit trails should mark the history of on-line data import.
Small Business Needs 
  • With a business system, it is likely that there will be users who use it eight hours a day, which puts the emphasis on efficiency of user interface rather than on its approachability to naive users.
  • Business systems require network support, and the ability to support multiple simultaneous users.
  • Some business users may want access to the system from an MS Windows 95/98/NT box. For these folks, a web-based interface could be just handy. Web interfaces are also nice a for ASP type deployment.
  • Small businesses do not often have sophisticated investment portfolios; they instead need support for additional sophistication in such areas as:
    • Customer and Vendor Lists; Invoicing
    • Payroll (Batch processed and individual)
    • Inventory Control & Asset Management
    • Amortization Schedules, Depreciation
    • Shipping and Receiving
    • Accounts Receivable, Accounts Payable (A/R, A/P)
    • Credit Card Processing
  • Support for calculations associated with accrual accounting.
  • Ambitions for the future might include interfaces to online shopping carts, credit card clearing interfaces, and ERP systems.
Reconciling Those Needs 

A seemingly contradictory factor is that the kinds of sophistication that are required vary considerably. Consider:

  • A home user does not generally require most of the sophistication of accrual accounting that is required by business enterprises. 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.
  • On the other hand, home users are in increasing need of surprisingly sophisticated financial tools for managing stock portfolios, including:
    • Mutual funds
    • Retirement savings plans, with such identifiers as 401(k), IRA, Roth IRA, RRSP, or Insurance Annuities
    • Corporate stock purchase plans
    • Corporate option plans

Another set of contradictory requirements has to do with the back-end, and interfacing to other systems:

  • Home users need a simple-to-install, simple-to-maintain system. This essentially rules out the use of SQL for the storage medium/back-end for home users. (That is, the current state of the art for SQL on Linux does not offer any simple, fool-proof management for data).
  • By contrast, non-SQL systems for business use are almost unimaginable. SQL provides a high degree of data integrity and storage robustness, and also simplifies tremendously the import and export of data. Powerful SQL tools exist that can work magic in the hands of a good DB admin.

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.

Features and Functions

This section reviews the current status of various features. Some of these are 'in process', some are 'almost done', some are 'completely done'. This section thus provides status on both where we've been, and where we're going.

Internationalization
All menus, markup and help-text should be internationalized, so that GnuCash may be usable in any country. This would include the printing of currency values in the local country conventions.

Current status: Essentially Done (?)

  • All GUI messages currently use GNU gettext() for the message catalogs. Translations exist for English, British, French, Swedish, German, Japanese.
  • Help pages available only in English and French.
  • Monetary and string handling done through glibc. The latest glibc (2.2.3) is needed to get the correct functions.
  • Yannick Le Ny <y-le-ny@ifrance.com> traduction en francais
  • Most GUI input elements use the gtk text widget, and thus use the XIM input method in Asian locales. This allows e.g. Kanji, Katakana support. However, the register does not use XIM, and thus doesn't currently support the Asian languages. This needs fixing. (This may be done already??)

Reports
A variety of reports, including Net Worth, Balance Sheets, and Profit and Loss statements. These should be printable: that is, exportable as HTML as well as print-ready postscript. These should be easy to customize. Ideally, even novice users should be able to create custom reports.

The Report Generator should be a separate but "dockable" subsystem of the whole. That is, it should be possible to run the report generator in a stand-alone, read-only fashion without having to start up the main application. It should be possible to run reports nightly from a command-line and/or cron job. The GUI should remember what reports were run last time, and these should be re-run/redisplayed whenever the report generator is used.

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. Note there are several flavours of customization:

  • Allow user to specify a custom logo (e.g. company logo/address) on every page (generically, having a header and footer for every page).
  • Allowing user to modify report title/subtitle on the fly (and possibly add notes at the top or bottom of the report, e.g. to explain line items).
  • Allow user to use the transaction query interface to pick the set of transactions that will make up the report.
  • Memorize the report that was asked for, give that report a name, and in the future, allow that same exact report to be re-run. Allow user to edit this report properties at a later date. Note that the basic idea is similar to that of memorized queries, discussed below. 
       Note that the customization info should be stored in a 
       Arrangements File (see below).

Generated reports should be exportable to other gnome systems (probably using bonobo). Reports should also be exportable to the Gnumeric spreadsheet (probably by writing out gnumeric file format). Export of CSV (comma separated values) and tab-delimited formats (for other spreadsheet import) would be good. Tables & etc. should be exportable to AbiWord, StarOffice, other word processors. (formats: docbook sgml? would then make convert to richtext, TeX easy.) Export should be as wysiwyg as possible.

Must be possible to e-mail reports (for example, invoices) to users. Suggest an evolution addressbok /mailer bonobo plugin.

Relationship to budgeting not clear ...

Stock portfolio tools should include a Cost Averaging report, Market Index report, Stock Option values, Estimation of capital gains tax liabilities.

Reports should be printable to printer (postscript/ Adobe Acrobat). <p> Status:

  • A general reporting infrastructure was implemented in Perl, in the form of html-embedded perl (ePerl). However, this reporting mechanism was abandoned in part because ongoing build and install problems related to ePerl and swig. Also, since ePerl didn't participate in the interpreter even loop, the report generator had to run as a separate process, reading data via pipes. This was uglier than some folks liked.
  • A general reporting infrastructure has been implemented in Scheme. Currently, there are a variety of reports for Profit/Loss, Balance Sheet, and portfolio valuation; none are particularly sophisticated.
  • Done: Reports are displayed with the gtk-html widget. This widget provides postscript printing and Acrobat output.
  • There is currently no way (no longer any way??) to generate reports from the command line ...
  • While many reports have been implemented, there is no master list of what we should have. We should have ....
  • The following technologies were rejected/unused mostly because they were too complex, didn't hang together technologies: 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.

Graphs

Provide support for graphs, charts, etc., such as: Asset allocation pie chart, portfolio value vs. cost, ROI. Graphs should be printable to printer. Graph generation should be fully integrated with reporting, both for data collection via queries, and for displayed output.

Status:

  • Different graphing packages were evaluated, GUPPI. Guppi was chosen. Considered & rejected were plotutils, gnumeric graphing code (Miguel says they'll replace gnumeric code with guppi.) Miguel's/Gnumeric requirements were: interactive plot editing -- each segment attributes totally settable/controllable -- drag/move callbacks when segments are click-dragged.
  • Basic pie charts and bar charts are used in GnuCash reports. There are problems: dates along the bottom of a bar-chart are not well-spaced/autoscaled. The over look is a bit klunky.

Transaction Query
Allow user to build (complex) queries to locate a set of transactions that match some criteria: e.g. a date range, or a matching payee, description, amount, etc. Once a user has created a complex query, it must be possible to memorize it (i.e. give it a name, and store it for future reuse).

Status:

  • The query engine has been implemented (as of 1.4.0, grib)
  • The GUI for creating queries has been implemented (as of 1.4.0, grib)
  • The queries are handled by the Postgres SQL backend. (as of 1.6.0, linas)
  • Queries can be turned into XML and back, for file storage or network transmission. This used to work for XML version 1 but was broken in version 2.
  • The ability to memorize queries has not been implemented and awaits further action (needed for reports, above).

Simplified Ledger
Ledger should look clean, work easily.

Status:

Essentially done.

  • Multi-line ledger confusion fixed by using correct left-right journal display style. Fixed in 1.6.0, Peticolas, Champaigne.
  • Stocks and Mutual funds are handled by placing them each in their own account. Each account can be viewed individually. If all of the stock accounts are children of a master trading account, then the trading account can be viewed and modified in a General Ledger window. Layout problems fixed in 1.6.0.
  • How to most simply allow the user to enter loads and fees? Through multi-line transactions. Seems to work well in 1.6.0.

Themes, Icons, Glitz
A variety of finer touches need work:

  • Hint-of-the-Day. A collection of a some 50-100 hints-of-the-day: short (2-4 sentence) hints/tips on how to use gnucash. Every time the user starts gnucash, an new hint shows up ... Status: Hint infrastructure complete (RGMerkel, version 1.4.0). Need to add hints (only a dozen are currently available).

  • Themes. Some theme testing required. The effect of themes on the register window needs to be reviewed. Some themes look flaky in the main account window, might be a gtk bug ???


  • Household Assets/House Inventory Add wizard to walk user through a set of questions about household inventory & help user value them. (do you own a house? appraised value? mortgage? do you own jewelry? appraised value? etc.) In particular, show how appreciation and depreciation should be treated. See the section Arrangements for a discussion of the customization issues.

  • More account types Introduce more 'fundamental' account types: (amortized) Loan, Mortgage, ESOP, House, Line of Credit.

  • Register View Allow user to view only non-reconciled transactions ...

  • Configurable main-window Status Bar Bottom of main window currently shows total asset, and total income-expense (profits). Make this configurable, so that user can show arbitrary sums of arbitrary accounts. This is mostly solved by having the MDI interface have reports, and the use of multi-paning. But the default display for gnucash should be changed to show a very small (1-4 line) networth and P&L report, and maybe a cash-flow report. See the section Arrangements for a discussion of the customization issues.

  • Dockable Registers/ aka "Browser Mode". Currently, when each new register opens, it opens in a new window. An alternate style would be to 'dock' the register window in a bigger frame, and just have 'backward/forward' buttons to navigate through different registers (the way that a browser navigates web pages.) This of course would be a user preference. Possiblity for doing this exists with MDI. Maybe we shouldn't bother doing this ??

  • Context sensitive help. When users create new accounts, need to suggest stuff if the user typed something unexpected ... (e.g. non-alphanumeric input) ...

  • Folder Tabs 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. This is maybe a bs. request that shoudn't be implemented.

     The following have been completed, but possibly not fully
     documented:

  • Pop-up Calendar All date fields should pop up a calendar widget; selected date should get entered in field. (peticolas, version 1.4 ??)

  • Pop-up Calculator All price/amount fields should pop up a calculator widget; output of calculator gets entered in field. Instead of a popup calculator, this was implemented by allowing all fields to take algebraic expressions (plus, minus, times, divide). (rlb ?? version 1.6.0)

  • Button Bar A user-configurable button-bar. Solved in version 1.6.0 with tabs, not buttons, via gnome MDI (gribble, version 1.6.0) See also the section Arrangements for a discussion of the customization issues.

  • Currency Exchange Table Keep a currency exchange-rate table. This is now automatically handled via the 'price database' (rlbrowning, version 1.6.0) (the finance::quote perl module handles currency exchange rate fetches)

  • Currency Selection Pop-up Currency field should get replaced by menu of long-hand currency names, three-letter ISO 4217 abbreviations, and symbols. User should be able to hand-enter non-IS4217 currencies. Status: Done in 1.4.0 

               </p>

  • Cut-n-paste Cut-n-paste of whole transactions in the register window... Status: Done. (by Dave Peticolas, in 1.4.0)

  • Auto-completion Quick-fill should also auto-complete amount, memo fields. Status: Done in 1.4.0, Dave Peticolas

  • Autoincrement Check numbers should auto-increment. Hit + key in check number field (same keystroke as in quicken). Status: Done in 1.4.0, Dave Peticolas

  • Navigation Menu navigation using the keyboard should be possible. Hit the Alt-F to get file menu, hit Alt-FS to save. Similarly, tab-key navigation in the register should be possible. Status: Done (in 1.3.x ?, Dave & all, partly inherited via gtk widget set.).

  • Fly-Over Help When the user pauses the mouse over a button, "fly-over" pop-up help windows should appear. Status: Done (in 1.3.x, inherited via gnome/gtk widget set).

  • Grayed-out Form Help Create grayed out entries in the ledger, titled "Memo", "Description", etc, helping users understand what should be typed into each field. Status: Done (by Dave?), as of version 1.3.2(?)

  • Key Bindings for Editing Text Fields. The input fields use the gtk text widget, which provides key bindings that are similar to the Netscape/emacs key bindings. This allows e.g. emacs-style ctrl-a, ctrl-k to do the right thing. Status: Done (in 1.3.x, inherited via gnome/gtk text widget).

    •        </ul>

Miscellaneous Small Projects
A variety of small internal projects. All have been completed as of 1.6.0

  • File Format. Rework to use text file format. Will be XML-based. Status: RLB, LewisMoss. Version 1.6.0 Done.

  • Reconcile Window. Auto-pay credit card when reconciling credit card accounts (Done, Dave). Auto-add bank fee when reconciling bank accounts. (Not done?, Dave).

  • Print Register Window. Output register window to printer. Status: Done: there is a register report which is printable, there is botton on register. Done in 1.6.0

  • # of decimal places in prices (penny stock). Part of the big numeric overhaul. Done, Gribble, others, version 1.6.0

  • gtkhtml. Move to gtkhtml from gtk-xmhtml. Done in 1.5, Grib.

  • print. Print reports, etc. Done in 1.5, Grib. This came 'for free' with gtkhtml.

  • key-val pairs. Add generic key-slot mechanism into accounts, transactions, journal-entries. Done in 1.5.0, Grib.

  • guid in fileio. No longer relevant with new file format. Dave.

Books, Accounting Periods
Ability to close the book at end of the fiscal year. This consists of several steps:

  • Permanently lock some transactions 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.
  • Transfer the Income minus Expense for the book period to an equity account, so that each new period starts with zero income/expense balances.
  • A mechanism to purge really old transactions from the database.
  • Extensions to querying and reporting infrastructure ... The query changes might be painful ...
  • A user should be allowed to 'delete' an account only if it has no transactions in the currently open book. Of course, it's not deleted from the old books. From this last, we conclude that every chart of accounts should have a beginning and ending date (that match the book period), and the file format needs to support multiple charts ...
  • Memorized Transactions ... Currently, transaction auto-completion works by auto-completing with the last 'similar' transaction. This ability will get trashed when books for the old year get closed, because there won't be 'similar' transactions.

Status:

  • A mini-design Doc exists in src/engine/extensions.txt A far more extensive, four-part proposal is ??? somewhere in the mailing list archives (by Linas Vepstas, circa Feb-May 2001)

Check Printing
Create a check-printing ability. Include MICR (Magnetic Ink, Computer Readable) check printing abilities. Yahoo Check Printing provides a list of vendors & printers.

Print vendor/client/payee address on the check (so that check can be mailed with window envelopes.) This requires gnucash to integrate with addressbook. <p>Status:

  • More check formats need to be supported.
  • Done, except for address part, in version 1.4.0. (gribble)
  • Need a sample check/sample transaction to print out so that user can test printer.
  • MICR Fonts are available & brought to mailing list.


Wizards
Create a set of wizards to walk through some of the more complex tasks, such as new user setup, account creation, QIF import, budget prep, obscure functional corners.

Wizards are great, but lets not thow away the denser GUI's. For 8-hour-a-day users, the wizards can be irritating. A single, dense screen can be more efficient and nicer. So when adding wizards, don't dump GUI's !! (instead, make them 'advanced' features). <p> Status: The following not done:

  • Account Creation The account creation panel is somewhat busy. Maybe could use a wizard?
  • Budget Setup Setting up a budget.
  • Obscure Corners Various obscure corners of the application may be non-intuitive, and need wizard help. e.g. stock splits? e.g. using foreign currency on a business trip?

Completed:

  • New User Setup Provide a default Chart of Accounts, which will mostly consist of a default set 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. Profiles: home-owner vs. renter non-for-profit (some non-profits are very very simple, just a club). Done in version 1.6.0, C. Champagne, J LewisMoss
  • QIF Import QIF Import is just complicated enough that it needs a wizard walk-through of the steps. Grib, version 1.6.0, Done.
<p>


Arrangments
An "application arrangement" is the defining look-n-feel of an application. The idea is similar to, but not the same as 'skins'/'themes'. Its similar to, but not the same as allowing a user to set 'preferences'. Its similar to, but not the same as, allowing a user to generate customized financial reports. In the context of GnuCash, a 'arrangement' should be a file (that can be traded by users, uploaded and shared) that controls important aspects of how the application is configured.

In particular, the GnuCash Arrangement should include the following:

  • A list of sample/initial accounts. These might be tailored for a home user (groceries, gas, electric), an apartment dweller (rent, laundry), or different kinds of business users. Because these sample accounts appear in the Arrangement file, it becomes easy to create & distribute customized arrangements.
  • A list of pre-defined reports and graphs. The kind that you'd find for a home user might be different than for a person managing a stock portfolio, which is in turn different from what a business might need. The Arrangement File should include install-specific customizations, such as the report headers, footers, etc.
  • Hint of the day. The types of 'hint of the day' would be different for new users, than it would be for advanced users. Thus, different arrangements would have different catalogues of 'hint of the day'.
  • Menu Contents & Navigation. New users might be presented with a simple set of menu contents. 'Power Users' might be presented with deep, nested sets of menus, with oodles of features.
  • Register Layout. The layout of the register might be customized for different countries: e.g. in Germany, a different type of electronic banking seems to require the display of account numbers in separate columns in the register. 
       A good arrangement infrastructure will not only allow gnucash to be configured
       for different application domains, but also will allow users to fine-tune
       thier own prefered arrangement.   It can also simplify the code base: 
       instead of having two products, a home-user application, and a small-business 
       application, each with a different code base and #defines and what not, instead,
       we have one code base, and different arrangments for each.
       However, most importantly, the arrangments should be easy to share between users.
       They should be such that users are encouraged to trade and use arrangments,
       and to create new ones that suit thier needs.

The idea for arrangements was inspired by Adam Curry's commentary on radio formats and Napster.

Status: Not started. Individually, all these cusomizable things exist here and there in gnucash, but they cannot be shared between users: a gnucash user cannot mail her favorite 'arrangement' to her freind.

User Preferences, Session Management
A dialog system and file format for manipulating user preferences. Preferences include things like default currency, register layout and colors, etc.

What are some of the competitive preference-handling technologies? Lets get some URL's here ... Following the Unix tradition, there is no global preferences registry. Note that session management and preferences are related things ... sort-of. Right now, we don't treat them as such ...

Status:

Done, more or less, version 1.6.0.

  • Works real good; lots of preferences in the GUI. Implemented in home-grown scheme. (version 1.4.0, rlb)
  • These are saved in the '.gnucash/config.auto' file. The current file format is raw scheme code, rather delicate to tweak by hand ...
  • Session management mostly works, but doesn't use the sawmill/gnome/X ICCCM system. GnuCash remembers MDI based reports, restart reopens in same state. Sizes and shapes and positions are remembered. Done in version 1.6.0
  • Independently of session management, the register windows should remember how big they were last time they were popped up, and they should pop up the same size, again. The app should remember these sizes from invocation to invocation. Done in version 1.6.0, but seems a bit buggy.

Architecture Review
The application is wired together partly with C, partly with Scheme. The architecture of the wiring and how scheme is fit in needs to be reviewed, with a general overview created so that additional extensions may be added in a straightforward manner.

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:

  • Scheme/Guile is the central extension language. Guile interfaces auto-generated using g-wrap.
  • Optional interfaces to the data engine (for, e.g. perl) can be generated using SWIG.
  • Dave to collate & edit architecture documents. RLB to provide diagrams.

</dl>

GnuCash Architecture

Decisions

Project Decisions

Design Decisions

Rules

Project Rules

Design Rules

=== Coding Rules===

Retrieved from "https://wiki.gnucash.org/wiki/index.php?title=Project_and_Design_Documentation&oldid=11277"