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:
parent
68d5bc1f32
commit
7c77a1af31
1 changed files with 128 additions and 0 deletions
128
doc/ledger.texi
128
doc/ledger.texi
|
|
@ -55,6 +55,8 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||||
@ifnottex
|
@ifnottex
|
||||||
@node Top, Introduction, (dir), (dir)
|
@node Top, Introduction, (dir), (dir)
|
||||||
@top Overview
|
@top Overview
|
||||||
|
|
||||||
|
@insertcopying
|
||||||
@end ifnottex
|
@end ifnottex
|
||||||
|
|
||||||
@menu
|
@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
|
output such data if the @command{xml} command is used, and can read
|
||||||
the same data.
|
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
|
@bye
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue