General cleanup, expanded the commenting section, addex index entries
This commit is contained in:
Craig Earls
John Wiegley
parent
20f0e236c0
commit
eb84048127
1 changed files with 345 additions and 308 deletions
653
doc/ledger3.texi
653
doc/ledger3.texi
|
|
@ -45,7 +45,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|||
@titlepage
|
||||
@title Ledger: Command-Line Accounting
|
||||
@subtitle For Version 3.0 of Ledger
|
||||
@subtitle Draft Manual Time-stamp: <2011-12-13 15:17 (cpearls)>
|
||||
@subtitle Draft Manual Time-stamp: <2011-12-14 09:58 (cpearls)>
|
||||
@author John Wiegley
|
||||
@end titlepage
|
||||
|
||||
|
|
@ -253,6 +253,7 @@ enter these commands:
|
|||
./configure && make install
|
||||
@end smallexample
|
||||
|
||||
@findex help
|
||||
@node Getting Help, , Building the Program, Introduction to Ledger
|
||||
@section Getting help
|
||||
Ledger has a complete online help system based on GNU Info. This manual
|
||||
|
|
@ -262,22 +263,23 @@ options:
|
|||
|
||||
@option{ledger --help-info} brings up help on how to use the info system.
|
||||
|
||||
@option{ledger --help-comm concept} search the manual index and bring up pages associated with `concept'.
|
||||
@option{ledger --help-comm concept} searches the manual index and brings up pages associated with `concept'.
|
||||
|
||||
@option{ledger --help-calc} brings up the value expressions chapter of the manual
|
||||
@option{ledger --help-calc} brings up the value expressions chapter of this manual (@pxref{Value Expressions}).
|
||||
|
||||
@option{ledger --help-disp} brings up the Format Strings chapter of the manual.
|
||||
@option{ledger --help-disp} brings up the Format Strings chapter of this manual (@pxref{Format Strings}).
|
||||
|
||||
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:
|
||||
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:
|
||||
|
||||
@smallexample
|
||||
http://groups.google.com/group/ledger-cli
|
||||
@end smallexample
|
||||
|
||||
You can also find help at the @samp{#ledger} channel on the IRC server
|
||||
@noindent You can also find help at the @samp{#ledger} channel on the IRC server
|
||||
@samp{irc.freenode.net}.
|
||||
|
||||
@cindex tutorial
|
||||
@node Ledger Tutorial , Principles of Accounting, Introduction to Ledger, Top
|
||||
@chapter Ledger Tutorial
|
||||
|
||||
|
|
@ -289,7 +291,7 @@ You can also find help at the @samp{#ledger} channel on the IRC server
|
|||
|
||||
@node Start a Journal, Run Some Reports, Ledger Tutorial , Ledger Tutorial
|
||||
@section Start a Journal File
|
||||
@cindex Journals
|
||||
@cindex journals
|
||||
A journal is a record of your financial transactions and will be central
|
||||
to using Ledger. For now we just want to get a taste of what Ledger can
|
||||
do. An example journal is included with the source code distribution,
|
||||
|
|
@ -313,7 +315,7 @@ to @xref{Keeping a Journal}.
|
|||
@node Balance Report, Register Report, Run Some Reports, Run Some Reports
|
||||
@subsection Balance Report
|
||||
@cindex balance report
|
||||
@findex balance
|
||||
@findex balance (bal)
|
||||
To find the balances of all of your accounts, run this command:
|
||||
|
||||
@smallexample
|
||||
|
|
@ -367,7 +369,7 @@ $ ledger -f drewr3.dat balance Assets Liabilities
|
|||
@node Register Report, Cleared Report, Balance Report, Run Some Reports
|
||||
@subsection Register Report
|
||||
@cindex register report
|
||||
@findex register
|
||||
@findex register (reg)
|
||||
To show all transactions and a running total:
|
||||
@smallexample
|
||||
ledger -f drewr3.dat register
|
||||
|
|
@ -410,7 +412,8 @@ Ledger will generate:
|
|||
@end smallexample
|
||||
|
||||
@noindent To limit this to a more useful subset, simply add the accounts you are are interested in seeing transactions for:
|
||||
|
||||
@cindex accounts, limiting by
|
||||
@cindex limiting by accounts
|
||||
@smallexample
|
||||
$ ledger -f drewr3.dat register Groceries
|
||||
10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50
|
||||
|
|
@ -444,7 +447,8 @@ $ ledger -f drewr3.dat register payee "Organic"
|
|||
|
||||
@node Cleared Report, Using the Windows command line, Register Report, Run Some Reports
|
||||
@subsection Cleared Report
|
||||
|
||||
@cindex cleared report
|
||||
@findex cleared
|
||||
A very useful report is to show what your obligations are versus what
|
||||
expenditures have actually been recorded. It can take several days for
|
||||
a check to clear, but you should treat it as money spent. The
|
||||
|
|
@ -470,14 +474,15 @@ $ ledger -f drewr3.dat cleared
|
|||
$ -20.00 0 MasterCard
|
||||
$ 200.00 0 Mortgage:Principal
|
||||
$ -243.60 0 Tithe
|
||||
---------------- ---------------- ---------
|
||||
---------------- ---------------- ---------
|
||||
$ -243.60 0
|
||||
@end smallexample
|
||||
|
||||
@noindent The first column shows the outstanding balance, the second column show the ``cleared'' balance.
|
||||
@node Using the Windows command line, , Cleared Report, Run Some Reports
|
||||
@subsection Using the Windows Command Line
|
||||
|
||||
@cindex windows cmd.exe
|
||||
@cindex currency symbol display on windows
|
||||
Using ledger under the windows command shell has one significant
|
||||
limitation. CMD.exe is limited to standard ASCII characters and as such
|
||||
cannot display any currency symbols other than dollar signs ($).
|
||||
|
|
@ -500,6 +505,7 @@ cannot display any currency symbols other than dollar signs ($).
|
|||
@item @strong{Report} @tab @strong{Description}
|
||||
@item @code{balance} @tab Show account balances
|
||||
@item @code{register} @tab Show all transactions with running total
|
||||
@item @code{csv} @tab Show transactions in csv format, for exporting to other programs
|
||||
@item @code{print} @tab Print transaction in a ledger readable format
|
||||
@item @code{output} @tab Similar to print without included transactions
|
||||
@item @code{xml} @tab Produce XML output of the register command
|
||||
|
|
@ -593,7 +599,7 @@ cannot display any currency symbols other than dollar signs ($).
|
|||
@item @code{-M} @tab @code{--Monthly} @tab Group postings by month
|
||||
@item @code{} @tab @code{--quarterly} @tab Group postings by quarter
|
||||
@item @code{-Y} @tab @code{--yearly} @tab Group postings by year
|
||||
@item @code{-dow} @tab @code{} @tab Group by day of weeks
|
||||
@item @code{} @tab @code{--dow} @tab Group by day of weeks
|
||||
@item @code{-s} @tab @code{--subtotal} @tab Group posting together, similar to balance report
|
||||
@end multitable
|
||||
|
||||
|
|
@ -615,12 +621,10 @@ cannot display any currency symbols other than dollar signs ($).
|
|||
@node Principles of Accounting, Keeping a Journal, Ledger Tutorial , Top
|
||||
@chapter Principles of Accounting with Ledger
|
||||
|
||||
|
||||
@menu
|
||||
* Accounting with Ledger::
|
||||
* Stating where money goes::
|
||||
* Assets and Liabilities::
|
||||
* Typical queries::
|
||||
* Commodities and Currencies::
|
||||
* Accounts and Inventories::
|
||||
* Understanding Equity::
|
||||
|
|
@ -693,9 +697,10 @@ place has less money now than when you started your ledger; and every
|
|||
positive figure means that that account or person or place has more
|
||||
money now than when you started your ledger. Make sense?
|
||||
|
||||
@node Assets and Liabilities, Typical queries, Stating where money goes, Principles of Accounting
|
||||
@node Assets and Liabilities, Commodities and Currencies, Stating where money goes, Principles of Accounting
|
||||
@section Assets and Liabilities
|
||||
|
||||
@cindex assets and liabilities
|
||||
@cindex debts are liabilities
|
||||
Assets are money that you have, and Liabilities are money that you
|
||||
owe. ``Liabilities'' is just a more inclusive name for Debts.
|
||||
|
||||
|
|
@ -762,7 +767,7 @@ This assumes, of course, that you use account names like
|
|||
@menu
|
||||
* Tracking reimbursable expenses::
|
||||
@end menu
|
||||
|
||||
@cindex reimbursable expense tracking
|
||||
@node Tracking reimbursable expenses, , Assets and Liabilities, Assets and Liabilities
|
||||
@subsection Tracking reimbursable expenses
|
||||
|
||||
|
|
@ -913,125 +918,7 @@ spent using your MasterCard on behalf of Company XYZ, and that Company
|
|||
XYZ spent the money on computer software and paid it back about two
|
||||
weeks later.
|
||||
|
||||
@node Typical queries, Commodities and Currencies, Assets and Liabilities, Principles of Accounting
|
||||
@section Typical queries
|
||||
|
||||
A query such as the following shows all expenses since last
|
||||
October, sorted by total:
|
||||
|
||||
@example
|
||||
ledger -b "last oct" -s -S T bal ^expenses
|
||||
@end example
|
||||
|
||||
From left to right the options mean: Show transactions since October, 2003;
|
||||
show all sub-accounts; sort by the absolute value of the total; and
|
||||
report the balance for all expenses.
|
||||
|
||||
@menu
|
||||
* Reporting monthly expenses::
|
||||
* Visualizing with Gnuplot::
|
||||
@end menu
|
||||
|
||||
@node Reporting monthly expenses, Visualizing with Gnuplot, Typical queries, Typical queries
|
||||
@subsection Reporting monthly expenses
|
||||
|
||||
The following query makes it easy to see monthly expenses, with each
|
||||
month's expenses sorted by the amount:
|
||||
|
||||
@example
|
||||
ledger -M --period-sort t reg ^expenses
|
||||
@end example
|
||||
|
||||
Now, you might wonder where the money came from to pay for these
|
||||
things. To see that report, add @option{-r}, which shows the
|
||||
``related account'' postings:
|
||||
|
||||
@example
|
||||
ledger -M --period-sort t -r reg ^expenses
|
||||
@end example
|
||||
|
||||
But maybe this prints too much information. You might just want to
|
||||
see how much you're spending with your MasterCard. That kind of query
|
||||
requires the use of a display predicate, since the postings
|
||||
calculated must match @samp{^expenses}, while the postings
|
||||
displayed must match @samp{mastercard}. The command would be:
|
||||
|
||||
@example
|
||||
ledger -M -r -d /mastercard/ reg ^expenses
|
||||
@end example
|
||||
|
||||
This query says: Report monthly subtotals; report the ``related
|
||||
account'' postings; display only related postings whose
|
||||
account matches @samp{mastercard}, and base the calculation on
|
||||
postings matching @samp{^expenses}.
|
||||
|
||||
This works just as well for report the overall total, too:
|
||||
|
||||
@example
|
||||
ledger -s -r -d /mastercard/ reg ^expenses
|
||||
@end example
|
||||
|
||||
The @option{-s} option subtotals all postings, just as @option{-M}
|
||||
subtotaled by the month. The running total in both cases is off,
|
||||
however, since a display expression is being used.
|
||||
|
||||
@node Visualizing with Gnuplot, , Reporting monthly expenses, Typical queries
|
||||
@subsection Visualizing with Gnuplot
|
||||
|
||||
If you have @command{Gnuplot} installed, you can graph any of the
|
||||
above register reports. The script to do this is included in the
|
||||
ledger distribution, and is named @file{scripts/report}. Install
|
||||
@file{report} anywhere along your @env{PATH}, and then use
|
||||
@command{report} instead of @command{ledger} when doing a register
|
||||
report. The only thing to keep in mind is that you must specify
|
||||
@option{-j} or @option{-J} to indicate whether Gnuplot should plot the
|
||||
amount, or the running total. For example, this command plots total
|
||||
monthly expenses made on your MasterCard.
|
||||
|
||||
@example
|
||||
report -j -M -r -d /mastercard/ reg ^expenses
|
||||
@end example
|
||||
|
||||
The @command{report} script is a very simple Bourne shell script, that
|
||||
passes a set of scripted commands to Gnuplot. Feel free to modify the
|
||||
script to your liking, since you may prefer histograms to line plots,
|
||||
for example.
|
||||
|
||||
@menu
|
||||
* Typical plots::
|
||||
@end menu
|
||||
|
||||
@node Typical plots, , Visualizing with Gnuplot, Visualizing with Gnuplot
|
||||
@subsubsection Typical plots
|
||||
|
||||
Here are some useful plots:
|
||||
|
||||
@smallexample
|
||||
report -j -M reg ^expenses # monthly expenses
|
||||
report -J reg checking # checking account balance
|
||||
report -J reg ^income ^expenses # cash flow report
|
||||
|
||||
# net worth report, ignoring non-$ postings
|
||||
|
||||
report -J -l "Ua>=@{\$0.01@}" reg ^assets ^liab
|
||||
|
||||
# net worth report starting last February. the use of a display
|
||||
# predicate (-d) is needed, otherwise the balance will start at
|
||||
# zero, and thus the y-axis will not reflect the true balance
|
||||
|
||||
report -J -l "Ua>=@{\$0.01@}" -d "d>=[last feb]" reg ^assets ^liab
|
||||
@end smallexample
|
||||
|
||||
The last report uses both a calculation predicate (@option{-l}) and a
|
||||
display predicate (@option{-d}). The calculation predicates limits
|
||||
the report to postings whose amount is greater than $1 (which can
|
||||
only happen if the posting amount is in dollars). The display
|
||||
predicate limits the transactions @emph{displayed} to just those since last
|
||||
February, even those transactions from before then will be computed as part
|
||||
of the balance.
|
||||
|
||||
|
||||
@node Commodities and Currencies, Accounts and Inventories, Typical queries, Principles of Accounting
|
||||
@node Commodities and Currencies, Accounts and Inventories, Assets and Liabilities, Principles of Accounting
|
||||
@section Commodities and Currencies
|
||||
|
||||
Ledger makes no assumptions about the commodities you use; it only
|
||||
|
|
@ -1483,17 +1370,17 @@ posting.
|
|||
|
||||
@menu
|
||||
* Most Basic Entry::
|
||||
* Commenting on your journal::
|
||||
* Starting up::
|
||||
* Currency and Commodities::
|
||||
* Structuring Your Accounts::
|
||||
* Commenting on your journal::
|
||||
* Currency and Commodities::
|
||||
* Advanced Transactions::
|
||||
* File Format::
|
||||
* Archiving Previous Years ::
|
||||
* Using Emacs::
|
||||
@end menu
|
||||
|
||||
@node Most Basic Entry, Commenting on your journal, Keeping a Journal, Keeping a Journal
|
||||
@node Most Basic Entry, Starting up, Keeping a Journal, Keeping a Journal
|
||||
@section The Most Basic Entry
|
||||
|
||||
Here is the Pacific Bell example from above, given as a Ledger
|
||||
|
|
@ -1532,51 +1419,21 @@ 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}
|
||||
account lines Ledger will generate 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}
|
||||
|
||||
|
||||
@menu
|
||||
* Comments::
|
||||
@end menu
|
||||
|
||||
@node Commenting on your journal, Starting up, Most Basic Entry, Keeping a Journal
|
||||
@section Commenting on your Journal
|
||||
@cindex comments, characters
|
||||
Comments are generally started using a ';'. However, in order to
|
||||
increase compatibility with other text manipulation programs and methods
|
||||
three additional comment characters are valid if used at the beginning
|
||||
of a line: @code{#}, @code{|}, and @code{*} and @code{%}.
|
||||
@cindex block comments
|
||||
@cindex comments, block
|
||||
Block comments can be made by use @code{@!comment} ... @code{@!end comment}
|
||||
|
||||
@smallexample
|
||||
|
||||
; This is a single line comment,
|
||||
# and this,
|
||||
% and this,
|
||||
| and this,
|
||||
* and this.
|
||||
|
||||
!comment
|
||||
This is a block comment with
|
||||
multipl lines
|
||||
!end comment
|
||||
@end smallexample
|
||||
|
||||
@node Starting up, Currency and Commodities, Commenting on your journal, Keeping a Journal
|
||||
@node Starting up, Structuring Your Accounts, Most Basic Entry, Keeping a Journal
|
||||
@section Starting up
|
||||
|
||||
@cindex initial equity
|
||||
@cindex beginning ledger
|
||||
|
||||
Unless you have recently arrived from another planet, you already have a
|
||||
financial state. You need to capture that financial state so that Ledger
|
||||
has a starting point.
|
||||
financial state. You need to capture that financial state so that
|
||||
Ledger has a starting point.
|
||||
|
||||
At some convenient point in time you new the balances and outstanding
|
||||
obligation of every financial account you have. Those amounts form the
|
||||
|
|
@ -1603,7 +1460,85 @@ There is nothing special about the name ``Opening Balances'' as the
|
|||
payee of the account name, anything convenient that you understand will
|
||||
work.
|
||||
|
||||
@node Currency and Commodities, Structuring Your Accounts, Starting up, Keeping a Journal
|
||||
@node Structuring Your Accounts, Commenting on your journal, Starting up, Keeping a Journal
|
||||
@section Structuring your Accounts
|
||||
|
||||
@cindex accounts, naming
|
||||
@cindex naming 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:
|
||||
@enumerate
|
||||
@item
|
||||
Expenses: where money goes
|
||||
@item
|
||||
Assets: where money sits
|
||||
@item
|
||||
Income: where money comes from
|
||||
@item
|
||||
Liabilities: money you owe
|
||||
@item
|
||||
Equity: the real value of your property.
|
||||
@end enumerate
|
||||
|
||||
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.
|
||||
|
||||
Beneath these top level accounts you can have any level of detail you
|
||||
desire. For example, if you want to keep specific track of how much you spend on
|
||||
burgers and fries, you could have the following:
|
||||
@smallexample
|
||||
Expenses:Food:Hamburgers and Fries
|
||||
@end smallexample
|
||||
|
||||
|
||||
@node Commenting on your journal, Currency and Commodities, Structuring Your Accounts, Keeping a Journal
|
||||
@section Commenting on your Journal
|
||||
@cindex comments, characters
|
||||
Comments are generally started using a ';'. However, in order to
|
||||
increase compatibility with other text manipulation programs and methods
|
||||
four additional comment characters are valid if used at the beginning
|
||||
of a line: @code{#}, @code{|}, and @code{*} and @code{%}.
|
||||
@cindex block comments
|
||||
@cindex comments, block
|
||||
Block comments can be made by use @code{@!comment} ... @code{@!end comment}
|
||||
|
||||
@smallexample
|
||||
|
||||
; This is a single line comment,
|
||||
# and this,
|
||||
% and this,
|
||||
| and this,
|
||||
* and this.
|
||||
|
||||
!comment
|
||||
This is a block comment with
|
||||
multiple lines
|
||||
!end comment
|
||||
@end smallexample
|
||||
|
||||
There are several forms of comments within a transaction, for example:
|
||||
@smallexample
|
||||
|
||||
; this is a global comment that is not applied to a specific transaction
|
||||
; it can start with any of the five characters but is not included in the
|
||||
; output from 'print' or 'output'
|
||||
|
||||
2011/12/11 Something Sweet
|
||||
; German Chocolate Cake
|
||||
; :Broke Diet:
|
||||
Expenses:Food $10.00 ; Friends: The gang
|
||||
Assets:Credit Union:Checking
|
||||
@end smallexample
|
||||
|
||||
@noindent The first comment is global and Ledger will not attach it to any specific
|
||||
transactions. The comments within the transaction must all start with `;'s and are
|
||||
preserved as part of the transaction. The `:'s indicate metadata and tags
|
||||
(@pxref{Transaction Notes and Tags}).
|
||||
|
||||
@node Currency and Commodities, Advanced Transactions, Commenting on your journal, Keeping a Journal
|
||||
@section Currency and Commodities
|
||||
|
||||
@cindex currency
|
||||
|
|
@ -1713,7 +1648,7 @@ both liquid and commodity assets. Now, on the day of the sale:
|
|||
Assets:Broker $2,500.00
|
||||
@end smallexample
|
||||
|
||||
You can, of course, elide the amount of the last posting. It is there
|
||||
@noindent You can, of course, elide the amount of the last posting. It is there
|
||||
for clarity's sake.
|
||||
|
||||
The @{$30.00@} is a lot price. You can also use a lot date,
|
||||
|
|
@ -1774,43 +1709,10 @@ a balance posting in this case to Equity:Capital Losses to reflect the
|
|||
11 cent difference, which is then balanced by Assets:Checking because
|
||||
its amount is null.
|
||||
|
||||
@node Structuring Your Accounts, Advanced Transactions, Currency and Commodities, Keeping a Journal
|
||||
@section Structuring your Accounts
|
||||
|
||||
@cindex accounts, naming
|
||||
@cindex naming 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:
|
||||
@enumerate
|
||||
@item
|
||||
Expenses: where money goes
|
||||
@item
|
||||
Assets: where money sits
|
||||
@item
|
||||
Income: where money comes from
|
||||
@item
|
||||
Liabilities: money you owe
|
||||
@item
|
||||
Equity: the real value of your property.
|
||||
@end enumerate
|
||||
|
||||
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.
|
||||
|
||||
Beneath these top level accounts you can have any level of detail you
|
||||
desire. For example, if you want to keep specific track of how much you spend on
|
||||
burgers and fries, you could have the following:
|
||||
@smallexample
|
||||
Expenses:Food:Hamburgers and Fries
|
||||
@end smallexample
|
||||
|
||||
|
||||
|
||||
|
||||
@node Advanced Transactions, File Format, Structuring Your Accounts, Keeping a Journal
|
||||
@node Advanced Transactions, File Format, Currency and Commodities, Keeping a Journal
|
||||
@section Advanced Transactions
|
||||
@menu
|
||||
* Transaction Notes and Tags::
|
||||
|
|
@ -1879,7 +1781,8 @@ have specific values:
|
|||
ledger reg %name=value
|
||||
ledger reg tag name=value
|
||||
@end smallexample
|
||||
@findex --group-by tag
|
||||
@findex group-by "tag('foo')"
|
||||
@cindex group by tags
|
||||
The group-by and sort functions also support tags:
|
||||
@smallexample
|
||||
ledger --group-by "tag('foo')" bal
|
||||
|
|
@ -2895,6 +2798,7 @@ kill the report buffer
|
|||
@menu
|
||||
* Introduction::
|
||||
* Balance Reports::
|
||||
* Typical queries::
|
||||
* Advanced Reports::
|
||||
@end menu
|
||||
|
||||
|
|
@ -2908,7 +2812,7 @@ show you the basics of combining various options and commands. In the next
|
|||
chapters you will find details about the specific commands and
|
||||
options.
|
||||
|
||||
@node Balance Reports, Advanced Reports, Introduction, Building Reports
|
||||
@node Balance Reports, Typical queries, Introduction, Building Reports
|
||||
@section Balance Reports
|
||||
@menu
|
||||
* Controlling the Accounts and Payees::
|
||||
|
|
@ -2922,7 +2826,7 @@ The balance report is the most commonly used report. The simplest invocation is
|
|||
@smallexample
|
||||
ledger balance -f drewr3.dat
|
||||
@end smallexample
|
||||
@noindent which will print the balances of every account in you journal.
|
||||
@noindent which will print the balances of every account in your journal.
|
||||
|
||||
@smallexample
|
||||
$ -3,804.00 Assets
|
||||
|
|
@ -3001,15 +2905,78 @@ more possibilities.
|
|||
These examples all use the default formatting for the balance
|
||||
report. Customizing the formatting can easily allowing to see only what
|
||||
you want, or interface Ledger with other programs.
|
||||
@node Typical queries, Advanced Reports, Balance Reports, Building Reports
|
||||
@section Typical queries
|
||||
|
||||
@node Advanced Reports, , Balance Reports, Building Reports
|
||||
A query such as the following shows all expenses since last
|
||||
October, sorted by total:
|
||||
|
||||
@example
|
||||
ledger -b "last oct" -s -S T bal ^expenses
|
||||
@end example
|
||||
|
||||
From left to right the options mean: Show transactions since last October;
|
||||
show all sub-accounts; sort by the absolute value of the total; and
|
||||
report the balance for all accounts that begin with ``expenses''.
|
||||
|
||||
@menu
|
||||
* Reporting monthly expenses::
|
||||
@end menu
|
||||
|
||||
@node Reporting monthly expenses, , Typical queries, Typical queries
|
||||
@subsection Reporting monthly expenses
|
||||
|
||||
The following query makes it easy to see monthly expenses, with each
|
||||
month's expenses sorted by the amount:
|
||||
|
||||
@example
|
||||
ledger -M --period-sort t reg ^expenses
|
||||
@end example
|
||||
|
||||
Now, you might wonder where the money came from to pay for these
|
||||
things. To see that report, add @option{-r}, which shows the
|
||||
``related account'' postings:
|
||||
|
||||
@example
|
||||
ledger -M --period-sort t -r reg ^expenses
|
||||
@end example
|
||||
|
||||
But maybe this prints too much information. You might just want to
|
||||
see how much you're spending with your MasterCard. That kind of query
|
||||
requires the use of a display predicate, since the postings
|
||||
calculated must match @samp{^expenses}, while the postings
|
||||
displayed must match @samp{mastercard}. The command would be:
|
||||
|
||||
@example
|
||||
ledger -M -r --display "account =~ /mastercard/" reg ^expenses
|
||||
@end example
|
||||
|
||||
This query says: Report monthly subtotals; report the ``related
|
||||
account'' postings; display only related postings whose
|
||||
account matches @samp{mastercard}, and base the calculation on
|
||||
postings matching @samp{^expenses}.
|
||||
|
||||
This works just as well for report the overall total, too:
|
||||
|
||||
@example
|
||||
ledger -s -r --display "account =~ /mastercard/"/ reg ^expenses
|
||||
@end example
|
||||
|
||||
The @option{-s} option subtotals all postings, just as @option{-M}
|
||||
subtotaled by the month. The running total in both cases is off,
|
||||
however, since a display expression is being used.
|
||||
|
||||
|
||||
|
||||
@node Advanced Reports, , Typical queries, Building Reports
|
||||
@section Advanced Reports
|
||||
|
||||
@menu
|
||||
* Asset Allocation::
|
||||
* Visualizing with Gnuplot::
|
||||
@end menu
|
||||
|
||||
@node Asset Allocation, , Advanced Reports, Advanced Reports
|
||||
@node Asset Allocation, Visualizing with Gnuplot, Advanced Reports, Advanced Reports
|
||||
@subsection Asset Allocation
|
||||
A very popular method of managing portfolios is to control the
|
||||
percent allocation of assets by certain categories. The mix of
|
||||
|
|
@ -3119,6 +3086,64 @@ total for the next level up in the tree. @code{percent} format their
|
|||
ratio as a percentage. The fourth line tells ledger to display the
|
||||
current market value of the the line.
|
||||
|
||||
@cindex plotting
|
||||
@cindex GNUplot
|
||||
@node Visualizing with Gnuplot, , Asset Allocation, Advanced Reports
|
||||
@subsection Visualizing with Gnuplot
|
||||
@cindex GNUplot script
|
||||
If you have @command{Gnuplot} installed, you can graph any of the above
|
||||
register reports. The script to do this is included in the ledger
|
||||
distribution, and is named @file{contrib/report}. Install @file{report}
|
||||
anywhere along your @env{PATH}, and then use @command{report} instead of
|
||||
@command{ledger} when doing a register report. The only thing to keep
|
||||
in mind is that you must specify @option{-j (--amount-data)} or
|
||||
@option{-J (--total-data)} to indicate whether Gnuplot should plot the
|
||||
amount, or the running total. For example, this command plots total
|
||||
monthly expenses made on your MasterCard.
|
||||
|
||||
@example
|
||||
report -j -M -r --display "account =~ /mastercard/" reg ^expenses
|
||||
@end example
|
||||
|
||||
The @command{report} script is a very simple Bourne shell script, that
|
||||
passes a set of scripted commands to Gnuplot. Feel free to modify the
|
||||
script to your liking, since you may prefer histograms to line plots,
|
||||
for example.
|
||||
|
||||
@menu
|
||||
* Typical plots::
|
||||
@end menu
|
||||
|
||||
@node Typical plots, , Visualizing with Gnuplot, Visualizing with Gnuplot
|
||||
@subsubsection Typical plots
|
||||
|
||||
Here are some useful plots:
|
||||
|
||||
@smallexample
|
||||
report -j -M reg ^expenses # monthly expenses
|
||||
report -J reg checking # checking account balance
|
||||
report -J reg ^income ^expenses # cash flow report
|
||||
|
||||
# net worth report, ignoring non-$ postings
|
||||
|
||||
report -J -l "Ua>=@{\$0.01@}" reg ^assets ^liab
|
||||
|
||||
# net worth report starting last February. the use of a display
|
||||
# predicate (-d) is needed, otherwise the balance will start at
|
||||
# zero, and thus the y-axis will not reflect the true balance
|
||||
|
||||
report -J -l "Ua>=@{\$0.01@}" -d "d>=[last feb]" reg ^assets ^liab
|
||||
@end smallexample
|
||||
|
||||
The last report uses both a calculation predicate (@option{-l}) and a
|
||||
display predicate (@option{-d}). The calculation predicates limits
|
||||
the report to postings whose amount is greater than $1 (which can
|
||||
only happen if the posting amount is in dollars). The display
|
||||
predicate limits the transactions @emph{displayed} to just those since last
|
||||
February, even those transactions from before then will be computed as part
|
||||
of the balance.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -3126,44 +3151,38 @@ current market value of the the line.
|
|||
@chapter Reporting Commands
|
||||
@menu
|
||||
* Primary Financial Reports:: Reports in other formats:: Reports about
|
||||
* Reports in other formats::
|
||||
* Reports in other Formats::
|
||||
* Reports about your Journals::
|
||||
* Developer Commands::
|
||||
@end menu
|
||||
|
||||
@node Primary Financial Reports, Reports in other formats, Reporting Commands, Reporting Commands
|
||||
@node Primary Financial Reports, Reports in other Formats, Reporting Commands, Reporting Commands
|
||||
@section Primary Financial Reports
|
||||
|
||||
@menu
|
||||
* balance::
|
||||
* equity::
|
||||
* register::
|
||||
* print::
|
||||
* The balance Command::
|
||||
* The equity Command::
|
||||
* The register Command::
|
||||
* The print Command::
|
||||
@end menu
|
||||
|
||||
@node balance, equity, Primary Financial Reports, Primary Financial Reports
|
||||
@subsection balance
|
||||
@node The balance Command, The equity Command, Primary Financial Reports, Primary Financial Reports
|
||||
@subsection The @code{balance} Command
|
||||
|
||||
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.
|
||||
@node equity, register, balance, Primary Financial Reports
|
||||
@subsection equity
|
||||
@node The equity Command, The register Command, The balance Command, Primary Financial Reports
|
||||
@subsection The @code{equity} Command
|
||||
|
||||
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}.
|
||||
|
||||
|
||||
@menu
|
||||
* register::
|
||||
* print::
|
||||
@end menu
|
||||
|
||||
@node register, print, equity, Primary Financial Reports
|
||||
@subsection register
|
||||
@node The register Command, The print Command, The equity Command, Primary Financial Reports
|
||||
@subsection The @code{register} Command
|
||||
|
||||
The @command{register} command displays all the postings occurring
|
||||
in a single account, line by line. The account regexp must be
|
||||
|
|
@ -3183,8 +3202,8 @@ 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.
|
||||
|
||||
@node print, , register, Primary Financial Reports
|
||||
@subsection print
|
||||
@node The print Command, , The register Command, Primary Financial Reports
|
||||
@subsection The @code{print} Command
|
||||
|
||||
The @command{print} command prints out ledger transactions in a textual
|
||||
format that can be parsed by Ledger. They will be properly formatted,
|
||||
|
|
@ -3196,21 +3215,83 @@ The @command{print} command can be a handy way to clean up a ledger
|
|||
file whose formatting has gotten out of hand.
|
||||
|
||||
|
||||
@node Reports in other formats, Reports about your Journals, Primary Financial Reports, Reporting Commands
|
||||
@section Reports in other formats
|
||||
@node Reports in other Formats, Reports about your Journals, Primary Financial Reports, Reporting Commands
|
||||
@section Reports in other Formats
|
||||
@menu
|
||||
* csv::
|
||||
* Comma Separated Variable files::
|
||||
* Emacs::
|
||||
* org::
|
||||
* pricemap::
|
||||
* xml::
|
||||
* Emacs org mode::
|
||||
* The pricemap Command::
|
||||
* The xml Command::
|
||||
* prices and pricedb::
|
||||
@end menu
|
||||
|
||||
@node csv, Emacs, Reports in other formats, Reports in other formats
|
||||
@subsection csv
|
||||
@node Comma Separated Variable files, Emacs, Reports in other Formats, Reports in other Formats
|
||||
@subsection Comma Separated Variable files
|
||||
@menu
|
||||
* The csv command::
|
||||
* The convert command::
|
||||
@end menu
|
||||
|
||||
@node Emacs, org, csv, Reports in other formats
|
||||
@node The csv command, The convert command, Comma Separated Variable files, Comma Separated Variable files
|
||||
@subsubsection The @code{csv} command
|
||||
The csv command will output print out the desired ledger transactions in
|
||||
a csv format suitable for import into other programs. You can determine
|
||||
the transaction to print using all the normal limiting and searching
|
||||
functions.
|
||||
@cindex csv conversion
|
||||
@cindex reading csv
|
||||
@cindex comma separated variable file reading
|
||||
@node The convert command, , The csv command, Comma Separated Variable files
|
||||
@subsubsection The @code{convert} command
|
||||
Convert reads your Ledger journal then parses a comma separated value
|
||||
(csv) file into Ledger transactions. Many banks offer csv file
|
||||
downloads. Unfortunately the file formats, aside form the commas, are
|
||||
all different. The ledger convert command tried to help as much as it
|
||||
can.
|
||||
|
||||
Your banks csv files will have field in different orders from other
|
||||
banks, so there must be a way to tell Ledger what to expect. Insert a
|
||||
line at the beginning of the csv file that describes the fields to Ledger.
|
||||
|
||||
For example, this is a portion of a csv file downloaded from a credit
|
||||
union in the United States:
|
||||
@smallexample
|
||||
|
||||
Account Name: VALUFIRST CHECKING
|
||||
Account Number: 71
|
||||
Date Range: 11/13/2011 - 12/13/2011
|
||||
|
||||
Transaction Number,Date,Description,Memo,Amount Debit,Amount Credit,Balance,Check Number,Fees
|
||||
767718,12/13/2011,"Withdrawal","ACE HARDWARE 16335 S HOUGHTON RD",-8.80,,00001640.04,,
|
||||
767406,12/13/2011,"Withdrawal","ACE HARDWARE 16335 S HOUGHTON RD",-1.03,,00001648.84,,
|
||||
683342,12/13/2011,"Visa Checking","NetFlix Date 12/12/11 000326585896 5968",-21.85,,00001649.87,,
|
||||
639668,12/13/2011,"Withdrawal","ID: 1741472662 CO: XXAA.COM PAYMNT",-236.65,,00001671.72,,
|
||||
1113648,12/12/2011,"Withdrawal","Tuscan IT #00037657",-29.73,,00001908.37,,
|
||||
@end smallexample
|
||||
|
||||
Unfortunately, as it stands Ledger cannot read it, but you can. Ledger
|
||||
expects the first line to contain a description of the fields on each
|
||||
line of the file. The fields ledger can recognize are called
|
||||
``@code{date}'' ``@code{posted}'', ``@code{code}'', ``@code{payee} or
|
||||
@code{desc}'', ``@code{amount}'', ``@code{cost}'', ``@code{total}'', and
|
||||
``@code{note}''.
|
||||
|
||||
Delete the account description lines at the top, and replace the first line in the data above with:
|
||||
@smallexample
|
||||
date,payee,note,amount,,,code,
|
||||
@end smallexample
|
||||
|
||||
Then execute ledger like this:
|
||||
@smallexample
|
||||
ledger convert download.csv --input-date-format "%m/%d/%Y"
|
||||
@end smallexample
|
||||
|
||||
Where the @code{--input-date-format} option tells ledger how to
|
||||
interpret the dates.
|
||||
|
||||
Importing csv files is a lot of work, and but is very amenable to scripting.
|
||||
@node Emacs, Emacs org mode, Comma Separated Variable files, Reports in other Formats
|
||||
@subsection Emacs
|
||||
|
||||
The @command{emacs} command outputs results in a form that can be read
|
||||
|
|
@ -3222,8 +3303,8 @@ directly by Emacs Lisp. The format of the @code{sexp} is:
|
|||
...) ; list of transactions
|
||||
@end smallexample
|
||||
|
||||
@node org, pricemap, Emacs, Reports in other formats
|
||||
@subsection org
|
||||
@node Emacs org mode, The pricemap Command, Emacs, Reports in other Formats
|
||||
@subsection Emacs @code{org} Mode
|
||||
The @code{org} command produces a journal file suitable for use in the
|
||||
Emacs org mode. More details on using org mode can be found at
|
||||
@url{http://www.orgmode.org}.
|
||||
|
|
@ -3534,11 +3615,11 @@ file and manipulated using Babel. However, only simple Ledger features
|
|||
have been illustrated; please refer to the Ledger documentation for
|
||||
examples of more complex operations with a ledger.
|
||||
|
||||
@node pricemap, xml, org, Reports in other formats
|
||||
@subsection pricemap
|
||||
@node The pricemap Command, The xml Command, Emacs org mode, Reports in other Formats
|
||||
@subsection The @code{pricemap} Command
|
||||
|
||||
@node xml, prices and pricedb, pricemap, Reports in other formats
|
||||
@subsection xml
|
||||
@node The xml Command, prices and pricedb, The pricemap Command, Reports in other Formats
|
||||
@subsection The @code{xml} Command
|
||||
|
||||
By default, Ledger uses a human-readable data format, and displays its
|
||||
reports in a manner meant to be read on screen. For the purpose of
|
||||
|
|
@ -3614,7 +3695,7 @@ Lastly follows the amount of the posting, indicated by
|
|||
there are four different kinds, each with its own format:
|
||||
|
||||
@enumerate
|
||||
@item boolean
|
||||
@item Boolean
|
||||
@item integer
|
||||
@item amount
|
||||
@item balance
|
||||
|
|
@ -3689,7 +3770,7 @@ output such data if the @command{xml} command is used, and can read
|
|||
the same data.
|
||||
|
||||
|
||||
@node prices and pricedb, , xml, Reports in other formats
|
||||
@node prices and pricedb, , The xml Command, Reports in other Formats
|
||||
@subsection prices and pricedb
|
||||
|
||||
The @command{prices} command displays the price history for matching
|
||||
|
|
@ -3703,69 +3784,25 @@ by Ledger. This is useful for generating and tidying up pricedb
|
|||
database files.
|
||||
|
||||
|
||||
@node Reports about your Journals, Developer Commands, Reports in other formats, Reporting Commands
|
||||
@node Reports about your Journals, Developer Commands, Reports in other Formats, Reporting Commands
|
||||
@section Reports about your Journals
|
||||
|
||||
@menu
|
||||
* accounts::
|
||||
* convert::
|
||||
* commodities::
|
||||
* entry and xact::
|
||||
* payees::
|
||||
@end menu
|
||||
|
||||
@node accounts, convert, Reports about your Journals, Reports about your Journals
|
||||
@node accounts, commodities, Reports about your Journals, Reports about your Journals
|
||||
@subsection accounts
|
||||
|
||||
The @command{accounts} reports all of the accounts in the journal.
|
||||
Following the command with a regular expression will limit the output to
|
||||
accounts matching the regex.
|
||||
|
||||
@cindex csv conversion
|
||||
@cindex reading csv
|
||||
@cindex comma separated variable file reading
|
||||
@node convert, commodities, accounts, Reports about your Journals
|
||||
@subsection convert
|
||||
Convert reads your Ledger journal then parses a comma separated value
|
||||
(csv) file into Ledger transactions. Many banks offer csv file
|
||||
downloads. Unfortunately the file formats, aside form the commas, are
|
||||
all different. The ledger convert command tried to help as much as it
|
||||
can.
|
||||
@menu
|
||||
* Preparing CSV files::
|
||||
@end menu
|
||||
|
||||
@node Preparing CSV files, , convert, convert
|
||||
@subsubsection Preparing CSV files for conversion
|
||||
Your banks csv files will have field in different orders from other
|
||||
banks, so there must be a way to tell Ledger what to expect. Insert a
|
||||
line at the beginning of the csv file that describes the fields to Ledger.
|
||||
|
||||
For example, this is a portion of a csv file downloaded from a credit
|
||||
union in the United States:
|
||||
@smallexample
|
||||
|
||||
Account Name: VALUFIRST CHECKING
|
||||
Account Number: 71
|
||||
Date Range: 11/13/2011 - 12/13/2011
|
||||
|
||||
Transaction Number,Date,Description,Memo,Amount Debit,Amount Credit,Balance,Check Number,Fees
|
||||
767718,12/13/2011,"Withdrawal","ACE HARDWARE 16335 S HOUGHTON RD",-8.80,,00001640.04,,
|
||||
767406,12/13/2011,"Withdrawal","ACE HARDWARE 16335 S HOUGHTON RD",-1.03,,00001648.84,,
|
||||
683342,12/13/2011,"Visa Checking","NetFlix Date 12/12/11 000326585896 5968",-21.85,,00001649.87,,
|
||||
639668,12/13/2011,"Withdrawal","ID: 1741472662 CO: XXAA.COM PAYMNT",-236.65,,00001671.72,,
|
||||
1113648,12/12/2011,"Withdrawal","Tuscan IT #00037657",-29.73,,00001908.37,,
|
||||
@end smallexample
|
||||
|
||||
Unfortunately, as it stands Ledger cannot read it, but you can. Ledger
|
||||
expects the first line to contain a description of the fields on each
|
||||
line of the file. The fields ledger can recognize are called
|
||||
``@code{date}'' ``@code{posted}'', ``@code{code}'', ``@code{payee} or
|
||||
@code{desc}'', ``@code{amount}'', ``@code{cost}'', ``@code{total}'', and
|
||||
``@code{note}''.
|
||||
|
||||
|
||||
@node commodities, entry and xact, convert, Reports about your Journals
|
||||
@node commodities, entry and xact, accounts, Reports about your Journals
|
||||
@subsection commodities
|
||||
Report all commodities present in the journals under consideration.
|
||||
|
||||
|
|
@ -3863,7 +3900,7 @@ nothing for a command line user.
|
|||
@subsection source
|
||||
The @code{source} command take a journal file as an argument and parses
|
||||
it checking for errors, no other reports are generated, and no other
|
||||
arguments are necessary. Ledger will reteurn success if no errors are
|
||||
arguments are necessary. Ledger will return success if no errors are
|
||||
found.
|
||||
|
||||
@node Debug Options, Pre-commands, source, Developer Commands
|
||||
|
|
@ -3959,7 +3996,7 @@ Print details of how ledger uses the given formatting description and apply it a
|
|||
@item parse <VALUE EXPR>
|
||||
Print details of how ledger uses the given value expression description and apply it against a model transaction.
|
||||
@item period
|
||||
evaluate the given period and report how leodger interprets it:
|
||||
evaluate the given period and report how Ledger interprets it:
|
||||
@smallexample
|
||||
20:22:21 ~/ledger (next)> ledger period "this year"
|
||||
--- Period expression tokens ---
|
||||
|
|
@ -3979,7 +4016,7 @@ END_REACHED: <EOF>
|
|||
1: 11-Jan-01
|
||||
@end smallexample
|
||||
@item query
|
||||
evaluate the given query and report how leodger interprets it against the model transaction:
|
||||
evaluate the given query and report how Ledger interprets it against the model transaction:
|
||||
|
||||
@smallexample
|
||||
20:25:42 ~/ledger (next)> ledger query "/Book/"
|
||||
|
|
@ -4299,7 +4336,7 @@ FIX THIS ENTRY
|
|||
FIX THIS ENTRY
|
||||
|
||||
@option{count}
|
||||
Direct ledger to report the number of items when appended to the commodites, accounts or payees command.
|
||||
Direct ledger to report the number of items when appended to the commodities, accounts or payees command.
|
||||
|
||||
@option{csv-format}
|
||||
FIX THIS ENTRY
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue