Merge pull request #299 from bkuhn/document-exchange-option-with-colon

Document --exchange COMMODITY1:COMMODITY2 syntax.

Thanks!

1 files changed, 21 insertions, 1 deletions

diff --git a/doc/ledger3.texi b/doc/ledger3.texi
index d4df63ec..2897aa9f 100644
--- a/doc/ledger3.texi
+++ b/doc/ledger3.texi
@@ -6262,7 +6262,16 @@ FIX THIS ENTRY @c ASK JOHN
 @item --exchange @var{COMMODITY}
 @itemx -X @var{COMMODITY}
 Display values in terms of the given @var{COMMODITY}. The latest
-available price is used.
+available price is used.  The syntax
+@option{-X @var{COMMODITY1}:@var{COMMODITY2}} displays values in @var{COMMODITY1}
+in terms of @var{COMMODITY2} using the latest available price, but
+will not automatically covert any other commodities to
+@var{COMMODITY2}.  Multiple @option{-X} arguments may be used on a
+single command line (as in
+@option{-X COMMODITY1:COMMODITY2 -X COMMODITY3:COMMODITY2}),
+which is particularly useful for situations where many prices are
+available for reporting in terms of @var{COMMODITY2}, but only a few
+should be displayed that way .
 
 @item --flat
 Force the full names of accounts to be used in the balance report. The
@@ -7342,6 +7351,17 @@ You can also now use @option{--exchange @var{COMMODITY} (-X)} (and
 and @option{--price (-I)}, to see valuation reports of just your basis
 costs or lot prices.
 
+Finally, sometimes, you may seek to only report one (or some subset)
+of the commodities in terms of another commodity.  In this
+situation, you can use the syntax
+@option{--exchange @var{COMMODITY1}:@var{COMMODITY2}} to request that
+ledger always display @var{COMMODITY1} in terms of @var{COMMODITY2},
+but you want no other commodities to be automatically displayed in terms of
+@var{COMMODITY2} without additional @option{--exchange} options.   For
+example, if you wanted to report EUR and BTC in terms of USD, but report
+all other commodities without conversion to USD, you could use:
+@option{--exchange EUR:USD -X BTC:USD}.
+
 @node Environment variables,  , Commodity reporting, Detailed Option Description
 @subsection Environment variables