Christian Stimming's update to the currency documentation.

git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@3681 57a11ea4-9604-0410-9ed3-97b8803252fd

src/doc/currencies.txt

@@ -0,0 +1,52 @@
+From Bill Gribble <grib@billgribble.com>
+Tue, 3 Oct 2000 11:09:54 -0500 
+
+We need to fix a single way of dealing with this that
+addresses all of the concerns.  Maybe we should list the
+problems/requirements to make sure we are talking about the same
+thing.  I know I've repeated several times that I believe the
+"eliminate Currency accounts" problem-set is separable from the
+"global A=L+E" problem-set; I'll list them all together here, because
+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
+    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
+    semantics.
+  - 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
+    accounting equation (and all account balances) in a
+    user-selectable functional currency.
+
+I think the following bits will address the first three issues above.
+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
+    '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
+    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.
+
+The balancing semantics of this approach are unambiguous, no existing
+balanced gnucash transactions would be disallowed (the transaction's
+common currency just gets saved in a pointer) and the fuzzy
+distinction between the account's currency, security, damount, value
+is cleared up.
+
+About the last point, the global accounting equation.  Evaluating this
+equation requires the computation of current asset values and
+unrealized gains/losses.  I believe this is possible in a
+straightforward way using the reporting framework, a user-selectable
+functional currency, accepted accounting policies, and a historical
+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.

src/engine/Account.h

@@ -201,16 +201,19 @@ const char *   xaccAccountGetDescription (Account *account);
 const char *   xaccAccountGetNotes (Account *account);
 
 /* New commodity access routines.
- * In the near future, there will only be one commodity associated
- * with an account, rather than two.  Use the 
- * xaccAccountSetCommodity() and xaccAccountGetCommodity() 
+ *
+ * In the near future, the account structure will no longer store two
+ * commodities ('currency' and 'security'). Instead it will store only
+ * one commodity, that is the one formerly known as 'security'.  Use
+ * the xaccAccountSetCommodity() and xaccAccountGetCommodity()
  * routines to set and fetch it.
  *
- * Basically, the next version of the engine will eliminate the 
+ * Basically, the next version of the engine will eliminate the
  * 'currency' field of the Account structure.  Instead, the common
- * currency will be stored with the transaction.  This will 
- * vastly simplify inter-account transfers.
- */
+ * currency will be stored with the transaction.  The 'value' of a
+ * split is a translation of the Split's 'damount' (which is the
+ * amount of the Account's commodity involved) into the Transaction's
+ * balancing currency.  */
 #define xaccAccountGetCommodity xaccAccountGetEffectiveSecurity
 void xaccAccountSetCommodity (Account *account, const gnc_commodity *comm);
 

src/engine/AccountP.h

@@ -91,11 +91,26 @@ struct _account {
    */
   GNCAccountType type;
 
-  /* The currency field denotes the default currency in which all
-   * splits in this account are denominated.  The gnc_commodity type
-   * represents the namespace, full name, and symbol for the currency.
-   * Currency trading accounts allow splits between accounts when the
-   * currency string matches the security string.  */
+  /* Old semantics: The currency field denotes the default currency in
+   * which all splits in this account are denominated.  Currency
+   * trading accounts allow splits between accounts when the currency
+   * string matches the security string.
+   *
+   * The gnc_commodity type represents the namespace, full name, and
+   * symbol for the currency.
+   *
+   * New semantics, likely to appear soon: This account structure will
+   * no longer store a 'currency' and a 'security'. Instead it will
+   * store only one commodity (i.e. currency), that is the one
+   * formerly known as 'security'.  The 'damount' of each split
+   * represents the transferred amount in the account's commodity
+   * (formerly known as security).
+   *
+   * Meanwhile, we'll be in a transition period, where we store the
+   * currency both in the account and the transaction. Warning
+   * messages will print to the screen if things don't go well.
+
+*/
   const gnc_commodity * currency;
   const gnc_commodity * security;
   int  currency_scu;

src/engine/Transaction.h

@@ -227,9 +227,13 @@ Timespec      xaccTransRetDatePostedTS (Transaction *trans);
 int           xaccTransCountSplits (Transaction *trans);
 
 /* --------------------------------------------------------------- */
-/* Commmodities.  Most of the commodty routines below are/will
+/* Commmodities.  Most of the commodity routines below are/will
  * be obsolescent.  They will all be replaced by two routines:
  * xaccTransSet/GetCurrency().  
+ *
+ * Semantics: Each transaction's 'currency' is by definition the
+ * balancing common currency for the splits in that transaction.
+ *
  * The xaccTransGetCurrency() routine will give the same result
  * as xaccTransFindCommonCurrency(), except that 'finding' won't
  * be necessary: the common currency will be stored with the 
@@ -237,14 +241,16 @@ int           xaccTransCountSplits (Transaction *trans);
  * always avaiable, thus eliminating the need for many of the other
  * checks and comparisons.
  *
- * Note side effect: the Account structure will no longer store
- * a currency.   Meanwhile, we'll be in a transition period, where
- * we store teh currency both in the account and the transaction. 
- * Warning messages will print to the screen if things don't go well.
- * If there are no warnings after a few months, then we'll make the
- * transition permanent.  Meanwhile, the xaccTransSetCurrency()
- * will attempt to do 'the right thing'.
- */
+ * Note side effect: the Account structure will no longer store a
+ * 'currency' and a 'security'. Instead it will store only one
+ * commodity (i.e. currency), that is the one formerly known as
+ * 'security'.  Meanwhile, we'll be in a transition period, where we
+ * store the currency both in the account and the transaction. Warning
+ * messages will print to the screen if things don't go well.  If
+ * there are no warnings after a few months, then we'll make the
+ * transition permanent.  Meanwhile, the xaccTransSetCurrency() will
+ * attempt to do 'the right thing'.
+ * */
 
 #define xaccTransGetCurrency xaccTransFindCommonCurrency
 void xaccTransSetCurrency (Transaction *trans, 

src/engine/TransactionP.h

@@ -103,10 +103,12 @@ struct _split
   char    reconciled;        /* The reconciled field                      */
   Timespec date_reconciled;  /* date split was reconciled                 */
 
-  /* 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. */
+  /* New semantics: 'value' is the amount of the transaction balancing
+   * commodity (i.e. currency) involved, 'damount' is the amount of
+   * the account's commodity (formerly known as 'security') involved.
+   *
+   * Old semantics: value is the amount of the account's currency 
+   * involved, damount is the amount of the account's security.  */
   gnc_numeric  value;         
   gnc_numeric  damount;  
 
@@ -154,17 +156,17 @@ struct _transaction
   kvp_frame * kvp_data;
 
 
-  /* 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.  However, right now we are in a transition period:
-   * we store it here an in the account, and test its value dynamically
+  /* The common_currency field is the balancing common currency for
+   * all the splits in the transaction. 
+   *
+   * This field is going to replace the currency field in the account
+   * structures.  However, right now we are in a transition period: we
+   * store it here an in the account, and test its value dynamically
    * for correctness.  If we can run for a few months without errors,
    * then we'll make the conversion permanent.
    *
    * Alternate, better(?) name: "valuation currency": it is the
-   * currency in which all of the splits can be valued.
-   */
+   * currency in which all of the splits can be valued.  */
   const gnc_commodity *common_currency;
 
   /* version number, used for tracking multiuser updates */