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

General cleanup, expanded the commenting section, addex index entries

Browse source
This commit is contained in:
Craig Earls 2011-12-14 11:40:08 -07:00 • committed by John Wiegley
parent 20f0e236c0
commit eb84048127
1 changed files with 345 additions and 308 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

653
doc/ledger3.texi
View file

@ -45,7 +45,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@titlepage @titlepage
@title Ledger: Command-Line Accounting @title Ledger: Command-Line Accounting
@subtitle For Version 3.0 of Ledger @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 @author John Wiegley
@end titlepage @end titlepage
@ -253,6 +253,7 @@ enter these commands:
./configure && make install ./configure && make install
@end smallexample @end smallexample
@findex help
@node Getting Help, , Building the Program, Introduction to Ledger @node Getting Help, , Building the Program, Introduction to Ledger
@section Getting help @section Getting help
Ledger has a complete online help system based on GNU Info. This manual 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-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, If you need help on how to use Ledger, or run into problems, you can
you can join the Ledger mailing list at the following Web address: join the Ledger mailing list at the following Web address:
@smallexample @smallexample
http://groups.google.com/group/ledger-cli http://groups.google.com/group/ledger-cli
@end smallexample @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}. @samp{irc.freenode.net}.
@cindex tutorial
@node Ledger Tutorial , Principles of Accounting, Introduction to Ledger, Top @node Ledger Tutorial , Principles of Accounting, Introduction to Ledger, Top
@chapter Ledger Tutorial @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 @node Start a Journal, Run Some Reports, Ledger Tutorial , Ledger Tutorial
@section Start a Journal File @section Start a Journal File
@cindex Journals @cindex journals
A journal is a record of your financial transactions and will be central 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 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, 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 @node Balance Report, Register Report, Run Some Reports, Run Some Reports
@subsection Balance Report @subsection Balance Report
@cindex balance report @cindex balance report
@findex balance @findex balance (bal)
To find the balances of all of your accounts, run this command: To find the balances of all of your accounts, run this command:
@smallexample @smallexample
@ -367,7 +369,7 @@ $ ledger -f drewr3.dat balance Assets Liabilities
@node Register Report, Cleared Report, Balance Report, Run Some Reports @node Register Report, Cleared Report, Balance Report, Run Some Reports
@subsection Register Report @subsection Register Report
@cindex register report @cindex register report
@findex register @findex register (reg)
To show all transactions and a running total: To show all transactions and a running total:
@smallexample @smallexample
ledger -f drewr3.dat register ledger -f drewr3.dat register
@ -410,7 +412,8 @@ Ledger will generate:
@end smallexample @end smallexample
@noindent To limit this to a more useful subset, simply add the accounts you are are interested in seeing transactions for: @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 @smallexample
$ ledger -f drewr3.dat register Groceries $ ledger -f drewr3.dat register Groceries
10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50 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 @node Cleared Report, Using the Windows command line, Register Report, Run Some Reports
@subsection Cleared Report @subsection Cleared Report
@cindex cleared report
@findex cleared
A very useful report is to show what your obligations are versus what A very useful report is to show what your obligations are versus what
expenditures have actually been recorded. It can take several days for expenditures have actually been recorded. It can take several days for
a check to clear, but you should treat it as money spent. The 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 $ -20.00 0 MasterCard
$ 200.00 0 Mortgage:Principal $ 200.00 0 Mortgage:Principal
$ -243.60 0 Tithe $ -243.60 0 Tithe
---------------- ---------------- --------- ---------------- ---------------- ---------
$ -243.60 0 $ -243.60 0
@end smallexample @end smallexample
@noindent The first column shows the outstanding balance, the second column show the ``cleared'' balance. @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 @node Using the Windows command line, , Cleared Report, Run Some Reports
@subsection Using the Windows Command Line @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 Using ledger under the windows command shell has one significant
limitation. CMD.exe is limited to standard ASCII characters and as such limitation. CMD.exe is limited to standard ASCII characters and as such
cannot display any currency symbols other than dollar signs ($). 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 @strong{Report} @tab @strong{Description}
@item @code{balance} @tab Show account balances @item @code{balance} @tab Show account balances
@item @code{register} @tab Show all transactions with running total @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{print} @tab Print transaction in a ledger readable format
@item @code{output} @tab Similar to print without included transactions @item @code{output} @tab Similar to print without included transactions
@item @code{xml} @tab Produce XML output of the register command @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{-M} @tab @code{--Monthly} @tab Group postings by month
@item @code{} @tab @code{--quarterly} @tab Group postings by quarter @item @code{} @tab @code{--quarterly} @tab Group postings by quarter
@item @code{-Y} @tab @code{--yearly} @tab Group postings by year @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 @item @code{-s} @tab @code{--subtotal} @tab Group posting together, similar to balance report
@end multitable @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 @node Principles of Accounting, Keeping a Journal, Ledger Tutorial , Top
@chapter Principles of Accounting with Ledger @chapter Principles of Accounting with Ledger
@menu @menu
* Accounting with Ledger:: * Accounting with Ledger::
* Stating where money goes:: * Stating where money goes::
* Assets and Liabilities:: * Assets and Liabilities::
* Typical queries::
* Commodities and Currencies:: * Commodities and Currencies::
* Accounts and Inventories:: * Accounts and Inventories::
* Understanding Equity:: * 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 positive figure means that that account or person or place has more
money now than when you started your ledger. Make sense? 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 @section Assets and Liabilities
@cindex assets and liabilities
@cindex debts are liabilities
Assets are money that you have, and Liabilities are money that you Assets are money that you have, and Liabilities are money that you
owe. ``Liabilities'' is just a more inclusive name for Debts. 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 @menu
* Tracking reimbursable expenses:: * Tracking reimbursable expenses::
@end menu @end menu
@cindex reimbursable expense tracking
@node Tracking reimbursable expenses, , Assets and Liabilities, Assets and Liabilities @node Tracking reimbursable expenses, , Assets and Liabilities, Assets and Liabilities
@subsection Tracking reimbursable expenses @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 XYZ spent the money on computer software and paid it back about two
weeks later. weeks later.
@node Typical queries, Commodities and Currencies, Assets and Liabilities, Principles of Accounting @node Commodities and Currencies, Accounts and Inventories, 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
@section Commodities and Currencies @section Commodities and Currencies
Ledger makes no assumptions about the commodities you use; it only Ledger makes no assumptions about the commodities you use; it only
@ -1483,17 +1370,17 @@ posting.
@menu @menu
* Most Basic Entry:: * Most Basic Entry::
* Commenting on your journal::
* Starting up:: * Starting up::
* Currency and Commodities::
* Structuring Your Accounts:: * Structuring Your Accounts::
* Commenting on your journal::
* Currency and Commodities::
* Advanced Transactions:: * Advanced Transactions::
* File Format:: * File Format::
* Archiving Previous Years :: * Archiving Previous Years ::
* Using Emacs:: * Using Emacs::
@end menu @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 @section The Most Basic Entry
Here is the Pacific Bell example from above, given as a Ledger 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 that the start of the transaction (the date typically) is at the
beginning of the first line of the transaction, and the accounts are 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 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 account lines Ledger will generate an error. There must be at least two
give an error. There must be at least two spaces, or a tab, between the spaces, or a tab, between the amount and the account. If you do not
amount and the account. If you do not have adequate separation between have adequate separation between the amount and the account Ledger will
the amount and the account Ledger will give an error and stop give an error and stop calculating}
calculating}
@menu @node Starting up, Structuring Your Accounts, Most Basic Entry, Keeping a Journal
* 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
@section Starting up @section Starting up
@cindex initial equity @cindex initial equity
@cindex beginning ledger @cindex beginning ledger
Unless you have recently arrived from another planet, you already have a Unless you have recently arrived from another planet, you already have a
financial state. You need to capture that financial state so that Ledger financial state. You need to capture that financial state so that
has a starting point. Ledger has a starting point.
At some convenient point in time you new the balances and outstanding At some convenient point in time you new the balances and outstanding
obligation of every financial account you have. Those amounts form the 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 payee of the account name, anything convenient that you understand will
work. 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 @section Currency and Commodities
@cindex currency @cindex currency
@ -1713,7 +1648,7 @@ both liquid and commodity assets. Now, on the day of the sale:
Assets:Broker $2,500.00 Assets:Broker $2,500.00
@end smallexample @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. for clarity's sake.
The @{$30.00@} is a lot price. You can also use a lot date, 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 11 cent difference, which is then balanced by Assets:Checking because
its amount is null. 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, Currency and Commodities, Keeping a Journal
@node Advanced Transactions, File Format, Structuring Your Accounts, Keeping a Journal
@section Advanced Transactions @section Advanced Transactions
@menu @menu
* Transaction Notes and Tags:: * Transaction Notes and Tags::
@ -1879,7 +1781,8 @@ have specific values:
ledger reg %name=value ledger reg %name=value
ledger reg tag name=value ledger reg tag name=value
@end smallexample @end smallexample
@findex --group-by tag @findex group-by "tag('foo')"
@cindex group by tags
The group-by and sort functions also support tags: The group-by and sort functions also support tags:
@smallexample @smallexample
ledger --group-by "tag('foo')" bal ledger --group-by "tag('foo')" bal
@ -2895,6 +2798,7 @@ kill the report buffer
@menu @menu
* Introduction:: * Introduction::
* Balance Reports:: * Balance Reports::
* Typical queries::
* Advanced Reports:: * Advanced Reports::
@end menu @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 chapters you will find details about the specific commands and
options. options.
@node Balance Reports, Advanced Reports, Introduction, Building Reports @node Balance Reports, Typical queries, Introduction, Building Reports
@section Balance Reports @section Balance Reports
@menu @menu
* Controlling the Accounts and Payees:: * Controlling the Accounts and Payees::
@ -2922,7 +2826,7 @@ The balance report is the most commonly used report. The simplest invocation is
@smallexample @smallexample
ledger balance -f drewr3.dat ledger balance -f drewr3.dat
@end smallexample @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 @smallexample
$ -3,804.00 Assets $ -3,804.00 Assets
@ -3001,15 +2905,78 @@ more possibilities.
These examples all use the default formatting for the balance These examples all use the default formatting for the balance
report. Customizing the formatting can easily allowing to see only what report. Customizing the formatting can easily allowing to see only what
you want, or interface Ledger with other programs. 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 @section Advanced Reports
@menu @menu
* Asset Allocation:: * Asset Allocation::
* Visualizing with Gnuplot::
@end menu @end menu
@node Asset Allocation, , Advanced Reports, Advanced Reports @node Asset Allocation, Visualizing with Gnuplot, Advanced Reports, Advanced Reports
@subsection Asset Allocation @subsection Asset Allocation
A very popular method of managing portfolios is to control the A very popular method of managing portfolios is to control the
percent allocation of assets by certain categories. The mix of 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 ratio as a percentage. The fourth line tells ledger to display the
current market value of the the line. 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 @chapter Reporting Commands
@menu @menu
* Primary Financial Reports:: Reports in other formats:: Reports about * Primary Financial Reports:: Reports in other formats:: Reports about
* Reports in other formats:: * Reports in other Formats::
* Reports about your Journals:: * Reports about your Journals::
* Developer Commands:: * Developer Commands::
@end menu @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 @section Primary Financial Reports
@menu @menu
* balance:: * The balance Command::
* equity:: * The equity Command::
* register:: * The register Command::
* print:: * The print Command::
@end menu @end menu
@node balance, equity, Primary Financial Reports, Primary Financial Reports @node The balance Command, The equity Command, Primary Financial Reports, Primary Financial Reports
@subsection balance @subsection The @code{balance} Command
The @command{balance} command reports the current balance of all The @command{balance} command reports the current balance of all
accounts. It accepts a list of optional regexps, which confine the accounts. It accepts a list of optional regexps, which confine the
balance report to the matching accounts. If an account contains balance report to the matching accounts. If an account contains
multiple types of commodities, each commodity's total is reported multiple types of commodities, each commodity's total is reported
separately. separately.
@node equity, register, balance, Primary Financial Reports @node The equity Command, The register Command, The balance Command, Primary Financial Reports
@subsection equity @subsection The @code{equity} Command
The @command{equity} command prints out accounts balances as if they The @command{equity} command prints out accounts balances as if they
were transactions. This makes it easy to establish the starting balances were transactions. This makes it easy to establish the starting balances
for an account, such as when @ref{Archiving Previous Years}. for an account, such as when @ref{Archiving Previous Years}.
@node The register Command, The print Command, The equity Command, Primary Financial Reports
@menu @subsection The @code{register} Command
* register::
* print::
@end menu
@node register, print, equity, Primary Financial Reports
@subsection register
The @command{register} command displays all the postings occurring The @command{register} command displays all the postings occurring
in a single account, line by line. The account regexp must be 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 add either @option{-j} or @option{-J} to your register command, in
order to plot either the amount or total column, respectively. order to plot either the amount or total column, respectively.
@node print, , register, Primary Financial Reports @node The print Command, , The register Command, Primary Financial Reports
@subsection print @subsection The @code{print} Command
The @command{print} command prints out ledger transactions in a textual The @command{print} command prints out ledger transactions in a textual
format that can be parsed by Ledger. They will be properly formatted, 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. file whose formatting has gotten out of hand.
@node Reports in other formats, Reports about your Journals, Primary Financial Reports, Reporting Commands @node Reports in other Formats, Reports about your Journals, Primary Financial Reports, Reporting Commands
@section Reports in other formats @section Reports in other Formats
@menu @menu
* csv:: * Comma Separated Variable files::
* Emacs:: * Emacs::
* org:: * Emacs org mode::
* pricemap:: * The pricemap Command::
* xml:: * The xml Command::
* prices and pricedb:: * prices and pricedb::
@end menu @end menu
@node csv, Emacs, Reports in other formats, Reports in other formats @node Comma Separated Variable files, Emacs, Reports in other Formats, Reports in other Formats
@subsection csv @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 @subsection Emacs
The @command{emacs} command outputs results in a form that can be read 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 ...) ; list of transactions
@end smallexample @end smallexample
@node org, pricemap, Emacs, Reports in other formats @node Emacs org mode, The pricemap Command, Emacs, Reports in other Formats
@subsection org @subsection Emacs @code{org} Mode
The @code{org} command produces a journal file suitable for use in the 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 Emacs org mode. More details on using org mode can be found at
@url{http://www.orgmode.org}. @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 have been illustrated; please refer to the Ledger documentation for
examples of more complex operations with a ledger. examples of more complex operations with a ledger.
@node pricemap, xml, org, Reports in other formats @node The pricemap Command, The xml Command, Emacs org mode, Reports in other Formats
@subsection pricemap @subsection The @code{pricemap} Command
@node xml, prices and pricedb, pricemap, Reports in other formats @node The xml Command, prices and pricedb, The pricemap Command, Reports in other Formats
@subsection xml @subsection The @code{xml} Command
By default, Ledger uses a human-readable data format, and displays its 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 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: there are four different kinds, each with its own format:
@enumerate @enumerate
@item boolean @item Boolean
@item integer @item integer
@item amount @item amount
@item balance @item balance
@ -3689,7 +3770,7 @@ output such data if the @command{xml} command is used, and can read
the same data. 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 @subsection prices and pricedb
The @command{prices} command displays the price history for matching 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. 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 @section Reports about your Journals
@menu @menu
* accounts:: * accounts::
* convert::
* commodities:: * commodities::
* entry and xact:: * entry and xact::
* payees:: * payees::
@end menu @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 @subsection accounts
The @command{accounts} reports all of the accounts in the journal. The @command{accounts} reports all of the accounts in the journal.
Following the command with a regular expression will limit the output to Following the command with a regular expression will limit the output to
accounts matching the regex. 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 @node commodities, entry and xact, accounts, Reports about your Journals
@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
@subsection commodities @subsection commodities
Report all commodities present in the journals under consideration. Report all commodities present in the journals under consideration.
@ -3863,7 +3900,7 @@ nothing for a command line user.
@subsection source @subsection source
The @code{source} command take a journal file as an argument and parses 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 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. found.
@node Debug Options, Pre-commands, source, Developer Commands @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> @item parse <VALUE EXPR>
Print details of how ledger uses the given value expression description and apply it against a model transaction. Print details of how ledger uses the given value expression description and apply it against a model transaction.
@item period @item period
evaluate the given period and report how leodger interprets it: evaluate the given period and report how Ledger interprets it:
@smallexample @smallexample
20:22:21 ~/ledger (next)> ledger period "this year" 20:22:21 ~/ledger (next)> ledger period "this year"
--- Period expression tokens --- --- Period expression tokens ---
@ -3979,7 +4016,7 @@ END_REACHED: <EOF>
1: 11-Jan-01 1: 11-Jan-01
@end smallexample @end smallexample
@item query @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 @smallexample
20:25:42 ~/ledger (next)> ledger query "/Book/" 20:25:42 ~/ledger (next)> ledger query "/Book/"
@ -4299,7 +4336,7 @@ FIX THIS ENTRY
FIX THIS ENTRY FIX THIS ENTRY
@option{count} @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} @option{csv-format}
FIX THIS ENTRY FIX THIS ENTRY