From d84638045acc47e8a299520931f3191add30b8e7 Mon Sep 17 00:00:00 2001
From: John Wiegley <johnw@newartisans.com>
Date: Tue, 24 Feb 2009 03:56:27 -0400
Subject: [PATCH] Added note to docs about "primary" commodities

Whenever a commodity is exchanged for another in a posting, one of the
two is considered "primary", and the other secondary.  Primariness of a
commodity is remembered, since the --market option only renders balances
into secondary commodities, never primaries.  To render primaries, use
the --exchange=COMMODITY option.

In all of the following examples, the P commodity is considered primary
and the S is secondary (the P at the beginning of the line indicates a
price-setting directive):

    2009/01/01 Sample 1a
        Assets:Brokerage:Stocks                100 S
        Assets:Brokerage:Cash                 -100 P

    P 2009/01/15 00:00:00 S 2 P

    2009/02/01 Sample 2a
        Assets:Brokerage:Stocks                100 S @ 1 P
        Assets:Brokerage:Cash

    P 2009/02/01 00:00:00 S 4 P

    2009/03/01 Sample 3a
        Assets:Brokerage:Stocks                100 S @@ 100 P
        Assets:Brokerage:Cash

    P 2009/03/01 00:00:00 S 8 P

    2009/04/01 Sample 4a
        Assets:Brokerage:Cash                  100 P
        Assets:Brokerage:Stocks               -100 S {1 P}

    P 2009/04/01 00:00:00 S 16 P
---
 doc/ledger.texi | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/doc/ledger.texi b/doc/ledger.texi
index b2ac29dd..3b0785eb 100644
--- a/doc/ledger.texi
+++ b/doc/ledger.texi
@@ -3942,6 +3942,45 @@ That is the extent of the XML data format used by Ledger.  It will
 output such data if the @command{xml} command is used, and can read
 the same data.
 
+@chapter Random things
+
+Whenever a commodity is exchanged for another in a posting, one of the
+two is considered @emph{primary}, and the other secondary.
+Primariness of a commodity is remembered, since the @option{--market}
+option only renders balances into secondary commodities, never
+primaries.  To render primaries, use the @option{--exchange=COMMODITY}
+option.
+
+In all of the following examples, the P commodity is considered primary
+and the S is secondary (the P at the beginning of the line indicates a
+price-setting directive):
+
+@smallexample
+2009/01/01 Sample 1a
+    Assets:Brokerage:Stocks                100 S
+    Assets:Brokerage:Cash                 -100 P
+
+P 2009/01/15 00:00:00 S 2 P
+
+2009/02/01 Sample 2a
+    Assets:Brokerage:Stocks                100 S @ 1 P
+    Assets:Brokerage:Cash
+
+P 2009/02/01 00:00:00 S 4 P
+
+2009/03/01 Sample 3a
+    Assets:Brokerage:Stocks                100 S @@ 100 P
+    Assets:Brokerage:Cash
+
+P 2009/03/01 00:00:00 S 8 P
+
+2009/04/01 Sample 4a
+    Assets:Brokerage:Cash                  100 P
+    Assets:Brokerage:Stocks               -100 S @{1 P@}
+
+P 2009/04/01 00:00:00 S 16 P
+@end smallexample
+
 @chapter Anatomy of a journal file
 
 Everything begins with a journal file---the anatomy of which is covered