reverted to single file for ease of use with emacs texinfo mode

12 files changed, 1914 insertions, 1923 deletions

diff --git a/doc/L3-FormatStrings.texi b/doc/L3-FormatStrings.texi
deleted file mode 100644
index ee56891f..00000000
--- a/doc/L3-FormatStrings.texi
+++ /dev/null
@@ -1,149 +0,0 @@
-@c -*-texinfo-*-
-
-@node Format Strings, Journal File Format, Period Expressions, Top
-@chapter 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
diff --git a/doc/L3-Introduction.texi b/doc/L3-Introduction.texi
deleted file mode 100644
index b393ce06..00000000
--- a/doc/L3-Introduction.texi
+++ /dev/null
@@ -1,162 +0,0 @@
-@c -*-texinfo-*-
-@node Introduction to Ledger, Principles of Accounting, ,Top
-@chapter Introduction to Ledger
-
-LEDGER is an accounting tool with the moxie to exist.  It provides no
-bells or whistles, and returns the user to the days before user
-interfaces were even a twinkling in their father's CRT.
-
-What it does offer is a double-entry accounting journal with all the
-flexibility and muscle of its modern day cousins, without any of the
-fat.  Think of it as the Bran Muffin of accounting tools.
-
-To use it, you need to start keeping a journal.  This is the basis of
-all accounting, and if you haven't started yet, now is the time to
-learn.  The little booklet that comes with your checkbook is a journal,
-so we'll describe double-entry accounting in terms of that.
-
-A checkbook journal records debits (subtractions, or withdrawals) and
-credits (additions, or deposits) with reference to a single account:
-the checking account.  Where the money comes from, and where it goes
-to, are described in the payee field, where you write the person or
-company's name.  The ultimate aim of keeping a checkbook journal is to
-know how much money is available to spend.  That's really the aim of
-all journals.
-
-What computers add is the ability to walk through these postings,
-and tell you things about your spending habits; to let you devise
-budgets and get control over your spending; to squirrel away money
-into virtual savings account without having to physically move money
-around; etc.  As you keep your journal, you are recording information
-about your life and habits, and sometimes that information can start
-telling you things you aren't aware of.  Such is the aim of all good
-accounting tools.
-
-The next step up from a checkbook journal, is a journal that keeps track
-of all your accounts, not just checking.  In such a journal, you record
-not only who gets paid---in the case of a debit---but where the money
-came from.  In a checkbook journal, its assumed that all the money
-comes from your checking account.  But in a general journal, you write
-posting two-lines: the source account and target account.
-@emph{There must always be a debit from at least one account for every
-credit made to another account}.  This is what is meant by
-``double-entry'' accounting: the journal must always balance to zero,
-with an equal number of debits and credits.
-
-
-For example, let's say you have a checking account and a brokerage
-account, and you can write checks from both of them.  Rather than keep
-two checkbooks, you decide to use one journal for both.  In this general
-journal you need to record a payment to Pacific Bell for your monthly
-phone bill, and a transfer (via check) from your brokerage account to
-your checking account.  The Pacific Bell bill is $23.00, let's say, and
-you want to pay it from your checking account.  In the general journal
-you need to say where the money came from, in addition to where it's
-going to.  These transactions might look like this:
-
-@smallexample
-9/29        Pacific Bell                $23.00     $23.00
-            Checking                   $-23.00          0
-9/30        Checking                   $100.00    $100.00
-      (123) Brokerage                 $-100.00          0
-@end smallexample
-
-The posting must balance to $0: $23 went to Pacific Bell, $23 came from
-Checking.  The next entry shows check number 123 written against your
-brokerage account, transfering money to your checking account.  There is
-nothing left over to be accounted for, since the money has simply moved
-from one account to another in both cases.  This is the basis of
-double-entry accounting: money never pops in or out of existence; it is
-always a posting from one account to another.
-
-Keeping a general journal is the same as keeping two separate journals:
-One for Pacific Bell and one for Checking.  In that case, each time a
-payment is written into one, you write a corresponding withdrawal into
-the other.  This makes it easier to write in a ``running balance'',
-since you don't have to look back at the last time the account was
-referenced---but it also means having a lot of journal books, if you
-deal with multiple accounts.
-
-Here is a good place for an aside on the use of the word `account'.
-Most private people consider an account to be something that holds money
-at an institution for them.  LEDGER uses a more general definition
-of the word.  An account is anywhere money can go.  Other finance
-programs use ``categories'', LEDGER uses accounts. So, for
-example, if you buy some groceries at Trader Joe's then more groceries
-at Whole Foods Markets you might assign the transactions like this
-@smallexample
-2011/03/15   Trader Joe's
-      Expenses:Groceries   $100.00
-      Assets:Checking
-2011/03/15   Whole Food Market
-      Expenses:Groceries   $75.00
-      Assets:Checking
-@end smallexample
-In both cases the money goes to the ``Groceries'' account, even though
-the payees were different.  You can set up your accounts in any way you
-choose.
-
-Enter the beauty of computerized accounting.  The purpose of the
-LEDGER program is to make general journal accounting simple, by keeping
-track of the balances for you.  Your only job is to enter the
-postings.  If a posting does not balance, LEDGER displays an
-error and indicates the incorrect posting.@footnote{In some
-special cases, it automatically balances this transaction for you.}
-
-In summary, there are two aspects of LEDGER use: updating the journal
-data file, and using the LEDGER tool to view the summarized result of
-your transactions.
-
-And just for the sake of example---as a starting point for those who
-want to dive in head-first---here are the journal transactions from above,
-formatted as the LEDGER program wishes to see them:
-
-@smallexample
-2004/09/29 Pacific Bell
-     Expenses:Pacific Bell              $23.00
-     Assets:Checking
-@end smallexample
-
-The account balances and registers in this file, if saved as
-@file{ledger.dat}, could be reported using:
-
-@example
-$ ledger -f ledger.dat balance
-$ ledger -f ledger.dat register checking
-$ ledger -f ledger.dat register bell
-@end example
-
-An important difference between LEDGER and other finance packages is
-that journal will never alter your input file.  You can create and edit
-that file in any way you prefer, but journal is only for analyzing the
-data, not for altering it.
-
-@section More introduction
-
-
-@section Building the program
-
-LEDGER is written in ANSI C++, and should compile on any platform.  It
-depends on the GNU multiprecision integer library (libgmp), and the
-Perl regular expression library (libpcre).  It was developed using GNU
-make and gcc 3.3, on a PowerBook running OS/X.
-
-To build and install once you have these libraries on your system,
-enter these commands:
-
-@example
-./configure && make install
-@end example
-
-@section Getting help
-
-If you need help on how to use LEDGER, or run into problems, you can
-join the LEDGER mailing list at the following Web address:
-
-@example
-http://groups.google.com/group/ledger-cli
-@end example
-
-You can also find help at the @samp{#ledger} channel on the IRC server
-@samp{irc.freenode.net}.
-
diff --git a/doc/L3-Journal.texi b/doc/L3-Journal.texi
deleted file mode 100644
index 419d1445..00000000
--- a/doc/L3-Journal.texi
+++ /dev/null
@@ -1,346 +0,0 @@
-@c -*-texinfo-*-
-
-@node Keeping a Journal, Most Basic Entry, Principles of Accounting, Top
-@chapter Keeping a Journal
-
-The most important part of accounting is keeping a good journal.  If you
-have a good journal, tools can be written to work whatever mathematical
-tricks you need to better understand your spending patterns.  Without a
-good journal, no tool, however smart, can help you.
-
-The LEDGER program aims at making journal transactions as simple as
-possible.  Since it is a command-line tool, it does not provide a user
-interface for keeping a journal.  If you like, you may use GnuCash to
-maintain your journal, in which case LEDGER will read
-GnuCash's data files directly.  In that case, read the GnuCash manual
-now, and skip to the next chapter.
-
-If you are not using GnuCash, but a text editor to maintain your
-journal, read on.  LEDGER has been designed to make data transactions as
-simple as possible, by keeping the journal format easy, and also by
-automagically determining as much information as possible based on the
-nature of your transactions.
-
-For example, you do not need to tell LEDGER about the accounts you
-use.  Any time LEDGER sees a posting involving an account it knows
-nothing about, it will create it@footnote{This also means if you
-misspell an account it will end up getting counted separately from what
-you intended.  The provided Emacs major mode provides for automatically
-filling in account names.}.  If you use a commodity that is new to
-LEDGER, it will create that commodity, and determine its display
-characteristics (placement of the symbol before or after the amount,
-display precision, etc) based on how you used the commodity in the
-posting.
-
-@menu
-* Most Basic Entry::            
-* Commodities::                 
-* Structuring Your Accounts::   
-* Transaction Notes and Tags::  
-* File Format::                 
-* Archiving Previous Years ::   
-* Ledger Tutorial ::            
-@end menu
-
-@node Most Basic Entry, Commodities, Keeping a Journal, Keeping a Journal
-@section The Most Basic Entry
-
-Here is the Pacific Bell example from above, given as a LEDGER
-posting, with the additional of a check number:
-
-@smallexample
-9/29 (1023) Pacific Bell
-    Expenses:Utilities:Phone                   $23.00
-    Assets:Checking                           $-23.00
-@end smallexample
-
-As you can see, it is very similar to what would be written on paper,
-minus the computed balance totals, and adding in account names that work
-better with LEDGER's scheme of things.  In fact, since
-LEDGER is smart about many things, you don't need to specify the
-balanced amount, if it is the same as the first line:
-
-@smallexample
-9/29 (1023) Pacific Bell
-    Expenses:Utilities:Phone                   $23.00
-    Assets:Checking
-@end smallexample
-
-For this transaction, LEDGER will figure out that $-23.00 must come from
-@samp{Assets:Checking} in order to balance the transaction.
-
-Also note the structure of the account entries.  There is an implied
-hierarchy established by separating with colons.  See
-(@pxref{Structuring Your Accounts}) for details and suggestions regarding
-your accounts.
-
-
-
-@strong{The format is very flexible and it isn't necessary that you
-indent and space out things exactly as shown. The only requirements are
-that the start of the transaction (the date typically) is at the
-beginning of the first line of the transaction, and the accounts are
-indented by at least one space.  If you omit the leading spaces in the
-account lines LEDGER will not count the transaction and will not
-give an error.  There must be at least two spaces, or a tab, between the
-amount and the account.  If you do not have adequate separation between
-the amount and the account LEDGER will give an error and stop
-calculating}
-
-@node Commodities, Structuring Your Accounts, Most Basic Entry, Keeping a Journal
-@section Commodities
-
-LEDGER is agnostic when it comes to how you value your accounts.
-Dollars, Euros, Pounds, Francs, etc. are just ``commodities''.  Holdings
-in stocks, bonds, mutual funds and other financial instrument can be
-label using whatever is convenient for you (stock ticker symbols are
-suggested for publicly traded assets).@footnote{you can track ANYTHING,
-even time. As long as it cannot be created or destroyed inside your
-accounting system.}
-
-This is fundamentally different than many common accounting packages,
-which assume the same currency throughout all of your accounts.  This
-means if you typically operate in Euros, but travel to the US and has
-some expenses, you would have to do the currency conversion BEFORE you
-made the entry into your financial system.  With ledger this is not
-required.  In the same journal you can have entries in any or all
-commodities you actually hold.  You can use the reporting capabilities
-to convert all commodities to a single commodity for reporting purposes
-without ever changing the underlying entry.
-
-For example, the following entries reflect transaction made for a
-business trip to Europe from the US:
-
-@smallexample
-2011/09/23   Cash in Munich
-    Assets:Cash  50.00 Euros
-    Assets:Checking  $-66.00
-
-2011/09/24  Dinner in Munich
-    Expenses:Business:Travel  35.00 Euro
-    Assets:Cash
-@end smallexample
-
-This says that $66.00 came out of checking and turned into 50 Euros. The
-implied exchange rate was $1.32.  Then 35 Euros was spent on Dinner in Munich.
-
-
-@node Structuring Your Accounts, Transaction Notes and Tags , Commodities ,Keeping a Journal
-@section Structuring your Accounts
-
-There really are no requirements for how you do this, but to preserve
-your sanity we suggest some very basic structure to your accounting
-system.
-
-At the highest level you have five sorts of accounts: Expenses, Assets,
-Income, Liabilities and Equity.  Briefly, you can think of these as places money goes,
-places money sits, places money comes from and money you owe.
-
-Starting the structure off this way will make it simpler for you to get
-answers to the questions you really need to ask about your finances.
-
-@node Transaction Notes and Tags, File Format, Structuring Your Accounts, Keeping a Journal
-@section Transaction Notes and Tags
-LEDGER 3.0 supports entry and transaction ``notes'', which may  
-contain new metadata and tag markers.  Here's an example:
-
-@smallexample
-   2004/05/27 (100) Credit card company
-       ; This is an entry note!
-       ; Sample: Value
-       Liabilities:MasterCard         $20.00
-       ; This is a transaction note!
-       ; Sample: Another Value
-       ; :MyTag:
-       Assets:Bank:Checking
-       ; :AnotherTag:
-@end smallexample
-
-An indented paragraph starting with `;' is parsed as a persistent note  
-for its preceding category.  These notes will get printed back to you  
-with the ``print'' command.  They are accessible to value expressions  
-using the ``note'' variable.
-
-Further, any occurrence of ``:foo:'' in a note will cause a metadata tag  
-for "foo" to be registered for that entry.  You can then search for  
-such transactions using:
-
-@smallexample
-   ledger reg %foo
-   ldeger reg tag foo
-@end smallexample
-
-Also, if any word in the note ends (but does not start) with a colon,  
-the remainder of that line will be taken to be the metadata value for  
-that tag.  That is:
-
-@smallexample
-   ; :foo:bar:baz:  <-- These are three tags
-   ; name: value    <-- this is a tag with a value
-@end smallexample
-
-Tags with value can be searched for just like tags.  In addition, you  
-can further limit your tag search by looking for only those tags that  
-have specific values:
-
-@smallexample
-   ledger reg %name=value
-   ledger reg tag name=value
-@end smallexample
-
-The group-by and sort functions also support tags:
-@smallexample
-ledger --group-by "tag('foo')" bal 
-@end smallexample
-Will produce a balance summary of all transanction with tag `foo' group by transactions wiht the same value for `foo'.
-
-@smallexample
-ledger reg --sort "tag('foo')" %foo
-@end smallexample
-Produces a register view with the transaction have tag `foo' sorted by the tags value.
-
-Comments that occur before an entry, or which starts at column  
-zero, are always ignored and are neither searched nor printed back.
-
-
-
-@node File Format, Command-line Syntax ,Transaction Notes and Tags, Keeping a Journal
-@section File format
-
-The ledger file format is quite simple, but also very flexible.  It
-supports many options, though typically the user can ignore most of
-them.  They are summarized below.
-
-The initial character of each line determines what the line means, and
-how it should be interpreted.  Allowable initial characters are:
-
-@table @code
-@item NUMBER
-A line beginning with a number denotes a transaction.  It may be followed
-by any number of lines, each beginning with whitespace, to denote the
-transaction's account postings.  The format of the first line is:
-
-@example
-DATE[=EDATE] [*|!] [(CODE)] DESC
-@end example
-
-If @samp{*} appears after the date (with optional effective date), it
-indicates the transaction is ``cleared'', which can mean whatever the user
-wants it to mean.  If @samp{!} appears after the date, it indicates d
-the transaction is ``pending''; i.e., tentatively cleared from the user's
-point of view, but not yet actually cleared.  If a @samp{CODE} appears
-in parentheses, it may be used to indicate a check number, or the type
-of the posting.  Following these is the payee, or a description of
-the posting.
-
-The format of each following posting is:
-
-@example
-  ACCOUNT  AMOUNT  [; NOTE]
-@end example
-
-The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual
-postings, or square brackets if it is a virtual postings that
-must balance.  The @samp{AMOUNT} can be followed by a per-unit
-posting cost, by specifying @samp{@@ AMOUNT}, or a complete
-posting cost with @samp{@@@@ AMOUNT}.  Lastly, the @samp{NOTE} may
-specify an actual and/or effective date for the posting by using
-the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or
-@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}.
-
-@item =
-An automated transaction.  A value expression must appear after the equal
-sign.
-
-After this initial line there should be a set of one or more
-postings, just as if it were normal transaction.  If the amounts of the
-postings have no commodity, they will be applied as modifiers to
-whichever real posting is matched by the value expression.
-
-@item ~
-A period transaction.  A period expression must appear after the tilde.
-
-After this initial line there should be a set of one or more
-postings, just as if it were normal transaction.
-
-@item !
-A line beginning with an exclamation mark denotes a command directive.
-It must be immediately followed by the command word.  The supported
-commands are:
-
-@table @samp
-@item !include
-Include the stated journal file.
-
-@item !account
-The account name is given is taken to be the parent of all
-postings that follow, until @samp{!end} is seen.
-
-@item !end
-Ends an account block.
-@end table
-
-@item ;
-A line beginning with a colon indicates a comment, and is
-ignored. Comments will not be returned in a ``print'' response.
-@item indented ; 
-If the semi colon is indented and occurs inside a transaction, it is
-parsed as a persistent note for its preceding category.  These notes or
-tags can be used to augment to reporting and filtering capabilities of
-LEDGER.
-@item Y
-If a line begins with a capital Y, it denotes the year used for all
-subsequent transactions that give a date without a year.  The year should
-appear immediately after the Y, for example: @samp{Y2004}.  This is
-useful at the beginning of a file, to specify the year for that file.
-If all transactions specify a year, however, this command has no effect.
-
-@item P
-Specifies a historical price for a commodity.  These are usually found
-in a pricing history file (see the @option{-Q} option).  The syntax
-is:
-@example
-P DATE SYMBOL PRICE
-@end example
-
-@item N SYMBOL
-Indicates that pricing information is to be ignored for a given
-symbol, nor will quotes ever be downloaded for that symbol.  Useful
-with a home currency, such as the dollar ($).  It is recommended that
-these pricing options be set in the price database file, which
-defaults to @file{~/.pricedb}.  The syntax for this command is:
-@example
-N SYMBOL
-@end example
-
-@item D AMOUNT
-Specifies the default commodity to use, by specifying an amount in the
-expected format.  The @command{transaction} command will use this commodity
-as the default when none other can be determined.  This command may be
-used multiple times, to set the default flags for different
-commodities; whichever is seen last is used as the default commodity.
-For example, to set US dollars as the default commodity, while also
-setting the thousands flag and decimal flag for that commodity, use:
-@example
-D $1,000.00
-@end example
-
-@item C AMOUNT1 = AMOUNT2
-Specifies a commodity conversion, where the first amount is given to
-be equivalent to the second amount.  The first amount should use the
-decimal precision desired during reporting:
-@example
-C 1.00 Kb = 1024 bytes
-@end example
-
-@item i, o, b, h
-These four relate to timeclock support, which permits LEDGER to read
-timelog files.  See the timeclock's documentation for more info on the
-syntax of its timelog files.
-@end table
-
-@node Archiving Previous Years , , ,Keeping a Journal
-@section Archiving Previous Years
-
-@node Ledger Tutorial , , ,Keeping a Journal
-@section Ledger Tutorial
diff --git a/doc/L3-JournalFormat.texi b/doc/L3-JournalFormat.texi
deleted file mode 100644
index ac7059ca..00000000
--- a/doc/L3-JournalFormat.texi
+++ /dev/null
@@ -1,242 +0,0 @@
-@c -*-texinfo-*-
-@node Journal File Format,Extending with Python, Format Strings,  Top
-@chapter LEDGER Journal File Format
-
-This chapter offers a complete description of the journal data format,
-suitable for implementors in other languages to follow.  For users,
-the chapter on keeping a journal is less extensive, but more typical
-of common usage (@pxref{Keeping a Journal}).
-
-Data is collected in the form of @dfn{transactions} which occur in one
-or more @dfn{journal files}.  Each transaction, in turn, is made up of
-one or more @dfn{postings}, which describe how @dfn{amounts} flow from
-one @dfn{account} to another.  Here is an example of the simplest of
-journal files:
-
-@example
-2010/05/31 Just an example
-    Expenses:Some:Account                $100.00
-    Income:Another:Account
-@end example
-
-In this example, there is a transaction date, a payee, or description
-of the transaction, and two postings.  The postings show movement of
-one hundred dollars from an account within the Income hierarchy, to
-the specified expense account.  The name and meaning of these accounts
-in arbitrary, with no preferences implied, although you will find it
-useful to follow standard accounting practice (@pxref{Principles of
-Accounting}).
-
-Since an amount is missing from the second posting, it is assumed to
-be the inverse of the first.  This guarantee the cardinal rule of
-double-entry accounting: the sum of every transaction must balance to
-zero, or it is in error.  Whenever Ledger encounters a @dfn{null
-posting} in a transaction, it uses it to balance the remainder.
-
-It is also typical---though not enforced---to think of the first
-posting as the destination, and the final as the source.  Thus, the
-amount of the first posting is typically positive.  Consider:
-
-@example
-2010/05/31 An income transaction
-    Assets:Checking       $1,000.00
-    Income:Salary
-
-2010/05/31 An expense transaction
-    Expenses:Dining         $100.00
-    Assets:Checking
-@end example
-
-@emph{Note:} It is important to note that there must be at least two spaces between
-the end of the post and the beginning of the amount (including and
-commdity designator).
-
-@section Specifying amounts
-
-The heart of a journal is the amounts it records, and this fact is
-reflected in the diversity of amount expressions allowed.  All of them
-are covered here, though it must be said that sometimes, there are
-multiple ways to achieve a desired result.
-
-@subsection Integer amounts
-
-In the simplest form, bare decimal numbers are accepted:
-
-@example
-2010/05/31 An income transaction
-    Assets:Checking        1000.00
-    Income:Salary
-@end example
-
-Such amounts may only use an optional period for a decimal point.
-These are referred to as @dfn{integer amounts} or @dfn{uncommoditized
-amounts}.  In most ways they are similar to @dfn{commoditized
-amounts}, but for one signficant difference: They always display in
-reports with @dfn{full precision}.  More on this in a moment.  For
-now, a word must be said about how Ledger stores numbers.
-
-Every number parsed by Ledger is stored internally as an
-infinite-precision rational value.  Floating-point math is never used,
-as it cannot be trusted to maintain precision of values.  So, in the
-case of @samp{1000.00} above, the internal value is @samp{100000/100}.
-
-While rational numbers are great at not losing precision, the question
-arises: How should they be displayed?  A number like @samp{100000/100}
-is no problem, since it represents a clean decimal fraction.  But what
-about when the number @samp{1/1} is divided by three?  How should one
-print @samp{1/3}, an infinitely repeating decimal?
-
-Ledger gets around this problem by rendering rationals into decimal at
-the last possible moment, and only for display.  As such, some
-rounding must, at times, occur.  If this rounding would affect the
-calculation of a running total, special accommodation postings are
-generated to make you aware it has happened.  In practice, it happens
-rarely, but even then it does not reflect adjustment of the
-@emph{internal amount}, only the displayed amount.
-
-What has still not been answered is how Ledger rounds values.  Should
-@samp{1/3} be printed as @samp{0.33} or @samp{0.33333}?  For
-commoditized amounts, the number of decimal places is decided by
-observing how each commodity is used; but in the case of integer
-amounts, an arbitrary factor must be chosen.  Initially, this factor
-is six.  Thus, @samp{1/3} is printed back as @samp{0.333333}.
-Further, this rounding factor becomes associated with each particular
-value, and is carried through mathematical operations.  For example,
-if that particular number were multiplied by itself, the decimal
-precision of the result would be twelve.  Addition and subtraction do
-not affect precision.
-
-Since each integer amount retains its own display precision, this is
-called @dfn{full precision}, as opposed to commoditized amounts, which
-always look to their commodity to know what precision they should
-round to, and so use @dfn{commodity precision}.
-
-@subsection Commoditized amounts
-
-A @dfn{commoditized amount} is an integer amount which has an
-associated commodity.  This commodity can appear before or after the
-amount, and may or may not be separated from it by a space.  Most
-characters are allowed in a commodity name, except for the following:
-
-@itemize
-@item Any kind of whitespace
-@item Numerical digits
-@item Punctuation: @samp{.,;:?!}
-@item Mathematical and logical operators: @samp{-+*/^&|=}
-@item Bracketing characters: @samp{<>[]()}@{@}
-@item The at symbol: @samp{@@}
-@end itemize
-
-And yet, any of these may appear in a commodity name if it is
-surrounded by double quotes, for example:
-
-@example
-100 "EUN+133"
-@end example
-
-If a @dfn{quoted commodity} is found, it is displayed in quotes as
-well, to avoid any confusion as to which part is the amount, and which
-part is the commodity.
-
-Another feature of commoditized amounts is that they are reported back
-in the same form as parsed.  If you specify dollar amounts using
-@samp{$100}, they will print the same; likewise with @samp{100 $} or
-@samp{$100.000}.  You may even use decimal commas, such as
-@samp{$100,00}, or thousand-marks, as in @samp{$10,000.00}.
-
-These display characteristics become associated with the commodity,
-with the result being that all amounts of the same commodity are
-reported consistently.  Where this is most noticeable is the
-@dfn{display precision}, which is determined by the most precise value
-seen for a given commodity.  In most cases.
-
-Ledger makes a distinction by @dfn{observed amounts} and unobserved
-amounts.  An observed amount is critiqued by Ledger to determine how
-amounts using that commodity should be displayed; unobserved amounts
-are significant in their value only---no matter how they are
-specified, it does not change how other amounts in that commodity will
-be displayed.
-
-An example of this is found in cost expressions, covered next.
-
-@section Posting costs
-
-You have seen how to specify either a commoditized or an integer
-amount for a posting.  But what if the amount you paid for something
-was in one commodity, and the amount received was another?  There are
-two main ways to express this:
-
-@example
-2010/05/31 Farmer's Market
-    Assets:My Larder           100 apples
-    Assets:Checking                $20.00
-@end example
-
-In this example, you have paid twenty dollars for one hundred apples.
-The cost to you is twenty cents per apple, and Ledger calculates this
-implied cost for you.  You can also make the cost explicit using a
-@dfn{cost amount}:
-
-@example
-2010/05/31 Farmer's Market
-    Assets:My Larder           100 apples @@ $0.200000
-    Assets:Checking
-@end example
-
-Here the @dfn{per-unit cost} is given explicitly in the form of a cost
-amount; and since cost amount are @emph{unobserved}, the use of six
-decimal places has no effect on how dollar amounts are displayed in
-the final report.  You can also specify the @dfn{total cost}:
-
-@example
-2010/05/31 Farmer's Market
-    Assets:My Larder           100 apples @@@@ $20
-    Assets:Checking
-@end example
-
-These three forms have identical meaning.  In most cases the first is
-preferred, but the second two are necessary when more than two
-postings are involved:
-
-@example
-2010/05/31 Farmer's Market
-    Assets:My Larder           100 apples        @@ $0.200000
-    Assets:My Larder           100 pineapples    @@ $0.33
-    Assets:My Larder           100 "crab apples" @@ $0.04
-    Assets:Checking
-@end example
-
-Here the implied cost is @samp{$57.00}, which is entered into the null
-posting automatically so that the transaction balances.
-
-@subsection Primary commodities
-
-In every transaction involving more than one commodity, there is
-always one which is the @dfn{primary commodity}.  This commodity
-should be thought of as the exchange commodity, or the commodity used
-to buy and sells units of the other commodity.  In the fruit examples
-above, dollars are the primary commodity.  This is decided by Ledger
-on the placement of the commodity in the transaction:
-
-@example
-2010/05/31 Sample Transaction
-    Expenses               100 secondary
-    Assets                  50 primary
-
-2010/05/31 Sample Transaction
-    Expenses               100 secondary @@ 0.5 primary
-    Assets
-
-2010/05/31 Sample Transaction
-    Expenses               100 secondary @@@@ 50 primary
-    Assets
-@end example
-
-The only case where knowledge of primary versus secondary comes into
-play is in reports that use the @option{-V} or @option{-B} options.
-With these, only primary commodities are shown.
-
-If a transaction uses only one commodity, this commodity is also
-considered a primary.  In fact, when Ledger goes about ensures that
-all transactions balance to zero, it only ever asks this of primary
-commodities.
diff --git a/doc/L3-Main.texi b/doc/L3-Main.texi
deleted file mode 100644
index aabc0f34..00000000
--- a/doc/L3-Main.texi
+++ /dev/null
@@ -1,96 +0,0 @@
-\input texinfo  @c -*-texinfo-*-
-
-@setfilename ledger.info
-@settitle Ledger: Command-Line Accounting
-
-@dircategory User Applications
-@copying
-Copyright (c) 2003-2010, John Wiegley.  All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
-
-- Redistributions of source code must retain the above copyright
-  notice, this list of conditions and the following disclaimer.
-
-- Redistributions in binary form must reproduce the above copyright
-  notice, this list of conditions and the following disclaimer in the
-  documentation and/or other materials provided with the distribution.
-
-- Neither the name of New Artisans LLC nor the names of its
-  contributors may be used to endorse or promote products derived from
-  this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-@end copying
-
-@documentencoding UTF-8
-
-@iftex
-@finalout
-@end iftex
-
-@macro ledgerprog
-  @sc{ledger}
-@end macro
-
-
-@titlepage
-@title LEDGER: Command-Line Accounting
-@author John Wiegley
-@end titlepage
-
-@direntry
-* Ledger: (ledger).           Command-Line Accounting
-@end direntry
-
-@contents
-
-@ifnottex
-@node Top,  , (dir), (dir)
-@top Overview
-
-@insertcopying
-@end ifnottex
-
-@ifnottex
-@section Copyright
-@insertcopying
-@end ifnottex
-
-@menu 
-* Introduction to Ledger::
-* Principles of Accounting::
-* Keeping a Journal::
-* Command-line Syntax::
-* Basic Reporting Commands::
-* Value Expressions::
-* Format Strings::
-* Journal File Format::
-* Extending with Python::
-@end menu
-
-
-@c each chapter is in an idividual texi file included here
-@include L3-Introduction.texi
-@include L3-Principles.texi
-@include L3-Journal.texi
-@include L3-Syntax.texi
-@include L3-Reporting.texi
-@include L3-ValueExpressions.texi
-@include L3-FormatStrings.texi
-@include L3-JournalFormat.texi
-@include L3-Python.texi
-
-@bye
diff --git a/doc/L3-Principles.texi b/doc/L3-Principles.texi
deleted file mode 100644
index 1de75967..00000000
--- a/doc/L3-Principles.texi
+++ /dev/null
@@ -1,4 +0,0 @@
-@c -*-texinfo-*-
-
-@node Principles of Accounting, Keeping a Journal, Introduction to Ledger, Top
-@chapter Principles of Accounting
diff --git a/doc/L3-Python.texi b/doc/L3-Python.texi
deleted file mode 100644
index 3f985237..00000000
--- a/doc/L3-Python.texi
+++ /dev/null
@@ -1,3 +0,0 @@
-@c -*-texinfo-*-
-@node Extending with Python, , Journal File Format, Top
-@chapter Extending with Python
diff --git a/doc/L3-Queries.texi b/doc/L3-Queries.texi
deleted file mode 100644
index ef45d948..00000000
--- a/doc/L3-Queries.texi
+++ /dev/null
@@ -1,3 +0,0 @@
-@c -*-texinfo-*-
-
-@chapter Report Queries
diff --git a/doc/L3-Reporting.texi b/doc/L3-Reporting.texi
deleted file mode 100644
index cb675aba..00000000
--- a/doc/L3-Reporting.texi
+++ /dev/null
@@ -1,11 +0,0 @@
-@c -*-texinfo-*-
-
-@node Basic Reporting Commands, Value Expressions, Command-line Syntax, Top
-@chapter Basic Reporting Commands
-
-@menu
-* Budgeting and Forecasting::   
-@end menu
-
-@node Budgeting and Forecasting, , ,Basic Reporting Commands
-@section Budgeting and Forecasting
diff --git a/doc/L3-Syntax.texi b/doc/L3-Syntax.texi
deleted file mode 100644
index 83bd1320..00000000
--- a/doc/L3-Syntax.texi
+++ /dev/null
@@ -1,677 +0,0 @@
-@c -*-texinfo-*-
-@node Command-line Syntax, Basic Reporting Commands, File Format, Top
-@chapter Command-line Syntax
-
-
-@menu
-* Cookbook::                    
-* Quick Reference::             
-* Commands::                    
-* Options::                     
-* Period Expressions::          
-@end menu
-
-@node Cookbook, Quick Reference, Command-line Syntax, Command-line Syntax
-@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
-
-@node Quick Reference, Commands, Cookbook, Command-line Syntax
-@section Quick Reference
-
-This chapter describes LEDGER'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.
-
-LEDGER 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.
-
-
-@node Commands, Options, Quick Reference, Command-line Syntax
-@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 LEDGER 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 LEDGER.  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 LEDGER.
-
-@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 LEDGER 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, Command-line Syntax
-@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 LEDGER 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 LEDGER 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 LEDGER 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, Command-line Syntax
-@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
-
diff --git a/doc/L3-ValueExpressions.texi b/doc/L3-ValueExpressions.texi
deleted file mode 100644
index f893229f..00000000
--- a/doc/L3-ValueExpressions.texi
+++ /dev/null
@@ -1,230 +0,0 @@
-@c -*-texinfo-*-
-
-@node Value Expressions, Variables, Basic Reporting Commands, Top
-@chapter Value Expressions
-
-Value expressions are an expression language used by LEDGER 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
-
-@menu
-* Variables::                   
-@end menu
-
-@node Variables,  , Value Expressions, Value Expressions
-@section 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
-
-@subsection 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
-
-@subsection 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
-
-@section 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
-
-@section Operators
-
-The binary and ternary operators, in order of precedence, are:
-
-@enumerate
-@item @samp{* /}
-@item @samp{+ -}
-@item @samp{! < > =}
-@item @samp{& | ?:}
-@end enumerate
-
-@section 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
-
diff --git a/doc/Ledger3.texi b/doc/Ledger3.texi
new file mode 100644
index 00000000..b804ee4c
--- /dev/null
+++ b/doc/Ledger3.texi
@@ -0,0 +1,1914 @@
+\input texinfo  @c -*-texinfo-*-
+
+@setfilename ledger3.info
+@settitle Ledger: Command-Line Accounting
+
+@dircategory User Applications
+@copying
+Copyright (c) 2003-2010, John Wiegley.  All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+- Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+- Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+- Neither the name of New Artisans LLC nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+@end copying
+
+@documentencoding UTF-8
+
+@iftex
+@finalout
+@end iftex
+
+@macro ledgerprog
+  @sc{ledger}
+@end macro
+
+
+@titlepage
+@title LEDGER: Command-Line Accounting
+@author John Wiegley
+@end titlepage
+
+@direntry
+* Ledger: (ledger).           Command-Line Accounting
+@end direntry
+
+@contents
+
+@ifnottex
+@node Top, Copying, (dir), (dir)
+@top Overview
+LEDGER is an accounting tool with the moxie to exist.  It provides no
+bells or whistles, and returns the user to the days before user
+interfaces were even a twinkling in their father's CRT.
+@c @insertcopying
+@end ifnottex
+
+@menu
+* Copying::                     
+* Introduction to Ledger::      
+* Principles of Accounting::    
+* Keeping a Journal::           
+* Command-line Syntax::         
+* Basic Reporting Commands::    
+* Value Expressions::           
+* Format Strings::              
+* Journal File Format::         
+* Extending with Python::       
+@end menu
+
+@node Copying, Introduction to Ledger, Top, Top
+@chapter Copying
+@insertcopying
+
+@node Introduction to Ledger, Principles of Accounting, Copying, Top
+@chapter Introduction to Ledger
+
+LEDGER is an accounting tool with the moxie to exist.  It provides no
+bells or whistles, and returns the user to the days before user
+interfaces were even a twinkling in their father's CRT.
+
+What it does offer is a double-entry accounting journal with all the
+flexibility and muscle of its modern day cousins, without any of the
+fat.  Think of it as the Bran Muffin of accounting tools.
+
+To use it, you need to start keeping a journal.  This is the basis of
+all accounting, and if you haven't started yet, now is the time to
+learn.  The little booklet that comes with your checkbook is a journal,
+so we'll describe double-entry accounting in terms of that.
+
+A checkbook journal records debits (subtractions, or withdrawals) and
+credits (additions, or deposits) with reference to a single account:
+the checking account.  Where the money comes from, and where it goes
+to, are described in the payee field, where you write the person or
+company's name.  The ultimate aim of keeping a checkbook journal is to
+know how much money is available to spend.  That's really the aim of
+all journals.
+
+What computers add is the ability to walk through these postings,
+and tell you things about your spending habits; to let you devise
+budgets and get control over your spending; to squirrel away money
+into virtual savings account without having to physically move money
+around; etc.  As you keep your journal, you are recording information
+about your life and habits, and sometimes that information can start
+telling you things you aren't aware of.  Such is the aim of all good
+accounting tools.
+
+The next step up from a checkbook journal, is a journal that keeps track
+of all your accounts, not just checking.  In such a journal, you record
+not only who gets paid---in the case of a debit---but where the money
+came from.  In a checkbook journal, its assumed that all the money
+comes from your checking account.  But in a general journal, you write
+posting two-lines: the source account and target account.
+@emph{There must always be a debit from at least one account for every
+credit made to another account}.  This is what is meant by
+``double-entry'' accounting: the journal must always balance to zero,
+with an equal number of debits and credits.
+
+
+For example, let's say you have a checking account and a brokerage
+account, and you can write checks from both of them.  Rather than keep
+two checkbooks, you decide to use one journal for both.  In this general
+journal you need to record a payment to Pacific Bell for your monthly
+phone bill, and a transfer (via check) from your brokerage account to
+your checking account.  The Pacific Bell bill is $23.00, let's say, and
+you want to pay it from your checking account.  In the general journal
+you need to say where the money came from, in addition to where it's
+going to.  These transactions might look like this:
+
+@smallexample
+9/29        Pacific Bell                $23.00     $23.00
+            Checking                   $-23.00          0
+9/30        Checking                   $100.00    $100.00
+      (123) Brokerage                 $-100.00          0
+@end smallexample
+
+The posting must balance to $0: $23 went to Pacific Bell, $23 came from
+Checking.  The next entry shows check number 123 written against your
+brokerage account, transfering money to your checking account.  There is
+nothing left over to be accounted for, since the money has simply moved
+from one account to another in both cases.  This is the basis of
+double-entry accounting: money never pops in or out of existence; it is
+always a posting from one account to another.
+
+Keeping a general journal is the same as keeping two separate journals:
+One for Pacific Bell and one for Checking.  In that case, each time a
+payment is written into one, you write a corresponding withdrawal into
+the other.  This makes it easier to write in a ``running balance'',
+since you don't have to look back at the last time the account was
+referenced---but it also means having a lot of journal books, if you
+deal with multiple accounts.
+
+Here is a good place for an aside on the use of the word `account'.
+Most private people consider an account to be something that holds money
+at an institution for them.  LEDGER uses a more general definition
+of the word.  An account is anywhere money can go.  Other finance
+programs use ``categories'', LEDGER uses accounts. So, for
+example, if you buy some groceries at Trader Joe's then more groceries
+at Whole Foods Markets you might assign the transactions like this
+@smallexample
+2011/03/15   Trader Joe's
+      Expenses:Groceries   $100.00
+      Assets:Checking
+2011/03/15   Whole Food Market
+      Expenses:Groceries   $75.00
+      Assets:Checking
+@end smallexample
+In both cases the money goes to the ``Groceries'' account, even though
+the payees were different.  You can set up your accounts in any way you
+choose.
+
+Enter the beauty of computerized accounting.  The purpose of the
+LEDGER program is to make general journal accounting simple, by keeping
+track of the balances for you.  Your only job is to enter the
+postings.  If a posting does not balance, LEDGER displays an
+error and indicates the incorrect posting.@footnote{In some
+special cases, it automatically balances this transaction for you.}
+
+In summary, there are two aspects of LEDGER use: updating the journal
+data file, and using the LEDGER tool to view the summarized result of
+your transactions.
+
+And just for the sake of example---as a starting point for those who
+want to dive in head-first---here are the journal transactions from above,
+formatted as the LEDGER program wishes to see them:
+
+@smallexample
+2004/09/29 Pacific Bell
+     Expenses:Pacific Bell              $23.00
+     Assets:Checking
+@end smallexample
+
+The account balances and registers in this file, if saved as
+@file{ledger.dat}, could be reported using:
+
+@example
+$ ledger -f ledger.dat balance
+$ ledger -f ledger.dat register checking
+$ ledger -f ledger.dat register bell
+@end example
+
+An important difference between LEDGER and other finance packages is
+that journal will never alter your input file.  You can create and edit
+that file in any way you prefer, but journal is only for analyzing the
+data, not for altering it.
+
+@section More introduction
+
+@menu
+* Building the Program::        
+* Getting Help::                
+@end menu
+
+@node Building the Program, Getting Help, Introduction to Ledger, Introduction to Ledger
+@section Building the program
+
+LEDGER is written in ANSI C++, and should compile on any platform.  It
+depends on the GNU multiprecision integer library (libgmp), and the
+Perl regular expression library (libpcre).  It was developed using GNU
+make and gcc 3.3, on a PowerBook running OS/X.
+
+To build and install once you have these libraries on your system,
+enter these commands:
+
+@example
+./configure && make install
+@end example
+
+@node Getting Help,  , Building the Program, Introduction to Ledger
+@section Getting help
+
+If you need help on how to use LEDGER, or run into problems, you can
+join the LEDGER mailing list at the following Web address:
+
+@example
+http://groups.google.com/group/ledger-cli
+@end example
+
+You can also find help at the @samp{#ledger} channel on the IRC server
+@samp{irc.freenode.net}.
+
+
+@node Principles of Accounting, Keeping a Journal, Introduction to Ledger, Top
+@chapter Principles of Accounting
+
+@node Keeping a Journal, Command-line Syntax, Principles of Accounting, Top
+@chapter Keeping a Journal
+
+The most important part of accounting is keeping a good journal.  If you
+have a good journal, tools can be written to work whatever mathematical
+tricks you need to better understand your spending patterns.  Without a
+good journal, no tool, however smart, can help you.
+
+The LEDGER program aims at making journal transactions as simple as
+possible.  Since it is a command-line tool, it does not provide a user
+interface for keeping a journal.  If you like, you may use GnuCash to
+maintain your journal, in which case LEDGER will read
+GnuCash's data files directly.  In that case, read the GnuCash manual
+now, and skip to the next chapter.
+
+If you are not using GnuCash, but a text editor to maintain your
+journal, read on.  LEDGER has been designed to make data transactions as
+simple as possible, by keeping the journal format easy, and also by
+automagically determining as much information as possible based on the
+nature of your transactions.
+
+For example, you do not need to tell LEDGER about the accounts you
+use.  Any time LEDGER sees a posting involving an account it knows
+nothing about, it will create it@footnote{This also means if you
+misspell an account it will end up getting counted separately from what
+you intended.  The provided Emacs major mode provides for automatically
+filling in account names.}.  If you use a commodity that is new to
+LEDGER, it will create that commodity, and determine its display
+characteristics (placement of the symbol before or after the amount,
+display precision, etc) based on how you used the commodity in the
+posting.
+
+@menu
+* Most Basic Entry::            
+* Commodities::                 
+* Structuring Your Accounts::   
+* Transaction Notes and Tags::  
+* File Format::                 
+* Archiving Previous Years ::   
+* Ledger Tutorial ::            
+@end menu
+
+@node Most Basic Entry, Commodities, Keeping a Journal, Keeping a Journal
+@section The Most Basic Entry
+
+Here is the Pacific Bell example from above, given as a LEDGER
+posting, with the additional of a check number:
+
+@smallexample
+9/29 (1023) Pacific Bell
+    Expenses:Utilities:Phone                   $23.00
+    Assets:Checking                           $-23.00
+@end smallexample
+
+As you can see, it is very similar to what would be written on paper,
+minus the computed balance totals, and adding in account names that work
+better with LEDGER's scheme of things.  In fact, since
+LEDGER is smart about many things, you don't need to specify the
+balanced amount, if it is the same as the first line:
+
+@smallexample
+9/29 (1023) Pacific Bell
+    Expenses:Utilities:Phone                   $23.00
+    Assets:Checking
+@end smallexample
+
+For this transaction, LEDGER will figure out that $-23.00 must come from
+@samp{Assets:Checking} in order to balance the transaction.
+
+Also note the structure of the account entries.  There is an implied
+hierarchy established by separating with colons.  See
+(@pxref{Structuring Your Accounts}) for details and suggestions regarding
+your accounts.
+
+
+
+@strong{The format is very flexible and it isn't necessary that you
+indent and space out things exactly as shown. The only requirements are
+that the start of the transaction (the date typically) is at the
+beginning of the first line of the transaction, and the accounts are
+indented by at least one space.  If you omit the leading spaces in the
+account lines LEDGER will not count the transaction and will not
+give an error.  There must be at least two spaces, or a tab, between the
+amount and the account.  If you do not have adequate separation between
+the amount and the account LEDGER will give an error and stop
+calculating}
+
+@node Commodities, Structuring Your Accounts, Most Basic Entry, Keeping a Journal
+@section Commodities
+
+LEDGER is agnostic when it comes to how you value your accounts.
+Dollars, Euros, Pounds, Francs, etc. are just ``commodities''.  Holdings
+in stocks, bonds, mutual funds and other financial instrument can be
+label using whatever is convenient for you (stock ticker symbols are
+suggested for publicly traded assets).@footnote{you can track ANYTHING,
+even time. As long as it cannot be created or destroyed inside your
+accounting system.}
+
+This is fundamentally different than many common accounting packages,
+which assume the same currency throughout all of your accounts.  This
+means if you typically operate in Euros, but travel to the US and has
+some expenses, you would have to do the currency conversion BEFORE you
+made the entry into your financial system.  With ledger this is not
+required.  In the same journal you can have entries in any or all
+commodities you actually hold.  You can use the reporting capabilities
+to convert all commodities to a single commodity for reporting purposes
+without ever changing the underlying entry.
+
+For example, the following entries reflect transaction made for a
+business trip to Europe from the US:
+
+@smallexample
+2011/09/23   Cash in Munich
+    Assets:Cash  50.00 Euros
+    Assets:Checking  $-66.00
+
+2011/09/24  Dinner in Munich
+    Expenses:Business:Travel  35.00 Euro
+    Assets:Cash
+@end smallexample
+
+This says that $66.00 came out of checking and turned into 50 Euros. The
+implied exchange rate was $1.32.  Then 35 Euros was spent on Dinner in Munich.
+
+
+@node Structuring Your Accounts, Transaction Notes and Tags, Commodities, Keeping a Journal
+@section Structuring your Accounts
+
+There really are no requirements for how you do this, but to preserve
+your sanity we suggest some very basic structure to your accounting
+system.
+
+At the highest level you have five sorts of accounts: Expenses, Assets,
+Income, Liabilities and Equity.  Briefly, you can think of these as places money goes,
+places money sits, places money comes from and money you owe.
+
+Starting the structure off this way will make it simpler for you to get
+answers to the questions you really need to ask about your finances.
+
+@node Transaction Notes and Tags, File Format, Structuring Your Accounts, Keeping a Journal
+@section Transaction Notes and Tags
+LEDGER 3.0 supports entry and transaction ``notes'', which may  
+contain new metadata and tag markers.  Here's an example:
+
+@smallexample
+   2004/05/27 (100) Credit card company
+       ; This is an entry note!
+       ; Sample: Value
+       Liabilities:MasterCard         $20.00
+       ; This is a transaction note!
+       ; Sample: Another Value
+       ; :MyTag:
+       Assets:Bank:Checking
+       ; :AnotherTag:
+@end smallexample
+
+An indented paragraph starting with `;' is parsed as a persistent note  
+for its preceding category.  These notes will get printed back to you  
+with the ``print'' command.  They are accessible to value expressions  
+using the ``note'' variable.
+
+Further, any occurrence of ``:foo:'' in a note will cause a metadata tag  
+for "foo" to be registered for that entry.  You can then search for  
+such transactions using:
+
+@smallexample
+   ledger reg %foo
+   ldeger reg tag foo
+@end smallexample
+
+Also, if any word in the note ends (but does not start) with a colon,  
+the remainder of that line will be taken to be the metadata value for  
+that tag.  That is:
+
+@smallexample
+   ; :foo:bar:baz:  <-- These are three tags
+   ; name: value    <-- this is a tag with a value
+@end smallexample
+
+Tags with value can be searched for just like tags.  In addition, you  
+can further limit your tag search by looking for only those tags that  
+have specific values:
+
+@smallexample
+   ledger reg %name=value
+   ledger reg tag name=value
+@end smallexample
+
+The group-by and sort functions also support tags:
+@smallexample
+ledger --group-by "tag('foo')" bal 
+@end smallexample
+Will produce a balance summary of all transanction with tag `foo' group by transactions wiht the same value for `foo'.
+
+@smallexample
+ledger reg --sort "tag('foo')" %foo
+@end smallexample
+Produces a register view with the transaction have tag `foo' sorted by the tags value.
+
+Comments that occur before an entry, or which starts at column  
+zero, are always ignored and are neither searched nor printed back.
+
+
+
+@node File Format, Archiving Previous Years , Transaction Notes and Tags, Keeping a Journal
+@section File format
+
+The ledger file format is quite simple, but also very flexible.  It
+supports many options, though typically the user can ignore most of
+them.  They are summarized below.
+
+The initial character of each line determines what the line means, and
+how it should be interpreted.  Allowable initial characters are:
+
+@table @code
+@item NUMBER
+A line beginning with a number denotes a transaction.  It may be followed
+by any number of lines, each beginning with whitespace, to denote the
+transaction's account postings.  The format of the first line is:
+
+@example
+DATE[=EDATE] [*|!] [(CODE)] DESC
+@end example
+
+If @samp{*} appears after the date (with optional effective date), it
+indicates the transaction is ``cleared'', which can mean whatever the user
+wants it to mean.  If @samp{!} appears after the date, it indicates d
+the transaction is ``pending''; i.e., tentatively cleared from the user's
+point of view, but not yet actually cleared.  If a @samp{CODE} appears
+in parentheses, it may be used to indicate a check number, or the type
+of the posting.  Following these is the payee, or a description of
+the posting.
+
+The format of each following posting is:
+
+@example
+  ACCOUNT  AMOUNT  [; NOTE]
+@end example
+
+The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual
+postings, or square brackets if it is a virtual postings that
+must balance.  The @samp{AMOUNT} can be followed by a per-unit
+posting cost, by specifying @samp{@@ AMOUNT}, or a complete
+posting cost with @samp{@@@@ AMOUNT}.  Lastly, the @samp{NOTE} may
+specify an actual and/or effective date for the posting by using
+the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or
+@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}.
+
+@item =
+An automated transaction.  A value expression must appear after the equal
+sign.
+
+After this initial line there should be a set of one or more
+postings, just as if it were normal transaction.  If the amounts of the
+postings have no commodity, they will be applied as modifiers to
+whichever real posting is matched by the value expression.
+
+@item ~
+A period transaction.  A period expression must appear after the tilde.
+
+After this initial line there should be a set of one or more
+postings, just as if it were normal transaction.
+
+@item !
+A line beginning with an exclamation mark denotes a command directive.
+It must be immediately followed by the command word.  The supported
+commands are:
+
+@table @samp
+@item !include
+Include the stated journal file.
+
+@item !account
+The account name is given is taken to be the parent of all
+postings that follow, until @samp{!end} is seen.
+
+@item !end
+Ends an account block.
+@end table
+
+@item ;
+A line beginning with a colon indicates a comment, and is
+ignored. Comments will not be returned in a ``print'' response.
+@item indented ; 
+If the semi colon is indented and occurs inside a transaction, it is
+parsed as a persistent note for its preceding category.  These notes or
+tags can be used to augment to reporting and filtering capabilities of
+LEDGER.
+@item Y
+If a line begins with a capital Y, it denotes the year used for all
+subsequent transactions that give a date without a year.  The year should
+appear immediately after the Y, for example: @samp{Y2004}.  This is
+useful at the beginning of a file, to specify the year for that file.
+If all transactions specify a year, however, this command has no effect.
+
+@item P
+Specifies a historical price for a commodity.  These are usually found
+in a pricing history file (see the @option{-Q} option).  The syntax
+is:
+@example
+P DATE SYMBOL PRICE
+@end example
+
+@item N SYMBOL
+Indicates that pricing information is to be ignored for a given
+symbol, nor will quotes ever be downloaded for that symbol.  Useful
+with a home currency, such as the dollar ($).  It is recommended that
+these pricing options be set in the price database file, which
+defaults to @file{~/.pricedb}.  The syntax for this command is:
+@example
+N SYMBOL
+@end example
+
+@item D AMOUNT
+Specifies the default commodity to use, by specifying an amount in the
+expected format.  The @command{transaction} command will use this commodity
+as the default when none other can be determined.  This command may be
+used multiple times, to set the default flags for different
+commodities; whichever is seen last is used as the default commodity.
+For example, to set US dollars as the default commodity, while also
+setting the thousands flag and decimal flag for that commodity, use:
+@example
+D $1,000.00
+@end example
+
+@item C AMOUNT1 = AMOUNT2
+Specifies a commodity conversion, where the first amount is given to
+be equivalent to the second amount.  The first amount should use the
+decimal precision desired during reporting:
+@example
+C 1.00 Kb = 1024 bytes
+@end example
+
+@item i, o, b, h
+These four relate to timeclock support, which permits LEDGER to read
+timelog files.  See the timeclock's documentation for more info on the
+syntax of its timelog files.
+@end table
+
+@node Archiving Previous Years , Ledger Tutorial , File Format, Keeping a Journal
+@section Archiving Previous Years
+
+@node Ledger Tutorial ,  , Archiving Previous Years , Keeping a Journal
+@section Ledger Tutorial
+
+
+@node Command-line Syntax, Basic Reporting Commands, Keeping a Journal, Top
+@chapter Command-line Syntax
+
+
+@menu
+* Cookbook::                    
+* Quick Reference::             
+* Commands::                    
+* Options::                     
+* Period Expressions::          
+@end menu
+
+@node Cookbook, Quick Reference, Command-line Syntax, Command-line Syntax
+@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
+
+@node Quick Reference, Commands, Cookbook, Command-line Syntax
+@section Quick Reference
+
+This chapter describes LEDGER'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.
+
+LEDGER 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.
+
+
+@node Commands, Options, Quick Reference, Command-line Syntax
+@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 LEDGER 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 LEDGER.  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 LEDGER.
+
+@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 LEDGER 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, Command-line Syntax
+@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 LEDGER 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 LEDGER 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 LEDGER 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,  , Options, Command-line Syntax
+@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 Basic Reporting Commands, Value Expressions, Command-line Syntax, Top
+@chapter Basic Reporting Commands
+
+@menu
+* Budgeting and Forecasting::   
+@end menu
+
+@node Budgeting and Forecasting,  , Basic Reporting Commands, Basic Reporting Commands
+@section Budgeting and Forecasting
+
+
+@node Value Expressions, Format Strings, Basic Reporting Commands, Top
+@chapter Value Expressions
+
+Value expressions are an expression language used by LEDGER 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
+
+@menu
+* Variables::                   
+@end menu
+
+@node Variables,  , Value Expressions, Value Expressions
+@section 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
+
+@subsection 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
+
+@subsection 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
+
+@section 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
+
+@section Operators
+
+The binary and ternary operators, in order of precedence, are:
+
+@enumerate
+@item @samp{* /}
+@item @samp{+ -}
+@item @samp{! < > =}
+@item @samp{& | ?:}
+@end enumerate
+
+@section 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
+
+
+@node Format Strings, Journal File Format, Value Expressions, Top
+@chapter 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 Journal File Format, Extending with Python, Format Strings, Top
+@chapter LEDGER Journal File Format
+
+This chapter offers a complete description of the journal data format,
+suitable for implementors in other languages to follow.  For users,
+the chapter on keeping a journal is less extensive, but more typical
+of common usage (@pxref{Keeping a Journal}).
+
+Data is collected in the form of @dfn{transactions} which occur in one
+or more @dfn{journal files}.  Each transaction, in turn, is made up of
+one or more @dfn{postings}, which describe how @dfn{amounts} flow from
+one @dfn{account} to another.  Here is an example of the simplest of
+journal files:
+
+@example
+2010/05/31 Just an example
+    Expenses:Some:Account                $100.00
+    Income:Another:Account
+@end example
+
+In this example, there is a transaction date, a payee, or description
+of the transaction, and two postings.  The postings show movement of
+one hundred dollars from an account within the Income hierarchy, to
+the specified expense account.  The name and meaning of these accounts
+in arbitrary, with no preferences implied, although you will find it
+useful to follow standard accounting practice (@pxref{Principles of
+Accounting}).
+
+Since an amount is missing from the second posting, it is assumed to
+be the inverse of the first.  This guarantee the cardinal rule of
+double-entry accounting: the sum of every transaction must balance to
+zero, or it is in error.  Whenever Ledger encounters a @dfn{null
+posting} in a transaction, it uses it to balance the remainder.
+
+It is also typical---though not enforced---to think of the first
+posting as the destination, and the final as the source.  Thus, the
+amount of the first posting is typically positive.  Consider:
+
+@example
+2010/05/31 An income transaction
+    Assets:Checking       $1,000.00
+    Income:Salary
+
+2010/05/31 An expense transaction
+    Expenses:Dining         $100.00
+    Assets:Checking
+@end example
+
+@emph{Note:} It is important to note that there must be at least two spaces between
+the end of the post and the beginning of the amount (including and
+commdity designator).
+
+@section Specifying amounts
+
+The heart of a journal is the amounts it records, and this fact is
+reflected in the diversity of amount expressions allowed.  All of them
+are covered here, though it must be said that sometimes, there are
+multiple ways to achieve a desired result.
+
+@subsection Integer amounts
+
+In the simplest form, bare decimal numbers are accepted:
+
+@example
+2010/05/31 An income transaction
+    Assets:Checking        1000.00
+    Income:Salary
+@end example
+
+Such amounts may only use an optional period for a decimal point.
+These are referred to as @dfn{integer amounts} or @dfn{uncommoditized
+amounts}.  In most ways they are similar to @dfn{commoditized
+amounts}, but for one signficant difference: They always display in
+reports with @dfn{full precision}.  More on this in a moment.  For
+now, a word must be said about how Ledger stores numbers.
+
+Every number parsed by Ledger is stored internally as an
+infinite-precision rational value.  Floating-point math is never used,
+as it cannot be trusted to maintain precision of values.  So, in the
+case of @samp{1000.00} above, the internal value is @samp{100000/100}.
+
+While rational numbers are great at not losing precision, the question
+arises: How should they be displayed?  A number like @samp{100000/100}
+is no problem, since it represents a clean decimal fraction.  But what
+about when the number @samp{1/1} is divided by three?  How should one
+print @samp{1/3}, an infinitely repeating decimal?
+
+Ledger gets around this problem by rendering rationals into decimal at
+the last possible moment, and only for display.  As such, some
+rounding must, at times, occur.  If this rounding would affect the
+calculation of a running total, special accommodation postings are
+generated to make you aware it has happened.  In practice, it happens
+rarely, but even then it does not reflect adjustment of the
+@emph{internal amount}, only the displayed amount.
+
+What has still not been answered is how Ledger rounds values.  Should
+@samp{1/3} be printed as @samp{0.33} or @samp{0.33333}?  For
+commoditized amounts, the number of decimal places is decided by
+observing how each commodity is used; but in the case of integer
+amounts, an arbitrary factor must be chosen.  Initially, this factor
+is six.  Thus, @samp{1/3} is printed back as @samp{0.333333}.
+Further, this rounding factor becomes associated with each particular
+value, and is carried through mathematical operations.  For example,
+if that particular number were multiplied by itself, the decimal
+precision of the result would be twelve.  Addition and subtraction do
+not affect precision.
+
+Since each integer amount retains its own display precision, this is
+called @dfn{full precision}, as opposed to commoditized amounts, which
+always look to their commodity to know what precision they should
+round to, and so use @dfn{commodity precision}.
+
+@subsection Commoditized amounts
+
+A @dfn{commoditized amount} is an integer amount which has an
+associated commodity.  This commodity can appear before or after the
+amount, and may or may not be separated from it by a space.  Most
+characters are allowed in a commodity name, except for the following:
+
+@itemize
+@item Any kind of whitespace
+@item Numerical digits
+@item Punctuation: @samp{.,;:?!}
+@item Mathematical and logical operators: @samp{-+*/^&|=}
+@item Bracketing characters: @samp{<>[]()}@{@}
+@item The at symbol: @samp{@@}
+@end itemize
+
+And yet, any of these may appear in a commodity name if it is
+surrounded by double quotes, for example:
+
+@example
+100 "EUN+133"
+@end example
+
+If a @dfn{quoted commodity} is found, it is displayed in quotes as
+well, to avoid any confusion as to which part is the amount, and which
+part is the commodity.
+
+Another feature of commoditized amounts is that they are reported back
+in the same form as parsed.  If you specify dollar amounts using
+@samp{$100}, they will print the same; likewise with @samp{100 $} or
+@samp{$100.000}.  You may even use decimal commas, such as
+@samp{$100,00}, or thousand-marks, as in @samp{$10,000.00}.
+
+These display characteristics become associated with the commodity,
+with the result being that all amounts of the same commodity are
+reported consistently.  Where this is most noticeable is the
+@dfn{display precision}, which is determined by the most precise value
+seen for a given commodity.  In most cases.
+
+Ledger makes a distinction by @dfn{observed amounts} and unobserved
+amounts.  An observed amount is critiqued by Ledger to determine how
+amounts using that commodity should be displayed; unobserved amounts
+are significant in their value only---no matter how they are
+specified, it does not change how other amounts in that commodity will
+be displayed.
+
+An example of this is found in cost expressions, covered next.
+
+@section Posting costs
+
+You have seen how to specify either a commoditized or an integer
+amount for a posting.  But what if the amount you paid for something
+was in one commodity, and the amount received was another?  There are
+two main ways to express this:
+
+@example
+2010/05/31 Farmer's Market
+    Assets:My Larder           100 apples
+    Assets:Checking                $20.00
+@end example
+
+In this example, you have paid twenty dollars for one hundred apples.
+The cost to you is twenty cents per apple, and Ledger calculates this
+implied cost for you.  You can also make the cost explicit using a
+@dfn{cost amount}:
+
+@example
+2010/05/31 Farmer's Market
+    Assets:My Larder           100 apples @@ $0.200000
+    Assets:Checking
+@end example
+
+Here the @dfn{per-unit cost} is given explicitly in the form of a cost
+amount; and since cost amount are @emph{unobserved}, the use of six
+decimal places has no effect on how dollar amounts are displayed in
+the final report.  You can also specify the @dfn{total cost}:
+
+@example
+2010/05/31 Farmer's Market
+    Assets:My Larder           100 apples @@@@ $20
+    Assets:Checking
+@end example
+
+These three forms have identical meaning.  In most cases the first is
+preferred, but the second two are necessary when more than two
+postings are involved:
+
+@example
+2010/05/31 Farmer's Market
+    Assets:My Larder           100 apples        @@ $0.200000
+    Assets:My Larder           100 pineapples    @@ $0.33
+    Assets:My Larder           100 "crab apples" @@ $0.04
+    Assets:Checking
+@end example
+
+Here the implied cost is @samp{$57.00}, which is entered into the null
+posting automatically so that the transaction balances.
+
+@subsection Primary commodities
+
+In every transaction involving more than one commodity, there is
+always one which is the @dfn{primary commodity}.  This commodity
+should be thought of as the exchange commodity, or the commodity used
+to buy and sells units of the other commodity.  In the fruit examples
+above, dollars are the primary commodity.  This is decided by Ledger
+on the placement of the commodity in the transaction:
+
+@example
+2010/05/31 Sample Transaction
+    Expenses               100 secondary
+    Assets                  50 primary
+
+2010/05/31 Sample Transaction
+    Expenses               100 secondary @@ 0.5 primary
+    Assets
+
+2010/05/31 Sample Transaction
+    Expenses               100 secondary @@@@ 50 primary
+    Assets
+@end example
+
+The only case where knowledge of primary versus secondary comes into
+play is in reports that use the @option{-V} or @option{-B} options.
+With these, only primary commodities are shown.
+
+If a transaction uses only one commodity, this commodity is also
+considered a primary.  In fact, when Ledger goes about ensures that
+all transactions balance to zero, it only ever asks this of primary
+commodities.
+
+@node Extending with Python,  , Journal File Format, Top
+@chapter Extending with Python
+
+@bye