added documentation for the 'prices' command

2 files changed, 52 insertions, 17 deletions

diff --git a/ledger.texi b/ledger.texi
index 00b5fb01..db20cdab 100644
--- a/ledger.texi
+++ b/ledger.texi
@@ -250,9 +250,16 @@ whose formatting has gotten out of hand.
 
 @subsection equity
 
-The @command{equity} commands print out accounts balance as if they were
-transactions.  This makes it easy to establish the starting balances
-for an account, when @ref{Archiving previous years}.
+The @command{equity} command prints out accounts balances as if they
+were entries.  This makes it easy to establish the starting balances
+for an account, such as when @ref{Archiving previous years}.
+
+@subsection prices
+
+The @command{prices} command displays the price history for matching
+commodities.  The @option{-A} flag is useful with this report, to
+display the running average price, or @option{-X} to show the price
+trend.
 
 @subsection entry
 
@@ -499,6 +506,9 @@ Sets the default format for the @command{register} report.
 @item --print-format STR
 Sets the default format for the @command{print} report.
 
+@item --prices-format STR
+Sets the default format for the @command{prices} report.
+
 @item --plot-value-format STR
 Sets the default format for the @command{register} report, when @option{-j}
 is being used.
@@ -2193,20 +2203,9 @@ functionality and are willing to debug problems that come up, pass the
 option @samp{--enable-python} to configure, and contact the author via
 email.
 
-Below is a quick example of text that could be pasted into a ledger
-file to generate a customized amount column in the register report.
-It does nothing more than add $100 to each transaction's amount, but
-it demonstrates the potential for more complex extensions:
-
-@example
-!python
-import ledger
-def foo(d, val):
-    return d.xact.amount + val
-!end
-
---amount-expr 'foo'@{$100@}
-@end example
+A quick example of how to use Python can be found by generating the
+@command{prices} report using @file{pysample.dat}.  See that file
+itself for more details.
 
 @contents
 @bye
diff --git a/pysample.dat b/pysample.dat
new file mode 100644
index 00000000..feac582e
--- /dev/null
+++ b/pysample.dat
@@ -0,0 +1,36 @@
+!python
+# These functions maintain the minimum and maximum of the values
+# passed to them.  This is used to maintain the current min/max in the
+# prices report.
+
+min_val = 0
+def vmin(d, val):
+    global min_val
+    if not min_val or val < min_val:
+        min_val = val
+	return val
+    return min_val
+
+max_val = 0
+def vmax(d, val):
+    global max_val
+    if not max_val or val > max_val:
+        max_val = val
+	return val
+    return max_val
+!end
+
+; Change the 'prices' report format to show min/max values
+--prices-format %[%Y/%m/%d %H:%M:%S %Z]   %-8N %10t %10('vmin'a) %10('vmax'a) %12T\n
+
+2004/05/01 Checking balance
+  Assets:Checking               $500.00
+  Equity:Opening Balances
+
+2004/05/29 Book Store
+  Expenses:Books                 $20.00
+  Assets:Checking
+
+2004/05/29 Restaurant
+  Expenses:Food                  $50.00
+  Liabilities:MasterCard