From 26777370eff0c0a911e0752fa7113c92a5273ca0 Mon Sep 17 00:00:00 2001 From: David Hampton Date: Thu, 17 Jul 2003 06:59:44 +0000 Subject: [PATCH] Sync the g2 branch with the gnome2-merge-1 tag. git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/branches/gnucash-gnome2-dev@8896 57a11ea4-9604-0410-9ed3-97b8803252fd --- lib/Makefile.am | 2 +- lib/README | 9 +++ src/doc/Makefile.am | 3 +- src/doc/books.txt | 8 +- src/doc/doxygen.cfg.in | 9 +-- src/doc/doxygen_main_page.c | 69 +++++++++++++++-- src/doc/lots.txt | 148 ++++++++++++++++++++++++++++++++++-- 7 files changed, 222 insertions(+), 26 deletions(-) diff --git a/lib/Makefile.am b/lib/Makefile.am index 882b08798a..2cee85b120 100644 --- a/lib/Makefile.am +++ b/lib/Makefile.am @@ -1,4 +1,4 @@ SUBDIRS = libc guile-www srfi egg -EXTRA_DIST = README +EXTRA_DIST = README guppi-legend.patch diff --git a/lib/README b/lib/README index 4506f96bbb..e6d455c2fa 100644 --- a/lib/README +++ b/lib/README @@ -7,3 +7,12 @@ Finance::Quote -------------- Available from http://finance-quote.sourceforge.net. + +------------------------------------------------ + +guppi-legend.patch: Apply this patch to the Guppi 0.40.3 package (and + compile and install the patched version) in order + to fix the reversed legend problem with stacked + barcharts. + +------------------------------------------------ diff --git a/src/doc/Makefile.am b/src/doc/Makefile.am index a3048dd65d..bf55f18552 100644 --- a/src/doc/Makefile.am +++ b/src/doc/Makefile.am @@ -4,6 +4,7 @@ SUBDIRS = \ xml EXTRA_DIST = \ + README \ backup.txt \ budget.txt \ constderv.html \ @@ -68,6 +69,6 @@ uninstall-hook: doxygen.cfg: doxygen.cfg.in Makefile rm -f $@.tmp sed < $< > $@.tmp \ - -e 's:@-top_srcdir-@:${top_srcdir}:g' + -e 's:@-top_srcdir-@:${top_srcdir}:g; s:@-VERSION-@:${VERSION}:g' mv $@.tmp $@ diff --git a/src/doc/books.txt b/src/doc/books.txt index c3b5c20c74..8290312b7f 100644 --- a/src/doc/books.txt +++ b/src/doc/books.txt @@ -241,8 +241,8 @@ Plan A has been implemented in the engine. fails to store the kvp's in a book structure ?? -The current implementation of books is broken by the lack of support of -'lots' in the engine. The problem is that for stock accounts (and +The current implementation of books is broken because it does not +yet make use of 'lots'. The problem is that for stock accounts (and other non-currency accounts), it is not enough to supply merely the opening balance. In order to handle depreciation or cap gains properly, the dates and quantities of a purchase need to be easily available. @@ -260,10 +260,10 @@ Open Issues *) Trimming of price database ??? -*) handling of multi-book reports ??? Need to work out the recommended way +*) Handling of multi-book reports ??? Need to work out the recommended way of making this happen.... -*) Lots ... +*) Lots are now implemented in the engine, but not yet used in this code. diff --git a/src/doc/doxygen.cfg.in b/src/doc/doxygen.cfg.in index 3644b234ca..643ca3f147 100644 --- a/src/doc/doxygen.cfg.in +++ b/src/doc/doxygen.cfg.in @@ -4,7 +4,7 @@ # General configuration options #--------------------------------------------------------------------------- PROJECT_NAME = GnuCash -PROJECT_NUMBER = +PROJECT_NUMBER = @-VERSION-@ OUTPUT_DIRECTORY = OUTPUT_LANGUAGE = English EXTRACT_ALL = NO @@ -13,7 +13,6 @@ EXTRACT_STATIC = NO EXTRACT_LOCAL_CLASSES = NO HIDE_UNDOC_MEMBERS = NO HIDE_UNDOC_CLASSES = NO -HIDE_FRIEND_COMPOUNDS = NO BRIEF_MEMBER_DESC = YES REPEAT_BRIEF = YES ALWAYS_DETAILED_SEC = NO @@ -48,7 +47,7 @@ SHOW_USED_FILES = YES #--------------------------------------------------------------------------- # configuration options related to warning and progress messages #--------------------------------------------------------------------------- -QUIET = NO +QUIET = YES WARNINGS = YES WARN_IF_UNDOCUMENTED = YES WARN_FORMAT = @@ -61,7 +60,7 @@ FILE_PATTERNS = RECURSIVE = YES EXCLUDE = EXCLUDE_SYMLINKS = YES -EXCLUDE_PATTERNS = +EXCLUDE_PATTERNS = *P.h EXAMPLE_PATH = EXAMPLE_PATTERNS = EXAMPLE_RECURSIVE = NO @@ -135,8 +134,6 @@ MAN_LINKS = NO # configuration options related to the XML output #--------------------------------------------------------------------------- GENERATE_XML = NO -XML_SCHEMA = -XML_DTD = #--------------------------------------------------------------------------- # configuration options for the AutoGen Definitions output #--------------------------------------------------------------------------- diff --git a/src/doc/doxygen_main_page.c b/src/doc/doxygen_main_page.c index 62dcee512a..2d2c3405d9 100644 --- a/src/doc/doxygen_main_page.c +++ b/src/doc/doxygen_main_page.c @@ -1,13 +1,58 @@ -/*! \mainpage GnuCash design and developer's manual +/*! \mainpage GnuCash design and developer's reference \section intro Introduction -This is the new GnuCash developper and design manual for GnuCash. Previous documentation will slowly be integrated into this, and eventually it should always be up to date since it is generated directly from the source files using Doxygen. + +This is the new GnuCash developer and design manual for GnuCash. +Previous documentation will slowly be integrated into this, and +eventually it should always be up to date since it is generated +directly from the source files using Doxygen. \section hacking Hacking on this documentation -I will eventually post a style guide for documenting, and document one of the files "by the book". Until then, feel free to start documenting or playing with doxygen configuration. + +I will eventually post a style guide for documenting, and document one +of the files "by the book". Until then, feel free to start +documenting or playing with doxygen configuration. This main page can +be found in src/doc/doxygen_main_page.c . + +\subsection style_discussion Style discussion + +[cstim 2003-03-25] It's too bad that doxygen doesn't show the "Member +Groups" (those created on-the-fly with @{ and @}) inside the Module +pages (named groups, created with \\addtogroup). This means that the +"member group" grouping of the account-related functions is only shown +in the documentation of the Account.h header file. But in the +documentation of the Engine group (module) all these functions are +lumped together into one unreadable long list. This is bad (because +1. nobody will read through the long list, 2. hyperlinks don't even +work properly since the document is simply too big). Isn't there a way +to have this member groups also show up on the module pages...? +Unfortunately nesting several named modules (groups) into one another +doesn't really solve this problem, because that way all +account-related functions will show up in one separate group each -- +which makes these unreadable as well. Maybe it would even be better to +not have these function names show up on the module page at all. If +they appear *only* on the file page, they will show up in their +respective "member group" grouping and everything would be fine. + +[cstim 2003-03-25] The "Data Structures" page of doxygen doesn't show +anything useful for gnucash. Obviously doxygen only accepts "real" C +struct definitions for inclusion on that page. However, all gnucash +data structures are defined somewhere in private headers, and only the +typedefs are publically visible. Isn't there a way to have doxygen +show the documentation for the typedefs on the "Data +Structures" page? Unfortunately I don't know how. + +[cstim 2003-03-25] This mainpage file should at some time be moved to +a file name ending in .txt or even .html. It's a PITA to edit one huge +C comment. All text editors will run amok sooner or later (well, +XEmacs does :) and will not support proper HTML markup and editing +inside this C comment... well, that's not really a problem of the +outcome, yes. It would just make life easier for editing this +non-source file. \subsection config Editing Doxygen configuration + To edit the doxygen configuration, you can use: * cd src/doc @@ -15,11 +60,19 @@ cd src/doc doxywizard doxygen.cfg & \subsection reference Doxygen reference documentation -The Doxygen web site (http://www.stack.nl/~dimitri/doxygen/) has a complete user manual. For the impatient, here are the most interesting sections: -- How to write documentation blocks for files, functions, variables, etc.: http://www.stack.nl/~dimitri/doxygen/docblocks.html. - Do not forget to add a file documentation block (@file) at the top of your file, -otherwise, your documentation will not appear in the html. -- List of the special commands you can use within your documentation blocks: http://www.stack.nl/~dimitri/doxygen/commands.html + +The Doxygen web site (http://www.stack.nl/~dimitri/doxygen/) has a +complete user manual. For the impatient, here are the most +interesting sections: + +- How to write grouped documentation for files, functions, variables, +etc.: http://www.stack.nl/~dimitri/doxygen/grouping.html . Do not +forget to add a file documentation block (@file) at the top of your +file. Otherwise, all documentation in that file will not appear +in the html output. + +- List of the special commands you can use within your documentation +blocks: http://www.stack.nl/~dimitri/doxygen/commands.html \section contact Contacts diff --git a/src/doc/lots.txt b/src/doc/lots.txt index 9f69df3067..d7aa894dea 100644 --- a/src/doc/lots.txt +++ b/src/doc/lots.txt @@ -250,7 +250,7 @@ I move to brazil, and take my RHAT stock (purchased in dollars) to my brazilian broker (who will sell them for cruzeiros). Is the correct answer to just 'punt' in these cases? -How is teh closing of books to be handled in such a case? +How is the closing of books to be handled in such a case? GUI Elements: -- The user should be able to specify a default 'realized-gain' @@ -259,6 +259,14 @@ GUI Elements: account that is associated witha a stock account. +FIFO's +====== +What is a FIFO ? A FIFO is a type of accounting policy where +income from selling inventory is accounted by selling the oldest +inventory first. Thus, the profit/loss of the sale corresponds +to the difference in price between when it was bought and sold. +FIFO's are also used in depreciation schedules, and in other places. + Implementation ============== @@ -274,13 +282,141 @@ lots so that all lots belonging to an account can be quickly retreived. (In principle, the lots can be found by scanning every split in the account, but this is a painful process.) +Implementing Cap Gains (Is a Pain in the Neck) +============================================== +Although Lots provide a good conceptual framework for determing +gains or losses when a lot is closed, cap-gains on half-open +lots present additional complexities. Consider the following +stock purchase and subsequent sale of half the stock: + +Account A is a stock account +Account B is a bank account +Account C is an income account + + Acct A Txn Acct B Acct C +Date Action Amt Prc Value Amt Amt +1/1/01 buy 100s $10 $1000 ($1000) - +2/2/02 sell (50)s $25 $1250 $1250 - +2/2/02 gain - - $750 $750 + +The gain, shown in the third line, is computed as a straight +sum of purchase price to sale price. + +Should the above be reprsented as two transactions, or as three? +One could, in principle, combine the second and third lines into +one transaction. However, this has some drawbacks: computing +the overall balance of such a transaction is tricky, because +it has so many different splits (including, possibly, splits +for brokerage fees, tax, etc. not shown). The alternative +is to represent each line as a separate transaction. This has +other drawbacks: If the date, amount, price or value is adjusted +for the second transaction, the corresponding values must be +adjusted for the third, and vice-versa. + +Both schemes pose trouble for the register display: we want +the stock register to show the gain as if it were a part of +the stock sale; but the third line is a pair of splits, and +we want to show only one of these two splits. Whichever method +is chosen, the register has to filter out some of the splits +that it shows. + +The implementation that seems best is to represnet the sale +with two separate transactions: one for the sale itself, and a +separate one for the gains. This makes computing the balance +easier, although it makes the logic for setting the date +more complex. Ughh.. + + +Conversion +========== +When Lots are finally put into production, old GnuCash datasets +will need to be converted. Conversion will be done by running +all splits in an account through an accounting FIFO. The goal +of the FIFO is to match up purchases and sales so that these can +be assigned to a Lot. + +The conversion algorithm will work as follows: + +for each account { + loop over splits { + // perform the 'double-balance' check + if (split commodity != transaction currency) account needs conversion + } + if account needs conversion + for each split { + If (split amount > 0) create new lot, put split in lot. + If (split amount < 0) find oldest lot, put split in that lot + } +} + +See the file Scrub2.h for details. + + +GUI +=== +A GUI for handling Lots is needed: ability to view a lot, and to cut/paste +or move a split from one lot to another. Need a GUI to create a lot, +maybe append some notes to it. Need ability to view account in lot-mode. + +For automatically managing accounts, need to implement a variety of +different accounting policies (of which the FIFO policy is currently +implemented in the 'Scrub' routines). + + +Basic GUI: + The goal of the basic GUI is to handle most usages of + most lots in most places. There also need to be special-purpose + dialogs for specific applications, e.g. stocks, inventory, etc. + + Shows three areas: + -- list of lots, one of which can be highlighted. + Lot names can be edited in-place. + -- contents of a single lot (displayed in a narrow, + mini-register view, showing only date, memo, quant, + balance) + -- list of splits not in any lot. + (not clear if screen real-estate allows side-by-side + placement, or if this must be above/below. above/below + would suck) + + Shows various buttons: + -- two arrows, which move split into/out of lot. + This is a traditional way of moving something from one + list to another, but some UI designers argue against this. + Is there a better way to move splits into/out-of a lot? + + -- button, labelled 'close lot', which, when pressed, will + set lot balance to zero. (by using fifo on the unassigned + splits, if possible). + + -- A field showing realized gain/loss on a closed lot, and + a pull-down allowing the gain/loss to be posted to a + specific account. + (The default is stored in kvp:/lots-mgmt/gains-acct/) + + -- button or menu item, 'add notes to this lot'. + + Status ====== -Core support for Lots in the engine is complete (April 2002). -See src/engine/gnc-lot.h for the public API. -FIFO's have not been started. -The XML backend support for lot is complete (but untested). -The Postgres backend does not yet support lots. + o Core support for Lots in the engine is complete (April 2002, ships in + version 1.8.x, used by business backend). + o See src/engine/gnc-lot.h for the public API. + o The XML backend support for lot is complete (April 2002, ships in + version 1.8.x). + o The Postgres backend does not yet support lots. + o Scrub routines to automatically take old gnucash datasets and + transition them to double-balanced lots have been implemented. + These implement a FIFO accounting policy (April 2003) + +XXX need to add a lot id, have it auto-gened by the scrubber. + + o No GUI yet. + +XXX It is a good idea to generate a gain/loss split for ever sale, not +just the lot closure. Need to tweak the register to hide/show as appropriate. +Need to add a tag to the gain spl;it to indicate its's 'special' nature. + -------------------------- end of file ------------------------------