Added skeletons for new chapters to the Ledger documentation.

They still need finishing, and some of them may eventually replace some
existing chapters.
This commit is contained in:
John Wiegley 2009-02-06 14:32:29 -04:00
parent 68d5bc1f32
commit 7c77a1af31

View file

@ -55,6 +55,8 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@ifnottex
@node Top, Introduction, (dir), (dir)
@top Overview
@insertcopying
@end ifnottex
@menu
@ -3944,4 +3946,130 @@ That is the extent of the XML data format used by Ledger. It will
output such data if the @command{xml} command is used, and can read
the same data.
@chapter Anatomy of a journal file
Everything begins with a journal file---the anatomy of which is covered
in detail in chapter one. To review: a @emph{journal} contains one or
more @emph{entries}, each of which refers to two or more
@emph{transactions}. A @emph{transaction} specifies that a given
@emph{amount} is added to, or subtracted from, an @emph{account}.
(@emph{Accounts} may be nested hierarchically by separating the elements
using a colon). Lastly, an @emph{amount} is a figure representing a
given @emph{quantity} of a @emph{commodity}. Here follows a review of
these terms, which are all used extensively throughout this chapter:
@table @emph
@item journal
A journal is a data file containing a series of entries.
@item entry
An entry relates a group of two or more transactions, with the absolute
constraint that the total sum of an entry's transactions must equal
zero. That is, every entry in a journal must @emph{balance} to zero.
@item transaction
Transactions record how commodities are moved between accounts. If you
spent money on a movie ticket, for example, such an entry would have two
transactions: One to show how the money was taken from your wallet, and
another to show how it was applied to your movie expenses.
@item account
An account
@item amount
@item quantity
@item commodity
@end table
@chapter Example accounting practices
@chapter Generating useful reports
Once you have a journal file representing a recent history of your
finances, the next step is to generate reports in order to give richer
meaning to this data. For example: Where do you spend your money? Do
you have enough to cover upcoming expenses? Are you creating or losing
net worth? Are your investment performing well? All of these questions
can be answered easily with Ledger---if you know how to ask them.
Preparing complex reports is not a simple task, but neither is it a
difficult one. All that's required is a proper understanding of how
Ledger views your data, and how it prepares it for reporting.
After Ledger reads a journal file, it creates an in-memory
representation reflecting the order and composition of those entries.
@chapter Value expressions
@chapter Format strings
@chapter Extensions in Python
@chapter The design of Ledger
The following sections discuss how Ledger is architected, from the
ground up, and will show how to use the various parts of the Ledger
library from your own scripts. Ledger essentially follows five steps in
reporting data to the user:
@begin enumerate
@item Parse journal file into an internal representation
@item Perform any implied math within the journal file
@item ``Face'' this internal representation as a virtual document
@item Apply a series of transforms to the virtual document
@item Display the virtual document using a formatting command
@end enumerate
The calculations in step two are specified by the user, such as when a
transaction's value might contain mathematical operators. The
calculations in step four are implied in the transformations, for
example when the @option{--average} option is used.
At the core, however, Ledger is basically a sophisticated calculator
with special knowledge about commoditized values. It knows what you
mean if you add ten dollars to twenty euros, and later ask for the
balance of that particular account. So it follows that first we must
discuss how Ledger deals with math, and from there move on to describing
how the steps above are achieved.
@section Numerics
@subsection Basic amounts
The most fundamental type in Ledger is the amount, which may or may not
have a commodity attached to it. First, we'll deal with the bare case,
just to show how the amount type works. In C++, most all of Ledger's
internal types end in @example{_t}; in Python, the same type name is
used, but the @example{_t} suffix is dropped. Examples of usage in both
languages will be presented throughout.
amount_t
commodity_t
updater_t
datetime_t
balance_t
balance_pair_t
value_t
valexpr_t
format_t
mask_t
@section Journal Representation
journal_t
account_t
entry_t
transaction_t
parser_t
@section Reporting
@section Terminal Interface
@section General Utility
@bye