diff options
| -rw-r--r-- | doc/ledger3.texi | 653 |
1 files changed, 345 insertions, 308 deletions
diff --git a/doc/ledger3.texi b/doc/ledger3.texi index f2f7eebb..bf7b14cd 100644 --- a/doc/ledger3.texi +++ b/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 + +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 -@node Advanced Reports, , Balance Reports, Building Reports +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 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 -@node Emacs, org, csv, Reports in other formats +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 |