sfos/ledger
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial commit of new documentation structure

Browse source
This commit is contained in:
Craig Earls 2011-09-28 09:00:44 -07:00
parent 11a9063958
commit cce00a33de
6 changed files with 1630 additions and 87 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

161
doc/L3-Introduction.texi Normal file
View file

@ -0,0 +1,161 @@
@c -*-texinfo-*-
@ledgerprog@ 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. @ledgerprog@ uses a more general definition
of the word. An account is anywhere money can go. Other finance
programs use ``categories'', @ledgerprog@ 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
@ledgerprog@ 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, @ledgerprog@ 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 @ledgerprog@ use: updating the journal
data file, and using the @ledgerprog@ 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 @ledgerprog 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 @ledgerprog@ 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
@ledgerprog@ 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 @ledgerprog, or run into problems, you can
join the @ledgerprog@ 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 Quick Reference, Ledger Tutorial, Introduction, Top

323
doc/L3-Journal.texi Normal file
View file

@ -0,0 +1,323 @@
@c -*-texinfo-*-
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 @ledgerprog@ 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 @ledgerprog@ 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. @ledgerprog@ 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 @ledgerprog@ about the accounts you
use. Any time @ledgerprog@ 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
@ledgerprog@, 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.
@section The Most Basic Entry
Here is the Pacific Bell example from above, given as a @ledgerprog@
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 @ledgerprog@'s scheme of things. In fact, since
@ledgerprog@ 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, @ledgerprog@ 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 @ledgerprog@ 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 @ledgerprog@ will give an error and stop
calculating}
@section Commodities
@ledgerprog@ 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.
@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.
@section Transaction Notes and Tags
@ledgerprog@ 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 balalnce 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, , Value expressions, Quick Reference
@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
@ledgerprog.
@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 @ledgerprog@ to read
timelog files. See the timeclock's documentation for more info on the
syntax of its timelog files.
@end table

91
doc/ledger3.texi → doc/L3-JournalFormat.texi
View file

@ -1,80 +1,3 @@
\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
@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
@chapter Introduction
@chapter Principles of accounting
@chapter Keeping a journal
@chapter Basic reporting commands
@chapter Command-line syntax
@chapter Journal data format
This chapter offers a complete description of the journal data format,
suitable for implementors in other languages to follow. For users,
@ -121,6 +44,10 @@ amount of the first posting is typically positive. Consider:
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
@ -310,13 +237,3 @@ 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.
@chapter Report queries
@chapter Value expressions
@chapter Format strings
@chapter Extending with Python
@bye

96
doc/L3-Main.texi Normal file
View file

@ -0,0 +1,96 @@
\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 @ledgerprog: 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
@chapter Introduction
@include Introduction3.texi
@chapter Principles of accounting
@include Principles3.texi
@chapter Keeping a journal
@include Journal3.texi
@chapter Basic reporting commands
@chapter Command-line syntax
@include Syntax3.texi
@chapter Journal data format
@include JournalFormat3.texi
@chapter Report queries
@chapter Value expressions
@chapter Format strings
@chapter Extending with Python
@bye

2
doc/L3-Principles.texi Normal file
View file

@ -0,0 +1,2 @@
@c -*-texinfo-*-

1044
doc/L3-Syntax.texi Normal file
View file

File diff suppressed because it is too large Load diff