[Gnucash-changes] Folding txt files into Doxygen output
Neil Williams
codehelp at cvs.gnucash.org
Sun Jun 19 13:49:58 EDT 2005
Log Message:
-----------
Folding txt files into Doxygen output
Tags:
----
gnucash-gnome2-dev
Modified Files:
--------------
gnucash:
ChangeLog
gnucash/src/doc:
backend-api.txt
backend-errors.txt
backup.txt
books.txt
budget.txt
business.txt
constraints.txt
currencies.txt
doxygen.cfg.in
doxygen_main_page.c
engine.txt
g2-architecture.txt
generic-druid-framework.txt
guid.txt
loans.txt
lots.txt
multicurrency-discussion.txt
netlogin.txt
plugin.txt
prices.txt
qif.txt
tax.txt
user-prefs-howto.txt
gnucash/src/engine:
design.txt
extensions.txt
kvp_doc.txt
gnucash/src/scm:
startup-design.txt
Removed Files:
-------------
gnucash/src/doc:
gnc-commodity.txt
Revision Data
-------------
Index: ChangeLog
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/ChangeLog,v
retrieving revision 1.1487.2.229
retrieving revision 1.1487.2.230
diff -LChangeLog -LChangeLog -u -r1.1487.2.229 -r1.1487.2.230
--- ChangeLog
+++ ChangeLog
@@ -1,3 +1,35 @@
+2005-06-19 Neil Williams <linux at codehelp.co.uk>
+ * src/doc/backend-api.txt
+ * src/doc/backend-errors.txt
+ * src/doc/backup.txt
+ * src/doc/books.txt
+ * src/doc/budget.txt
+ * src/doc/business.txt
+ * src/doc/constraints.txt
+ * src/doc/currencies.txt
+ * src/doc/doxygen.cfg.in
+ * src/doc/doxygen_main_page.c
+ * src/doc/engine.txt
+ * src/doc/g2-architecture.txt
+ * src/doc/generic-druid-framework.txt
+ * src/doc/guid.txt
+ * src/doc/loans.txt
+ * src/doc/lots.txt
+ * src/doc/multicurrency-discussion.txt
+ * src/doc/netlogin.txt
+ * src/doc/plugin.txt
+ * src/doc/prices.txt
+ * src/doc/qif.txt
+ * src/doc/tax.txt
+ * src/doc/user-prefs-howto.txt
+ * src/engine/design.txt
+ * src/engine/extensions.txt
+ * src/engine/kvp_doc.txt
+ * src/scm/startup-design.txt: Folding text files
+ into Doxygen output.
+
+ * src/doc/gnc-commodity.txt: Removed: empty.
+
2005-06-12 Derek Atkins <derek at ihtfp.com>
* src/engine/gnc-hooks*:
--- src/doc/gnc-commodity.txt
+++ /dev/null
@@ -1,10 +0,0 @@
-README.gnc-commodity
-
-Bill Gribble <grib at billgribble.com>
-2 Aug 2000
-
-gnc-commodity : a representation of currencies, stocks, and other
-tradable commodities.
-
-
-
Index: doxygen_main_page.c
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/doxygen_main_page.c,v
retrieving revision 1.1.4.2
retrieving revision 1.1.4.3
diff -Lsrc/doc/doxygen_main_page.c -Lsrc/doc/doxygen_main_page.c -u -r1.1.4.2 -r1.1.4.3
--- src/doc/doxygen_main_page.c
+++ src/doc/doxygen_main_page.c
@@ -1,14 +1,96 @@
/** \mainpage GnuCash design and developer's reference
This is the new 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
+\section maindocs Documentation Sections.
+
+The documentation is organised in a rough sequence:
+
+-# \ref manualguide Start with the main GnuCash manual.
+-# \ref texihtml Design overview.
+-# \ref doxylist Individual topic overviews, linked into the
+ full API reference for each topic, generated from source code.
+-# \ref maingeneral How to work with Doxygen in your own code.
+
+\subsection manualguide External documentation.
+
+Please refer to the main
+<a href="http://www.gnucash.org/en/docs.phtml">documentation
+page</a> on the gnucash website which includes links to the
+GnuCash Manual and the Concepts Guide in various formats.
+
+\subsection texihtml Documentation elsewhere in the source tree.
+
+See also <a href="http://code.neil.williamsleesmill.me.uk/texi/gnucash-design.html">
+GnuCash Design Overview</a> which can be generated from the source using texi2html
+from the texinfo files in src/doc/design.
+
+The <a href="http://code.neil.williamsleesmill.me.uk/finutil.html">
+Financial Transaction Utility</a> documentation is not compatible with Doxygen.
+
+\section doxylist Doxygen overviews.
+
+Where possible, each overview is dated - take care to review older texts
+in relation to existing code.
+
+- \ref backuppolicy
+- \ref bookperiods
+- \ref business1
+- \ref currencies
+- \ref deprecated
+- \ref engine
+- \ref backendold
+- \ref financeconstraints
+- \ref druidframework
+- \ref guid
+- \ref gnome2
+- \ref networkoverview
+- \ref backenderrors
+- \ref loanhandling
+- \ref kvpvalues
+- \ref lotsoverview
+- \ref multicurrency
+- \ref plugindesign
+- \ref pricedocs
+- \ref gnucashextension
+- \ref qif
+- \ref backendapi
+- \ref budgetplan
+- \ref taxnotes
+- \ref todo
+- \ref userprefs
+
+Each overview in this section is generated directly from the
+source files using Doxygen but some topics need updating.
+
+\section maingeneral General Doxygen help.
+
+- \ref tipshints
+- \ref reference
+- \ref stylediscussion
+
+*/
+
+/* Editing this file? Comments can be inserted in this file
+ Remember to use C syntax but skip the extra asterisk so that doxygen
+ignores the extra notes, like this one.
+*/
+/* Hacking alert: When adding new sections, keep the references in
+alphabetical order OF THE DESCRIPTION, not the reference title.
+
+Also, make sure all reference titles are unique across the entire
+Doxygen output.
+
+Keep each section within one C comment block and any text before
+the first section of a page must be in the same comment block as the
+page title itself.
+
+*/
+
+/** \section hacking Hacking on this documentation
There is the beginning of a style guide for documenting under
-\ref tips_hints.
+\ref tipshints.
The Book Merge files are an attempt to document "by the book".
\ref BookMerge\n
@@ -17,21 +99,29 @@
Each doxygen section must be within a single comment block although
large comment blocks can be split into separate pages:
-\ref style_discussion.
+\ref stylediscussion.
This main page is just an introduction to doxygen markup, see the
Doxygen manual for the full command set.
-- \ref tips_hints Tips and hints for using doxygen
-- \ref style_discussion Long comments, pages, editors
+- \ref tipshints Tips and hints for using doxygen
+- \ref stylediscussion Long comments, pages, editors
- \ref reference Links to the Doxygen manual
+Code snippets need special handling in the text overviews. Change all
+comment markers to // (so that the overview comment remains intact)
+and then wrap each code snippet in the \a verbatim \a endverbatim
+doxygen markers.
+
+One useful method is to edit these .txt files using the syntax highlighting
+of normal C files.
+
*/
/**
-\page tips_hints Useful tips for doxygen in C files
+\page tipshints Useful tips for doxygen in C files
- \ref index Introduction
- - \ref style_discussion Long comments, pages, editors
+ - \ref stylediscussion Long comments, pages, editors
- \ref reference The Doxygen manual
\section tips An introduction to doxygen markup
@@ -54,14 +144,14 @@
a simple block can still be linked into doxygen as long as the file is
identified to doxygen using a '\\file' section:
-/** \\file filename.h\n
+** \\file filename.h\n
\\brief one-liner summary of the file purpose\n
\\author the usual copyright statement
\subsection Methods How to document
Every doxygen comment block starts with an adapted comment marker.
-You can use an extra slash /// or an extra asterisk /** . Blocks end
+You can use an extra slash /// or an extra asterisk ** . Blocks end
in the usual way. Doxygen accepts commands using a backslash.
To put a description with each function or structure, use '\\brief'
@@ -86,7 +176,7 @@
Use the 'back reference' to document enumerator values:\n
enum testenum {\n
- enum_one /**< less than marker tells doxygen to use this line
+ enum_one **< less than marker tells doxygen to use this line
to document enum_one.
\subsection config Editing Doxygen configuration
@@ -99,10 +189,10 @@
*/
-/** \page style_discussion Style discussion
+/** \page stylediscussion Style discussion
- \ref index Introduction
-- \ref tips_hints Tips and hints for using doxygen
+- \ref tipshints Tips and hints for using doxygen
- \ref reference Links to the Doxygen manual
[codehelpgpg 2004-07-25] Doxygen now copes with addgroup and this page
@@ -131,8 +221,8 @@
/** \page reference Doxygen reference documentation
- \ref index Introduction
-- \ref tips_hints Tips and hints for using doxygen
-- \ref style_discussion Long comments, pages, editors
+- \ref tipshints Tips and hints for using doxygen
+- \ref stylediscussion Long comments, pages, editors
The Doxygen web site (http://www.stack.nl/~dimitri/doxygen/) has a
complete user manual. For the impatient, here are the most
@@ -153,7 +243,9 @@
News about GnuCash as well as the latest version can always be found at http://www.gnucash.org/
\subsection email Email
-If you have any suggestions concerning this documentation, do not hesitate to send suggestions to gnucash-devel (see http://www.gnucash.org/en/lists.phtml for details)
+If you have any suggestions concerning this documentation, do not hesitate to send suggestions to
+gnucash-devel (see http://www.gnucash.org/en/lists.phtml for details)
-Benoit Grégoire mailto:bock at step.polymtl.ca
+Benoit Grégoire <bock at step.polymtl.ca>
+Neil Williams <linux at codehelp.co.uk>
*/
Index: business.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/business.txt,v
retrieving revision 1.4
retrieving revision 1.4.2.1
diff -Lsrc/doc/business.txt -Lsrc/doc/business.txt -u -r1.4 -r1.4.2.1
--- src/doc/business.txt
+++ src/doc/business.txt
@@ -1,21 +1,25 @@
+/** \page business1 Business Overview
-Business Object Overview
-------------------------
+API: \ref Business
-The GnuCash Businesness objects, in src/business/business-core, implement
+\section businessoverview Business Objects
+
+The GnuCash Business objects, in src/business/business-core, implement
certain basic small-business accounting functions. Below follows a summary
overview of the objects and the data that they store. These are listed in
order of complexity; with the basic building blocks first, and the more
complex structures last.
-Address:
+\subsection address Address:
A very simple object, stores strings for name/street-address/phone/fax/email
The address is not a separate entity, but is meant to be embedded in other
objects (that is, there is no addressbook; there is no address database that
is separate from the objects that use addresses; there is no 'foreach'
that can be used to iterate over all addresses.)
-BillTerm:
+API: \ref Address
+
+\subsection billterm BillTerm:
Describes billing terms, that is when a bill is due, and what sort of a
discount is applied (if any). The BillTerm object currently supports:
-- the discount applied to a bill (absolute numeric value),
@@ -24,19 +28,19 @@
-- cutoff ??
The proximo type does what ???
+API: \ref BillTerm
-Entry:
+\subsection entry Entry:
-Invoice:
+\subsection invoice Invoice:
Pulls together info needed to geenrate an invoice, including addresses,
job, the dates, the billing terms, the amounts, and the accounts
to be credited.
+API: \ref Entry
+\section bus_design Business Design & Implementation Notes
-
-Business Design & Implementation Notes
----------------------------------------
Derek Atkins <warlord at mit.edu>
Version of October 2003
@@ -72,5 +76,6 @@
- A parent has a list of all children.
- A parent has a pointer to the current 'replica child', if one exists.
+*/
------------------------- end of file ------------------------------
Index: tax.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/tax.txt,v
retrieving revision 1.1
retrieving revision 1.1.14.1
diff -Lsrc/doc/tax.txt -Lsrc/doc/tax.txt -u -r1.1 -r1.1.14.1
--- src/doc/tax.txt
+++ src/doc/tax.txt
@@ -1,6 +1,4 @@
-
-Some notes about taxes
-----------------------
+/** \page taxnotes Some notes about taxes
From: Jon Kaare Hellan <Jon.K.Hellan at item.ntnu.no>
@@ -20,4 +18,4 @@
So I need a way to keep track of these adjustments register for each
stock in a portfolio.
-
+*/
Index: user-prefs-howto.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/user-prefs-howto.txt,v
retrieving revision 1.1
retrieving revision 1.1.4.1
diff -Lsrc/doc/user-prefs-howto.txt -Lsrc/doc/user-prefs-howto.txt -u -r1.1 -r1.1.4.1
--- src/doc/user-prefs-howto.txt
+++ src/doc/user-prefs-howto.txt
@@ -1,8 +1,10 @@
+/** \page userprefs User Preferences HOWTO
+
Well, since I just explained this issue to Benoit on IRC, I thought I could
just post it here. If somebody (Benoit?) considers it helpful, you might add
it somewhere to CVS.
-How to add a preferences option
+\section userprefsadd How to add a preferences option
This text explains how to add options to the global preference dialog
from a module. The text uses the example of one simple boolean option
@@ -11,11 +13,13 @@
The option is created in the file src/import-export/hbci/hbci.scm,
with the following function call as a top-level function in that file:
+\verbatim
(gnc:register-configuration-option
(gnc:make-simple-boolean-option
(N_ "Online Banking & Importing") (N_ "HBCI Remember PIN in memory")
"b" (N_ "Remember the PIN for HBCI in memory during a session")
#f))
+\endverbatim
The actual option is created by the function call to
gnc:make-simple-boolean-option. Its first (string) argument is the
@@ -34,10 +38,12 @@
During the actual program run, the option is looked up only once, in
src/import-export/hbci/hbci-interaction.c line 53:
- cache_pin =
+\verbatim
+cache_pin =
gnc_lookup_boolean_option(N_("Online Banking & Importing"),
"HBCI Remember PIN in memory",
FALSE);
+\endverbatim
The third argument here is the default value in case the lookup
fails. The C function prototypes for lookup of other options can be found in
@@ -45,12 +51,13 @@
Scheme can be seen e.g. in src/report/standard-reports/register.scm
line 556:
+\verbatim
(gnc:option-value (gnc:lookup-global-option "User Info" "User Name"))
+\endverbatim
I.e., the option itself has to be looked up first by
gnc:lookup-global-option (from src/app-utils/prefs.scm), and then the
function gnc:option-value returns the actual value of the option
(defined in src/app-utils/options.scm).
-
-
+*/
Index: loans.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/loans.txt,v
retrieving revision 1.3
retrieving revision 1.3.4.1
diff -Lsrc/doc/loans.txt -Lsrc/doc/loans.txt -u -r1.3 -r1.3.4.1
--- src/doc/loans.txt
+++ src/doc/loans.txt
@@ -1,7 +1,9 @@
-Handling loan repayment in GnuCash::Scheduled Transactions
-------------------------------------------------------------
+/** \page loanhandling Handling loan repayment in GnuCash::Scheduled Transactions
+
July, 2002 - jsled at asychronous.org
+API: \ref SchedXaction
+
Bugs 84892 and 84877 detail a request for a new Loan/Mortgage account type,
and Scheduled Transaction support for loan repayment. While it's debatable
that a new account type is required, there is definitely a need for Scheduled
@@ -16,23 +18,23 @@
We define loan repayment values in the following terms:
-Identifiers:
+Identifiers:\n
P : the original principal. This is the overall principal afforded by the
- loan at the time of it's creation.
+ loan at the time of it's creation.\n
P' : The beginning principal. This is the principal at the time of entry
- into GnuCash.
+ into GnuCash.\n
I : The interest rate associated with the loan. Note that this may change
over time [based on an addition to the Prime rate, for instance], at
various frequencies [yearly, monthly, quarterly...]. Ideally, we can
- use the FreqSpec mechanism to facilitate the interest rate adjustment.
-N : The length of the loan in periods.
-m : The minimum periodic payment.
+ use the FreqSpec mechanism to facilitate the interest rate adjustment.\n
+N : The length of the loan in periods.\n
+m : The minimum periodic payment.\n
n : The current period of the repayment.
-Functions:
+Functions:\n
PMT : Total equal periodic payment, as per Gnumeric/Excel's definitions
- [see end for more detail].
-IPMT : Monthly payment interest portion, ""
+ [see end for more detail].\n
+IPMT : Monthly payment interest portion, ""\n
PPMT : Monthly payment principal portion, ""
[ NOTE: 'PMT(I,N,P) = IPMT(I, n, N, P) + PPMT(I, n, N, P)' for 0 <= n < N ]
@@ -41,6 +43,7 @@
The formula entered into the SX template for a loan may then look like:
Example 1:
+\verbatim
Desc/Memo | Account | Credit | Debit
----------+-----------------------------+----------------+-------------------
Repayment | Assets:Bank:Checking | | =PMT(I,n,N,P)
@@ -49,11 +52,13 @@
PMI | Expenses:Loan_Name:Misc | fixed_amt |
Principal | Liabilities:Loan_Name | =PPMT(I,n,N,P) |
-----------------------------------------------------------------------------
+\endverbatim
Or, in the case where an escrow account is involved [with thanks to warlord
for the review and fixes]:
Example 2:
+\verbatim
Desc/Memo | Account | Credit | Debit
---------------+-----------------------------+----------------+--------------
Repayment | Assets:Bank:Checking | | =PMT(I,n,N,P)
@@ -65,15 +70,20 @@
PMI | Expenses:Loan_Name:Misc | fixed_amt |
Principal | Liabilities:Loan_Name | =PPMT(I,n,N,P) |
| | + pre_payment |
+\endverbatim
+
FreqSpec = 1 month
+\verbatim
-----------------------------------------------------------------------------
Desc/Memo | Account | Credit | Debit
---------------+-----------------------------+----------------+--------------
Insurance | Assets:Loan_Escrow_acct | | insurance_amt
Insurance | Expenses:Home_Insurance | insurance_amt |
-FreqSpec = 1 year
+\endverbatim
+FreqSpec = 1 year
+\verbatim
-----------------------------------------------------------------------------
Desc/Memo | Account | Credit | Debit
---------------+-----------------------------+----------------+--------------
@@ -81,15 +91,13 @@
Taxes | Expenses:Property_Taxes | taxes_amt |
FreqSpec = Quarterly
-----------------------------------------------------------------------------
+\endverbatim
--------------------------
+\section guidpractical Practical questions regarding the implementation of this facility are:
-Practical questions regarding the implementation of this facility are:
-
------
-| 1. The transactions as in Example 2 are not going to be scheduled for the
-| same day; are their values linked at all / do they need to share the
+| 1. The transactions as in Example 2 are not going to be scheduled for the\n
+| same day; are their values linked at all / do they need to share the\n
| same var bindings?
Yes, they would want to be linked. More precisely, the insurance/tax amounts
@@ -138,7 +146,6 @@
and potentially allowing a storage place for such frame data in the future
with less file-versioning headache. This is the option that will be pursued.
-
Another element implicit in the original requirements to support
loans/repayment calculations is implicit variables. These are symbolic names
which can be used and are automagically bound to values. The known implicit
@@ -159,16 +166,15 @@
easier to add support for new functions to the SX code via Scheme.
------
-| 3. How do we deal with periodic [yearly, semi-yearly] updating of various
+| 3. How do we deal with periodic [yearly, semi-yearly] updating of various\n
| "fixed" variables?
Another change in the way variables are used is that some SXes -- especially
loan-repayment -- may involve variables which are not tied to the instance of
the SX, but rather to variables which:
-. are also involved in another SX
-. change with a frequency different than the SX
-. are represented by a relationship to the outside world ["prime + 1.7"]
+- are also involved in another SX
+- change with a frequency different than the SX
+- are represented by a relationship to the outside world ["prime + 1.7"]
A partial fix for this problem is to provide multiple levels of scope for
variable bindings, and expose this to the user by a method of assigning
@@ -189,7 +195,6 @@
now, we punt on this issue, but hopefully will provide enough of a framework
for this to be reasonably added in the future.
-
We define four types of variables supported by this scheme:
implicit : provided only by the system
@@ -210,85 +215,78 @@
created.
e.g.: loan tax amount, loan interest rate
------
-| 4. From where do we get the dollar amount against which to do the [PI]PMT
+| 4. From where do we get the dollar amount against which to do the [PI]PMT\n
| calculation?
The user will specify the parameters of the Loan via some UI... then where
does the data go?
-. KVP data for that account?
-. KVP data for the SX?
-. Do we have a different top-level "Loan" object?
-. Present only in the SX template transactions/variable-frames?
-
+- KVP data for that account?
+- KVP data for the SX?
+- Do we have a different top-level "Loan" object?
+- Present only in the SX template transactions/variable-frames?
I believe that the only location of the data after Druid creation is in the
variable-binding frames and the formulae in the template transactions. The
Druid would thus simply assist the user in creating the following SX-related
structures:
-. SXGroup: Loan Repayment
- . variable_frame
- . P [static]
- . N [static]
- . n [implicit]
- . I [periodic]
- . pmi_amount [periodic]
- . tax_amount [periodic]
- . pre_payment [periodic]
- . insurance_amount [periodic]
- . SX: Payment
- . Bank -> { Escrow,
+- SXGroup: Loan Repayment
+ - variable_frame
+ - P [static]
+ - N [static]
+ - n [implicit]
+ - I [periodic]
+ - pmi_amount [periodic]
+ - tax_amount [periodic]
+ - pre_payment [periodic]
+ - insurance_amount [periodic]
+- SX: Payment
+ - Bank -> { Escrow,
Liability:Loan:Principal,
Expense:Loan:Interest,
Expense:Loan:Insurance }
- . SX: Tax
- . Escrow -> Expense:Tax
- . SX: Insurance
- . Escrow -> Expense:Insurance
+- SX: Tax
+ - Escrow -> Expense:Tax
+- SX: Insurance
+ - Escrow -> Expense:Insurance
---------------------------------------------------
-Questions
+/section loansquestions Questions
-1/ UI - visible should all this machination be to the user? Should they even
+- UI - visible should all this machination be to the user? Should they even
see them as such. The current SX since-last-run UI makes them pretty
visible, and in my estimation it actually helps to make them a bit more
formal and visible. At the same time, it may be overwhelming for the user
to have to create formal variables with weird types like "implicit",
"transient", "static", and "periodic".
---------------------------------------------------
-
-Priorities, Plan
+\section loansplan Priorities, Plan
The above represents an "ideal" set of extensions to the SX framework to
enable multiple "enhancement"-level functionalities. Therefore, the
following is the prioritized schedule, with annotations:
-1. Functions [PMT, [IP]PMT] in exp_parser; implicit variables [n].
-2. [Visual-only] SX grouping
-3. Loan-repayment creation Druid
-4. SX-only static vars
-5. SX-only periodic vars
-6. SX-group vars, var_frames
+-# Functions [PMT, [IP]PMT] in exp_parser; implicit variables [n].
+-# [Visual-only] SX grouping
+-# Loan-repayment creation Druid
+-# SX-only static vars
+-# SX-only periodic vars
+-# SX-group vars, var_frames
After the completion of item 4, the feature can safely be called "finished".
Items 5 and 6 only serve to increase the robustness of the facility and make
the user's life slightly easier, at the cost of making _my_ life harder. :)
---------------------------------------------------
-Reference
--------------------------
+\section loansreference Reference
+
-Other software:
-----------
+\subsection loanssoftware Other software:
Gnumeric supports the following functions WRT payment calculation:
-* PMT( rate, nper, pv [, fv, type] )
+- PMT( rate, nper, pv [, fv, type] )
PMT returns the amount of payment for a loan based on a constant interest
rate and constant payments (ea. payment equal).
@rate : constant interest rate
@@ -296,39 +294,35 @@
@pv : present value
@fv : future value
@type : payment type
- . 0 : end of period
- . 1 : beginning of period
+ - 0 : end of period
+ - 1 : beginning of period
-* IPMT( rate, per, nper, pv, fv, type )
+- IPMT( rate, per, nper, pv, fv, type )
IPMT calculates the amount of a payment of an annuity going towards
interest. Formula for IPMT is:
IPMT(per) = - principal(per-1) * interest_rate
where:
principal(per-1) = amount of the remaining principal from last period.
-* ISPMT( rate, per, nper, pv )
+- ISPMT( rate, per, nper, pv )
ISPMT returns the interest paid on a given period.
If @per < 1 or @per > @nper, returns #NUM! err.
-* PPMT(rate, per, nper, pv [, fv, type] )
+- PPMT(rate, per, nper, pv [, fv, type] )
PPMT calculates the amount of a payment of an annuity going towards
principal.
PPMT(per) = PMT - IPMT(per)
where: PMT is payment
- IPMT is interest for period per
+ - IPMT is interest for period per
-* PV( rate, nper, pmt [, fv, type] )
+- PV( rate, nper, pmt [, fv, type] )
Calculates the present value of an investment
@rate : periodic interest rate
@nper : number of compounding periods
@pmt : payment made each period
@fv : future value
-
---------------------------------------------------
---------------------------------------------------
-
-Day Two:
+/section loanspayment Day Two:
As per warlord's comments, the definition of IPMT needs to be updated to
account for principal pre-payment. IPMT is actually defined by computation
@@ -342,25 +336,27 @@
would need to do something creative about this ... but as it stands, we'll
leave this as an Excercise for the Reader. :)
-
------
-
-Druid thoughts...
+\section loansdruid Druid thoughts...
Page Order:
+
Intro ->
+
Params ->
+
Opts ->
+
Repayment ->
+
[Insurance ->]
+
[PMI ->]
+
[Taxes ->]
-Review/Approval
+Review/Approval
---------------------------------------------------
-| Intro
---------------------------------------------------
+\subsection loansdruidintro Intro
"This is a step-by-step method of creating a loan
repayment setup within GnuCash. In this Druid,
@@ -372,12 +368,10 @@
"If you make a mistake or want to make changes
later, you can edit the created Scheduled
Transactions directly."
---------------------------------------------------
+\subsection loansdruidparams Params
---------------------------------------------------
-| Params
---------------------------------------------------
+\verbatim
Principal : [amount entry]
Actual Principal : [[optional] amount entry]
Interest Rate : [numeric entry] %
@@ -389,12 +383,10 @@
Start Date : [Gnome Date Entry]
Length : [num entry] [years|v]
Remaining : [num entry]
---------------------------------------------------
-
+\endverbatim
---------------------------------------------------
-| Options
---------------------------------------------------
+\section loansoptions Options
+\verbatim
Do you...
[ ] ... utilize an escrow account?
Account: [ acct select |v]
@@ -406,12 +398,10 @@
[ ] Via the Escrow account?
[ ] ... have some other expense not listed above?
[ ] Via the Escrow account?
---------------------------------------------------
+\endverbatim
-
---------------------------------------------------
-| Repayment
---------------------------------------------------
+\section loansrepayment Repayment
+\verbatim
Amount : [ amount entry ]
Assets from : [ account sel |v]
Princiapl to : [ account sel |v]
@@ -421,11 +411,10 @@
Frequency : +- freqspec ----------------+
| .... |
+---------------------------+
---------------------------------------------------
+\endverbatim
---------------------------------------------------
-| Insurance
---------------------------------------------------
+\section loansinsurance Insurance
+\verbataim
Amount : [ amount entry ]
Account : [ account sel |v]
Frequency :
@@ -433,49 +422,42 @@
[ ] Other: +- freqspec ----------------+
| .... |
+---------------------------+
---------------------------------------------------
+\endverbatim
+\section loanstaxes Taxes/PMI/Other
---------------------------------------------------
-| Taxes/PMI/Other
---------------------------------------------------
[ same as Insurance ]
---------------------------------------------------
-===========================================================================
-===========================================================================
+
Options in repayment:
-. loan freq != repayment freq
- . floated
- . not
-
-. Where does over-payment go?
- . where
- . into the escrow account
- . directly applied
- . how
- . towards principal [interest is then re-calculated]
- . towards interest [principal is then re-calculated]
-
-. still to do...
- . expression parser/gnc-exp-parser extensions to handle...
- . ...symbols [account names] into functions
- . ...errors better
- . ...iter/count/implicit vars
- . druid...
- . add ipmt', ppmt' calculations, using above
- . kvp storage of "real" data
- . sx grouping
+- loan freq != repayment freq
+ - floated
+ - not
+
+- Where does over-payment go?
+ - where
+ - into the escrow account
+ - directly applied
+ - how
+ - towards principal [interest is then re-calculated]
+ - towards interest [principal is then re-calculated]
+
+- still to do...
+ - expression parser/gnc-exp-parser extensions to handle...
+ - ...symbols [account names] into functions
+ - ...errors better
+ - ...iter/count/implicit vars
+ - druid...
+ - add ipmt', ppmt' calculations, using above
+ - kvp storage of "real" data
+ - sx grouping
http://www.interest.com/hugh/calc/mort_links.html
+\section loansfeedback Druid Feedback:
-===========================================================================
-===========================================================================
-
-Druid Feedback:
-
+\verbatim
<Wilddev> jsled: <auspex> Wilddev: The labels need colons, mnemonics, and right-alignment.
<Wilddev> <auspex> Wilddev: It may be worthwhile for gnucash to create GtkSpinButton subclasses which show the percent symbol and others within the field.
<Wilddev> <auspex> Wilddev: I don't know how complicated that will be.
@@ -494,29 +476,29 @@
<jsled> Hmm. Okay. The between-transaction period is a frequency editor on the Repayment page.
<Wilddev> <auspex> I'm wondering if "Original Principal" should be a vulgate
such as "Loan Amount"
+\endverbatim
-----------
-Expression changes, round 2
+\section loansexpression Expression changes, round 2
We need the following abilities in order to get mortgage/loan repayment
working:
-. Ability to get the original value of an account
- . [perhaps, ability to reference an external value?]
-. Ability to get the present value of an account
-. Ability to get the current i in an "i-of-N" sequence
+- Ability to get the original value of an account
+ - [perhaps, ability to reference an external value?]
+- Ability to get the present value of an account
+- Ability to get the current i in an "i-of-N" sequence
As well, it'd be nice to have:
-. some sort of signature checking on functions in expressions
-. safe[r] error handling?
+- some sort of signature checking on functions in expressions
+- safe[r] error handling?
We decide that the original/present value of the account should be handled in
scheme, and thus we actually need a way to reference accounts down to the
scheme expressions. We decide to use the Quote symbols to refer to a string
literal. The expression parser should be modified to parse this.
-----------
-
The current 'i' and 'N' are going to be handled by having a list of
predefined variables which the user cannot have access to. For the time
being, this is 'i' and 'N'.
+
+*/
Index: doxygen.cfg.in
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/doxygen.cfg.in,v
retrieving revision 1.2.4.3
retrieving revision 1.2.4.4
diff -Lsrc/doc/doxygen.cfg.in -Lsrc/doc/doxygen.cfg.in -u -r1.2.4.3 -r1.2.4.4
--- src/doc/doxygen.cfg.in
+++ src/doc/doxygen.cfg.in
@@ -300,7 +300,7 @@
# disable (NO) the todo list. This list is created by putting \todo
# commands in the documentation.
-GENERATE_TODOLIST = NO
+GENERATE_TODOLIST = YES
# The GENERATE_TESTLIST tag can be used to enable (YES) or
# disable (NO) the test list. This list is created by putting \test
@@ -400,7 +400,7 @@
# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp
# *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm
-FILE_PATTERNS =
+FILE_PATTERNS = *.c *.h *.txt
# The RECURSIVE tag can be used to turn specify whether or not subdirectories
# should be searched for input files as well. Possible values are YES and NO.
@@ -475,12 +475,12 @@
# Note: To get rid of all source code in the generated output, make sure also
# VERBATIM_HEADERS is set to NO.
-SOURCE_BROWSER = NO
+SOURCE_BROWSER = YES
# Setting the INLINE_SOURCES tag to YES will include the body
# of functions and classes directly in the documentation.
-INLINE_SOURCES = NO
+INLINE_SOURCES = YES
# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct
# doxygen to hide any special comment blocks from generated source code
@@ -492,7 +492,7 @@
# then for each documented function all documented
# functions referencing it will be listed.
-REFERENCED_BY_RELATION = YES
+REFERENCED_BY_RELATION = NO
# If the REFERENCES_RELATION tag is set to YES (the default)
# then for each documented function all documented entities
@@ -882,13 +882,13 @@
# compilation will be performed. Macro expansion can be done in a controlled
# way by setting EXPAND_ONLY_PREDEF to YES.
-MACRO_EXPANSION = NO
+MACRO_EXPANSION = YES
# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
# then the macro expansion is limited to the macros specified with the
# PREDEFINED and EXPAND_AS_PREDEFINED tags.
-EXPAND_ONLY_PREDEF = NO
+EXPAND_ONLY_PREDEF = YES
# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
# in the INCLUDE_PATH (see below) will be search if a #include is found.
@@ -899,7 +899,7 @@
# contain include files that are not input files but should be processed by
# the preprocessor.
-INCLUDE_PATH =
+INCLUDE_PATH = @-top_srcdir-@/src/engine/
# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
# patterns (like *.h and *.hpp) to filter out the header-files in the
@@ -921,7 +921,7 @@
# The macro definition that is found in the sources will be used.
# Use the PREDEFINED tag if you want to use a different macro definition.
-EXPAND_AS_DEFINED =
+EXPAND_AS_DEFINED = DEFINE_ENUM
# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then
# doxygen's preprocessor will remove all function-like macros that are alone
@@ -1114,4 +1114,5 @@
# The SEARCHENGINE tag specifies whether or not a search engine should be
# used. If set to NO the values of all tags below this one will be ignored.
-SEARCHENGINE = NO
+SEARCHENGINE = YES
+
Index: qif.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/qif.txt,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -Lsrc/doc/qif.txt -Lsrc/doc/qif.txt -u -r1.1 -r1.1.2.1
--- src/doc/qif.txt
+++ src/doc/qif.txt
@@ -1,10 +1,13 @@
- The (new new) QIF Importer infrastructure
+/** \page qif QIF importer infrastructure.
+
Derek Atkins <derek at ihtfp.com>
2004-01-07
A work in progress....
-0. Introduction
+API: \ref Import_Export
+
+\section qifintro 0. Introduction
The existing qif importer in src/import-export/qif-import is both hard
to maintain and hard to re-integrate into the shared import
@@ -25,7 +28,7 @@
import infrastructure.
-1. Importer Architecture
+\section qifarch 1. Importer Architecture
The importer is a multi-step, staged system that should implement a
read, parse, convert, combine, filter, finish process. The importer
@@ -51,8 +54,7 @@
questions to ask the user (and how are those responses returned to the
importer)?
-
-2. The Import Process
+\section qifprocess 2. The Import Process
The import process starts when the UI creates a new import context.
All of a single import is performed within that context. The context
@@ -101,8 +103,8 @@
freed.
-3. Importer Data Objects
-
+\section qifobject 3. Importer Data Objects
+\verbatim
QifContext
QifError
QifFile
@@ -113,16 +115,17 @@
+-QifSecurity
+-QifTxn
+-QifInvstTxn
+\endverbatim
-Internal Data Types
+\subsection qifinternal Internal Data Types
QifHandler
QifData
-4. Importer API
-
-QIF Contexts
+\section qifapi 4. Importer API
+\subsection qifcontexts QIF Contexts
+\verbatim
/** Create and destroy an import context */
QifContext qif_context_create(void)
void qif_context_destroy(QifContext ctx)
@@ -135,10 +138,10 @@
* same set of objects within the context.
*/
void qif_context_merge_files(QifContext ctx);
+\endverbatim
-
-QIF Files
-
+\section qiffiles QIF Files
+\verbatim
/**
* Open, read, and minimally parse the QIF file, filename.
* If progress is non-NULL, will call progress with pg_arg and a value from
@@ -166,9 +169,9 @@
* Do we need progress-bar info here?
*/
QifError qif_file_parse(QifFile ctx, gpointer ui_arg)
+\endverbatim
-
-5. Importer State Machine
+\section qifstate 5. Importer State Machine
The state machine has the following structure. Named states (and substates)
must proceed in order. Some states (e.g. state b) have multiple choices.
@@ -192,3 +195,4 @@
f. map qif securities to gnucash commodities
g. duplicate detection with existing gnucash txns
h. transaction matcher (map one-sided txns using Payee/Memo info)
+*/
Index: plugin.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/plugin.txt,v
retrieving revision 1.1
retrieving revision 1.1.14.1
diff -Lsrc/doc/plugin.txt -Lsrc/doc/plugin.txt -u -r1.1 -r1.1.14.1
--- src/doc/plugin.txt
+++ src/doc/plugin.txt
@@ -1,10 +1,11 @@
-Date: Mon, 19 Oct 1998 11:08:53 +0200
-From: Stephan Lichtenauer <s_lichtenauer at muenchen.org>
-To: linas at linas.org
+/** \page plugindesign Plugin design proposal
+
+Date: Mon, 19 Oct 1998 11:08:53 +0200\n
+From: Stephan Lichtenauer <s_lichtenauer at muenchen.org>\n
+To: linas at linas.org\n
Subject: [Fwd: ANNOUNCE version 1.1.20]
-DESIGN PROPOSAL (ROUGH OUTLINE)
------------------------------
+\section pluginoutline DESIGN PROPOSAL (ROUGH OUTLINE)
I thought that there is only one engine that manages runtime data, but
to store and read it it uses the i/o-plugins that handle the data in a very
@@ -15,27 +16,26 @@
through the application. It could work with the CORBA persistence framework if I
remember right and the GNOME VFS.
-Engine
---------
+\subsection pluginengine Engine
Split the existing engine in the following classes that match the existing data
structures:
-- GcAccountGroup
-- GcAccount
-- GcSplit
-- GcTransaction
-- GcEngine
+- GncAccountGroup
+- GncAccount
+- GncSplit
+- GncTransaction
+- GncEngine
These five classes first of all simply use the design already used in the
engine. Additionally I would introduce a class
-- GcRegistry
+- GncRegistry
that is used to store some metadata that is used by e.g. plug ins or the user
interface. Since there is in my eyes need for two different classes of metadata,
-global and account-group related one, I would give GcAccountGroup as well as
-GcEngine a gcGetRegistry method that returns the local and the global registry
+global and account-group related one, I would give GncAccountGroup as well as
+GncEngine a gncGetRegistry method that returns the local and the global registry
object. The registry can store its data in the account database and (global
data) in the config file in the user's root directory. An example for global
metadata of my plugin would be a database of all REUTERS codes of stocks
@@ -43,21 +43,19 @@
save e.g. what codes have been selected to be updated etc. An ui could store
general options (e.g. user preferences) in the global registry and e.g. last
position of windows in the local registry.
-GcEngine could as well be a metaclass since it only has to represent the engine
-as such, with methods like gcReadAccountGroup.
-GcSplit could be an abstract class whose functionality can be implemented
+GncEngine could as well be a metaclass since it only has to represent the engine
+as such, with methods like gncReadAccountGroup.
+GncSplit could be an abstract class whose functionality can be implemented
in derived concrete classes, e.g. for simple money transfers, buy of securities
(which will be further divided in stocks, futures, bonds) etc. Alternatively
-additional
-data could be stored in an extended comment field with every split in MIME format.
-Infrastructure for that is already partially implemented but is (in my eyes) no
-perfectly
-clear OOP design.
+additional data could be stored in an extended comment field with every split in
+MIME format.Infrastructure for that is already partially implemented but is
+(in my eyes) no perfectly clear OOP design.
-One GcSplit subclass is GcComment that can store general data like company
+One GncSplit subclass is GncComment that can store general data like company
statements. Since this could be data that affects more than one account (e.g.
-general economical data), it is stored centralized and the GcComment object in
-the different accounts only point on this data. GcSplit subclasses that
+general economical data), it is stored centralized and the GncComment object in
+the different accounts only point on this data. GncSplit subclasses that
represent any type of securities will have to have additional fields, e.g. to
store maturities, volume (for special price quotes) etc.
@@ -65,18 +63,18 @@
different sources is proposed. I would realize this completely with plug in
objects. So I would introduce
-- GcPlugIn
+- GncPlugIn
to be the base class of all plug ins. How to make plugins independent from ui
toolkits (GTK, QT/KDE), I do not know since they will need an ui in many cases.
-- GcIOPlugIn
+- GncIOPlugIn
is derived from it and will be the base class for all i/o plugins, e.g.
-GcIOXacc, GcIOQif, GcIOSql, GcIOOnlineBanking, GcIOReadWww (yeah, my plugin!)
+GncIOXacc, GncIOQif, GncIOSql, GncIOOnlineBanking, GncIOReadWww (yeah, my plugin!)
etc. Since some of the media is non-persistent, ie it is not sure if you will
-get the data again in the future (e.g. from web pages), GcIOPlugIn has a method
-gcIsPersistentMedia that returns FALSE in such cases. Then the data obtained
+get the data again in the future (e.g. from web pages), GncIOPlugIn has a method
+gncIsPersistentMedia that returns FALSE in such cases. Then the data obtained
from this source can be copied to a persistent media (e.g. the SQL database).
An IO plugin has a limited lifespan and is only used to read/write data from/to
accounts/account groups/splits resp. create these objects as appropriate when
@@ -84,12 +82,12 @@
One example:
You make a bank transfer in your account. The data is written to the
-GcIOOnlineBanking object that uses the WWW-interface of your bank to give the
+GncIOOnlineBanking object that uses the WWW-interface of your bank to give the
data to your bank. Then it reads the state of the transfer (via an online
request to your bank account balance) what will then appear in your account.
-Possibly the GcIOOnlineBanking plugin is not persistent, i.e. you will not get a
+Possibly the GncIOOnlineBanking plugin is not persistent, i.e. you will not get a
full track of all of your transactions of the past via online banking, then the
-data is stored locally (e.g. via GcIOPlugInXacc).
+data is stored locally (e.g. via GncIOPlugInXacc).
One account group so can use many IO plugins at the same to get its data.
Perhaps the IO plugins could be based on the GNOME VFS (virtual file system), if
@@ -101,26 +99,26 @@
quotes or MetaStock data or online banking interfaces that is not that simple;
and it also has to work the other way round. So we need a
-- GcDataMapper
+- GncDataMapper
-class that has at least two methods gcFindAccounts and gcFindSources. Both get a
+class that has at least two methods gncFindAccounts and gncFindSources. Both get a
-- GcMapInfo
+- GncMapInfo
struct as parameter that contains information on how to find the account or the
-source. Both return a vector of GcMapInfos that contain information about
-the matches. When you call gcFindAccounts you normally fill the fields with data
+source. Both return a vector of GncMapInfos that contain information about
+the matches. When you call gncFindAccounts you normally fill the fields with data
like the banking account number, REUTERS codes etc. and the method returns a
list of accounts that could match. If there is more or less then one account the
user could be prompted to help; the data obtained from a succesful match will be
-stored in the registry by the GcDataMapper so it can be used in the future and
+stored in the registry by the GncDataMapper so it can be used in the future and
to do reverse mapping. Reverse mapping is what gcFindSources is for. There you
-fill the GcMapInfo with the things like accountId, account name, comments etc.
-and the GcDataMapper tries to find (with the help of its registry if there is
+fill the GncMapInfo with the things like accountId, account name, comments etc.
+and the GncDataMapper tries to find (with the help of its registry if there is
already some data available) some sources (e.g. quotes web pages, online banking
interfaces, company web pages etc.) and the IO plugins for this account. Again
user help could be involved the first time or later again if the user wants to
-modify the matches. How to actually do the mapping is job of the GcDataMapper,
+modify the matches. How to actually do the mapping is job of the GncDataMapper,
it could use regexp libraries etc. The most simple implementation would to be a
simple user query where the user has to find the matches.
@@ -145,7 +143,7 @@
A second type would be the
-- GcReportPlugIn
+- GncReportPlugIn
that is used for report generation/data analyzing. A report interface that
generates HTML code (that can then be translated to SGML, PS, TeX etc. via an
@@ -164,34 +162,32 @@
repository.
Report plugins first of all have to have a kind of
-string gcMakeReport(string params);
-method that gets the parameters stored in the HTML command (e.g. accoundId, data
+\verbatim
+string gncMakeReport(string params);
+\endverbatim
+method that gets the parameters stored in the HTML command (e.g. accountId, data
range, graph type etc.), this has to be obtained through dialogs that are
maintained by the plugin itself, this is why I have said I do not know how to
make plugins toolkit-independent) and returns the generated HTML-code. They
have to have a second method to display this dialog and a
general plug-in mechanism that allows to find and load GnuCash corba plugins;
-this of course is already introduced in the GcPlugIn class.
-If plugins are chainable the gcMakeReport has to be modified/extended that they
+this of course is already introduced in the GncPlugIn class.
+If plugins are chainable the gncMakeReport has to be modified/extended that they
get can get an account(-group) as input and return a new, modified
account(-group) that could be then input for a second plugin (eg the one that
finally creates the HTML-code). A usage for that could be a filter that eliminates
noise in stock quotes and so generates new quotes that are then used as input to a
-Chaikin
-Oscillator plugin.
-
+Chaikin Oscillator plugin.
I hope it is in line with all the other proposals (e.g. scripting, budget engine
-etc).
-I did not mention script languages in this document, I think it should be
+etc). I did not mention script languages in this document, I think it should be
possible to access the engine via CORBA bindings for all these languages and to
even create new classes or derive them, so writing plugins should be easily
possible with compiled languages as well as with interpreted ones.
-
Stephan Lichtenauer
Rassosiedlung 25
82284 Grafrath
s_lichtenauer at muenchen.org
-
+*/
Index: g2-architecture.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/Attic/g2-architecture.txt,v
retrieving revision 1.1.2.2
retrieving revision 1.1.2.3
diff -Lsrc/doc/g2-architecture.txt -Lsrc/doc/g2-architecture.txt -u -r1.1.2.2 -r1.1.2.3
--- src/doc/g2-architecture.txt
+++ src/doc/g2-architecture.txt
@@ -1,13 +1,12 @@
-0) Naming
----------
+/** \page gnome2 GnuCash Gnome2 architecture
-g1 - The gtk1 and gnome1 libraries.
-g2 - The gtk2 and gnome2 libraries.
+\section gnome2names Naming
+g1 - The gtk1 and gnome1 libraries.
+g2 - The gtk2 and gnome2 libraries.
-1) GTK2 Primer
---------------
+\section gnome2primer GTK2 Primer
In gtk2, an "action" is a g_object that represents some action that
the user might want to perform. This object could represent opening a
@@ -45,10 +44,7 @@
g_object and gtk_object. You must use one function set or the other
for any given item.
-
-
-2) Windowing Architecture
--------------------------
+\section gnome2windows Windowing Architecture
In the gtk1/gnome1 (hereafter g1) version of Gnucash, the windowing
was based on the "Multiple Document Interface" of g1. This code was
@@ -66,9 +62,9 @@
The first level of this architecture is an object representing a
"pluggable" window. This object is responsible for:
- 1) the window itself
- 2) providing a framework for plugins
- 3) providing a base set of menus (and actions)
+-# the window itself
+-# providing a framework for plugins
+-# providing a base set of menus (and actions)
Plugins can be one of two types. The first type is simply called a
"plugin" (e.g. gnc-plugin-register.c) and is used to add functionality
@@ -81,10 +77,9 @@
plugin page must also provide a standard set of functions to interact
with the plugin manager code.
+\section gnome2model Model/View Architecture
-
-3) Model/View Architecture
---------------------------
+API: \ref GuiTreeModel
As mentioned above, the ctree widget has been deprecated in g2. Some
parts of gnucash have been converted to the new style using either a
@@ -148,13 +143,14 @@
the accounts the user may select for the opening balance to an account
that has the same currency as the account being created.
+\section gnome2ref References
-
-
-References
-----------
http://developer.gnome.org/dotplan/porting/index.html
http://developer.gnome.org/doc/API/2.0/glib/index.html
+
http://developer.gnome.org/doc/API/2.0/gobject/index.html
+
http://developer.gnome.org/doc/API/2.0/gtk/index.html
+
+*/
Index: books.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/books.txt,v
retrieving revision 1.6.4.4
retrieving revision 1.6.4.5
diff -Lsrc/doc/books.txt -Lsrc/doc/books.txt -u -r1.6.4.4 -r1.6.4.5
--- src/doc/books.txt
+++ src/doc/books.txt
@@ -1,11 +1,11 @@
+/** \page bookperiods Books / Accounting Periods
- Books / Accounting Periods
- --------------------------
- Implementation Overview
+API: \ref Book\n
- Linas Vepstas <linas at linas.org> December 2001
- Last Updated August 2003
+\section periodsintro Implementation Overview
+ Linas Vepstas <linas at linas.org> December 2001
+ Last Updated August 2003
A top, unimplemented request for GnuCash is the ability to 'close
the books', that is, to add support for 'accounting periods'.
@@ -13,8 +13,8 @@
and a GUI is partially finished. This file reviews the
implementation design choices and the current design status.
-Definition
-----------
+\subsection periodsdefines Definition
+
An accounting period or 'book' is a set of accounts and transactions
that, once closed, must never be modified again. Books are typically
closed once a quarter, or once a year. Generating a report from a
@@ -34,16 +34,19 @@
gains, taxes, etc. depend on the dates of the originating
transaction. See 'lots.txt' for details.
+API: \ref Lot
+
+\subsection periodsrequired Requirements
-Requirements
-------------
Must have good performance (large data files usually mean poor performance).
Use the idea of 'books' to prevent file bloat. Must have access to
historical data. Must be able to create bar-charts, graphs, reports
of multi-year data (i.e. create reports spanning multiple books).
-Status
-------
+\ref Period
+
+\subsection periodsstatus Status
+
The top-level structure that holds references to all of the data in
a book is implemented in src/engine/qofbook.c. The routines to
split one book into two, automatically setting account balances,
@@ -52,13 +55,14 @@
below. The actual implementation is not yet complete, see
"Implementation Notes" at bottom for the current status.
+\section periodssolution Possible Solutions
+
+API: \ref Query
-Possible Solutions
-------------------
Listed in order from worst to best:
-Plan F:
--------
+\subsection periodsdelete Plan F:
+
Simply 'delete' old transactions, and adjust the equity to make up for
this. More specifically: Split one file into two, with only 'old'
transactions in one, and only 'new' transactions in the other.
@@ -91,37 +95,40 @@
all 'old' transactions have been cleared/reconciled. But that might be
a bit much for non-bank accounts).
-Pros & Cons of plan F:
-----------------------
-pro: simple. The simplest option.
-pro: truncated file loads much faster
-pro: old/irrelevant accounts can be safely deleted from newest file
+API: \ref Transaction
+
+\subsection periodsf Pros & Cons of plan F:
+
+- pro: simple. The simplest option.
+- pro: truncated file loads much faster
+- pro: old/irrelevant accounts can be safely deleted from newest file
(while still being preserved in old files).
-con: impossible to generate 5 year reports, multi-year graphs. This
+
+- con: impossible to generate 5 year reports, multi-year graphs. This
would really hurt, esp, when tracking stocks/mutual funds/retirement
accounts over a number of years.
I think this last one is the Achilles heel, the torpedo in the rudder
that sinks the boat.
+\subsection periodspland Plan D
-Plan D:
--------
As above, but instead of deleting, add a kvp to each transaction stating
'/book/closed-on=12.31.2000'. Then modify the default query for the
registers so that the only displayed transactions are those that are *not*
part of a closed book. Modify the Query GUI dialog to add 'book' as
a query parameter.
-pro: easy access to historical record
-con: slow loads; file size not reduced.
-con: dealing with opening balances, equity, is icky.
-con: can't delete/hide old/stale accounts.
+- pro: easy access to historical record
+
+- con: slow loads; file size not reduced.
+- con: dealing with opening balances, equity, is icky.
+- con: can't delete/hide old/stale accounts.
We move on....
-Plan C:
--------
+\subsection periodsplanc Plan C
+
As in plan F, but instead of creating two books, clone the account tree
into two: 'old' and 'new'. The old and new accounts are identical,
except that they get different guid's. Every account in the old
@@ -157,22 +164,22 @@
or it searches new accounts *and* their corresponding 'old' copies.
(There are three ways to deal with this account continuity issue:
- \\ don't deal with it in query.c: force various GUI dialogs to explicitly
+- don't deal with it in query.c: force various GUI dialogs to explicitly
formulate queries involving the /book/previous-guid string.
but this gets messy in the GUI's. May lead to excess cut-n-paste
of similar code between different GUI's.
- \\ 'hide' the distinction between 'old' and 'new' in query.c:
+- 'hide' the distinction between 'old' and 'new' in query.c:
the users of query.c need only to specify a boolean flag: search
closed books: yes/no. However, this is conceptually ugly, and
prevents query from doing low-level queries on specific
books.
- \\ create query utility wrapper/pre-processor that takes a query,
+- create query utility wrapper/pre-processor that takes a query,
and then modifies it to search through closed books as well.
This is the 'cleanest' solution. ??
- \\ All these are delicate, and need a little more thought and
+- All these are delicate, and need a little more thought and
exploration. Goal is to simplify queries, not burden the system
with cryptic, complex code.
)
@@ -185,18 +192,18 @@
asset-value-over-time-bar-chart always looks at closed books.
-pro: safer than plan F, since we really can enforce the 'you aren't
+- pro: safer than plan F, since we really can enforce the 'you aren't
allowed to edit closed books' rule.
-pro: solves the old-account/new-account problem, since new accounts
+- pro: solves the old-account/new-account problem, since new accounts
can be edited/deleted without damaging old account.
-pro: solves the historical reporting problem.
+- pro: solves the historical reporting problem.
-con: queries are potentially slow, loading of file is potentially slow.
+- con: queries are potentially slow, loading of file is potentially slow.
But now we have enough info to propose the final solution:
-Plan A:
--------
+\subsection periodsplana Plan A:
+
The kvp markup of plan C coupled to the multi-file solution of plan F.
In initial startup of GnuCash, only the 'current' book is loaded.
If user asks for a report that requires data from old books, then
@@ -206,9 +213,9 @@
needs to somehow know the filenames of the old books. I recommend
against storing the books as different sections of one file, for
many reasons:
- % risk of corruption of old books
- % bloated file size
- % the single-file solution would need to invent a 'directory' so
+- risk of corruption of old books
+- bloated file size
+- the single-file solution would need to invent a 'directory' so
that the location of the old books in the file can be quickly
found and lseek()'ed or mmap()'ed. But why invent a directory?
Unix already provides directories!
@@ -222,24 +229,24 @@
every book gets not only a unique guid, and also stores some
meta-information (as book-level kvp's):
-/book/title=some-user-supplied-name
-/book/notes=user-supplied-descriptive-comments
-/book/start-date=xxx
-/book/end-date=xxx
-/book/previous-book-guids=(list 0xa 0xb 0xc)
+/book/title=some-user-supplied-name\n
+/book/notes=user-supplied-descriptive-comments\n
+/book/start-date=xxx\n
+/book/end-date=xxx\n
+/book/previous-book-guids=(list 0xa 0xb 0xc)\n
/book/accounting-period=enum {none, week, month, quarter, trimester, year}
-Pro's & Con's
--------------
+\subsection periodsaprocon Pro's & Con's
+
I am not aware of any con's to plan A at this point.
-Implementation Overview
-----------------------
+\section periodsoverview Implementation Overview
+
Plan A has been implemented in the engine. To quickly summarize:
--- Partitioning involves splitting one book into two, called the
+- Partitioning involves splitting one book into two, called the
"old, closing book", and the "current open book".
--- Accounts are copied between old and new books. One of the copies
+- Accounts are copied between old and new books. One of the copies
is issued new GUID's, but the rest of the account data is copied.
KVP pairs are then added so that each copy points at the other,
and can thus be easily found. The "gemini" KVP keyword is used.
@@ -248,57 +255,56 @@
The transaction is a transfer from equity. An equity account is
created automagically, if needed.
--- Transactions. Transactions are partitioned, and end up either
+- Transactions. Transactions are partitioned, and end up either
in the old or the new book. Splits move with transactions.
Note that some transactions, associated with open lots, may be
kept in the new book (See below).
--- Lots. If a transaction has a split in an open lot, then that
+- Lots. If a transaction has a split in an open lot, then that
transaction is not moved to the closed book. It needs to stay
with the open book. If a lot is closed, and all of the other
lots associated with all of the transactions in this lot are
also closed, then the lot may be moved to the closed book
(and all of the other associated lots must then also be moved).
--- Prices. Prices are sorted into the new and old books according
+- Prices. Prices are sorted into the new and old books according
to the date on the price.
--- Scheduled transactions/recurring transactions. These are left
+- Scheduled transactions/recurring transactions. These are left
in the new book, untouched. They are not copied into the old
book, and no trace of their existence is left in the old book.
--- Business Objects. Not implemented.
+- Business Objects. Not implemented.
+\section periodsnotes Implementation Notes
-Implementation Notes:
----------------------
--- src/engine/Period.[ch]
+- src/engine/Period.[ch]
Implements the main logic to split one book into two, and populate
it with the appropriate keys, markup, etc. and to carry balances
forward, etc.
- src/engine/kvp-util.[ch]
+- src/engine/kvp-util.[ch]
Gemini code: code which allows 'linked lists' to be created, using
nothing but kvp trees and guid's. These links are used to identify
peer accounts/ peer transactions, etc.
- src/engine/gnc-lot.[ch]
+- src/engine/gnc-lot.[ch]
Implements accounting Lots.
- src/engine/Scrub2.[ch]
+- src/engine/Scrub2.[ch]
Implements simple FIFO for lots. Data is scrubbed with respect to
this FIFO before the books are closed. Commodity accounts (e.g.
stock accounts) must have a coherent Lots structure before books
can be closed. The scrubber makes sure there's nothing hanging
out.
- src/gnome/druid-acct-period.[ch]
+- src/gnome/druid-acct-period.[ch]
Implements a druid interface to allow user to specify book closing
dates, add a title and notes to a book, and walk through the process.
Uses FreqSpec.[ch] and the widget in gnc-frequency.[ch] to allow
the user to specify the frequency of book closings.
--- The Postgres backend has been modified to support multiple books.
+- The Postgres backend has been modified to support multiple books.
All books are stored in the same database; there is no performance
penalty for storing all books together in the same SQL database,
because they can be easily picked apart by an appropriate SQL query.
@@ -312,14 +318,14 @@
However, an SQL admin, if they were desperate to trim the DB size,
could DELETE FROM * WHERE bookguid='asdfasdfasdf';
--- The XML-file backend can store multiple books in one file. There
+- The XML-file backend can store multiple books in one file. There
is currently minimal support for writing out multiple books,
one per file (this enables faster load, by not loading old books).
There is currently no support for loading multiple books from multiple
files.
-ANNOUNCE: Book Closing Beta 2
------------------------------
+\section periodsannounce ANNOUNCE: Book Closing Beta 2
+
Books AKA Accounting Periods can now be closed by going to the 'Action'
menu on the main window, and selecting 'close books'. This will popup
a druid that will allow you to select closing dates. Books are closed
@@ -343,103 +349,96 @@
The old data will be in separate files, and there is currently no
way to load several files at once.
+\section periodsissues Open Issues/Questions that Need Discussion:
-Open Issues/Questions that Need Discussion:
--------------------------------------------
-*) How to handle business objects? e.g. vendors, customers should be
+- How to handle business objects? e.g. vendors, customers should be
copied into both old and new books. But invoices should be in one
or the other. Need to document which is which.
Copy:
customer -- ok, has guid, has for-each
- employee
-
+ employee\n
No-op:
address -- do nothing
-*) Discussion Q: What should the naming convention be for the different
+- Discussion Q: What should the naming convention be for the different
books? When the XML file backend is used, different books need to be
stored as different files (in order to avoid the performance
- penalty of a large file load). Currently, what's implemented is
-
- book-1dc750aa3e6fd045c13ac8afb1a9ac03-my-gnucash-file.xac.gml
-
+ penalty of a large file load). Currently, what's implemented is\n
+ book-1dc750aa3e6fd045c13ac8afb1a9ac03-my-gnucash-file.xac.gml\n
where the number is the GUID of the closed book (needed to be able to
quickly find the book/file) and 'my-gnucash-file.xac' is the name of
- the original file whose books were closed.
-
+ the original file whose books were closed.\n
Need to change the name to include the word "archive".
-*) Discussion Q: When saving books, make the book title part of the
+- Discussion Q: When saving books, make the book title part of the
book name (user convenience).
-*) Should closed books be allowed to have unreconciled transactions?
+- Should closed books be allowed to have unreconciled transactions?
Answer: probably. Should there be a warning?
+\section periodstodo Open Issues / ToDo
-Open Issues / ToDo
-------------------
-*) Change GUI to allow user to specify a default equity account
+- Change GUI to allow user to specify a default equity account
for dealing with opening balances. Should be done with kvp markup.
-*) Fix crash when exiting gnucash after closing books.
+- Fix crash when exiting gnucash after closing books.
-*) The filename of the old, closed books should probably be saved
+- The filename of the old, closed books should probably be saved
in the KVP tree of the current open book. This need be done only
from the file backend.
-*) Need to mark closed book as unalterable, and respect that markup.
+- Need to mark closed book as unalterable, and respect that markup.
I think there's a 'closed' flag in the book, but I don't think its
respected.
-*) The book closing GUI (druid-acct-period.c) needs to save/restore
+- The book closing GUI (druid-acct-period.c) needs to save/restore
period end date (the FreqSpec) to KVP on open book. This would be
easy once we have a freq-spec-to-kvp and freq-spec-from-kvp routines.
-*) Handling of lots in book closing is implemented but is poorly tested.
+- Handling of lots in book closing is implemented but is poorly tested.
Need to write test cases. Also test cases for prices in book
closing.
-*) price-saving in the SQL backend is probably borken, its certainly
+- price-saving in the SQL backend is probably borken, its certainly
untested. Need to remove old deprecated price-lookup mechanism,
and replace w/ qofquery.
-*) Need to provide for loading of closed books, because this is needed
+- Need to provide for loading of closed books, because this is needed
for reports.
-*) 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....
-*) Have some way of remembering the quickfill text from older books.
+- Have some way of remembering the quickfill text from older books.
-*) Possibly neat idea:
+- Possibly neat idea:
Book closing, as currently implemented in the GUI, is driven entirely
by the date-posted. There is no (planned) interface to allow you to
exclude some certain transactions from a particular closing (although
it would be 'easy' to add this: right before I close a book, I have a
list of transactions which can be added to/removed from).
-*) add 13-period support to FreqSpec and the FreqSpec widget.
+- add 13-period support to FreqSpec and the FreqSpec widget.
e.g. from the mailing list:
One of the calendars my company uses is like this:
13 periods
1st period begins jan 1st, partial first week plus 4 weeks.
2nd - 13th period begins on a sunday every four weeks.
- 13th period - 4th week may be less than full week because it ends on 12/31.
-
- For 2003:
- 01. 01/01 - 02/01
- 02. 02/02 - 03/01
- 03. 03/02 - 03/29
- 04. 03/30 - 04/26
- 05. 04/27 - 05/24
- 06. 05/25 - 06/21
- 07. 06/22 - 07/19
- 08. 07/20 - 08/16
- 09. 08/17 - 09/13
- 10. 09/14 - 10/11
- 11. 10/12 - 11/08
- 12. 11/09 - 12/06
- 13. 12/07 - 12/31
+ 13th period - 4th week may be less than full week because it ends on 12/31.\n
+ For 2003:\n
+ 01. 01/01 - 02/01\n
+ 02. 02/02 - 03/01\n
+ 03. 03/02 - 03/29\n
+ 04. 03/30 - 04/26\n
+ 05. 04/27 - 05/24\n
+ 06. 05/25 - 06/21\n
+ 07. 06/22 - 07/19\n
+ 08. 07/20 - 08/16\n
+ 09. 08/17 - 09/13\n
+ 10. 09/14 - 10/11\n
+ 11. 10/12 - 11/08\n
+ 12. 11/09 - 12/06\n
+ 13. 12/07 - 12/31\n
-
+*/
=========================== end of file ========================
Index: budget.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/budget.txt,v
retrieving revision 1.1
retrieving revision 1.1.14.1
diff -Lsrc/doc/budget.txt -Lsrc/doc/budget.txt -u -r1.1 -r1.1.14.1
--- src/doc/budget.txt
+++ src/doc/budget.txt
@@ -1,12 +1,12 @@
+/** \page budgetplan Some Thoughts about GnuCash Budgeting
-
-Some Thoughts about GnuCash Budgeting
+API: \ref Budget
Bob Drzyzgula
18-April-1998
-Abstract
+\section budgetabstract Abstract
At this point, this document contains my personal thoughts about possible
design criteria for a budgeting engine in GnuCash. These should not
@@ -17,29 +17,27 @@
one might do this, and I hope that this document will serve to continue
the discussion that began on the GnuCash/Xacc mailing list.
-\tableofcontents
+\section bugettoc tableofcontents
-1 Definitions
+\subsection budgetdefines Definitions
As with any design paper, we'll need a few definitions. I'll try to
stick as close to possible to the Xacc usage of these terms, but I'm
not intimately familiar with the code, so I may have made some errors
here.
-Journal A journal is a simply a list of transactions with minimal
+- Journal A journal is a simply a list of transactions with minimal
characterization. For the purposes of this paper, the journal is
defined to include only transactions that have already occurred,
i.e., expected or up-coming expenses would not appear in the journal.
-
-Calendar For the purposes of this paper, the calendar as a list of
+- Calendar For the purposes of this paper, the calendar as a list of
fully-defined future transactions, organized by date. A transaction
would only appear in the calendar if there was a low likelihood
that it would change. Future transactions that would only change
by surprise (e.g. the cable TV bill) could appear in the calendar,
but utility bills such as from the natural gas company would appear
in the calendar only after receipt.
-
-Template A template is in effect a partially defined transaction,
+- Template A template is in effect a partially defined transaction,
possibly containing constraints. For example, one might have a template
that would identify the price, payee, description, asset account
and expense account (but not the date) for buying a Value Meal #4
@@ -56,13 +54,11 @@
could be extremely useful in making projections. Quicken, of course,
has similar things called ``memorized transactions,'' but Quicken
gives less control over their creation, meaning and use.
-
-Schedule The schedule is a supplement to the calendar that contains
+- Schedule The schedule is a supplement to the calendar that contains
only dated references to templates, which could be further narrowed
as part of the reference, e.g. an undated template could be given
a date but not a firm value when referenced from the schedule.
-
-Ledger The ledger is in effect documentation of the journal, in that
+- Ledger The ledger is in effect documentation of the journal, in that
it describes the meaning of the transactions with respect to the
balances in the various accounts. In Xacc, this appears also to
be known as the register. It isn't clear to me that Xacc maintans
@@ -71,8 +67,7 @@
but it is less clear that one would want to include the template
references from the schedule directly in the ledger; it may make
more sense for the schedule to be a ledger unto itself.
-
-Budget A budget is an allocation of monetary flows. As funds enter
+- Budget A budget is an allocation of monetary flows. As funds enter
the system through the income accounts, they must be transferred
to other accounts; a direct deposit would be a transfer to an asset
account, a loan payment through payroll deduction a transfer to
@@ -100,11 +95,11 @@
monthly or per-four-weeks. The former might be referred to as ``budgeting
on a monthly basis.''
-2 Documenting the Budget
+\subsection budgetdocs Documenting the Budget
One possible way to document a budget might be as a classic ``input-ouput
table''. Consider the following table:
-
+\verbatim
+---------+----------+---------+-----+------+------+-----+------+------+
| | Checking | Savings | MMA | Cash | Visa | Tax | Food | Rent |
+---------+----------+---------+-----+------+------+-----+------+------+
@@ -123,7 +118,7 @@
+---------+----------+---------+-----+------+------+-----+------+------+
|Interest | | 2 | 3 | | | | | |
+---------+----------+---------+-----+------+------+-----+------+------+
-
+\endverbatim
The first five data columns and the first five data rows have the same
names. These are the asset and liability accounts. The last three
@@ -131,22 +126,20 @@
accounts (When I learn a little more SGML I'll try to make the table
a little more readable). Notice:
-* If you sum across the income rows, you obtain the total income for
+- If you sum across the income rows, you obtain the total income for
each account: $25 from paychecks and $5 from interest, for a total
of $30. If you sum down the expense rows, you obtain the total expenses
for each account: $5 for taxes, $13 for food, and $5 for rent (OK,
so we eat a lot). Just looking at these two figures, we can immediately
see that we expect to make $30 and spend $23 of it.
-
-* The sense of each amount is positive from the row account to the
+- The sense of each amount is positive from the row account to the
column account. Thus, $20 of pay is direct-deposited to the checking
account, and the remaining $5 is withheld for taxes. $1 is transferred
from the savings account to the money market account. We plan to
use the Visa card to buy $7 worth of food and to take a $8 cash
advance. We also plan to pay Visa bills totalling $3 from the checking
account.
-
-* If you sum down an asset/liability column, you will obtain the total
+- If you sum down an asset/liability column, you will obtain the total
amount we expect to add to that account (e.g. $6 added to the MMA,
$20 added to checking, $3 to Visa). If you sum across an asset/liability
row, you will obtain the total amount we expect to remove from that
@@ -156,11 +149,10 @@
in that account for the budget period. Thus, we expect checking
to be a wash, the MMA to grow by $6, and to go $12 further in the
hole on our Visa card.
-
-* Again, what is documented here is the planned account-to-account
+- Again, what is documented here is the planned account-to-account
flow across the entire period, not individual transactions.
-3 Contributing Data
+\subsection budgetcontrib Contributing Data
(to be done)
================================================================
@@ -168,15 +160,14 @@
Where I'm headed for the rest of it is this:
- * I expect to point out that the Journal, Calendar and
+- I expect to point out that the Journal, Calendar and
Ledger as I have described them are only tangentially
related to the budget. They are the emperical data and
the Budget and the Schedule are the models. The goal
would be to have an engine that would allow one to
measure the deviation of the emperical data from
the model in various ways.
-
- * I expect to talk about the task of generating both
+- I expect to talk about the task of generating both
the schedule and the budget. When one prepares this
stuff, one usually has a rather diverse collection of
data to work with. Bi-weekly paychecks, monthly
@@ -188,8 +179,7 @@
I expect to do this by preparing projected transactions
as "templates", and then specifying a time series of
instantiations of the templates.
-
- * I expect to describe a design for a sort of OO
+- I expect to describe a design for a sort of OO
time series engine, where "time series" is a class.
Instances of "time series" will have begin dates,
end dates, frequencies, and the data series itself.
@@ -198,8 +188,7 @@
to commensurate frequencies before combination. Thus,
explicit conversion functions, say "monthly_to_daily"
will need to be defined.
-
- * Once these pieces are in place, then one should be
+- Once these pieces are in place, then one should be
able to use the time series engine to digest the
scraps of paper with scribbles saying "Katie's lunch,
$2.30 every Monday through Thursday except only
@@ -208,8 +197,7 @@
still needs milk" into something usable as a
budget -or- as a schedule (these being two seperate
outputs).
-
- * While I expect that such an engine would be extremely
+- While I expect that such an engine would be extremely
useful for about 80% of the data that would go into
a budget, there will of course be other data for which
this would be overkill or cumbersome. Like "$85 each
@@ -223,16 +211,15 @@
it should not, however, be implemented as hand edits to the
draft table coming out of the time series engine,
because one will want to be able to iterate on this.
-
- * Nonetheless, it probably remains true that users
+- Nonetheless, it probably remains true that users
would wish to take the final budget output of all this
automated stuff, and hack it up into something
that somehow pleases them better. Thus it probably
*does* make sense to allow hand edits at the final
stage, and/or to simply enter an entire budget by
hand if that is what you want to do.
-
- * So far, I don't see any simple way to implement
+- So far, I don't see any simple way to implement
something like Quicken's SuperCategories. Maybe this
is related to why it works so poorly in Quicken. :-)
+*/
Index: currencies.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/currencies.txt,v
retrieving revision 1.1
retrieving revision 1.1.8.1
diff -Lsrc/doc/currencies.txt -Lsrc/doc/currencies.txt -u -r1.1 -r1.1.8.1
--- src/doc/currencies.txt
+++ src/doc/currencies.txt
@@ -1,3 +1,7 @@
+/** \page currencies Currency Issues
+
+API: \ref Commodity
+
From Bill Gribble <grib at billgribble.com>
Tue, 3 Oct 2000 11:09:54 -0500
@@ -10,15 +14,15 @@
I think it's just a "feature" of some particular solutions that they
are separable.
- - we want to eliminate the need for currency trading accounts. From
+- we want to eliminate the need for currency trading accounts. From
a user interaction perspective, this means we need to allow
transfers directly between accounts denominated in different
commodities.
- - we want transactions to have clear and unambiguous balancing
+- we want transactions to have clear and unambiguous balancing
semantics.
- - we want to store the actual amounts of commodities involved
+- we want to store the actual amounts of commodities involved
transactions rather than price and quantity.
- - we want to be able to globally check and display the terms of the
+- we want to be able to globally check and display the terms of the
accounting equation (and all account balances) in a
user-selectable functional currency.
@@ -26,12 +30,12 @@
Basically I'm just agreeing with your last suggestion, Dave; Rob and I
hammered on it on a white board and weren't able to poke any holes.
- - Eliminate the 'currency' from the Account structure. Add a
+- Eliminate the 'currency' from the Account structure. Add a
'currency' to the Transaction structure. Each transaction's
'currency' is by definition the balancing common currency for the
splits in that transaction.
- - Eliminate the 'share price' field from the Split structure and
+- Eliminate the 'share price' field from the Split structure and
replace it with a 'value' field. The 'value' is a translation of
the Split's 'damount' (which is the amount of the Account's
security involved) into the Transaction's balancing currency.
@@ -50,3 +54,5 @@
price database. There has been discussion about moving to a
report-based main window; if that were to be the case, we could make
the accounting equation readily visible to the user.
+
+*/
Index: lots.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/lots.txt,v
retrieving revision 1.8.4.5
retrieving revision 1.8.4.6
diff -Lsrc/doc/lots.txt -Lsrc/doc/lots.txt -u -r1.8.4.5 -r1.8.4.6
--- src/doc/lots.txt
+++ src/doc/lots.txt
@@ -1,11 +1,9 @@
-
- Lots
- ====
- Architecture & Implementation Overview
+/** \page lotsoverview Lots Architecture & Implementation Overview
Linas Vepstas <linas at linas.org>
Last Revised May 2004
+API \ref Lot
One often needs to know that the item 'bought' in one transaction
is the same one as the item 'sold' in a different transaction.
@@ -23,8 +21,8 @@
creation of the lot helps determine when a bill is due, when depreciation
starts, or the tax rate for capital gains on a stock market investment.
-Definition
-==========
+\section lotsdefines Definition
+
In GnuCash, a 'lot' will consist of a set of splits identified with
a unique lot number. Any given split can belong to one lot and one
lot only. All splits in a lot must also belong to the same account.
@@ -36,14 +34,13 @@
forward into the current open book; closed lots are left behind in the
book in which they were closed.
+\section How Lots Are Used
-How Lots Are Used
-=================
The following sections review how lots are used to implement various
accounting devices, and some of the related issues.
-Billing:
---------
+\subsection Billing
+
Tracking lots is the 'definition' of A/R and A/P. You want to be able
to say that this bill is 120 days old, and its balance has been partly
paid off; and you want to be able to do this whether or not there are
@@ -55,15 +52,15 @@
information about bills, such as a due date or payment terms, should
be stored as kvp values associated with the lot.
-Billing Example:
-----------------
+\subsection Billing Example
+
Normally, there is a one-to-one correspondence between bills and
lots: there is one lot per bill, and one bill per lot. (Note: this
is not how gnucash invoices are currently implemented; this is a
proposed implementation.)
For example:
-
+\verbatim
invoice #258 customer XXX
Order placed 20 December 2001
quant (10) gallons paint $10/each $100
@@ -75,6 +72,7 @@
Payment received 24 january 2002 $50 Balance Due: $88.27
Payment received 13 february 2002 $60 Balance Due: $28.27
Payment received 18 march 2002 $28.27 PAID IN FULL
+\endverbatim
In this example, the lot encompasses four transactions, dated
December, January, February and March. The December transaction
@@ -93,9 +91,8 @@
of a lot in the "Paintbrush Inventory" account. These lots should
not be confused with the invoice lot.
+\subsection lotsinventory Inventory
-Inventory:
-----------
The correct way of handling inventory under GnuCash is to have a
separate account for each widget type. The account balance represents
how many widgets there are in the warehouse. Lots offer an additional
@@ -115,9 +112,8 @@
not listing them in account lists, and providing an alternate
management GUI.
+\subsection Capital Gains
-Capital Gains:
---------------
In the United States, gains on stock investments are taxed at different
rates depending on how long they were held before being sold. By using
lots with an investment account, it becomes easy to track when any given
@@ -129,21 +125,25 @@
For example, the user may have conceptually made the following
transactions:
+\verbatim
> Date Desc Buy Sell Price Value
> 18/1/01 XCORP 500 $10.00 $5000.00
> 21/3/01 XCORP 500 $12.00 $6000.00
> 14/7/02 XCORP 750 $20.00 $15000.00
+\endverbatim
However, the two buy transactions create different lots (because
you can't add to a stock-investment lot after its been created, because
the purchases occurred on different dates). Thus, when the shares are
sold, the sale is split across two lots:
+\verbatim
> Date Desc Lot Buy Sell Price Value
> 18/1/01 XCORP 187 500 $10.00 $5000.00
> 21/3/01 XCORP 188 500 $12.00 $6000.00
> 14/7/02 XCORP 187 500 $20.00 $10000.00
> 14/7/02 XCORP 188 250 $20.00 $5000.00
+\endverbatim
In the above, lot 187 was closed, and lot 188 has a balance of 250
shares. Note that we used a FIFO accounting method in this example:
@@ -167,9 +167,8 @@
must figure out a way of doing this (i.e. re-combining splits) on
its own.
+\section lotsclosing Closing of Books
-Closing of Books
-================
A few words on lots and the closing of books. Without lots, there
is really no way of correctly implementing book closing. That is
because some reports, such as the capital-gains report, need to know
@@ -190,14 +189,13 @@
all closed lots that participate in these 'open transations',
ad infinitum.
+\section lotsdouble The "Double Balance" Requirment
-The "Double Balance" Requirment
-===============================
The following is a proposal for how to handle both realized
and unrealized gains/losses by means of "adjusting transactions."
It works for simple cases, but has issues for more complex cases.
-------------------
+
Canonical transaction balancing: If all splits in a transaction
are in the same 'currency' as the transaction currency, then the
sum of the splits *must* equal zero. This is the old, existing
@@ -208,21 +206,19 @@
we can't force a zero balance as above. Instead, we will force
a different requirement, the 'double-balance' requirement:
--- All splits that are *not* in the transaction currency C
+- All splits that are *not* in the transaction currency C
must be made a part of a lot. (Thus, for example,
the transaction currency C is dollars, whereas the split
commodity is 'S', shares of RHAT. If a transaction
has C in dollars, and 'S' in RHAT, then the S split must
be made a part of a Lot.)
-
--- The lot will have a designated 'lot currency' L that must
+- The lot will have a designated 'lot currency' L that must
be the same as the C of every split in the lot. One
cannot enter a split into the lot if C != L. (That is,
if I'm working with a Lot of RHAT shares, then *all*
splits in the lot must belong to dollar-denominated
transactions.)
-
--- When a lot is closed, we must have the 'double-balance'
+- When a lot is closed, we must have the 'double-balance'
condition: The sum total of all 'S' is zero, and the
sum total of all 'C' is zero. Thus, if I buy 100 shares
of RHAT for $5 and sell 100 shares of RHAT for $10, then
@@ -245,7 +241,7 @@
that because the 'adjusting transaction' contains a split
holding S (albeit zero S), it *must* be a part of a Lot.
-------------------
+
The above seems to work for simple stock-transactions, but
fails in other more complex cases. Here's an example.
@@ -267,14 +263,13 @@
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'
+- The user should be able to specify a default 'realized-gain'
account that is associated witha a stock account.
--- The user should be able to specify a default 'unrealized-gain'
+- The user should be able to specify a default 'unrealized-gain'
account that is associated witha a stock account.
+\section lotsfifo FIFO's
-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
@@ -286,9 +281,8 @@
properly, so that it should be easy to add other policies,
e.g. LIFO. See policy.c for what would need to be implemented.
+\section lotsimplement Implementation
-Implementation
-==============
Every split has a pointer to a lot (which may be null). A lot has a list
of splits in it (so that the other splits in the lot can be easily found).
A lot does not need to maintain a balance (this is easy enough to calculate
@@ -301,22 +295,25 @@
(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)
-==============================================
+\section lotscapgains 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
+Account C is an income account
+\verbatim
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
+\endverbatim
The gain, shown in the third line, is computed as a straight
sum of purchase price to sale price.
@@ -345,22 +342,22 @@
easier, although it makes the logic for setting the date
more complex. Ughh..
-Cap Gains Implementation Notes
-==============================
+\section loanscapnotes Cap Gains Implementation Notes
+
Cap Gains will be handled by GnuCash as described above, using
two distinct transactions. These transactions will be marked up
using KVP, pointing to each other, so that the one can be found
from the other. Implementation in src/engine/cap-gains.c
Quick API Overview:
- xaccSplitGetCapGains(): Returns the capital gains associated with
+- xaccSplitGetCapGains(): Returns the capital gains associated with
a split. Split must have been a sale/purchase in a previously
opened lot.
- xaccSplitAssignToLot(): If a split is not already in a lot,
+- xaccSplitAssignToLot(): If a split is not already in a lot,
then it places it into a lot, using a FIFO accounting policy.
-Cap Gains Actual Implementation
-===============================
+\section lotscapimplement Cap Gains Actual Implementation
+
Cap Gains are noted by creating a separate transaction with two
splits in it. One of the splits is as described above: zero
amount, non-zero value. There is a GUI requirement that when
@@ -371,14 +368,14 @@
source split, so that the one can be quickly found from the other.
Things kept in sync:
--- date posted
--- value
--- void status
--- other things ?
+- date posted
+- value
+- void status
+- other things ?
Things not kept in sync:
--- kvp trees
--- description, memo, action.
+- kvp trees
+- description, memo, action.
The posted date is kept in sync using a data-constraint scheme.
If xaccTransactionSetDatePosted() is called, the date change is
@@ -402,18 +399,17 @@
recomputed; this in turn may require the split to be split into
peices, or to be recombined into one from several pieces.
-TODO:
--- need to copy void status when source split date changes.
--- its possible for the the price, as recorded by one split
+\section lotstodo TODO
+- need to copy void status when source split date changes.
+- its possible for the the price, as recorded by one split
to vary wildly from that in another split in the same
transaction. That's bad, prices should be normalized.
Theres a routine to do this, xaccScrubSubSplitPrice()
but its not currently used.
--- write automated test cases to handle each situation.
+- write automated test cases to handle each situation.
+\section lotsconversion Conversion
-Conversion
-==========
As Lots are 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 policy (currently,
@@ -421,7 +417,7 @@
match up purchases and sales so that these can be assigned to a Lot.
The conversion algorithm will work as follows:
-
+\verbatim
for each account {
loop over splits {
// perform the 'double-balance' check
@@ -433,6 +429,7 @@
If (split amount < 0) find oldest lot, put split in that lot
}
}
+\endverbatim
See the file Scrub2.h for details of teh low-level API, and Scrub3.h
for the high-level API.
@@ -442,11 +439,11 @@
lots, those cap gains will be ignored and will throw off balances.
User will need to hand-edit to recover.
--- TODO: Modify scrub routines to look for splits with zero amount,
+- TODO: Modify scrub routines to look for splits with zero amount,
try to assign these to lots as appropriate. ??
-GUI
-===
+\section lotsgui 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.
@@ -455,81 +452,76 @@
different accounting policies (of which the FIFO policy is currently
implemented in the 'Scrub' routines).
-
-Basic GUI:
+\subsection lotsbasicgui 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.
+- 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,
+- 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.
+- 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.
+- 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
+- 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 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'.
+- button or menu item, 'add notes to this lot'.
-todo:
----- change lot viewer to use gnc-query-list
----- after the gnome2 port, add the 'unclaimed splits" window
+\subsection lotsguitodo todo:
+- change lot viewer to use gnc-query-list
+- after the gnome2 port, add the 'unclaimed splits" window
to the lot viewer, this will allow it to be a simple lot editor.
----- Add a new policy (or change the existing fifo policy) to only
+- Add a new policy (or change the existing fifo policy) to only
open lots with a particular sign for the opening split. This
way, things like business invoice overpayments are not used
to start new lots, but are instead applied to new purchases.
+\section lotsstatus Status
-Status
-======
- o Core support for Lots in the engine is complete (April 2002, ships in
+- 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
+- See src/engine/gnc-lot.h for the public API.
+- The XML backend support for lot is complete (April 2002, ships in
version 1.8.x).
- o Scrub routines to automatically take old gnucash datasets and
+- 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)
- o Closed/Open lots are handled correctly during book closing.
+- Closed/Open lots are handled correctly during book closing.
See src/engine/Period.c (August 2003)
- o Work is finished on the automatic computation & tracking
+- Work is finished on the automatic computation & tracking
of gain/loss transactions. Most of the engine API is in
src/engine/cap-gains.h although the high-level 'scrub' API
is in src/engine/Scrub3.h. See src/doc/constraints.txt for
a 'big picture' view of how its done. (September 2003)
- o A basic lot-viewing GUI is in src/gnome/lot-viewer.c
+- A basic lot-viewing GUI is in src/gnome/lot-viewer.c
This GUI cannot 'edit' lots. (August 2003)
-
- o The Postgres backend does not yet support lots.
+- The Postgres backend does not yet support lots.
XXX In particular, the programming API for Lots is currently
non-transactional. There's no dirty flag, and the backend is not
signalled that the lots have changed. This is the case both for
Scrub2.c and for src/gnome/lot-viewer.c (which changes KVP's).
-
- o Need to write extensive test cases to verify the rather complex
+- Need to write extensive test cases to verify the rather complex
constraints between the gains and lots and splits.
+- Need to write a cap-gains report!
- o Need to write a cap-gains report!
-
-
+*/
-------------------------- end of file ------------------------------
Index: multicurrency-discussion.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/multicurrency-discussion.txt,v
retrieving revision 1.1
retrieving revision 1.1.8.1
diff -Lsrc/doc/multicurrency-discussion.txt -Lsrc/doc/multicurrency-discussion.txt -u -r1.1 -r1.1.8.1
--- src/doc/multicurrency-discussion.txt
+++ src/doc/multicurrency-discussion.txt
@@ -1,202 +1,287 @@
+/** \page multicurrency Multicurrency Discussion
+
<cstim> goonie: well...
+
<goonie> How about this:
+
<cstim> goonie: You can print each value as a gnc-monetary
-<cstim> goonie: this?
+ goonie: this?
+
<goonie> cstim: don't worry, go on with your outline.
+
<cstim> How are you printing balances right now?
-<cstim> I guess you plug a gnc-numeric into the html code.
-<cstim> If you do a s/gnc-numeric/gnc-monetary/
-<cstim> ... then everything would be multi-currency compilant
-<cstim> Of course the gnc-monetary needs the actual currency specified.
-<cstim> Would that lead to problems
-<cstim> ?
-<cstim> Definition of gnc-monetary is in src/scm/gnc-numeric.scm
+ I guess you plug a \a gnc-numeric into the html code.
+ If you do a s/\a gnc-numeric/\a gnc-monetary/
+ ... then everything would be multi-currency compilant
+ Of course the \a gnc-monetary needs the actual currency specified.
+ Would that lead to problems?
+Definition of \a gnc-monetary is in src/scm/gnc-numeric.scm
+
<goonie> Cool.
-<cstim> Right now every gnc-monetary is printed like $500.23, DEM 123.45, CHF 456.32
+
+<cstim> Right now every \a gnc-monetary is printed like $500.23, DEM 123.45, CHF 456.32
+
<goonie> I think that should work fine.
-<cstim> but the formatting of gnc-monetary could be modified by any style sheet.
-<cstim> goonie: ok.
+
+<cstim> but the formatting of \a gnc-monetary could be modified by any style sheet.
+
<goonie> You also had some code for calculating totals in multiple currencies?
+
<cstim> goonie: ouch. Yes. But that gets complicated quickly.
+
<goonie> Yes, it does.
+
<cstim> goonie: You will need to use a commodity-collector from report-utilities.scm
+
<goonie> OK, cool, I think I can figure it out.
-<<cstim> goonie: You will need to use a commodity-collector from report-utilities.scm
+
+<cstim> goonie: You will need to use a commodity-collector from report-utilities.scm
+
<goonie> OK, cool, I think I can figure it out.
+
<cstim> If you want the total of only one commodity, you can use the 'getpair action of commodity-collector...
-<cstim> but if you want to show (correctly) all of the currencies, you will have a lot of trouble.
-<cstim> Basically, I have the "reference implementation" in html-utilities.scm .
+ but if you want to show (correctly) all of the currencies, you will have a lot of trouble.
+ Basically, I have the "reference implementation" in html-utilities.scm .
+
<goonie> OK, excellent.
+
<cstim> You can see how I print just one balance...
-<cstim> in the big function gnc:html-build-acct-table, line 297, where I print the total sum.
-<cstim> That would be a starting point to see how a balance with a bunch of commodities gets printed.
-<goonie> cstim: taking it up a level for a second, how would you prefer a total for a collection of splits in different currencies to be displayed?
+ in the big function \a gnc:html-build-acct-table, line 297, where I print the total sum.
+ That would be a starting point to see how a balance with a bunch of commodities gets printed.
+
+<goonie> cstim: taking it up a level for a second, how would you prefer a total for a
+collection of splits in different currencies to be displayed?
+
<cstim> what do you mean by "total for splits"?
-<goonie> OK, consider a transaction report for the account Expenses:Beer for the period 1/1/2001 to 2/1/2001 (UK date format ;)
-<goonie> and let's say I've had beer in Australia, the US, Germany, and Hong Kong during that period.
-* cstim prefers to have the beer in Germany...
-<goonie> further, let's assume that my "native currency" is AUD.
-<goonie> cstim: try some of the Australian specialty beers.
+
+<goonie> OK, consider a transaction report for the account Expenses:Beer for the period
+1/1/2001 to 2/1/2001 (UK date format ;)
+ and let's say I've had beer in Australia, the US, Germany, and Hong Kong during that period.
+ further, let's assume that my "native currency" is AUD.
+ cstim: try some of the Australian specialty beers.
+
<cstim> yes
+
<goonie> cstim: but even VB or Carlton Draught is an improvement on soap suds . . . er, Budweiser.
-<goonie> but back to Gnucash matters . . .
-<-- dres has quit (Connection reset by peer)
+ but back to Gnucash matters . . .
+
<cstim> yes
+
<goonie> now there's several possibilities for doing the totals here . . .
+
<cstim> wait wait
-<cstim> what accounts and what splits are you thinking of?
-<cstim> or in other words, what are your sorting/account/viewing parameters?
+ what accounts and what splits are you thinking of?
+ or in other words, what are your sorting/account/viewing parameters?
+
<goonie> Only one account selected, sorted by date, say (we'll discuss subtotals in a sec).
+
<cstim> goonie: One account means that there is only one currency, right?
+
<goonie> dave_p: hang on, let me just check . . .
-<goonie> s/dave_p/cstim
+ s/dave_p/cstim
+
<cstim> oh
-* cstim screwed up his homework about pole-zero plots
+
<goonie> dave_p: what's the status of currency-in-transaction?
+
<cstim> s/dave_p/???/
+
<goonie> nope, really dave_p this time :)
+
<cstim> dave_p is away: I'm doin' stuff
-<cstim> AFAIK an account has a commodity and a transaction has a commodity.
+ AFAIK an account has a commodity and a transaction has a commodity.
+
<goonie> correct.
-<cstim> gnc:account-get-commodity, gnc:transaction-get-commodity
+
+<cstim> \a gnc:account-get-commodity, \a gnc:transaction-get-commodity
+
<goonie> However, read the comments in TransactionP.h
-<goonie> /* The common_currency field indicates the currency type that
-<goonie> * all of the splits in this transaction share in common. This
-<goonie> * field is going to replace the currency field in the account
-<goonie> * structures.
-* cstim is reading
+\verbatim
+ * The common_currency field indicates the currency type that
+ * all of the splits in this transaction share in common. This
+ * field is going to replace the currency field in the account
+ * structures.
+\endverbatim
+
<cstim> yeah, that's right.
+
<goonie> So, in the short term, your assumption is correct.
-<goonie> In the long term, not the case.
+ In the long term, not the case.
+
<cstim> What I would usually call the "currency" of an account is in Gnucash acctually called "security".
-<cstim> gnc:account-get-commodity will return this security of the account.
+\a gnc:account-get-commodity will return this security of the account.
+
<goonie> Gotta love terminology.
-<goonie> The reason for the differentiation is for stock/mutual fund accounts, IIRC.
-<cstim> info IIRC?
-<goonie> If I Recall Correctly.
-<cstim> oh
-<cstim> BTW, is cvs down? Seems like...
-<goonie> Yes.
-<goonie> It's driving the rest of us nuts too .
+ The reason for the differentiation is for stock/mutual fund accounts, if I recall correctly.
+
<cstim> The more recent comments about commodities are in Transaction.h, line 229 ff.
-<cstim> or Account.h, line 203ff.
-<goonie> Yep, so the situation I described above can't happen right now, but will be possible in the near future.
-<goonie> Which brings us back to how should we display things:
-<goonie> A total for each currency.
-* cstim doesn't yet understand the situation.
+ or Account.h, line 203ff.
+
+<goonie> Yep, so the situation I described above can't happen right now, but will be possible
+in the near future. Which brings us back to how should we display things:
+ A total for each currency.
+
<cstim> What account would that be?
+
<goonie> The account Expenses:Beer.
+
<cstim> What security will it have?
+
<goonie> AUD
+
<cstim> okay.
+
<cstim> go ahead
+
<goonie> OK, say that there's only four transactions in that account for the period in question:
-<goonie> $2 in AUD, 5 USD, 1 EURO, and 12 HKD being the values.
-<goonie> What should we display as the total(s)?
-<goonie> Or more to the point, what options do we need to offer?
-<cstim> waitwait.
-<cstim> Expenses:beer has security AUD.
---> dres (dres at user-2ivf2cm.dialup.mindspring.com) has joined #gnucash
-<dres> have I pointed out that having a modem connection sucks recently? :)
-<cstim> So there is one Transaction between Cash:USD and the beer.
-<cstim> And one between Cash:Euro and the beer.
-<cstim> And one between (what the heck is) Cash:HKD and the beer.
+ $2 in AUD, 5 USD, 1 EURO, and 12 HKD being the values. What should we display as the total(s)?
+ Or more to the point, what options do we need to offer?
+
+<cstim> waitwait. Expenses:beer has security AUD.
+ So there is one Transaction between Cash:USD and the beer.
+ And one between Cash:Euro and the beer.
+ And one between (what the heck is) Cash:HKD and the beer.
+
<goonie> Hong Kong Dollar, BTW.
-<dres> hong kong dollars?
-<goonie> yep, they have their own currency.
-<dres> smart of them.
+
<cstim> And, say, those Transaction have the transaction-commodity according to the Cash:*
+
<goonie> yep.
+
<cstim> But the split which belongs to Exp:Beer has only one value
-<cstim> and that value represents the beer expense in AUD.
-<cstim> i.e. in the split's account's security.
+ and that value represents the beer expense in AUD.
+ i.e. in the split's account's security.
+
<goonie> hang on . . . let me think this through carefully . . .
+
<cstim> ok, lets get things straight: Each split has two fields, value and damount
-* goonie is thinking this through.
-<cstim> Quote from a grib posting last October:
-<cstim> - Eliminate the 'share price' field from the Split structure and
-<cstim> replace it with a 'value' field. The 'value' is a translation of
-<cstim> the Split's 'damount' (which is the amount of the Account's
-<cstim> security involved) into the Transaction's balancing currency.
-<cstim> the last sentence is the one that matters.
-<goonie> /* value is the amount of the account's currency involved,
-<goonie> * damount is the amount of the account's security. For
-<goonie> * bank-type accounts, currency == security and
-<goonie> * value == damount. */
-<goonie> gnc_numeric value;
-<goonie> gnc_numeric damount;
-<goonie> from src/engine/TransactionP.h
+ Quote from a grib posting last October:
+\verbatim
+ - Eliminate the 'share price' field from the Split structure and
+ replace it with a 'value' field. The 'value' is a translation of
+ the Split's 'damount' (which is the amount of the Account's
+ security involved) into the Transaction's balancing currency.
+\endverbatim
+ the last sentence is the one that matters.
+
+<goonie>
+\verbatim
+ * value is the amount of the account's currency involved,
+ * damount is the amount of the account's security. For
+ * bank-type accounts, currency == security and
+ * value == damount.
+ gnc_numeric value;
+ gnc_numeric damount;
+\endverbatim
+ from src/engine/ TransactionP.h
+
<cstim> that's outdated.
-<cstim> In the long run: value is the amount of the transaction-commodity involved, damount is the amount of the account-commodity involved.
-<goonie> OK, but the value returned from gnc:split-get-value is the value rather than the damount.
-<goonie> sorry for the long delay, I was reading code to make sure I understood what was going on.
-<goonie> value being the one denominated in the transaction-commodity.
-<cstim> That's right. gnc:split-get-value gives you the value, whereas gnc:split-get-share-amount gives you the damount
-<cstim> Maybe that functions need some name change in the future.
+ In the long run: value is the amount of the transaction-commodity involved, damount is
+the amount of the account-commodity involved.
+
+<goonie> OK, but the value returned from \a gnc:split-get-value is the value rather than the damount.
+ sorry for the long delay, I was reading code to make sure I understood what was going on.
+ value being the one denominated in the transaction-commodity.
+
+<cstim> That's right. \a gnc:split-get-value gives you the value, whereas
+\a gnc:split-get-share-amount gives you the damount
+ Maybe that functions need some name change in the future.
+
<goonie> perhaps.
-<goonie> the trouble is that there are so many things that need names in gnucash, that you start to run out :)
+ the trouble is that there are so many things that need names in gnucash, that you start to run out :)
+
<cstim> :)
-<cstim> We could gnc:split-get-share-amount => gnc:split-get-damount
-<cstim> whatever.
-<cstim> My point for the Beer is
-<cstim> let's have some.
+ We could \a gnc:split-get-share-amount => \a gnc:split-get-damount
+ whatever. My point for the Beer is let's have some.
+
<dres> beer doesn't need a point. it just is.
+
<cstim> oops.
-<cstim> I would expect that the transaction report uses gnc:split-get-share-amount
-<cstim> which in this case gives you already the amounts exchanged into AUD and everything's fine.
+ I would expect that the transaction report uses \a gnc:split-get-share-amount
+ which in this case gives you already the amounts exchanged into AUD and everything's fine.
+
<goonie> You would prefer that over the transaction-specific value, then?
-<cstim> Well, if I want the list for one specific account, then I would expect all amounts to be in that account's commodity, i.e. the account-commodity (formerly known as security :)
+
+<cstim> Well, if I want the list for one specific account, then I would expect all amounts to be
+in that account's commodity, i.e. the account-commodity (formerly known as security :)
+
<goonie> yep.
-<goonie> But then the problem just arises in a different light if you have multiple accounts, sorted by date, say.
-<cstim> I would recommend a name change for gnc:split-get-share-amount.
-<cstim> multiple accounts.
-<cstim> okay, let's talk about that.
-<cstim> what scenario do you think of?
+ But then the problem just arises in a different light if you have multiple accounts, sorted by date, say.
+
+<cstim> I would recommend a name change for \a gnc:split-get-share-amount.
+ multiple accounts. okay, let's talk about that. what scenario do you think of?
+
<goonie> cstim: could you mail Dave wrt function renaming?
+
<cstim> I'll send a mail to the ML
-<goonie> OK, let's say you've selected Expenses:Champagne (in Francs), Expenses:Saki (in Yen), and Expenses:VB (in Aussie dollars), and you want a report for all those transactions for the past month, sorted by date.
-<goonie> You have Cash:Francs, Cash:Yen and Cash:Aussie accounts with the expected currencies.
+
+<goonie> OK, let's say you've selected Expenses:Champagne (in Francs), Expenses:Saki
+(in Yen), and Expenses:VB (in Aussie dollars), and you want a report for all those transactions
+for the past month, sorted by date. You have Cash:Francs, Cash:Yen and
+Cash:Aussie accounts with the expected currencies.
+
<cstim> what's VB?
+
<goonie> Victoria Bitter (Australian Beer).
-<cstim> okay.
-<cstim> well...
+
+<cstim> okay. well...
+
<goonie> If you want a distinctively Australian Alcoholic beverage, s/VB/Sparkling Red
-<cstim> Lets have some.
-* goonie offers cstim a glass of fine Rutherglen sparkling red.
-<cstim> Transaction report: but it doesn't make much sense to show a total sum for that anyway, does it_
-<cstim> s/_/?/
-<cstim> oh well, it might.
+
+<cstim> Lets have some. ( goonie offers cstim a glass of fine Rutherglen sparkling red. )
+ Transaction report: but it doesn't make much sense to show a total sum for that anyway, does it_
+ s/_/?/ oh well, it might.
+
<goonie> Option 1) display a total for each currency in the report.
+
<cstim> exactly.
-<cstim> Option 2) shows the total for only one currency, the report-currency.
-<cstim> Option 3) somehow gets the right exchange rate so that it also ends up with only one total.
-<cstim> I'd recommend option 2 for now.
-<cstim> For option one you basically would have to copy the code out of the html-build-acct-table function cited above.
+ Option 2) shows the total for only one currency, the report-currency.
+ Option 3) somehow gets the right exchange rate so that it also ends up with only one total.
+ I'd recommend option 2 for now. For option one you basically would have to copy the
+code out of the html-build-acct-table function cited above.
+
<goonie> So, what happens to transactions not in the report-currency in option 2) - they aren't totalled?
+
<cstim> Maybe with the tons of comments it is do-able
-<cstim> goonie: yes, they dissolve in heat and aren't totalled.
-<goonie> OK, I think I can implement 1) and 2). 3 (which might have to be split into 3a, 3b . . . ) can probably wait.
-<goonie> Well, I could implement a "quickie" 3a that just grabs a current exchange rate and does the conversion on it.
-<cstim> again, for 1) you "just" have to copy ~100 lines of code from html-utilities.scm and adapt them to your table structure.
+ goonie: yes, they dissolve in heat and aren't totalled.
+
+<goonie> OK, I think I can implement 1) and 2). 3 (which might have to be split into 3a, 3b . . . )
+can probably wait. Well, I could implement a "quickie" 3a that just grabs a current exchange
+rate and does the conversion on it.
+
+<cstim> again, for 1) you "just" have to copy ~100 lines of code from html-utilities.scm and
+adapt them to your table structure.
+
<goonie> that has all sorts of problems, but might be useful if taken with a grain of salt.
-<goonie> OK.
+ OK.
+
<cstim> oh, a quick 3) costs you about 5 lines of extra cost.
+
<goonie> I think I can cope with that :)
-<cstim> just look into pnl.scm and see how they (i.e. I) use gnc:make-exchange-alist and gnc:make-exchange-function
-<cstim> both from src/scm/commodity-utilities.scm
-<goonie> OK, cool.
-<goonie> Thanks for your help.
+
+<cstim> just look into pnl.scm and see how they (i.e. I) use gnc:make-exchange-alist and
+\a gnc:make-exchange-function both from \a src/scm/commodity-utilities.scm
+
+<goonie> OK, cool. Thanks for your help.
+
<cstim> what did you mean by "quickie" 3a that just grabs a current exchange rate "
-<cstim> a dialog box? a parameter? gnc-prices?
-<goonie> gnc-prices.
-<goonie> or a parameter.
-<goonie> something other than digging through a bunch of historical data trying to figure out what the exchange rate was at the time of particular transactions.
-<cstim> parameter: Bad. gnc-prices: Goood. I'd be happy if someone could implement that to augment the current code in commodity-utilities.scm
-<cstim> Oh, the exchange rate at the time of a particular *transaction* is easy --
-<cstim> -- that's just the fraction value/damount .
+ a dialog box? a parameter? gnc-prices?
+
+<goonie> gnc-prices. or a parameter.
+ something other than digging through a bunch of historical data trying to figure out what
+the exchange rate was at the time of particular transactions.
+
+<cstim> parameter: Bad. gnc-prices: Goood. I'd be happy if someone could implement that
+to augment the current code in commodity-utilities.scm Oh, the exchange rate at the time
+of a particular *transaction* is easy -- that's just the fraction value/damount .
+
<goonie> not always - what if the transaction is (say) yen/yen but you want to display in dollars?
-<goonie> for instance, our glass of saki, paid for in cash yen.
-<cstim> Yes, right. currently the commodity-utilities stuff uses a weighted average over the history. But using the last known exchange rate instead may be useful at times.
-<cstim> Maybe I'll implmement something like that
-<cstim> maybe if i have time :)
-<goonie>diff -up 'gnucash/src/engine/Query.c' 'gnucash_transaction_report/src/engine/Query.c'
+ for instance, our glass of saki, paid for in cash yen.
+
+<cstim> Yes, right. currently the commodity-utilities stuff uses a weighted average over the
+history. But using the last known exchange rate instead may be useful at times. Maybe I'll
+implmement something like that maybe if i have time :)
+
+<goonie>diff -up 'gnucash/src/engine/ Query.c' 'gnucash_transaction_report/src/engine/ Query.c'
+
+*/
Index: prices.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/prices.txt,v
retrieving revision 1.2
retrieving revision 1.2.2.1
diff -Lsrc/doc/prices.txt -Lsrc/doc/prices.txt -u -r1.2 -r1.2.2.1
--- src/doc/prices.txt
+++ src/doc/prices.txt
@@ -1,10 +1,15 @@
+/** \page pricedocs Price Overview
+The Prices and the Price DB overview is in src/doc/design/engine.texinfo
+(also available online as individual HTML:
+http://code.neil.williamsleesmill.me.uk/texi/gnucash-design_4.html#SEC66 )
-Prices and the Price DB API is documented in design/engine.texinfo
+API: \ref Price
Below, a few meta-notes about how prices and the GUI (should) interact:
-----------
+\section pricecompute Computing Prices
+
When a price is computed from the (value/amt) that a user entered
in a register, and this price is stored in the priceDB, then
both the register entry and the price must have links to each other
@@ -20,14 +25,15 @@
the correpsonding priceDB entry must be deleted as well (since
it is not safe to assume that the price is 'correct').
-----------
+\section Rounding errors
+
When doing price math in the register, one must be careful, because
round-off errors can make 'obvious' math inaccurate. Note that if
we define price as (value/amt), then we will find that
value != price * amt due to roundoff handling. One must be careful
and consistent in handling this in the register, as otherwise
users will be driven crazy by inconsitent behaviour.
-----------
-
(Linas Vepstas April 2003)
+
+*/
Index: constraints.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/constraints.txt,v
retrieving revision 1.2.2.1
retrieving revision 1.2.2.2
diff -Lsrc/doc/constraints.txt -Lsrc/doc/constraints.txt -u -r1.2.2.1 -r1.2.2.2
--- src/doc/constraints.txt
+++ src/doc/constraints.txt
@@ -1,12 +1,11 @@
+/** \page financeconstraints Financial Constraints in GnuCash
- Financial Constraints in GnuCash
- --------------------------------
- Linas Vepstas <linas at linas.org>
+ Linas Vepstas <linas at linas.org>
September 2003
-Overview:
----------
+\section financeoverview Overview:
+
The GnuCash Engine implements a set of financial constraints so
that a set of basic/core accounting rules are obeyed. The best
known example is the "double-entry" constraint: the total value
@@ -22,8 +21,8 @@
easier to add and work with new types of constraints.
-Introduction:
--------------
+\section financeintro Introduction:
+
There are three very different classes of constraints within GnuCash,
which should not be confused with each other. They work in very
different ways and have very different goals. First, there are
@@ -61,9 +60,9 @@
as there is pressure to support more complex constraints that vary
by region/country, by account type, by industry, etc.
-Why Not 'Lazy Evaluation'?
---------------------------
-Lazy evaluation is supperfically like constraints, but differs in an
+\section financelazy Why Not 'Lazy Evaluation'?
+
+Lazy evaluation is superficially like constraints, but differs in an
important way. With lazy evaluation, when something changes (e.g.
the posted date) it is marked dirty. Later, when something else needs
something (e.g. the posted date on a gains split), the dirty flag
@@ -79,24 +78,21 @@
deopendencies. At this time, the sync point is the xaccTransCommitEdit()
subroutine.
-List of Constraints
--------------------
+\section financelist List of Constraints
+
The following is a list of the constraints that are currently
implemented in the GnuCash Engine, with a short description of what
they are, and how they work.
--- Double Entry
--- Double-Balance
--- Date Posted of Gains Transaction
+- Double Entry
+- Double-Balance
+- Date Posted of Gains Transaction
The posted date of the gains transaction is kept in sync with the
posted date on the transaction that is the source of the gains.
See the document 'lots.txt', section 'Cap Gains Actual Implementation'
for details.
--- Value of Gains Transaction
+- Value of Gains Transaction
The value recorded by teh gains transaction is kept in sync with
the value
-
-
-
-
+*/
Index: backup.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/backup.txt,v
retrieving revision 1.1
retrieving revision 1.1.14.1
diff -Lsrc/doc/backup.txt -Lsrc/doc/backup.txt -u -r1.1 -r1.1.14.1
--- src/doc/backup.txt
+++ src/doc/backup.txt
@@ -1,3 +1,6 @@
+/** \page backuppolicy Backup Design
+
+API: \ref Backend
Currently, backups and log files are automatically stored by the engine
with date/time stamps every time the user hits 'save' in the gui.
@@ -5,36 +8,31 @@
(The actual file writing is done by xaccWriteAccountGroupFile() in
in src/engine/FileIOP.h)
-Proposed design changes:
-------------------------
-a) Allow user to configure which directory backups should be put into.
- (currently, this is same as current directory). Requires changes to
- engine FileIOP.h as well as GUI.
+\section backupchanges Proposed design changes:
+-# Allow user to configure which directory backups should be put into.
+ (currently, this is same as current directory). Requires changes to
+ engine FileIOP.h as well as GUI.\n
One possible default is ~/.gnucash/data/ (Which is supposed to
be the place where files are saved if no directory is specified.!?)
-
-b) Prompt the user to make a backup every third save. Make this number
+-# Prompt the user to make a backup every third save. Make this number
configurable. If no default backup path set, prompt to set it,
with suggested path being ~/.gnucash/backups/
-
-c) If save format was XML text, then could use RCS ...
- Alternately,
-For those that don't know, xdelta is like RCS, but it's designed to
-handle any kind of data, including binary, is supposed to work really
-well, and transparently handles gzipped data with some form of MD5sum
-verification. It's also available in library form. Like RCS it would
-give us the ability to do cool things like snapshot the data every so
-often for nearly no cost. Want to see what things looked like 6
-months ago? Just enter the right date into the "time-warp" dialog :>
-
-For those on Debian systems, just install the xdelta and
-libxdelta2-dev packages. Others can get the source from
-ftp://www.xcf.berkeley.edu/pub/xdelta/, or just go to
-ftp.debian.org:/pub/debian/dists/unstable/main/source/utils/xdelta*.tar.gz
-
-
-d) Could monitor how many changes (records altered) the user has made,
+-# If save format was XML text, then could use RCS ...
+ Alternately,
+ For those that don't know, xdelta is like RCS, but it's designed to
+ handle any kind of data, including binary, is supposed to work really
+ well, and transparently handles gzipped data with some form of MD5sum
+ verification. It's also available in library form. Like RCS it would
+ give us the ability to do cool things like snapshot the data every so
+ often for nearly no cost. Want to see what things looked like 6
+ months ago? Just enter the right date into the "time-warp" dialog :>\n
+ For those on Debian systems, just install the xdelta and
+ libxdelta2-dev packages. Others can get the source from
+ ftp://www.xcf.berkeley.edu/pub/xdelta/, or just go to
+ ftp.debian.org:/pub/debian/dists/unstable/main/source/utils/xdelta*.tar.gz
+-# Could monitor how many changes (records altered) the user has made,
and could prompt for more frequent saves if lots of editing has
ocurred...
+*/
Index: backend-api.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/backend-api.txt,v
retrieving revision 1.1
retrieving revision 1.1.4.1
diff -Lsrc/doc/backend-api.txt -Lsrc/doc/backend-api.txt -u -r1.1 -r1.1.4.1
--- src/doc/backend-api.txt
+++ src/doc/backend-api.txt
@@ -1,74 +1,62 @@
- GnuCash Backend API (v2)
+/** \page backendapi QOF Backend Design
Derek Atkins
<derek at ihtfp.com>
+ Neil Williams
+ <linux at codehelp.co.uk>
+
Created: 2002-10-07
+Updated: 2005-05-22
-Problem:
---------
+API: \ref Backend
-The current Backend API is hardcoded to dealing with Accounts,
-Transactions, and Splits. The Backend Query API does not allow
-caching of a Query (meaning the Backend has to recompile the Query
-every time the query is executed). With the inclusion of a multitude
-of new datatypes and plugable architure, the Backend API requires
-modification to handle the new data.
+\section outline Outline:
+The Backend Query API allows caching of a Query (meaning the Backend
+does not have to recompile the Query every time the query is executed).
-"Dynamic" Data Types:
----------------------
+\section newobjects New QOF Objects
The engine has a set of APIs to load new data types into the engine.
-The Backends need this as well. Currently the engine supplies a set
-of registration functions to register Backend handlers for new data
-types. Each Backend defines a plug-in API and then data types can
-register themselves. This is how extensibility works.
-
-For example, the "file" Backend defines the API for plug-in data
-types. It requires data types to implement four functions:
-create_parser(), add_item(), get_count(), and write().
-
-A new data-type, the GncFOO type, implements the required APIs and
-registers itself with gncObjectRegisterBackend(). The file backend
-can then either lookup the GncFOO object by name by calling
-gncObjectLookupBackend(), or can iterate over all the registered
-objects by using gncObjectForeachBackend(), depending on the
-particular backend operation.
-
-By using these functions, new data types can be registered and new
-types of data stored using generic Backend API functions. The backend
-implementing generic *_edit() or session_load() APIs could then lookup
-data types by name or iterate over all known data types to determine
-how to load or save data. Each backend can define the set of
-interfaces it requires data-types to implement.
-
-
-Handling Queries:
------------------
-
-The version-1 Backend provides a single run-query method that returns
-a list of splits. This has proven to be limiting, and recompiling the
-query into the backend format each time can be time consuming. To fix
-this the backend query API needs to be broken into three pieces:
-
- gpointer (*query_compile)(Backend* be, Query* query);
-
- compiles a Query* into whatever Backend Language is necessary.
-
- void (*query_free)(Backend* be, gpointer query);
-
+The Backends use this as well. There is a noticeable difference
+between QOF and GnuCash: GnuCash extends the backend by defining routines
+for each object. QOF backends handle each object equally and generically.
+
+A new object is declared using the base QOF types and zero or more
+references to other QOF objects. Each QOF backend must handle each
+base QOF type and references to other objects - usually by storing
+the type of the referenced object and the GUID of the referenced object
+as the value and the GUID of the original object as the key in a
+GHashTable or other lookup mechanism within the backend. See
+::QofEntityReference.
+
+\section backendqueries Handling Queries:
+
+The backend query API is broken into three pieces:
+
+\subsection querycompile Compiling a QofQuery
+\verbatim
+ gpointer (*query_compile)(QofBackend* be, QofQuery* query);
+\endverbatim
+ compiles a QofQuery* into whatever QofBackend language is necessary.
+
+\subsection queryfree Free the query
+\verbatim
+ void (*query_free)(Backend* be, gpointer query);
+\endverbatim
frees the compiled Query (obtained from the query_compile method).
+\subsection queryrun Run the query
+\verbatim
void (*query_run)(Backend* be, gpointer query);
-
+\endverbatim
executes the compiled Query and inserts the responses into the
engine. It will search for the type corresponding to the
Query search_for type: gncQueryGetSearchFor(). Note that the
search type CANNOT change between a compile and the execute,
but the query infrastructure maintains that invariant.
-
In this manner, a Backend (e.g. the Postgres backend) can compile the
Query into its own format (e.g. a SQL expression) and then use the
pre-compiled expression every run instead of rebuilding the
@@ -81,80 +69,17 @@
and not even a challenging one, but it needs to be clearly
acknowledged up front.
-Also note that this API can usurp the price_lookup() method, assuming
-the GNCPriceLookup can be subsumed by the Query.
-
-
-Handling Multiple Datatypes:
-----------------------------
-
-The current API specifically defines "edit" functions for Accounts and
-Transactions. This rather rigid API does not allow for adding new
-data types to the Backend. A better approach is to generalize the
-begin_edit, rollback_edit, and commit_edit APIs into a general API
-which is dynamically sub-typed at runtime:
-
- void (*begin_edit)(Backend* be, GNCIdTypeConst data_type, gpointer object);
- void (*rollback_edit)(Backend* be, GNCIdTypeConst data_type, gpointer object);
- void (*commit_edit)(Backend* be, GNCIdTypeConst data_type, gpointer object);
-
-This API looks just like the existing API for Accounts, Periods, and
-Price entries, although it quite obviously does not match the
-Transaction commit. Note that not all data-types need to implement
-all three types (there is no rollback on Accounts, Prices, or
-Periods). Note that certain data-types can _still_ be special (e.g.
-the Period handling).
-
-Question: why does the transaction commit have two transactions? In
-particular, can't the backend "know" that the "original" transaction
-is in "trans->orig". Besides, if the Backend is truly in charge of
-the data, then the engine can make changes to the local copy and can
-"back out" by accessing the backend (or commit by sending it to the
-backend). Can't one assume that the "backend" knows how the engine is
-implementing the rollback caching?
-
-
-When to load data?
-------------------
+\section backendload When to load data?
Data loads into the engine at two times, at start time and at query
-time. Loading data during queries is discussed above. This section
+time. Loading data during queries is discussed above. This section
discusses data loaded at startup.
-Currently the API has book_load() and price_load(). That's nice for
-the book and price DB, but there may be other items that need to be
-loaded at "start" time. A better approach would be to combine all
-the _load() APIs into a single API:
-
- void session_load(Backend*, GNCBook*);
-
-This one API would load all the necessary "start-time" data, including
-the Chart of Accounts, the Commodity Table, the Scheduled Transaction
-List, the Pricedb, etc. There is no need to have multiple APIs for
-each of the data types loaded at start-time. Dynamic data-types that
-require data to be loaded at start-time can register a specific API
-for the backend to execute the load.
-
-
-Usefulness of sync_*()?
------------------------
-
-What is the point of sync_all(), sync_group(), and sync_price()?
-Obviously one of them is necessary to implement "save-as", but there
-is no need for multiple versions. New datatypes can just be plugged
-in by the dynamic API. There is no reason to differentiate the book
-from the pricedb, as they are still attached to each other.
-Therefore, sync_all() should be left and sync_group() and sync_price()
-should be removed.
-
-
-Usefulness of export()?
------------------------
-
-The export() method is used to export a Chart of Accounts to a file.
-Is it really necessary that this be in the backend? What does it mean
-to "export" in anything else? Note that only the file backend even
-IMPLEMENTS this method... How general is export?
-
-
-============================== END OF DOCUMENT =====================
+\verbatim
+ void session_load(QofBackend*, QofBook*);
+\endverbatim
+
+This one API loads all the necessary "start-time" data, There is no
+need to have multiple APIs for each of the data types loaded at start-time.
+*/
+============================== END OF DOCUMENT =====================
Index: netlogin.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/netlogin.txt,v
retrieving revision 1.1
retrieving revision 1.1.8.1
diff -Lsrc/doc/netlogin.txt -Lsrc/doc/netlogin.txt -u -r1.1 -r1.1.8.1
--- src/doc/netlogin.txt
+++ src/doc/netlogin.txt
@@ -1,26 +1,20 @@
+/** \page networkoverview GnuCash Network Login
-GnuCash Network Login
----------------------
A quick sketch of how network login works when using the xml-web backend
for communicating with a gnucash server.
-
-1) User enters in a URL Location via GUI dialogue. Location is assumed
+-# User enters in a URL Location via GUI dialogue. Location is assumed
to be plain html, and is displayed with gnc_html_show_url()
in its own window.
-
-2) The displayed page is presumably some kind of login page. It is not
+-# The displayed page is presumably some kind of login page. It is not
gnucash specific, and is entirely up to the webmaster or sysadmin
to provide, modify, etc. the login & authentication information.
The user types in name, passord, whatever.
-
-3) The authentication mechanism issues a guid which will be used
+-# The authentication mechanism issues a guid which will be used
to identify the session. The guid is placed in a cookie labelled
- "gnc-server-sesion-guid=xxxxxxxxxxxxxxxxxxxxx"
-
+ "gnc-server-sesion-guid=xxxxxxxxxxxxxxxxxxxxx"\n
Because a cookie can be snoopedand then used to steal a session,
the only secure way of doing this is to use SSL.
+-# The cookie is used to identify the session to the gnc-server.
-4) The cookie is used to identify the session to the gnc-server.
-
-
+*/
Index: guid.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/guid.txt,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -Lsrc/doc/guid.txt -Lsrc/doc/guid.txt -u -r1.1.2.1 -r1.1.2.2
--- src/doc/guid.txt
+++ src/doc/guid.txt
@@ -1,12 +1,11 @@
-
- GUID's - Globally Unique Identifiers
- Design Issues
- -------------
+/** \page guid Globally Unique Identifiers: Design Issues
Linas Vepstas November 2003
-Summary:
---------
+API: \ref GUID
+
+\section guidsummary Summary
+
GUID's are meant to uniquely identify a GnuCash object. However,
when that object is backed up (by copying a gnucash data file),
the identified object is no longer unique. Book closing is a
@@ -19,9 +18,8 @@
uniqueness, searchability, copies and storage-space issues
that come up when handling GUID's on book closing.
+\section guidintro Introduction
-Introduction:
--------------
GUID's are meant to be a way of identifying a given GnuCash entity.
Accounts, transactions, splits, prices and lots all have GUID's.
GUID's can be used as a reference: by knowing a GUID, the matching
@@ -48,9 +46,8 @@
transactions, while the 'open book' looks just like it (has the
same accounts, etc), but doesn't have the old transactions.
+\section guidissue The Issue
-The Issue:
-----------
The current book-closing code makes a copy of the account tree,
and sorts all transactions, by date, into the new or the old
account tree. With the goal of not confusing the new and the
@@ -58,5 +55,6 @@
a new set of guids. The Pro's & Con's of this scheme:
Pro: The 'old', closed accounts can be uniquely accessed according
-to thier GUID's, without causing confusion with similar/same.
+to their GUID's, without causing confusion with similar/same.
+*/
Index: backend-errors.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/backend-errors.txt,v
retrieving revision 1.1
retrieving revision 1.1.4.1
diff -Lsrc/doc/backend-errors.txt -Lsrc/doc/backend-errors.txt -u -r1.1 -r1.1.4.1
--- src/doc/backend-errors.txt
+++ src/doc/backend-errors.txt
@@ -1,189 +1,94 @@
+/** \page backenderrors Handling Backend Communications Errors
- Handling Backend Communications Errors
- --------------------------------------
- Architectural Discussion
- December 2001
- Proposed/Reviewed, Linas Vepstas, Dave Peticolas
+ Architectural Discussion
+ December 2001
+ Proposed/Reviewed, Linas Vepstas, Dave Peticolas
+
+ Updated and adapted for general QOF usage, May 2005
+ Neil Williams <linux at codehelp.co.uk>
+
+API: \ref Backend
+
+\section backendproblem Problem:
-Problem:
---------
What to do if a serious error occurs in a backend while
-GnuCash is being used? For example, what happens if the connection
-to the SQL server is lost, because the SQL server has died, and/or
+QOF is being used? For example, what happens if the connection
+to a SQL server is lost, because the SQL server has died, and/or
because there is a network problem (unplugged ethernet cable, etc.)
+With the QSF backend, what happens if the write operation fails?
+(disk full, permission failure, etc.)
+\section backendgeneric The "Generic Handler, Report it to the User" idea:
-Discussion:
------------
-There are a set of macros in the Postgres backend that check for
-a Postgres error, and completely shut down the connection to the
-Postgres server whenever even a minor error occurs. This is
-excessively harsh. How to do better?
-
-
-The "Handle it Automatically in the Backend" idea:
---------------------------------------------------
-Detect the error in the backend, and do something 'intelligent'
-in the backend, trying to recover from it. What one does depends on
-the actual context (depending one what is going on in the code at that
-point.) In other words, implement automatic session-reconnection in
-the backend.
-
-To do this, you can't just handle the errors in the macros (SEND_QUERY,
-FINISH_QUERY, etc) since it depends on the context and how much work
-you've sent to the postgres process so far. One error that would
-be nice to be able to recover from is a simple loss of connection (the
-postmaster gets killed and restarted). This might require one to
-'replay' some last few queries,
-
-
-The "Generic Handler, Report it to the User" idea:
---------------------------------------------------
-There's a simple, direct thing we should get working first:
-
-Go ahead and close the connection, but then return to the engine
-in some nice way, let the engine report the error by GUI, and then
+Go ahead and close the connection / clean up, but then return to
+QOF in some nice way, use qof_session_get_error to report the error
+to any GUI using program-specific handlers and then
allow the user to initiaite a new session (or maybe try to do it
-automatically): and do all this without deleting all the accounts
-and transactions.
-
-Its some fair amount of work just to untangle the flow of control
-for this case, and leave gnucash in a usable state without having
-an open session.
+automatically): and do all this without deleting any data.
I like this for several reasons:
--- its generic, it can handle any backend error anywhere in the code.
+- its generic, it can handle any backend error anywhere in the code.
You don't have to second-guess based on whether some recent query
may or might not have completed.
--- I beleive that reconnect will be quicker, because you won't need
+- I believe that reconnect will be quicker, because you won't need
reload piles of accounts and transactions.
--- If the user can't reconnect, then they can always save to a file.
+- If the user can't reconnect, then they can always save to a file.
This can be a double bonus if done right: e.g. user works on laptop,
saves to file, takes laptop to airport, works off-line, and then
syncs her changes back up when she goes on-line again.
+\section backendresults Discussion:
-Discussion:
-----------
-> Should the backend try reconnecting first, or just go ahead and
-> return an error condition immediately? If the latter, then the
-> current backend error-handling can just stay as it is and the gui
-> codes need to add checks in several places, right?
-
-The backend can try reconnecting automatically. But lets think through
-what this implies, and we'll see its not that good an idea:
-
-It will need to remember the user's password to reconnect (It currently
-drops the passwd as a security precaution). I don't have an opinion
-as to whether it should log the reconnect in the gncSession table.
-I don't know if it should try to do a streamlined reconnect -- e.g.
-skip checking the version numbers ... but maybe the SQL server was
-rebooted (or at least, all users were kicked) precisely because the
-version numbers changed ??
+Should the backend try reconnecting first, or just go ahead and
+return an error condition immediately? If the latter, then the
+current backend error-handling can just stay as it is and the gui
+codes need to add checks in several places, right?
The problem with automatic reconnect from within the backend is that you
don't know quite where to restart... or rather, you have trouble getting
-to the right place to restart. Take for example
+to the right place to restart.
-pgendStoreTransaction (PGBackend *be, Transaction *trans)
-{
- /* lock it up so that we store atomically */
- bufp = "BEGIN;\n"
- "LOCK TABLE gncTransaction IN EXCLUSIVE MODE;\n"
- "LOCK TABLE gncEntry IN EXCLUSIVE MODE;\n";
- SEND_QUERY (be,bufp, );
- FINISH_QUERY(be->connection);
-
- pgendStoreTransactionNoLock (be, trans, TRUE);
-
- bufp = "COMMIT;\n"
- "NOTIFY gncTransaction;";
- SEND_QUERY (be,bufp, );
- FINISH_QUERY(be->connection); // << network error occurs here!!!
-
-Well, you can't just re-login, and reissue the commit. You really need
+You can't just re-login, and reissue the commit. You really need
to rewind to the begining of the subroutine. How can you do this?
-Alternative 1) wrap this routine:
-
- pgendStoreTransaction (PGBackend *be, Transaction *trans)
- {
- do {
- pgendIfNotLoggedInThenReLogin(be);
- pgendStoreTransactionOnceOnly(be, trans);
- } while (NO_ERROR ! pgendGetError());
- }
-
- well, maybe not infinite loop, maybe three retries or something.
+Alternative 1) wrap the routine and retry three times.
Alternative 2) throw an error, let some much higher layer catch it.
Well, approach 1) seems reasonable... until you think about what happens
if three retries doesn't cut it: then you have to throw an error
anyway, and hope the higher layer deals with it. So even if you
-implement 1), you *still* have to implement 2) anyway.
+implement 1), you *still* have to implement 2) anyway.
So my attitude is to skip doing 1 for now (maybe we can add it later)
and just make sure that when we "throw" the error, it really does behave
like a throw should behave, and short-cuts its way up to where its
caught. The catcher should probably be a few strategic places in the
-GUI, like wherever a xaccQuery() is issued, and wherever an
-xaccTransCommitEdit() is issued (which is hopefully not a lot of
-places ?).
-
+GUI, like wherever a QofQuery() is issued, and wherever an
+object is edited.
What's the point of doing 2 cleanly? Because I suspect that most
-network errors won't be automatically recoverable. Most likely,
-either someone tripped over an ethernet cable, or the server crashed,
-and you gotta call the sysadmin on the phone, etc. The goal is not
-to crash the client when the network is down, but rather let the user
-continue to work off-line (rather than a forced coffee break).
-
-Alternately, user might take a forced coffee break, and 10 minutes
-later, manually reconnects and resumes work ... without having to
-stop & restart gnucash, without having to close and reopen a register,
-re-run a report window, etc. Because its the re-opening of the
-app that is the major pain in the butt.
-
-
-How to Report Errors to the GUI
--------------------------------
-> How would the engine->GUI error reporting happen? A direct callback?
-> Or having the GUI always check for session errors?
+network / filesystem errors won't be automatically recoverable.
+Most likely, either someone tripped over an ethernet cable, or the
+server crashed or the disc is full and you gotta call the sysadmin on
+the phone or clear out some files, etc. The goal is not to crash the
+client when the backend reports an error, but rather let the user
+continue to work.
-We should use the session error mechanism for reporting these errors.
-Note that the API allows a simple 'try-throw-catch' style error
-handling in C. Because we don't/can't unwind the stack as a true
-'throw' would, we need to make sure that when we "throw" the error,
-it emulates this as best it can: it short-cuts its way up and out of
-the engine, to where its caught in the GUI. The catcher should probably
-be a few strategic places in the GUI, like wherever a xaccQuery() is
-issued, and wherever an xaccTransCommitEdit() is issued.
-
-Unfortunately, there are a *lot* of places where these calls are
-issued, and therefore, its a lot of work to modify all of these places
-to check for an error condition. It would simplify things if there
-was also a callback medchanism.
-
-Propose:
-Maybe gnc-event.h should be extended to generate events for errors
-as well ...
+\section errorreport How to Report Errors to the GUI
-How about this idea:
+How would the engine->GUI error reporting happen? A direct callback?
+Or having the GUI always check for session errors?
-change gnc_session_push_error() so that it calls
-gnc_engine_generate_event (GUID_of_session, GNC_EVENT_ERROR)
-
-The GUI would register a handler; the handler would call
-gnc_session_get_error() to find out the details of the error; and
-maybe put a popup on the screen, maybe set some flags so that the
-GUI starts working differently...
-
-This would save a *lot* of trouble of having to check the error code
-in the zillion places where CommitEdit is called. Of course, if the
-error occurs, then all the code that executes following the CommitEdit
-is 'suspect', and is potentially buggy/non-robust in the face of that
-error. Alligators lie here ...
+We should use the session error mechanism for reporting these errors.
+Note that the API allows a simple 'try-throw-catch' style error
+handling in C. Because we don't/can't unwind the stack as a true
+'throw' would, we need to make sure that when we "throw" the error,
+it emulates this as best it can: it short-cuts its way up and out of
+the engine, to where its caught in the GUI.
+If there are a *lot* of places where these calls are
+issued, simplify things by implementing your own callback mechanism.
+*/
-============================== END OF DOCUMENT =====================
+============================== END OF DOCUMENT =====================
Index: engine.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/engine.txt,v
retrieving revision 1.2.2.1
retrieving revision 1.2.2.2
diff -Lsrc/doc/engine.txt -Lsrc/doc/engine.txt -u -r1.2.2.1 -r1.2.2.2
--- src/doc/engine.txt
+++ src/doc/engine.txt
@@ -1,13 +1,16 @@
+/** \page engine Engine Framework
+API: \ref Engine
-The engine API documentation can be found in the src/doc/design/engine.texinfo file.
+Additional engine API documentation can be found in the src/doc/design/engine.texinfo file.
This file contains some extra meta-information that is not directly relevant
to the API documentation.
+\section firstclass First Class Objects (C structs) vs. Storing Data in KVP Trees
+
+API: \ref KVP
-First Class Objects (C structs) vs. Storing Data in KVP Trees
--------------------------------------------------------------
Suppose you have a neat idea for a new feature for the GnuCash engine.
Should you create a C structure (a "first class object") and all
of the required machinery for it (e.g. an SQL backend), or should you
@@ -27,15 +30,16 @@
design an appropriate SQL table around it, so that the database
can be queried efficiently and rapidly.
-Terminology:
+\subsection terms Terminology:
-First-class object: something that has a C struct associated with it,
+- First-class object: something that has a C struct associated with it,
and has its own specialized backend infrastructure for storing/quering
it.
-Second-class object: something that lives entirely in a KVP tree.
+- Second-class object: something that lives entirely in a KVP tree.
Note, however, that not all data in a KVP tree deserves to be called
an 'object'. Some things in a KVP tree are merely 'attributes'.
If you push on this point, there is indeed a gray area between
second-class objects and attributes.
+*/
Index: generic-druid-framework.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/doc/generic-druid-framework.txt,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -Lsrc/doc/generic-druid-framework.txt -Lsrc/doc/generic-druid-framework.txt -u -r1.1 -r1.1.2.1
--- src/doc/generic-druid-framework.txt
+++ src/doc/generic-druid-framework.txt
@@ -1,11 +1,11 @@
- Generic (Import) Druid Framework
+/** \page druidframework Generic (Import) Druid Framework
+
Derek Atkins <derek at ihtfp.com>
2004-01-12
Work in progress
-
-0. Background
+\section druidbackground Background
The GNOME Druid infrastructure wants to force you to be UI-driven.
What this means is that the druid is started and lives in gtk_main()
@@ -32,8 +32,7 @@
whenever possible. This means the importer should be GUI-driven, not
backend-driven.
-
-1. The Problem
+\section druidproblem The Problem
For a generic importer druid, we want to create a single druid (or set
of druid components) that all importers can use. Moreover, this
@@ -64,8 +63,7 @@
preference). Each sub-process can have a set of doc pages available
which can be displayed (or not) based on a user preference.
-
-2. The Druid Framework
+\section druidmain The Druid Framework
In order to refrain from pulling Gnome and GTK into the backend
implementations, we need a GUI-independent UI framework for Druids.
@@ -110,8 +108,7 @@
means the import backend should be completely callback-based,
including the cleanup code in case the user interrupts the import.
-
-3. Druid Sub-Process Providers
+\section druidprocess Druid Sub-Process Providers
In order to abstract the Druid from the various importer backends, the
import process is broken into a set of sub-processes. Each
@@ -144,8 +141,7 @@
back-page callback, or any other callbacks required by the specific
provider.
-
-4. Putting the Druid Together
+\section druidtogether Putting the Druid Together
In order to build the druid, the import backend builds the list of
providers and passes that list to the Druid Builder. The Builder
@@ -153,8 +149,7 @@
provider and inserts them into the druid. Finally, the builder
displays the druid and starts the process.
-
-5. Linking into the Backend
+\section druidbackend Linking into the Backend
When supplying the list of providers to the builder, the backend also
provides a set of callbacks. Since the backend knows what providers
@@ -163,16 +158,15 @@
The callback function should process the data, set the next druid
page, and then return.
+\section druidcore Core GncDruid Types
-6. Core GncDruid Types
-
-GncDruidPage
+\subsection druidpage GncDruidPage
Opaque (toolkit-specific) type: a druid page. Used to pass an
opaque object from the provider, through the backend, to the druid
system (e.g. in order to set the druid page).
-GncDruidCB
+\subsection druidcallback GncDruidCB
Base type of a druid callback. Minimum information is the backend context.
@@ -180,24 +174,24 @@
gpointer backend_ctx;
-GncDruid
+\subsection druidobject GncDruid
The context object of a druid. This object contains all the
necessary data to maintain the druid and reference all it's data.
Members:
- void set_page(
- GncDruid,
+ void set_page(\n
+ GncDruid,\n
GncDruidPage);
Set the current page of the druid to the GncDruidPage.
- GncDruidProvider current_provider;
- GncDruidProvider (*next_provider)(GncDruid);
+ GncDruidProvider current_provider;\n
+ GncDruidProvider (*next_provider)(GncDruid);\n
GncDruidProvider (*prev_provider)(GncDruid);
-GncDruidProviderDesc
+\subsection druidproviderdesc GncDruidProviderDesc
The Druid Provider Description base class. This defines the minimal
information to name a provider and provide the interface required to
@@ -207,12 +201,12 @@
Members:
- const gchar *name;
- gboolean (*provider_needed)(GncDruidCB);
- gboolean (*next_cb)(GncDruid, GncDruidCB);
+ const gchar *name;\n
+ gboolean (*provider_needed)(GncDruidCB);\n
+ gboolean (*next_cb)(GncDruid, GncDruidCB);\n
gboolean (*prev_cb)(GncDruid, GncDruidCB);
-GncDruidProvider
+\subsection druidprovider GncDruidProvider
An instance of a Druid Provider. Still toolkit-independent (a
toolkit-specific subclass actually implements the functions
@@ -221,16 +215,15 @@
Members:
- GncDruidPage (*first_page)(GncDruidProvider);
- GncDruidPage (*next_page)(GncDruidProvider);
+ GncDruidPage (*first_page)(GncDruidProvider);\n
+ GncDruidPage (*next_page)(GncDruidProvider);\n
GncDruidPage (*prev_page)(GncDruidProvider);
+\section druidapi The Druid Builder API
-7. The Druid Builder API
-
-GncDruid gnc_druid_build(
- GList *providers,
- gpointer backend_ctx,
+GncDruid gnc_druid_build(\n
+ GList *providers,\n
+ gpointer backend_ctx,\n
void (*end)(gpointer))
Build a druid using the supplied list of providers descriptions
@@ -240,28 +233,26 @@
the case of the user clicking "cancel". It cleans up the backend
context.
+\section druidinternal The Basic (internal) Provider APIs
-8. The Basic (internal) Provider APIs
-
-GncDruidProvider gnc_provider_get_instance(
- GncDruid druid_ctx,
- GncDruidProviderDesc description,
+GncDruidProvider gnc_provider_get_instance(\n
+ GncDruid druid_ctx,\n
+ GncDruidProviderDesc description,\n
gpointer backend_ctx)
Obtain an instance of a Druid Provider based on the Provider
Description. This is used by the druid builder to obtain a Provider
Instance given the Provider Description.
-void gnc_provider_register(
- const gchar* name,
+void gnc_provider_register(\n
+ const gchar* name,\n
gnc_provider_get_instance);
Register a Provider Implementation of the provided name. Provide a
creation function that gnc_provider_get_instance() can use to obtain
a fully initialized provider object.
-
-9. Specific GncDruidProviderDesc APIs
+\section druidproviderapi Specific GncDruidProviderDesc APIs
Each provider needs to create its own subclass of GncDruidProviderDesc
that defines its specific interface to the backend. The following
@@ -276,9 +267,9 @@
Members:
- void (*get_ambiguity)(
- gpointer be_ctx,
- GncImportFormat* choices,
+ void (*get_ambiguity)(\n
+ gpointer be_ctx,\n
+ GncImportFormat* choices,\n
GncImportFormat* last_choice);
GncDruidChooseFmtCB
@@ -294,10 +285,10 @@
Members:
- gboolean multi_file;
- gchar* last_directory;
- GList * (*get_files)(gpointer be_ctx);
- const gchar* (*get_filename)(GncImportFile file);
+ gboolean multi_file;\n
+ gchar* last_directory;\n
+ GList * (*get_files)(gpointer be_ctx);\n
+ const gchar* (*get_filename)(GncImportFile file);\n
void (*remove_file)(gpointer be_ctx, GncImportFile file)
GncDruidSelectFileCB
@@ -305,3 +296,5 @@
Members:
gchar* filename;
+
+*/
Index: kvp_doc.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/kvp_doc.txt,v
retrieving revision 1.35.4.3
retrieving revision 1.35.4.4
diff -Lsrc/engine/kvp_doc.txt -Lsrc/engine/kvp_doc.txt -u -r1.35.4.3 -r1.35.4.4
--- src/engine/kvp_doc.txt
+++ src/engine/kvp_doc.txt
@@ -1,15 +1,14 @@
+/** \page kvpvalues KVP Values used By GnuCash
- KVP Values used By GnuCash
- --------------------------
Date Last Revised: August 2003
+API: \ref KVP
This file documents the use of keys in the key-value pair system
used by the GnuCash Application (both the engine, and non-engine, GUI
pieces). Before assigning keys for use, please read the Key-Value
Policy in the GnuCash Design Document located under src/doc/design.
-
The format of the data below is:
Name: The name of the key, including key names of parent frames
@@ -27,9 +26,9 @@
for using the key here. Also include any API calls which use
the key. If more than one entity can use the key,
-
Example:
+\verbatim
Name: /my-favorite-thing
Type: string
Entities: Account
@@ -37,244 +36,333 @@
This key stores a text description of the user's
favorite thing. Do not use this key to store things
which the user merely likes!
-
+\endverbatim
Please put the keys in alphabetical order.
---------------------------------------------------------------------------
+\section kvpvaluelist List of existing values
+
+[ \ref kvpA ] [ \ref kvpB ] [ \ref kvpC ] [ \ref kvpD ] [ \ref kvpE ]
+[ \ref kvpF ] [ \ref kvpG ] [ \ref kvpH ] [ \ref kvpJ ] [ \ref kvpK ] [ \ref kvpL ]\n
+[ \ref kvpM ] [ \ref kvpN ] [ \ref kvpO ] [ \ref kvpP ] [ \ref kvpQ ]
+[ \ref kvpR ] [ \ref kvpS ] [ \ref kvpT ] [ \ref kvpU ] [ \ref kvpV ] [ \ref kvpW ]
+
+\subsection kvpA A
+
+\subsection kvpB B
+
+\verbatim
Name: /book/
Type: kvp_frame
Entities: Account, Book, Transaction
Use: kvp subdirectory holding info relating to accounting periods, including
the 'twin' of an open/closed account, pointers to the open-balance
transactions, the closing dates, etc.
+\endverbatim
+\verbatim
Name: /book/accounting-period
-Type: string, enum {none, week, month, quarter, trimester, year} XXX not used, should be UIFreqSpec stuff ..
+Type: string, enum {none, week, month, quarter, trimester, year}
+ XXX not used, should be UIFreqSpec stuff ..
Entities: Book
Use: An enumerated identifier indicating how often books are supposed
to be closed. This key will typically be present only in an
open book, as it seems meaningless in a closed book.
+\endverbatim
+\verbatim
Name: /book/close-date
Type: Timespec
Entities: Book
Use: The posted closing date of this book. This book only contains
transactions whose posted date is earlier than this closing date.
+\endverbatim
+\verbatim
Name: /book/closed-acct
Type: GUID
Entities: Transaction
Use: The GUID of the account for which this transaction represents the
opening balance. This value will occur *only* in transactions that
are opening balances.
+\endverbatim
+\verbatim
Name: /book/closed-book
Type: GUID
Entities: Transaction
Use: The GUID of the book for which this transaction represents the
opening balance. This value will occur *only* in transactions that
are opening balances.
+\endverbatim
+\verbatim
Name: /book/log-date
Type: Timespec
Entities: Book
Use: A log of the date which the user performed the closing of the book.
+\endverbatim
+\verbatim
Name: /book/next-acct
Type: GUID
Entities: Account
Use: The GUID of the account that follows this one, chronologically.
Note that the open-date of the next book should equal the close-date
of the book that this account belongs to.
+\endverbatim
+\verbatim
Name: /book/next-book
Type: GUID
Entities: Account, Book
Use: The GUID of the book that follows this one, chronologically.
Note that the open-date of the next book should equal the close-date
of this book.
+\endverbatim
+\verbatim
Name: /book/notes
Type: string
Entities: Book
Use: User-suplied notes for the book. The user can set this to any value
and change it at any time for any reason.
+\endverbatim
+\verbatim
Name: /book/open-date
Type: Timespec
Entities: Book
Use: The posted opening date of this book. This book only contains transactions
whose posted date is later than this closing date.
+\endverbatim
+\verbatim
Name: /book/prev-acct
Type: GUID
Entities: Account
Use: The GUID of the account that preceeds this one, chronologically.
Note that the close-date of the previous book should equal the open-date
of the book that this account belongs to.
+\endverbatim
+\verbatim
Name: /book/prev-book
Type: GUID
Entities: Account, Book
Use: The GUID of the book that preceeds this one, chronologically.
Note that the close-date of the previous book should equal the open-date
of this book.
+\endverbatim
+\verbatim
Name: /book/title
Type: string
Entities: Book
Use: A user-suplied title for the book. The user can set this to any value
and change it at any time for any reason.
------------------------
+\endverbatim
+\subsection kvpC C
+
+\verbatim
Name: /counters/...
Type: int64
Entities: Book
Use: Holders for a bunch of counters for various types. Used specifically
in the business objects for ID counters. The counter name is the path
that follows /counters/, e.g. "/counters/GncCustomer"
-
+\endverbatim
+
+\subsection kvpD D
+
+\subsection kvpE E
------------------------
+\subsection kvpF F
+\verbatim
Name: /from-sched-xaction
Type: GUID
Entities: Transaction
Use: Identifies that the Transaction was created from a ScheduledTransaction,
and stores the GUID of that SX.
+\endverbatim
+\subsection kvpG G
+
+\verbatim
Name: /gains-source
Type: guid
Entities: Split
Use: GUID of the split that is at the source of the cap gains recorded
in this split.
+\endverbatim
+\verbatim
Name: /gains-split
Type: guid
Entities: Split
Use: GUID of the split that records the capital gains for this split.
+\endverbatim
------------------------
-
+\verbatim
Name: /gemini/
Type: kvp_glist
Entities: Account, Book
Use: kvp bag holding frames that identify accounts or books
that are copies of this account.
+\endverbatim
-Name: /gemini/*
+\verbatim
+Name: /gemini/.*
Type: kvp_frame
Entities: Account, Book
Use: bag value holds a frame that identifies a single copied account.
Other copies would appear in other bag values.
+\endverbatim
-Name: /gemini/*/acct_guid
+\verbatim
+Name: /gemini/<type>/acct_guid
Type: guid
Entities: Account
Use: guid of another account that is a copy of this one.
+\endverbatim
-Name: /gemini/*/book_guid
+\verbatim
+Name: /gemini/<type>/book_guid
Type: guid
Entities: Account, Book
Use: When this appears in an account, then it contains the guid of
the book that the other account belongs to. When this appears
in a book, then this is the guid of the other book.
+\endverbatim
-Name: /gemini/*/date
+\verbatim
+Name: /gemini/<type>/date
Type: timespec
Entities: Account, Book
Use: date that the copy was created.
+\endverbatim
------------------------
+\subsection kvpH H
+\verbatim
Name: /hbci/
Type: frame
Entitites: Account, Book
Use: subdirectory for information related to the German online banking
protocol HBCI
+\endverbatim
+\verbatim
Name: /hbci/account-id
Type: string
Entities: Account
Use: HBCI Account code of the HBCI counterpart of this gnucash account
in the real world
+\endverbatim
+\verbatim
Name: /hbci/bank-code
Type: string
Entitites: Account
Use: Bank code of HBCI account
+\endverbatim
+\verbatim
Name: /hbci/country-code
Type: gint64
Entitites: Account
Use: Country code of the bank of HBCI account
+\endverbatim
+\verbatim
Name: /hbci/trans-retrieval
Type: Timespec
Entities: Account
Use: Time of the last statement retrieval through HBCI for this
specific account
+\endverbatim
+\verbatim
Name: /hbci/config-filename
Type: string
Entitied: Book
Use: OpenHBCI configuration file name, where the real HBCI
configuration for the OpenHBCI library can be found
+\endverbatim
+
+\subsection kvpJ J
------------------------
+\subsection kvpK K
+\subsection kvpL L
+
+\verbatim
Name: last-num
Type: string
Entities: Account
Use: xaccAccountGetLastNum, xaccAccountSetLastNum
Store the last number used in an account's transactions.
Used in auto-filling the Num field.
+\endverbatim
------------------------
-
+\verbatim
Name: /lot-mgmt/
Type: kvp_frame
Entities: Account
Use: Frame holding info regarding how lots should be managed in this
account, including what accounting policy to use, where realized
gains should be reported, and etc.
+\endverbatim
+\verbatim
Name: /lot-mgmt/gains-acct/
Type: frame
Entities: Account
Use: When a lot in this account is double-balanced, this frame
holds per-currency accounts to which realized gains are to
be posted.
+\endverbatim
+\verbatim
Name: /lot-mgmt/gains-acct/xxxxx
Type: guid
Entities: Account
Use: When a lot in this account is double-balanced, this key specifies
the account to which realized gains are to be posted.
+\endverbatim
+\verbatim
Name: /lot-mgmt/next-id
Type: int64
Entities: Account
Use: The next unused lot id number, used to autogenerate
a lot title.
+\endverbatim
-
+\verbatim
Name: /lot-split/
Type: kvp_glist
Entities: Split
Use: A bag of kvp frames holding identification of splits
that were split off of this split. Same style as the
/gemini/, look there for additional doco's.
+\endverbatim
-Name: /lot-split/*/peer_guid
+\verbatim
+Name: /lot-split/<type>/peer_guid
Type: GUID
Entities: Split
Use: The GUID of the peer split which was split from this split.
+\endverbatim
------------------------
+\subsection kvpM M
+\subsection kvpN N
+
+\verbatim
Name: /notes
Type: string
Entities: Account, Lot, Transaction
@@ -282,26 +370,36 @@
any value and change it at any time for any reason.
Accessors: xaccAccountGetNotes(), xaccAccountSetNotes(),
xaccTransGetNotes(), xaccTransSetNotes()
+\endverbatim
+
+\subsection kvpO O
+\verbatim
Name: old-currency
Type: string
Entities: Account
Use: This string holds the canonical name of the old Account
currency. This may be deleted at some point in the future.
+\endverbatim
+\verbatim
Name: old-currency-scu
Type: gint64
Entities: Account
Use: This holds the old currency scu. This may be deleted at
some point in the future.
+\endverbatim
+\verbatim
Name: old-docref
Type: string
Entities: Transactions, Splits
Use: This string holds the old Docref value which was supported in earlier
versions of GnuCash but which was never used for any purpose. The
value is retained in case any users were making use of it.
+\endverbatim
+\verbatim
Name: old-price-source
Type: string
Entities: Account
@@ -310,47 +408,67 @@
this value will be deprecated when the new version of Finance::Quote
is fully supported. The new version of Finance::Quote uses a different
scheme to identify sources for price quotes.
+\endverbatim
+\verbatim
Name: old-security
Type: string
Entities: Account
Use: This string holds the canonical name of the old Account
security. This may be deleted at some point in the future.
+\endverbatim
+\verbatim
Name: old-security-scu
Type: gint64
Entities: Account
Use: This holds the old security scu. This may be deleted at
some point in the future.
+\endverbatim
+
+\subsection kvpP P
------------------------
+\subsection kvpQ Q
+\subsection kvpR R
+
+\verbatim
Name: /reconcile-info/
Type: frame
Entities: Account
Use: store reconcile information about accounts
+\endverbatim
+\verbatim
Name: /reconcile-info/include-children
Type: gint64
Entities: Account
Use: A boolean flag indicating whether transactions in sub-accounts should be
included during reconcilition.
+\endverbatim
+\verbatim
Name: /reconcile-info/last-date
Type: frame
Entities: Account
Use: store the statement date of the last reconciliation
+\endverbatim
+\verbatim
Name: /reconcile-info/postpone/date
Type: gint64
Entities: Account
Use: store the ending statement date of a postponed reconciliation
+\endverbatim
+\verbatim
Name: /reconcile-info/postpone/balance
Type: numeric
Entities: Account
Use: store the ending balance of a postponed reconciliation
+\endverbatim
+\verbatim
Name: /reconcile-info/auto-interest-transfer
Type: string
Entities: Account
@@ -358,82 +476,114 @@
"Automatic interest transfer" on a per-account basis.
Acceptable values are "true" and "false".
(This really could use a KVP_TYPE_BOOLEAN.)
+\endverbatim
------------------------
+\subsection kvpS S
+\verbatim
Name: /sched-xaction/
Type: frame
Entities: Split in a SchedXaction
Use: Storage for the various fields of a scheduled transaction's
template Splits.
+\endverbatim
+\verbatim
Name: /sched-xaction/account
Type: GUID
Entities: Split associated with a SchedXaction
Use: The GUID of this Split's xfrm account.
+\endverbatim
+\verbatim
Name: /sched-xaction/credit-formula
Type: string
Entities: Split associated with a SchedXaction
Use: Store the formula for the credit side of the split
+\endverbatim
+\verbatim
Name: /sched-xaction/debit-formula
Type: string
Entities: Split associated with a SchedXaction
Use: Formula for the debit. Either the credit or the
debit formula must be empty.
+\endverbatim
------------------------
-
+\verbatim
Name: split-type
Entities: Split
Use: xaccSplitGetType, xaccSplitMakeStockSplit
Store a string representing the type of split, if not normal.
+\endverbatim
+
+\subsection kvpT T
+\verbatim
Name: /tax-US/code
Type: string
Entities: Account
Use: see src/scm/report/[tax,txf]*.scm
+\endverbatim
+\verbatim
Name: /tax-US/payer-name-source
Type: string
Entities: Account
Use: see src/scm/report/[tax,txf]*.scm
+\endverbatim
+\verbatim
Name: tax-related
Type: gint64
Entities: Account
Use: A boolean flag indicated whether the Account is tax-related.
+\endverbatim
+\verbatim
Name: /title
Type: string
Entities: Lot
-Use: A user-suplied title for the lot. The user can set this to
+Use: A user-supplied title for the lot. The user can set this to
any value and change it at any time for any reason.
+\endverbatim
+\verbatim
Name: trans-date-due
Type: Timespec
Entities: Transaction
Use: Accounts/Receivable, Accounts/Payable Due Date.
+\endverbatim
+\verbatim
Name: trans-txn-type
Type: string
Entities: Transaction
Use: A/R, A/P Transaction Type (Invoice or Payment)
+\endverbatim
+\subsection kvpU U
+
+\verbatim
Name: user-keys
Type: frame
Entities: All
Use: This frame is used to store keys which are editable directly by
the user. The program should not attach any semantics to keys
under this frame.
+\endverbatim
+
+\subsection kvpV V
+\verbatim
Name: void-reason
Type: string
Entities: Transaction
Use: This string is used to store the reason why a transaction has been
voided. Note that it should only exist if the transaction has been voided.
+\endverbatim
+\verbatim
Name: void-former-amount
Type: gnc_numeric
Entities: Split
@@ -441,5 +591,9 @@
that it should only exist if the parent transaction has been voided (but
checking the reconcile status of the split is a more direct way of finding
out a split has been voided).
+\endverbatim
+
+\subsection kvpW W
+*/
--------------------------- end of document ------------------------
Index: extensions.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/extensions.txt,v
retrieving revision 1.6
retrieving revision 1.6.6.1
diff -Lsrc/engine/extensions.txt -Lsrc/engine/extensions.txt -u -r1.6 -r1.6.6.1
--- src/engine/extensions.txt
+++ src/engine/extensions.txt
@@ -1,16 +1,16 @@
+/** \page gnucashextension Proposed GnuCash Extensions
-Proposed Extensions
--------------------
The following are proposals for various, as-yet-unimplemented
enhancements. The goal of this document is to understand some
of the changes that will come soon to the interfaces.
-Accounting Periods
-------------------
+\section accountperiods Accounting Periods
+
Acconting periods are implemented by creating an object that
describes the accounting period, and then assigning every
transaction to at least one period.
+\verbatim
typedef struct _accountingPeriod {
GUID guid; // id
char *name; // user-selectable name
@@ -19,6 +19,7 @@
Timespec * end_date;
AccountGroup *topgrp; // chart of accounts for this period.
} AccountingPeriod;
+\endverbatim
The Transaction struct has to be extended with a period guid.
Every transaction can belong to at most one accounting period.
@@ -29,27 +30,24 @@
closed books. Basically, a new chart of accounts needs to be written
out/read from the engine for each new accounting period.
-
The xaccPeriodClose() subroutine performs the following:
--- crawl over all transactions and mark them as being part of this
+- crawl over all transactions and mark them as being part of this
accounting period (actually, new transactions should by default be
getting put into the currently open period...)
--- find the equity account (what if there is more than one equity account
+- find the equity account (what if there is more than one equity account
?? what if equity has sub-accounts ?? )
--- transfer all income/expense to equity (shouldn't the equity account
+- transfer all income/expense to equity (shouldn't the equity account
match the income/expense heirarchy?)
--- return a new account group with new opening balances ...
-
+- return a new account group with new opening balances ...
+\section transactionchanges Changes to Transaction Structure
-Changes to Transaction Structure
---------------------------------
Add an accounting period guid (see above).
-Changes to Journal Entry (Split) Structure
-------------------------------------------
-Voucher Reference
------------------
+\section splitchanges Changes to Journal Entry (Split) Structure
+
+\subsection splitvoucher Voucher Reference
+
Add a char * voucher; This is a generic id string that somehow
identifies the piece of paper/electronic document(s) that indicate
where/how to find the paper trial for this entry. This list of id's
@@ -58,19 +56,15 @@
that the user wants to store. For the SQL backend, this is a key
to a user-definable table.
-====================================================================
-
-Additional Banking Info
+\section bankingchanges Additional Banking Info
BankId -- routing & transit number (US) or Bankleitzan (DE) or Banque (FR)
BranchID -- Agence (FR), blank for other countries
AcctKey -- Cle (FR), blank in others
-
Account type enumerants:
bank account types:
checking, savings, moneymarket, creditline, cma (cash amangement account)
-
-
+*/
Index: design.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/engine/design.txt,v
retrieving revision 1.24
retrieving revision 1.24.6.1
diff -Lsrc/engine/design.txt -Lsrc/engine/design.txt -u -r1.24 -r1.24.6.1
--- src/engine/design.txt
+++ src/engine/design.txt
@@ -1,11 +1,26 @@
+/** \page backendold Engine Architecture (old)
+
+API: Backend
+
+\section oldintro Introduction
+
This document is becoming obsolete. Please refer to the design
documentation in src/doc/design for a complete description of the
Engine architecture.
+http://code.neil.williamsleesmill.me.uk/texi/gnucash-design_4.html#SEC30
+
+The only remaining architecture flaw is related to the GnuCash XML v2
+backend modularisation. QofSession includes a dynamic method of loading
+a QofBackend that supercedes the use of gnc_module_load that currently
+loads the module using guile/scheme. When the old XML backend is replaced
+by Sqlite, this will be resolved.
+
+Note that this flaw <b>does not appear in QOF</b> itself. The C code
+enabling the entire guile/scheme load mechanism is GnuCash only.
+
+\subsection oldflaw Architecture Flaw
-Architecture Flaw
------------------
-A few areas in the engine are marked 'FIXME: architecture flaw'.
-What does this really mean? There is a Soviet joke from the 1960's:
+What does Architecture Flaw really mean? There is a Soviet joke from the 1960's:
A westerner in Moscow stops a man to ask him the time. The man puts
down his breifcase, and flicks his wrist to look at his watch. "The
@@ -14,21 +29,20 @@
interest, "Why, that's a mighty fine watch you have there! We don't
have anything like that in the America!" The Soviet responds, "Why
yes, this demonstrates the superiority of Soviet engineering over
-decadent captalist design." Stooping to pick up his breifcase,
+decadent captalist design." Stooping to pick up his briefcase,
he mumbles half to himself, "If only these batteries weren't so heavy."
-There are a few places where the engine requires the use of guile.
-These should be eliminated.
+There is only one place where the engine requires the use of guile.
+This is the remaining architecture flaw, see above.
+\section oldreview Accounting Engine
-Accounting Engine
------------------
This document reviews the operation of, and various design points
pertinent to the GnuCash accounting engine. The latest version
of this document can be found in the engine source-code directory.
-Stocks, non-Currency-Denominated Assets
----------------------------------------
+\section enginestock Stocks, non-Currency-Denominated Assets
+
The engine includes support for non-currency-denominated assets,
such as stocks, bonds, mutual funds, inventory. This is done with
two values in the Split structure:
@@ -60,10 +74,10 @@
Thus, for example, the purchase of shares can be represented as:
- source:
+ source:\n
debit ABC Bank for $1045 (1045 dollars * dollar "price" of 1.00)
- destination:
+ destination:\n
credit PQR Stock for $1000 (100 shares at $10 per share)
credit StockBroker category $45 in fees
@@ -71,10 +85,10 @@
be at least one common currency/security between all of them. Thus,
for example:
- source:
+ source:\n
debit ABC Bank for $1045 (1045 dollars * dollar "price" of 1.00)
- destination:
+ destination:\n
credit VolkTrader for 2000 DM (1000 dollars at 2.0 mark per dollar)
credit Fees category $45 in fees
@@ -86,8 +100,8 @@
Note that we ignored the price when adding the second split.
-Recoding a Stock Price
-----------------------
+\subsection enginestock Recoding a Stock Price
+
A stock price may be recorded in a brokerage account with a single
split that has zero value:
(share price) * (zero shares) == (zero dollars)
@@ -97,19 +111,20 @@
requires at least two splits to balance. (at least when double-entry
is enabled).
-Recording a Stock Split
------------------------
+\subsection engineplit Recording a Stock Split
+
Stock splits (i.e. when a company issues x shares of new stock for every
share already owned) may be recorded with a pair of journal entries as
follows:
(-old num shrs) * (old price) + (new num shrs) * (new price) == 0.0
+
where each journal entry credits/debits the same account.
Of course (new num shrs) == (1+x) * (old num shrs)
and the price goes inversely.
-Stock Options
--------------
+\section enginestock Stock Options
+
Stock options are not currently supported. To support them, the
following needs to be added:
@@ -133,38 +148,37 @@
the ability to purchase (with a call option) or sell (with a put option)
100 shares of the underlying stock.
+\seection engineerror Error Reporting
-Error Reporting
----------------
The error reporting architecture (partially implemented), uses a globally
visible subroutine to return an error. In the naivest possible implementation,
the error reporting mechanism would look like this:
-
- int error_num; /* global error number */
+\verbatim
+ int error_num; // global error number
int xaccGetError (void) { return error_num; }
void xaccSomeFunction (Args *various_args) {
if (bad_thing_happened) error_num = 42;
}
-
+\endverbatim
Many programmers are used to a different interface, e.g.
-
+\verbatim
int xaccSomeFunction (Args *various_args) {
if (bad_thing_happened) return (42);
}
-
+\endverbatim
Because of this, it is important to explain why the former design was
choosen over the latter. Let us begin by listing how the choosen design
is as good as, and in many ways can be better to the later design.
- (1) Allows programmer to check for errors asynchronously, e.g. outside
+-# Allows programmer to check for errors asynchronously, e.g. outside
of a performance critical loop, or far away, after the return of
several subroutines.
- (2) (with the right implementation) Allows reporting of multiple, complex
+-# (with the right implementation) Allows reporting of multiple, complex
errors. For example, it can be used to implement a trace mechanism.
- (3) (with the right implementation) Can be thread safe.
- (4) Allows errors that occurred deep in the implementation to be reported
+-# (with the right implementation) Can be thread safe.
+-# Allows errors that occurred deep in the implementation to be reported
up to much higher levels without requiring baggage in the middle.
The right implementation for (2) is to implement not a single
@@ -173,54 +187,51 @@
implementation for (3) is the use pthread_getspecific() to define a
per-thread global and/or ring/queue.
+\section engineisolation Engine Isolation
-Engine Isolation
-----------------
Goals of engine isolation:
- o Hide the engine behind an API so that multiple, pluggable engines
+- Hide the engine behind an API so that multiple, pluggable engines
could be created, e.g. SQL or CORBA.
- o Engine users are blocked from being able to put engine internal
+- Engine users are blocked from being able to put engine internal
structures in an inconsistent state. Updates are "atomic".
Some half-finished thoughts about the engine API:
--- The engine structures should not be accessible to any code outside
+- The engine structures should not be accessible to any code outside
of the engine. Thus, the engine structures have been moved to
AccountP.h, TransactionP.h, etc.
The *P.h files should not be included by code outside of the engine.
-
--- The down-side of hiding is that it can hurt performance. Even trivial data
+- The down-side of hiding is that it can hurt performance. Even trivial data
accesses require a subroutine call. Maybe a smarter idea would be to leave
the structures exposed, allow direct manipulation, and then "copy-in" and
"copy-out" the structures into parallel structures when a hidden back end
needs to be invoked.
-
--- the upside of hiding behind an API is that the engine can be
+- the upside of hiding behind an API is that the engine can be
instrumented with extension language (perl, scheme, tcl, python) hooks
for pre/post processing of the data. To further enable such hooks, we
should probably surround all operations on structures with "begin-edit"
and "end-edit" calls.
-
--- begin/end braces could potentially be useful for two-phase commit schemes.
+- begin/end braces could potentially be useful for two-phase commit schemes.
where "end-edit" is replaced by "commit-edit" or "reject-edit".
+\section enginereconcile Reconciliation
-Reconciliation
---------------
The 'reconcile' state of a transaction can have one of the following values:
-/* Values for the reconciled field in Transaction: */
-#define NREC 'n' /* not reconciled or cleared */
-#define CREC 'c' /* The transaction has been cleared */
-#define YREC 'y' /* The transaction has been reconciled */
-#define FREC 'f' /* frozen into accounting period */
+\verbatim
+// Values for the reconciled field in Transaction:
+#define NREC 'n' // not reconciled or cleared
+#define CREC 'c' // The transaction has been cleared
+#define YREC 'y' // The transaction has been reconciled
+#define FREC 'f' // frozen into accounting period
+\endverbatim
(Note that FREC is not yet used/implemented ...)
The process of reconciliation works as follows:
-1) User enters new transaction. All splits are marked 'n' for 'new'
+-# User enters new transaction. All splits are marked 'n' for 'new'
or 'no, not yet reconciled'.
-2) User beleives that the transaction has cleared the bank,
+-# User beleives that the transaction has cleared the bank,
e.g. that a cheque written out has been deposited/cashed.
User clicks in the 'R' column in the register gui,
marking the split 'c' for 'cleared'. User can freely
@@ -228,7 +239,7 @@
no complaints. This is a 'safe' operation. Note that the
register shows the 'cleared' subtotal, which is, essentially,
a guess of the banks view of the account balance.
-3) When user gets the bank statement, user launches the
+-# When user gets the bank statement, user launches the
reconcile dialogue. This dialogue is used to match transactions
on the bank statement with which is recorded locally.
Reconciled transactions are marked with a 'y'.
@@ -238,7 +249,7 @@
the ordinary register dialogue. It should be sort-of
'set in stone'. (The engine does NOT enforce this,
only the gui enforces this.)
-4) When the books are closed, all splits should be marked
+-# When the books are closed, all splits should be marked
'frozen', and become truly un-editable. The engine should
enforce 'frozen', and just plain not allow editing of closed
books, period. The only wat to change this would have been
@@ -246,6 +257,7 @@
change all 'f' to 'y'.)
About storing dates associated with reconcile:
+\verbatim
> I think that there should be a date stamp attached to the reconciliation
> field so that as well as knowing that it has been reconciled, you also
> know *when* it was reconciled.
@@ -264,14 +276,14 @@
>
> It's not terribly important for cheques that get cashed right away; it *is*
> for things that hang around uncashed for a while.
+\endverbatim
If the above is implemented, what date should be stored if the user
toggles the recn flag a few time? The date of the last toggle?
The very first date that it was recn'ed?
+\section enginebackup Automatic Backup
-Automatic Backup
-----------------
The following has been implemented:
Have (by default) xacc create a backup file
@@ -288,9 +300,8 @@
To a limited degree, it provides atomicity/consistency/etc at the
course-grained account-group level.
+\section enginetransaction Transaction Processing
-Transaction Processing
-----------------------
There is a rudimentary level of "TP" build in, via the routines
xaccTransBeginEdit(), xaccTransRollbackEdit(), and xaccTransCommitEdit(),
which allow changes to be made to a transaction, and then commited,
@@ -311,6 +322,7 @@
The SQL back-end should implement posting entirely in the
'Commit()' routine. The pseudo-algorithms should look as follows:
+\verbatim
BeginEdit () {
// save a copy of what it was before we start editing
old_transaction = this;
@@ -343,6 +355,7 @@
this = old_transaction;
old_transaction = NULL;
}
+\endverbatim
The GUI should check to make sure that the Commit() routine didn't fail.
If it did fail, then the GUI should pop up a notice to the user stating
@@ -351,10 +364,8 @@
other human user might have changed the data so that they could
coordinate as needed.)
+\section enginelogs Journal Logs
-
-Journal Logs
-------------
The following has been implemented; see TransLog.c for details.
Transaction logs. The idea was that every time a transaction
@@ -369,16 +380,18 @@
In effect, you'd have things like
+\verbatim
=== 97/01/01 04:32:00 === Add Transaction ==== [whatever was added] ====
=== 97/01/01 04:32:02 === Delete Transaction ==== [whatever was deleted] ====
+\endverbatim
It also is a useful debugging tool, as if you make sure that the
"log_transaction()" call starts by opening the log file, writes, and
then closes and syncs, you know what is going on with the data even if
horrible things happen to the "master" database file.
-Session Mgmt
-------------
+\section enginemanagement Session Management
+
To allow the user of the engine some guarantee of atomic updates,
serialized file I/O, related miscellany, the concept of a session
is supported. No file IO can be performed until a session has
@@ -393,24 +406,27 @@
stock-quote update daemon running under a different pid doesn't trash
data being currently edited by the user.
+\section enginetodo Remaining Work Items
-Remaining Work Items
---------------------
To find other remaining work items in the code, grep for the string
"hack alert".
+See also the \ref todo.
-Ideas for engine enhancements:
------------------------------
- 1) Have (by default) gnucash immediately re-read a file after every
- write, and compare the two resulting AccountGroups for equality.
+\section engineenhance Ideas for engine enhancements:
+-# Have (by default) gnucash immediately re-read a file after every
+ write, and compare the two resulting AccountGroups for equality.\n
During development, this is a good idea, as it will help uncover
thinko's more quickly, instead of letting them hide for weeks or months
(as the last one did). Its not a bad self-consistency check when
- monkeying with the internals, damn the performance.
-
+ monkeying with the internals, damn the performance.\n
It can be removed/disabled for product versions.
+\section olddate Needs updating.
This document is dated May 2000
+
+Updated the architecture flaw section, June 2005.
+
+*/
Index: startup-design.txt
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/scm/startup-design.txt,v
retrieving revision 1.4
retrieving revision 1.4.6.1
diff -Lsrc/scm/startup-design.txt -Lsrc/scm/startup-design.txt -u -r1.4 -r1.4.6.1
--- src/scm/startup-design.txt
+++ src/scm/startup-design.txt
@@ -1,27 +1,23 @@
-The startup process looks like this right now:
+/** \page schemestart Scheme startup process
- * gnucash is a hybrid /bin/sh and guile script which first execs
+\section current The startup process looks like this right now:
+
+- gnucash is a hybrid /bin/sh and guile script which first execs
gnucash-env on itself to set up the proper environment and then
run the rest of the code in the gnucash file as a guile script.
-
- * from the gnucash script itself, the (gnucash bootstrap) is loaded,
+- from the gnucash script itself, the (gnucash bootstrap) is loaded,
and then control transfers to the scheme function, main.
-
- * the current module is set to (gnucash bootstrap) -- this is a hack
+- the current module is set to (gnucash bootstrap) -- this is a hack
and should change later.
-
- * gnc:main is called to finish starting up the application.
-
- * parse the command line
-
- * load the system config if we haven't already (there's a
- command-line option to load the file earlier,
- --load-system-config)
-
- * load the user's ~/gnucash/config.user if it exists, otherwise
+- gnc:main is called to finish starting up the application.
+- parse the command line
+- load the system config if we haven't already (there's a
+ command-line option to load the file earlier, --load-system-config)
+- load the user's ~/gnucash/config.user if it exists, otherwise
load the user's ~/gnucash/config.auto if it exists.
config.auto is where we'll eventually spit out UI selected prefs.
+*/
----- %< -------------------------------------------- >% ------
Rob Browning <rlb at cs.utexas.edu> PGP=E80E0D04F521A094 532B97F5D64E3930
More information about the gnucash-changes
mailing list