Initial commit of new documentation structure

1 files changed, 1044 insertions, 0 deletions

diff --git a/doc/L3-Syntax.texi b/doc/L3-Syntax.texi
new file mode 100644
index 00000000..afe4520d
--- /dev/null
+++ b/doc/L3-Syntax.texi
@@ -0,0 +1,1044 @@
+@c -*-texinfo-*-
+
+@section Cookbook
+
+@subsection Invoking Ledger
+
+@example
+ledger --group-by "tag('trip')" bal
+legder reg --sort "tag('foo')" %foo
+ledger cleared VWCU NFCU Tithe Misentry
+ledger register Joint --uncleared
+ledger register NFCUChecking  --sort d  -d 'd>[2011/04/01]' until 2011/05/25
+@end example
+@subsection Ledger Files
+
+@example
+= /^Income:Taxable/ 
+  (Liabilities:Tithe Owed)    -0.1
+= /Noah/ 
+  (Liabilities:Tithe Owed)    -0.1
+= /Jonah/ 
+  (Liabilities:Tithe Owed)    -0.1
+= /Tithe/
+  (Liabilities:Tithe Owed)    -1.0
+@end example
+
+
+@section Quick Reference
+
+This chapter describes @ledgerprog's features and serves as a quick
+reference. You may wish to survey this to get an overview before diving
+in to the @ref{Ledger Tutorial} and more detailed examples that follow.
+
+@ledgerprog@ has a very simple command-line interface, named---enticingly
+enough---@command{ledger}.  It supports a few reporting commands, and
+a large number of options for refining the output from those commands.
+The basic syntax of any ledger command is:
+
+@example
+ledger [OPTIONS...] COMMAND [ARGS...]
+@end example
+
+Command options must always precede the command word.  After the
+command word there may appear any number of arguments.  For most
+commands, these arguments are regular expressions that cause the
+output to relate only to postings matching those regular
+expressions.  For the @command{transaction} command, the arguments have a
+special meaning, described below.
+
+The regular expressions arguments always match the account name that a
+posting refers to.  To match on the payee of the transaction instead,
+precede the regular expression with @samp{--}.  For example, the
+following balance command reports account totals for rent, food and
+movies, but only those whose payee matches Freddie:
+
+@example
+ledger bal rent food movies -- freddie
+@end example
+
+There are many, many command options available with the
+@command{ledger} command, and it takes a while to master them.
+However, none of them are required to use the basic reporting
+commands.
+
+@menu
+* Commands::                    
+* Options::                     
+* Period expressions::          
+* Format strings::              
+* Value expressions::           
+* File format::                 
+@end menu
+
+@node Commands, Options, Quick Reference, Quick Reference
+@section Commands
+
+@subsection balance
+
+The @command{balance} command reports the current balance of all
+accounts.  It accepts a list of optional regexps, which confine the
+balance report to the matching accounts.  If an account contains
+multiple types of commodities, each commodity's total is reported
+separately.
+
+@subsection register
+
+The @command{register} command displays all the postings occurring
+in a single account, line by line.  The account regexp must be
+specified as the only argument to this command.  If any regexps occur
+after the required account name, the register will contain only those
+postings that match.  Very useful for hunting down a particular
+posting.
+
+The output from @command{register} is very close to what a typical
+checkbook, or single-account ledger, would look like.  It also shows a
+running balance.  The final running balance of any register should
+always be the same as the current balance of that account.
+
+If you have Gnuplot installed, you may plot the amount or running
+total of any register by using the script @file{report}, which is
+included in the @ledgerprog@ distribution.  The only requirement is that you
+add either @option{-j} or @option{-J} to your register command, in
+order to plot either the amount or total column, respectively.
+
+@subsection print
+
+The @command{print} command prints out ledger transactions in a textual
+format that can be parsed by @ledgerprog@.  They will be properly formatted,
+and output in the most economic form possible.  The ``print'' command
+also takes a list of optional regexps, which will cause only those
+postings which match in some way to be printed.
+
+The @command{print} command can be a handy way to clean up a ledger
+file whose formatting has gotten out of hand.
+
+@subsection output
+
+The @command{output} command is very similar to the @command{print}
+command, except that it attempts to replicate the specified ledger
+file exactly.  The format of the command is:
+
+@example
+ledger -f FILENAME output FILENAME
+@end example
+
+Where @file{FILENAME} is the name of the ledger file to output.  The
+reason for specifying this command is that only transactions contained
+within that file will be output, and not an included transactions (as can
+happen with the @command{print} command).
+
+@subsection xml
+
+The @command{xml} command outputs results similar to what
+@command{print} and @command{register} display, but as an XML form.
+This data can then be read in and processed.  Use the
+@option{--totals} option to include the running total with each
+posting.
+
+@subsection emacs
+
+The @command{emacs} command outputs results in a form that can be read
+directly by Emacs Lisp.  The format of the sexp is:
+
+@example
+((BEG-POS CLEARED DATE CODE PAYEE
+  (ACCOUNT AMOUNT)...)  ; list of postings
+ ...)                   ; list of transactions
+@end example
+
+@subsection equity
+
+The @command{equity} command prints out accounts balances as if they
+were transactions.  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{-D} to show each price's
+deviation from that average.
+
+There is also a @command{pricesdb} command which outputs the same
+information as @command{prices}, but does in a format that can be
+parsed by @ledgerprog@.
+
+@subsection xact
+
+The @command{xact} commands simplifies the creation of new transactions.
+It works on the principle that 80% of all postings are variants of
+earlier postings.  Here's how it works:
+
+Say you currently have this posting in your ledger file:
+
+@smallexample
+2004/03/15 * Viva Italiano
+    Expenses:Food                       $12.45
+    Expenses:Tips                        $2.55
+    Liabilities:MasterCard             $-15.00
+@end smallexample
+
+Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva
+Italiano} again.  The exact amounts are different, but the overall
+form is the same.  With the @command{xact} command you can type:
+
+@example
+ledger xact 2004/4/9 viva food 11 tips 2.50
+@end example
+
+This produces the following output:
+
+@smallexample
+2004/04/09 Viva Italiano
+    Expenses:Food                       $11.00
+    Expenses:Tips                        $2.50
+    Liabilities:MasterCard             $-13.50
+@end smallexample
+
+It works by finding a past posting matching the regular expression
+@samp{viva}, and assuming that any accounts or amounts specified will
+be similar to that earlier posting.  If @ledgerprog@ does not succeed in
+generating a new transaction, an error is printed and the exit code is set
+to @samp{1}.
+
+There is a shell script in the distribution's @file{scripts} directory
+called @file{xact}, which simplifies the task of adding a new transaction
+to your ledger.  It launches @command{vi} to confirm that the transaction
+looks appropriate.
+
+Here are a few more examples of the @command{xact} command, assuming
+the above journal transaction:
+
+@example
+ledger xact 4/9 viva 11.50
+ledger xact 4/9 viva 11.50 checking # (from `checking')
+ledger xact 4/9 viva food 11.50 tips 8
+ledger xact 4/9 viva food 11.50 tips 8 cash
+ledger xact 4/9 viva food $11.50 tips $8 cash
+ledger xact 4/9 viva dining "DM 11.50"
+@end example
+
+@node Options, Period expressions, Commands, Quick Reference
+@section Options
+
+With all of the reports, command-line options are useful to modify the
+output generated.  These command-line options always occur before the
+command word.  This is done to distinguish options from exclusive
+regular expressions, which also begin with a dash.  The basic form for
+most commands is:
+
+@example
+ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]]
+@end example
+
+The @var{OPTIONS} and @var{REGEXPS} expressions are both optional.
+You could just use @samp{ledger balance}, without any options---which
+prints a summary of all accounts.  But for more specific reporting, or
+to change the appearance of the output, options are needed.
+
+@subsection Basic options
+
+These are the most basic command options.  Most likely, the user will
+want to set them using environment variables (see @ref{Options}),
+instead of using actual command-line options:
+
+@option{--help} (@option{-h}) prints a summary of all the options, and
+what they are used for.  This can be a handy way to remember which
+options do what.  This help screen is also printed if ledger is run
+without a command.
+
+@option{--version} (@option{-v}) prints the current version of ledger
+and exits.  This is useful for sending bug reports, to let the author
+know which version of ledger you are using.
+
+@option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file.
+This command may be used multiple times.
+Typically, the environment variable
+@env{LEDGER_FILE} is set, rather than using this command-line option.
+
+@option{--output FILE} (@option{-o FILE}) redirects output from any
+command to @var{FILE}.  By default, all output goes to standard
+output.
+
+@option{--init-file FILE} (@option{-i FILE}) causes FILE to be read by
+ledger before any other ledger file.  This file may not contain any
+postings, but it may contain option settings.  To specify options
+in the init file, use the same syntax as the command-line, but put each
+option on it's own line.  Here's an example init file:
+
+@smallexample
+--price-db ~/finance/.pricedb
+--cache /tmp/ledger-cache
+
+; ~/.ledgerrc ends here
+@end smallexample
+
+Option settings on the command-line or in the environment always take
+precedence over settings in the init file.
+
+@option{--cache FILE} identifies FILE as the default binary cache
+file.  That is, if the ledger files to be read are specified using the
+environment variable @env{LEDGER_FILE}, then whenever a command is
+finished a binary copy will be written to the specified cache, to
+speed up the loading time of subsequent queries.  This filename can
+also be given using the environment variable @env{LEDGER_CACHE}, or by
+putting the option into your init file.  The @option{--no-cache}
+option causes @ledgerprog@ to always ignore the binary cache.
+
+@option{--account NAME} (@option{-a NAME}) specifies the default
+account which QIF file postings are assumed to relate to.
+
+@subsection Report filtering
+
+These options change which postings affect the outcome of a
+report, in ways other than just using regular expressions:
+
+@option{--current}(@option{-c}) displays only transactions occurring on or
+before the current date.
+
+@option{--begin DATE} (@option{-b DATE}) constrains the report to
+transactions on or after @var{DATE}.  Only transactions after that date will be
+calculated, which means that the running total in the balance report
+will always start at zero with the first matching transaction.  (Note: This
+is different from using @option{--display} to constrain what is
+displayed).
+
+@option{--end DATE} (@option{-e DATE}) constrains the report so that
+transactions on or after @var{DATE} are not considered.  The ending date
+is inclusive.
+
+@option{--period STR} (@option{-p STR}) sets the reporting period
+to @var{STR}.  This will subtotal all matching transactions within each
+period separately, making it easy to see weekly, monthly, quarterly,
+etc., posting totals.  A period string can even specify the
+beginning and end of the report range, using simple terms like ``last
+june'' or ``next month''.  For more using period expressions, see
+@ref{Period expressions}.
+
+@option{--period-sort EXPR} sorts the postings within each
+reporting period using the value expression @var{EXPR}.  This is most
+often useful when reporting monthly expenses, in order to view the
+highest expense categories at the top of each month:
+
+@example
+ledger -M --period-sort -At reg ^Expenses
+@end example
+
+@option{--cleared} (@option{-C}) displays only postings whose transaction
+has been marked ``cleared'' (by placing an asterix to the right of the
+date).
+
+@option{--uncleared} (@option{-U}) displays only postings whose
+transaction has not been marked ``cleared'' (i.e., if there is no asterix to
+the right of the date).
+
+@option{--real} (@option{-R}) displays only real postings, not
+virtual.  (A virtual posting is indicated by surrounding the
+account name with parentheses or brackets; see the section on using
+virtual postings for more information).
+
+@option{--actual} (@option{-L}) displays only actual postings, and
+not those created due to automated postings.
+
+@option{--related} (@option{-r}) displays postings that are
+related to whichever postings would otherwise have matched the
+filtering criteria.  In the register report, this shows where money
+went to, or the account it came from.  In the balance report, it shows
+all the accounts affected by transactions having a related posting.
+For example, if a file had this transaction:
+
+@smallexample
+2004/03/20 Safeway
+    Expenses:Food                       $65.00
+    Expenses:Cash                       $20.00
+    Assets:Checking                    $-85.00
+@end smallexample
+
+And the register command was:
+
+@example
+ledger -r register food
+@end example
+
+The following would be output, showing the postings related to the
+posting that matched:
+
+@smallexample
+2004/03/20 Safeway              Expenses:Cash               $-20.00      $-20.00
+                                Assets:Checking              $85.00       $65.00
+@end smallexample
+
+@option{--budget} is useful for displaying how close your postings
+meet your budget.  @option{--add-budget} also shows unbudgeted
+postings, while @option{--unbudgeted} shows only those.
+@option{--forecast} is a related option that projects your budget into
+the future, showing how it will affect future balances.
+@xref{Budgeting and forecasting}.
+
+@option{--limit EXPR} (@option{-l EXPR}) limits which postings
+take part in the calculations of a report.
+
+@option{--amount EXPR} (@option{-t EXPR}) changes the value expression
+used to calculate the ``value'' column in the @command{register}
+report, the amount used to calculate account totals in the
+@command{balance} report, and the values printed in the
+@command{equity} report.  @xref{Value expressions}.
+
+@option{--total EXPR} (@option{-T EXPR}) sets the value expression
+used for the ``totals'' column in the @command{register} and
+@command{balance} reports.
+
+@subsection Output customization
+
+These options affect only the output, but not which postings are
+used to create it:
+
+@option{--collapse} (@option{-n}) causes transactions in a
+@command{register} report with multiple postings to be collapsed
+into a single, subtotaled transaction.
+
+@option{--subtotal} (@option{-s}) causes all transactions in a
+@command{register} report to be collapsed into a single, subtotaled
+transaction.
+
+@option{--by-payee} (@option{-P}) reports subtotals by payee.
+
+@option{--comm-as-payee} (@option{-x}) changes the payee of every
+posting to be the commodity used in that posting.  This can be
+useful when combined with other options, such as @option{-s}.
+
+@option{--empty} (@option{-E}) includes even empty accounts in the
+@command{balance} report.
+
+@option{--weekly} (@option{-W}) reports posting totals by the
+week.  The week begins on whichever day of the week begins the month
+containing that posting.  To set a specific begin date, use a
+period string, such as @samp{weekly from DATE}.  @option{--monthly}
+(@option{-M}) reports posting totals by month; @option{--yearly}
+(@option{-Y}) reports posting totals by year.  For more complex
+period, using the @option{--period} option described above.
+
+@option{--dow} reports postings totals for each day of the week.
+This is an easy way to see if weekend spending is more than on
+weekdays.
+
+@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing
+the values determined using the value expression @var{EXPR}.  For
+example, using @option{-S -UT} in the balance report will sort account
+balances from greatest to least, using the absolute value of the
+total.  For more on how to use value expressions, see @ref{Value
+expressions}.
+
+@option{--wide} (@option{-w}) causes the default @command{register}
+report to assume 132 columns instead of 80.
+
+@option{--head} causes only the first N transactions to be printed.  This
+is different from using the command-line utility @command{head}, which
+would limit to the first N postings.  @option{--tail} outputs only
+the last N transactions.  Both options may be used simultaneously.  If a
+negative amount is given, it will invert the meaning of the flag
+(instead of the first five transactions being printed, for example, it
+would print all but the first five).
+
+@option{--pager} tells @ledgerprog@ to pass its output to the given pager
+program---very useful when the output is especially long.  This
+behavior can be made the default by setting the @env{LEDGER_PAGER}
+environment variable.
+
+@option{--average} (@option{-A}) reports the average posting
+value.
+
+@option{--deviation} (@option{-D}) reports each posting's
+deviation from the average.  It is only meaningful in the
+@command{register} and @command{prices} reports.
+
+@option{--percentage} (@option{-%}) shows account subtotals in the
+@command{balance} report as percentages of the parent account.
+
+@option{--totals} include running total information in the
+@command{xml} report.
+
+@option{--amount-data} (@option{-j}) changes the @command{register}
+report so that it outputs nothing but the date and the value column,
+and the latter without commodities.  This is only meaningful if the
+report uses a single commodity.  This data can then be fed to other
+programs, which could plot the date, analyze it, etc.
+
+@option{--total-data} (@option{-J}) changes the @command{register}
+report so that it outputs nothing but the date and totals column,
+without commodities.
+
+@option{--display EXPR} (@option{-d EXPR}) limits which postings
+or accounts or actually displayed in a report.  They might still be
+calculated, and be part of the running total of a register report, for
+example, but they will not be displayed.  This is useful for seeing
+last month's checking postings, against a running balance which
+includes all posting values:
+
+@example
+ledger -d "d>=[last month]" reg checking
+@end example
+
+The output from this command is very different from the following,
+whose running total includes only postings from the last month
+onward:
+
+@example
+ledger -p "last month" reg checking
+@end example
+
+Which is more useful depends on what you're looking to know: the total
+amount for the reporting range (@option{-p}), or simply a display
+restricted to the reporting range (using @option{-d}).
+
+@option{--date-format STR} (@option{-y STR}) changes the basic date
+format used by reports.  The default uses a date like 2004/08/01,
+which represents the default date format of @samp{%Y/%m/%d}.  To
+change the way dates are printed in general, the easiest way is to put
+@option{--date-format FORMAT} in the @ledgerprog@ initialization file
+@file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}).
+
+@option{--format STR} (@option{-F STR}) sets the reporting format for
+whatever report ledger is about to make.  @xref{Format strings}.
+There are also specific format commands for each report type:
+
+@itemize
+@item @option{--balance-format STR}
+@item @option{--register-format STR}
+@item @option{--print-format STR}
+@item @option{--plot-amount-format STR} (-j @command{register})
+@item @option{--plot-total-format STR} (-J @command{register})
+@item @option{--equity-format STR}
+@item @option{--prices-format STR}
+@item @option{--wide-register-format STR} (-w @command{register})
+@end itemize
+
+@subsection Commodity reporting
+
+These options affect how commodity values are displayed:
+
+@option{--price-db FILE} sets the file that is used for recording
+downloaded commodity prices.  It is always read on startup, to
+determine historical prices.  Other settings can be placed in this
+file manually, to prevent downloading quotes for a specific, for
+example.  This is done by adding a line like the following:
+
+@example
+; Don't download quotes for the dollar, or timelog values
+N $
+N h
+@end example
+
+@option{--price-exp MINS} (@option{-L MINS}) sets the expected
+freshness of price quotes, in minutes.  That is, if the last known
+quote for any commodity is older than this value---and if
+@option{--download} is being used---then the Internet will be
+consulted again for a newer price.  Otherwise, the old price is still
+considered to be fresh enough.
+
+@option{--download} (@option{-Q}) causes quotes to be automagically
+downloaded, as needed, by running a script named @command{getquote}
+and expecting that script to return a value understood by ledger.  A
+sample implementation of a @command{getquote} script, implemented in
+Perl, is provided in the distribution.  Downloaded quote price are
+then appended to the price database, usually specified using the
+environment variable @env{LEDGER_PRICE_DB}.
+
+There are several different ways that ledger can report the totals it
+displays.  The most flexible way to adjust them is by using value
+expressions, and the @option{-t} and @option{-T} options.  However,
+there are also several ``default'' reports, which will satisfy most
+users basic reporting needs:
+
+@table @code
+@item -O, --quantity
+Reports commodity totals (this is the default)
+
+@item -B, --basis
+Reports the cost basis for all postings.
+
+@item -V, --market
+Reports the last known market value for all commodities.
+
+@item -G --gain
+Reports the net gain/loss for all commodities in the report that have
+a price history.
+@end table
+
+@subsection Environment variables
+
+Every option to ledger may be set using an environment variable.  If
+an option has a long name such @option{--this-option}, setting the
+environment variable @env{LEDGER_THIS_OPTION} will have the same
+affect as specifying that option on the command-line.  Options on the
+command-line always take precedence over environment variable
+settings, however.
+
+Note that you may also permanently specify option values by placing
+option settings in the file @file{~/.ledgerrc}, for example:
+
+@example
+--cache /tmp/.mycache
+--pager /bin/cat
+
+@end example
+
+@node Period expressions, Format strings, Options, Quick Reference
+@section Period expressions
+
+A period expression indicates a span of time, or a reporting interval,
+or both.  The full syntax is:
+
+@example
+[INTERVAL] [BEGIN] [END]
+@end example
+
+The optional @var{INTERVAL} part may be any one of:
+
+@example
+every day
+every week
+every monthly
+every quarter
+every year
+every N days     # N is any integer
+every N weeks
+every N months
+every N quarters
+every N years
+daily
+weekly
+biweekly
+monthly
+bimonthly
+quarterly
+yearly
+@end example
+
+After the interval, a begin time, end time, both or neither may be
+specified.  As for the begin time, it can be either of:
+
+@example
+from <SPEC>
+since <SPEC>
+@end example
+
+The end time can be either of:
+
+@example
+to <SPEC>
+until <SPEC>
+@end example
+
+Where @var{SPEC} can be any of:
+
+@example
+2004
+2004/10
+2004/10/1
+10/1
+october
+oct
+this week  # or day, month, quarter, year
+next week
+last week
+@end example
+
+The beginning and ending can be given at the same time, if it spans a
+single period.  In that case, just use @var{SPEC} by itself.  In that
+case, the period @samp{oct}, for example, will cover all the days in
+october.  The possible forms are:
+
+@example
+<SPEC>
+in <SPEC>
+@end example
+
+Here are a few examples of period expressions:
+
+@example
+monthly
+monthly in 2004
+weekly from oct
+weekly from last month
+from sep to oct
+from 10/1 to 10/5
+monthly until 2005
+from apr
+until nov
+last oct
+weekly last august
+@end example
+
+@node Format strings, Value expressions, Period expressions, Quick Reference
+@section Format strings
+
+Format strings may be used to change the output format of reports.
+They are specified by passing a formatting string to the
+@option{--format} (@option{-F}) option.  Within that string,
+constructs are allowed which make it possible to display the various
+parts of an account or posting in custom ways.
+
+Within a format strings, a substitution is specified using a percent
+character (@samp{%}).  The basic format of all substitutions is:
+
+@example
+%[-][MIN WIDTH][.MAX WIDTH]EXPR
+@end example
+
+If the optional minus sign (@samp{-}) follows the percent character,
+whatever is substituted will be left justified.  The default is right
+justified.  If a minimum width is given next, the substituted text
+will be at least that wide, perhaps wider.  If a period and a maximum
+width is given, the substituted text will never be wider than this,
+and will be truncated to fit.  Here are some examples:
+
+@example
+%-P     a transaction's payee, left justified
+%20P    The same, right justified, at least 20 chars wide
+%.20P   The same, no more than 20 chars wide
+%-.20P  Left justified, maximum twenty chars wide
+@end example
+
+The expression following the format constraints can be a single
+letter, or an expression enclosed in parentheses or brackets.  The
+allowable expressions are:
+
+@table @code
+@item %
+Inserts a percent sign.
+
+@item t
+Inserts the results of the value expression specified by @option{-t}.
+If @option{-t} was not specified, the current report style's value
+expression is used.
+
+@item T
+Inserts the results of the value expression specified by @option{-T}.
+If @option{-T} was not specified, the current report style's value
+expression is used.
+
+@item |
+Inserts a single space.  This is useful if a width is specified, for
+inserting a certain number of spaces.
+
+@item _
+Inserts a space for each level of an account's depth.  That is, if an
+account has two parents, this construct will insert two spaces.  If a
+minimum width is specified, that much space is inserted for each level
+of depth.  Thus @samp{%5_}, for an account with four parents, will
+insert twenty spaces.
+
+@item (EXPR)
+Inserts the amount resulting from the value expression given in
+parentheses.  To insert five times the total value of an account, for
+example, one could say @samp{%12(5*O)}.  Note: It's important to put
+the five first in that expression, so that the commodity doesn't get
+stripped from the total.
+
+@item [DATEFMT]
+Inserts the result of formatting a posting's date with a date
+format string, exactly like those supported by @code{strftime}.  For
+example: @samp{%[%Y/%m/%d %H:%M:%S]}.
+
+@item S
+Insert the pathname of the file from which the transaction's data was read.
+
+@item B
+Inserts the beginning character position of that transaction within the file.
+
+@item b
+Inserts the beginning line of that transaction within the file.
+
+@item E
+Inserts the ending character position of that transaction within the file.
+
+@item e
+Inserts the ending line of that transaction within the file.
+
+@item D
+By default, this is the same as @samp{%[%Y/%m%/d]}.  The date format
+used can be changed at any time with the @option{-y} flag, however.
+Using @samp{%D} gives the user more control over the way dates are
+output.
+
+@item d
+This is the same as the @samp{%D} option, unless the transaction has an
+effective date, in which case it prints
+@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}.
+
+@item X
+If a posting has been cleared, this inserts @samp{*} followed by a
+space; otherwise nothing is inserted.
+
+@item Y
+This is the same as @samp{%X}, except that it only displays a state
+character if all of the member postings have the same state.
+
+@item C
+Inserts the checking number for a transaction, in parentheses, followed by
+a space; if none was specified, nothing is inserted.
+
+@item P
+Inserts the payee related to a posting.
+
+@item a
+Inserts the optimal short name for an account.  This is normally used
+in balance reports.  It prints a parent account's name if that name
+has not been printed yet, otherwise it just prints the account's name.
+
+@item A
+Inserts the full name of an account.
+
+@item W
+This is the same as @samp{%A}, except that it first displays the
+posting's state @emph{if the transaction's posting states are not
+all the same}, followed by the full account name.  This is offered as
+a printing optimization, so that combined with @samp{%Y}, only the
+minimum amount of state detail is printed.
+
+@item o
+Inserts the ``optimized'' form of a posting's amount.  This is
+used by the print report.  In some cases, this inserts nothing; in
+others, it inserts the posting amount and its cost.  It's use is
+not recommend unless you are modifying the print report.
+
+@item n
+Inserts the note associated with a posting, preceded by two spaces
+and a semi-colon, if it exists.  Thus, no none becomes an empty
+string, while the note @samp{foo} is substituted as @samp{ ; foo}.
+
+@item N
+Inserts the note associated with a posting, if one exists.
+
+@item /
+The @samp{%/} construct is special.  It separates a format string
+between what is printed for the first posting of a transaction, and
+what is printed for all subsequent postings.  If not used, the
+same format string is used for all postings.
+@end table
+
+@node Value expressions, File format, Format strings, Quick Reference
+@section Value expressions
+
+Value expressions are an expression language used by @ledgerprog@ to
+calculate values used by the program for many different purposes:
+
+@enumerate
+@item
+The values displayed in reports
+@item
+For predicates (where truth is anything non-zero), to determine which
+postings are calculated (@option{-l}) or displayed (@option{-d}).
+@item
+For sorting criteria, to yield the sort key.
+@item
+In the matching criteria used by automated postings.
+@end enumerate
+
+Value expressions support most simple math and logic operators, in
+addition to a set of one letter functions and variables.  A function's
+argument is whatever follows it.  The following is a display predicate
+that I use with the @command{balance} command:
+
+@example
+ledger -d /^Liabilities/?T<0:UT>100 balance
+@end example
+
+The effect is that account totals are displayed only if: 1) A
+Liabilities account has a total less than zero; or 2) the absolute
+value of the account's total exceeds 100 units of whatever commodity
+contains.  If it contains multiple commodities, only one of them must
+exceed 100 units.
+
+Display predicates are also very handy with register reports, to
+constrain which transactions are printed.  For example, the following
+command shows only transactions from the beginning of the current month,
+while still calculating the running balance based on all transactions:
+
+@example
+ledger -d "d>[this month]" register checking
+@end example
+
+This advantage to this command's complexity is that it prints the
+running total in terms of all transactions in the register.  The following,
+simpler command is similar, but totals only the displayed
+postings:
+
+@example
+ledger -b "this month" register checking
+@end example
+
+@subsection Variables
+
+Below are the one letter variables available in any value expression.
+For the register and print commands, these variables relate to
+individual postings, and sometimes the account affected by a
+posting.  For the balance command, these variables relate to
+accounts---often with a subtle difference in meaning.  The use of each
+variable for both is specified.
+
+@table @code
+@item t
+This maps to whatever the user specified with @option{-t}.  In a
+register report, @option{-t} changes the value column; in a balance
+report, it has no meaning by default.  If @option{-t} was not
+specified, the current report style's value expression is used.
+
+@item T
+This maps to whatever the user specified with @option{-T}.  In a
+register report, @option{-T} changes the totals column; in a balance
+report, this is the value given for each account.  If @option{-T} was
+not specified, the current report style's value expression is used.
+
+@item m
+This is always the present moment/date.
+@end table
+
+@subsubsection Posting/account details
+
+@table @code
+@item d
+A posting's date, as the number of seconds past the epoch.  This
+is always ``today'' for an account.
+
+@item a
+The posting's amount; the balance of an account, without
+considering children.
+
+@item b
+The cost of a posting; the cost of an account, without its
+children.
+
+@item v
+The market value of a posting, or an account without its children.
+
+@item g
+The net gain (market value minus cost basis), for a posting or an
+account without its children.  It is the same as @samp{v-b}.
+
+@item l
+The depth (``level'') of an account.  If an account has one parent,
+it's depth is one.
+
+@item n
+The index of a posting, or the count of postings affecting an
+account.
+
+@item X
+1 if a posting's transaction has been cleared, 0 otherwise.
+
+@item R
+1 if a posting is not virtual, 0 otherwise.
+
+@item Z
+1 if a posting is not automated, 0 otherwise.
+@end table
+
+@subsubsection Calculated totals
+
+@table @code
+@item O
+The total of all postings seen so far, or the total of an account
+and all its children.
+
+@item N
+The total count of postings affecting an account and all its
+children.
+
+@item B
+The total cost of all postings seen so far; the total cost of an
+account and all its children.
+
+@item V
+The market value of all postings seen so far, or of an account and
+all its children.
+
+@item G
+The total net gain (market value minus cost basis), for a series of
+postings, or an account and its children.  It is the same as
+@samp{V-B}.
+@end table
+
+@subsection Functions
+
+The available one letter functions are:
+
+@table @code
+@item -
+Negates the argument.
+
+@item U
+The absolute (unsigned) value of the argument.
+
+@item S
+Strips the commodity from the argument.
+
+@item A
+The arithmetic mean of the argument; @samp{Ax} is the same as
+@samp{x/n}.
+
+@item P
+The present market value of the argument.  The syntax @samp{P(x,d)} is
+supported, which yields the market value at time @samp{d}.  If no date
+is given, then the current moment is used.
+@end table
+
+@subsection Operators
+
+The binary and ternary operators, in order of precedence, are:
+
+@enumerate
+@item @samp{* /}
+@item @samp{+ -}
+@item @samp{! < > =}
+@item @samp{& | ?:}
+@end enumerate
+
+@subsection Complex expressions
+
+More complicated expressions are possible using:
+
+@table @code
+@item NUM
+A plain integer represents a commodity-less amount.
+
+@item @{AMOUNT@}
+An amount in braces can be any kind of amount supported by ledger,
+with or without a commodity.  Use this for decimal values.
+
+@item /REGEXP/
+@item W/REGEXP/
+A regular expression that matches against an account's full name.  If
+a posting, this will match against the account affected by the
+posting.
+
+@item //REGEXP/
+@item p/REGEXP/
+A regular expression that matches against a transaction's payee name.
+
+@item ///REGEXP/
+@item w/REGEXP/
+A regular expression that matches against an account's base name.  If
+a posting, this will match against the account affected by the
+posting.
+
+@item c/REGEXP/
+A regular expression that matches against the transaction code (the text
+that occurs between parentheses before the payee name).
+
+@item e/REGEXP/
+A regular expression that matches against a posting's note, or
+comment field.
+
+@item (EXPR)
+A sub-expression is nested in parenthesis.  This can be useful passing
+more complicated arguments to functions, or for overriding the natural
+precedence order of operators.
+
+@item [DATE]
+Useful specifying a date in plain terms.  For example, you could say
+@samp{[2004/06/01]}.
+@end table
+