doc update

ledger.texi

@@ -2995,6 +2995,59 @@ its various reports.  It will always report balances in terms of the
 commodity total, rather than the current value of those commodities.
 To enable pricing reports, use one of the commodity reporting options.
 
+@subsection Commodity equivalencies
+
+Sometimes a commodity has several forms which are all equivalent.  An
+example of this is time.  Whether tracked in terms of minutes, hours
+or days, it should be possible to convert between the various forms.
+Doing this requires the use of commodity equivalencies.
+
+For example, you might have the following two transactions, one which
+transfers an hour of time into a @samp{Billable} account, and another
+which decreases the same account by ten minutes.  The resulting report
+will indicate that fifty minutes remain:
+
+@smallexample
+2005/10/01 Work done for company
+    Billable:Client                 1h
+    Project:XYZ
+    
+2005/10/02 Return ten minutes to the project
+    Project:XYZ                    10m
+    Billable:Client
+@end smallexample
+
+Reporting the balance for this ledger file produces:
+
+@smallexample
+       50.0m  Billable:Client
+      -50.0m  Project:XYZ
+@end smallexample
+
+This example works because ledger already knows how to handle seconds,
+minutes and hours, as part of its time tracking support.  Defining
+other equivalencies is simple.  The following is an example that
+creates data equivalencies, helpful for tracking bytes, kilobytes,
+megabytes, and more:
+
+@smallexample
+C 1.00 Kb = 1024 b
+C 1.00 Mb = 1024 Kb
+C 1.00 Gb = 1024 Mb
+C 1.00 Tb = 1024 Gb
+@end smallexample
+
+Each of these definitions correlates a commodity (such as @samp{Kb})
+and a default precision, with a certain quantity of another commodity.
+In the above example, kilobytes are reporetd with two decimal places
+of precision and each kilobyte is equal to 1024 bytes.
+
+Equivalency chains can be as long as desired.  Whenever a commodity
+would report as a decimal amount (less than @samp{1.00}), the next
+smallest commodity is used.  If a commodity could be reported in terms
+of a higher commodity without resulting to a partial fraction, then
+the larger commodity is used.
+
 @node Accounts and Inventories, Understanding Equity, Commodities and Currencies, Keeping a ledger
 @section Accounts and Inventories