From cbf4cba18bd207917a24a8beb797ea773b3ad1ce Mon Sep 17 00:00:00 2001 From: John Wiegley Date: Mon, 25 Jun 2012 19:10:45 -0500 Subject: Fixed a minor documentation bug --- doc/ledger3.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 30d7d5a4..bfe12a75 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -1335,7 +1335,7 @@ Or to see a particular funds expenses, the @samp{School} fund in this case: @smallexample -ledger --code-as-payee -P reg ^Expenses -- School +ledger --code-as-payee -P reg ^Expenses @School @end smallexample Both approaches yield different kinds of flexibility, depending on how -- cgit v1.2.3 From f34a4e315eee54f31993432a349804ed51ea9138 Mon Sep 17 00:00:00 2001 From: John Wiegley Date: Wed, 1 Aug 2012 16:08:43 -0500 Subject: Change occurences of #+srcname to #+name --- doc/ledger3.texi | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index bfe12a75..cdae6bcc 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -4183,7 +4183,7 @@ The easiest, albeit possibly less useful, way in which to use Ledger within an org file is to use a single source block to record all Ledger entries. The following is an example source block: @smallexample -#+srcname: allinone +#+name: allinone #+begin_src ledger 2010/01/01 * Starting balance assets:bank:savings £1300.00 @@ -4254,7 +4254,7 @@ placed several entries, but we could have had each entry in a separate src block. Note that all code blocks you wish to refer to later must have the :noweb yes babel header argument specified. @smallexample -#+srcname: income +#+name: income #+begin_src ledger :noweb yes 2010/01/01 * Starting balance assets:bank:savings £1300.00 @@ -4279,7 +4279,7 @@ The following entries relate to personal expenses, such as rent and food. Again, these have all been placed in a single src block but could have been done individually. @smallexample -#+srcname: expenses +#+name: expenses #+begin_src ledger :noweb yes 2010/07/23 Rent expenses:rent £500.00 @@ -4306,7 +4306,7 @@ to Ledger. This code block can now be evaluated (C-c C-c) and the results generated by incorporating the transactions referred to by the <> and <>= lines. @smallexample -#+srcname: balance +#+name: balance #+begin_src ledger :cmdline bal :noweb yes <> <> @@ -4348,7 +4348,7 @@ each monthly period (the -M argument) with a running total in the final column (which should be 0 at the end if all the entries are correct). @smallexample -#+srcname: monthlyregister +#+name: monthlyregister #+begin_src ledger :cmdline -M reg :noweb yes <> <> @@ -4372,7 +4372,7 @@ are increasing (or decreasing!). In this case, the final column will be the running total of the assets in our ledger. @smallexample -#+srcname: monthlyassetsregister +#+name: monthlyassetsregister #+begin_src ledger :cmdline -M reg assets :noweb yes <> <> -- cgit v1.2.3 From a54ee9047b11b52e6bc1edf1431d65977ea9f714 Mon Sep 17 00:00:00 2001 From: John Wiegley Date: Tue, 7 Aug 2012 15:19:59 -0500 Subject: Doc fix --- doc/ledger3.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index cdae6bcc..1ea4fd02 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -1335,7 +1335,7 @@ Or to see a particular funds expenses, the @samp{School} fund in this case: @smallexample -ledger --code-as-payee -P reg ^Expenses @School +ledger --code-as-payee -P reg ^Expenses @@School @end smallexample Both approaches yield different kinds of flexibility, depending on how -- cgit v1.2.3 From fa89dc16a63ab30a030311115127e6138a78f0e7 Mon Sep 17 00:00:00 2001 From: "Bradley M. Kuhn" Date: Mon, 10 Sep 2012 00:08:59 -0400 Subject: Document "Data File Parsing Information" format strings. Based on my reading of src/format.cc and inspection of output on some test data, I believe this is adequate documentation for these format strings. --- doc/ledger3.texi | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 1ea4fd02..bff96adf 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -6691,6 +6691,7 @@ As an example of how flexible the --format strings can be, the default balance f * Quantities and Calculations:: * Dates:: * Text Formatting:: +* Data File Parsing Information:: * Misc:: @end menu @@ -6762,7 +6763,7 @@ The character based formatting ledger can do is limited to the ANSI terminal cha @item @code{value_date } @tab @code{} @tab @end multitable -@node Text Formatting, Misc, Dates, New formatting codes +@node Text Formatting, Data File Parsing Information, Dates, New formatting codes @subsection Text Formatting @subsubsection Summary @multitable @columnfractions .6 .4 @@ -6797,7 +6798,26 @@ Return str surrounded by double quotes, @code{""}. Values can have numerous annotations, such as effective dates and lot prices. @code{strip} removes these annotations. @end table -@node Misc, , Text Formatting, New formatting codes + +@node Data File Parsing Information, Misc, Text Formatting, New formatting codes +@subsection Data File Parsing Information + +The format strings in the table below provide locational metadata +regarding the coordinates of entries in the source data file(s) that +generated the posting. + +@subsubsection Summary +@multitable @columnfractions .3 .2 .5 +@item @strong{Function} @tab @strong{Abbrev.} @tab @strong{Description} +@item @code{filename} @tab S @tab @tab name of ledger data file from whence posting came +@item @code{beg_pos} @tab B @tab character position in @code{filename} where entry for posting begins +@item @code{end_pos} @tab E @tab character position in @code{filename} where entry for posting ends +@item @code{beg_line} @tab b @tab line number in @code{filename} where entry for posting begins +@item @code{end_line} @tab e @tab line number in @code{filename} where posting's entry for posting ends +@end multitable + + +@node Misc, , Data File Parsing Information, New formatting codes @subsection Miscellaneous @multitable @columnfractions .3 .2 .5 @item @strong{Function} @tab @strong{Abbrev.} @tab @strong{Description} -- cgit v1.2.3 From 137183d19f2ae54c030a1f7dcd59e02341f088c6 Mon Sep 17 00:00:00 2001 From: "Bradley M. Kuhn" Date: Mon, 10 Sep 2012 00:12:51 -0400 Subject: Fixed typo: removed extra @tab. --- doc/ledger3.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index bff96adf..16bf0564 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -6809,7 +6809,7 @@ generated the posting. @subsubsection Summary @multitable @columnfractions .3 .2 .5 @item @strong{Function} @tab @strong{Abbrev.} @tab @strong{Description} -@item @code{filename} @tab S @tab @tab name of ledger data file from whence posting came +@item @code{filename} @tab S @tab name of ledger data file from whence posting came @item @code{beg_pos} @tab B @tab character position in @code{filename} where entry for posting begins @item @code{end_pos} @tab E @tab character position in @code{filename} where entry for posting ends @item @code{beg_line} @tab b @tab line number in @code{filename} where entry for posting begins -- cgit v1.2.3 From ccf10e20604a9fc074c1f7f1f98905be59a0e0b4 Mon Sep 17 00:00:00 2001 From: "Bradley M. Kuhn" Date: Fri, 14 Sep 2012 16:35:46 -0400 Subject: Created Fixated prices node. There was a Fixated prices section, but no Fixated prices node. This of course required an update of nodes and menus throughout chapter. --- doc/ledger3.texi | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 16bf0564..6dc1787d 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -2486,6 +2486,7 @@ kill the report buffer * Virtual posting costs:: * Commodity prices:: * Prices vs. costs:: +* Fixated prices:: * Lot dates:: * Lot notes:: * Lot value expressions:: @@ -3131,7 +3132,7 @@ Plus, it comes with dangers. This works fine: And in cases where the amounts do not divide into whole figure and must be rounded, the capital gains figure could be off by a cent. Use with caution. -@node Prices vs. costs, Lot dates, Commodity prices, Transactions +@node Prices vs. costs, Fixated prices, Commodity prices, Transactions @section Prices vs. costs Because lot pricing provides enough information to infer the cost, the @@ -3151,6 +3152,7 @@ However, note that what you see in some reports may differ, for example in the print report. Functionally, however, there is no difference, and neither the register nor the balance report are sensitive to this difference. +@node Fixated prices, Lot dates, Prices vs. costs, Transactions @section Fixated prices If you buy a stock last year, and ask for its value today, Ledger will consult @@ -3174,7 +3176,7 @@ below) to fix the value of a commodity lot. * Fixated costs:: @end menu -@node Fixated costs, , Prices vs. costs, Prices vs. costs +@node Fixated costs, , Fixated prices, Fixated prices @subsection Fixated costs Since price annotations are costs are largely interchangeable and a matter of @@ -3190,7 +3192,7 @@ of the cost: This is the same as the previous transaction, with the same caveats found in the section ``Prices vs. costs''. -@node Lot dates, Lot notes, Prices vs. costs, Transactions +@node Lot dates, Lot notes, Fixated prices, Transactions @section Lot dates In addition to lot prices, you can specify lot dates and reveal them with -- cgit v1.2.3 From 438806ac71a9a56645d824d2dbebb2bd565155ce Mon Sep 17 00:00:00 2001 From: "Bradley M. Kuhn" Date: Fri, 14 Sep 2012 16:39:41 -0400 Subject: Documentation for the fixed directive. Based on conversation with johnw on IRC, I believe this text properly documents the intended feature of the fixed directive. --- doc/ledger3.texi | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 6dc1787d..d4c89951 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -2047,6 +2047,37 @@ Closes block commands like @code{tag} or @code{comment}. @item fixed @c instance_t::fixed_directive in textual.cc +A fixed block is used to set fixated prices (@pxref{Fixated prices}) for a series of +transactions. It's purely a typing saver, for use when entering many +transactions with fixated prices. + +Thus, the following: +@smallexample +fixed CAD $0.90 + 2012-04-10 Lunch in Canada + Assets:Wallet -15.50 CAD + Expenses:Food 15.50 CAD + + 2012-04-11 Second day Dinner in Canada + Assets:Wallet -25.75 CAD + Expenses:Food 25.75 CAD +endfixed +@end smallexample +is equivalent to this: +@smallexample + 2012-04-10 Lunch in Canada + Assets:Wallet -15.50 CAD @{=$0.90@} + Expenses:Food 15.50 CAD @{=$0.90@} + + 2012-04-11 Second day Dinner in Canada + Assets:Wallet -25.75 CAD @{=$0.90@} + Expenses:Food 25.75 CAD @{=$0.90@} +@end smallexample + +Note that ending a @samp{fixed} is done differently than other +directives, as @samp{fixed} is closed with an @samp{endfixed} (i.e., +there is @strong{no space} between @samp{end} and @samp{fixed}). + @item include @c instance_t::include_directive in textual.cc Include the stated file as if it were part of the current file. -- cgit v1.2.3 From 06356ebf90bb051b2cfef09dbed646fd4c31a759 Mon Sep 17 00:00:00 2001 From: "Bradley M. Kuhn" Date: Fri, 14 Sep 2012 16:54:12 -0400 Subject: Make reference and link to Bug Report #789 in fixed directive documentation. Due to weirdness that's currently true with the existing next branch of ledger, I believe it's important to tell users in the documentation that there are some discrepancies in the 'fixed' directive behavior. The documentation from my previous commit is written to explain what 'fixed' *should* do; adding the bug report link here is a placeholder to tell users that it may not do what they think it does. Obviously, if someone closes #789, they should remove this paragraph added herein. But, if the bug report is closed, but the documentation lags behind, the worst that happens is some users have to click through to see the bug is closed. --- doc/ledger3.texi | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index d4c89951..9a91d79e 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -2078,6 +2078,10 @@ Note that ending a @samp{fixed} is done differently than other directives, as @samp{fixed} is closed with an @samp{endfixed} (i.e., there is @strong{no space} between @samp{end} and @samp{fixed}). +For the moment, users may wish to study +@uref{http://bugs.ledger-cli.org/show_bug.cgi?id=789, Bug Report 789} +before using the @samp{fixed} directive in production. + @item include @c instance_t::include_directive in textual.cc Include the stated file as if it were part of the current file. -- cgit v1.2.3 From 1ebc014f55715418ef8f379c1cc7567937dcf8e3 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 3 Oct 2012 12:23:21 -0700 Subject: correcte --period-sort arguments in section 7.3.1 --- doc/ledger3.texi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 9a91d79e..4ab27f5f 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -3751,7 +3751,7 @@ 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 +ledger -M --period-sort "(amount)" reg ^expenses @end example Now, you might wonder where the money came from to pay for these @@ -3759,7 +3759,7 @@ things. To see that report, add @option{-r}, which shows the ``related account'' postings: @example -ledger -M --period-sort t -r reg ^expenses +ledger -M --period-sort "(amount)" -r reg ^expenses @end example But maybe this prints too much information. You might just want to -- cgit v1.2.3 From ecc91c6b95c7ead18cf4e51e5a5aa72db966aaa6 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Thu, 4 Oct 2012 06:25:18 -0700 Subject: Corrected a few missing @ symbols per Jeroen --- doc/ledger3.texi | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 4ab27f5f..2d10cb35 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -2984,7 +2984,7 @@ source account. Whenever a commodity is exchanged like this, the commodity moved to the target account is considered "secondary", while the commodity used for purchasing and tracked in the cost is "primary". -Said another way, whenever Ledger sees a posting cost of the form "AMOUNT @ +Said another way, whenever Ledger sees a posting cost of the form "AMOUNT @@ AMOUNT", the commodity used in the second amount is marked "primary". The only meaning a primary commodity has is that -V flag will never convert a @@ -2997,7 +2997,7 @@ Just as you can have amount expressions, you can have posting expressions: @smallexample 2012-03-10 My Broker - Assets:Brokerage 10 AAPL @ ($500.00 / 10) + Assets:Brokerage 10 AAPL @@ ($500.00 / 10) Assets:Brokerage:Cash @end smallexample @@ -3005,7 +3005,7 @@ You can even have both: @smallexample 2012-03-10 My Broker - Assets:Brokerage (5 AAPL * 2) @ ($500.00 / 10) + Assets:Brokerage (5 AAPL * 2) @@ ($500.00 / 10) Assets:Brokerage:Cash @end smallexample @@ -3018,7 +3018,7 @@ instead, use @@@@: @smallexample 2012-03-10 My Broker - Assets:Brokerage 10 AAPL @@@@ $500.00 + Assets:Brokerage 10 AAPL @@ $500.00 Assets:Brokerage:Cash @end smallexample -- cgit v1.2.3 From 8bb5bae7a97dbc2052eb4aa44c1e805b7c07bd5f Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Tue, 9 Oct 2012 16:09:09 -0700 Subject: Filled in many blank entries Also reformatted the option lists to be more like the GCC manual --- doc/ledger3.texi | 1241 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 770 insertions(+), 471 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 2d10cb35..ab59f2ae 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -293,8 +293,7 @@ called @file{drewr3.dat} (@pxref{Example Data File}). Copy it someplace convenient and open up a terminal window in that directory. -If you would rather start with your own journal right away please skip -to @xref{Keeping a Journal}. +If you would rather start with your own journal right away please see @ref{Keeping a Journal}. @node Run Some Reports, Command Line Quick Reference, Start a Journal, Ledger Tutorial @section Run a Few Reports @@ -370,11 +369,11 @@ To show all transactions and a running total: ledger -f drewr3.dat register @end smallexample -Ledger will generate: +@noindent Ledger will generate: @smallexample 10-Dec-01 Checking balance Assets:Checking $ 1,000.00 $ 1,000.00 - Equity:Opening Balances $ -1,000.00 0 + Equity:Opening Balances $ -1,000.00 0 10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50 Expense:Food:Groceries $ 37.50 $ 75.00 Expense:Food:Groceries $ 37.50 $ 112.50 @@ -447,7 +446,8 @@ $ ledger -f drewr3.dat register payee "Organic" 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 -@samp{cleared} report shows just that: +@samp{cleared} report shows just that (note that the cleared report will +not format correctly for accounts that contain multiple commodities): @smallexample $ ledger -f drewr3.dat cleared @@ -473,7 +473,7 @@ $ ledger -f drewr3.dat cleared $ -243.60 0 @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 shows the ``cleared'' balance. @node Using the Windows command line, , Cleared Report, Run Some Reports @subsection Using the Windows Command Line @cindex windows cmd.exe @@ -482,6 +482,7 @@ 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 ($). +@page @node Command Line Quick Reference, , Run Some Reports, Ledger Tutorial @section Command Line Quick Reference @@ -588,10 +589,8 @@ cannot display any currency symbols other than dollar signs ($). @item @code{-F STR} @tab @code{--format STR} @tab Set reporting format @item @code{} @tab @code{--balance-format STR} @tab @item @code{} @tab @code{--register-format STR} @tab -@item @code{} @tab @code{--print-format STR} @tab -@item @code{-j register} @tab @code{--plot-amount-format STR} @tab -@item @code{-J register} @tab @code{--plot-total-format STR} @tab -@item @code{} @tab @code{--equity-format STR} @tab +@item @code{-j register} @tab @code{--plot-amount-format STR} @tab format the output of a amount plots +@item @code{-J register} @tab @code{--plot-total-format STR} @tab format the output of a total plot @item @code{} @tab @code{--prices-format STR} @tab @item @code{-w register} @tab @code{--wide-register-format STR} @tab @item @code{} @tab @code{--anon} @tab Print the ledger register with anonymized accounts and payees, useful for filing bug reports @@ -604,7 +603,7 @@ cannot display any currency symbols other than dollar signs ($). @item @code{-P} @tab @code{--by-payee} @tab Group postings by common payee names @item @code{-D} @tab @code{--daily} @tab Group postings by day @item @code{-W} @tab @code{--weekly} @tab Group postings by week -@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{-Y} @tab @code{--yearly} @tab Group postings by year @item @code{} @tab @code{--dow} @tab Group by day of weeks @@ -3188,7 +3187,7 @@ print report. Functionally, however, there is no difference, and neither the register nor the balance report are sensitive to this difference. @node Fixated prices, Lot dates, Prices vs. costs, Transactions -@section Fixated prices +@section Fixated prices and costs If you buy a stock last year, and ask for its value today, Ledger will consult its price database to see what the most recent price for that stock is. You @@ -3207,14 +3206,7 @@ else happens to the stock in the meantime. Fixated prices are a special case of using lot valuation expressions (see below) to fix the value of a commodity lot. -@menu -* Fixated costs:: -@end menu - -@node Fixated costs, , Fixated prices, Fixated prices -@subsection Fixated costs - -Since price annotations are costs are largely interchangeable and a matter of +Since price annotations and costs are largely interchangeable and a matter of preference, there is an equivalent syntax for specified fixated prices by way of the cost: @@ -3225,7 +3217,7 @@ of the cost: @end smallexample This is the same as the previous transaction, with the same caveats found in -the section ``Prices vs. costs''. +@ref{Prices vs. costs}. @node Lot dates, Lot notes, Fixated prices, Transactions @section Lot dates @@ -4432,6 +4424,14 @@ examples of more complex operations with a ledger. @node The pricemap Command, The xml Command, Emacs org mode, Reports in other Formats @subsection The @code{pricemap} Command +If you have the graphviz graph visualization package installed, ledger +can generate a graph of the relationship between your various +commodities. The output file is in the ``dot'' format. + +This is probably not very interesting, unless you have many different +commdities valued in terms of each other. For example, multiple +currencies and multiples investments valued in those currencies. + @node The xml Command, prices and pricedb, The pricemap Command, Reports in other Formats @subsection The @code{xml} Command @@ -4810,6 +4810,7 @@ it against a model transaction. Print details of how ledger uses the given formatting description and apply it against a model transaction. @item generate +FIX THIS ENTRY @item parse Print details of how ledger uses the given value expression description and apply it against a model transaction. @@ -4873,6 +4874,7 @@ model transaction: true @end smallexample @item template +FIX THIS ENTRY @end table @node Command-line Syntax, Budgeting and Forecasting, Reporting Commands, Top @@ -4935,7 +4937,6 @@ commands. * Session Options:: * Report Options:: * Report Filtering:: -* Search Terms:: * Output Customization:: * Commodity Reporting:: * Environment Variables:: @@ -4951,50 +4952,49 @@ GUIs, which would make use of the different scopes by keeping an instance of Ledger running in the background and running multiple sessions with multiple reports per session. - -@option{--args-only} Ignore all environment and init-file settings and +@table @code +@item --args-only +Ignore all environment and init-file settings and use only command-line arguments to control Ledger. Useful for debugs or testing small Journal files not associated with you main financial database. - -@option{--help} +@item --help Displays the info page for ledger. -@option{--init-file } +@item --init-file Specifies the location of the init file @file{.ledgerrc} -@option{--options} Display the options in effect for this Ledger -invocation, along with their values and the source of those values, for -example: +@item --options + Display the options in effect for this Ledger invocation, along with +their values and the source of those values, for example: @smallexample 14:15:02 > ledger --options bal --cleared -f ~/ledger/test/input/drewr3.dat =============================================================================== [Global scope options] [Session scope options] - --file = ~/ledger/test/input/drewr3.dat -f - --price-db = ~/FinanceData/PriceDB $price-db + --file = ~/ledger/test/input/drewr3.dat -f + --price-db = ~/FinanceData/PriceDB $price-db [Report scope options] - --cleared --cleared - --color ?normalize - --date-format = %Y/%m/%d $date-format - --limit = cleared --cleared - --prepend-width = 0 ?normalize - --meta-width = 0 ?normalize - --date-width = 10 ?normalize - --payee-width = 21 ?normalize - --account-width = 21 ?normalize - --amount-width = 12 ?normalize - --total-width = 12 ?normalize + --cleared --cleared + --color ?normalize + --date-format = %Y/%m/%d $date-format + --limit = cleared --cleared + --prepend-width = 0 ?normalize + --meta-width = 0 ?normalize + --date-width = 10 ?normalize + --payee-width = 21 ?normalize + --account-width = 21 ?normalize + --amount-width = 12 ?normalize + --total-width = 12 ?normalize =============================================================================== $ 775.00 Assets:Checking $ -1,000.00 Equity:Opening Balances $ 225.00 Expenses:Food:Groceries -------------------- 0 - @end smallexample @noindent For the `source' column, a value starting with a `@code{-}' or `@code{--}' indicated the source was a command line argument. It the @@ -5002,7 +5002,10 @@ entry starts with a `@code{$}', the source was an environment variable. If the source is `@code{?normalize}' the value was set internally by ledger, in a function called @code{normalize_options}. -@option{--script } Execute a ledger script. +@item --script +Execute a ledger script. +@end table + @node Session Options, Report Options, Global Options, Detailed Options Description @subsection Session Options @@ -5013,22 +5016,26 @@ GUIs, which would make use of the different scopes by keeping an instance of Ledger running in the background and running multiple sessions with multiple reports per session. -@option{--decimal-comma} Direct Ledger to parse journals using the -European standard comma as decimal separator, vice a period. +@table @code +@item --decimal-comma +Direct Ledger to parse journals using the European standard comma as +decimal separator, vice a period. -@option{--download} Direct Ledger to download prices using the script -defined in @code{--getquote}. +@item --download +Direct Ledger to download prices using the script defined in +@code{--getquote}. -@option{--file } +@item --file Specify the input file path for this invocation. @cindex getquote @cindex download prices -@option{--getquote } Tells ledger where to find the user defined -script to download prices information. +@item --getquote +Tells ledger where to find the user defined script to download prices +information. -@option{--input-date-format } Specify the input date format -for journal entries. For example, +@item --input-date-format +Specify the input date format for journal entries. For example, @smallexample ledger convert Export.csv --input-date-format "%m/%d/%Y" @end smallexample @@ -5037,8 +5044,8 @@ Would convert the @file{Export.csv} file to ledger format, assuming the the dates in the CSV file are like 12/23/2009 (@pxref{Date and Time Format Codes}). -@option{--master-account } Prepends all account names with the -argument. +@item --master-account +Prepends all account names with the argument. @smallexample 21:51:39 ~/ledger (next)> ledger -f test/input/drewr3.dat bal --master-account HUMBUG 0 HUMBUG @@ -5063,23 +5070,24 @@ argument. $ 200.00 Mortgage:Principal @end smallexample -@option{--price-db } Specify the location of the price entry data -file. +@item --price-db +Specify the location of the price entry data file. -@option{--price-exp INTEGER_MINUTES} Set the expected freshness of price -quotes, in minutes. That is, if the last known quote for any commodity -is older than this value, and if ‘--download’ is being used, then the -Internet will be consulted again for a newer price. Otherwise, the old -price is still considered to be fresh enough. - -@option{--strict} Ledger normally silently accepts any account or -commodity in a posting, even if you have misspelled a common used one. -The option @code{--strict} changes that behavior. While running -@code{--strict}, Ledger interprets all cleared transactions as correct, -and if it finds a new account or commodity (same as a misspelled -commodity or account) it will issue a warning giving you the file and -line number of the problem. +@item --price-exp INTEGER_MINUTES +Set the expected freshness of price quotes, in minutes. That is, if the +last known quote for any commodity is older than this value, and if +@samp{--download} is being used, then the Internet will be consulted again +for a newer price. Otherwise, the old price is still considered to be +fresh enough. +@item --strict +Ledger normally silently accepts any account or commodity in a posting, +even if you have misspelled a common used one. The option +@code{--strict} changes that behavior. While running @code{--strict}, +Ledger interprets all cleared transactions as correct, and if it finds a +new account or commodity (same as a misspelled commodity or account) it +will issue a warning giving you the file and line number of the problem. +@end table @node Report Options, Report Filtering, Session Options, Detailed Options Description @subsection Report Options Options for Ledger report affect three separate scopes of operation: @@ -5088,7 +5096,7 @@ difference between these scopes. Ledger 3.0 contains provisions for GUIs, which would make use of the different scopes by keeping an instance of Ledger running in the background and running multiple sessions with multiple reports per session. -@option{--abbrev-len } Sets the minimum +@code{--abbrev-len } Sets the minimum length an account can be abbreviated to if it doesn't fit inside the @code{account-width}. If @code{abbrev-len} is zero, then the account name will be truncated on the right. If @code{abbrev-len} is greater @@ -5096,40 +5104,52 @@ than @code{account-width} then the account will be truncated on the left, with no shortening of the account names in order to fit into the desired width. -@option{--account } Prepend @code{} to all accounts +@table @code +@item --account +Prepend @code{} to all accounts reported. That is, the option @code{--account Personal} would tack @code{Personal:} to the beginning of every account reported in a balance report or register report. -@option{--account-width } Set the width of the account column in +@item --account-width + Set the width of the account column in the @code{register} report to @code{N} characters. -@option{--actual-dates} Show actual dates of transactions +@item --actual-dates + Show actual dates of transactions (@pxref{Effective Dates}). Also @code{-L}. -@option{--actual} Report only real transactions, with no automated or +@item --actual + Report only real transactions, with no automated or virtual transactions used. -@option{--add-budget} Show only unbudgeted postings. +@item --add-budget + Show only unbudgeted postings. -@option{--amount-data} On a register report print only the dates and +@item --amount-data + On a register report print only the dates and amount of postings. Useful for graphing and spreadsheet applications. -@option{--amount } Apply the given value expression to the posting +@item --amount + Apply the given value expression to the posting amount (@pxref{Value Expressions}). Using @code{--amount} you can apply an arbitrary transformation to the postings. -@option{--amount-width } Set the width in characters of the amount +@item --amount-width + Set the width in characters of the amount column in the register report. -@option{--anon} anonymizes registry output, mostly for sending in bug +@item --anon + anonymizes registry output, mostly for sending in bug reports. -@option{--average} Print average values over the number of transactions +@item --average + Print average values over the number of transactions instead of running totals. -@option{--balance-format } specifies the format to use for the +@item --balance-format + specifies the format to use for the @code{balance} report (@pxref{Format Strings}). The default is: @smallexample "%(justify(scrub(display_total), 20, -1, true, color))" @@ -5139,14 +5159,18 @@ instead of running totals. "--------------------\n" @end smallexample -@option{--base} ASK JOHN +@item --base + ASK JOHN -@option{--basis} Report the cost basis on all posting +@item --basis + Report the cost basis on all posting -@option{--begin } Specify the start date of all calculations. +@item --begin + Specify the start date of all calculations. Transactions before that date will be ignored. -@option{--bold-if } print the entire line in bold if the given +@item --bold-if + print the entire line in bold if the given value expression is true (@pxref{Value Expressions}). @smallexample @@ -5154,7 +5178,8 @@ ledger reg Expenses --begin Dec --bold-if "amount > 100" @end smallexample @noindent list all transactions since the beginning of December and bold any posting greater than $100 -@option{--budget-format } +@item --budget-format + specifies the format to use for the @code{budget} report (@pxref{Format Strings}). The default is: @smallexample "%(justify(scrub(display_total), 20, -1, true, color))" @@ -5164,14 +5189,17 @@ specifies the format to use for the @code{budget} report (@pxref{Format Strings} "--------------------\n" @end smallexample -@option{--budget} only display budgeted items. In a register report this +@item --budget + only display budgeted items. In a register report this displays transaction in the budget, in a balance report this displays accounts in the budget (@pxref{Budgeting and Forecasting}). -@option{--by-payee } +@item --by-payee + group the register report by payee. -@option{--cleared-format } specifies the format to use +@item --cleared-format + specifies the format to use for the @code{cleared} report (@pxref{Format Strings}). The default is: @smallexample @@ -5186,25 +5214,32 @@ for the @code{cleared} report (@pxref{Format Strings}). The default is: "---------------- ---------------- ---------\n" @end smallexample -@option{--cleared} consider only transaction that have been cleared for +@item --cleared + consider only transaction that have been cleared for display and calculation. -@option{--collapse} By default ledger prints all account in an account +@item --collapse + By default ledger prints all account in an account tree. With @code{--collapse} it print only the top level account specified. -@option{--collapse-if-zero} Collapses the account display only if it has +@item --collapse-if-zero + Collapses the account display only if it has a zero balance. -@option{--color} use color is the tty supports it. +@item --color + use color is the tty supports it. -@option{--columns } specify the width of the register report in +@item --columns + specify the width of the register report in characters. -@option{--count} Direct ledger to report the number of items when +@item --count + Direct ledger to report the number of items when appended to the commodities, accounts or payees command. -@option{--csv-format} specifies the format to use for the @code{csv} +@item --csv-format + specifies the format to use for the @code{csv} report (@pxref{Format Strings}). The default is: @smallexample "%(quoted(date))," @@ -5216,25 +5251,32 @@ report (@pxref{Format Strings}). The default is: "%(quoted(cleared ? \"*\" : (pending ? \"!\" : \"\")))," "%(quoted(join(note | xact.note)))\n" @end smallexample -@option{--current} +@item --current + Shorthand for @code{--limit "date <= today"} -@option{--daily} +@item --daily + Shorthand for @code{--period "daily"} -@option{--date-format } specifies format ledger should use +@item --date-format + specifies format ledger should use to print dates (@pxref{Date and Time Format Codes}). -@option{--date } transforms the date of the transaction using +@item --date + transforms the date of the transaction using @code{EXPR} -@option{--date-width } specifies the width, in characters, of the +@item --date-width + specifies the width, in characters, of the date column in the register report. -@option{--datetime-format} +@item --datetime-format + ASK JOHN -@option{--dc} Display register or balance in debit/credit format +@item --dc + Display register or balance in debit/credit format If you use @samp{--dc} with either the register (reg) or balance (bal) commands, you will now get extra columns. The register goes from this: @smallexample @@ -5285,81 +5327,103 @@ For the balance report without @samp{--dc}: @end smallexample -@option{--depth } limit the depth of the account tree. In a balance -report, for example, a @code{--depth 2} statement will print balances -only for account with two levels, i.e. @code{Expenses:Entertainment} but -not @code{Expenses:entertainemnt:Dining}. This is a display predicate, -which means it only affects display, not the total calculations. +@item --depth + limit the depth of the account tree. In a balance report, for example, +a @code{--depth 2} statement will print balances only for account with +two levels, i.e. @code{Expenses:Entertainment} but not +@code{Expenses:entertainemnt:Dining}. This is a display predicate, which +means it only affects display, not the total calculations. -@option{--deviation} reports each posting’s deviation from the - average. It is only mean- ingful in the register and prices reports. +@item --deviation + reports each posting’s deviation from the average. It is only + meaningful in the register and prices reports. -@option{--display-amount } apply a transform to the +@item --display-amount + apply a transform to the @strong{displayed} amount. This occurs after calculations occur. -@option{--display } +@item --display + display lines that satisfy the expression given. -@option{--display-total } apply a transform to the +@item --display-total + apply a transform to the @strong{displayed} total. This occurs after calculations occur. -@option{--dow} +@item --dow + group transactions by the day of the week. @smallexample ledger reg Expenses --dow --collapse @end smallexample @noindent will print all Expenses totalled for each day of the week. -@option{--effective} +@item --effective + use effective dates for all calculations (@pxref{Effective Dates}). -@option{--empty} +@item --empty + include empty accounts in the report. -@option{--end } +@item --end + specify the end date for transaction to be considered in the report. -@option{--equity} related to the @code{equity} command (@pxref{The +@item --equity + related to the @code{equity} command (@pxref{The equity Command}). Gives current account balances in the form of a register report. -@option{--exact} +@item --exact + ASK JOHN -@option{--exchange } display values in terms of the given +@item --exchange + display values in terms of the given commodity. The latest available price is used. -@option{--flat} force the full names of accounts to be used inthe +@item --flat + force the full names of accounts to be used inthe balance report. The balance report will not use an indented tree. -@option{--force-color} output tty color codes even if the tty doesn't +@item --force-color + output tty color codes even if the tty doesn't support them. Ueful for TTY that don't advertise their capabilities correctly. -@option{--force-pager} +@item --force-pager + force Ledger to paginate its output. -@option{forecast-while} +@item --forecast-while + FIX THIS ENTRY -@option{forecast-years} +@item --forecast-years + FIX THIS ENTRY -@option{--format } +@item --format + use the given format string to print output. -@option{--gain} +@item --gain + report on gains using the latest available prices . -@option{generated} +@item --generated + ASK JOHN -@option{--group-by } group transaction together in the register +@item --group-by + group transaction together in the register report. EXPR can be anything, although most common would be @code{"payee"} or @code{"commodity"}. The @code{tags()} function is also useful here. -@option{--group-title-format} sets the format for the headers that +@item --group-title-format + sets the format for the headers that separate reports section of a grouped report. Only has effect with a @code{--group-by} register report. @smallexample @@ -5376,200 +5440,282 @@ ledger reg Expenses --group-by "payee" --group-title-format "------------------- @end smallexample -@option{--head } +@item --head + Print the first INT entries. Opposite of @code{--tail}. -@option{--inject} -See email from John W. +@item --inject +Use @code{Expected} amounts in calculations. In the case that you know +that amount a transaction should be, but the actual transaction has the +wrong value you can use metadata to put in the expected amount: +@smallexample +2012-03-12 Paycheck + Income $-990; Expected:: $-1000.00 + Checking +@end smallexample + +Then using the command @code{ledger reg --inject=Expected Income} would +treat the transaction as iff the ``Expected Value'' was actual. +@item --invert -@option{--invert} Change the sign of all reported values. -@option{--limit } Only transactions that satisfy the expression +@item --limit + Only transactions that satisfy the expression will be considered in the calculation. -@option{--lot-dates} -FIX THIS ENTRY +@item --lot-dates +Report the date on which each commodity in a balance report was purchased. -@option{--lot-prices} -FIX THIS ENTRY +@item --lot-prices -@option{--lot-tags} -FIX THIS ENTRY +Report the price at which each commodity in a balance report was purchased. -@option{--lots-actual} -FIX THIS ENTRY +@item --lot-tags -@option{--lots} -FIX THIS ENTRY +Report the tag attached to each commodity in a balance report. -@option{market} -FIX THIS ENTRY +@item --lots-actual -@option{meta} FIX THIS ENTRY -@option{meta-width} +@item --lots + +Report the date and price at which each commodity was purchased in a balance report. + +@item --market + +Use the latest market value for all commodities. + +@item --meta + FIX THIS ENTRY -@option{--monthly} +@item --meta-width + FIX THIS ENTRY -@option{--no-color} +@item --monthly + +synonymn for @code{--period "monthly"} + +@item --no-color + suppress any color TTY output. -@option{--no-rounding} -FIX THIS ENTRY +@item --no-rounding -@option{--no-titles} FIX THIS ENTRY -@option{--no-total} -FIX THIS ENTRY +@item --no-titles -@option{--now} -FIX THIS ENTRY +Suppress the output of group titles -@option{only} -FIX THIS ENTRY +@item --no-total -@option{--output} -FIX THIS ENTRY +Suppress printing the final total line in a balance report. -@option{--pager} -FIX THIS ENTRY +@item --now -@option{payee} FIX THIS ENTRY -@option{payee-width} +@item --only + FIX THIS ENTRY -@option{--pending} -Use only postings tht are marked pending +@item --output -@option{percent} FIX THIS ENTRY -@option{period} -FIX THIS ENTRY +@item --pager -@option{--pivot} -FIX THIS ENTRY +Specify the pager program to use. -@option{plot-amount-format} -FIX THIS ENTRY +@item --payee -@option{plot-total-format} -FIX THIS ENTRY +Sets a value expression for formatting the payee. In the register report +this prevents the second entry from having a date and payee for each +transaction -@option{prepend-format} -FIX THIS ENTRY +@item --payee-width N -@option{prepend-width} -FIX THIS ENTRY +Set the number of columns dedicated to the payee in the register report. -@option{pricedb-format} -FIX THIS ENTRY +@item --pending -@option{price} -FIX THIS ENTRY +Use only postings that are marked pending -@option{prices-format} -FIX THIS ENTRY +@item --percent +Calculate the percentage value of each account in a blance reports. +Only works for account that have a single commoditiy. + +@item --period + +Define a period expression the sets the time period during which +transactions are to be accounted. For a register report only th +transactions that satisfy the period expression with be displayed. For +a balance report only those transactions will be accounted in the final +balances. + +@item --pivot + +Produce a balance pivot report ``around'' the given tag. For example, +if you have multiple cars and track each fuel purchase in +@code{Expenses:Auto:Fuel} and tag each fuel purchase with a tag +identifying which car the purchase was for @code{; Car: Prius}, then the command: +@smallexample +ledger bal Fuel --pivot "Car" --period "this year" + $ 3491.26 Car + $ 1084.22 M3:Expenses:Auto:Fuel + $ 149.65 MG V11:Expenses:Auto:Fuel + $ 621.89 Prius:Expenses:Auto:Fuel + $ 1635.50 Sienna:Expenses:Auto:Fuel + $ 42.69 Expenses:Auto:Fuel +-------------------- + $ 3533.95 +@end smallexample + +@item --plot-amount-format + +Define the output format for a amount data plot. @xref{Visualizing with Gnuplot}. + +@item --plot-total-format + +Define the output format for a total data plot. @xref{Visualizing with Gnuplot}. + +@item --prepend-format STR + +Prepend STR to every line of the output + +@item --prepend-width N + +Reserve @code{N} spaces at the beginning of each line of the output + + +@item --price -@option{quantity} FIX THIS ENTRY -@option{--quarterly} +@item --quantity + FIX THIS ENTRY -@option{raw} +@item --quarterly + +Synonym for @code{--period "quarterly"}. + +@item --raw + FIX THIS ENTRY -@option{--real} Account using only real transactions ignoring virtual +@item --real + Account using only real transactions ignoring virtual and automatic transactions. -@option{register-format} -FIX THIS ENTRY -@option{related-all} -FIX THIS ENTRY +@item --related-all + +Show all postings in a transaction, similar to @code{--related} but show +both ``sides'' of each transaction. + +@item --related -@option{--related} -In a register report show the related account. +In a register report show the related account. This is the other +``side'' of the transaction. + +@item --revalued-only -@option{--revalued-only} FIX THIS ENTRY -@option{--revalued-total} +@item --revalued-total + FIX THIS ENTRY -@option{--revalued} +@item --revalued + FIX THIS ENTRY -@option{seed} +@item --seed + FIX THIS ENTRY -@option{sort-all} +@item --sort-all + FIX THIS ENTRY -@option{--sort } +@item --sort + Sort the register report based on the value expression given to sort -@option{--sort-xacts} -FIX THIS ENTRY +@item --sort-xacts + +Sort the posting within transactions using the given value expression + +@item --start-of-week +Tell ledger to use a particular day of the week to start its ``weekly'' +summary. @code{--start-of-week=1} specifies Monday as the start of the +week. -@option{--start-of-week } Tell ledger to use a particular day of -the week to start its ``weekly'' summary. @code{--start-of-week=1} -specifies Monday as the start of the week. +@item --subtotal -@option{--subtotal} FIX THIS ENTRY -@option{--tail } +@item --tail + report only the last entries. Only useful ona register report. -@option{total-data} +@item --total-data + FIX THIS ENTRY -@option{total} +@item --total + FIX THIS ENTRY -@option{total-width} +@item --total-width + FIX THIS ENTRY -@option{truncate} +@item --truncate + FIX THIS ENTRY -@option{unbudgeted} +@item --unbudgeted + FIX THIS ENTRY -@option{uncleared} +@item --uncleared + FIX THIS ENTRY -@option{unrealized-gains} +@item --unrealized-gains + FIX THIS ENTRY -@option{unrealized-losses} +@item --unrealized-losses + FIX THIS ENTRY -@option{unrealized} +@item --unrealized + FIX THIS ENTRY -@option{unround} +@item --unround + FIX THIS ENTRY -@option{--weekly} +@item --weekly + synonymn for @code{--period "weekly"} -@option{--wide} lets the register report use 132 columns. Identical to -@code{--columns "132"} +@item --wide +lets the register report use 132 columns. Identical to @code{--columns +"132"} -@option{yearly} +@item --yearly synonymn for @code{--period "yearly"} - +@end table @@ -5579,29 +5725,37 @@ These are the most basic command options. Most likely, the user will want to set them using environment variables (see @ref{Environment Variables}), instead of using actual command-line options: -@option{--help} (@option{-h}) prints a summary of all the options, and -what they are used for. This can be a handy way to remember which -options do what. This help screen is also printed if ledger is run -without a command. - -@option{--version} (@option{-v}) prints the current version of ledger -and exits. This is useful for sending bug reports, to let the author -know which version of ledger you are using. - -@option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file. -This command may be used multiple times. -Typically, the environment variable -@env{LEDGER_FILE} is set, rather than using this command-line option. - -@option{--output FILE} (@option{-o FILE}) redirects output from any -command to @var{FILE}. By default, all output goes to standard -output. - -@option{--init-file FILE} (@option{-i FILE}) causes FILE to be read by -ledger before any other ledger file. This file may not contain any -postings, but it may contain option settings. To specify options -in the init file, use the same syntax as the command-line, but put each -option on it's own line. Here's an example init file: +@table @code +@item --help +@item -h +Prints a summary of all the options, and what they are used for. This +can be a handy way to remember which options do what. This help screen +is also printed if ledger is run without a command. + +@item --version +@item -v +prints the current version of ledger and exits. This is useful for +sending bug reports, to let the author know which version of ledger you +are using. + +@item --file FILE +@item -f FILE +reads FILE as a ledger file. This command may be used multiple times. +Typically, the environment variable @env{LEDGER_FILE} is set, rather +than using this command-line option. + +@item --output FILE +@item -o FILE +redirects output from any command to @var{FILE}. By default, all output +goes to standard output. + +@item --init-file FILE +@item -i FILE +causes FILE to be read by ledger before any other ledger file. This +file may not contain any postings, but it may contain option settings. +To specify options in the init file, use the same syntax as the +command-line, but put each option on it's own line. Here's an example +init file: @smallexample --price-db ~/finance/.pricedb @@ -5613,68 +5767,81 @@ Option settings on the command-line or in the environment always take precedence over settings in the init file. -@option{--account NAME} (@option{-a NAME}) specifies the default -account which QIF file postings are assumed to relate to. +@item --account NAME +@item -a NAME +specifies the default account which QIF file postings are assumed to +relate to. +@end table -@node Report Filtering, Search Terms, Report Options, Detailed Options Description +@node Report Filtering, Output Customization, Report Options, Detailed Options Description @subsection Report filtering These options change which postings affect the outcome of a report, in ways other than just using regular expressions: -@option{--current}(@option{-c}) displays only transactions occurring on or -before the current date. - -@option{--begin DATE} (@option{-b DATE}) constrains the report to -transactions on or after @var{DATE}. Only transactions after that date will be -calculated, which means that the running total in the balance report -will always start at zero with the first matching transaction. (Note: This -is different from using @option{--display} to constrain what is -displayed). - -@option{--end DATE} (@option{-e DATE}) constrains the report so that -transactions on or after @var{DATE} are not considered. The ending date -is inclusive. - -@option{--period STR} (@option{-p STR}) sets the reporting period -to @var{STR}. This will subtotal all matching transactions within each -period separately, making it easy to see weekly, monthly, quarterly, -etc., posting totals. A period string can even specify the -beginning and end of the report range, using simple terms like ``last -June'' or ``next month''. For more using period expressions, see -@ref{Period Expressions}. - -@option{--period-sort EXPR} sorts the postings within each -reporting period using the value expression @var{EXPR}. This is most -often useful when reporting monthly expenses, in order to view the -highest expense categories at the top of each month: +@table @code +@item --current +@item -c +displays only transactions occurring on or before the current date. + +@item --begin DATE +@item -b DATE constrains the report to transactions on or after +@var{DATE}. Only transactions after that date will be calculated, which +means that the running total in the balance report will always start at +zero with the first matching transaction. (Note: This is different from +using @option{--display} to constrain what is displayed). + +@item --end DATE +@item -e DATE +constrains the report so that transactions on or after @var{DATE} are +not considered. The ending date is inclusive. + +@item --period STR +@item -p STR sets the reporting period to @var{STR}. This will subtotal +all matching transactions within each period separately, making it easy +to see weekly, monthly, quarterly, etc., posting totals. A period +string can even specify the beginning and end of the report range, using +simple terms like ``last June'' or ``next month''. For more using +period expressions, see @ref{Period Expressions}. + +@item --period-sort EXPR +sorts the postings within each reporting period using the value +expression @var{EXPR}. This is most often useful when reporting monthly +expenses, in order to view the highest expense categories at the top of +each month: @smallexample ledger -M --period-sort -At reg ^Expenses @end smallexample -@option{--cleared} (@option{-C}) displays only postings whose transaction -has been marked ``cleared'' (by placing an asterisk to the right of the -date). +@item --cleared +@item -C + displays only postings whose transaction has been marked ``cleared'' +(by placing an asterisk to the right of the date). -@option{--uncleared} (@option{-U}) displays only postings whose -transaction has not been marked ``cleared'' (i.e., if there is no asterisk to -the right of the date). +@item --uncleared +@item -U +displays only postings whose transaction has not been marked ``cleared'' +(i.e., if there is no asterisk to the right of the date). -@option{--real} (@option{-R}) displays only real postings, not virtual. -(A virtual posting is indicated by surrounding the account name with -parentheses or brackets; see @ref{Virtual postings} for more -information). +@item --real +@item -R + displays only real postings, not virtual. (A virtual posting is +indicated by surrounding the account name with parentheses or brackets; +see @ref{Virtual postings} for more information). -@option{--actual} (@option{-L}) displays only actual postings, and -not those created due to automated postings. +@item --actual +@item -L +displays only actual postings, and not those created due to automated +postings. -@option{--related} (@option{-r}) displays postings that are -related to whichever postings would otherwise have matched the -filtering criteria. In the register report, this shows where money -went to, or the account it came from. In the balance report, it shows -all the accounts affected by transactions having a related posting. -For example, if a file had this transaction: +@item --related +@item -r +displays postings that are related to whichever postings would otherwise +have matched the filtering criteria. In the register report, this shows +where money went to, or the account it came from. In the balance +report, it shows all the accounts affected by transactions having a +related posting. For example, if a file had this transaction: @smallexample 2004/03/20 Safeway @@ -5697,154 +5864,184 @@ posting that matched: Assets:Checking $85.00 $65.00 @end smallexample -@option{--budget} is useful for displaying how close your postings -meet your budget. @option{--add-budget} also shows un-budgeted -postings, while @option{--unbudgeted} shows only those. -@option{--forecast} is a related option that projects your budget into -the future, showing how it will affect future balances. -@xref{Budgeting and Forecasting}. +@item --budget +is useful for displaying how close your postings meet your budget. +@code{--add-budget} also shows un-budgeted postings, while +@code{--unbudgeted} shows only those. @code{--forecast} is a related +option that projects your budget into the future, showing how it will +affect future balances. @xref{Budgeting and Forecasting}. -@option{--limit EXPR} (@option{-l EXPR}) limits which postings -take part in the calculations of a report. +@item --limit EXPR +@item -l EXPR +limits which postings take part in the calculations of a report. -@option{--amount EXPR} (@option{-t EXPR}) changes the value expression -used to calculate the ``value'' column in the @command{register} -report, the amount used to calculate account totals in the -@command{balance} report, and the values printed in the +@item --amount EXPR +@item -t EXPR +changes the value expression used to calculate the ``value'' column in +the @command{register} report, the amount used to calculate account +totals in the @command{balance} report, and the values printed in the @command{equity} report. @xref{Value Expressions}. -@option{--total EXPR} (@option{-T EXPR}) sets the value expression -used for the ``totals'' column in the @command{register} and -@command{balance} reports. - -@node Search Terms, Output Customization, Report Filtering, Detailed Options Description -@subsection Search Terms - -Valid Ledger invocations look like: -@smallexample - ledger [OPTIONS] -@end smallexample - -Where @samp{COMMAND} is any command verb (@pxref{Reporting Commands}), @samp{OPTIONS} can occur -anywhere, and @samp{SEARCH-TERM} is one or more of the following: - -@smallexample - word search for any account containing 'word' - TERM and TERM boolean AND between terms - TERM or TERM boolean OR between terms - not TERM invert the meaning of the term - payee word search for any payee containing 'word' - @@word shorthand for 'payee word' - desc word alternate for 'payee word' - note word search for any note containing 'word' - &word shorthand for 'note word' - tag word search for any metadata tag containing 'word' - tag word=value search for any metadata tag containing 'word' - whose value contains 'value' - %word shorthand for 'tag word' - %word=value shorthand for 'tag word=value' - meta word alternate for 'tag word' - meta word=value alternate for 'tag word=value' - expr 'EXPR' apply the given value expression as a predicate - '=EXPR' shorthand for 'expr EXPR' - \( TERMS \) group terms; useful if using and/or/not -@end smallexample - -So, to list all transaction that charged to ``food'' but not ``dining'' for any payee other than ``chang'' the following three commands would be equivalent: - -@smallexample - ledger reg food not dining @@chang - ledger reg food and not dining and not payee chang - ledger reg food not dining expr 'payee =~ /chang/' -@end smallexample - -@node Output Customization, Commodity Reporting, Search Terms, Detailed Options Description +@item --total EXPR +@item -T EXPR +sets the value expression used for the ``totals'' column in the +@command{register} and @command{balance} reports. +@end table +@c @node Search Terms, Output Customization, Report Filtering, Detailed Options Description +@c @subsection Search Terms + +@c Valid Ledger invocations look like: +@c @smallexample +@c ledger [OPTIONS] +@c @end smallexample + +@c Where @samp{COMMAND} is any command verb (@pxref{Reporting Commands}), @samp{OPTIONS} can occur +@c anywhere, and @samp{SEARCH-TERM} is one or more of the following: + +@c @smallexample +@c word search for any account containing 'word' +@c TERM and TERM boolean AND between terms +@c TERM or TERM boolean OR between terms +@c not TERM invert the meaning of the term +@c payee word search for any payee containing 'word' +@c @@word shorthand for 'payee word' +@c desc word alternate for 'payee word' +@c note word search for any note containing 'word' +@c &word shorthand for 'note word' +@c tag word search for any metadata tag containing 'word' +@c tag word=value search for any metadata tag containing 'word' +@c whose value contains 'value' +@c %word shorthand for 'tag word' +@c %word=value shorthand for 'tag word=value' +@c meta word alternate for 'tag word' +@c meta word=value alternate for 'tag word=value' +@c expr 'EXPR' apply the given value expression as a predicate +@c '=EXPR' shorthand for 'expr EXPR' +@c \( TERMS \) group terms; useful if using and/or/not +@c @end smallexample + +@c So, to list all transaction that charged to ``food'' but not ``dining'' +@c for any payee other than ``chang'' the following three commands would be +@c equivalent: + +@c @smallexample +@c ledger reg food not dining @@chang +@c ledger reg food and not dining and not payee chang +@c ledger reg food not dining expr 'payee =~ /chang/' +@c @end smallexample + +@node Output Customization, Commodity Reporting, Report Filtering, Detailed Options Description @subsection Output Customization These options affect only the output, but not which postings are used to create it: -@option{--collapse} (@option{-n}) causes transactions in a -@command{register} report with multiple postings to be collapsed +@table @code +@item --collapse +@item -n +causes transactions in a @command{register} report with multiple +postings to be collapsed into a single, subtotaled transaction. + +@item --subtotal +@item -s + causes all transactions in a @command{register} report to be collapsed into a single, subtotaled transaction. -@option{--subtotal} (@option{-s}) causes all transactions in a -@command{register} report to be collapsed into a single, subtotaled -transaction. - -@option{--by-payee} (@option{-P}) reports subtotals by payee. - - -@option{--empty} (@option{-E}) includes even empty accounts in the -@command{balance} report. - -@option{--weekly} (@option{-W}) reports posting totals by the -week. The week begins on whichever day of the week begins the month -containing that posting. To set a specific begin date, use a -period string, such as @samp{weekly from DATE}. @option{--monthly} -(@option{-M}) reports posting totals by month; @option{--yearly} -(@option{-Y}) reports posting totals by year. For more complex -period, using the @option{--period} option described above. - -@option{--dow} reports postings totals for each day of the week. -This is an easy way to see if weekend spending is more than on -weekdays. - -@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing -the values determined using the value expression @var{EXPR}. For -example, using @option{-S -UT} in the balance report will sort account -balances from greatest to least, using the absolute value of the -total. For more on how to use value expressions, see @ref{Value -Expressions}. - -@option{--pivot TAG} produces a pivot table around the tag provided. -This requires meta data using valued tags. - -@option{--wide} (@option{-w}) causes the default @command{register} -report to assume 132 columns instead of 80. - -@option{--head} causes only the first N transactions to be printed. This -is different from using the command-line utility @command{head}, which -would limit to the first N postings. @option{--tail} outputs only -the last N transactions. Both options may be used simultaneously. If a -negative amount is given, it will invert the meaning of the flag -(instead of the first five transactions being printed, for example, it -would print all but the first five). - -@option{--pager} tells Ledger to pass its output to the given pager -program---very useful when the output is especially long. This -behavior can be made the default by setting the @env{LEDGER_PAGER} -environment variable. - -@option{--average} (@option{-A}) reports the average posting -value. - -@option{--deviation} (@option{-D}) reports each posting's -deviation from the average. It is only meaningful in the -@command{register} and @command{prices} reports. - -@option{--percent} (@option{-%}) shows account subtotals in the -@command{balance} report as percentages of the parent account. +@item --by-payee +@item -P +reports subtotals by payee. + + +@item --empty +@item -E +includes even empty accounts in the @command{balance} report. + +@item --weekly +@item -W +reports posting totals by the week. The week begins on whichever day of +the week begins the month containing that posting. To set a specific +begin date, use a period string, such as @samp{weekly from DATE}. +@item --monthly +@item -M +reports posting totals by month; +@item --yearly +@item -Y +reports posting totals by year. For more complex period, using the +@item --period +option described above. + +@item --dow +reports postings totals for each day of the week. This is an easy way +to see if weekend spending is more than on weekdays. + +@item --sort EXPR +@item -S EXPR +sorts a report by comparing the values determined using the value +expression @var{EXPR}. For example, using @option{-S -UT} in the +balance report will sort account balances from greatest to least, using +the absolute value of the total. For more on how to use value +expressions, see @ref{Value Expressions}. + +@item --pivot TAG +produces a pivot table around the tag provided. This requires meta data +using valued tags. + +@item --wide +@item -w +causes the default @command{register} report to assume 132 columns +instead of 80. + +@item --head +causes only the first N transactions to be printed. This is different +from using the command-line utility @command{head}, which would limit to +the first N postings. @option{--tail} outputs only the last N +transactions. Both options may be used simultaneously. If a negative +amount is given, it will invert the meaning of the flag (instead of the +first five transactions being printed, for example, it would print all +but the first five). + +@item --pager +tells Ledger to pass its output to the given pager program---very useful +when the output is especially long. This behavior can be made the +default by setting the @env{LEDGER_PAGER} environment variable. + +@item --average +@item -A +reports the average posting value. + +@item --deviation +@item -D +reports each posting's deviation from the average. It is only +meaningful in the @command{register} and @command{prices} reports. + +@item --percent +@item -% +shows account subtotals in the @command{balance} report as percentages +of the parent account. @c @option{--totals} include running total information in the @c @command{xml} report. -@option{--amount-data} (@option{-j}) changes the @command{register} -report so that it outputs nothing but the date and the value column, -and the latter without commodities. This is only meaningful if the -report uses a single commodity. This data can then be fed to other -programs, which could plot the date, analyze it, etc. +@item --amount-data +@item -j +changes the @command{register} report so that it outputs nothing but the +date and the value column, and the latter without commodities. This is +only meaningful if the report uses a single commodity. This data can +then be fed to other programs, which could plot the date, analyze it, +etc. -@option{--total-data} (@option{-J}) changes the @command{register} -report so that it outputs nothing but the date and totals column, -without commodities. +@item --total-data +@item -J +changes the @command{register} report so that it outputs nothing but the +date and totals column, without commodities. -@option{--display EXPR} (@option{-d EXPR}) limits which postings -or accounts or actually displayed in a report. They might still be -calculated, and be part of the running total of a register report, for -example, but they will not be displayed. This is useful for seeing -last month's checking postings, against a running balance which -includes all posting values: +@item --display EXPR +@item -d EXPR +limits which postings or accounts or actually displayed in a report. +They might still be calculated, and be part of the running total of a +register report, for example, but they will not be displayed. This is +useful for seeing last month's checking postings, against a running +balance which includes all posting values: @smallexample ledger -d "d>=[last month]" reg checking @@ -5862,38 +6059,133 @@ Which is more useful depends on what you're looking to know: the total amount for the reporting range (@option{-p}), or simply a display restricted to the reporting range (using @option{-d}). -@option{--date-format STR} (@option{-y STR}) changes the basic date -format used by reports. The default uses a date like 2004/08/01, -which represents the default date format of @samp{%Y/%m/%d}. To -change the way dates are printed in general, the easiest way is to put -@option{--date-format FORMAT} in the Ledger initialization file -@file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}). - -@option{--format STR} (@option{-F STR}) sets the reporting format for -whatever report ledger is about to make. @xref{Format Strings}. -There are also specific format commands for each report type: - -@itemize -@item @option{--balance-format STR} -@item @option{--register-format STR} -@item @option{--print-format STR} -@item @option{--plot-amount-format STR} (-j @command{register}) -@item @option{--plot-total-format STR} (-J @command{register}) -@item @option{--equity-format STR} -@item @option{--prices-format STR} -@item @option{--wide-register-format STR} (-w @command{register}) -@end itemize +@item --date-format STR +@item -y STR +changes the basic date format used by reports. The default uses a date +like 2004/08/01, which represents the default date format of +@samp{%Y/%m/%d}. To change the way dates are printed in general, the +easiest way is to put @option{--date-format FORMAT} in the Ledger +initialization file @file{~/.ledgerrc} (or the file referred to by +@env{LEDGER_INIT}). + +@item --format STR +@item -F STR +sets the reporting format for whatever report ledger is about to make. +@xref{Format Strings}. There are also specific format commands for each +report type: + +@item --balance-format STR +Define the output format for the @code{balance} report. The default (defined in @code{report.h} is: +@smallexample + "%(ansify_if( + justify(scrub(display_total), 20, + 20 + int(prepend_width), true, color), + bold if should_bold)) + %(!options.flat ? depth_spacer : \"\") + %-(ansify_if( + ansify_if(partial_account(options.flat), blue if color), + bold if should_bold))\n%/ + %$1\n%/ + %(prepend_width ? \" \" * int(prepend_width) : \"\") + --------------------\n" +@end smallexample +@item --cleared-format +Defines the format for the cleared report. The default is: +@smallexample + "%(justify(scrub(get_at(display_total, 0)), 16, 16 + int(prepend_width), + true, color)) %(justify(scrub(get_at(display_total, 1)), 18, + 36 + int(prepend_width), true, color)) + %(latest_cleared ? format_date(latest_cleared) : \" \") + %(!options.flat ? depth_spacer : \"\") + %-(ansify_if(partial_account(options.flat), blue if color))\n%/ + %$1 %$2 %$3\n%/ + %(prepend_width ? \" \" * int(prepend_width) : \"\") + ---------------- ---------------- ---------\n" +@end smallexample +@item --register-format STR +Define the output format for the @code{register} report. The default (defined in @code{report.h} is: +@smallexample + "%(ansify_if( + ansify_if(justify(format_date(date), int(date_width)), + green if color and date > today), + bold if should_bold)) + %(ansify_if( + ansify_if(justify(truncated(payee, int(payee_width)), int(payee_width)), + bold if color and !cleared and actual), + bold if should_bold)) + %(ansify_if( + ansify_if(justify(truncated(display_account, int(account_width), + int(abbrev_len)), int(account_width)), + blue if color), + bold if should_bold)) + %(ansify_if( + justify(scrub(display_amount), int(amount_width), + 3 + int(meta_width) + int(date_width) + int(payee_width) + + int(account_width) + int(amount_width) + int(prepend_width), + true, color), + bold if should_bold)) + %(ansify_if( + justify(scrub(display_total), int(total_width), + 4 + int(meta_width) + int(date_width) + int(payee_width) + + int(account_width) + int(amount_width) + int(total_width) + + int(prepend_width), true, color), + bold if should_bold))\n%/ + %(justify(\" \", int(date_width))) + %(ansify_if( + justify(truncated(has_tag(\"Payee\") ? payee : \" \", + int(payee_width)), int(payee_width)), + bold if should_bold)) + %$3 %$4 %$5\n" +@end smallexample +@item --csv-format +Sets the format for @code{csv} reports. The default is: +@smallexample +"%(quoted(date)), + %(quoted(code)), + %(quoted(payee)), + %(quoted(display_account)), + %(quoted(commodity)), + %(quoted(quantity(scrub(display_amount)))), + %(quoted(cleared ? \"*\" : (pending ? \"!\" : \"\"))), + %(quoted(join(note | xact.note)))\n" +@end smallexample +@item --plot-amount-format STR +Sets the format for amount plots, using the @code{-j} option. The default is: +@smallexample +"%(format_date(date, \"%Y-%m-%d\")) %(quantity(scrub(display_amount)))\n" +@end smallexample +@item --plot-total-format STR +Sets the format for total plots, using the @code{-J} option. The default is: +@smallexample +"%(format_date(date, \"%Y-%m-%d\")) %(quantity(scrub(display_total)))\n" +@end smallexample +@item --pricedb-format STR +Sets the format expected for the histroical price file. The default is +@smallexample +"P %(datetime) %(display_account) %(scrub(display_amount))\n" +@end smallexample + +@item --prices-format STR +Sets the format for the @command{prices} report. The deault is: +@smallexample +"%(date) %-8(display_account) %(justify(scrub(display_amount), 12, + 2 + 9 + 8 + 12, true, color))\n" +@end smallexample +@item --wide-register-format STR +(-w @command{register}) +@end table @node Commodity Reporting, Environment Variables, Output Customization, Detailed Options Description @subsection Commodity Reporting These options affect how commodity values are displayed: - -@option{--price-db FILE} sets the file that is used for recording -downloaded commodity prices. It is always read on start up, to -determine historical prices. Other settings can be placed in this -file manually, to prevent downloading quotes for a specific commodity, for -example. This is done by adding a line like the following: +@table @code +@item --price-db FILE +sets the file that is used for recording downloaded commodity prices. +It is always read on start up, to determine historical prices. Other +settings can be placed in this file manually, to prevent downloading +quotes for a specific commodity, for example. This is done by adding a +line like the following: @smallexample ; Don't download quotes for the dollar, or timelog values @@ -5901,24 +6193,31 @@ N $ N h @end smallexample -Note: Ledger NEVER write output to files. You are responsible for +@noindent Note: Ledger NEVER write output to files. You are responsible for updated the price-db file. The best way is to have your price download script maintain this file. -@option{--price-exp MINS} (@option{-L MINS}) sets the expected -freshness of price quotes, in minutes. That is, if the last known quote -for any commodity is older than this value---and if @option{--download} -is being used---then the Internet will be consulted again for a newer -price. Otherwise, the old price is still considered to be fresh enough. - -@option{--download} (@option{-Q}) causes quotes to be automagically -downloaded, as needed, by running a script named @command{getquote} -and expecting that script to return a value understood by ledger. A -sample implementation of a @command{getquote} script, implemented in -Perl, is provided in the distribution. Downloaded quote price are -then appended to the price database, usually specified using the -environment variable @env{LEDGER_PRICE_DB}. - +The format of the file can be changed by telling ledger to use the +@code{--pricedb-format} you define. + +@item --price-exp MINS +@item -L MINS +sets the expected freshness of price quotes, in minutes. That is, if +the last known quote for any commodity is older than this value---and if +@code{--download} is being used---then the Internet will be consulted +again for a newer price. Otherwise, the old price is still considered +to be fresh enough. + +@item --download +@item -Q +causes quotes to be automagically downloaded, as needed, by running a +script named @command{getquote} and expecting that script to return a +value understood by ledger. A sample implementation of a +@command{getquote} script, implemented in Perl, is provided in the +distribution. Downloaded quote price are then appended to the price +database, usually specified using the environment variable +@env{LEDGER_PRICE_DB}. +@end table There are several different ways that ledger can report the totals it displays. The most flexible way to adjust them is by using value expressions, and the @option{-t} and @option{-T} options. However, @@ -6689,7 +6988,7 @@ minimum amount of state detail is printed. Inserts the ``optimized'' form of a posting's amount. This is used by the print report. In some cases, this inserts nothing; in others, it inserts the posting amount and its cost. It's use is -not recommend unless you are modifying the print report. +not recommended unless you are modifying the print report. @item n Inserts the note associated with a posting, preceded by two spaces -- cgit v1.2.3 From 25f063ab7cb0af91891ed7e0a9948eb2e884be42 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 10 Oct 2012 07:31:17 -0700 Subject: Fixes bug 801. Replaces "jorunal" with Ledger on line 235 of ledger3.texi --- doc/ledger3.texi | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index ab59f2ae..b0373dc2 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -236,7 +236,7 @@ $ ledger -f ledger.dat register Bell An important difference between Ledger and other finance packages is that journal will never alter your input file. You can create and edit -that file in any way you prefer, but journal is only for analyzing the +that file in any way you prefer, but Ledger is only for analyzing the data, not for altering it. @@ -504,7 +504,6 @@ cannot display any currency symbols other than dollar signs ($). @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 @item @code{emacs} @tab Produce Emacs lisp output @item @code{equity} @tab Print account balances as transactions -- cgit v1.2.3 From d7a03c471692f508118be7a9d0bb30f49374c1e7 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 10 Oct 2012 09:43:16 -0700 Subject: Detailed section on the new commodity valuation system. --- doc/ledger3.texi | 485 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 320 insertions(+), 165 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index b0373dc2..08be7551 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -280,7 +280,6 @@ http://groups.google.com/group/ledger-cli @menu * Start a Journal:: * Run Some Reports:: -* Command Line Quick Reference:: @end menu @node Start a Journal, Run Some Reports, Ledger Tutorial , Ledger Tutorial @@ -295,7 +294,7 @@ directory. If you would rather start with your own journal right away please see @ref{Keeping a Journal}. -@node Run Some Reports, Command Line Quick Reference, Start a Journal, Ledger Tutorial +@node Run Some Reports, , Start a Journal, Ledger Tutorial @section Run a Few Reports @menu @@ -482,147 +481,6 @@ 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 ($). -@page -@node Command Line Quick Reference, , Run Some Reports, Ledger Tutorial -@section Command Line Quick Reference - -@menu -* Reporting Commands Quick Reference:: -* Basic Options Quick Reference:: -* Report Filtering Quick Reference:: -* Error Checking and Calculation Options:: -* Output Customization Quick Reference:: -* Grouping Options:: -* Commodity Reporting Quick Reference:: -@end menu - -@node Reporting Commands Quick Reference, Basic Options Quick Reference, Command Line Quick Reference, Command Line Quick Reference -@subsection Reporting Commands -@multitable @columnfractions .2 .8 -@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{xml} @tab Produce XML output of the register command -@item @code{emacs} @tab Produce Emacs lisp output -@item @code{equity} @tab Print account balances as transactions -@item @code{prices} @tab Print price history for matching commodities -@item @code{pricedb} @tab Print price history for matching commodities in ledger readable format -@item @code{xact} @tab Used to generate transactions based on previous postings -@end multitable - -@node Basic Options Quick Reference, Report Filtering Quick Reference, Reporting Commands Quick Reference, Command Line Quick Reference -@subsection Basic Options -@multitable @columnfractions .1 .25 .65 -@item @strong{Short} @tab @strong{Long} @tab @strong{Description} -@item @code{-h} @tab @code{--help} @tab prints summary of all options -@item @code{-v} @tab @code{--version} @tab prints version of ledger executable -@item @code{-f FILE} @tab @code{--file FILE} @tab read @file{FILE} as a ledger file -@item @code{-o FILE} @tab @code{--output FILE} @tab redirects output to @file{FILE} -@item @code{-i FILE} @tab @code{--init-file FILE} @tab specify options file -@item @code{-a NAME} @tab @code{--account NAME} @tab specify default account name for QIF file postings -@end multitable - -@node Report Filtering Quick Reference, Error Checking and Calculation Options, Basic Options Quick Reference, Command Line Quick Reference -@subsection Report Filtering -@multitable @columnfractions .1 .25 .65 -@item @strong{Short} @tab @strong{Long} @tab @strong{Description} -@item @code{-c} @tab @code{--current} @tab Display transaction on or before the current date -@item @code{-b DATE} @tab @code{--begin DATE} @tab Begin reports on or after @code{DATE} -@item @code{-e DATE} @tab @code{--end DATE} @tab Limits end date of transactions for report -@item @code{-p STR} @tab @code{--period} @tab Set report period to STR -@item @code{ } @tab @code{--period-sort} @tab Sort postings within each period -@item @code{-C} @tab @code{--cleared} @tab Display only cleared postings -@item @code{} @tab @code{--dc} @tab Display register or balance in debit/credit format -@item @code{-U} @tab @code{--uncleared} @tab Display only uncleared postings -@item @code{-R} @tab @code{--real} @tab Display only real postings -@item @code{-L} @tab @code{--actual} @tab Displays only actual postings, not automated -@item @code{-r} @tab @code{--related} @tab Display related postings -@item @code{} @tab @code{--budget} @tab Display how close your postings meet your budget -@item @code{} @tab @code{--add-budget} @tab Shows un-budgeted postings -@item @code{} @tab @code{--unbudgeted} @tab Shows only un-budgeted postings -@item @code{} @tab @code{--forecast} @tab Project balances into the future -@item @code{-l EXPR} @tab @code{--limit EXPR} @tab Limits postings in calculations -@item @code{-t EXPR} @tab @code{--amount} @tab Change value expression reported in register report -@item @code{-T EXPR} @tab @code{--total} @tab Change the value expression used for ``totals'' column in register and balance reports -@end multitable - -@node Error Checking and Calculation Options, Output Customization Quick Reference, Report Filtering Quick Reference, Command Line Quick Reference -@subsection Error Checking and Calculation Options - -@multitable @columnfractions .1 .25 .65 -@item @strong{Short} @tab @strong{Long} @tab @strong{Description} -@item @code{} @tab @code{--strict} @tab accounts, tags or commodities not previously declared will cause warnings -@item @code{} @tab @code{--pedantic} @tab accounts, tags or commodities not previously declared will cause errors -@item @code{} @tab @code{--check-payees} @tab enable strict and pedantic checking for payees as well as accounts, commodities and tags. -@item @code{} @tab @code{--immediate} @tab instructs ledger to evaluate calculations immediately rather than lazily -@end multitable - - -@node Output Customization Quick Reference, Grouping Options, Error Checking and Calculation Options, Command Line Quick Reference -@subsection Output Customization -@multitable @columnfractions .15 .4 .45 -@item @strong{Short} @tab @strong{Long} @tab @strong{Description} -@item @code{-n} @tab @code{--collapse} @tab Collapse transactions with multiple postings -@item @code{-s} @tab @code{--subtotal} @tab Report register as a single subtotal -@item @code{-P} @tab @code{--by-payee} @tab Report subtotals by payee -@item @code{-E} @tab @code{--empty} @tab Include empty accounts in report -@item @code{-W} @tab @code{--weekly} @tab Report posting totals by week -@item @code{-Y} @tab @code{--yearly} @tab Report posting totals by year -@item @code{} @tab @code{--dow} @tab report Posting totals by day of week -@item @code{-S EXPR} @tab @code{--sort EXPR} @tab Sorts a report using @code{EXPR} -@item @code{-w} @tab @code{--wide} @tab Assume 132 columns instead of 80 -@item @code{} @tab @code{--head N} @tab Report the first N postings -@item @code{} @tab @code{--tail N} @tab Report the last N postings -@item @code{} @tab @code{--pager prog} @tab Direct output @code{prog} pager program -@item @code{-A} @tab @code{--average} @tab Reports average posting value -@item @code{-D} @tab @code{--deviation} @tab Reports each posting deviation from the average -@item @code{-%} @tab @code{--percent} @tab Show subtotals in the balance report as percentages -@c @item @code{} @tab @code{--totals} @tab Include running total in the @code{xml} report -@item @code{} @tab @code{--pivot TAG} @tab produce a pivot table of the tag type specified -@item @code{-j} @tab @code{--amount-data} @tab Show only date and value column -@item @code{-J} @tab @code{--total-data} @tab Show only dates and totals -@item @code{-d EXPR} @tab @code{--display EXPR} @tab Limit only the display of certain postings -@item @code{-y STR} @tab @code{--date-format STR} @tab Change the basic date format used in reports -@item @code{-F STR} @tab @code{--format STR} @tab Set reporting format -@item @code{} @tab @code{--balance-format STR} @tab -@item @code{} @tab @code{--register-format STR} @tab -@item @code{-j register} @tab @code{--plot-amount-format STR} @tab format the output of a amount plots -@item @code{-J register} @tab @code{--plot-total-format STR} @tab format the output of a total plot -@item @code{} @tab @code{--prices-format STR} @tab -@item @code{-w register} @tab @code{--wide-register-format STR} @tab -@item @code{} @tab @code{--anon} @tab Print the ledger register with anonymized accounts and payees, useful for filing bug reports -@end multitable - -@node Grouping Options, Commodity Reporting Quick Reference, Output Customization Quick Reference, Command Line Quick Reference -@subsection Grouping Options -@multitable @columnfractions .1 .25 .65 -@item @strong{Short} @tab @strong{Long} @tab @strong{Description} -@item @code{-P} @tab @code{--by-payee} @tab Group postings by common payee names -@item @code{-D} @tab @code{--daily} @tab Group postings by day -@item @code{-W} @tab @code{--weekly} @tab Group postings by week -@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{} @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 - -@node Commodity Reporting Quick Reference, , Grouping Options, Command Line Quick Reference -@subsection Commodity Reporting - -@multitable @columnfractions .1 .25 .65 -@item @strong{Short} @tab @strong{Long} @tab @strong{Description} -@item @code{} @tab @code{--price-db FILE} @tab Use @file{FILE} for retrieving stored commodity prices -@item @code{-L MINS} @tab @code{--price-exp MINS} @tab Set expected freshness of prices in minutes -@item @code{-Q} @tab @code{--download} @tab Download quotes using @code{getquote} -@item @code{} @tab @code{--getquote} @tab Sets path to a user defined script to download commodity prices. -@item @code{-O} @tab @code{--quantity} @tab Report commodity totals without conversion -@item @code{-B} @tab @code{--basis} @tab Report cost basis -@item @code{-V} @tab @code{--market} @tab Report last known market value -@item @code{-G} @tab @code{--gain} @tab Report net gain loss for commodities that have a price history -@end multitable @node Principles of Accounting, Keeping a Journal, Ledger Tutorial , Top @chapter Principles of Accounting with Ledger @@ -1382,6 +1240,7 @@ posting. * Currency and Commodities:: * Keeping it Consistent:: * Journal Format:: +* Converting from other formats:: * Archiving Previous Years :: * Using Emacs:: @end menu @@ -1719,6 +1578,145 @@ its amount is null. @node Complete control over commodity pricing, , Fixing Lot Prices, Currency and Commodities @subsection Complete control over commodity pricing +Ledger allows you to have very detailed control over how your +commodities are valued. You can fine tune the results given using the +@code{--market} or @code{--exchange} options. There are now several +points of interception, you can specify the valuation method: +@enumerate + @item on a commodity itself + @item on a posting, via metadata (affect is largely the same as #1) + @item on an xact, which then applies to all postings in that xact + @item on any posting via an automated transaction + @item on a per-account basis + @item on a per-commodity basis + @item by changing the journal default of @code{market} +@end enumerate + +Fixated pricing (such as @code{@{=$20@})} still plays a role in this scheme. As far as +valuation goes, it's shorthand for writing @code{((s,d,t -> market($20,d,t)))}. + + +A valuation function receives three arguments: + +@table @code +@item source + A string identifying the commodity whose price is being asked for + (example: "EUR") +@item date + The reference date the price should be relative. +@item target +A string identifying the ``target'' commodity, or the commodity the + returned price should be in. This argument is null if @code{--market} + was used instead of @code{--exchange}. +@end table + +The valuation function should return an amount. If you've written your +function in Python, you can return something like @code{Amount("$100")}. If the +function returns an explicit value, that value is always used, regardless +of the commodity, the date, or the desired target commodity. For example, + +@smallexample +define myfunc_seven(s, d, t) = 7 EUR +@end smallexample + +In order to specify a fixed price, but still valuate that price into the +target commodity, use something like this: +@smallexample +define myfunc_five(s, d, t) = market(5 EUR, d, t) +@end smallexample + +The @code{value} directive sets the valuation used for all commodities +used in the rest of the data stream. This is the fallback, if nothing +more specific is found. +@smallexample +value myfunc_seven +@end smallexample + +You can set a specific valuation function on a per-commodity basis. +Instead of defining a function, you can also pass a lambda. +@smallexample +commodity $ + value s, d, t -> 6 EUR +@end smallexample + +Each account can also provide a default valuation function for any +commodities transferred to that account. + +@smallexample +account Expenses:Food5 + value myfunc_five +@end smallexample + +The metadata field @code{Value}, if found, overrides the valuation function +on a transaction-wide or per-posting basis. + +@smallexample += @@XACT and Food + ; Value:: 8 EUR + (Equity) $1 + += @@POST and Dining + (Expenses:Food9) $1 + ; Value:: 9 EUR +@end smallexample + +Lastly, you can specify the valuation function/value for any specific +amount using the @code{(( ))} commodity annotation. + +@smallexample +2012-03-02 KFC + Expenses:Food2 $1 ((2 EUR)) + Assets:Cash2 + +2012-03-03 KFC + Expenses:Food3 $1 + ; Value:: 3 EUR + Assets:Cash3 + +2012-03-04 KFC + ; Value:: 4 EUR + Expenses:Food4 $1 + Assets:Cash4 + +2012-03-05 KFC + Expenses:Food5 $1 + Assets:Cash5 + +2012-03-06 KFC + Expenses:Food6 $1 + Assets:Cash6 + +2012-03-07 KFC + Expenses:Food7 1 CAD + Assets:Cas7 + +2012-03-08 XACT + Expenses:Food8 $1 + Assets:Cash8 + +2012-03-09 POST + Expenses:Dining9 $1 + Assets:Cash9 +@end smallexample + + +@smallexample +ledger reg -V food +12-Mar-02 KFC Expenses:Food2 2 EUR 2 EUR +12-Mar-03 KFC -1 EUR 1 EUR + Expenses:Food3 3 EUR 4 EUR +12-Mar-04 KFC -2 EUR 2 EUR + Expenses:Food4 4 EUR 6 EUR +12-Mar-05 KFC -3 EUR 3 EUR + Expenses:Food5 5 EUR 8 EUR +12-Mar-06 KFC -4 EUR 4 EUR + Expenses:Food6 6 EUR 10 EUR +12-Mar-07 KFC Expenses:Food7 7 EUR 17 EUR +12-Mar-08 XACT Expenses:Food8 8 EUR 25 EUR +12-Mar-09 POST (Expenses:Food9) 9 EUR 34 EUR +@end smallexample + + @node Keeping it Consistent, Journal Format, Currency and Commodities, Keeping a Journal @section Keeping it Consistent @@ -1750,7 +1748,7 @@ ledger accounts >> Accounts.dat @noindent You will have to edit this file to add the @samp{account} directive. -@node Journal Format, Archiving Previous Years , Keeping it Consistent, Keeping a Journal +@node Journal Format, Converting from other formats, Keeping it Consistent, Keeping a Journal @section Journal Format The ledger file format is quite simple, but also very flexible. It @@ -2238,7 +2236,21 @@ timelog files. See the timeclock's documentation for more info on the syntax of its timelog files. @end table -@node Archiving Previous Years , Using Emacs, Journal Format, Keeping a Journal +@node Converting from other formats, Archiving Previous Years , Journal Format, Keeping a Journal +@section Converting from other formats +There are numerous tools to help convert various formats to a Ledger +file. Most banks will generate a commas separated value file that can +easily be parsed into Ledger format using one of those tools. Some of the more popular tools are: +@itemize +@item @code{icsv2ledger} +@item @code{csvToLedger} +@item @code{CSV2Ledger} +@end itemize +@noindent Directly pulling information from banks is outside the scope of Ledger's +function. + + +@node Archiving Previous Years , Using Emacs, Converting from other formats, Keeping a Journal @section Archiving Previous Years @@ -4882,11 +4894,12 @@ FIX THIS ENTRY @menu * Basic Usage:: +* Command Line Quick Reference:: * Detailed Options Description:: * Period Expressions:: @end menu -@node Basic Usage, Detailed Options Description, Command-line Syntax, Command-line Syntax +@node Basic Usage, Command Line Quick Reference, Command-line Syntax, Command-line Syntax @section Basic Usage This chapter describes Ledger's features and options. You may wish to @@ -4927,8 +4940,148 @@ There are many, many command options available with the However, none of them are required to use the basic reporting commands. +@node Command Line Quick Reference, Detailed Options Description, Basic Usage, Command-line Syntax +@section Command Line Quick Reference + +@menu +* Reporting Commands Quick Reference:: +* Basic Options Quick Reference:: +* Report Filtering Quick Reference:: +* Error Checking and Calculation Options:: +* Output Customization Quick Reference:: +* Grouping Options:: +* Commodity Reporting Quick Reference:: +@end menu + +@node Reporting Commands Quick Reference, Basic Options Quick Reference, Command Line Quick Reference, Command Line Quick Reference +@subsection Reporting Commands +@multitable @columnfractions .2 .8 +@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{xml} @tab Produce XML output of the register command +@item @code{emacs} @tab Produce Emacs lisp output +@item @code{equity} @tab Print account balances as transactions +@item @code{prices} @tab Print price history for matching commodities +@item @code{pricedb} @tab Print price history for matching commodities in ledger readable format +@item @code{xact} @tab Used to generate transactions based on previous postings +@end multitable + +@node Basic Options Quick Reference, Report Filtering Quick Reference, Reporting Commands Quick Reference, Command Line Quick Reference +@subsection Basic Options +@multitable @columnfractions .1 .25 .65 +@item @strong{Short} @tab @strong{Long} @tab @strong{Description} +@item @code{-h} @tab @code{--help} @tab prints summary of all options +@item @code{-v} @tab @code{--version} @tab prints version of ledger executable +@item @code{-f FILE} @tab @code{--file FILE} @tab read @file{FILE} as a ledger file +@item @code{-o FILE} @tab @code{--output FILE} @tab redirects output to @file{FILE} +@item @code{-i FILE} @tab @code{--init-file FILE} @tab specify options file +@item @code{-a NAME} @tab @code{--account NAME} @tab specify default account name for QIF file postings +@end multitable + +@node Report Filtering Quick Reference, Error Checking and Calculation Options, Basic Options Quick Reference, Command Line Quick Reference +@subsection Report Filtering +@multitable @columnfractions .1 .25 .65 +@item @strong{Short} @tab @strong{Long} @tab @strong{Description} +@item @code{-c} @tab @code{--current} @tab Display transaction on or before the current date +@item @code{-b DATE} @tab @code{--begin DATE} @tab Begin reports on or after @code{DATE} +@item @code{-e DATE} @tab @code{--end DATE} @tab Limits end date of transactions for report +@item @code{-p STR} @tab @code{--period} @tab Set report period to STR +@item @code{ } @tab @code{--period-sort} @tab Sort postings within each period +@item @code{-C} @tab @code{--cleared} @tab Display only cleared postings +@item @code{} @tab @code{--dc} @tab Display register or balance in debit/credit format +@item @code{-U} @tab @code{--uncleared} @tab Display only uncleared postings +@item @code{-R} @tab @code{--real} @tab Display only real postings +@item @code{-L} @tab @code{--actual} @tab Displays only actual postings, not automated +@item @code{-r} @tab @code{--related} @tab Display related postings +@item @code{} @tab @code{--budget} @tab Display how close your postings meet your budget +@item @code{} @tab @code{--add-budget} @tab Shows un-budgeted postings +@item @code{} @tab @code{--unbudgeted} @tab Shows only un-budgeted postings +@item @code{} @tab @code{--forecast} @tab Project balances into the future +@item @code{-l EXPR} @tab @code{--limit EXPR} @tab Limits postings in calculations +@item @code{-t EXPR} @tab @code{--amount} @tab Change value expression reported in register report +@item @code{-T EXPR} @tab @code{--total} @tab Change the value expression used for ``totals'' column in register and balance reports +@end multitable + +@node Error Checking and Calculation Options, Output Customization Quick Reference, Report Filtering Quick Reference, Command Line Quick Reference +@subsection Error Checking and Calculation Options -@node Detailed Options Description, Period Expressions, Basic Usage, Command-line Syntax +@multitable @columnfractions .1 .25 .65 +@item @strong{Short} @tab @strong{Long} @tab @strong{Description} +@item @code{} @tab @code{--strict} @tab accounts, tags or commodities not previously declared will cause warnings +@item @code{} @tab @code{--pedantic} @tab accounts, tags or commodities not previously declared will cause errors +@item @code{} @tab @code{--check-payees} @tab enable strict and pedantic checking for payees as well as accounts, commodities and tags. +@item @code{} @tab @code{--immediate} @tab instructs ledger to evaluate calculations immediately rather than lazily +@end multitable + + +@node Output Customization Quick Reference, Grouping Options, Error Checking and Calculation Options, Command Line Quick Reference +@subsection Output Customization +@multitable @columnfractions .15 .4 .45 +@item @strong{Short} @tab @strong{Long} @tab @strong{Description} +@item @code{-n} @tab @code{--collapse} @tab Collapse transactions with multiple postings +@item @code{-s} @tab @code{--subtotal} @tab Report register as a single subtotal +@item @code{-P} @tab @code{--by-payee} @tab Report subtotals by payee +@item @code{-E} @tab @code{--empty} @tab Include empty accounts in report +@item @code{-W} @tab @code{--weekly} @tab Report posting totals by week +@item @code{-Y} @tab @code{--yearly} @tab Report posting totals by year +@item @code{} @tab @code{--dow} @tab report Posting totals by day of week +@item @code{-S EXPR} @tab @code{--sort EXPR} @tab Sorts a report using @code{EXPR} +@item @code{-w} @tab @code{--wide} @tab Assume 132 columns instead of 80 +@item @code{} @tab @code{--head N} @tab Report the first N postings +@item @code{} @tab @code{--tail N} @tab Report the last N postings +@item @code{} @tab @code{--pager prog} @tab Direct output @code{prog} pager program +@item @code{-A} @tab @code{--average} @tab Reports average posting value +@item @code{-D} @tab @code{--deviation} @tab Reports each posting deviation from the average +@item @code{-%} @tab @code{--percent} @tab Show subtotals in the balance report as percentages +@c @item @code{} @tab @code{--totals} @tab Include running total in the @code{xml} report +@item @code{} @tab @code{--pivot TAG} @tab produce a pivot table of the tag type specified +@item @code{-j} @tab @code{--amount-data} @tab Show only date and value column +@item @code{-J} @tab @code{--total-data} @tab Show only dates and totals +@item @code{-d EXPR} @tab @code{--display EXPR} @tab Limit only the display of certain postings +@item @code{-y STR} @tab @code{--date-format STR} @tab Change the basic date format used in reports +@item @code{-F STR} @tab @code{--format STR} @tab Set reporting format +@item @code{} @tab @code{--balance-format STR} @tab +@item @code{} @tab @code{--register-format STR} @tab +@item @code{-j register} @tab @code{--plot-amount-format STR} @tab format the output of a amount plots +@item @code{-J register} @tab @code{--plot-total-format STR} @tab format the output of a total plot +@item @code{} @tab @code{--prices-format STR} @tab +@item @code{-w register} @tab @code{--wide-register-format STR} @tab +@item @code{} @tab @code{--anon} @tab Print the ledger register with anonymized accounts and payees, useful for filing bug reports +@end multitable + +@node Grouping Options, Commodity Reporting Quick Reference, Output Customization Quick Reference, Command Line Quick Reference +@subsection Grouping Options +@multitable @columnfractions .1 .25 .65 +@item @strong{Short} @tab @strong{Long} @tab @strong{Description} +@item @code{-P} @tab @code{--by-payee} @tab Group postings by common payee names +@item @code{-D} @tab @code{--daily} @tab Group postings by day +@item @code{-W} @tab @code{--weekly} @tab Group postings by week +@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{} @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 + +@node Commodity Reporting Quick Reference, , Grouping Options, Command Line Quick Reference +@subsection Commodity Reporting + +@multitable @columnfractions .1 .25 .65 +@item @strong{Short} @tab @strong{Long} @tab @strong{Description} +@item @code{} @tab @code{--price-db FILE} @tab Use @file{FILE} for retrieving stored commodity prices +@item @code{-L MINS} @tab @code{--price-exp MINS} @tab Set expected freshness of prices in minutes +@item @code{-Q} @tab @code{--download} @tab Download quotes using @code{getquote} +@item @code{} @tab @code{--getquote} @tab Sets path to a user defined script to download commodity prices. +@item @code{-O} @tab @code{--quantity} @tab Report commodity totals without conversion +@item @code{-B} @tab @code{--basis} @tab Report cost basis +@item @code{-V} @tab @code{--market} @tab Report last known market value +@item @code{-G} @tab @code{--gain} @tab Report net gain loss for commodities that have a price history +@end multitable + +@node Detailed Options Description, Period Expressions, Command Line Quick Reference, Command-line Syntax @section Detailed Option Description @menu @@ -4962,7 +5115,7 @@ database. Displays the info page for ledger. @item --init-file -Specifies the location of the init file @file{.ledgerrc} +Specifies the location of the init file. The default is @file{~/.ledgerrc} @item --options Display the options in effect for this Ledger invocation, along with @@ -5095,15 +5248,16 @@ difference between these scopes. Ledger 3.0 contains provisions for GUIs, which would make use of the different scopes by keeping an instance of Ledger running in the background and running multiple sessions with multiple reports per session. -@code{--abbrev-len } Sets the minimum + +@table @code +@item --abbrev-len +Sets the minimum length an account can be abbreviated to if it doesn't fit inside the @code{account-width}. If @code{abbrev-len} is zero, then the account name will be truncated on the right. If @code{abbrev-len} is greater than @code{account-width} then the account will be truncated on the left, with no shortening of the account names in order to fit into the desired width. - -@table @code @item --account Prepend @code{} to all accounts reported. That is, the option @code{--account Personal} would tack @@ -5515,16 +5669,14 @@ Suppress the output of group titles Suppress printing the final total line in a balance report. @item --now - -FIX THIS ENTRY +Define the current date in case to you to do calculate in the past or future using @code{--current} @item --only FIX THIS ENTRY -@item --output - -FIX THIS ENTRY +@item --output +Redriect the output of ledger to the file defined in @file{PATH}. @item --pager @@ -5667,13 +5819,11 @@ report only the last entries. Only useful ona register report. FIX THIS ENTRY -@item --total - -FIX THIS ENTRY +@item --total +Define a vlaue expression used to calulate the total in reports. @item --total-width - -FIX THIS ENTRY +Set the width of the total field in the register report. @item --truncate @@ -5685,7 +5835,7 @@ FIX THIS ENTRY @item --uncleared -FIX THIS ENTRY +Use only uncleared transactions in calculations and reports. @item --unrealized-gains @@ -5700,8 +5850,7 @@ FIX THIS ENTRY FIX THIS ENTRY @item --unround - -FIX THIS ENTRY +Perform all calculations without rounding and display results to full precision. @item --weekly @@ -7938,11 +8087,16 @@ need to create sums of multiple commodities, use a Balance. For example: @node Major Changes from version 2.6, Example Data File, Extending with Python, Top @chapter Major Changes from version 2.6 +@itemize +@item OFX support has been removed from Ledger 3.0 +@item single character value expressions are deprecated and should be changed to the new value expressions available in 3.0 +@end itemize + @node Example Data File, Miscellaneous Notes, Major Changes from version 2.6, Top @appendix Example Journal File: drewr.dat The following journal file is included with the source distribution of ledger. It is called @file{drewr.dat} and exhibits many ledger - features, include automatic and virtual transactions, + features, include automatic and virtual transactions, @smallexample ; -*- ledger -*- @@ -8045,6 +8199,7 @@ ledger register Checking --sort d -d 'd>[2011/04/01]' until 2011/05/25 (Liabilities:Tithe Owed) -1.0 @end smallexample + @node Concept Index, Command Index, Miscellaneous Notes, Top @unnumbered Concept Index -- cgit v1.2.3 From 8c7ac50fd8e29a0c2edf172f4bfa020aebdd2f7b Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 10 Oct 2012 21:21:00 -0700 Subject: formatting and grammar cleanup --- doc/ledger3.texi | 184 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 100 insertions(+), 84 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 08be7551..4cc28f43 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -4054,19 +4054,19 @@ file whose formatting has gotten out of hand. @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 +The @command{csv} command will output print out the desired ledger transactions in +a csv format suitable for import into other programs. You can specify +the transactions 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 +The @code{convert} command parses a comma separated value +(csv) file and outputs Ledger transactions. Many banks offer csv file +downloads. Unfortunately the file formats, aside the from commas, are +all different. The ledger @code{convert} command tries to help as much as it can. Your banks csv files will have fields in different orders from other @@ -4277,12 +4277,12 @@ financial state. Eventually, babel will support passing arguments to currently. Instead, we can use the concepts of literary programming, as implemented by the noweb features of babel, to help us. -@subsubheading Multiple Ledger source blocks with noweb +@subsubheading Multiple Ledger source blocks with @command{noweb} -The noweb feature of babel allows us to expand references to other code -blocks within a code block. For Ledger, this can be used to group -transactions according to type, say, and then bring various sets of -transactions together to generate reports. +The @command{noweb} feature of babel allows us to expand references to +other code blocks within a code block. For Ledger, this can be used to +group transactions according to type, say, and then bring various sets +of transactions together to generate reports. Using the same transactions used above, we could consider splitting these into expenses and income, as follows: @@ -4342,9 +4342,9 @@ transactions. The overall balance of your account and expenditure with a breakdown according to category is specified by passing the :cmdline bal argument -to Ledger. This code block can now be evaluated (C-c C-c) and the +to Ledger. This code block can now be evaluated (@code{C-c C-c}) and the results generated by incorporating the transactions referred to by the -<> and <>= lines. +@code{<>} and @code{<>} lines. @smallexample #+name: balance #+begin_src ledger :cmdline bal :noweb yes @@ -4359,7 +4359,7 @@ results generated by incorporating the transactions referred to by the @end smallexample If you want a more detailed breakdown of where your money is and where -it has been spent, you can specify the -s flag (i.e. :cmdline -s bal) to +it has been spent, you can specify the -s flag (i.e. @code{:cmdline -s bal}) to tell Ledger to include sub-accounts in the report. @smallexample @@ -4384,7 +4384,7 @@ tell Ledger to include sub-accounts in the report. You can also generate a monthly register (the reg command) by executing the following src block. This presents a summary of transactions for -each monthly period (the -M argument) with a running total in the final +each monthly period (the @code{-M} argument) with a running total in the final column (which should be 0 at the end if all the entries are correct). @smallexample @@ -4435,12 +4435,12 @@ examples of more complex operations with a ledger. @node The pricemap Command, The xml Command, Emacs org mode, Reports in other Formats @subsection The @code{pricemap} Command -If you have the graphviz graph visualization package installed, ledger +If you have the @code{graphviz} graph visualization package installed, ledger can generate a graph of the relationship between your various commodities. The output file is in the ``dot'' format. This is probably not very interesting, unless you have many different -commdities valued in terms of each other. For example, multiple +commodities valued in terms of each other. For example, multiple currencies and multiples investments valued in those currencies. @node The xml Command, prices and pricedb, The pricemap Command, Reports in other Formats @@ -4595,7 +4595,7 @@ the same data. @node prices and pricedb, , The xml Command, Reports in other Formats -@subsection prices and pricedb +@subsection @code{prices} and @code{pricedb} The @command{prices} command displays the price history for matching commodities. The @option{-A} flag is useful with this report, to @@ -4619,7 +4619,7 @@ database files. @end menu @node accounts, commodities, Reports about your Journals, Reports about your Journals -@subsection accounts +@subsection @code{accounts} The @command{accounts} reports all of the accounts in the journal. Following the command with a regular expression will limit the output to @@ -4627,12 +4627,12 @@ accounts matching the regex. @node commodities, entry and xact, accounts, Reports about your Journals -@subsection commodities +@subsection @command{commodities} Report all commodities present in the journals under consideration. @node entry and xact, payees, commodities, Reports about your Journals -@subsection entry and xact +@subsection @command{entry} and @command{xact} The @code{entry} and @command{xact} commands simplify the creation of new transactions. It works on the principle that 80% of all postings @@ -4686,7 +4686,7 @@ ledger xact 4/9 viva dining "DM 11.50" backwards compatibility with Ledger 2.X. @node payees, , entry and xact, Reports about your Journals -@subsection payees +@subsection @code{payees} The @command{payees} reports all of the unique payees in the journal. To filter the payees displayed you must use the prefix: @smallexample @@ -4711,18 +4711,18 @@ macbook-2:$ @end menu @node echo, reload, Developer Commands, Developer Commands -@subsection echo +@subsection @command{echo} This command simply echos its argument back to the output. @node reload, source, echo, Developer Commands -@subsection reload +@subsection @command{reload} Forces ledger to reload any journal files. This function exists to support external programs controlling a running ledger process and does nothing for a command line user. @node source, Debug Options, reload, Developer Commands -@subsection source +@subsection @command{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 return success if no errors are @@ -4734,16 +4734,19 @@ found. These options are primarily for Ledger developers, but may be of some use to a user trying something new. - @option{--args-only} ignore init +@table @code + @item --args-only +ignore init files and environment variables for the ledger run. -@option{--verify} enable additional assertions during run-time. This -causes a significant slowdown. When combined with @option{--debug} -ledger will produce memory trace information. +@item --verify +enable additional assertions during run-time. This causes a significant +slowdown. When combined with @code{--debug} ledger will produce +memory trace information. -@option{--debug "argument"} If Ledger has been built with debug options -this will provide extra data during the run. The following are the -available arguments to debug: +@item --debug "argument" +If Ledger has been built with debug options this will provide extra data +during the run. The following are the available arguments to debug: @multitable @columnfractions .32 .43 .27 @item @code{account.display} @tab @code{expr.calc.when} @tab @code{org.next_amount} @@ -4772,7 +4775,7 @@ available arguments to debug: @item @code{expr.calc} @tab @code{option.names} @end multitable -@option{--trace INTEGER_TRACE_LEVEL} +@item --trace INTEGER_TRACE_LEVEL Enable tracing. The integer specifies the level of trace desired: @multitable @columnfractions .3 .7 @item @code{LOG_OFF} @tab 0 @@ -4789,15 +4792,16 @@ Enable tracing. The integer specifies the level of trace desired: @item @code{LOG_ALL} @tab 11 @end multitable -@option{--verbose} +@item --verbose Print detailed information on the execution of Ledger. -@option{--version} +@item --version Print version information and exit. +@end table @node Pre-commands, , Debug Options, Developer Commands @subsection Pre-Commands -Pre-commands are useful when you aren't sure how a command or option +Pre-commands are useful when you aren't sure how a command or option will work. @table @code @item args @@ -4821,7 +4825,8 @@ it against a model transaction. Print details of how ledger uses the given formatting description and apply it against a model transaction. @item generate -FIX THIS ENTRY +Randomly generates syntactically valid Ledger data from a seed. Used by the +GenerateTests harness for development testing @item parse Print details of how ledger uses the given value expression description and apply it against a model transaction. @@ -4885,7 +4890,8 @@ model transaction: true @end smallexample @item template -FIX THIS ENTRY +Shows the insertion template that a "draft" or "xact" sub-command generates. +This is a debugging command. @end table @node Command-line Syntax, Budgeting and Forecasting, Reporting Commands, Top @@ -5032,21 +5038,21 @@ commands. @item @code{-w} @tab @code{--wide} @tab Assume 132 columns instead of 80 @item @code{} @tab @code{--head N} @tab Report the first N postings @item @code{} @tab @code{--tail N} @tab Report the last N postings -@item @code{} @tab @code{--pager prog} @tab Direct output @code{prog} pager program +@item @code{} @tab @code{--pager PATH} @tab Direct output to @code{PATH} pager program @item @code{-A} @tab @code{--average} @tab Reports average posting value @item @code{-D} @tab @code{--deviation} @tab Reports each posting deviation from the average @item @code{-%} @tab @code{--percent} @tab Show subtotals in the balance report as percentages @c @item @code{} @tab @code{--totals} @tab Include running total in the @code{xml} report @item @code{} @tab @code{--pivot TAG} @tab produce a pivot table of the tag type specified -@item @code{-j} @tab @code{--amount-data} @tab Show only date and value column -@item @code{-J} @tab @code{--total-data} @tab Show only dates and totals -@item @code{-d EXPR} @tab @code{--display EXPR} @tab Limit only the display of certain postings +@item @code{-j} @tab @code{--amount-data} @tab Show only date and value column to format the output for plots +@item @tab @code{--plot-amount-format STR} @tab specify the format for the plot output +@item @code{-J} @tab @code{--total-data} @tab Show only dates and totals to format the output for plots +@item @tab @code{--plot-total-format STR} @tab specify the format for the plot output +@item @code{-d EXPR} @tab @code{--display EXPR} @tab Display only posting that meet the criteris in the EXPR @item @code{-y STR} @tab @code{--date-format STR} @tab Change the basic date format used in reports @item @code{-F STR} @tab @code{--format STR} @tab Set reporting format @item @code{} @tab @code{--balance-format STR} @tab @item @code{} @tab @code{--register-format STR} @tab -@item @code{-j register} @tab @code{--plot-amount-format STR} @tab format the output of a amount plots -@item @code{-J register} @tab @code{--plot-total-format STR} @tab format the output of a total plot @item @code{} @tab @code{--prices-format STR} @tab @item @code{-w register} @tab @code{--wide-register-format STR} @tab @item @code{} @tab @code{--anon} @tab Print the ledger register with anonymized accounts and payees, useful for filing bug reports @@ -5196,7 +5202,7 @@ Would convert the @file{Export.csv} file to ledger format, assuming the the dates in the CSV file are like 12/23/2009 (@pxref{Date and Time Format Codes}). -@item --master-account +@item --master-account Prepends all account names with the argument. @smallexample 21:51:39 ~/ledger (next)> ledger -f test/input/drewr3.dat bal --master-account HUMBUG @@ -5549,13 +5555,11 @@ correctly. force Ledger to paginate its output. -@item --forecast-while - -FIX THIS ENTRY - -@item --forecast-years +@item --forecast-while +Continue forecasting while @code{} is true. -FIX THIS ENTRY +@item --forecast-years +Forecast at most @code{N} years in the future. @item --format @@ -5563,11 +5567,12 @@ use the given format string to print output. @item --gain -report on gains using the latest available prices . +report on gains using the latest available prices. @item --generated - -ASK JOHN +Include auto-generated postings (such as those from automated transactions) +in the report, in cases where you normally wouldn't want +them. @item --group-by group transaction together in the register @@ -5640,13 +5645,13 @@ Report the date and price at which each commodity was purchased in a balance rep Use the latest market value for all commodities. -@item --meta +@item --meta -FIX THIS ENTRY +In the register report, prepend the transaction with the value of the given tag. @item --meta-width -FIX THIS ENTRY +Specify the width of the Meta column used for the @code{--meta} options. @item --monthly @@ -5657,8 +5662,8 @@ synonymn for @code{--period "monthly"} suppress any color TTY output. @item --no-rounding - -FIX THIS ENTRY +Don't output postings. Note that this will cause the running total +to often not add up! It's main use is for @code{-j} and @code{-J} reports. @item --no-titles @@ -5673,7 +5678,8 @@ Define the current date in case to you to do calculate in the past or future usi @item --only -FIX THIS ENTRY +This is a postings predicate that applies after certain +transforms have been executed, such as periodic gathering. @item --output Redriect the output of ledger to the file defined in @file{PATH}. @@ -5700,7 +5706,7 @@ Use only postings that are marked pending Calculate the percentage value of each account in a blance reports. Only works for account that have a single commoditiy. -@item --period +@item --period Define a period expression the sets the time period during which transactions are to be accounted. For a register report only th @@ -5708,7 +5714,7 @@ transactions that satisfy the period expression with be displayed. For a balance report only those transactions will be accounted in the final balances. -@item --pivot +@item --pivot Produce a balance pivot report ``around'' the given tag. For example, if you have multiple cars and track each fuel purchase in @@ -5726,6 +5732,7 @@ ledger bal Fuel --pivot "Car" --period "this year" $ 3533.95 @end smallexample +@xref{Metadata values}. @item --plot-amount-format Define the output format for a amount data plot. @xref{Visualizing with Gnuplot}. @@ -5744,8 +5751,7 @@ Reserve @code{N} spaces at the beginning of each line of the output @item --price - -FIX THIS ENTRY +use the price of the commodity purchase for performing calculations @item --quantity @@ -5757,7 +5763,10 @@ Synonym for @code{--period "quarterly"}. @item --raw -FIX THIS ENTRY +In the print report, show transactions using the exact same syntax as +specified by the user in their data file. Don't do any massaging or +interpreting. Can be useful for minor cleanups, like just aligning +amounts. @item --real Account using only real transactions ignoring virtual @@ -5788,7 +5797,7 @@ FIX THIS ENTRY @item --seed -FIX THIS ENTRY +Sets the random seed for the @code{generate} command. Used as part of development testing. @item --sort-all @@ -5826,8 +5835,11 @@ Define a vlaue expression used to calulate the total in reports. Set the width of the total field in the register report. @item --truncate - -FIX THIS ENTRY +Indicates how truncation should happen when the contents of columns +exceed their width. Valid arguments are @code{leading}, @code{middle}, +and @code{trailing}. The default is smarter than any of these three, as +it considers sub-names within the account name (that style is called +``abbreviate''. @item --unbudgeted @@ -5933,7 +5945,8 @@ report, in ways other than just using regular expressions: displays only transactions occurring on or before the current date. @item --begin DATE -@item -b DATE constrains the report to transactions on or after +@item -b DATE +constrains the report to transactions on or after @var{DATE}. Only transactions after that date will be calculated, which means that the running total in the balance report will always start at zero with the first matching transaction. (Note: This is different from @@ -5945,7 +5958,8 @@ constrains the report so that transactions on or after @var{DATE} are not considered. The ending date is inclusive. @item --period STR -@item -p STR sets the reporting period to @var{STR}. This will subtotal +@item -p STR +sets the reporting period to @var{STR}. This will subtotal all matching transactions within each period separately, making it easy to see weekly, monthly, quarterly, etc., posting totals. A period string can even specify the beginning and end of the report range, using @@ -6723,8 +6737,8 @@ ledger --forecast "d<[2010]" bal ^assets ^liabilities @node Value Expressions, Format Strings, Budgeting and Forecasting, Top @chapter Value Expressions -Value expressions are an expression language used by Ledger to -calculate values used by the program for many different purposes: +Ledger uses value expressions to make +calculations for many different purposes: @enumerate @item @@ -6739,19 +6753,21 @@ In the matching criteria used by automated postings. @end enumerate Value expressions support most simple math and logic operators, in -addition to a set of one letter functions and variables. A function's -argument is whatever follows it. The following is a display predicate -that I use with the @command{balance} command: +addition to a set of functions and variables. -@smallexample -ledger -d /^Liabilities/?T<0:UT>100 balance -@end smallexample +@c A function's +@c argument is whatever follows it. The following is a display predicate +@c that I use with the @command{balance} command: + +@c @smallexample +@c ledger -d /^Liabilities/?T<0:UT>100 balance +@c @end smallexample -The effect is that account totals are displayed only if: 1) A -Liabilities account has a total less than zero; or 2) the absolute -value of the account's total exceeds 100 units of whatever commodity -contains. If it contains multiple commodities, only one of them must -exceed 100 units. +@c The effect is that account totals are displayed only if: 1) A +@c Liabilities account has a total less than zero; or 2) the absolute +@c value of the account's total exceeds 100 units of whatever commodity +@c contains. If it contains multiple commodities, only one of them must +@c exceed 100 units. Display predicates are also very handy with register reports, to constrain which transactions are printed. For example, the following -- cgit v1.2.3 From f1c459b80c43de1d2e1a8ab51f2d91c33b9bd03b Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Fri, 12 Oct 2012 06:56:21 -0700 Subject: Fixed several typos and cleaned up formatting --- doc/ledger3.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 4cc28f43..84f32857 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -235,7 +235,7 @@ $ ledger -f ledger.dat register Bell @end smallexample An important difference between Ledger and other finance packages is -that journal will never alter your input file. You can create and edit +that Ledger will never alter your input file. You can create and edit that file in any way you prefer, but Ledger is only for analyzing the data, not for altering it. -- cgit v1.2.3 From 0d90de44b62274ae761b8d81c754f2c78cd44f56 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Sat, 13 Oct 2012 07:48:00 -0700 Subject: Added more details to the convert command as provide by Johan Klahn --- doc/ledger3.texi | 45 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 84f32857..b429d27e 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -4098,7 +4098,7 @@ line of the file. The fields ledger can recognize are called Delete the account description lines at the top, and replace the first line in the data above with: @smallexample -date,payee,note,amount,,,code, +,date,payee,note,amount,,,code, @end smallexample Then execute ledger like this: @@ -4110,6 +4110,49 @@ 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. + +If there are columns in the bank data you would like to keep in your +ledger data, besides the primary fileds described above, you can name +them in the field descriptor list and Ledger will include them in the +transaction as meta data if it doesn't recognize the field name. For +example, if you want to capture the bank transaction number and it +occurs in the first column of the data use: + + +@smallexample +transid,date,payee,note,amount,,,code, +@end smallexample + +Ledger will include @code{; transid: 767718} in the first transaction is +fromthe file above. + +The @code{convert} command accepts three options, the most important +ones are @code{--invert} which inverts the amount field, and +@code{--account NAME} which you can use to specify the account to +balance against and @code{--rich-data}. When using the rich-data switch +additional metadata is stored as tags. There is, for example, a UUID field. If +an entry with the same UUID tag is already included in the normal ledger +file (specified via -f or $LEDGER_FILE) this entry will not be printed +again. + +You can also use @code{convert} with @code{payee} and @code{account} +directives. First, you can use the @code{payee} and @code{alias} +directive to rewrite the @code{payee} field based on some rules. Then you can +use the account and its @code{payee} directive to specify the account. I use it +like this, for example: + +@smallexample +payee Aldi + alias ^ALDI SUED SAGT DANKE +account Aufwand:Einkauf:Lebensmittel + payee ^(Aldi|Alnatura|Kaufland|REWE)$ +@end smallexample + +Note that it may be necessary for the output of 'ledger convert' to be +passed through 'ledger print' a second time if you want to match on the +new payee field. During the 'ledger convert' run only the original payee +name as specified in the csv data seems to be used. + @node Emacs, Emacs org mode, Comma Separated Variable files, Reports in other Formats @subsection Emacs -- cgit v1.2.3 From c51ad98a6636b054fae1a8b2eca009ed516ee158 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Sat, 13 Oct 2012 08:16:39 -0700 Subject: Fixe emacs command chapter heading --- doc/ledger3.texi | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index b429d27e..aabb9445 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -4038,14 +4038,14 @@ file whose formatting has gotten out of hand. @section Reports in other Formats @menu * Comma Separated Variable files:: -* Emacs:: +* The emacs command:: * Emacs org mode:: * The pricemap Command:: * The xml Command:: * prices and pricedb:: @end menu -@node Comma Separated Variable files, Emacs, Reports in other Formats, Reports in other Formats +@node Comma Separated Variable files, The emacs command, Reports in other Formats, Reports in other Formats @subsection Comma Separated Variable files @menu * The csv command:: @@ -4153,8 +4153,8 @@ passed through 'ledger print' a second time if you want to match on the new payee field. During the 'ledger convert' run only the original payee name as specified in the csv data seems to be used. -@node Emacs, Emacs org mode, Comma Separated Variable files, Reports in other Formats -@subsection Emacs +@node The emacs command, Emacs org mode, Comma Separated Variable files, Reports in other Formats +@subsection The @code{emacs} command The @command{emacs} command outputs results in a form that can be read directly by Emacs Lisp. The format of the @code{sexp} is: @@ -4165,7 +4165,7 @@ directly by Emacs Lisp. The format of the @code{sexp} is: ...) ; list of transactions @end smallexample -@node Emacs org mode, The pricemap Command, Emacs, Reports in other Formats +@node Emacs org mode, The pricemap Command, The emacs command, 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 -- cgit v1.2.3 From 6b5fb0da7372d7f5e48607b3885b8f9b01afa99c Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Fri, 19 Oct 2012 04:00:13 +0200 Subject: Reformatted tables and moved date formatting code section --- doc/ledger3.texi | 1093 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 568 insertions(+), 525 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index aabb9445..531a0870 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -261,7 +261,7 @@ enter these commands: Ledger has a complete online help system based on GNU Info. This manual can be searched directly from the command line using the following options: -@option{ledger --help} bring up this entire manual in your tty. +@code{ledger --help} bring up this entire manual in your tty. 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: @@ -270,8 +270,8 @@ join the Ledger mailing list at the following Web address: http://groups.google.com/group/ledger-cli @end smallexample -@noindent You can also find help at the @samp{#ledger} channel on the IRC server -@samp{irc.freenode.net}. +@noindent You can also find help at the @code{#ledger} channel on the IRC server +@code{irc.freenode.net}. @cindex tutorial @node Ledger Tutorial , Principles of Accounting, Introduction to Ledger, Top @@ -419,14 +419,14 @@ $ ledger -f drewr3.dat register Groceries 11-Jan-19 Grocery Store Expense:Food:Groceries $ 44.00 $ 334.00 @end smallexample -@noindent Which matches the balance reported for the @samp{Groceries} account: +@noindent Which matches the balance reported for the @code{Groceries} account: @smallexample $ ledger -f drewr3.dat balance Groceries $ 334.00 Expenses:Food:Groceries @end smallexample -@noindent If you would like to find transaction to only a certain payee use @samp{payee} or @@: +@noindent If you would like to find transaction to only a certain payee use @code{payee} or @@: @smallexample $ ledger -f drewr3.dat register payee "Organic" 10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50 @@ -445,7 +445,7 @@ $ ledger -f drewr3.dat register payee "Organic" 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 -@samp{cleared} report shows just that (note that the cleared report will +@code{cleared} report shows just that (note that the cleared report will not format correctly for accounts that contain multiple commodities): @smallexample @@ -626,7 +626,7 @@ ledger -M register expenses:auto @end example This assumes, of course, that you use account names like -@samp{Expenses:Auto:Gas} and @samp{Expenses:Auto:Repair}. +@code{Expenses:Auto:Gas} and @code{Expenses:Auto:Repair}. @menu * Tracking reimbursable expenses:: @@ -728,8 +728,8 @@ It's easier shown than said: And now the reimbursements account is paid off, accounts payable is paid off, and $100.00 has been effectively transferred from the company's checking account to your personal checking account. The -money simply ``waited''---in both @samp{Assets:Reimbursements:Company -XYZ}, and @samp{Company XYZ:Accounts Payable:Your Name}---until such +money simply ``waited''---in both @code{Assets:Reimbursements:Company +XYZ}, and @code{Company XYZ:Accounts Payable:Your Name}---until such time as it could be paid off. The value of tracking expenses from both sides like that is that you @@ -773,7 +773,7 @@ apply account Company XYZ end apply account @end smallexample -(Note: The @samp{apply account} above means that all accounts mentioned in +(Note: The @code{apply account} above means that all accounts mentioned in the file are children of that account. In this case it means that all activity in the file relates to Company XYZ). @@ -839,8 +839,8 @@ P 2004/06/21 02:18:02 AAPL $32.91 P 2004/06/21 02:18:02 AU $400.00 @end smallexample -Specify the price history to use with the @option{--price-db} option, -with the @option{-V} option to report in terms of current market +Specify the price history to use with the @code{--price-db} option, +with the @code{-V} option to report in terms of current market value: @example @@ -910,7 +910,7 @@ or days, it should be possible to convert between the various forms. Doing this requires the use of commodity equivalencies. For example, you might have the following two postings, one which -transfers an hour of time into a @samp{Billable} account, and another +transfers an hour of time into a @code{Billable} account, and another which decreases the same account by ten minutes. The resulting report will indicate that fifty minutes remain: @@ -944,13 +944,13 @@ C 1.00 Gb = 1024 Mb C 1.00 Tb = 1024 Gb @end smallexample -Each of these definitions correlates a commodity (such as @samp{Kb}) +Each of these definitions correlates a commodity (such as @code{Kb}) and a default precision, with a certain quantity of another commodity. In the above example, kilobytes are reported with two decimal places of precision and each kilobyte is equal to 1024 bytes. Equivalency chains can be as long as desired. Whenever a commodity -would report as a decimal amount (less than @samp{1.00}), the next +would report as a decimal amount (less than @code{1.00}), the next smallest commodity is used. If a commodity could be reported in terms of a higher commodity without resulting to a partial fraction, then the larger commodity is used. @@ -975,8 +975,8 @@ EverQuest account: Now your EverQuest:Inventory has 3 apples and 5 steaks in it. The amounts are negative, because you are taking @emph{from} Black's Tavern in order to add to your Inventory account. Note that you don't -have to use @samp{Places:Black's Tavern} as the source account. You -could use @samp{EverQuest:System} to represent the fact that you +have to use @code{Places:Black's Tavern} as the source account. You +could use @code{EverQuest:System} to represent the fact that you acquired them online. The only purpose for choosing one kind of source account over another is for generate more informative reports later on. The more you know, the better analysis you can perform. @@ -1029,7 +1029,7 @@ assets is greater than the absolute value of your starting equity, it means you are making money. Clear as mud? Keep thinking about it. Until you figure it out, put -@samp{-Equity} at the end of your balance command, to remove the +@code{-Equity} at the end of your balance command, to remove the confusing figure from the total. @node Dealing with Petty Cash, Working with multiple funds and accounts, Understanding Equity, Principles of Accounting @@ -1042,7 +1042,7 @@ a few large ones, as with checks. One solution is: don't bother. Move your spending to a debit card, but in general ignore cash. Once you withdraw it from the ATM, mark -it as already spent to an @samp{Expenses:Cash} category: +it as already spent to an @code{Expenses:Cash} category: @smallexample 2004/03/15 ATM @@ -1051,7 +1051,7 @@ it as already spent to an @samp{Expenses:Cash} category: @end smallexample If at some point you make a large cash expense that you want to track, -just ``move'' the amount of the expense from @samp{Expenses:Cash} into +just ``move'' the amount of the expense from @code{Expenses:Cash} into the target account: @smallexample @@ -1091,8 +1091,8 @@ reserves resources for later: The problem with this kind of setup is that when you spend money, it comes from two or more places at once: the account and the fund. And yet, the correlation of amounts between funds and accounts is rarely -one-to-one. What if the school fund has @samp{$500.00}, but -@samp{$400.00} of that comes from Checking, and @samp{$100.00} from +one-to-one. What if the school fund has @code{$500.00}, but +@code{$400.00} of that comes from Checking, and @code{$100.00} from Savings? Traditional finance packages require that the money reside in only one @@ -1130,14 +1130,14 @@ account: When reports are generated, by default they'll appear in terms of the funds. In this case, you will likely want to mask out your -@samp{Assets} account, because otherwise the balance won't make much +@code{Assets} account, because otherwise the balance won't make much sense: @example ledger bal -^Assets @end example -If the @option{--real} option is used, the report will be in terms of +If the @code{--real} option is used, the report will be in terms of the real accounts: @example @@ -1159,7 +1159,7 @@ The second way of tracking funds is to use transaction codes. In this respect the codes become like virtual accounts that embrace the entire set of postings. Basically, we are associating a transaction with a fund by setting its code. Here are two transactions that deposit money -into, and spend money from, the @samp{Funds:School} fund: +into, and spend money from, the @code{Funds:School} fund: @smallexample 2004/03/25 (Funds:School) Donations @@ -1176,10 +1176,10 @@ balance or registers reports will reflect this. That the transactions relate to a particular fund is kept only in the code. How does this become a fund report? By using the -@option{--code-as-payee} option, you can generate a register report +@code{--code-as-payee} option, you can generate a register report where the payee for each posting shows the code. Alone, this is not terribly interesting; but when combined with the -@option{--by-payee} option, you will now see account subtotals for any +@code{--by-payee} option, you will now see account subtotals for any postings related to a specific fund. So, to see the current monetary balances of all funds, the command would be: @@ -1187,7 +1187,7 @@ monetary balances of all funds, the command would be: ledger --code-as-payee -P reg ^Assets @end smallexample -Or to see a particular funds expenses, the @samp{School} fund in this +Or to see a particular funds expenses, the @code{School} fund in this case: @smallexample @@ -1270,7 +1270,7 @@ balanced amount, if it is the same as the first line: @end smallexample For this transaction, Ledger will figure out that $-23.00 must come from -@samp{Assets:Checking} in order to balance the transaction. +@code{Assets:Checking} in order to balance the transaction. Also note the structure of the account entries. There is an implied hierarchy established by separating with colons (see @pxref{Structuring @@ -1733,7 +1733,7 @@ account Expenses account Expenses:Utilities ... @end smallexample -Using the @samp{--strict} option will cause Ledger to complain if any accounts are not previously defined: +Using the @code{--strict} option will cause Ledger to complain if any accounts are not previously defined: @smallexample 15:27:39 ~/ledger (next) > ledger bal --strict Warning: "FinanceData/Master.dat", line 6: Unknown account 'Liabilities:Tithe Owed' @@ -1741,12 +1741,12 @@ Warning: "FinanceData/Master.dat", line 8: Unknown account 'Liabilities:Tithe Ow Warning: "FinanceData/Master.dat", line 15: Unknown account 'Allocation:Equities:Domestic' @end smallexample -If you have a large Ledger register already created use the @samp{accounts} command to get started: +If you have a large Ledger register already created use the @code{accounts} command to get started: @smallexample ledger accounts >> Accounts.dat @end smallexample -@noindent You will have to edit this file to add the @samp{account} directive. +@noindent You will have to edit this file to add the @code{account} directive. @node Journal Format, Converting from other formats, Keeping it Consistent, Keeping a Journal @section Journal Format @@ -1775,11 +1775,11 @@ transaction's account postings. The format of the first line is: DATE[=EDATE] [*|!] [(CODE)] DESC @end smallexample -If @samp{*} appears after the date (with optional effective date), it +If @code{*} appears after the date (with optional effective date), it indicates the transaction is ``cleared'', which can mean whatever the user -wants it to mean. If @samp{!} appears after the date, it indicates d +wants it to mean. If @code{!} appears after the date, it indicates d the transaction is ``pending''; i.e., tentatively cleared from the user's -point of view, but not yet actually cleared. If a @samp{CODE} appears +point of view, but not yet actually cleared. If a @code{CODE} appears in parentheses, it may be used to indicate a check number, or the type of the posting. Following these is the payee, or a description of the posting. @@ -1790,18 +1790,18 @@ The format of each following posting is: ACCOUNT AMOUNT [; NOTE] @end smallexample -The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual +The @code{ACCOUNT} may be surrounded by parentheses if it is a virtual posting, or square brackets if it is a virtual posting that -must balance. The @samp{AMOUNT} can be followed by a per-unit -posting cost, by specifying @samp{@@ AMOUNT}, or a complete -posting cost with @samp{@@@@ AMOUNT}. Lastly, the @samp{NOTE} may +must balance. The @code{AMOUNT} can be followed by a per-unit +posting cost, by specifying @code{@@ AMOUNT}, or a complete +posting cost with @code{@@@@ AMOUNT}. Lastly, the @code{NOTE} may specify an actual and/or effective date for the posting by using -the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or -@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}.(See @pxref{Virtual postings}) +the syntax @code{[ACTUAL_DATE]} or @code{[=EFFECTIVE_DATE]} or +@code{[ACTUAL_DATE=EFFECTIVE_DATE]}.(See @pxref{Virtual postings}) @item P Specifies a historical price for a commodity. These are usually found -in a pricing history file (see the @option{-Q} option). The syntax +in a pricing history file (see the @code{-Q} option). The syntax is: @smallexample P DATE SYMBOL PRICE @@ -1844,8 +1844,8 @@ Command directives must occur at the beginning of a line. Use of ! and @item account Pre-declare valid account names. This only has effect if -@samp{--strict} or @samp{--pedantic} is used (see below). The -@samp{account} directive supports several optional sub-directives, if +@code{--strict} or @code{--pedantic} is used (see below). The +@code{account} directive supports several optional sub-directives, if they immediately follow the account directive and if they begin with whitespace: @@ -1860,14 +1860,14 @@ whitespace: default @end smallexample -The @samp{note} sub-directive associates a textual note with the account. This can -be accessed later using the @samp{note} valexpr function in any account context. +The @code{note} sub-directive associates a textual note with the account. This can +be accessed later using the @code{note} valexpr function in any account context. -The @samp{alias} sub-directive, which can occur multiple times, allows the alias to +The @code{alias} sub-directive, which can occur multiple times, allows the alias to be used in place of the full account name anywhere that account names are allowed. -The @samp{payee} sub-directive, which can occur multiple times, provides regexps +The @code{payee} sub-directive, which can occur multiple times, provides regexps that identify the account if that payee is encountered and an account within its transaction ends in the name "Unknown". Example: @@ -1877,13 +1877,13 @@ its transaction ends in the name "Unknown". Example: Assets:Cash @end smallexample -The @samp{check} and @samp{assert} directives warn or error (respectively) if the given +The @code{check} and @code{assert} directives warn or error (respectively) if the given value expression evaluates to false within the context of any posting. -The @samp{eval} directive evaluates the value expression in the context of the +The @code{eval} directive evaluates the value expression in the context of the account at the time of definition. At the moment this has little value. -The @samp{default} directive specifies that this account should be used as the +The @code{default} directive specifies that this account should be used as the ``balancing account'' for any future transactions that contain only a single posting. @@ -1992,13 +1992,13 @@ check Start a block comment, closed by @code{end comment}. @item commodity -Pre-declare commodity names. This only has effect if @samp{--strict} or -@samp{--pedantic} is used (see below). +Pre-declare commodity names. This only has effect if @code{--strict} or +@code{--pedantic} is used (see below). commodity $ commodity CAD -The @samp{commodity} directive supports several optional sub-directives, if they +The @code{commodity} directive supports several optional sub-directives, if they immediately follow the commodity directive and if they begin with whitespace: @smallexample @@ -2009,18 +2009,18 @@ immediately follow the commodity directive and if they begin with whitespace: default @end smallexample -The @samp{note} sub-directive associates a textual note with the commodity. At +The @code{note} sub-directive associates a textual note with the commodity. At present this has no value other than documentation. -The @samp{format} directive gives you a way to tell Ledger how to format this +The @code{format} directive gives you a way to tell Ledger how to format this commodity. In future using this directive will disable Ledger's observation of other ways that commodity is used, and will provide the ``canonical'' representation. -The @samp{nomarket} directive states that the commodity's price should never be +The @code{nomarket} directive states that the commodity's price should never be auto-downloaded. -The @samp{default} directive marks this as the ``default'' commodity. +The @code{default} directive marks this as the ``default'' commodity. @item define @c instance_t::define_directive in textual.cc @@ -2070,13 +2070,13 @@ is equivalent to this: Expenses:Food 25.75 CAD @{=$0.90@} @end smallexample -Note that ending a @samp{fixed} is done differently than other -directives, as @samp{fixed} is closed with an @samp{endfixed} (i.e., -there is @strong{no space} between @samp{end} and @samp{fixed}). +Note that ending a @code{fixed} is done differently than other +directives, as @code{fixed} is closed with an @code{endfixed} (i.e., +there is @strong{no space} between @code{end} and @code{fixed}). For the moment, users may wish to study @uref{http://bugs.ledger-cli.org/show_bug.cgi?id=789, Bug Report 789} -before using the @samp{fixed} directive in production. +before using the @code{fixed} directive in production. @item include @c instance_t::include_directive in textual.cc @@ -2084,7 +2084,7 @@ Include the stated file as if it were part of the current file. @item payee @c instance_t::payee_mapping_directive in textual.cc -The @samp{payee} directive supports one optional sub-directive, if it immediately +The @code{payee} directive supports one optional sub-directive, if it immediately follows the payee directive and if it begins with whitespace: @smallexample @@ -2092,7 +2092,7 @@ follows the payee directive and if it begins with whitespace: alias KENTUCKY FRIED CHICKEN @end smallexample -The @samp{alias} directive provides a regexp which, if it matches a parsed payee, +The @code{alias} directive provides a regexp which, if it matches a parsed payee, the declared payee name is substituted: @smallexample @@ -2152,8 +2152,8 @@ Note that anything following ``@code{end tag}'' is ignored. placing the name of the tag that is being closed is a simple way to keep track. @item tag -Pre-declares tag names. This only has effect if @samp{--strict} or -@samp{--pedantic} is used (see below). +Pre-declares tag names. This only has effect if @code{--strict} or +@code{--pedantic} is used (see below). @smallexample tag Receipt @@ -2169,7 +2169,7 @@ follow the tag directive and if they begin with whitespace: assert value != "foobar" @end smallexample -The @samp{check} and @samp{assert} directives warn or error (respectively) if the given +The @code{check} and @code{assert} directives warn or error (respectively) if the given value expression evaluates to false within the context of any use of the related tag. In such a context, ``value'' is bound to the value of the tag (which may not be a string if typed-metadata is used!). Such checks or @@ -2183,7 +2183,7 @@ This is a synonym for @code{comment} and must be closed by and @code{end} tag. @c instance_t::year_directive in textual.cc Denotes the year used for all subsequent transactions that give a date without a year. The year should appear immediately after the Y, for -example: @samp{year 2004}. This is useful at the beginning of a file, to +example: @code{year 2004}. This is useful at the beginning of a file, to specify the year for that file. If all transactions specify a year, however, this command has no effect. @@ -2408,8 +2408,8 @@ save typing and improve accuracy. Ledger doesn't leave you hanging, Type a portion of the payee and hit , and @code{ledger-mode} will suggest a completion. When filling in the account type the first few letters followed by a and the account will be filled in. For -example typing @samp{ExAuF} would yield -@samp{Expenses:Auto:Fuel} if you had previously used that account in +example typing @code{ExAuF} would yield +@code{Expenses:Auto:Fuel} if you had previously used that account in this journal. If there are more than one account with similar starting, hitting multiple times will iterate through them. This is a good habit to get in to prevent misspellings of accounts. Remember Ledger @@ -2434,7 +2434,7 @@ payee. For example, if your journal contains an entry Expenses:Tips $2.55 Liabilities:MasterCard $-15.00 @end smallexample -@noindent and you type @samp{C-c C-a}, the mini-buffer will appear showing the +@noindent and you type @code{C-c C-a}, the mini-buffer will appear showing the current year and month. If you complete the mini-buffer entry by typing @smallexample Entry: 2011/11/28 viva food 34 tip 7 @@ -2470,7 +2470,7 @@ your bank (or whatever else you want the concept to mean) @end smallexample If, for some reason you need to clear a specific posting in the -transaction you can type @samp{C-c C-c} and the posting at point will be +transaction you can type @code{C-c C-c} and the posting at point will be toggled. @node Reconciling accounts, Generating Reports, Working with entries, Using Emacs @@ -2817,7 +2817,7 @@ there are some tricks up Ledger's sleeve... You can use virtual accounts to transfer amounts to an account on the sly, bypassing the balancing requirement. The trick is that these postings are not -considered ``real'', and can be removed from all reports using @samp{--real}. +considered ``real'', and can be removed from all reports using @code{--real}. To specify a virtual account, surround the account name with parentheses: @@ -3060,7 +3060,7 @@ of an exceptional transaction, surround the @@ or @@@@ with parentheses: When a transaction occurs that exchange one commodity for another, Ledger records that commodity price not only within its internal price database, but also attached to the commodity itself. Usually this fact remains invisible to -the user, unless you turn on @samp{--lot-prices} to show these hidden price figures. +the user, unless you turn on @code{--lot-prices} to show these hidden price figures. For example, consider the stock sale given above: @@ -3234,7 +3234,7 @@ This is the same as the previous transaction, with the same caveats found in @section Lot dates In addition to lot prices, you can specify lot dates and reveal them with -@samp{--lot-dates}. Other than that, however, they have no special meaning to +@code{--lot-dates}. Other than that, however, they have no special meaning to Ledger. They are specified after the amount in square brackets (the same way that dates are parsed in value expressions): @@ -3262,7 +3262,7 @@ cannot begin with an @ character, as that would indicate a virtual cost: You can any combination of lot prices, dates or notes, in any order. They are all optional. -To show all lot information in a report, use @samp{--lots}. +To show all lot information in a report, use @code{--lots}. @node Lot value expressions, Automated transactions, Lot notes, Transactions @section Lot value expressions @@ -3602,7 +3602,7 @@ really knows that it debited $225 this month. A periodic transaction starts with a ~ followed by a period expression. Periodic transactions are used for budgeting and forecasting only, they -have no effect without the @samp{--budget} option specified. +have no effect without the @code{--budget} option specified. See @ref{Budgeting and Forecasting} for examples and details. @@ -3680,7 +3680,7 @@ command. $ 5,480.00 20:39:21 ~/ledger/test/input > @end smallexample -@noindent note the implicit logical and between @samp{Auto} and @samp{Mastercard}. +@noindent note the implicit logical and between @code{Auto} and @code{Mastercard}. If you want the entire contents of a branch of your account tree, use the highest common name in the branch: @@ -3703,7 +3703,7 @@ You can use general regular expressions in nearly anyplace Ledger needs a string The first example looks for any account starting with ``Bo'', of which there are none. The second looks for any account with ``Bo'', which is -@samp{Expenses:Books}. +@code{Expenses:Books}. @cindex limit by payees If you want to know exactly how much you have spent in a particular @@ -3758,7 +3758,7 @@ ledger -M --period-sort "(amount)" 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 +things. To see that report, add @code{-r}, which shows the ``related account'' postings: @example @@ -3768,8 +3768,8 @@ ledger -M --period-sort "(amount)" -r reg ^expenses 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: +calculated must match @code{^expenses}, while the postings +displayed must match @code{mastercard}. The command would be: @example ledger -M -r --display "account =~ /mastercard/" reg ^expenses @@ -3777,8 +3777,8 @@ ledger -M -r --display "account =~ /mastercard/" reg ^expenses 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}. +account matches @code{mastercard}, and base the calculation on +postings matching @code{^expenses}. This works just as well for report the overall total, too: @@ -3786,7 +3786,7 @@ This works just as well for report the overall total, too: ledger -s -r --display "account =~ /mastercard/"/ reg ^expenses @end example -The @option{-s} option subtotals all postings, just as @option{-M} +The @code{-s} option subtotals all postings, just as @code{-M} subtotaled by the month. The running total in both cases is off, however, since a display expression is being used. @@ -3922,8 +3922,8 @@ 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 +in mind is that you must specify @code{-j (--amount-data)} or +@code{-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. @@ -3954,8 +3954,8 @@ report -J -l "Ua>=@{\$0.01@}" reg ^assets ^liab 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 last report uses both a calculation predicate (@code{-l}) and a +display predicate (@code{-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 @@ -4018,7 +4018,7 @@ always be the same as the current balance of that account. If you have Gnuplot installed, you may plot the amount or running total of any register by using the script @file{report}, which is 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 @code{-j} or @code{-J} to your register command, in order to plot either the amount or total column, respectively. @node The print Command, , The register Command, Primary Financial Reports @@ -4132,7 +4132,7 @@ ones are @code{--invert} which inverts the amount field, and balance against and @code{--rich-data}. When using the rich-data switch additional metadata is stored as tags. There is, for example, a UUID field. If an entry with the same UUID tag is already included in the normal ledger -file (specified via -f or $LEDGER_FILE) this entry will not be printed +file (specified via @code{-f} or @code{$LEDGER_FILE}) this entry will not be printed again. You can also use @code{convert} with @code{payee} and @code{account} @@ -4148,9 +4148,9 @@ account Aufwand:Einkauf:Lebensmittel payee ^(Aldi|Alnatura|Kaufland|REWE)$ @end smallexample -Note that it may be necessary for the output of 'ledger convert' to be -passed through 'ledger print' a second time if you want to match on the -new payee field. During the 'ledger convert' run only the original payee +Note that it may be necessary for the output of @code{ledger convert} to be +passed through @code{ledger print} a second time if you want to match on the +new payee field. During the @code{ledger convert} run only the original payee name as specified in the csv data seems to be used. @node The emacs command, Emacs org mode, Comma Separated Variable files, Reports in other Formats @@ -4171,18 +4171,18 @@ 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}. -Org mode has a sub-system known as babel which allows for literate +Org mode has a sub-system known as Babel which allows for literate programming. This allows you to mix text and code within the same document and automatically execute code which may generate results which will then appear in the text. -One of the languages supported by org+babel is ledger so that you can +One of the languages supported by @code{org+babel} is Ledger, so that you can have ledger commands embedded in a text file and have the output of ledger commands also appear in the text file. The output can be updated whenever any new ledger entries are added. For instance, the following org mode text document snippet illustrates a -very naive but still useful of the org+babel system: +very naive but still useful of the @code{org+babel} system: @smallexample * A simple test of ledger in an org file @@ -4316,7 +4316,7 @@ Evaluating the code block again would generate a different report. Having to change the actual directive on the code block and re-evaluate makes it difficult to have more than one view of your transactions and financial state. Eventually, babel will support passing arguments to -#+call evaluations of code blocks but this support is missing +@code{#+call} evaluations of code blocks but this support is missing currently. Instead, we can use the concepts of literary programming, as implemented by the noweb features of babel, to help us. @@ -4377,7 +4377,7 @@ have been done individually. Given the ledger entries defined above in the income and expenses code blocks, we can now refer to these using the noweb expansion directives, -<>. We can now define different code blocks to generate specific +@code{<>}. We can now define different code blocks to generate specific reports for those transactions. Below are two examples, one to generate a balance report and one to generate a register report of all transactions. @@ -4402,7 +4402,7 @@ results generated by incorporating the transactions referred to by the @end smallexample If you want a more detailed breakdown of where your money is and where -it has been spent, you can specify the -s flag (i.e. @code{:cmdline -s bal}) to +it has been spent, you can specify the @code{-s} flag (i.e. @code{:cmdline -s bal}) to tell Ledger to include sub-accounts in the report. @smallexample @@ -4505,8 +4505,8 @@ The general format used for Ledger data is: @end smallexample -The data stream is enclosed in a @samp{ledger} tag, which contains a -series of one or more transactions. Each @samp{xact} describes the +The data stream is enclosed in a @code{ledger} tag, which contains a +series of one or more transactions. Each @code{xact} describes the transaction and contains a series of one or more postings: @smallexample @@ -4523,19 +4523,19 @@ transaction and contains a series of one or more postings: @end smallexample -The date format for @samp{en:date} is always @samp{YYYY/MM/DD}. The -@samp{en:cleared} tag is optional, and indicates whether the posting has -been cleared or not. There is also an @samp{en:pending} tag, for -marking pending postings. The @samp{en:code} and @samp{en:payee} tags +The date format for @code{en:date} is always @code{YYYY/MM/DD}. The +@code{en:cleared} tag is optional, and indicates whether the posting has +been cleared or not. There is also an @code{en:pending} tag, for +marking pending postings. The @code{en:code} and @code{en:payee} tags both contain whatever text the user wishes. After the initial transaction data, there must follow a set of postings -marked with @samp{en:postings}. Typically these postings will all +marked with @code{en:postings}. Typically these postings will all balance each other, but if not they will be automatically balanced into -an account named @samp{}. +an account named @code{}. -Within the @samp{en:postings} tag is a series of one or more -@samp{posting}'s, which have the following form: +Within the @code{en:postings} tag is a series of one or more +@code{posting}'s, which have the following form: @smallexample @@ -4552,13 +4552,13 @@ Within the @samp{en:postings} tag is a series of one or more @end smallexample This is a basic posting. It may also be begin with -@samp{tr:virtual} and/or @samp{tr:generated} tags, to indicate virtual -and auto-generated postings. Then follows the @samp{tr:account} +@code{tr:virtual} and/or @code{tr:generated} tags, to indicate virtual +and auto-generated postings. Then follows the @code{tr:account} tag, which contains the full name of the account the posting is related to. Colons separate parent from child in an account name. Lastly follows the amount of the posting, indicated by -@samp{tr:amount}. Within this tag is a @samp{value} tag, of which +@code{tr:amount}. Within this tag is a @code{value} tag, of which there are four different kinds, each with its own format: @enumerate @@ -4568,15 +4568,15 @@ there are four different kinds, each with its own format: @item balance @end enumerate -The format of a Boolean value is @samp{true} or @samp{false} -surrounded by a @samp{boolean} tag, for example: +The format of a Boolean value is @code{true} or @code{false} +surrounded by a @code{boolean} tag, for example: @smallexample true @end smallexample The format of an integer value is the numerical value surrounded by an -@samp{integer} tag, for example: +@code{integer} tag, for example: @smallexample 12036 @@ -4641,8 +4641,8 @@ the same data. @subsection @code{prices} and @code{pricedb} The @command{prices} command displays the price history for matching -commodities. The @option{-A} flag is useful with this report, to -display the running average price, or @option{-D} to show each price's +commodities. The @code{-A} flag is useful with this report, to +display the running average price, or @code{-D} to show each price's deviation from that average. There is also a @command{pricedb} command which outputs the same @@ -4690,7 +4690,7 @@ Say you currently have this posting in your ledger file: Liabilities:MasterCard $-15.00 @end smallexample -Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva +Now it's @code{2004/4/9}, and you've just eating at @code{Viva Italiano} again. The exact amounts are different, but the overall form is the same. With the @command{xact} command you can type: @@ -4708,10 +4708,10 @@ This produces the following output: @end smallexample It works by finding a past posting matching the regular expression -@samp{viva}, and assuming that any accounts or amounts specified will +@code{viva}, and assuming that any accounts or amounts specified will be similar to that earlier posting. If Ledger does not succeed in generating a new transaction, an error is printed and the exit code is set -to @samp{1}. +to @code{1}. Here are a few more examples of the @command{xact} command, assuming the above journal transaction: @@ -4933,7 +4933,7 @@ model transaction: true @end smallexample @item template -Shows the insertion template that a "draft" or "xact" sub-command generates. +Shows the insertion template that a @code{draft} or @code{xact} sub-command generates. This is a debugging command. @end table @@ -4972,7 +4972,7 @@ meaning, described below. The regular expressions arguments always match the account name that a posting refers to. To match on the payee of the transaction instead, -precede the regular expression with @samp{payee} or @@. For example, the +precede the regular expression with @code{payee} or @@. For example, the following balance command reports account totals for rent, food and movies, but only those whose payee matches Freddie: @@ -5197,10 +5197,10 @@ their values and the source of those values, for example: -------------------- 0 @end smallexample -@noindent For the `source' column, a value starting with a `@code{-}' or -`@code{--}' indicated the source was a command line argument. It the -entry starts with a `@code{$}', the source was an environment -variable. If the source is `@code{?normalize}' the value was set +@noindent For the source column, a value starting with a @code{-} or +@code{--} indicated the source was a command line argument. It the +entry starts with a @code{$}, the source was an environment +variable. If the source is @code{?normalize} the value was set internally by ledger, in a function called @code{normalize_options}. @item --script @@ -5277,7 +5277,7 @@ Specify the location of the price entry data file. @item --price-exp INTEGER_MINUTES Set the expected freshness of price quotes, in minutes. That is, if the last known quote for any commodity is older than this value, and if -@samp{--download} is being used, then the Internet will be consulted again +@code{--download} is being used, then the Internet will be consulted again for a newer price. Otherwise, the old price is still considered to be fresh enough. @@ -5479,7 +5479,7 @@ ASK JOHN @item --dc Display register or balance in debit/credit format -If you use @samp{--dc} with either the register (reg) or balance (bal) commands, you +If you use @code{--dc} with either the register (reg) or balance (bal) commands, you will now get extra columns. The register goes from this: @smallexample 12-Mar-10 Employer Assets:Cash $100 $100 @@ -5508,7 +5508,7 @@ will now get extra columns. The register goes from this: @noindent Where the first column is debits, the second is credits, and the third is the running total. Only the running total may contain negative values. -For the balance report without @samp{--dc}: +For the balance report without @code{--dc}: @smallexample $70 Assets:Cash @@ -5518,7 +5518,7 @@ For the balance report without @samp{--dc}: 0 @end smallexample -@noindent And with @samp{--dc} it becomes this: +@noindent And with @code{--dc} it becomes this: @smallexample $105 $35 $70 Assets:Cash @@ -5619,8 +5619,8 @@ them. @item --group-by group transaction together in the register -report. EXPR can be anything, although most common would be -@code{"payee"} or @code{"commodity"}. The @code{tags()} function is +report. @code{EXPR} can be anything, although most common would be +@code{payee} or @code{commodity}. The @code{tags()} function is also useful here. @item --group-title-format @@ -5643,7 +5643,7 @@ ledger reg Expenses --group-by "payee" --group-title-format "------------------- @item --head -Print the first INT entries. Opposite of @code{--tail}. +Print the first @code{INT} entries. Opposite of @code{--tail}. @item --inject Use @code{Expected} amounts in calculations. In the case that you know @@ -5656,14 +5656,14 @@ wrong value you can use metadata to put in the expected amount: @end smallexample Then using the command @code{ledger reg --inject=Expected Income} would -treat the transaction as iff the ``Expected Value'' was actual. +treat the transaction as if the ``Expected Value'' was actual. @item --invert Change the sign of all reported values. @item --limit - Only transactions that satisfy the expression -will be considered in the calculation. + Only transactions that satisfy the expression will be considered in the +calculation. @item --lot-dates Report the date on which each commodity in a balance report was purchased. @@ -5717,12 +5717,13 @@ Suppress the output of group titles Suppress printing the final total line in a balance report. @item --now -Define the current date in case to you to do calculate in the past or future using @code{--current} +Define the current date in case to you to do calculate in the past or +future using @code{--current} @item --only -This is a postings predicate that applies after certain -transforms have been executed, such as periodic gathering. +This is a postings predicate that applies after certain transforms have +been executed, such as periodic gathering. @item --output Redriect the output of ledger to the file defined in @file{PATH}. @@ -5752,7 +5753,7 @@ Only works for account that have a single commoditiy. @item --period Define a period expression the sets the time period during which -transactions are to be accounted. For a register report only th +transactions are to be accounted. For a register report only the transactions that satisfy the period expression with be displayed. For a balance report only those transactions will be accounted in the final balances. @@ -5812,8 +5813,8 @@ interpreting. Can be useful for minor cleanups, like just aligning amounts. @item --real - Account using only real transactions ignoring virtual -and automatic transactions. +Account using only real transactions ignoring virtual and automatic +transactions. @item --related-all @@ -5865,7 +5866,7 @@ FIX THIS ENTRY @item --tail -report only the last entries. Only useful ona register report. +report only the last @code{INT} entries. Only useful ona register report. @item --total-data @@ -5882,7 +5883,7 @@ Indicates how truncation should happen when the contents of columns exceed their width. Valid arguments are @code{leading}, @code{middle}, and @code{trailing}. The default is smarter than any of these three, as it considers sub-names within the account name (that style is called -``abbreviate''. +``abbreviate''). @item --unbudgeted @@ -5954,7 +5955,7 @@ goes to standard output. @item --init-file FILE @item -i FILE -causes FILE to be read by ledger before any other ledger file. This +causes @code{FILE} to be read by ledger before any other ledger file. This file may not contain any postings, but it may contain option settings. To specify options in the init file, use the same syntax as the command-line, but put each option on it's own line. Here's an example @@ -5989,11 +5990,11 @@ displays only transactions occurring on or before the current date. @item --begin DATE @item -b DATE -constrains the report to transactions on or after -@var{DATE}. Only transactions after that date will be calculated, which -means that the running total in the balance report will always start at -zero with the first matching transaction. (Note: This is different from -using @option{--display} to constrain what is displayed). +constrains the report to transactions on or after @var{DATE}. Only +transactions after that date will be calculated, which means that the +running total in the balance report will always start at zero with the +first matching transaction. (Note: This is different from using +@code{--display} to constrain what is displayed). @item --end DATE @item -e DATE @@ -6002,12 +6003,12 @@ not considered. The ending date is inclusive. @item --period STR @item -p STR -sets the reporting period to @var{STR}. This will subtotal -all matching transactions within each period separately, making it easy -to see weekly, monthly, quarterly, etc., posting totals. A period -string can even specify the beginning and end of the report range, using -simple terms like ``last June'' or ``next month''. For more using -period expressions, see @ref{Period Expressions}. +sets the reporting period to @var{STR}. This will subtotal all matching +transactions within each period separately, making it easy to see +weekly, monthly, quarterly, etc., posting totals. A period string can +even specify the beginning and end of the report range, using simple +terms like ``last June'' or ``next month''. For more using period +expressions, see @ref{Period Expressions}. @item --period-sort EXPR sorts the postings within each reporting period using the value @@ -6100,8 +6101,8 @@ sets the value expression used for the ``totals'' column in the @c ledger [OPTIONS] @c @end smallexample -@c Where @samp{COMMAND} is any command verb (@pxref{Reporting Commands}), @samp{OPTIONS} can occur -@c anywhere, and @samp{SEARCH-TERM} is one or more of the following: +@c Where @code{COMMAND} is any command verb (@pxref{Reporting Commands}), @code{OPTIONS} can occur +@c anywhere, and @code{SEARCH-TERM} is one or more of the following: @c @smallexample @c word search for any account containing 'word' @@ -6149,7 +6150,7 @@ postings to be collapsed into a single, subtotaled transaction. @item --subtotal @item -s - causes all transactions in a @command{register} report to be collapsed +causes all transactions in a @command{register} report to be collapsed into a single, subtotaled transaction. @item --by-payee @@ -6165,7 +6166,7 @@ includes even empty accounts in the @command{balance} report. @item -W reports posting totals by the week. The week begins on whichever day of the week begins the month containing that posting. To set a specific -begin date, use a period string, such as @samp{weekly from DATE}. +begin date, use a period string, such as @code{weekly from DATE}. @item --monthly @item -M reports posting totals by month; @@ -6182,7 +6183,7 @@ to see if weekend spending is more than on weekdays. @item --sort EXPR @item -S EXPR sorts a report by comparing the values determined using the value -expression @var{EXPR}. For example, using @option{-S -UT} in the +expression @var{EXPR}. For example, using @code{-S -UT} in the balance report will sort account balances from greatest to least, using the absolute value of the total. For more on how to use value expressions, see @ref{Value Expressions}. @@ -6197,16 +6198,16 @@ causes the default @command{register} report to assume 132 columns instead of 80. @item --head -causes only the first N transactions to be printed. This is different +causes only the first @code{N} transactions to be printed. This is different from using the command-line utility @command{head}, which would limit to -the first N postings. @option{--tail} outputs only the last N +the first N postings. @code{--tail} outputs only the last @code{N} transactions. Both options may be used simultaneously. If a negative amount is given, it will invert the meaning of the flag (instead of the first five transactions being printed, for example, it would print all but the first five). @item --pager -tells Ledger to pass its output to the given pager program---very useful +tells Ledger to pass its output to the given pager program; very useful when the output is especially long. This behavior can be made the default by setting the @env{LEDGER_PAGER} environment variable. @@ -6224,7 +6225,7 @@ meaningful in the @command{register} and @command{prices} reports. shows account subtotals in the @command{balance} report as percentages of the parent account. -@c @option{--totals} include running total information in the +@c @code{--totals} include running total information in the @c @command{xml} report. @item --amount-data @@ -6261,15 +6262,15 @@ ledger -p "last month" reg checking @end smallexample Which is more useful depends on what you're looking to know: the total -amount for the reporting range (@option{-p}), or simply a display -restricted to the reporting range (using @option{-d}). +amount for the reporting range (@code{-p}), or simply a display +restricted to the reporting range (using @code{-d}). @item --date-format STR @item -y STR changes the basic date format used by reports. The default uses a date -like 2004/08/01, which represents the default date format of -@samp{%Y/%m/%d}. To change the way dates are printed in general, the -easiest way is to put @option{--date-format FORMAT} in the Ledger +like @code{2004/08/01}, which represents the default date format of +@code{%Y/%m/%d}. To change the way dates are printed in general, the +easiest way is to put @code{--date-format FORMAT} in the Ledger initialization file @file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}). @@ -6398,8 +6399,8 @@ N $ N h @end smallexample -@noindent Note: Ledger NEVER write output to files. You are responsible for -updated the price-db file. The best way is to have your price download +@noindent Note: Ledger NEVER writes output to files. You are responsible for +updating the price-db file. The best way is to have your price download script maintain this file. The format of the file can be changed by telling ledger to use the @@ -6408,8 +6409,8 @@ The format of the file can be changed by telling ledger to use the @item --price-exp MINS @item -L MINS sets the expected freshness of price quotes, in minutes. That is, if -the last known quote for any commodity is older than this value---and if -@code{--download} is being used---then the Internet will be consulted +the last known quote for any commodity is older than this value, and if +@code{--download} is being used, then the Internet will be consulted again for a newer price. Otherwise, the old price is still considered to be fresh enough. @@ -6425,7 +6426,7 @@ database, usually specified using the environment variable @end table There are several different ways that ledger can report the totals it displays. The most flexible way to adjust them is by using value -expressions, and the @option{-t} and @option{-T} options. However, +expressions, and the @code{-t} and @code{-T} options. However, there are also several ``default'' reports, which will satisfy most users basic reporting needs: @@ -6453,10 +6454,10 @@ commodity can mean different things to different people, depending on the accounts involved, the commodities, the nature of the transactions, etc. -When you specify @samp{-V}, or @samp{-X COMM}, you are requesting that +When you specify @code{-V}, or @code{-X COMM}, you are requesting that some or all of the commodities be valuated as of today (or whatever -@samp{--now} is set to). But what does such a valuation mean? This -meaning is governed by the presence of a @samp{VALUE} meta-data property, +@code{--now} is set to). But what does such a valuation mean? This +meaning is governed by the presence of a @code{VALUE} meta-data property, whose content is an expression used to compute that value. If no VALUE property is specified, each posting is assumed to have a @@ -6467,9 +6468,9 @@ follows: = expr true ; VALUE:: market(amount, date, exchange) @end smallexample -This definition emulates the present day behavior of @samp{-V} and @samp{-X} (in the -case of @samp{-X}, the requested commodity is passed via the string 'exchange' -above). +This definition emulates the present day behavior of @code{-V} and +@code{-X} (in the case of @code{-X}, the requested commodity is passed +via the string 'exchange' above). @cindex Euro conversion One thing many people have wanted to do is to fixate the valuation of @@ -6481,8 +6482,8 @@ old European currencies in terms of the Euro after a certain date: ; VALUE:: date < [Jun 2008] ? market(amount, date, exchange) : 1.44 EUR @end smallexample -This says: If @samp{--now} is some old date, use market prices as they -were at that time; but if @samp{--now} is past June 2008, use a fixed +This says: If @code{--now} is some old date, use market prices as they +were at that time; but if @code{--now} is past June 2008, use a fixed price for converting Deutsch Mark to Euro. Or how about never re-valuating commodities used in Expenses, since they @@ -6495,7 +6496,7 @@ cannot have a different future value: This says the future valuation is the same as the valuation at the time of posting. post.date equals the posting's date, while just 'date' is -the value of @samp{--now} (defaults to today). +the value of @code{--now} (defaults to today). Or how about valuating miles based on a reimbursement rate during a specific time period: @@ -6507,7 +6508,7 @@ specific time period: @end smallexample In this case, miles driven in 2007 will always be valuated at $1.05 -each. If you use @samp{-X EUR} to expressly request all amounts in +each. If you use @code{-X EUR} to expressly request all amounts in Euro, Ledger shall convert $1.05 to Euro by whatever means are appropriate for dollars. @@ -6547,16 +6548,16 @@ another currency. For example: Ledger presently has no way of handling such things as FIFO and LIFO. If you specify an unadorned commodity name, like AAPL, it will balance -against itself. If @samp{--lots} are not being displayed, then it will +against itself. If @code{--lots} are not being displayed, then it will appear to balance against any lot of AAPL. @cindex adorned commodity If you specify an adorned commodity, like AAPL @{$10.00@}, it will also -balance against itself, and against any AAPL if @samp{--lots} is not -specified. But if you do specify @samp{--lot-prices}, for example, then +balance against itself, and against any AAPL if @code{--lots} is not +specified. But if you do specify @code{--lot-prices}, for example, then it will balance against that specific price for AAPL. -Normally when you use @samp{-X } to request that amounts be reported in a +Normally when you use @code{-X } to request that amounts be reported in a specific commodity, Ledger uses these values: @itemize @@ -6569,16 +6570,17 @@ specific commodity, Ledger uses these values: For the balance report, use the value of that commodity as of today. @end itemize -You can now specify -H to ask that all valuations for any amount be done +You can now specify @code{-H} to ask that all valuations for any amount be done relative to the date that amount was encountered. -You can also now use -X (and -H) in conjunction with -B and -I, to see -valuation reports of just your basis costs or lot prices. +You can also now use @code{-X} (and @code{-H}) in conjunction with +@code{-B} and @code{-I}, to see valuation reports of just your basis +costs or lot prices. @node Environment Variables, , Commodity Reporting, Detailed Options Description @subsection Environment variables Every option to ledger may be set using an environment variable. If -an option has a long name such @option{--this-option}, setting the +an option has a long name such @code{--this-option}, setting the environment variable @env{LEDGER_THIS_OPTION} will have the same affect as specifying that option on the command-line. Options on the command-line always take precedence over environment variable @@ -6655,7 +6657,7 @@ last week The beginning and ending can be given at the same time, if it spans a single period. In that case, just use @var{SPEC} by itself. In that -case, the period @samp{oct}, for example, will cover all the days in +case, the period @code{oct}, for example, will cover all the days in October. The possible forms are: @smallexample @@ -6729,7 +6731,7 @@ ledger -p "this year" --monthly --average --subtotal balance ^expenses The reported totals are the current year's average for each account. Once these period transactions are defined, creating a budget report is as -easy as adding @option{--budget} to the command-line. For example, a +easy as adding @code{--budget} to the command-line. For example, a typical monthly expense report would be: @example @@ -6744,8 +6746,8 @@ ledger --budget --monthly register ^expenses A budget report includes only those accounts that appear in the budget. To see all expenses balanced against the budget, use -@option{--add-budget}. You can even see only the un-budgeted expenses -using @option{--unbudgeted}: +@code{--add-budget}. You can even see only the un-budgeted expenses +using @code{--unbudgeted}: @example ledger --unbudgeted --monthly register ^expenses @@ -6780,15 +6782,15 @@ ledger --forecast "d<[2010]" bal ^assets ^liabilities @node Value Expressions, Format Strings, Budgeting and Forecasting, Top @chapter Value Expressions -Ledger uses value expressions to make -calculations for many different purposes: +Ledger uses value expressions to make calculations for many different +purposes: @enumerate @item The values displayed in reports @item For predicates (where truth is anything non-zero), to determine which -postings are calculated (@option{-l}) or displayed (@option{-d}). +postings are calculated (@code{-l}) or displayed (@code{-d}). @item For sorting criteria, to yield the sort key. @item @@ -6822,8 +6824,8 @@ ledger -d "d>[this month]" register checking @end smallexample This advantage to this command's complexity is that it prints the -running total in terms of all transactions in the register. The following, -simpler command is similar, but totals only the displayed +running total in terms of all transactions in the register. The +following, simpler command is similar, but totals only the displayed postings: @smallexample @@ -6844,20 +6846,20 @@ Below are the one letter variables available in any value expression. For the register and print commands, these variables relate to individual postings, and sometimes the account affected by a posting. For the balance command, these variables relate to -accounts---often with a subtle difference in meaning. The use of each +accounts, often with a subtle difference in meaning. The use of each variable for both is specified. @table @code @item t -This maps to whatever the user specified with @option{-t}. In a -register report, @option{-t} changes the value column; in a balance -report, it has no meaning by default. If @option{-t} was not +This maps to whatever the user specified with @code{-t}. In a +register report, @code{-t} changes the value column; in a balance +report, it has no meaning by default. If @code{-t} was not specified, the current report style's value expression is used. @item T -This maps to whatever the user specified with @option{-T}. In a -register report, @option{-T} changes the totals column; in a balance -report, this is the value given for each account. If @option{-T} was +This maps to whatever the user specified with @code{-T}. In a +register report, @code{-T} changes the totals column; in a balance +report, this is the value given for each account. If @code{-T} was not specified, the current report style's value expression is used. @item m @@ -6884,7 +6886,7 @@ The market value of a posting, or an account without its children. @item g The net gain (market value minus cost basis), for a posting or an -account without its children. It is the same as @samp{v-b}. +account without its children. It is the same as @code{v-b}. @item l The depth (``level'') of an account. If an account has one parent, @@ -6926,7 +6928,7 @@ all its children. @item G The total net gain (market value minus cost basis), for a series of postings, or an account and its children. It is the same as -@samp{V-B}. +@code{V-B}. @end table @node Functions, Operators, Variables, Value Expressions @@ -6945,12 +6947,12 @@ The absolute (unsigned) value of the argument. Strips the commodity from the argument. @item A -The arithmetic mean of the argument; @samp{Ax} is the same as -@samp{x/n}. +The arithmetic mean of the argument; @code{Ax} is the same as +@code{x/n}. @item P -The present market value of the argument. The syntax @samp{P(x,d)} is -supported, which yields the market value at time @samp{d}. If no date +The present market value of the argument. The syntax @code{P(x,d)} is +supported, which yields the market value at time @code{d}. If no date is given, then the current moment is used. @end table @@ -6960,10 +6962,10 @@ is given, then the current moment is used. The binary and ternary operators, in order of precedence, are: @enumerate -@item @samp{* /} -@item @samp{+ -} -@item @samp{! < > =} -@item @samp{& | ?:} +@item @code{* /} +@item @code{+ -} +@item @code{! < > =} +@item @code{& | ?:} @end enumerate @menu @@ -7045,177 +7047,235 @@ precedence order of operators. @item [DATE] Useful specifying a date in plain terms. For example, you could say -@samp{[2004/06/01]}. +@code{[2004/06/01]}. @end table +@menu +* Misc:: +@end menu + +@node Misc, , Complex Expressions, Complex Expressions +@subsection Miscellaneous +@multitable @columnfractions .3 .2 .5 +@item @strong{Function} @tab @strong{Abbrev.} @tab @strong{Description} +@item @code{amount_expr } @tab @code{} @tab +@item @code{abs } @tab @code{} @tab --> U +@item @code{code} @tab @code{} @tab returns the transaction code, the string between the parenthesis after the date. +@item @code{commodity } @tab @code{} @tab +@item @code{display_amount } @tab @code{} @tab --> t +@item @code{display_total } @tab @code{} @tab --> T +@item @code{date } @tab @code{} @tab +@item @code{format_date } @tab @code{} @tab +@item @code{format } @tab @code{} @tab +@item @code{floor } @tab @code{} @tab +@item @code{get_at } @tab @code{} @tab +@item @code{is_seq } @tab @code{} @tab +@item @code{justify } @tab @code{} @tab +@item @code{join } @tab @code{} @tab +@item @code{market --> P } @tab @code{} @tab +@item @code{null } @tab @code{} @tab +@item @code{now --> d m } @tab @code{} @tab +@item @code{options } @tab @code{} @tab +@item @code{post } @tab @code{} @tab +@item @code{percent } @tab @code{} @tab +@item @code{price } @tab @code{} @tab +@item @code{print } @tab @code{} @tab +@item @code{quoted } @tab @code{} @tab +@item @code{quantity } @tab @code{} @tab +@item @code{rounded } @tab @code{} @tab +@item @code{scrub } @tab @code{} @tab +@item @code{strip --> S } @tab @code{} @tab +@item @code{should_bold } @tab @code{} @tab +@item @code{truncated } @tab @code{} @tab +@item @code{total_expr } @tab @code{} @tab +@item @code{today } @tab @code{} @tab +@item @code{top_amount } @tab @code{} @tab +@item @code{to_boolean } @tab @code{} @tab +@item @code{to_int } @tab @code{} @tab +@item @code{to_datetime } @tab @code{} @tab +@item @code{to_date } @tab @code{} @tab +@item @code{to_amount } @tab @code{} @tab +@item @code{to_balance } @tab @code{} @tab +@item @code{to_spring } @tab @code{} @tab +@item @code{to_mask } @tab @code{} @tab +@item @code{to_sequence } @tab @code{} @tab +@item @code{unrounded } @tab @code{} @tab +@item @code{value_date } @tab @code{} @tab +@end multitable @node Format Strings, Ledger for Developers, Value Expressions, Top @chapter Format Strings @menu * Basics:: +* Format String Structure:: * Format Expressions:: * --balance-format:: -* New formatting codes:: -* Date and Time Format Codes:: +* Formatting codes:: @end menu -@node Basics, Format Expressions, Format Strings, Format Strings +@node Basics, Format String Structure, Format Strings, Format Strings @section Format String Basics -Format strings may be used to change the output format of reports. -They are specified by passing a formatting string to the -@option{--format} (@option{-F}) option. Within that string, -constructs are allowed which make it possible to display the various -parts of an account or posting in custom ways. +Format strings may be used to change the output format of reports. They +are specified by passing a formatting string to the @code{--format} +(@code{-F}) option. Within that string, constructs are allowed which +make it possible to display the various parts of an account or posting +in custom ways. +There are several additional flags that allow you to define formats for +specific reports. These are useful to define in your configuration file +and will allow you to run ledger reports from the command line without +having to enter a new format for each command. + +@itemize +@item @code{--balance-report} +@item @code{--cleared-report} +@item @code{--register-report} +@item @code{--csv-report} +@item @code{--plot-amount-report} +@item @code{--plot-total-report} +@item @code{--pricedb-report} +@item @code{--prices-report} +@item @code{--wide-register-report} +@end itemize + +@node Format String Structure, Format Expressions, Basics, Format Strings +@section Format String Structure Within a format string, a substitution is specified using a percent -character (@samp{%}). The basic format of all substitutions is: +character (@code{%}). The basic format of all substitutions is: @smallexample %[-][MIN WIDTH][.MAX WIDTH](VALEXPR) @end smallexample -If the optional minus sign (@samp{-}) follows the percent character, +If the optional minus sign (@code{-}) follows the percent character, whatever is substituted will be left justified. The default is right -justified. If a minimum width is given next, the substituted text -will be at least that wide, perhaps wider. If a period and a maximum -width is given, the substituted text will never be wider than this, -and will be truncated to fit. Here are some examples: +justified. If a minimum width is given next, the substituted text will +be at least that wide, perhaps wider. If a period and a maximum width +is given, the substituted text will never be wider than this, and will +be truncated to fit. Here are some examples: -@smallexample -%-P a transaction's payee, left justified -%20P The same, right justified, at least 20 chars wide -%.20P The same, no more than 20 chars wide -%-.20P Left justified, maximum twenty chars wide -@end smallexample +@table @code +@item %-20P +a transaction's payee, left justified and padded to 20 characters wide. +@item %20P +The same, right justified, at least 20 chars wide +@item %.20P +The same, no more than 20 chars wide +@end table -The expression following the format constraints can be a single -letter, or an expression enclosed in parentheses or brackets. +The expression following the format constraints can be a single letter, +or an expression enclosed in parentheses or brackets. -@node Format Expressions, --balance-format, Basics, Format Strings +@node Format Expressions, --balance-format, Format String Structure, Format Strings @section Format Expressions - The -allowable expressions are: + The allowable expressions are: @table @code @item % Inserts a percent sign. @item t -Inserts the results of the value expression specified by @option{-t}. -If @option{-t} was not specified, the current report style's value +Inserts the results of the value expression specified by @code{-t}. +If @code{-t} was not specified, the current report style's value expression is used. @item T -Inserts the results of the value expression specified by @option{-T}. -If @option{-T} was not specified, the current report style's value +Inserts the results of the value expression specified by @code{-T}. +If @code{-T} was not specified, the current report style's value expression is used. -@item | -Inserts a single space. This is useful if a width is specified, for -inserting a certain number of spaces. - -@item _ -Inserts a space for each level of an account's depth. That is, if an -account has two parents, this construct will insert two spaces. If a -minimum width is specified, that much space is inserted for each level -of depth. Thus @samp{%5_}, for an account with four parents, will -insert twenty spaces. - @item (EXPR) Inserts the amount resulting from the value expression given in parentheses. To insert five times the total value of an account, for -example, one could say @samp{%12(5*O)}. Note: It's important to put -the five first in that expression, so that the commodity doesn't get +example, one could say @code{%12(5*O)}. Note: It's important to put the +five first in that expression, so that the commodity doesn't get stripped from the total. @item [DATEFMT] Inserts the result of formatting a posting's date with a date format string, exactly like those supported by @code{strftime}. For -example: @samp{%[%Y/%m/%d %H:%M:%S]}. +example: @code{%[%Y/%m/%d %H:%M:%S]}. @item S -Insert the pathname of the file from which the transaction's data was read. +Insert the pathname of the file from which the transaction's data was +read. Only sensible in a register report. @item B -Inserts the beginning character position of that transaction within the file. +Inserts the beginning character position of that transaction within the +file. @item b Inserts the beginning line of that transaction within the file. @item E -Inserts the ending character position of that transaction within the file. +Inserts the ending character position of that transaction within the +file. @item e Inserts the ending line of that transaction within the file. -@item D -By default, this is the same as @samp{%[%Y/%m%/d]}. The date format -used can be changed at any time with the @option{-y} flag, however. -Using @samp{%D} gives the user more control over the way dates are -output. +@c @item D +@c By default, this is the same as @code{%[%Y/%m%/d]}. The date format +@c used can be changed at any time with the @code{-y} flag, however. Using +@c @code{%D} gives the user more control over the way dates are output. @item d -This is the same as the @samp{%D} option, unless the transaction has an -effective date, in which case it prints -@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}. +Returns the data accoridng to the default format. If the transaction +has an effective date, it prints @code{[ACTUAL_DATE=EFFECTIVE_DATE]}. @item X -If a posting has been cleared, this inserts @samp{*} followed by a -space; otherwise nothing is inserted. +If a posting has been cleared, this returns a 1, otherwise returns 0. @item Y -This is the same as @samp{%X}, except that it only displays a state +This is the same as @code{%X}, except that it only displays a state character if all of the member postings have the same state. @item C -Inserts the checking number for a transaction, in parentheses, followed by -a space; if none was specified, nothing is inserted. +Inserts the transaction type. This is the value specified between +parenthesis on the first line of the transaction. @item P Inserts the payee related to a posting. -@item a -Inserts the optimal short name for an account. This is normally used -in balance reports. It prints a parent account's name if that name -has not been printed yet, otherwise it just prints the account's name. +@c @item a +@c Inserts the optimal short name for an account. This is normally used in +@c balance reports. It prints a parent account's name if that name has not +@c been printed yet, otherwise it just prints the account's name. @item A Inserts the full name of an account. -@item W -This is the same as @samp{%A}, except that it first displays the -posting's state @emph{if the transaction's posting states are not -all the same}, followed by the full account name. This is offered as -a printing optimization, so that combined with @samp{%Y}, only the -minimum amount of state detail is printed. +@c @item W +@c This is the same as @code{%A}, except that it first displays the +@c posting's state @emph{if the transaction's posting states are not all +@c the same}, followed by the full account name. This is offered as a +@c printing optimization, so that combined with @code{%Y}, only the minimum +@c amount of state detail is printed. -@item o -Inserts the ``optimized'' form of a posting's amount. This is -used by the print report. In some cases, this inserts nothing; in -others, it inserts the posting amount and its cost. It's use is -not recommended unless you are modifying the print report. +@c @item o +@c Inserts the ``optimized'' form of a posting's amount. This is used by +@c the print report. In some cases, this inserts nothing; in others, it +@c inserts the posting amount and its cost. It's use is not recommended +@c unless you are modifying the print report. -@item n -Inserts the note associated with a posting, preceded by two spaces -and a semi-colon, if it exists. Thus, no none becomes an empty -string, while the note @samp{foo} is substituted as @samp{ ; foo}. @item N Inserts the note associated with a posting, if one exists. @item / -The @samp{%/} construct is special. It separates a format string +The @code{%/} construct is special. It separates a format string between what is printed for the first posting of a transaction, and what is printed for all subsequent postings. If not used, the same format string is used for all postings. @end table -@node --balance-format, New formatting codes, Format Expressions, Format Strings +@node --balance-format, Formatting codes, Format Expressions, Format Strings @section --balance-format -As an example of how flexible the --format strings can be, the default balance format looks like this: +As an example of how flexible the @code{--format} strings can be, the default +balance format looks like this (the various functions are descirbed later): @smallexample "%(justify(scrub(display_total), 20, -1, true, color))" @@ -7225,34 +7285,37 @@ As an example of how flexible the --format strings can be, the default balance f "--------------------\n" @end smallexample -@node New formatting codes, Date and Time Format Codes, --balance-format, Format Strings -@section New Formatting Codes +@node Formatting codes, , --balance-format, Format Strings +@section Formatting Functions and Codes @menu * Field Widths:: * Colors:: * Quantities and Calculations:: * Dates:: +* Date and Time Format Codes:: * Text Formatting:: * Data File Parsing Information:: -* Misc:: @end menu -@node Field Widths, Colors, New formatting codes, New formatting codes +@node Field Widths, Colors, Formatting codes, Formatting codes @subsection Field Widths -@multitable @columnfractions .3 .2 .5 -@item @strong{Function} @tab @strong{Abbrev.} @tab @strong{Description} +The following codes return the width allocated for the specific fields. +The defaults can be changed using the corresponding command line +options: +@itemize @item @code{date_width} @item @code{payee_width} @item @code{account_width} @item @code{amount_width} @item @code{total_width} -@end multitable +@end itemize -@node Colors, Quantities and Calculations, Field Widths, New formatting codes +@node Colors, Quantities and Calculations, Field Widths, Formatting codes @subsection Colors -The character based formatting ledger can do is limited to the ANSI terminal character colors and font highlight in a normal TTY session. +The character based formatting ledger can do is limited to the ANSI +terminal character colors and font highlights in a normal TTY session. @multitable @columnfractions .3 .3 .3 @item @code{red} @tab @code{magenta} @tab @code{bold} @item @code{green } @tab @code{cyan} @tab @code{underline} @@ -7262,231 +7325,211 @@ The character based formatting ledger can do is limited to the ANSI terminal cha -@node Quantities and Calculations, Dates, Colors, New formatting codes +@node Quantities and Calculations, Dates, Colors, Formatting codes @subsection Quantities and Calculations -@multitable @columnfractions .3 .2 .5 -@item @strong{Function} @tab @strong{Abbrev.} @tab @strong{Description} -@item @code{amount_expr } @tab @code{} @tab -@item @code{abs} @tab @code{U} @tab -@item @code{commodity } @tab @code{} @tab -@item @code{display_amount } @tab @code{t} @tab -@item @code{display_total } @tab @code{T} @tab -@item @code{floor } @tab @code{} @tab -@item @code{get_at } @tab @code{} @tab -@item @code{is_seq } @tab @code{} @tab -@item @code{market } @tab @code{P} @tab -@item @code{percent } @tab @code{} @tab -@item @code{price } @tab @code{} @tab -@item @code{quantity } @tab @code{} @tab -@item @code{rounded } @tab @code{} @tab -@item @code{truncated } @tab @code{} @tab -@item @code{total_expr } @tab @code{} @tab -@item @code{top_amount } @tab @code{} @tab -@item @code{to_boolean } @tab @code{} @tab -@item @code{to_int } @tab @code{} @tab -@item @code{to_amount } @tab @code{} @tab -@item @code{to_balance } @tab @code{} @tab -@item @code{unrounded } @tab @code{} @tab -@end multitable +@table @code +@item amount_expr +@item abs +@item commodity +@item display_amount +@item display_total +@item floor +@item get_at +@item is_seq +@item market +@item percent +@item price +@item quantity +@item rounded +@item truncated +@item total_expr +@item top_amount +@item to_boolean +@item to_int +@item to_amount +@item to_balance +@item unrounded +@end table -@node Dates, Text Formatting, Quantities and Calculations, New formatting codes -@subsection Dates - -@multitable @columnfractions .3 .2 .5 -@item @strong{Function} @tab @strong{Abbrev.} @tab @strong{Description} -@item @code{date } @tab @code{} @tab -@item @code{format_date } @tab @code{} @tab -@item @code{now } @tab @code{} @tab --> d m -@item @code{today } @tab @code{} @tab -@item @code{to_datetime } @tab @code{} @tab -@item @code{to_date } @tab @code{} @tab -@item @code{value_date } @tab @code{} @tab -@end multitable - -@node Text Formatting, Data File Parsing Information, Dates, New formatting codes -@subsection Text Formatting -@subsubsection Summary -@multitable @columnfractions .6 .4 -@item @strong{Function} @tab @strong{Description} -@item @code{ansify_if(str,color) } @tab Colorize the string -@item @code{justify(str, fwidth, lwidth, right, colorize) } @tab Right or left justify the string. -@item @code{join(str) } @tab Remove line feeds from the input string. Mainly used internally for org-mode output -@item @code{quoted(str) } @tab Returns @code{""}. -@item @code{strip } @tab @code{Removes additional annotations from values.} -@item @code{scrub } @tab @code{S} -@item @code{should_bold } @tab @code{} -@end multitable -@subsubsection Detailed Descriptions +@node Dates, Date and Time Format Codes, Quantities and Calculations, Formatting codes +@subsection Date Functions +The following functions allow you to manipulate and format dates. @table @code -@item ansify_if(value, color) -Surrounds the string representing value with ANSI codes to give it -@code{color} on an TTY display. Has no effect if directed to a file. -@item justify(value, first_width, latter_width, right_justify, colorize) -Right or left justify the string representing @code{value}. The width -of the field in the first line is given by @code{first_width}. For -subsequent lines the width is given by @code{latterwidth}. If -@code{latter_width=-1}, then @code{first_width} is use for all lines. -If @code{right_justify=true} then the field is right justify within the -width of the field. If it is @code{false}, then the field is left -justified and padded to the full width of the field. If @code{colorize} -is true then ledger will honor color settings. -@item join(str) -Replaces line feeds in str with @code{\n}. -@item quoted(str) -Return str surrounded by double quotes, @code{""}. -@item strip(value) -Values can have numerous annotations, such as effective dates and lot -prices. @code{strip} removes these annotations. +@item date +Returns the date of the current transaction +@item format_date(date, "FORMAT STRING") +formats the date using the given format string. +@item now +Returns the current date and time. If the @code{--now} option is +defined it will return that value. +@item today +Returns the current date. If the @code{--now} option is +defined it will return that value. +@item to_datetime +convert a string to a date-time value +@item to_date +convert a string to date value +@item value_date @end table -@node Data File Parsing Information, Misc, Text Formatting, New formatting codes -@subsection Data File Parsing Information - -The format strings in the table below provide locational metadata -regarding the coordinates of entries in the source data file(s) that -generated the posting. - -@subsubsection Summary -@multitable @columnfractions .3 .2 .5 -@item @strong{Function} @tab @strong{Abbrev.} @tab @strong{Description} -@item @code{filename} @tab S @tab name of ledger data file from whence posting came -@item @code{beg_pos} @tab B @tab character position in @code{filename} where entry for posting begins -@item @code{end_pos} @tab E @tab character position in @code{filename} where entry for posting ends -@item @code{beg_line} @tab b @tab line number in @code{filename} where entry for posting begins -@item @code{end_line} @tab e @tab line number in @code{filename} where posting's entry for posting ends -@end multitable - - -@node Misc, , Data File Parsing Information, New formatting codes -@subsection Miscellaneous -@multitable @columnfractions .3 .2 .5 -@item @strong{Function} @tab @strong{Abbrev.} @tab @strong{Description} -@item @code{amount_expr } @tab @code{} @tab -@item @code{abs } @tab @code{} @tab --> U -@item @code{code} @tab @code{} @tab returns the transaction code, the string between the parenthesis after the date. -@item @code{commodity } @tab @code{} @tab -@item @code{display_amount } @tab @code{} @tab --> t -@item @code{display_total } @tab @code{} @tab --> T -@item @code{date } @tab @code{} @tab -@item @code{format_date } @tab @code{} @tab -@item @code{format } @tab @code{} @tab -@item @code{floor } @tab @code{} @tab -@item @code{get_at } @tab @code{} @tab -@item @code{is_seq } @tab @code{} @tab -@item @code{justify } @tab @code{} @tab -@item @code{join } @tab @code{} @tab -@item @code{market --> P } @tab @code{} @tab -@item @code{null } @tab @code{} @tab -@item @code{now --> d m } @tab @code{} @tab -@item @code{options } @tab @code{} @tab -@item @code{post } @tab @code{} @tab -@item @code{percent } @tab @code{} @tab -@item @code{price } @tab @code{} @tab -@item @code{print } @tab @code{} @tab -@item @code{quoted } @tab @code{} @tab -@item @code{quantity } @tab @code{} @tab -@item @code{rounded } @tab @code{} @tab -@item @code{scrub } @tab @code{} @tab -@item @code{strip --> S } @tab @code{} @tab -@item @code{should_bold } @tab @code{} @tab -@item @code{truncated } @tab @code{} @tab -@item @code{total_expr } @tab @code{} @tab -@item @code{today } @tab @code{} @tab -@item @code{top_amount } @tab @code{} @tab -@item @code{to_boolean } @tab @code{} @tab -@item @code{to_int } @tab @code{} @tab -@item @code{to_datetime } @tab @code{} @tab -@item @code{to_date } @tab @code{} @tab -@item @code{to_amount } @tab @code{} @tab -@item @code{to_balance } @tab @code{} @tab -@item @code{to_spring } @tab @code{} @tab -@item @code{to_mask } @tab @code{} @tab -@item @code{to_sequence } @tab @code{} @tab -@item @code{unrounded } @tab @code{} @tab -@item @code{value_date } @tab @code{} @tab -@end multitable +@menu +* Date and Time Format Codes:: +@end menu -@node Date and Time Format Codes, , New formatting codes, Format Strings -@section Date and Time Format Codes +@node Date and Time Format Codes, Text Formatting, Dates, Formatting codes +@subsection Date and Time Format Codes Date and time format are specified as strings of single letter codes preceded by percent signs. Any separator, or no separator can be specified. -@subsection Dates +@subsubsection Days Dates are formed from a combination of day, month and year codes, in whatever order you prefer: -@option{%Y} is keyword for four digit year +@table @code +@item %Y +Four digit year -@option{%y} is keyword for two digit year +@item %y +Two digit year -@option{%m} is keyword for two digit month +@item %m +Two digit month -@option{%d} is keyword for two digit date +@item %d +Two digit date +@end table -@noindent So @code{"%Y%m%d"} yields @code{20111214} which provides a date that is simple to sort. +@noindent So @code{"%Y%m%d"} yields @code{20111214} which provides a date that is simple to sort on. -@subsection Weekdays +@subsubsection Weekdays You can have additional weekday information in your date with @code{%A} as -@option{%m-%d-%Y %A} yields @code{02-10-2010 Wednesday} - -@option{%A %m-%d-%Y} yields @code{Wednesday 02-10-2010} +@table @code +@item %m-%d-%Y %A +yields @code{02-10-2010 Wednesday} +@item %A %m-%d-%Y +yields @code{Wednesday 02-10-2010} +@end table @noindent These are options you can select for weekday -@option{%a} weekday, abbreviated Wed - -@option{%A} weekday, full Wednesday - -@option{%d} day of the month (dd), zero padded 10 - -@option{%e} day of the month (dd) 10 - -@option{%j} day of year, zero padded 000-366 - -@option{%u} day of week starting with Monday (1), i.e. @code{mtwtfss} 3 - -@option{%w} day of week starting with Sunday (0), i.e. @code{smtwtfs} 3 - -@subsection Month +@table @code +@item %a +weekday, abbreviated Wed +@item %A +weekday, full Wednesday +@item %d +day of the month (dd), zero padded 10 +@item %e +day of the month (dd) 10 +@item %j +day of year, zero padded 000-366 +@item %u +day of week starting with Monday (1), i.e. @code{mtwtfss} 3 +@item %w +day of week starting with Sunday (0), i.e. @code{smtwtfs} 3 +@end table +@subsubsection Month You can have additional month information in your date with @code{%B} as +@table @code +@item %m-%d-%Y %B +yields @code{ 02-10-2010 Februrary} -@option{%m-%d-%Y %B} yields @code{ 02-10-2010 Februrary} - -@option{%B %m-%d-%Y} yields @code{February 02-10-2010} - +@item %B %m-%d-%Y +yields @code{February 02-10-2010} +@end table @noindent These are options you can select for month +@table @code +@item %m +@code{mm} month as two digits -@option{%m} @code{mm} month as two digits +@item %b +Locale’s abbreviated month, for example @code{02} might be abbreviated as @code{Feb} -@option{%b} @code{Mon}, locale’s abbreviated Feb +@item %B +Locale’s full month, variable length February +@end table -@option{%B} locale’s full month, variable length February +@subsubsection Miscellaneous Date Codes +Additional date format parameters which can be used : +@table @code +@item %U +week number Sunday as first day of week 01–53 +@item %W +week number Monday as first day of week 01–53 +@item %V +week of the year 01–53 +@item %C +@code{cc} century 00–99 +@item %D +yields @code{mm/dd/yy 02/10/10} +@item %x +locale’s date representation @code{02/10/2010} for the U.S. +@item %F +yields @code{%Y-%m-%d 2010-02-10} +@end table +@menu +* Text Formatting:: +* Data File Parsing Information:: +* Misc:: +@end menu -@subsection Miscellaneous Date Codes -Additional date format parameters which can be used : +@node Text Formatting, Data File Parsing Information, Date and Time Format Codes, Formatting codes +@subsection Text Formatting +The following format functions allow you limited formatting of text: +@table @code +@item ansify_if(value, color) +Surrounds the string representing value with ANSI codes to give it +@code{color} on an TTY display. Has no effect if directed to a file. +@item justify(value, first_width, latter_width, right_justify, colorize) +Right or left justify the string representing @code{value}. The width +of the field in the first line is given by @code{first_width}. For +subsequent lines the width is given by @code{latterwidth}. If +@code{latter_width=-1}, then @code{first_width} is use for all lines. +If @code{right_justify=true} then the field is right justify within the +width of the field. If it is @code{false}, then the field is left +justified and padded to the full width of the field. If @code{colorize} +is true then ledger will honor color settings. +@item join(STR) +Replaces line feeds in @code{STR} with @code{\n}. +@item quoted(STR) +Return @code{STR} surrounded by double quotes, @code{"STR"}. +@item strip(value) +Values can have numerous annotations, such as effective dates and lot +prices. @code{strip} removes these annotations. +@end table -@option{%U} week number Sunday as first day of week 01–53 +@node Data File Parsing Information, , Text Formatting, Formatting codes +@subsection Data File Parsing Information -@option{%W} week number Monday as first day of week 01–53 +The following format strings provide locational metadata +regarding the coordinates of entries in the source data file(s) that +generated the posting. -@option{%V} week of the year 01–53 +@table @code +@item filename +name of ledger data file from whence posting came, abbreviated @code{S} +@item beg_pos +character position in @code{filename} where entry for posting begins, abbreviated @code{B} +@item end_pos +character position in @code{filename} where entry for posting ends, abbreviated @code{E} +@item beg_line +line number in @code{filename} where entry for posting begins, abbreviated @code{b} +@item end_line +line number in @code{filename} where posting's entry for posting ends, abbreviated @code{e} +@end table -@option{%C} @code{cc} century 00–99 -@option{%D} yields @code{mm/dd/yy 02/10/10} -@option{%x} locale’s date representation @code{02/10/2010} for the U.S. -@option{%F} yields @code{%Y-%m-%d 2010-02-10} @node Ledger for Developers, Extending with Python, Format Strings, Top @@ -7547,7 +7590,7 @@ Those tiers are: strings, etc. If you try to apply an operation between two values that makes no sense (like dividing an amount by a balance), an error occurs at runtime, rather than at compile-time (as would happen if you actually tried - to divide an amount_t by a balance_t). + to divide an @code{amount_t} by a @code{balance_t}). This is the core data type for the value expression language. @@ -7566,9 +7609,9 @@ Those tiers are: @item Query expressions Expressions can be onerous to type at the command-line, so there's a - shorthand for reporting called "query expressions". These add no + shorthand for reporting called ``query expressions''. These add no functionality of there own, but are purely translated from the input string - (cash) down to the corresponding value expression (account =~ /cash/). + (cash) down to the corresponding value expression @code{(account =~ /cash/)}. This is a convenience layer. @item Format strings @@ -7576,7 +7619,7 @@ Those tiers are: Format strings let you interpolate value expressions into string, with the requirement that any interpolated value have a string representation. Really all this does is calculate the value expression in the current - report context, call the resulting value's "to_string()" method, and stuffs + report context, call the resulting value's @code{to_string()} method, and stuffs the result into the output string. It also provides printf-like behavior, such as min/max width, right/left justification, etc. @@ -7609,19 +7652,19 @@ Those tiers are: @item The Journal object Finally, all transactions with their postings, and all accounts, are owned - by a journal_t object. This is the go-to object for querying ad reporting + by a @code{journal_t} object. This is the go-to object for querying ad reporting on your data. @item Textual journal parser There is a textual parser, wholly contained in textual.cc, which knows how - to parse text into journal objects, which then get "finalized" and added to + to parse text into journal objects, which then get ``finalized'' and added to the journal. Finalization is the step that enforces the double-entry guarantee. @item Iterators - Every journal object is "iterable", and these iterators are defined in + Every journal object is ``iterable'', and these iterators are defined in iterators.h and iterators.cc. This iteration logic is kept out of the basic journal objects themselves for the sake of modularity. @@ -7629,12 +7672,12 @@ Those tiers are: Another abstraction isolated to its own layer, this class encapsulating the comparison of journal objects, based on whatever value expression the user - passed to --sort. + passed to @code{--sort}. @item Temporaries Many reports bring pseudo-journal objects into existence, like postings - which report totals in a "" account. These objects are created and + which report totals in a @code{} account. These objects are created and managed by a temporaries_t object, which gets used in many places by the reporting filters. @@ -7666,7 +7709,7 @@ Those tiers are: iterator depends on the type of report. This iterator is then walked, and every object yielded from the iterator is - passed to an "item handler", whose type is directly related to the type of + passed to an ``item handler'', whose type is directly related to the type of the iterator. There are many, many item handlers, which can be chained together. Each @@ -7675,22 +7718,22 @@ Those tiers are: filters which compute the running totals; that queue and sort all the input items before playing them back out in a new order; that filter out items which fail to match a predicate, etc. Almost every reporting feature in - Ledger is related to one or more filters. Looking at filters.h, I see over + Ledger is related to one or more filters. Looking at @code{filters.h}, I see over 25 of them defined currently. @item The filter chain How filters get wired up, and in what order, is a complex process based on all the various options specified by the user. This is the job of the - chain logic, found entirely in chain.cc. It took a really long time to get + chain logic, found entirely in @code{chain.cc}. It took a really long time to get this logic exactly write, which is why I haven't exposed this layer to the Python bridge yet. @item Output modules Although filters are great and all, in the end you want to see stuff. This - is the job of special "leaf" filters call output modules. They are - implemented just like a regular filter, but they don't have a "next" filter + is the job of special ``leaf'' filters call output modules. They are + implemented just like a regular filter, but they don't have a ``next'' filter to pass the time on down to. Instead, they are the end of the line and must do something with the item that results in the user seeing something on their screen or in a file. @@ -7714,7 +7757,7 @@ Those tiers are: This creates the global scope object, performs error reporting, and handles command-line options which must precede even the creation of the global - scope, such as --debug. + scope, such as @code{--debug}. @end itemize And that's Ledger in a nutshell. All the rest are details, such as which @@ -7755,7 +7798,7 @@ double-entry accounting: the sum of every transaction must balance to zero, or it is in error. Whenever Ledger encounters a @dfn{null posting} in a transaction, it uses it to balance the remainder. -It is also typical---though not enforced---to think of the first +It is also typical, though not enforced, to think of the first posting as the destination, and the final as the source. Thus, the amount of the first posting is typically positive. Consider: @@ -7779,7 +7822,7 @@ amount of the first posting is typically positive. Consider: @node Comments and meta-data, Specifying Amounts, Journal File Format, Journal File Format @subsection Comments and meta-data -Comments are generally started using a ';'. However, in order to +Comments are generally started using a @code{;}. 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{*}. @@ -7822,13 +7865,13 @@ now, a word must be said about how Ledger stores numbers. Every number parsed by Ledger is stored internally as an infinite-precision rational value. Floating-point math is never used, as it cannot be trusted to maintain precision of values. So, in the -case of @samp{1000.00} above, the internal value is @samp{100000/100}. +case of @code{1000.00} above, the internal value is @code{100000/100}. While rational numbers are great at not losing precision, the question -arises: How should they be displayed? A number like @samp{100000/100} +arises: How should they be displayed? A number like @code{100000/100} is no problem, since it represents a clean decimal fraction. But what -about when the number @samp{1/1} is divided by three? How should one -print @samp{1/3}, an infinitely repeating decimal? +about when the number @code{1/1} is divided by three? How should one +print @code{1/3}, an infinitely repeating decimal? Ledger gets around this problem by rendering rationals into decimal at the last possible moment, and only for display. As such, some @@ -7839,11 +7882,11 @@ rarely, but even then it does not reflect adjustment of the @emph{internal amount}, only the displayed amount. What has still not been answered is how Ledger rounds values. Should -@samp{1/3} be printed as @samp{0.33} or @samp{0.33333}? For +@code{1/3} be printed as @code{0.33} or @code{0.33333}? For commoditized amounts, the number of decimal places is decided by observing how each commodity is used; but in the case of integer amounts, an arbitrary factor must be chosen. Initially, this factor -is six. Thus, @samp{1/3} is printed back as @samp{0.333333}. +is six. Thus, @code{1/3} is printed back as @code{0.333333}. Further, this rounding factor becomes associated with each particular value, and is carried through mathematical operations. For example, if that particular number were multiplied by itself, the decimal @@ -7866,10 +7909,10 @@ characters are allowed in a commodity name, except for the following: @itemize @bullet @item Any kind of white-space @item Numerical digits -@item Punctuation: @samp{.,;:?!} -@item Mathematical and logical operators: @samp{-+*/^&|=} -@item Bracketing characters: @samp{<>[]()}@{@} -@item The at symbol: @samp{@@} +@item Punctuation: @code{.,;:?!} +@item Mathematical and logical operators: @code{-+*/^&|=} +@item Bracketing characters: @code{<>[]()}@{@} +@item The at symbol: @code{@@} @end itemize And yet, any of these may appear in a commodity name if it is @@ -7885,9 +7928,9 @@ part is the commodity. Another feature of commoditized amounts is that they are reported back in the same form as parsed. If you specify dollar amounts using -@samp{$100}, they will print the same; likewise with @samp{100 $} or -@samp{$100.000}. You may even use decimal commas, such as -@samp{$100,00}, or thousand-marks, as in @samp{$10,000.00}. +@code{$100}, they will print the same; likewise with @code{100 $} or +@code{$100.000}. You may even use decimal commas, such as +@code{$100,00}, or thousand-marks, as in @code{$10,000.00}. These display characteristics become associated with the commodity, with the result being that all amounts of the same commodity are reported @@ -7951,7 +7994,7 @@ postings are involved: Assets:Checking @end smallexample -Here the implied cost is @samp{$57.00}, which is entered into the null +Here the implied cost is @code{$57.00}, which is entered into the null posting automatically so that the transaction balances. @node Primary commodities, , Posting costs, Journal File Format @@ -7979,7 +8022,7 @@ on the placement of the commodity in the transaction: @end smallexample The only case where knowledge of primary versus secondary comes into -play is in reports that use the @option{-V} or @option{-B} options. +play is in reports that use the @code{-V} or @code{-B} options. With these, only primary commodities are shown. If a transaction uses only one commodity, this commodity is also @@ -8010,7 +8053,7 @@ interface functions. The Session is where objects live like the Commodity's that Amount's refer to. The make a Session useful, you must read a Journal into it, using the function -`@samp{read_journal}`. This reads Ledger data from the given file, populates a +`@code{read_journal}`. This reads Ledger data from the given file, populates a Journal object within the current Session, and returns a reference to that Journal object. -- cgit v1.2.3 From 3dc538189e64c4bc0c3428e8784fdb1f593304df Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Tue, 23 Oct 2012 12:04:07 -0700 Subject: Formatting cleanup --- doc/ledger3.texi | 87 ++++++++++++++++++++++++++++++-------------------------- 1 file changed, 47 insertions(+), 40 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 531a0870..e377f02d 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -1225,7 +1225,7 @@ For example, you do not need to tell Ledger about the accounts you use. Any time Ledger sees a posting involving an account it knows nothing about, it will create it@footnote{This also means if you misspell an account it will end up getting counted separately from what -you intended. The provided Emacs major mode provides for automatically +you intended. The provided EMACS major mode provides for automatically filling in account names.}. If you use a commodity that is new to Ledger, it will create that commodity, and determine its display characteristics (placement of the symbol before or after the amount, @@ -1242,7 +1242,7 @@ posting. * Journal Format:: * Converting from other formats:: * Archiving Previous Years :: -* Using Emacs:: +* Using EMACS:: @end menu @node Most Basic Entry, Starting up, Keeping a Journal, Keeping a Journal @@ -2250,7 +2250,7 @@ easily be parsed into Ledger format using one of those tools. Some of the more function. -@node Archiving Previous Years , Using Emacs, Converting from other formats, Keeping a Journal +@node Archiving Previous Years , Using EMACS, Converting from other formats, Keeping a Journal @section Archiving Previous Years @@ -2299,7 +2299,7 @@ they were before the data was split. How often should you split your ledger? You never need to, if you don't want to. Even eighty years of data will not slow down ledger -much---and that's just using present day hardware! Or, you can keep +much, and that's just using present day hardware! Or, you can keep the previous and current year in one file, and each year before that in its own file. It's really up to you, and how you want to organize your finances. For those who also keep an accurate paper trail, it @@ -2309,45 +2309,52 @@ any electronic statements received during the year. In the arena of organization, just keep in mind this maxim: Do whatever keeps you doing it. -@node Using Emacs, , Archiving Previous Years , Keeping a Journal -@section Using Emacs to Maintain Your Journal -@cindex Emacs +@node Using EMACS, , Archiving Previous Years , Keeping a Journal +@section Using EMACS to Maintain Your Journal +@cindex EMACS @menu -* running ledger-mode:: +* Running ledger-mode:: * Working with entries:: * Reconciling accounts:: * Generating Reports:: @end menu -@node running ledger-mode, Working with entries, Using Emacs, Using Emacs -@subsection Running ledger-mode +@node Running ledger-mode, Working with entries, Using EMACS, Using EMACS +@subsection Running ledger-mode in EMACS Journal files are simple free text files easily modified by any text -editor. A special mode for Emacs is included with the source +editor. A special mode for EMACS is included with the source distribution. -@cindex Emacs .emacs file -To use the Emacs mode, copy the several lisp files from the source lisp -directory your your @file{site-lisp} directory and add the following line -to your @file{.emacs} (or equivalent, @file{~/Aquamacs/Preferences.el} -for Aquamacs on Mac OS X) +@cindex EMACS .emacs file + +Add the following line to your @file{.emacs} (or equivalent, +@file{~/Aquamacs/Preferences.el} for Aquamacs on Mac OS X) +@smallexample +(load "ldg-new") +@end smallexample + +Copy the several lisp files from the source lisp directory your your +@file{site-lisp} directory, or add the ledger lisp source directory to +your EMACS load path by adding: @smallexample -(load "ledger") +(add-to-list 'load-path "~/ledger/lisp") @end smallexample +@noindent to your @file{.emacs} file. To trigger ledger mode when you visit a journal file, the first line of each of your journal files should be: @smallexample ; -*-ledger-*- @end smallexample -To enter ledger-mode on a new file, type M-x ledger-mode. +To enter ledger-mode on a new file, type @command{M-x ledger-mode}. -Once you have loaded a Journal file into Emacs, you have several +Once you have loaded a Journal file into EMACS, you have several commands available to make entering, clearing and reconciling transactions and producing reports: -@cindex Emacs commands +@cindex EMACS commands @table @code @item C-i or auto complete entry @@ -2387,7 +2394,7 @@ kill the ledger report buffer * Generating Reports:: @end menu -@node Working with entries, Reconciling accounts, running ledger-mode, Using Emacs +@node Working with entries, Reconciling accounts, Running ledger-mode, Using EMACS @subsection Working with entries @menu * Manual Entry Support:: @@ -2405,13 +2412,13 @@ kill the ledger report buffer In most financial programs, some sort of auto-completion is available to save typing and improve accuracy. Ledger doesn't leave you hanging, @code{ledger-mode} provides tab completion on all portions of an entry. -Type a portion of the payee and hit , and @code{ledger-mode} will +Type a portion of the payee and hit @code{}, and @code{ledger-mode} will suggest a completion. When filling in the account type the first few -letters followed by a and the account will be filled in. For +letters followed by a @code{} and the account will be filled in. For example typing @code{ExAuF} would yield @code{Expenses:Auto:Fuel} if you had previously used that account in this journal. If there are more than one account with similar starting, -hitting multiple times will iterate through them. This is a good +hitting @code{} multiple times will iterate through them. This is a good habit to get in to prevent misspellings of accounts. Remember Ledger does not validate the names of payees or account so a misspelled account will be interpreted as a new account by ledger. @@ -2419,10 +2426,10 @@ will be interpreted as a new account by ledger. @node Automagically Adding new entries, Clearing Transactions, Manual Entry Support, Working with entries @subsubsection Automagically Adding new entries -@cindex new transactions in Emacs -@cindex Emacs, adding new transactions +@cindex new transactions in EMACS +@cindex EMACS, adding new transactions @code{C-c C-a} will run the @code{ledger entry} command (@pxref{entry -and xact}) from within Emacs. When typed, the mini-buffer will appear +and xact}) from within EMACS. When typed, the mini-buffer will appear with the current year and month, waiting for you to enter the day and the payee. Ledger will generate a new entry based on the most recent entry for that payee, using the amount and accounts from that @@ -2439,7 +2446,7 @@ current year and month. If you complete the mini-buffer entry by typing @smallexample Entry: 2011/11/28 viva food 34 tip 7 @end smallexample -@noindent Emacs will add the following entry to your journal: +@noindent EMACS will add the following entry to your journal: @smallexample 2011/11/30 Viva Italiano Expenses:Food $34.00 @@ -2450,8 +2457,8 @@ Entry: 2011/11/28 viva food 34 tip 7 ordered by date, not necessarily at the bottom of the file. @node Clearing Transactions, , Automagically Adding new entries, Working with entries @subsubsection Clearing Transactions and Postings -@cindex clearing transactions in Emacs -@cindex Emacs, clear transaction +@cindex clearing transactions in EMACS +@cindex EMACS, clear transaction @code{C-c C-e} will place an asterisk after the date in the current transaction. The tells ledger the transaction has been cleared through your bank (or whatever else you want the concept to mean) @@ -2473,13 +2480,13 @@ If, for some reason you need to clear a specific posting in the transaction you can type @code{C-c C-c} and the posting at point will be toggled. -@node Reconciling accounts, Generating Reports, Working with entries, Using Emacs +@node Reconciling accounts, Generating Reports, Working with entries, Using EMACS @subsection Reconciling accounts In the reconcile buffer, use SPACE to toggle the cleared status of a transaction, C-x C-s to save changes (to the ledger file as well). -@node Generating Reports, , Reconciling accounts, Using Emacs +@node Generating Reports, , Reconciling accounts, Using EMACS @subsection Generating Reports The ledger reports command asks the user to select a report to run then @@ -4039,7 +4046,7 @@ file whose formatting has gotten out of hand. @menu * Comma Separated Variable files:: * The emacs command:: -* Emacs org mode:: +* EMACS org mode:: * The pricemap Command:: * The xml Command:: * prices and pricedb:: @@ -4153,11 +4160,11 @@ passed through @code{ledger print} a second time if you want to match on the new payee field. During the @code{ledger convert} run only the original payee name as specified in the csv data seems to be used. -@node The emacs command, Emacs org mode, Comma Separated Variable files, Reports in other Formats +@node The emacs command, EMACS org mode, Comma Separated Variable files, Reports in other Formats @subsection The @code{emacs} command The @command{emacs} command outputs results in a form that can be read -directly by Emacs Lisp. The format of the @code{sexp} is: +directly by EMACS Lisp. The format of the @code{sexp} is: @smallexample ((BEG-POS CLEARED DATE CODE PAYEE @@ -4165,10 +4172,10 @@ directly by Emacs Lisp. The format of the @code{sexp} is: ...) ; list of transactions @end smallexample -@node Emacs org mode, The pricemap Command, The emacs command, Reports in other Formats -@subsection Emacs @code{org} Mode +@node EMACS org mode, The pricemap Command, The emacs command, 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 +EMACS org mode. More details on using org mode can be found at @url{http://www.orgmode.org}. Org mode has a sub-system known as Babel which allows for literate @@ -4475,7 +4482,7 @@ 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 The pricemap Command, The xml Command, Emacs org mode, Reports in other Formats +@node The pricemap Command, The xml Command, EMACS org mode, Reports in other Formats @subsection The @code{pricemap} Command If you have the @code{graphviz} graph visualization package installed, ledger @@ -5011,7 +5018,7 @@ commands. @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{xml} @tab Produce XML output of the register command -@item @code{emacs} @tab Produce Emacs lisp output +@item @code{emacs} @tab Produce EMACS lisp output @item @code{equity} @tab Print account balances as transactions @item @code{prices} @tab Print price history for matching commodities @item @code{pricedb} @tab Print price history for matching commodities in ledger readable format -- cgit v1.2.3 From bd3c13e2a2962930a4d06f4832ec0b1e2b8a845a Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Fri, 26 Oct 2012 10:49:22 -0700 Subject: Documented removal of draft and lisp commands in the 2.6 changes chapter --- doc/ledger3.texi | 2 ++ 1 file changed, 2 insertions(+) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index e377f02d..ecd4947f 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -8199,6 +8199,8 @@ need to create sums of multiple commodities, use a Balance. For example: @itemize @item OFX support has been removed from Ledger 3.0 @item single character value expressions are deprecated and should be changed to the new value expressions available in 3.0 +@item @code{draft} command is no longer supported, use @code{entry} or @code{exact} +@item @code{lisp} command is no longer supported, use @code{emacs}. @end itemize @node Example Data File, Miscellaneous Notes, Major Changes from version 2.6, Top -- cgit v1.2.3 From 0ff33003e8ea5e6278c5c7aec29e812d44485944 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Fri, 26 Oct 2012 20:13:20 -0700 Subject: Minor grammatical fixes --- doc/ledger3.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index ecd4947f..b60a0f5c 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -7800,7 +7800,7 @@ useful to follow standard accounting practice (@pxref{Principles of Accounting}). Since an amount is missing from the second posting, it is assumed to -be the inverse of the first. This guarantee the cardinal rule of +be the inverse of the first. This guarantees the cardinal rule of double-entry accounting: the sum of every transaction must balance to zero, or it is in error. Whenever Ledger encounters a @dfn{null posting} in a transaction, it uses it to balance the remainder. -- cgit v1.2.3 From 71ecd4ef792549af652431550e7b8b2f4fe93d50 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Thu, 1 Nov 2012 16:03:58 -0700 Subject: re-fixed draft and lisp command documentation --- doc/ledger3.texi | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index b60a0f5c..891cc1af 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -4045,14 +4045,14 @@ file whose formatting has gotten out of hand. @section Reports in other Formats @menu * Comma Separated Variable files:: -* The emacs command:: +* The lisp command:: * EMACS org mode:: * The pricemap Command:: * The xml Command:: * prices and pricedb:: @end menu -@node Comma Separated Variable files, The emacs command, Reports in other Formats, Reports in other Formats +@node Comma Separated Variable files, The lisp command, Reports in other Formats, Reports in other Formats @subsection Comma Separated Variable files @menu * The csv command:: @@ -4160,10 +4160,10 @@ passed through @code{ledger print} a second time if you want to match on the new payee field. During the @code{ledger convert} run only the original payee name as specified in the csv data seems to be used. -@node The emacs command, EMACS org mode, Comma Separated Variable files, Reports in other Formats -@subsection The @code{emacs} command +@node The lisp command, EMACS org mode, Comma Separated Variable files, Reports in other Formats +@subsection The @code{lisp} command -The @command{emacs} command outputs results in a form that can be read +The @command{lisp} command outputs results in a form that can be read directly by EMACS Lisp. The format of the @code{sexp} is: @smallexample @@ -4172,7 +4172,9 @@ directly by EMACS Lisp. The format of the @code{sexp} is: ...) ; list of transactions @end smallexample -@node EMACS org mode, The pricemap Command, The emacs command, Reports in other Formats +@noindent @code{emacs{ can also be used as asynonym for @code{lisp} + +@node EMACS org mode, The pricemap Command, The lisp command, 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 @@ -4682,11 +4684,11 @@ Report all commodities present in the journals under consideration. @node entry and xact, payees, commodities, Reports about your Journals -@subsection @command{entry} and @command{xact} +@subsection @command{draft}, @command{entry} and @command{xact} -The @code{entry} and @command{xact} commands simplify the creation of -new transactions. It works on the principle that 80% of all postings -are variants of earlier postings. Here's how it works: +The @code{draft}, @code{entry} and @command{xact} commands simplify the +creation of new transactions. It works on the principle that 80% of all +postings are variants of earlier postings. Here's how it works: Say you currently have this posting in your ledger file: @@ -8199,8 +8201,6 @@ need to create sums of multiple commodities, use a Balance. For example: @itemize @item OFX support has been removed from Ledger 3.0 @item single character value expressions are deprecated and should be changed to the new value expressions available in 3.0 -@item @code{draft} command is no longer supported, use @code{entry} or @code{exact} -@item @code{lisp} command is no longer supported, use @code{emacs}. @end itemize @node Example Data File, Miscellaneous Notes, Major Changes from version 2.6, Top -- cgit v1.2.3 From dc24ea721758b4a0121c78c4737492041a8dd093 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Tue, 6 Nov 2012 14:03:49 -0700 Subject: Fixe } bug --- doc/ledger3.texi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 891cc1af..52f6b79f 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -2177,7 +2177,7 @@ assertions are not called if no value is given. @item test @c instance_t::comment_directive in textual.cc -This is a synonym for @code{comment} and must be closed by and @code{end} tag. +This is a synonym for @code{comment} and must be closed by an @code{end} tag. @item year @c instance_t::year_directive in textual.cc @@ -4172,7 +4172,7 @@ directly by EMACS Lisp. The format of the @code{sexp} is: ...) ; list of transactions @end smallexample -@noindent @code{emacs{ can also be used as asynonym for @code{lisp} +@noindent @code{emacs} can also be used as asynonym for @code{lisp} @node EMACS org mode, The pricemap Command, The lisp command, Reports in other Formats @subsection EMACS @code{org} Mode -- cgit v1.2.3 From 49983e2870b6f39a6de1bbb1b8914035a79ac737 Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Sat, 10 Nov 2012 11:57:34 +0100 Subject: Correct typos --- doc/ledger3.texi | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 52f6b79f..f99504f0 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -4119,7 +4119,7 @@ interpret the dates. Importing csv files is a lot of work, and but is very amenable to scripting. If there are columns in the bank data you would like to keep in your -ledger data, besides the primary fileds described above, you can name +ledger data, besides the primary fields described above, you can name them in the field descriptor list and Ledger will include them in the transaction as meta data if it doesn't recognize the field name. For example, if you want to capture the bank transaction number and it @@ -4131,7 +4131,7 @@ transid,date,payee,note,amount,,,code, @end smallexample Ledger will include @code{; transid: 767718} in the first transaction is -fromthe file above. +from the file above. The @code{convert} command accepts three options, the most important ones are @code{--invert} which inverts the amount field, and @@ -4172,7 +4172,7 @@ directly by EMACS Lisp. The format of the @code{sexp} is: ...) ; list of transactions @end smallexample -@noindent @code{emacs} can also be used as asynonym for @code{lisp} +@noindent @code{emacs} can also be used as a synonym for @code{lisp} @node EMACS org mode, The pricemap Command, The lisp command, Reports in other Formats @subsection EMACS @code{org} Mode @@ -5595,12 +5595,12 @@ ASK JOHN commodity. The latest available price is used. @item --flat - force the full names of accounts to be used inthe + force the full names of accounts to be used in the balance report. The balance report will not use an indented tree. @item --force-color output tty color codes even if the tty doesn't -support them. Ueful for TTY that don't advertise their capabilities +support them. Useful for TTY that don't advertise their capabilities correctly. @item --force-pager @@ -5707,7 +5707,7 @@ Specify the width of the Meta column used for the @code{--meta} options. @item --monthly -synonymn for @code{--period "monthly"} +synonym for @code{--period "monthly"} @item --no-color @@ -5735,7 +5735,7 @@ This is a postings predicate that applies after certain transforms have been executed, such as periodic gathering. @item --output -Redriect the output of ledger to the file defined in @file{PATH}. +Redirect the output of ledger to the file defined in @file{PATH}. @item --pager @@ -5756,8 +5756,8 @@ Set the number of columns dedicated to the payee in the register report. Use only postings that are marked pending @item --percent -Calculate the percentage value of each account in a blance reports. -Only works for account that have a single commoditiy. +Calculate the percentage value of each account in a balance reports. +Only works for account that have a single commodity. @item --period @@ -5875,14 +5875,14 @@ FIX THIS ENTRY @item --tail -report only the last @code{INT} entries. Only useful ona register report. +report only the last @code{INT} entries. Only useful on a register report. @item --total-data FIX THIS ENTRY @item --total -Define a vlaue expression used to calulate the total in reports. +Define a value expression used to calculate the total in reports. @item --total-width Set the width of the total field in the register report. @@ -5919,14 +5919,14 @@ Perform all calculations without rounding and display results to full precision. @item --weekly -synonymn for @code{--period "weekly"} +synonym for @code{--period "weekly"} @item --wide lets the register report use 132 columns. Identical to @code{--columns "132"} @item --yearly -synonymn for @code{--period "yearly"} +synonym for @code{--period "yearly"} @end table @@ -6375,13 +6375,13 @@ Sets the format for total plots, using the @code{-J} option. The default is: "%(format_date(date, \"%Y-%m-%d\")) %(quantity(scrub(display_total)))\n" @end smallexample @item --pricedb-format STR -Sets the format expected for the histroical price file. The default is +Sets the format expected for the historical price file. The default is @smallexample "P %(datetime) %(display_account) %(scrub(display_amount))\n" @end smallexample @item --prices-format STR -Sets the format for the @command{prices} report. The deault is: +Sets the format for the @command{prices} report. The default is: @smallexample "%(date) %-8(display_account) %(justify(scrub(display_amount), 12, 2 + 9 + 8 + 12, true, color))\n" @@ -7231,7 +7231,7 @@ Inserts the ending line of that transaction within the file. @c @code{%D} gives the user more control over the way dates are output. @item d -Returns the data accoridng to the default format. If the transaction +Returns the data according to the default format. If the transaction has an effective date, it prints @code{[ACTUAL_DATE=EFFECTIVE_DATE]}. @item X @@ -7284,7 +7284,7 @@ same format string is used for all postings. @section --balance-format As an example of how flexible the @code{--format} strings can be, the default -balance format looks like this (the various functions are descirbed later): +balance format looks like this (the various functions are described later): @smallexample "%(justify(scrub(display_total), 20, -1, true, color))" -- cgit v1.2.3 From 2823c99107c5ea90b70350571d03fc566021e5a1 Mon Sep 17 00:00:00 2001 From: Karl Fogel Date: Sun, 16 Dec 2012 15:31:32 -0600 Subject: Update obsolete wording in documentation for 'year' command directive. --- doc/ledger3.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index f99504f0..1c588636 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -2182,7 +2182,7 @@ This is a synonym for @code{comment} and must be closed by an @code{end} tag. @item year @c instance_t::year_directive in textual.cc Denotes the year used for all subsequent transactions that give a date -without a year. The year should appear immediately after the Y, for +without a year. The year should appear immediately after the directive, for example: @code{year 2004}. This is useful at the beginning of a file, to specify the year for that file. If all transactions specify a year, however, this command has no effect. -- cgit v1.2.3 From ea09a8d50720f0ca42cee46d017e111a4349fa97 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 11 Jan 2013 10:07:58 -0800 Subject: escape @ characters properly so they show up --- doc/ledger3.texi | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index f99504f0..caec7667 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -1312,9 +1312,9 @@ your opening balance entry could look like this: Assets:Joint Checking $800.14 Assets:Other Checking $63.44 Assets:Savings $2805.54 - Assets:Investments:401K:Deferred 100.0000 VIFSX @ $80.5227 - Assets:Investments:401K:Matching 50.0000 VIFSX @ $83.7015 - Assets:Investments:IRA 250.0000 VTHRX @ $20.5324 + Assets:Investments:401K:Deferred 100.0000 VIFSX @@ $80.5227 + Assets:Investments:401K:Matching 50.0000 VIFSX @@ $83.7015 + Assets:Investments:IRA 250.0000 VTHRX @@ $20.5324 Liabilities:Mortgage $-175634.88 Liabilities:Car Loan $-3494.26 Liabilities:Visa -$1762.44 @@ -2970,12 +2970,12 @@ resulting posting cost is $50.00 per share. @node Explicit posting costs, Posting cost expressions, Posting cost, Transactions @section Explicit posting costs -You can make any posting's cost explicit using the @ symbol after the amount +You can make any posting's cost explicit using the @@ symbol after the amount or amount expression: @smallexample 2012-03-10 My Broker - Assets:Brokerage 10 AAPL @ $50.00 + Assets:Brokerage 10 AAPL @@ $50.00 Assets:Brokerage:Cash $-500.00 @end smallexample @@ -2984,7 +2984,7 @@ the first posting's cost, you can elide the other amount: @smallexample 2012-03-10 My Broker - Assets:Brokerage 10 AAPL @ $50.00 + Assets:Brokerage 10 AAPL @@ $50.00 Assets:Brokerage:Cash @end smallexample @@ -3029,7 +3029,7 @@ You can even have both: @node Total posting costs, Virtual posting costs, Posting cost expressions, Transactions @section Total posting costs -The cost figure following the @ character specifies the @emph{per-unit} price for +The cost figure following the @@ character specifies the @emph{per-unit} price for the commodity being transferred. If you'd like to specify the total cost instead, use @@@@: @@ -3149,7 +3149,7 @@ Plus, it comes with dangers. This works fine: @smallexample 2012-04-10 My Broker - Assets:Brokerage 10 AAPL @ $50.00 + Assets:Brokerage 10 AAPL @@ $50.00 Assets:Brokerage:Cash $750.00 2012-04-10 My Broker @@ -3167,7 +3167,7 @@ Plus, it comes with dangers. This works fine: @smallexample 2012-04-10 My Broker - Assets:Brokerage 10 AAPL @ $50.00 + Assets:Brokerage 10 AAPL @@ $50.00 Assets:Brokerage:Cash $750.00 2012-04-10 My Broker @@ -3192,7 +3192,7 @@ following two transactions are equivalent: @smallexample 2012-04-10 My Broker - Assets:Brokerage 10 AAPL @ $50.00 + Assets:Brokerage 10 AAPL @@ $50.00 Assets:Brokerage:Cash $750.00 2012-04-10 My Broker @@ -3257,7 +3257,7 @@ that dates are parsed in value expressions): You can also associate arbitrary notes for your own record keeping in parentheses, and reveal them with --lot-notes. One caveat is that the note -cannot begin with an @ character, as that would indicate a virtual cost: +cannot begin with an @@ character, as that would indicate a virtual cost: @smallexample 2012-04-10 My Broker @@ -4914,7 +4914,7 @@ model transaction: --- Context is first posting of the following transaction --- 2004/05/27 Book Store ; This note applies to all postings. :SecondTag: - Expenses:Books 20 BOOK @ $10 + Expenses:Books 20 BOOK @@ $10 ; Metadata: Some Value ; Typed:: $100 + $200 ; :ExampleTag: -- cgit v1.2.3 From 5d1971ee51a18f927185d20fb0a4426d8f08aa86 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Fri, 25 Jan 2013 07:26:55 -0700 Subject: Added Huququ'llah calculation back in. Example was inadvertantly removed while writing the Automated Transaction section. --- doc/ledger3.texi | 104 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 91 insertions(+), 13 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index b8aaa49b..f60bb26e 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -1814,7 +1814,7 @@ sign. After this initial line there should be a set of one or more postings, just as if it were normal transaction. If the amounts of the postings have no commodity, they will be applied as modifiers to -whichever real posting is matched by the value expression(See @pxref{Automated transactions}). +whichever real posting is matched by the value expression(See @pxref{Automated Transactions}). @item ~ A period transaction. A period expression must appear after the tilde. @@ -2542,7 +2542,7 @@ kill the report buffer * Lot dates:: * Lot notes:: * Lot value expressions:: -* Automated transactions:: +* Automated Transactions:: @end menu @node Basic format, Eliding amounts, Transactions , Transactions @@ -3271,7 +3271,7 @@ all optional. To show all lot information in a report, use @code{--lots}. -@node Lot value expressions, Automated transactions, Lot notes, Transactions +@node Lot value expressions, Automated Transactions, Lot notes, Transactions @section Lot value expressions Normally when you ask Ledger to display the values of commodities held, it @@ -3338,8 +3338,8 @@ In most cases, it is simplest to either use explicit amounts in your valuation expressions, or just pass the arguments down to market after modifying them to suit your needs. -@node Automated transactions, , Lot value expressions, Transactions -@section Automated transactions +@node Automated Transactions, , Lot value expressions, Transactions +@section Automated Transactions An automated transaction is a special kind of transaction which adds its postings to other transactions any time one of that other transactions' @@ -3391,9 +3391,10 @@ transaction. * State flags:: * Effective Dates:: * Periodic Transactions:: +* Concrete Example of Automated Transactions:: @end menu -@node Amount multipliers, Accessing the matching posting's amount, Automated transactions, Automated transactions +@node Amount multipliers, Accessing the matching posting's amount, Automated Transactions, Automated Transactions @subsection Amount multipliers As a special case, if an automated transaction's posting's amount (phew) has @@ -3422,7 +3423,7 @@ Then the latter transaction turns into this during parsing: Bar $-1000.00 @end smallexample -@node Accessing the matching posting's amount, Referring to the matching posting's account, Amount multipliers, Automated transactions +@node Accessing the matching posting's amount, Referring to the matching posting's account, Amount multipliers, Automated Transactions @subsection Accessing the matching posting's amount If you use an amount expression for an automated transaction's posting, that @@ -3449,7 +3450,7 @@ This becomes: (Foo) $-40.00 @end smallexample -@node Referring to the matching posting's account, Applying metadata to every matched posting, Accessing the matching posting's amount, Automated transactions +@node Referring to the matching posting's account, Applying metadata to every matched posting, Accessing the matching posting's amount, Automated Transactions @subsection Referring to the matching posting's account Sometimes want to refer to the account that matched in some way within the @@ -3474,7 +3475,7 @@ Becomes: Assets:Cash $-20.00 @end smallexample -@node Applying metadata to every matched posting, Applying metadata to the generated posting, Referring to the matching posting's account, Automated transactions +@node Applying metadata to every matched posting, Applying metadata to the generated posting, Referring to the matching posting's account, Automated Transactions @subsection Applying metadata to every matched posting If the automated transaction has a transaction note, that note is copied @@ -3500,7 +3501,7 @@ Becomes: Assets:Cash $-20.00 @end smallexample -@node Applying metadata to the generated posting, State flags, Applying metadata to every matched posting, Automated transactions +@node Applying metadata to the generated posting, State flags, Applying metadata to every matched posting, Automated Transactions @subsection Applying metadata to the generated posting If the automated transaction's posting has a note, that note is carried to the @@ -3530,14 +3531,14 @@ This is slightly different from the rules for regular transaction notes, in that an automated transaction's note does not apply to every posting within the automated transaction itself, but rather to every posting it matches. -@node State flags, Effective Dates, Applying metadata to the generated posting, Automated transactions +@node State flags, Effective Dates, Applying metadata to the generated posting, Automated Transactions @subsection State flags Although you cannot mark an automated transaction as a whole as cleared or pending, you can mark its postings with a * or ! before the account name, and that state flag gets carried to the generated posting. -@node Effective Dates, Periodic Transactions, State flags, Automated transactions +@node Effective Dates, Periodic Transactions, State flags, Automated Transactions @subsection Effective Dates @cindex effective dates @@ -3604,7 +3605,7 @@ automatic $37.50 deficit like you should, while your checking account really knows that it debited $225 this month. -@node Periodic Transactions, , Effective Dates, Automated transactions +@node Periodic Transactions, Concrete Example of Automated Transactions, Effective Dates, Automated Transactions @subsection Periodic Transactions A periodic transaction starts with a ~ followed by a period expression. @@ -3614,6 +3615,83 @@ have no effect without the @code{--budget} option specified. See @ref{Budgeting and Forecasting} for examples and details. +@node Concrete Example of Automated Transactions, , Periodic Transactions, Automated Transactions +@subsection Concrete Example of Automated Transactions + + +As a Bahá'í, I need to compute Huqúqu'lláh whenever I acquire assets. +It is similar to tithing for Jews and Christians, or to Zakát for +Muslims. The exact details of computing Huqúqu'lláh are somewhat +complex, but if you have further interest, please consult the Web. + +Ledger makes this otherwise difficult law very easy. Just set up an +automated posting at the top of your ledger file: + +@smallexample +; This automated transaction will compute Huqúqu'lláh based on this +; journal's postings. Any that match will affect the +; Liabilities:Huququ'llah account by 19% of the value of that posting. + += /^(?:Income:|Expenses:(?:Business|Rent$|Furnishings|Taxes|Insurance))/ + (Liabilities:Huququ'llah) 0.19 +@end smallexample + +This automated posting works by looking at each posting in the +ledger file. If any match the given value expression, 19% of the +posting's value is applied to the @samp{Liabilities:Huququ'llah} +account. So, if $1000 is earned from @samp{Income:Salary}, $190 is +added to @samp{Liabilities:Huqúqu'lláh}; if $1000 is spent on Rent, +$190 is subtracted. The ultimate balance of Huqúqu'lláh reflects how +much is owed in order to fulfill one's obligation to Huqúqu'lláh. +When ready to pay, just write a check to cover the amount shown in +@samp{Liabilities:Huququ'llah}. That transaction would look like: + +@smallexample +2003/01/01 (101) Baha'i Huqúqu'lláh Trust + Liabilities:Huququ'llah $1,000.00 + Assets:Checking +@end smallexample + +That's it. To see how much Huqúq is currently owed based on your +ledger transactions, use: + +@smallexample +ledger balance Liabilities:Huquq +@end smallexample + +This works fine, but omits one aspect of the law: that Huquq is only +due once the liability exceeds the value of 19 mithqáls of gold (which +is roughly 2.22 ounces). So what we want is for the liability to +appear in the balance report only when it exceeds the present day +value of 2.22 ounces of gold. This can be accomplished using the +command: + +@smallexample +ledger -Q -t "/Liab.*Huquq/?(a/P@{2.22 AU@}<=@{-1.0@}&a):a" -s bal liab +@end smallexample + +With this command, the current price for gold is downloaded, and the +Huqúqu'lláh is reported only if its value exceeds that of 2.22 ounces +of gold. If you wish the liability to be reflected in the parent +subtotal either way, use this instead: + +@smallexample +ledger -Q -T "/Liab.*Huquq/?(O/P@{2.22 AU@}<=@{-1.0@}&O):O" -s bal liab +@end smallexample + +In some cases, you may wish to refer to the account of whichever +posting matched your automated transaction's value expression. To do +this, use the special account name @samp{$account}: + +@smallexample += /^Some:Long:Account:Name/ + [$account] -0.10 + [Savings] 0.10 +@end smallexample + +This example causes 10% of the matching account's total to be deferred +to the @samp{Savings} account---as a balanced virtual posting, +which may be excluded from reports by using @option{--real}. -- cgit v1.2.3 From b9dbf54d9a5d0002e379263b4407450074e45211 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Tue, 29 Jan 2013 13:13:30 -0700 Subject: Improved emacs section. Now documents all behavior. --- doc/ledger3.texi | 66 +++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 49 insertions(+), 17 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index f60bb26e..2e0f9ed5 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -2325,7 +2325,9 @@ doing it. Journal files are simple free text files easily modified by any text editor. A special mode for EMACS is included with the source -distribution. +distribution. This mode provides syntax highlighting, a reconcile mode +and a report mode. This makes it quote possible to use ledger without +ever leaving EMACS. @cindex EMACS .emacs file @@ -2335,7 +2337,7 @@ Add the following line to your @file{.emacs} (or equivalent, (load "ldg-new") @end smallexample -Copy the several lisp files from the source lisp directory your your +Copy the several lisp files (@file{ldg-*.el}) from the source lisp directory your your @file{site-lisp} directory, or add the ledger lisp source directory to your EMACS load path by adding: @smallexample @@ -2352,7 +2354,8 @@ To enter ledger-mode on a new file, type @command{M-x ledger-mode}. Once you have loaded a Journal file into EMACS, you have several commands available to make entering, clearing and reconciling -transactions and producing reports: +transactions and producing reports (these are also available from the +menu if you can't remember the key combinations): @cindex EMACS commands @table @code @@ -2431,10 +2434,11 @@ will be interpreted as a new account by ledger. @code{C-c C-a} will run the @code{ledger entry} command (@pxref{entry and xact}) from within EMACS. When typed, the mini-buffer will appear with the current year and month, waiting for you to enter the day and -the payee. Ledger will generate a new entry based on the most recent -entry for that payee, using the amount and accounts from that -transaction. If you have a new amount simply type the amount after the -payee. For example, if your journal contains an entry +the payee, and optionally, a commoditized amount. Ledger will generate +a new entry based on the most recent entry for that payee, using the +amount and accounts from that transaction. If you have a new amount +simply type the amount after the payee. For example, if your journal +contains an entry @smallexample 2011/11/25 Viva Italiano Expenses:Food $12.45 @@ -2454,7 +2458,10 @@ Entry: 2011/11/28 viva food 34 tip 7 Liabilities:MasterCard @end smallexample @noindent Notice that the entry will appear at the correct place in the journal -ordered by date, not necessarily at the bottom of the file. +ordered by date, not at the bottom of the file. If you need to include +spaces in the payee name, then surrond the name of the payee with double +quotes, otherwise ledger will interpret the second part of the name as +an account. @node Clearing Transactions, , Automagically Adding new entries, Working with entries @subsubsection Clearing Transactions and Postings @cindex clearing transactions in EMACS @@ -2483,21 +2490,46 @@ toggled. @node Reconciling accounts, Generating Reports, Working with entries, Using EMACS @subsection Reconciling accounts -In the reconcile buffer, use SPACE to toggle the cleared status of a -transaction, C-x C-s to save changes (to the ledger file as well). +Enter the reconcile mode using the menu entry, or @code{C-c C-r}. Emacs +will prompt you for an account name, then display a second buffer with +all of the uncleared transactions. The reconcile buffer has several functions: +@table @code + @item SPACE + toggles the cleared status of a transaction, and show cleared balance inthe minibuffer + @item RETURN + moves the cursor to that transaction in the ledger. + @item C-x C-s + to save changes (to the ledger file as well). + @item q + quite the reconcile mode + @item n p + next line or previous line + @item A + add entry + @item D + delete entry + @item C-l + refresh display +@end table @node Generating Reports, , Reconciling accounts, Using EMACS @subsection Generating Reports The ledger reports command asks the user to select a report to run then creates a report buffer containing the results of running the associated -command line. Its' behavior is modified by a prefix argument which, -when given, causes the generated command line that will be used to -create the report to be presented for editing before the report is -actually run. Arbitrary unnamed command lines can be run by specifying -an empty name for the report. The command line used can later be named -and saved for future use as a named report from the generated reports -buffer. +command line. This allows you to run frequently used reports without +retyping the command line, or writing shell scripts for simple one line +commands. + +To generate a report, select the @code{Run Reports} menu, or type +@code{C-c C-o C-r}. Emacs will prompt for a report name. If it +recognizes the name it will run the report again. If it is a new name, +or blank it will respond by giving you an example command line to edit. +Hitting return willrun the report and present it in a new buffer. + +If you have given it a new name, then @code{s} will save the report for +future use. + In a report buffer, the following keys are available: @table @code -- cgit v1.2.3 From 2ecb03878fe948167b1e3049f35e77c750714852 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Tue, 29 Jan 2013 13:26:31 -0700 Subject: Documented the tags command. Documented that the account and commodities command now sort. --- doc/ledger3.texi | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 2e0f9ed5..377d740c 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -2574,7 +2574,7 @@ kill the report buffer * Lot dates:: * Lot notes:: * Lot value expressions:: -* Automated Transactions:: +* Automated Transactions:: @end menu @node Basic format, Eliding amounts, Transactions , Transactions @@ -4776,6 +4776,7 @@ database files. @menu * accounts:: * commodities:: +* tags:: * entry and xact:: * payees:: @end menu @@ -4785,15 +4786,27 @@ database files. 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. +accounts matching the regex. The output is sorted by name. Using the +@code{--count} option will tell you haw many entries use each account. -@node commodities, entry and xact, accounts, Reports about your Journals +@node commodities, tags, accounts, Reports about your Journals @subsection @command{commodities} -Report all commodities present in the journals under consideration. +Report all commodities present in the journals under consideration. The + output is sorted by name. Using the @code{--count} option will tell + you haw many entries use each commodity. +@node tags, entry and xact, commodities, Reports about your Journals +@subsection @command{tags} -@node entry and xact, payees, commodities, Reports about your Journals +The @command{tags} reports all of the tags in the journal. The output +is sorted by name. Using the @code{--count} option will tell you haw +many entries use each tag. Using the @code{--values} option will report +the values used by each tag. + + + +@node entry and xact, payees, tags, Reports about your Journals @subsection @command{draft}, @command{entry} and @command{xact} The @code{draft}, @code{entry} and @command{xact} commands simplify the -- cgit v1.2.3 From 0df13661686dfec66aa0d5a8dd88920e1e104fbc Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 30 Jan 2013 15:35:31 -0700 Subject: Bug 634 Added roundto function, optimized floor and ceiling Fixes Bug634 by adding roundto(amount, places). --- doc/ledger3.texi | 4 +++- src/amount.cc | 29 +++++++++++++++-------------- src/amount.h | 7 +++++++ src/balance.h | 11 +++++++++++ src/report.cc | 8 ++++++++ src/report.h | 1 + src/value.cc | 21 +++++++++++++++++++++ src/value.h | 7 +++++++ test/regress/25A099C9.test | 20 ++++++++++---------- 9 files changed, 83 insertions(+), 25 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 377d740c..ee4c990b 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -7192,6 +7192,7 @@ Useful specifying a date in plain terms. For example, you could say @item @strong{Function} @tab @strong{Abbrev.} @tab @strong{Description} @item @code{amount_expr } @tab @code{} @tab @item @code{abs } @tab @code{} @tab --> U +@item @code{ceiling } @tab @code{} @tab Returns the next integer toward +infty @item @code{code} @tab @code{} @tab returns the transaction code, the string between the parenthesis after the date. @item @code{commodity } @tab @code{} @tab @item @code{display_amount } @tab @code{} @tab --> t @@ -7199,7 +7200,7 @@ Useful specifying a date in plain terms. For example, you could say @item @code{date } @tab @code{} @tab @item @code{format_date } @tab @code{} @tab @item @code{format } @tab @code{} @tab -@item @code{floor } @tab @code{} @tab +@item @code{floor } @tab @code{} @tab Returns the next integer toward -infty @item @code{get_at } @tab @code{} @tab @item @code{is_seq } @tab @code{} @tab @item @code{justify } @tab @code{} @tab @@ -7215,6 +7216,7 @@ Useful specifying a date in plain terms. For example, you could say @item @code{quoted } @tab @code{} @tab @item @code{quantity } @tab @code{} @tab @item @code{rounded } @tab @code{} @tab +@item @code{roundto } @tab @code{} @tab Returns value rounded to n digits. Does not affect formatting. @item @code{scrub } @tab @code{} @tab @item @code{strip --> S } @tab @code{} @tab @item @code{should_bold } @tab @code{} @tab diff --git a/src/amount.cc b/src/amount.cc index ee03827e..51e69290 100644 --- a/src/amount.cc +++ b/src/amount.cc @@ -30,6 +30,7 @@ */ #include +#include #include "amount.h" #include "commodity.h" @@ -672,31 +673,31 @@ void amount_t::in_place_truncate() void amount_t::in_place_floor() { if (! quantity) - throw_(amount_error, _("Cannot floor an uninitialized amount")); + throw_(amount_error, _("Cannot compute floor on an uninitialized amount")); _dup(); - mpz_t quot; - mpz_init(quot); - mpz_fdiv_q(quot, mpq_numref(MP(quantity)), mpq_denref(MP(quantity))); - mpq_clear(MP(quantity)); - mpq_init(MP(quantity)); - mpq_set_num(MP(quantity), quot); + mpz_fdiv_q(temp, mpq_numref(MP(quantity)), mpq_denref(MP(quantity))); + mpq_set_z(MP(quantity), temp); } void amount_t::in_place_ceiling() { if (! quantity) - throw_(amount_error, _("Cannot ceiling an uninitialized amount")); + throw_(amount_error, _("Cannot compute ceiling on an uninitialized amount")); _dup(); - mpz_t quot; - mpz_init(quot); - mpz_cdiv_q(quot, mpq_numref(MP(quantity)), mpq_denref(MP(quantity))); - mpq_clear(MP(quantity)); - mpq_init(MP(quantity)); - mpq_set_num(MP(quantity), quot); + mpz_cdiv_q(temp, mpq_numref(MP(quantity)), mpq_denref(MP(quantity))); + mpq_set_z(MP(quantity), temp); +} + +void amount_t::in_place_roundto(int places) +{ + if (! quantity) + throw_(amount_error, _("Cannot round an uninitialized amount")); + double x=ceil(mpq_get_d(MP(quantity))*pow(10, places) - 0.49999999) / pow(10, places); + mpq_set_d(MP(quantity), x); } void amount_t::in_place_unround() diff --git a/src/amount.h b/src/amount.h index 1b7d2101..5fc2ad2e 100644 --- a/src/amount.h +++ b/src/amount.h @@ -346,6 +346,13 @@ public: } void in_place_round(); + amount_t roundto(int places) const { + amount_t temp(*this); + temp.in_place_round(); + return temp; + } + void in_place_roundto(int places); + /** Yields an amount which has lost all of its extra precision, beyond what the display precision of the commodity would have printed. */ amount_t truncated() const { diff --git a/src/balance.h b/src/balance.h index 9635742d..f822e353 100644 --- a/src/balance.h +++ b/src/balance.h @@ -325,6 +325,17 @@ public: pair.second.in_place_round(); } + balance_t roundto(int places) const { + balance_t temp(*this); + temp.in_place_roundto(places); + return temp; + } + + void in_place_roundto(int places) { + foreach (amounts_map::value_type& pair, amounts) + pair.second.in_place_roundto(places); + } + balance_t truncated() const { balance_t temp(*this); temp.in_place_truncate(); diff --git a/src/report.cc b/src/report.cc index 80993515..d90d22e4 100644 --- a/src/report.cc +++ b/src/report.cc @@ -691,6 +691,12 @@ value_t report_t::fn_round(call_scope_t& args) return args[0].rounded(); } +value_t report_t::fn_roundto(call_scope_t& args) +{ + if(args.has(1)) + return args[0].roundto(args.get(1)); +} + value_t report_t::fn_unround(call_scope_t& args) { return args[0].unrounded(); @@ -1435,6 +1441,8 @@ expr_t::ptr_op_t report_t::lookup(const symbol_t::kind_t kind, return WRAP_FUNCTOR(fn_red); else if (is_eq(p, "round")) return MAKE_FUNCTOR(report_t::fn_round); + else if (is_eq(p, "roundto")) + return MAKE_FUNCTOR(report_t::fn_roundto); break; case 's': diff --git a/src/report.h b/src/report.h index b0044f60..6533d2f1 100644 --- a/src/report.h +++ b/src/report.h @@ -176,6 +176,7 @@ public: value_t fn_floor(call_scope_t& scope); value_t fn_ceiling(call_scope_t& scope); value_t fn_round(call_scope_t& scope); + value_t fn_roundto(call_scope_t& scope); value_t fn_unround(call_scope_t& scope); value_t fn_abs(call_scope_t& scope); value_t fn_justify(call_scope_t& scope); diff --git a/src/value.cc b/src/value.cc index c57cff78..3df8f3c7 100644 --- a/src/value.cc +++ b/src/value.cc @@ -1612,6 +1612,27 @@ void value_t::in_place_round() throw_(value_error, _f("Cannot set rounding for %1%") % label()); } +void value_t::in_place_roundto(int places) +{ + DEBUG("amount.roundto", "=====> roundto places " << places); + switch (type()) { + case INTEGER: + return; + case AMOUNT: + as_amount_lval().in_place_roundto(places); + return; + case BALANCE: + as_balance_lval().in_place_roundto(places); + return; + case SEQUENCE: + foreach (value_t& value, as_sequence_lval()) + value.in_place_roundto(places); + return; + default: + break; + } +} + void value_t::in_place_truncate() { switch (type()) { diff --git a/src/value.h b/src/value.h index 249f3d7f..49d64ab6 100644 --- a/src/value.h +++ b/src/value.h @@ -443,6 +443,13 @@ public: } void in_place_round(); + value_t roundto(int places) const { + value_t temp(*this); + temp.in_place_roundto(places); + return temp; + } + void in_place_roundto(int places); + value_t truncated() const { value_t temp(*this); temp.in_place_truncate(); diff --git a/test/regress/25A099C9.test b/test/regress/25A099C9.test index fb362a4b..34c92c40 100644 --- a/test/regress/25A099C9.test +++ b/test/regress/25A099C9.test @@ -20,24 +20,24 @@ While parsing file "$sourcepath/src/amount.h", line 121: Error: Unexpected whitespace at beginning of line While parsing file "$sourcepath/src/amount.h", line 132: Error: Unexpected whitespace at beginning of line -While parsing file "$sourcepath/src/amount.h", line 711: +While parsing file "$sourcepath/src/amount.h", line 718: Error: Unexpected whitespace at beginning of line -While parsing file "$sourcepath/src/amount.h", line 741: +While parsing file "$sourcepath/src/amount.h", line 748: Error: Unexpected whitespace at beginning of line -While parsing file "$sourcepath/src/amount.h", line 749: +While parsing file "$sourcepath/src/amount.h", line 756: Error: Unexpected whitespace at beginning of line -While parsing file "$sourcepath/src/amount.h", line 752: +While parsing file "$sourcepath/src/amount.h", line 759: Error: Invalid date/time: line amount_t amoun -While parsing file "$sourcepath/src/amount.h", line 758: +While parsing file "$sourcepath/src/amount.h", line 765: Error: Invalid date/time: line string amount_ -While parsing file "$sourcepath/src/amount.h", line 764: +While parsing file "$sourcepath/src/amount.h", line 771: Error: Invalid date/time: line string amount_ -While parsing file "$sourcepath/src/amount.h", line 770: +While parsing file "$sourcepath/src/amount.h", line 777: Error: Invalid date/time: line string amount_ -While parsing file "$sourcepath/src/amount.h", line 776: -Error: Invalid date/time: line std::ostream& While parsing file "$sourcepath/src/amount.h", line 783: +Error: Invalid date/time: line std::ostream& +While parsing file "$sourcepath/src/amount.h", line 790: Error: Invalid date/time: line std::istream& -While parsing file "$sourcepath/src/amount.h", line 789: +While parsing file "$sourcepath/src/amount.h", line 796: Error: Unexpected whitespace at beginning of line end test -- cgit v1.2.3 From 0e16ce75f0c219cb83568c1a5b2362bd5028768d Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 30 Jan 2013 21:50:23 -0700 Subject: Add ability to reconcile new account without switching recon buffers Show cleared balance on command Update documentation --- doc/ledger3.texi | 6 +++++- lisp/ldg-reconcile.el | 11 +++++++++++ 2 files changed, 16 insertions(+), 1 deletion(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index ee4c990b..79ce0b0d 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -2502,13 +2502,17 @@ all of the uncleared transactions. The reconcile buffer has several functions: @item C-x C-s to save changes (to the ledger file as well). @item q - quite the reconcile mode + quit the reconcile mode @item n p next line or previous line @item A add entry @item D delete entry + @item g + reconcile new account + @item b + show cleared balance in mini-buffer @item C-l refresh display @end table diff --git a/lisp/ldg-reconcile.el b/lisp/ldg-reconcile.el index 011bf400..aaccfb07 100644 --- a/lisp/ldg-reconcile.el +++ b/lisp/ldg-reconcile.el @@ -26,6 +26,7 @@ (defun ledger-display-balance () "Calculate the cleared balance of the account being reconciled" + (interactive) (let ((buffer ledger-buf) (account ledger-acct)) (with-temp-buffer @@ -64,6 +65,11 @@ (forward-line) (ledger-display-balance))) +(defun ledger-reconcile-new-account (account) + (interactive "sAccount to reconcile: ") + (set (make-local-variable 'ledger-acct) account) + (ledger-reconcile-refresh)) + (defun ledger-reconcile-refresh () (interactive) (let ((inhibit-read-only t) @@ -203,10 +209,12 @@ (define-key map [? ] 'ledger-reconcile-toggle) (define-key map [?a] 'ledger-reconcile-add) (define-key map [?d] 'ledger-reconcile-delete) + (define-key map [?g] 'ledger-reconcile-new-account) (define-key map [?n] 'next-line) (define-key map [?p] 'previous-line) (define-key map [?s] 'ledger-reconcile-save) (define-key map [?q] 'ledger-reconcile-quit) + (define-key map [?b] 'ledger-display-balance) (define-key map [menu-bar] (make-sparse-keymap "ldg-recon-menu")) (define-key map [menu-bar ldg-recon-menu] (cons "Reconcile" map)) @@ -220,6 +228,9 @@ (define-key map [menu-bar ldg-recon-menu add] '("Add Entry" . ledger-reconcile-add)) (define-key map [menu-bar ldg-recon-menu tog] '("Toggle Entry" . ledger-reconcile-toggle)) (define-key map [menu-bar ldg-recon-menu sep3] '("--")) + (define-key map [menu-bar ldg-recon-menu bal] '("Show Cleared Balance" . ledger-display-balance)) + (define-key map [menu-bar ldg-recon-menu sep4] '("--")) + (define-key map [menu-bar ldg-recon-menu rna] '("Reconcile New Account" . ledger-reconcile-new-account)) (define-key map [menu-bar ldg-recon-menu ref] '("Refresh" . ledger-reconcile-refresh)) (define-key map [menu-bar ldg-recon-menu sav] '("Save" . ledger-reconcile-save)) -- cgit v1.2.3 From 0675208a63837b0ce6802b5124bb90514f07b5e0 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Fri, 1 Feb 2013 10:19:47 -0700 Subject: Add regional sort facility to ledger mode C-c C-s now bound to ledger-sort-region. ledger-sort-region is smart and find the beginning of the first xact within the region and the beginning of the first xact AFTER the region so that it can keep posing structure intact --- doc/ledger3.texi | 2 +- lisp/ldg-mode.el | 5 +++-- lisp/ldg-new.el | 1 + lisp/ldg-sort.el | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ lisp/ldg-xact.el | 26 ------------------------ 5 files changed, 67 insertions(+), 29 deletions(-) create mode 100644 lisp/ldg-sort.el (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 79ce0b0d..ac0208bd 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -2376,7 +2376,7 @@ reconcile uncleared entries related to an account @item C-c C-d delete the current entry @item C-c C-s -sort all entries in the journal by date. Drop comments outside of entries +sort all entries in the region. @item C-c C-o C-r run a ledger report @item C-C C-o C-g diff --git a/lisp/ldg-mode.el b/lisp/ldg-mode.el index 6179747d..001ec8eb 100644 --- a/lisp/ldg-mode.el +++ b/lisp/ldg-mode.el @@ -69,7 +69,7 @@ customizable to ease retro-entry.") (define-key map [(control ?c) (control ?c)] 'ledger-toggle-current) (define-key map [(control ?c) (control ?e)] 'ledger-toggle-current-entry) (define-key map [(control ?c) (control ?r)] 'ledger-reconcile) - (define-key map [(control ?c) (control ?s)] 'ledger-sort-buffer) + (define-key map [(control ?c) (control ?s)] 'ledger-sort-region) (define-key map [(control ?c) (control ?t)] 'ledger-test-run) (define-key map [tab] 'pcomplete) (define-key map [(control ?i)] 'pcomplete) @@ -96,7 +96,8 @@ customizable to ease retro-entry.") (define-key map [menu-bar ldg-menu sm] '("Set Month" . ledger-set-month)) (define-key map [menu-bar ldg-menu sy] '("Set Year" . ledger-set-year)) (define-key map [menu-bar ldg-menu s1] '("--")) - (define-key map [menu-bar ldg-menu so] '("Sort Buffer or Region" . ledger-sort-buffer)) + (define-key map [menu-bar ldg-menu so1] '("Sort Buffer" . ledger-sort-buffer)) + (define-key map [menu-bar ldg-menu so2] '("Sort Region" . ledger-sort-region)) (define-key map [menu-bar ldg-menu s2] '("--")) (define-key map [menu-bar ldg-menu te] '("Toggle Current Posting" . ledger-toggle-current)) (define-key map [menu-bar ldg-menu tt] '("Toggle Current Transaction" . ledger-toggle-current-entry)) diff --git a/lisp/ldg-new.el b/lisp/ldg-new.el index 4793f662..c885cf21 100644 --- a/lisp/ldg-new.el +++ b/lisp/ldg-new.el @@ -43,6 +43,7 @@ (require 'ldg-test) (require 'ldg-texi) (require 'ldg-xact) +(require 'ldg-sort) (require 'ldg-fonts) ;(autoload #'ledger-mode "ldg-mode" nil t) ;(autoload #'ledger-fully-complete-entry "ldg-complete" nil t) diff --git a/lisp/ldg-sort.el b/lisp/ldg-sort.el new file mode 100644 index 00000000..e1988413 --- /dev/null +++ b/lisp/ldg-sort.el @@ -0,0 +1,62 @@ +;;; ldg-xact.el --- Helper code for use with the "ledger" command-line tool + +;; Copyright (C) 2003-2013 John Wiegley (johnw AT gnu DOT org) + +;; This file is not part of GNU Emacs. + +;; This is free software; you can redistribute it and/or modify it under +;; the terms of the GNU General Public License as published by the Free +;; Software Foundation; either version 2, or (at your option) any later +;; version. +;; +;; This is distributed in the hope that it will be useful, but WITHOUT +;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +;; FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +;; for more details. +;; +;; You should have received a copy of the GNU General Public License +;; along with GNU Emacs; see the file COPYING. If not, write to the +;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, +;; MA 02111-1307, USA. + +;; A sample entry sorting function, which works if entry dates are of +;; the form YYYY/mm/dd. + +(defun ledger-next-record-function () + (if (re-search-forward + (concat "^[0-9/.=-]+\\(\\s-+\\*\\)?\\(\\s-+(.*?)\\)?\\s-+" + "\\(.+?\\)\\(\t\\|\n\\| [ \t]\\)") nil t) + (goto-char (match-beginning 0)) + (goto-char (point-max)))) + +(defun ledger-end-record-function () + (forward-paragraph)) + +(defun ledger-sort-region (beg end) + (interactive "r") ;load beg and end from point and mark automagically + (let ((new-beg beg) + (new-end end)) + (save-excursion + (save-restriction + (ledger-next-record-function) ;make sure point is at the beginning of a xact + (message "beg: %s end: %s" new-beg new-end) + (setq new-beg (point)) + (goto-char end) + (ledger-next-record-function) ;make sure end of region is at the beginning of + ;next record after the region + (setq new-end (point)) + (narrow-to-region beg end) + (goto-char (point-min)) + + (let ((inhibit-field-text-motion t)) + (sort-subr + nil + 'ledger-next-record-function + 'ledger-end-record-function)))))) + +(defun ledger-sort-buffer () + (interactive) + (ledger-sort-region (point-min) (point-max))) + + +(provide 'ldg-sort) \ No newline at end of file diff --git a/lisp/ldg-xact.el b/lisp/ldg-xact.el index 8907f58e..1df7d79a 100644 --- a/lisp/ldg-xact.el +++ b/lisp/ldg-xact.el @@ -22,32 +22,6 @@ ;; A sample entry sorting function, which works if entry dates are of ;; the form YYYY/mm/dd. -(defun ledger-next-record-function () - (if (re-search-forward - (concat "^[0-9/.=-]+\\(\\s-+\\*\\)?\\(\\s-+(.*?)\\)?\\s-+" - "\\(.+?\\)\\(\t\\|\n\\| [ \t]\\)") nil t) - (goto-char (match-beginning 0)) - (goto-char (point-max)))) - -(defun ledger-end-record-function () - (forward-paragraph)) - -(defun ledger-sort-region (beg end) - (interactive "r") ;load beg and end from point and mark automagically - (save-excursion - (save-restriction - (narrow-to-region beg end) - (goto-char (point-min)) - (message "%s %s %s" beg end (point-min)) - (let ((inhibit-field-text-motion t)) - (sort-subr - nil - 'ledger-next-record-function - 'ledger-end-record-function))))) - -(defun ledger-sort-buffer () - (interactive) - (ledger-sort-region (point-min) (point-max))) (provide 'ldg-xact) \ No newline at end of file -- cgit v1.2.3 From 37ea7f9b1fdb4fda416f1e35141e4778f1a3c138 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Fri, 1 Feb 2013 21:28:36 -0700 Subject: Updated developer section --- doc/ledger3.texi | 742 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 396 insertions(+), 346 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index ac0208bd..be7d7e98 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -77,8 +77,8 @@ twinkling in their father's CRT. * Budgeting and Forecasting:: * Value Expressions:: * Format Strings:: -* Ledger for Developers:: * Extending with Python:: +* Ledger for Developers:: * Major Changes from version 2.6:: * Example Data File:: * Miscellaneous Notes:: @@ -4093,7 +4093,6 @@ of the balance. * Primary Financial Reports:: Reports in other formats:: Reports about * Reports in other Formats:: * Reports about your Journals:: -* Developer Commands:: @end menu @node Primary Financial Reports, Reports in other Formats, Reporting Commands, Reporting Commands @@ -4774,7 +4773,7 @@ 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, , Reports in other Formats, Reporting Commands @section Reports about your Journals @menu @@ -4879,199 +4878,6 @@ macbook-2:$ -@node Developer Commands, , Reports about your Journals, Reporting Commands -@section Developer Commands -@menu -* echo:: -* reload:: -* source:: -* Debug Options:: -* Pre-commands:: -@end menu - -@node echo, reload, Developer Commands, Developer Commands -@subsection @command{echo} -This command simply echos its argument back to the output. - - -@node reload, source, echo, Developer Commands -@subsection @command{reload} -Forces ledger to reload any journal files. This function exists to -support external programs controlling a running ledger process and does -nothing for a command line user. - -@node source, Debug Options, reload, Developer Commands -@subsection @command{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 return success if no errors are -found. - -@node Debug Options, Pre-commands, source, Developer Commands -@subsection Debug Options - -These options are primarily for Ledger developers, but may be of some -use to a user trying something new. - -@table @code - @item --args-only -ignore init -files and environment variables for the ledger run. - -@item --verify -enable additional assertions during run-time. This causes a significant -slowdown. When combined with @code{--debug} ledger will produce -memory trace information. - -@item --debug "argument" -If Ledger has been built with debug options this will provide extra data -during the run. The following are the available arguments to debug: - -@multitable @columnfractions .32 .43 .27 -@item @code{account.display} @tab @code{expr.calc.when} @tab @code{org.next_amount} -@item @code{accounts.sorted} @tab @code{expr.compile} @tab @code{org.next_total} -@item @code{amount.convert} @tab @code{filters.changed_value} @tab @code{parser.error} -@item @code{amount.is_zero} @tab @code{filters.changed_value.rounding} @tab @code{pool.commodities} -@item @code{amount.parse} @tab @code{filters.collapse} @tab @code{post.assign} -@item @code{amount.price} @tab @code{filters.forecast} @tab @code{python.init} -@item @code{amount.truncate} @tab @code{filters.revalued} @tab @code{python.interp} -@item @code{amount.unround} @tab @code{format.abbrev} @tab @code{query.mask} -@item @code{amounts.commodities} @tab @code{format.expr} @tab @code{report.predicate} -@item @code{amounts.refs} @tab @code{generate.post} @tab @code{scope.symbols} -@item @code{archive.journal} @tab @code{generate.post.string} @tab @code{textual.include} -@item @code{auto.columns} @tab @code{item.meta} @tab @code{textual.parse} -@item @code{budget.generate} @tab @code{ledger.read} @tab @code{timelog} -@item @code{commodity.annotated.strip} @tab @code{ledger.validate} @tab @code{times.epoch} -@item @code{commodity.annotations} @tab @code{lookup} @tab @code{times.interval} -@item @code{commodity.compare} @tab @code{lookup.account} @tab @code{times.parse} -@item @code{commodity.download} @tab @code{mask.match} @tab @code{value.sort} -@item @code{commodity.prices.add} @tab @code{memory.counts} @tab @code{value.storage.refcount} -@item @code{commodity.prices.find} @tab @code{memory.counts.live} @tab @code{xact.extend} -@item @code{convert.csv} @tab @code{memory.debug} @tab @code{xact.extend.cleared} -@item @code{csv.mappings} @tab @code{op.cons} @tab @code{xact.extend.fail} -@item @code{csv.parse} @tab @code{op.memory} @tab @code{xact.finalize} -@item @code{draft.xact} @tab @code{option.args} -@item @code{expr.calc} @tab @code{option.names} -@end multitable - -@item --trace INTEGER_TRACE_LEVEL -Enable tracing. The integer specifies the level of trace desired: -@multitable @columnfractions .3 .7 -@item @code{LOG_OFF} @tab 0 -@item @code{LOG_CRIT} @tab 1 -@item @code{LOG_FATAL} @tab 2 -@item @code{LOG_ASSERT} @tab 3 -@item @code{LOG_ERROR} @tab 4 -@item @code{LOG_VERIFY} @tab 5 -@item @code{LOG_WARN} @tab 6 -@item @code{LOG_INFO} @tab 7 -@item @code{LOG_EXCEPT} @tab 8 -@item @code{LOG_DEBUG} @tab 9 -@item @code{LOG_TRACE} @tab 10 -@item @code{LOG_ALL} @tab 11 -@end multitable - -@item --verbose -Print detailed information on the execution of Ledger. - -@item --version -Print version information and exit. -@end table - -@node Pre-commands, , Debug Options, Developer Commands -@subsection Pre-Commands -Pre-commands are useful when you aren't sure how a command or option -will work. -@table @code -@item args -evaluate the given arguments against the following model transaction: -@smallexample -2004/05/27 Book Store - ; This note applies to all postings. :SecondTag: - Expenses:Books 20 BOOK @@ $10 - ; Metadata: Some Value - ; Typed:: $100 + $200 - ; :ExampleTag: - ; Here follows a note describing the posting. - Liabilities:MasterCard $-200.00 -@end smallexample -@item eval -evaluate the given value expression against the model transaction -@item expr "LIMIT EXPRESSION" -Print details of how ledger parses the given limit expression and apply -it against a model transaction. -@item format "FORMATTING" -Print details of how ledger uses the given formatting description and -apply it against a model transaction. -@item generate -Randomly generates syntactically valid Ledger data from a seed. Used by the -GenerateTests harness for development testing -@item parse -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 Ledger interprets it: -@smallexample -20:22:21 ~/ledger (next)> ledger period "this year" ---- Period expression tokens --- -TOK_THIS: this -TOK_YEAR: year -END_REACHED: - ---- Before stabilization --- - range: in year 2011 - ---- After stabilization --- - range: in year 2011 - start: 11-Jan-01 - finish: 12-Jan-01 - ---- Sample dates in range (max. 20) --- - 1: 11-Jan-01 -@end smallexample -@item query -evaluate the given query and report how Ledger interprets it against the -model transaction: - -@smallexample -20:25:42 ~/ledger (next)> ledger query "/Book/" ---- Input arguments --- -("/Book/") - ---- Context is first posting of the following transaction --- -2004/05/27 Book Store - ; This note applies to all postings. :SecondTag: - Expenses:Books 20 BOOK @@ $10 - ; Metadata: Some Value - ; Typed:: $100 + $200 - ; :ExampleTag: - ; Here follows a note describing the posting. - Liabilities:MasterCard $-200.00 - ---- Input expression --- -(account =~ /Book/) - ---- Text as parsed --- -(account =~ /Book/) - ---- Expression tree --- -0x7fd639c0da40 O_MATCH (1) -0x7fd639c10170 IDENT: account (1) -0x7fd639c10780 VALUE: /Book/ (1) - ---- Compiled tree --- -0x7fd639c10520 O_MATCH (1) -0x7fd639c0d6c0 IDENT: account (1) -0x7fd639c0d680 FUNCTION (1) -0x7fd639c10780 VALUE: /Book/ (1) - ---- Calculated value --- -true -@end smallexample -@item template -Shows the insertion template that a @code{draft} or @code{xact} sub-command generates. -This is a debugging command. -@end table @node Command-line Syntax, Budgeting and Forecasting, Reporting Commands, Top @chapter Command-line Syntax @@ -7241,7 +7047,7 @@ Useful specifying a date in plain terms. For example, you could say @item @code{value_date } @tab @code{} @tab @end multitable -@node Format Strings, Ledger for Developers, Value Expressions, Top +@node Format Strings, Extending with Python, Value Expressions, Top @chapter Format Strings @menu @@ -7667,49 +7473,206 @@ line number in @code{filename} where posting's entry for posting ends, abbreviat - - - -@node Ledger for Developers, Extending with Python, Format Strings, Top -@chapter Ledger for Developers +@node Extending with Python, Ledger for Developers, Format Strings, Top +@chapter Extending with Python +Python can be used to extend your Ledger +experience. But first, a word must be said about Ledger's data model, so that +other things make sense later. @menu -* Internal Design:: -* Journal File Format:: +* Basic data traversal:: +* Raw vs. Cooked:: +* Queries:: +* Embedded Python:: +* Amounts:: @end menu -@node Internal Design, Journal File Format, Ledger for Developers, Ledger for Developers -@section Internal Design -Ledger is developed as a tiered set of functionality, where lower tiers -know nothing about the higher tiers. In fact, multiple libraries are -built during the development the process, and link unit tests to these -libraries, so that it is a link error for a lower tier to violate this -modularity. - -Those tiers are: +@node Basic data traversal, Raw vs. Cooked, Extending with Python, Extending with Python +@section Basic data traversal -@itemize -@item Utility code +Every interaction with Ledger happens in the context of a Session. Even if +you don't create a session manually, one is created for you by the top-level +interface functions. The Session is where objects live like the Commodity's +that Amount's refer to. - There's lots of general utility in Ledger for doing time parsing, using - Boost.Regex, error handling, etc. It's all done in a way that can be - reused in other projects as needed. +The make a Session useful, you must read a Journal into it, using the function +`@code{read_journal}`. This reads Ledger data from the given file, populates a +Journal object within the current Session, and returns a reference to that +Journal object. -@item Commoditized Amounts (amount_t, commodity_t and friends) +Within the Journal live all the Transaction's, Posting's, and other objects +related to your data. There are also AutomatedTransaction's and +PeriodicTransaction's, etc. - An numerical abstraction combining multi-precision rational numbers (via - GMP) with commodities. These structures can be manipulated like regular - numbers in either C++ or Python (as Amount objects). +Here is how you would traverse all the postings in your data file: +@smallexample -@item Commodity Pool + import ledger - Commodities are all owned by a commodity pool, so that future parsing of - amounts can link to the same commodity and established a consistent price - history and record of formatting details. + for xact in ledger.read_journal("sample.dat").xacts: + for post in xact.posts: + print "Transferring %s to/from %s" % (post.amount, post.account) +@end smallexample -@item Balances +@node Raw vs. Cooked, Queries, Basic data traversal, Extending with Python +@section Raw vs. Cooked - Adds the concept of multiple amounts with varying commodities. Supports +Ledger data exists in one of two forms: raw and cooked. Raw objects are what +you get from a traversal like the above, and represent exactly what was seen +in the data file. Consider this journal: + +@smallexample + = true + (Assets:Cash) $100 + + 2012-03-01 KFC + Expenses:Food $100 + Assets:Credit +@end smallexample + + +In this case, the @emph{raw} regular transaction in this file is: + +@smallexample + 2012-03-01 KFC + Expenses:Food $100 + Assets:Credit +@end smallexample + +While the @emph{cooked} form is: + +@smallexample + 2012-03-01 KFC + Expenses:Food $100 + Assets:Credit $-100 + (Assets:Cash) $100 +@end smallexample + +So the easy way to think about raw vs. cooked is that raw is the unprocessed +data, and cooked has had all considerations applied. + +When you traverse a Journal by iterating its transactions, you are generally +looking at raw data. In order to look at cooked data, you must generate a +report of some kind by querying the journal: + +@smallexample + for post in ledger.read_journal("sample.dat").query("food"): + print "Transferring %s to/from %s" % (post.amount, post.account) +@end smallexample + +The reason why queries iterate over postings instead of transactions is that +queries often return only a ``slice'' of the transactions they apply to. You +can always get at a matching posting's transaction by looking at its "xact" +member: + +@smallexample + last_xact = None + for post in ledger.read_journal("sample.dat").query(""): + if post.xact != last_xact: + for post in post.xact.posts: + print "Transferring %s to/from %s" % (post.amount, + post.account) + last_xact = post.xact +@end smallexample + +This query ends up reporting every cooked posting in the Journal, but does it +transaction-wise. It relies on the fact that an unsorted report returns +postings in the exact order they were parsed from the journal file. + +@node Queries, Embedded Python, Raw vs. Cooked, Extending with Python +@section Queries + +The Journal.query() method accepts every argument you can specify on the +command-line, including --options. + +Since a query ``cooks'' the journal it applies to, only one query may be active +for that journal at a given time. Once the query object is gone (after the +for loop), then the data reverts back to its raw state. + +@node Embedded Python, Amounts, Queries, Extending with Python +@section Embedded Python + +Can you embed Python into your data files using the 'python' directive: + +@smallexample + python + import so + def check_path(path_value): + print "%s => %s" % (str(path_value), os.path.isfile(str(path_value))) + return os.path.isfile(str(path_value)) + + tag PATH + assert check_path(value) + + 2012-02-29 KFC + ; PATH: somebogusfile.dat + Expenses:Food $20 + Assets:Cash +@end smallexample + +Any Python functions you define this way become immediately available as +valexpr functions. + +@node Amounts, , Embedded Python, Extending with Python +@section Amounts + +When numbers come from Ledger, like post.amount, the type of the value is +Amount. It can be used just like an ordinary number, except that addition +and subtraction are restricted to amounts with the same commodity. If you +need to create sums of multiple commodities, use a Balance. For example: + +@smallexample + total = Balance() + for post in ledger.read_journal("sample.dat").query(""): + total += post.amount + print total +@end smallexample + + + + +@node Ledger for Developers, Major Changes from version 2.6, Extending with Python, Top +@chapter Ledger for Developers + +@menu +* Internal Design:: +* Journal File Format:: +* Developer Commands:: +* Ledger Development Environment:: +@end menu + +@node Internal Design, Journal File Format, Ledger for Developers, Ledger for Developers +@section Internal Design +Ledger is developed as a tiered set of functionality, where lower tiers +know nothing about the higher tiers. In fact, multiple libraries are +built during the development the process, and link unit tests to these +libraries, so that it is a link error for a lower tier to violate this +modularity. + +Those tiers are: + +@itemize +@item Utility code + + There's lots of general utility in Ledger for doing time parsing, using + Boost.Regex, error handling, etc. It's all done in a way that can be + reused in other projects as needed. + +@item Commoditized Amounts (amount_t, commodity_t and friends) + + An numerical abstraction combining multi-precision rational numbers (via + GMP) with commodities. These structures can be manipulated like regular + numbers in either C++ or Python (as Amount objects). + +@item Commodity Pool + + Commodities are all owned by a commodity pool, so that future parsing of + amounts can link to the same commodity and established a consistent price + history and record of formatting details. + +@item Balances + + Adds the concept of multiple amounts with varying commodities. Supports simple arithmetic, and multiplication and division with non-commoditized values. @@ -7902,7 +7865,7 @@ And that's Ledger in a nutshell. All the rest are details, such as which value expressions each journal item exposes, how many filters currently exist, which options the report and session scopes define, etc. -@node Journal File Format, , Internal Design, Ledger for Developers +@node Journal File Format, Developer Commands, Internal Design, Ledger for Developers @section Journal File Format for Developers This chapter offers a complete description of the journal data format, @@ -8168,163 +8131,250 @@ considered a primary. In fact, when Ledger goes about ensures that all transactions balance to zero, it only ever asks this of primary commodities. -@node Extending with Python, Major Changes from version 2.6, Ledger for Developers, Top -@chapter Extending with Python -Python can be used to extend your Ledger -experience. But first, a word must be said about Ledger's data model, so that -other things make sense later. - +@node Developer Commands, Ledger Development Environment, Journal File Format, Ledger for Developers +@section Developer Commands @menu -* Basic data traversal:: -* Raw vs. Cooked:: -* Queries:: -* Embedded Python:: -* Amounts:: +* echo:: +* reload:: +* source:: +* Debug Options:: +* Pre-commands:: @end menu -@node Basic data traversal, Raw vs. Cooked, Extending with Python, Extending with Python -@section Basic data traversal +@node echo, reload, Developer Commands, Developer Commands +@subsection @command{echo} +This command simply echos its argument back to the output. -Every interaction with Ledger happens in the context of a Session. Even if -you don't create a session manually, one is created for you by the top-level -interface functions. The Session is where objects live like the Commodity's -that Amount's refer to. -The make a Session useful, you must read a Journal into it, using the function -`@code{read_journal}`. This reads Ledger data from the given file, populates a -Journal object within the current Session, and returns a reference to that -Journal object. +@node reload, source, echo, Developer Commands +@subsection @command{reload} +Forces ledger to reload any journal files. This function exists to +support external programs controlling a running ledger process and does +nothing for a command line user. -Within the Journal live all the Transaction's, Posting's, and other objects -related to your data. There are also AutomatedTransaction's and -PeriodicTransaction's, etc. +@node source, Debug Options, reload, Developer Commands +@subsection @command{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 return success if no errors are +found. -Here is how you would traverse all the postings in your data file: -@smallexample +@node Debug Options, Pre-commands, source, Developer Commands +@subsection Debug Options - import ledger +These options are primarily for Ledger developers, but may be of some +use to a user trying something new. - for xact in ledger.read_journal("sample.dat").xacts: - for post in xact.posts: - print "Transferring %s to/from %s" % (post.amount, post.account) -@end smallexample +@table @code + @item --args-only +ignore init +files and environment variables for the ledger run. -@node Raw vs. Cooked, Queries, Basic data traversal, Extending with Python -@section Raw vs. Cooked +@item --verify +enable additional assertions during run-time. This causes a significant +slowdown. When combined with @code{--debug} ledger will produce +memory trace information. -Ledger data exists in one of two forms: raw and cooked. Raw objects are what -you get from a traversal like the above, and represent exactly what was seen -in the data file. Consider this journal: +@item --debug "argument" +If Ledger has been built with debug options this will provide extra data +during the run. The following are the available arguments to debug: -@smallexample - = true - (Assets:Cash) $100 +@multitable @columnfractions .32 .43 .27 +@item @code{account.display} @tab @code{expr.calc.when} @tab @code{org.next_amount} +@item @code{accounts.sorted} @tab @code{expr.compile} @tab @code{org.next_total} +@item @code{amount.convert} @tab @code{filters.changed_value} @tab @code{parser.error} +@item @code{amount.is_zero} @tab @code{filters.changed_value.rounding} @tab @code{pool.commodities} +@item @code{amount.parse} @tab @code{filters.collapse} @tab @code{post.assign} +@item @code{amount.price} @tab @code{filters.forecast} @tab @code{python.init} +@item @code{amount.truncate} @tab @code{filters.revalued} @tab @code{python.interp} +@item @code{amount.unround} @tab @code{format.abbrev} @tab @code{query.mask} +@item @code{amounts.commodities} @tab @code{format.expr} @tab @code{report.predicate} +@item @code{amounts.refs} @tab @code{generate.post} @tab @code{scope.symbols} +@item @code{archive.journal} @tab @code{generate.post.string} @tab @code{textual.include} +@item @code{auto.columns} @tab @code{item.meta} @tab @code{textual.parse} +@item @code{budget.generate} @tab @code{ledger.read} @tab @code{timelog} +@item @code{commodity.annotated.strip} @tab @code{ledger.validate} @tab @code{times.epoch} +@item @code{commodity.annotations} @tab @code{lookup} @tab @code{times.interval} +@item @code{commodity.compare} @tab @code{lookup.account} @tab @code{times.parse} +@item @code{commodity.download} @tab @code{mask.match} @tab @code{value.sort} +@item @code{commodity.prices.add} @tab @code{memory.counts} @tab @code{value.storage.refcount} +@item @code{commodity.prices.find} @tab @code{memory.counts.live} @tab @code{xact.extend} +@item @code{convert.csv} @tab @code{memory.debug} @tab @code{xact.extend.cleared} +@item @code{csv.mappings} @tab @code{op.cons} @tab @code{xact.extend.fail} +@item @code{csv.parse} @tab @code{op.memory} @tab @code{xact.finalize} +@item @code{draft.xact} @tab @code{option.args} +@item @code{expr.calc} @tab @code{option.names} +@end multitable - 2012-03-01 KFC - Expenses:Food $100 - Assets:Credit -@end smallexample +@item --trace INTEGER_TRACE_LEVEL +Enable tracing. The integer specifies the level of trace desired: +@multitable @columnfractions .3 .7 +@item @code{LOG_OFF} @tab 0 +@item @code{LOG_CRIT} @tab 1 +@item @code{LOG_FATAL} @tab 2 +@item @code{LOG_ASSERT} @tab 3 +@item @code{LOG_ERROR} @tab 4 +@item @code{LOG_VERIFY} @tab 5 +@item @code{LOG_WARN} @tab 6 +@item @code{LOG_INFO} @tab 7 +@item @code{LOG_EXCEPT} @tab 8 +@item @code{LOG_DEBUG} @tab 9 +@item @code{LOG_TRACE} @tab 10 +@item @code{LOG_ALL} @tab 11 +@end multitable +@item --verbose +Print detailed information on the execution of Ledger. -In this case, the @emph{raw} regular transaction in this file is: +@item --version +Print version information and exit. +@end table +@node Pre-commands, , Debug Options, Developer Commands +@subsection Pre-Commands +Pre-commands are useful when you aren't sure how a command or option +will work. +@table @code +@item args +evaluate the given arguments against the following model transaction: @smallexample - 2012-03-01 KFC - Expenses:Food $100 - Assets:Credit +2004/05/27 Book Store + ; This note applies to all postings. :SecondTag: + Expenses:Books 20 BOOK @@ $10 + ; Metadata: Some Value + ; Typed:: $100 + $200 + ; :ExampleTag: + ; Here follows a note describing the posting. + Liabilities:MasterCard $-200.00 @end smallexample - -While the @emph{cooked} form is: - +@item eval +evaluate the given value expression against the model transaction +@item expr "LIMIT EXPRESSION" +Print details of how ledger parses the given limit expression and apply +it against a model transaction. +@item format "FORMATTING" +Print details of how ledger uses the given formatting description and +apply it against a model transaction. +@item generate +Randomly generates syntactically valid Ledger data from a seed. Used by the +GenerateTests harness for development testing +@item parse +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 Ledger interprets it: @smallexample - 2012-03-01 KFC - Expenses:Food $100 - Assets:Credit $-100 - (Assets:Cash) $100 -@end smallexample +20:22:21 ~/ledger (next)> ledger period "this year" +--- Period expression tokens --- +TOK_THIS: this +TOK_YEAR: year +END_REACHED: -So the easy way to think about raw vs. cooked is that raw is the unprocessed -data, and cooked has had all considerations applied. +--- Before stabilization --- + range: in year 2011 -When you traverse a Journal by iterating its transactions, you are generally -looking at raw data. In order to look at cooked data, you must generate a -report of some kind by querying the journal: +--- After stabilization --- + range: in year 2011 + start: 11-Jan-01 + finish: 12-Jan-01 -@smallexample - for post in ledger.read_journal("sample.dat").query("food"): - print "Transferring %s to/from %s" % (post.amount, post.account) +--- Sample dates in range (max. 20) --- + 1: 11-Jan-01 @end smallexample - -The reason why queries iterate over postings instead of transactions is that -queries often return only a ``slice'' of the transactions they apply to. You -can always get at a matching posting's transaction by looking at its "xact" -member: +@item query +evaluate the given query and report how Ledger interprets it against the +model transaction: @smallexample - last_xact = None - for post in ledger.read_journal("sample.dat").query(""): - if post.xact != last_xact: - for post in post.xact.posts: - print "Transferring %s to/from %s" % (post.amount, - post.account) - last_xact = post.xact -@end smallexample +20:25:42 ~/ledger (next)> ledger query "/Book/" +--- Input arguments --- +("/Book/") -This query ends up reporting every cooked posting in the Journal, but does it -transaction-wise. It relies on the fact that an unsorted report returns -postings in the exact order they were parsed from the journal file. +--- Context is first posting of the following transaction --- +2004/05/27 Book Store + ; This note applies to all postings. :SecondTag: + Expenses:Books 20 BOOK @@ $10 + ; Metadata: Some Value + ; Typed:: $100 + $200 + ; :ExampleTag: + ; Here follows a note describing the posting. + Liabilities:MasterCard $-200.00 -@node Queries, Embedded Python, Raw vs. Cooked, Extending with Python -@section Queries +--- Input expression --- +(account =~ /Book/) -The Journal.query() method accepts every argument you can specify on the -command-line, including --options. +--- Text as parsed --- +(account =~ /Book/) -Since a query ``cooks'' the journal it applies to, only one query may be active -for that journal at a given time. Once the query object is gone (after the -for loop), then the data reverts back to its raw state. +--- Expression tree --- +0x7fd639c0da40 O_MATCH (1) +0x7fd639c10170 IDENT: account (1) +0x7fd639c10780 VALUE: /Book/ (1) -@node Embedded Python, Amounts, Queries, Extending with Python -@section Embedded Python +--- Compiled tree --- +0x7fd639c10520 O_MATCH (1) +0x7fd639c0d6c0 IDENT: account (1) +0x7fd639c0d680 FUNCTION (1) +0x7fd639c10780 VALUE: /Book/ (1) -Can you embed Python into your data files using the 'python' directive: +--- Calculated value --- +true +@end smallexample +@item template +Shows the insertion template that a @code{draft} or @code{xact} sub-command generates. +This is a debugging command. +@end table -@smallexample - python - import so - def check_path(path_value): - print "%s => %s" % (str(path_value), os.path.isfile(str(path_value))) - return os.path.isfile(str(path_value)) +@node Ledger Development Environment, , Developer Commands, Ledger for Developers +@section Ledger Development Environment - tag PATH - assert check_path(value) +@menu +* acrep build configuration tool:: +* Testing Framework:: +@end menu - 2012-02-29 KFC - ; PATH: somebogusfile.dat - Expenses:Food $20 - Assets:Cash -@end smallexample +@node acrep build configuration tool, Testing Framework, Ledger Development Environment, Ledger Development Environment +@subsection @code{acprep} build configuration tool -Any Python functions you define this way become immediately available as -valexpr functions. +@node Testing Framework, , acrep build configuration tool, Ledger Development Environment +@subsection Testing Framework +Ledger source ships with a farily complete set of tests to verify that +all is well, and no old errors have been resurfaced. Tests are run +individually with @code{ctest}. All tests can be run using @code{make +check} or @code{ninja check} depending on which build tool you prefer. -@node Amounts, , Embedded Python, Extending with Python -@section Amounts +Once built, the ledger executable resides under the @file{build} +subdirectory in the source tree. Tests are built and stored in the test +subdirectory for the build. For example, +@file{~/ledger/build/ledger/opt/test}. -When numbers come from Ledger, like post.amount, the type of the value is -Amount. It can be used just like an ordinary number, except that addition -and subtraction are restricted to amounts with the same commodity. If you -need to create sums of multiple commodities, use a Balance. For example: +@menu +* Running Tests:: +* Writing Tests:: +@end menu -@smallexample - total = Balance() - for post in ledger.read_journal("sample.dat").query(""): - total += post.amount - print total -@end smallexample +@node Running Tests, Writing Tests, Testing Framework, Testing Framework +@subsubsection Running Tests + +The complete test sweet can be run from the build directory using the +check option for the build tool you use. For example, @code{make +check}. The entire test suit tast around a minute for the optimized +built and many times longer for the debug version. While developing and +debugging, running individual tests can save a great deal of time. + +Individual tests can be run fron the @file{test} subdirectory of the +build location. To execute a single test use @code{ctest -V -R regex}, +where the regex mathes the name of the test you want to build. + +There are nearly 300 tests stored under the @file{test} sudirectoro +tmain source distribution. They are broken into two broad categories, +baseline and regression. To run the @file{5FBF2ED8} test, for example, +issue @code{ctest -V -R "5FB"}. +@node Writing Tests, , Running Tests, Testing Framework +@subsubsection Writing Tests -@node Major Changes from version 2.6, Example Data File, Extending with Python, Top +@node Major Changes from version 2.6, Example Data File, Ledger for Developers, Top @chapter Major Changes from version 2.6 @itemize -- cgit v1.2.3 From 7c618e541d4c1e5e4ac476b6724abf2ec97a38b2 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Fri, 1 Feb 2013 22:34:28 -0700 Subject: Added menu and keybinding for ledger-post-edit-amount editing the amount with calc is too cool for school. I can't believe I didn't see it before. It is in the docs now as well. --- doc/ledger3.texi | 13 +++++++++++++ lisp/ldg-mode.el | 11 ++++++----- lisp/ldg-post.el | 5 ----- 3 files changed, 19 insertions(+), 10 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index be7d7e98..815c770b 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -2403,6 +2403,7 @@ kill the ledger report buffer * Manual Entry Support:: * Automagically Adding new entries:: * Clearing Transactions:: +* Calculating Values with EMACS Calc:: @end menu @node Manual Entry Support, Automagically Adding new entries, Working with entries, Working with entries @@ -2487,6 +2488,18 @@ If, for some reason you need to clear a specific posting in the transaction you can type @code{C-c C-c} and the posting at point will be toggled. +@node Calculating Values with EMACS Calc, , Clearing Transactions, Working with entries +@subsubsection Calculating Values with EMACS Calc + +EMACS come with a very power calculator built in. You can use it to +easily insert calculated amounts directly into your ledger buffer. From +the menu, select @code{Calc on Amount}. Calc will pull the current +amount to the top of the calc stack. Calulate the value as you normally +would with an RPN calculator. When you have the desired value on thetop +of the calc stack, press @code{y}, and calc will insert the value +in place of the previous amount. + + @node Reconciling accounts, Generating Reports, Working with entries, Using EMACS @subsection Reconciling accounts diff --git a/lisp/ldg-mode.el b/lisp/ldg-mode.el index c6d899de..c185c198 100644 --- a/lisp/ldg-mode.el +++ b/lisp/ldg-mode.el @@ -62,10 +62,6 @@ customizable to ease retro-entry.") (set (make-local-variable 'pcomplete-termination-string) "") (let ((map (current-local-map))) -; (define-key map [(control ?c) (control ?a)] '(lambda (account) -; (interactive "sAccount:") -; (if ledger-works -; (ledger-add-entry account)))) (define-key map [(control ?c) (control ?a)] 'ledger-add-entry) (define-key map [(control ?c) (control ?d)] 'ledger-delete-current-entry) (define-key map [(control ?c) (control ?y)] 'ledger-set-year) @@ -75,6 +71,7 @@ customizable to ease retro-entry.") (define-key map [(control ?c) (control ?r)] 'ledger-reconcile) (define-key map [(control ?c) (control ?s)] 'ledger-sort-region) (define-key map [(control ?c) (control ?t)] 'ledger-test-run) + (define-key map [(control ?c) (control ?v)] 'ledger-post-edit-amount) (define-key map [tab] 'pcomplete) (define-key map [(control ?i)] 'pcomplete) (define-key map [(control ?c) tab] 'ledger-fully-complete-entry) @@ -86,7 +83,9 @@ customizable to ease retro-entry.") (define-key map [(control ?c) (control ?o) (control ?e)] 'ledger-report-edit) (define-key map [(control ?c) (control ?o) (control ?k)] 'ledger-report-kill) - + (define-key map [(meta ?p)] 'ledger-post-prev-xact) + (define-key map [(meta ?n)] 'ledger-post-next-xact) + (define-key map [menu-bar] (make-sparse-keymap "ldg-menu")) (define-key map [menu-bar ldg-menu] (cons "Ledger" map)) @@ -106,6 +105,8 @@ customizable to ease retro-entry.") (define-key map [toggle-post] '(menu-item "Toggle Current Posting" ledger-toggle-current)) (define-key map [toggle-xact] '(menu-item "Toggle Current Transaction" ledger-toggle-current-entry)) (define-key map [sep4] '(menu-item "--")) + (define-key map [edit-amount] '(menu-item "Calc on Amount" ledger-post-edit-amount)) + (define-key map [sep] '(menu-item "--")) (define-key map [delete-xact] '(menu-item "Delete Entry" ledger-delete-current-entry)) (define-key map [add-xact] '(menu-item "Add Entry" ledger-add-entry :enable ledger-works)) (define-key map [sep3] '(menu-item "--")) diff --git a/lisp/ldg-post.el b/lisp/ldg-post.el index 7cb525a7..14a8cdad 100644 --- a/lisp/ldg-post.el +++ b/lisp/ldg-post.el @@ -183,11 +183,6 @@ This is done so that the last digit falls in COLUMN, which defaults to 52." (goto-char (match-end ledger-regex-post-line-group-account)))) (defun ledger-post-setup () - (let ((map (current-local-map))) - (define-key map [(meta ?p)] 'ledger-post-prev-xact) - (define-key map [(meta ?n)] 'ledger-post-next-xact) - (define-key map [(control ?c) (control ?c)] 'ledger-post-pick-account) - (define-key map [(control ?c) (control ?e)] 'ledger-post-edit-amount)) (if ledger-post-auto-adjust-amounts (add-hook 'after-change-functions 'ledger-post-maybe-align t t)) (add-hook 'after-save-hook #'(lambda () (setq ledger-post-current-list nil)))) -- cgit v1.2.3 From 71de1e6cdcdea280f5bf63a8a2e3d7a22411c663 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Tue, 5 Feb 2013 11:07:36 -0700 Subject: Enh 246 add code folding to ledger mode Based on loccur. Hides everything but the xacts that match a regex. Linked to reconcile mode so that when you reconcile an account on xacts with that account are shown. Documentation updated --- doc/ledger3.texi | 51 +++++++++- lisp/ldg-mode.el | 5 +- lisp/ldg-new.el | 2 + lisp/ldg-occur.el | 252 ++++++++++++++++++++++++++++++++++++++++++++++++++ lisp/ldg-reconcile.el | 165 ++++++++++++++++++--------------- 5 files changed, 394 insertions(+), 81 deletions(-) create mode 100644 lisp/ldg-occur.el (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 815c770b..ce062104 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -2367,6 +2367,8 @@ add a new entry, based on previous entries toggle cleared status of an entire entry @item C-c C-c toggle cleared status of an individual posting +@item C-c C-f +toggle folding mode. When on shows only transactions that meet a given REGEX @item C-c C-y set default year for entry mode @item C-c C-m @@ -2401,12 +2403,13 @@ kill the ledger report buffer @subsection Working with entries @menu * Manual Entry Support:: +* Hiding Transactions:: * Automagically Adding new entries:: * Clearing Transactions:: * Calculating Values with EMACS Calc:: @end menu -@node Manual Entry Support, Automagically Adding new entries, Working with entries, Working with entries +@node Manual Entry Support, Hiding Transactions, Working with entries, Working with entries @subsubsection Manual Entry Support @cindex completion @@ -2427,8 +2430,38 @@ habit to get in to prevent misspellings of accounts. Remember Ledger does not validate the names of payees or account so a misspelled account will be interpreted as a new account by ledger. +@node Hiding Transactions, Automagically Adding new entries, Manual Entry Support, Working with entries +@subsubsection Hiding Transactions + +There are several ways to organize Ledger data files. You can use a +master file and @code{include} one file for each real bank or brokerage +account, separate files for major expense categories, a mix of those +ideas, or throw every transaction in to one giant file. The biggest +drawback to uing one file is that it can get confusing finding specific +transactions in the file. + +Ledger mode has a special transaction hiding mode that you can use to +hide all transactions except those that meet a regular expression you +provide. By default this command is bound to @code{C-c C-f}. EMACS +will ask for a regular expression, which at its simplest is just text +you want to match. For example, lets say you want to review the +transactions in your checking account named @code{"Assets:Checking"}. +Type @code{C-c C-f}, then type @code{Checking} in the minibuffer. EMACS +will hide all other transactions and highlight the remaining +transactions. You can edit them without fear that your other +transaction have had anything done, they are only hidden from view. + +The color used to highlight the xaction can be customized in the EMACS +customization menu. It is called @code{ledger-occur-xact-face}, and can +be changed to alter any charactistic of a font that you want. If you +don't want any highlighting, simply set +@code{ledger-occur-use-face-unfolded} to @code{nil} in the customization +menu. + +To clear the highlighting and show all transactions, type @code{C-c C-f} +again. -@node Automagically Adding new entries, Clearing Transactions, Manual Entry Support, Working with entries +@node Automagically Adding new entries, Clearing Transactions, Hiding Transactions, Working with entries @subsubsection Automagically Adding new entries @cindex new transactions in EMACS @cindex EMACS, adding new transactions @@ -2463,7 +2496,7 @@ ordered by date, not at the bottom of the file. If you need to include spaces in the payee name, then surrond the name of the payee with double quotes, otherwise ledger will interpret the second part of the name as an account. -@node Clearing Transactions, , Automagically Adding new entries, Working with entries +@node Clearing Transactions, Calculating Values with EMACS Calc, Automagically Adding new entries, Working with entries @subsubsection Clearing Transactions and Postings @cindex clearing transactions in EMACS @cindex EMACS, clear transaction @@ -2491,7 +2524,7 @@ toggled. @node Calculating Values with EMACS Calc, , Clearing Transactions, Working with entries @subsubsection Calculating Values with EMACS Calc -EMACS come with a very power calculator built in. You can use it to +EMACS come with a very powerful calculator built in. You can use it to easily insert calculated amounts directly into your ledger buffer. From the menu, select @code{Calc on Amount}. Calc will pull the current amount to the top of the calc stack. Calulate the value as you normally @@ -2529,6 +2562,14 @@ all of the uncleared transactions. The reconcile buffer has several functions: @item C-l refresh display @end table + +By default the reconcile mode uses transaction hiding to show only +transaction eligible for your reconcile. Th reconcile widow itself will +only show a summary of uncleared transaction while the main buffer will +show all transaction meeting the regex, cleared or not. This behavior +can be disabled by setting @code{ledger-fold-on-reconcile} to nil in the +emacs customization menus. + @node Generating Reports, , Reconciling accounts, Using EMACS @subsection Generating Reports @@ -2539,7 +2580,7 @@ retyping the command line, or writing shell scripts for simple one line commands. To generate a report, select the @code{Run Reports} menu, or type -@code{C-c C-o C-r}. Emacs will prompt for a report name. If it +@code{C-c C-o C-r}. EMACS will prompt for a report name. If it recognizes the name it will run the report again. If it is a new name, or blank it will respond by giving you an example command line to edit. Hitting return willrun the report and present it in a new buffer. diff --git a/lisp/ldg-mode.el b/lisp/ldg-mode.el index c185c198..4c55cdc0 100644 --- a/lisp/ldg-mode.el +++ b/lisp/ldg-mode.el @@ -72,6 +72,7 @@ customizable to ease retro-entry.") (define-key map [(control ?c) (control ?s)] 'ledger-sort-region) (define-key map [(control ?c) (control ?t)] 'ledger-test-run) (define-key map [(control ?c) (control ?v)] 'ledger-post-edit-amount) + (define-key map [(control ?c) (control ?f)] 'ledger-occur) (define-key map [tab] 'pcomplete) (define-key map [(control ?i)] 'pcomplete) (define-key map [(control ?c) tab] 'ledger-fully-complete-entry) @@ -110,7 +111,9 @@ customizable to ease retro-entry.") (define-key map [delete-xact] '(menu-item "Delete Entry" ledger-delete-current-entry)) (define-key map [add-xact] '(menu-item "Add Entry" ledger-add-entry :enable ledger-works)) (define-key map [sep3] '(menu-item "--")) - (define-key map [reconcile] '(menu-item "Reconcile Account" ledger-reconcile :enable ledger-works)))) + (define-key map [reconcile] '(menu-item "Reconcile Account" ledger-reconcile :enable ledger-works)) + (define-key map [reconcile] '(menu-item "Hide Xacts" ledger-occur)) + )) (defun ledger-time-less-p (t1 t2) "Say whether time value T1 is less than time value T2." diff --git a/lisp/ldg-new.el b/lisp/ldg-new.el index c885cf21..1d7d5cac 100644 --- a/lisp/ldg-new.el +++ b/lisp/ldg-new.el @@ -45,6 +45,8 @@ (require 'ldg-xact) (require 'ldg-sort) (require 'ldg-fonts) +(require 'ldg-occur) + ;(autoload #'ledger-mode "ldg-mode" nil t) ;(autoload #'ledger-fully-complete-entry "ldg-complete" nil t) ;(autoload #'ledger-toggle-current "ldg-state" nil t) diff --git a/lisp/ldg-occur.el b/lisp/ldg-occur.el new file mode 100644 index 00000000..9cf7f3b1 --- /dev/null +++ b/lisp/ldg-occur.el @@ -0,0 +1,252 @@ +;;; ldg-mode.el --- Helper code for use with the "ledger" command-line tool + +;; Copyright (C) 2003-2013 John Wiegley (johnw AT gnu DOT org) + +;; This file is not part of GNU Emacs. + +;; This is free software; you can redistribute it and/or modify it under +;; the terms of the GNU General Public License as published by the Free +;; Software Foundation; either version 2, or (at your option) any later +;; version. +;; +;; This is distributed in the hope that it will be useful, but WITHOUT +;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +;; FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +;; for more details. +;; +;; You should have received a copy of the GNU General Public License +;; along with GNU Emacs; see the file COPYING. If not, write to the +;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, +;; MA 02111-1307, USA. + + + + +;;; Commentary: +;; Provide code folding to ledger mode. Adapted from original loccur +;; mode by Alexey Veretennikov +;; +;; Adapted to ledger mode by Craig Earls + +;;; Code: + +(defface ledger-occur-folded-face + `((t :foreground "grey70" :invisible t )) + "Default face for Ledger occur mode hidden transactions" + :group 'ledger-faces) + +(defface ledger-occur-xact-face + `((t :background "blue" :weight normal )) + "Default face for Ledger occur mode shown transactions" + :group 'ledger-faces) + +(defconst ledger-occur-overlay-property-name 'ledger-occur-custom-buffer-grep) + +(defcustom ledger-occur-use-face-unfolded t + "if non-nil use a custom face for xacts shown in ledger-occur mode" + :group 'ledger) +(make-variable-buffer-local 'ledger-occur-use-face-unfolded) + + +(defvar ledger-occur-mode nil) ;; name of the minor mode, shown in the mode-line +(make-variable-buffer-local 'ledger-occur-mode) + +(or (assq 'ledger-occur-mode minor-mode-alist) + (nconc minor-mode-alist + (list '(ledger-occur-mode ledger-occur-mode)))) + +(defvar ledger-occur-history nil + "History of previously searched expressions for the prompt") +(make-variable-buffer-local 'ledger-occur-history) + +(defvar ledger-occur-last-match nil + "Last match found") +(make-variable-buffer-local 'ledger-occur-last-match) + +(defvar ledger-occur-overlay-list nil + "A list of currently active overlays to the ledger buffer.") +(make-variable-buffer-local 'ledger-occur-overlay-list) + + +(defun ledger-occur-mode (regex buffer) + (save-excursion + (set-buffer buffer) + (setq ledger-occur-mode + (if (or ledger-occur-mode + (null regex) + (zerop (length regex))) + nil + (concat " Ledger-Folded: " regex))) + (force-mode-line-update) + (ledger-occur-remove-overlays) + (if ledger-occur-mode + (let* ((buffer-matches (ledger-occur-find-matches regex)) + (ovl-bounds (ledger-occur-create-xact-overlay-bounds buffer-matches))) + (setq ledger-occur-overlay-list + (ledger-occur-create-xact-overlays ovl-bounds)) + (setq ledger-occur-overlay-list + (append ledger-occur-overlay-list + (ledger-occur-create-folded-overlays buffer-matches))) + (setq ledger-occur-last-match regex)) + (recenter)))) + +(defun ledger-occur (regex) + "Perform a simple grep in current buffer for the regular + expression REGEX + + This command hides all xact from the current buffer except + those containing the regular expression REGEX. A second call + of the function unhides lines again" + (interactive + (if ledger-occur-mode + (list nil) + (list (read-string (concat "Regexp<" (ledger-occur-prompt) + ">: ") "" 'ledger-occur-history )))) + (if (string-equal "" regex) (setq regex (ledger-occur-prompt))) + (ledger-occur-mode regex (current-buffer))) + +(defun ledger-occur-prompt () + "Returns the default value of the prompt. + + Default value for prompt is a current word or active + region(selection), if its size is 1 line" + (let ((prompt + (if (and transient-mark-mode + mark-active) + (let ((pos1 (region-beginning)) + (pos2 (region-end))) + ;; Check if the start and the of an active region is on + ;; the same line + (if (= (line-number-at-pos pos1) + (line-number-at-pos pos2)) + (buffer-substring-no-properties pos1 pos2))) + (current-word)))) + prompt)) + +(defun ledger-occur-create-folded-overlays(buffer-matches) + (let ((overlays + (let ((prev-end (point-min)) + (temp (point-max))) + (mapcar (lambda (match) + (progn + (setq temp prev-end) ;need a swap so that the + ;last form in the lambda + ;is the (make-overlay) + (setq prev-end (1+ (cadr match))) ;add 1 so + ;that we skip + ;the empty + ;line after + ;the xact + (make-overlay + temp + (car match) + (current-buffer) t nil))) + buffer-matches)))) + (mapcar (lambda (ovl) + (overlay-put ovl ledger-occur-overlay-property-name t) + (overlay-put ovl 'invisible t) + (overlay-put ovl 'intangible t)) + (push (make-overlay (cadr (car(last buffer-matches))) + (point-max) + (current-buffer) t nil) overlays)))) + + +(defun ledger-occur-create-xact-overlays (ovl-bounds) + (let ((overlays + (mapcar (lambda (bnd) + (make-overlay + (car bnd) + (cadr bnd) + (current-buffer) t nil)) + ovl-bounds))) + (mapcar (lambda (ovl) + (overlay-put ovl ledger-occur-overlay-property-name t) + (if ledger-occur-use-face-unfolded + (overlay-put ovl 'face 'ledger-occur-xact-face ))) + overlays))) + +(defun ledger-occur-change-regex (regex buffer) + "use this function to programatically change the overlays, + rather than quitting out and restarting" + (progn + (set-buffer buffer) + (setq ledger-occur-mode nil) + (force-mode-line-update) + (ledger-occur-mode regex buffer) + (recenter))) + +(defun ledger-occur-quit-buffer (buffer) + "quits hidings transaction in the given buffer. Used for + coordinating ledger-occur with other buffers, like reconcile" + (progn + (set-buffer buffer) + (setq ledger-occur-mode nil) + (force-mode-line-update) + (ledger-occur-remove-overlays) + (recenter))) + +(defun ledger-occur-remove-overlays () + (interactive) + (remove-overlays (point-min) + (point-max) ledger-occur-overlay-property-name t) + (setq ledger-occur-overlay-list nil)) + + +(defun ledger-occur-create-xact-overlay-bounds (buffer-matches) + (let ((prev-end (point-min)) + (overlays (list))) + (when buffer-matches + (mapcar (lambda (line) + (push (list (car line) (cadr line)) overlays) + (setq prev-end (cadr line))) + buffer-matches) + (setq overlays (nreverse overlays))))) + +(defun ledger-occur-find-xact-extents (pos) + "return point for beginning of xact and and of xact containing + position. Requires empty line separating xacts" + (interactive "d") + (save-excursion + (goto-char pos) + (let ((end-pos pos) + (beg-pos pos)) + (backward-paragraph) + (next-line) + (beginning-of-line) + (setq beg-pos (point)) + (forward-paragraph) + (previous-line) + (end-of-line) + (setq end-pos (1+ (point))) + (list beg-pos end-pos)))) + +(defun ledger-occur-find-matches (regex) + "Returns a list of 2-number tuples, specifying begnning of the + line and end of a line containing matching xact" + (save-excursion + (goto-char (point-min)) + ;; Set initial values for variables + (let ((curpoint nil) + (endpoint nil) + (lines (list))) + ;; Search loop + (while (not (eobp)) + (setq curpoint (point)) + ;; if something found + (when (setq endpoint (re-search-forward regex nil 'end)) + (save-excursion + (let ((bounds (ledger-occur-find-xact-extents (match-beginning 0)))) + (push bounds lines) + (setq curpoint (cadr bounds)))) ;move to the end of the + ;xact, no need to search + ;inside it more + (goto-char curpoint)) + (forward-line 1)) + (setq lines (nreverse lines))))) + + +(provide 'ldg-occur) + +;;; ldg-occur.el ends here diff --git a/lisp/ldg-reconcile.el b/lisp/ldg-reconcile.el index 753c2fa5..0cac33c5 100644 --- a/lisp/ldg-reconcile.el +++ b/lisp/ldg-reconcile.el @@ -24,6 +24,12 @@ (defvar ledger-buf nil) (defvar ledger-acct nil) +(defcustom ledger-fold-on-reconcile t + "if t, limit transactions shown in main buffer to those + matching the reconcile regex" + :group 'ledger) +(make-variable-buffer-local 'ledger-fold-on-reconcilex) + (defun ledger-display-balance () "Calculate the cleared balance of the account being reconciled" (interactive) @@ -55,10 +61,10 @@ (with-current-buffer ledger-buf (goto-char (cdr where)) (setq cleared (ledger-toggle-current-entry))) - ;remove the existing face and add the new face + ;remove the existing face and add the new face (remove-text-properties (line-beginning-position) - (line-end-position) - (list 'face)) + (line-end-position) + (list 'face)) (if cleared (add-text-properties (line-beginning-position) (line-end-position) @@ -72,7 +78,11 @@ (defun ledger-reconcile-new-account (account) (interactive "sAccount to reconcile: ") (set (make-local-variable 'ledger-acct) account) - (ledger-reconcile-refresh)) + (let ((buf (current-buffer))) + (if ledger-fold-on-reconcile + (ledger-occur-change-regex account ledger-buf)) + (set-buffer buf) + (ledger-reconcile-refresh))) (defun ledger-reconcile-refresh () (interactive) @@ -125,7 +135,10 @@ (defun ledger-reconcile-quit () (interactive) - (kill-buffer (current-buffer))) + (let ((buf ledger-buf)) + (kill-buffer (current-buffer)) + (if ledger-fold-on-reconcile + (ledger-occur-quit-buffer buf)))) (defun ledger-reconcile-finish () (interactive) @@ -144,49 +157,49 @@ (defun ledger-do-reconcile () "get the uncleared transactions in the account and display them in the *Reconcile* buffer" - (let* ((buf ledger-buf) + (let* ((buf ledger-buf) (account ledger-acct) (items (with-temp-buffer (ledger-exec-ledger buf (current-buffer) "--uncleared" "--real" - "emacs" account) + "emacs" account) (goto-char (point-min)) (unless (eobp) (unless (looking-at "(") (error (buffer-string))) (read (current-buffer)))))) - (dolist (item items) - (let ((index 1)) - (dolist (xact (nthcdr 5 item)) - (let ((beg (point)) - (where - (with-current-buffer buf - (cons - (nth 0 item) - (if ledger-clear-whole-entries - (save-excursion - (goto-line (nth 1 item)) - (point-marker)) - (save-excursion - (goto-line (nth 0 xact)) - (point-marker))))))) - (insert (format "%s %-4s %-30s %-30s %15s\n" - (format-time-string "%Y/%m/%d" (nth 2 item)) - (if (nth 3 item) - (nth 3 item) - "") - (nth 4 item) (nth 1 xact) (nth 2 xact))) - (if (nth 3 xact) - (set-text-properties beg (1- (point)) - (list 'face 'ledger-font-reconciler-cleared-face - 'where where)) - (set-text-properties beg (1- (point)) - (list 'face 'ledger-font-reconciler-uncleared-face - 'where where)))) - (setq index (1+ index))))) - (goto-char (point-min)) - (set-buffer-modified-p nil) - (toggle-read-only t))) + (dolist (item items) + (let ((index 1)) + (dolist (xact (nthcdr 5 item)) + (let ((beg (point)) + (where + (with-current-buffer buf + (cons + (nth 0 item) + (if ledger-clear-whole-entries + (save-excursion + (goto-line (nth 1 item)) + (point-marker)) + (save-excursion + (goto-line (nth 0 xact)) + (point-marker))))))) + (insert (format "%s %-4s %-30s %-30s %15s\n" + (format-time-string "%Y/%m/%d" (nth 2 item)) + (if (nth 3 item) + (nth 3 item) + "") + (nth 4 item) (nth 1 xact) (nth 2 xact))) + (if (nth 3 xact) + (set-text-properties beg (1- (point)) + (list 'face 'ledger-font-reconciler-cleared-face + 'where where)) + (set-text-properties beg (1- (point)) + (list 'face 'ledger-font-reconciler-uncleared-face + 'where where)))) + (setq index (1+ index))))) + (goto-char (point-min)) + (set-buffer-modified-p nil) + (toggle-read-only t))) (defun ledger-reconcile (account) @@ -196,6 +209,8 @@ (if rbuf (kill-buffer rbuf)) (add-hook 'after-save-hook 'ledger-reconcile-refresh-after-save) + (if ledger-fold-on-reconcile + (ledger-occur-mode account buf)) (with-current-buffer (pop-to-buffer (get-buffer-create "*Reconcile*")) (ledger-reconcile-mode) @@ -206,41 +221,41 @@ (defvar ledger-reconcile-mode-abbrev-table) (define-derived-mode ledger-reconcile-mode text-mode "Reconcile" - "A mode for reconciling ledger entries." - (let ((map (make-sparse-keymap))) - (define-key map [(control ?m)] 'ledger-reconcile-visit) - (define-key map [return] 'ledger-reconcile-visit) - (define-key map [(control ?c) (control ?c)] 'ledger-reconcile-finish) - (define-key map [(control ?x) (control ?s)] 'ledger-reconcile-save) - (define-key map [(control ?l)] 'ledger-reconcile-refresh) - (define-key map [? ] 'ledger-reconcile-toggle) - (define-key map [?a] 'ledger-reconcile-add) - (define-key map [?d] 'ledger-reconcile-delete) - (define-key map [?g] 'ledger-reconcile-new-account) - (define-key map [?n] 'next-line) - (define-key map [?p] 'previous-line) - (define-key map [?s] 'ledger-reconcile-save) - (define-key map [?q] 'ledger-reconcile-quit) - (define-key map [?b] 'ledger-display-balance) - - (define-key map [menu-bar] (make-sparse-keymap "ldg-recon-menu")) - (define-key map [menu-bar ldg-recon-menu] (cons "Reconcile" map)) - (define-key map [menu-bar ldg-recon-menu qui] '("Quit" . ledger-reconcile-quit)) - (define-key map [menu-bar ldg-recon-menu sep1] '("--")) - (define-key map [menu-bar ldg-recon-menu pre] '("Previous Entry" . previous-line)) - (define-key map [menu-bar ldg-recon-menu vis] '("Visit Entry" . ledger-reconcile-visit)) - (define-key map [menu-bar ldg-recon-menu nex] '("Next Entry" . next-line)) - (define-key map [menu-bar ldg-recon-menu sep2] '("--")) - (define-key map [menu-bar ldg-recon-menu del] '("Delete Entry" . ledger-reconcile-delete)) - (define-key map [menu-bar ldg-recon-menu add] '("Add Entry" . ledger-reconcile-add)) - (define-key map [menu-bar ldg-recon-menu tog] '("Toggle Entry" . ledger-reconcile-toggle)) - (define-key map [menu-bar ldg-recon-menu sep3] '("--")) - (define-key map [menu-bar ldg-recon-menu bal] '("Show Cleared Balance" . ledger-display-balance)) - (define-key map [menu-bar ldg-recon-menu sep4] '("--")) - (define-key map [menu-bar ldg-recon-menu rna] '("Reconcile New Account" . ledger-reconcile-new-account)) - (define-key map [menu-bar ldg-recon-menu ref] '("Refresh" . ledger-reconcile-refresh)) - (define-key map [menu-bar ldg-recon-menu sav] '("Save" . ledger-reconcile-save)) - - (use-local-map map))) + "A mode for reconciling ledger entries." + (let ((map (make-sparse-keymap))) + (define-key map [(control ?m)] 'ledger-reconcile-visit) + (define-key map [return] 'ledger-reconcile-visit) + (define-key map [(control ?c) (control ?c)] 'ledger-reconcile-finish) + (define-key map [(control ?x) (control ?s)] 'ledger-reconcile-save) + (define-key map [(control ?l)] 'ledger-reconcile-refresh) + (define-key map [? ] 'ledger-reconcile-toggle) + (define-key map [?a] 'ledger-reconcile-add) + (define-key map [?d] 'ledger-reconcile-delete) + (define-key map [?g] 'ledger-reconcile-new-account) + (define-key map [?n] 'next-line) + (define-key map [?p] 'previous-line) + (define-key map [?s] 'ledger-reconcile-save) + (define-key map [?q] 'ledger-reconcile-quit) + (define-key map [?b] 'ledger-display-balance) + + (define-key map [menu-bar] (make-sparse-keymap "ldg-recon-menu")) + (define-key map [menu-bar ldg-recon-menu] (cons "Reconcile" map)) + (define-key map [menu-bar ldg-recon-menu qui] '("Quit" . ledger-reconcile-quit)) + (define-key map [menu-bar ldg-recon-menu sep1] '("--")) + (define-key map [menu-bar ldg-recon-menu pre] '("Previous Entry" . previous-line)) + (define-key map [menu-bar ldg-recon-menu vis] '("Visit Entry" . ledger-reconcile-visit)) + (define-key map [menu-bar ldg-recon-menu nex] '("Next Entry" . next-line)) + (define-key map [menu-bar ldg-recon-menu sep2] '("--")) + (define-key map [menu-bar ldg-recon-menu del] '("Delete Entry" . ledger-reconcile-delete)) + (define-key map [menu-bar ldg-recon-menu add] '("Add Entry" . ledger-reconcile-add)) + (define-key map [menu-bar ldg-recon-menu tog] '("Toggle Entry" . ledger-reconcile-toggle)) + (define-key map [menu-bar ldg-recon-menu sep3] '("--")) + (define-key map [menu-bar ldg-recon-menu bal] '("Show Cleared Balance" . ledger-display-balance)) + (define-key map [menu-bar ldg-recon-menu sep4] '("--")) + (define-key map [menu-bar ldg-recon-menu rna] '("Reconcile New Account" . ledger-reconcile-new-account)) + (define-key map [menu-bar ldg-recon-menu ref] '("Refresh" . ledger-reconcile-refresh)) + (define-key map [menu-bar ldg-recon-menu sav] '("Save" . ledger-reconcile-save)) + + (use-local-map map))) (provide 'ldg-reconcile) \ No newline at end of file -- cgit v1.2.3 From 41469e9943986d909ee7cfa5fe977a57f6900431 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Tue, 5 Feb 2013 12:24:30 -0700 Subject: Grammar cleanup --- doc/ledger3.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index ce062104..95025d41 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -2564,7 +2564,7 @@ all of the uncleared transactions. The reconcile buffer has several functions: @end table By default the reconcile mode uses transaction hiding to show only -transaction eligible for your reconcile. Th reconcile widow itself will +transaction eligible for your reconcile. The reconcile widow itself will only show a summary of uncleared transaction while the main buffer will show all transaction meeting the regex, cleared or not. This behavior can be disabled by setting @code{ledger-fold-on-reconcile} to nil in the -- cgit v1.2.3 From 3d34a61ed595ab708ef101f07d7c68df1362f2e8 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Tue, 5 Feb 2013 14:50:59 -0700 Subject: Correct misspelling --- doc/ledger3.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 95025d41..a8f1d4b1 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -7220,7 +7220,7 @@ Inserts the ending line of that transaction within the file. @c @code{%D} gives the user more control over the way dates are output. @item d -Returns the data according to the default format. If the transaction +Returns the date according to the default format. If the transaction has an effective date, it prints @code{[ACTUAL_DATE=EFFECTIVE_DATE]}. @item X -- cgit v1.2.3 From d31913871fc2ca3ba26e12bb302df2dd93cdd3da Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 13 Feb 2013 15:53:16 -0700 Subject: Added rudimentary target checking to reconcile. --- doc/ledger3.texi | 12 ++++++- lisp/ldg-commodities.el | 93 +++++++++++++++++++++++++++++++++++++++++++++++++ lisp/ldg-new.el | 2 ++ lisp/ldg-reconcile.el | 56 +++++++++++++++++++++++------ 4 files changed, 152 insertions(+), 11 deletions(-) create mode 100644 lisp/ldg-commodities.el (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index a8f1d4b1..55732ceb 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -2542,7 +2542,7 @@ all of the uncleared transactions. The reconcile buffer has several functions: @table @code @item SPACE - toggles the cleared status of a transaction, and show cleared balance inthe minibuffer + toggles the cleared status of a transaction, and shows pending balance in the mini-buffer @item RETURN moves the cursor to that transaction in the ledger. @item C-x C-s @@ -2555,6 +2555,8 @@ all of the uncleared transactions. The reconcile buffer has several functions: add entry @item D delete entry + @item t + change target reconciliation amount @item g reconcile new account @item b @@ -2570,6 +2572,14 @@ show all transaction meeting the regex, cleared or not. This behavior can be disabled by setting @code{ledger-fold-on-reconcile} to nil in the emacs customization menus. +When you reconcile an account you nromally know the final balance you +are aiming at. When you enter the reconciliation mode ledger will ask +for a target balance. Enter the amount you are aiming for (the default +commodity can be chaged in the customization window). Each time you +toggle a posting to pending, ledger will calculate the new balance of +the account and display the new balance and the difference to make the +target. + @node Generating Reports, , Reconciling accounts, Using EMACS @subsection Generating Reports diff --git a/lisp/ldg-commodities.el b/lisp/ldg-commodities.el new file mode 100644 index 00000000..94d2ddf0 --- /dev/null +++ b/lisp/ldg-commodities.el @@ -0,0 +1,93 @@ +;;; ldg-commodities.el --- Helper code for use with the "ledger" command-line tool + +;; Copyright (C) 2003-2013 John Wiegley (johnw AT gnu DOT org) + +;; This file is not part of GNU Emacs. + +;; This is free software; you can redistribute it and/or modify it under +;; the terms of the GNU General Public License as published by the Free +;; Software Foundation; either version 2, or (at your option) any later +;; version. +;; +;; This is distributed in the hope that it will be useful, but WITHOUT +;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +;; FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +;; for more details. +;; +;; You should have received a copy of the GNU General Public License +;; along with GNU Emacs; see the file COPYING. If not, write to the +;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, +;; MA 02111-1307, USA. + +;; A sample entry sorting function, which works if entry dates are of +;; the form YYYY/mm/dd. + + + + +;;; Commentary: +;; Helper functions to deal with commoditized numbers. A commoditized +;; number will be a cons of value and string where the string contains +;; the commodity + +;;; Code: + +(defcustom ledger-reconcile-default-commodity "$" + "the default commodity for use in target calculations in ledger reconcile" + :type 'string + :group 'ledger) + +(defun ledger-string-balance-to-commoditized-amount (str) + (let ((fields (split-string str "[\n\r]"))) ; break any balances + ; with multi commodities + ; into a list + (mapcar '(lambda (str) + (let* ((parts (split-string str)) ;break into number and commodity string + (first (car parts)) + (second (cadr parts))) + ;"^-*[1-9][0-9]*[.,][0-9]*" + (if (string-match "^-*[1-9]+" first) + (list (string-to-number first) second) + (list (string-to-number second) first)))) + fields))) + + +(defun -commodity (c1 c2) + (if (string= (cadr c1) (cadr c2)) + (list (- (car c1) (car c2)) (cadr c1)) + (error "Can't subtract different commodities %S from %S" c2 c1))) + +(defun +commodity (c1 c2) + (if (string= (cadr c1) (cadr c2)) + (list (+ (car c1) (car c2)) (cadr c1)) + (error "Can't add different commodities, %S to %S" c1 c2))) + +(defun ledger-commodity-to-string (c1) + (let ((val (number-to-string (car c1))) + (commodity (cadr c1))) + (if (> (length commodity) 1) + (concat val " " commodity) + (concat commodity " " val)))) + +(defun ledger-read-commodity-string (comm) + (interactive (list (read-from-minibuffer + (concat "Enter commoditized amount (" ledger-reconcile-default-commodity "): ")))) + (let ((parts (split-string comm))) + (if parts + (if (/= (length parts) 2) ;;assume a number was entered and use default commodity + (list (string-to-number (car parts)) + ledger-reconcile-default-commodity) + (let ((valp1 (string-to-number (car parts))) + (valp2 (string-to-number (cadr parts)))) + (cond ((and (= valp1 valp2) (= 0 valp1));; means neither contained a valid number (both = 0) + (list 0 "")) + ((and (/= 0 valp1) (= valp2 0)) + (list valp1 (cadr parts))) + ((and (/= 0 valp2) (= valp1 0)) + (list valp2 (car parts))) + (t + (error "cannot understand commodity")))))))) + +(provide 'ldg-commodities) + +;;; ldg-commodities.el ends here diff --git a/lisp/ldg-new.el b/lisp/ldg-new.el index ad21564a..3c56c108 100644 --- a/lisp/ldg-new.el +++ b/lisp/ldg-new.el @@ -46,6 +46,8 @@ (require 'ldg-sort) (require 'ldg-fonts) (require 'ldg-occur) +(require 'ldg-commodities) + (autoload #'ledger-texi-update-test "ldg-texi" nil t) (autoload #'ledger-texi-update-examples "ldg-texi" nil t) diff --git a/lisp/ldg-reconcile.el b/lisp/ldg-reconcile.el index 63ea522b..bb8d97f2 100644 --- a/lisp/ldg-reconcile.el +++ b/lisp/ldg-reconcile.el @@ -24,6 +24,7 @@ (defvar ledger-buf nil) (defvar ledger-bufs nil) (defvar ledger-acct nil) +(defvar ledger-target nil) (defcustom ledger-recon-buffer-name "*Reconcile*" "Name to use for reconciliation window" @@ -54,19 +55,42 @@ :type 'boolean :group 'ledger) -(defun ledger-display-balance () - "Calculate the cleared balance of the account being reconciled" + +(defun ledger-reconcile-get-balances () + "Calculate the cleared and uncleared balance of the account being reconciled, + return a list with the account, uncleared and cleared balances as numbers" (interactive) (let ((buffer ledger-buf) - (account ledger-acct)) + (account ledger-acct) + (val nil)) (with-temp-buffer - (ledger-exec-ledger buffer (current-buffer) "balance" "--limit" "cleared or pending" account) - (goto-char (1- (point-max))) - (goto-char (line-beginning-position)) - (delete-horizontal-space) - (message "Current pending balance = %s" - (buffer-substring-no-properties (point) - (line-end-position)))))) + (ledger-exec-ledger buffer (current-buffer) + ; note that in the line below, the --format option is + ; separated from the actual format string. emacs does not + ; split arguments like the shell does, so you need to + ; specify the individual fields in the command line. + "balance" "--limit" "cleared or pending" + "--format" "(\"%(amount)\")" account) + (setq val (read (buffer-substring-no-properties (point-min) (point-max))))))) + +(defun ledger-display-balance () + "Calculate the cleared balance of the account being reconciled" + (interactive) + (let* ((pending (car (ledger-string-balance-to-commoditized-amount + (car (ledger-reconcile-get-balances))))) + (target-delta (if ledger-target + (-commodity ledger-target pending) + nil))) + + (if target-delta + (message "Pending balance: %s, Difference from target: %s" + (ledger-commodity-to-string pending) + (ledger-commodity-to-string target-delta)) + (message "Pending balance: %s" + (ledger-commodity-to-string pending))))) + + + (defun is-stdin (file) "True if ledger file is standard input" @@ -323,6 +347,8 @@ Spliting the windows of BUF if needed" (if ledger-fold-on-reconcile (ledger-occur-change-regex account ledger-buf)) (set-buffer (get-buffer ledger-recon-buffer-name)) + (setq ledger-target + (call-interactively #'ledger-read-commodity-string)) (unless (get-buffer-window rbuf) (ledger-reconcile-open-windows buf rbuf)) (ledger-reconcile-refresh)) @@ -337,10 +363,18 @@ Spliting the windows of BUF if needed" (ledger-reconcile-mode) (set (make-local-variable 'ledger-buf) buf) (set (make-local-variable 'ledger-acct) account) + (set (make-local-variable 'ledger-target) + (call-interactively #'ledger-read-commodity-string)) (ledger-do-reconcile)))))) (defvar ledger-reconcile-mode-abbrev-table) +(defun ledger-reconcile-change-target () + (setq ledger-target (call-interactively #'ledger-read-commodity-string))) +; (setq ledger-target +; (if (and target (> (length target) 0)) +; (ledger-string-balance-to-commoditized-amount target)))) + (defun ledger-reconcile-display-internals () (interactive) (message "%S %S" ledger-acct ledger-buf)) @@ -358,6 +392,7 @@ Spliting the windows of BUF if needed" (define-key map [?g] 'ledger-reconcile); (define-key map [?n] 'next-line) (define-key map [?p] 'previous-line) + (define-key map [?t] 'ledger-reconcile-change-target) (define-key map [?s] 'ledger-reconcile-save) (define-key map [?q] 'ledger-reconcile-quit) (define-key map [?b] 'ledger-display-balance) @@ -376,6 +411,7 @@ Spliting the windows of BUF if needed" (define-key map [menu-bar ldg-recon-menu tog] '("Toggle Entry" . ledger-reconcile-toggle)) (define-key map [menu-bar ldg-recon-menu sep3] '("--")) (define-key map [menu-bar ldg-recon-menu bal] '("Show Cleared Balance" . ledger-display-balance)) + (define-key map [menu-bar ldg-recon-menu tgt] '("Change Target Balance" . ledger-reconcile-change-target)) (define-key map [menu-bar ldg-recon-menu sep4] '("--")) (define-key map [menu-bar ldg-recon-menu rna] '("Reconcile New Account" . ledger-reconcile)) (define-key map [menu-bar ldg-recon-menu sep5] '("--")) -- cgit v1.2.3 From 2b8743d5026c0cb801cb2e3d8c8fb6d342db4990 Mon Sep 17 00:00:00 2001 From: Ryan Nowakowski Date: Sun, 17 Feb 2013 15:43:48 -0600 Subject: Small corrections in the Embedded Python section --- doc/ledger3.texi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 55732ceb..92cb07fb 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -7656,11 +7656,11 @@ for loop), then the data reverts back to its raw state. @node Embedded Python, Amounts, Queries, Extending with Python @section Embedded Python -Can you embed Python into your data files using the 'python' directive: +You can embed Python into your data files using the 'python' directive: @smallexample python - import so + import os def check_path(path_value): print "%s => %s" % (str(path_value), os.path.isfile(str(path_value))) return os.path.isfile(str(path_value)) -- cgit v1.2.3 From 3d90bfc4add2a85b80c2a90b7c0df9b95d77579d Mon Sep 17 00:00:00 2001 From: John Wiegley Date: Mon, 18 Feb 2013 20:54:10 -0600 Subject: Fix formatting and typos --- doc/ledger3.texi | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 92cb07fb..44f305f2 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -1971,7 +1971,7 @@ account. For example: capture Expenses:Deductible:Medical Medical @end smallexample -Would cause any posting with @code{Medical} in it's name to be replaced with +Would cause any posting with @code{Medical} in its name to be replaced with @code{Expenses:Deductible:Medical}. @@ -2889,9 +2889,9 @@ cannot appear in the Key: @node Typed metadata, , Metadata values, Metadata @subsection Typed metadata -If a metadata tag ends in ::, it's value will be parsed as a value expression -and stored internally as a value rather than as a string. For example, -although I can specify a date textually like so: +If a metadata tag ends in ::, its value will be parsed as a value +expression and stored internally as a value rather than as a string. +For example, although I can specify a date textually like so: @smallexample 2012-03-10 * KFC @@ -2900,10 +2900,10 @@ although I can specify a date textually like so: ; AuxDate: 2012/02/30 @end smallexample -@noindent This date is just a string, and won't be parsed as a date unless its value is -used in a date-context (at which time the string is parsed into a date -automatically every time it is needed as a date). If on the other hand I -write this: +@noindent This date is just a string, and won't be parsed as a date +unless its value is used in a date-context (at which time the string +is parsed into a date automatically every time it is needed as a +date). If on the other hand I write this: @smallexample 2012-03-10 * KFC @@ -2912,8 +2912,9 @@ write this: ; AuxDate:: [2012/02/30] @end smallexample -@noindent Then it is parsed as a date only once, and during parsing of the journal file, -which would let me know right away that it is an invalid date. +@noindent Then it is parsed as a date only once, and during parsing +of the journal file, which would let me know right away that it is an +invalid date. @node Virtual postings, Expression amounts, Metadata, Transactions @section Virtual postings -- cgit v1.2.3 From fe9153496a8cf494bc1962de1c43c43ed109d304 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Tue, 26 Feb 2013 08:11:36 -0700 Subject: Added a note to the introduction about paying attention to shell expansions --- doc/ledger3.texi | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 44f305f2..ae67df19 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -304,6 +304,16 @@ If you would rather start with your own journal right away please see @ref{Keepi * Using the Windows command line:: @end menu +Please note that as a command line program, Ledger is controlled from +your shell. There are several different command shells that all behave +slightly differently with repsect to some special characters. In +particular, the BaSH shell will interpret \$ signs differently than +ledger and they must be escaped to reach the actual program. Another +example is zsh, which will interpret \^ differently than ledger expects. +In all cases that follow you should take that into account when entering +the commandline arguments given. There are too many variations between +shells to give concrete examples for each. + @node Balance Report, Register Report, Run Some Reports, Run Some Reports @subsection Balance Report @cindex balance report -- cgit v1.2.3 From 09f5e41d96949927c20d9ced2c9d37fa5a9e785a Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Tue, 26 Feb 2013 08:13:51 -0700 Subject: unescaped a few symbols --- doc/ledger3.texi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index ae67df19..dbc25d8f 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -307,9 +307,9 @@ If you would rather start with your own journal right away please see @ref{Keepi Please note that as a command line program, Ledger is controlled from your shell. There are several different command shells that all behave slightly differently with repsect to some special characters. In -particular, the BaSH shell will interpret \$ signs differently than +particular, the BaSH shell will interpret $ signs differently than ledger and they must be escaped to reach the actual program. Another -example is zsh, which will interpret \^ differently than ledger expects. +example is zsh, which will interpret ^ differently than ledger expects. In all cases that follow you should take that into account when entering the commandline arguments given. There are too many variations between shells to give concrete examples for each. -- cgit v1.2.3 From 54f50a7690368aaa6d3fd2bd685484b1552aefcd Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 27 Feb 2013 10:06:22 -0700 Subject: Fix typo in ledger3.texi --- doc/ledger3.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index dbc25d8f..8a78b2f0 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -1559,7 +1559,7 @@ whose market value disregards any future changes in the price of gasoline. If you do not want price fixing, you can specify this same transaction -in one of two ways, both equivalent (note the lack of the equal sing +in one of two ways, both equivalent (note the lack of the equal sign from the transaction above): @smallexample -- cgit v1.2.3 From 917c11021390d2b53e8bf8ed1bb4f0d24abdcdda Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 27 Feb 2013 21:21:39 -0700 Subject: Removed EMACS section from Ledger3.texi --- doc/ledger3.texi | 312 +------------------------------------------------------ 1 file changed, 1 insertion(+), 311 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 8a78b2f0..3382ab33 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -1252,7 +1252,6 @@ posting. * Journal Format:: * Converting from other formats:: * Archiving Previous Years :: -* Using EMACS:: @end menu @node Most Basic Entry, Starting up, Keeping a Journal, Keeping a Journal @@ -2260,7 +2259,7 @@ easily be parsed into Ledger format using one of those tools. Some of the more function. -@node Archiving Previous Years , Using EMACS, Converting from other formats, Keeping a Journal +@node Archiving Previous Years , , Converting from other formats, Keeping a Journal @section Archiving Previous Years @@ -2319,315 +2318,6 @@ any electronic statements received during the year. In the arena of organization, just keep in mind this maxim: Do whatever keeps you doing it. -@node Using EMACS, , Archiving Previous Years , Keeping a Journal -@section Using EMACS to Maintain Your Journal -@cindex EMACS - -@menu -* Running ledger-mode:: -* Working with entries:: -* Reconciling accounts:: -* Generating Reports:: -@end menu - -@node Running ledger-mode, Working with entries, Using EMACS, Using EMACS -@subsection Running ledger-mode in EMACS - -Journal files are simple free text files easily modified by any text -editor. A special mode for EMACS is included with the source -distribution. This mode provides syntax highlighting, a reconcile mode -and a report mode. This makes it quote possible to use ledger without -ever leaving EMACS. - -@cindex EMACS .emacs file - -Add the following line to your @file{.emacs} (or equivalent, -@file{~/Aquamacs/Preferences.el} for Aquamacs on Mac OS X) -@smallexample -(load "ldg-new") -@end smallexample - -Copy the several lisp files (@file{ldg-*.el}) from the source lisp directory your your -@file{site-lisp} directory, or add the ledger lisp source directory to -your EMACS load path by adding: -@smallexample -(add-to-list 'load-path "~/ledger/lisp") -@end smallexample -@noindent to your @file{.emacs} file. - -To trigger ledger mode when you visit a journal file, the first line of -each of your journal files should be: -@smallexample -; -*-ledger-*- -@end smallexample -To enter ledger-mode on a new file, type @command{M-x ledger-mode}. - -Once you have loaded a Journal file into EMACS, you have several -commands available to make entering, clearing and reconciling -transactions and producing reports (these are also available from the -menu if you can't remember the key combinations): - -@cindex EMACS commands -@table @code -@item C-i or -auto complete entry -@item C-c C-a -add a new entry, based on previous entries -@item C-c C-e -toggle cleared status of an entire entry -@item C-c C-c -toggle cleared status of an individual posting -@item C-c C-f -toggle folding mode. When on shows only transactions that meet a given REGEX -@item C-c C-y -set default year for entry mode -@item C-c C-m -set default month for entry mode -@item C-c C-r -reconcile uncleared entries related to an account -@item C-c C-d -delete the current entry -@item C-c C-s -sort all entries in the region. -@item C-c C-o C-r -run a ledger report -@item C-C C-o C-g -go to the ledger report buffer -@item C-c C-o C-e -edit the defined ledger reports -@item C-c C-o C-s -save a report definition based on the current report -@item C-c C-o C-a -rerun a ledger report -@item C-c C-o C-k -kill the ledger report buffer -@end table - -@menu -* Working with entries:: -* Reconciling accounts:: -* Generating Reports:: -@end menu - -@node Working with entries, Reconciling accounts, Running ledger-mode, Using EMACS -@subsection Working with entries -@menu -* Manual Entry Support:: -* Hiding Transactions:: -* Automagically Adding new entries:: -* Clearing Transactions:: -* Calculating Values with EMACS Calc:: -@end menu - -@node Manual Entry Support, Hiding Transactions, Working with entries, Working with entries -@subsubsection Manual Entry Support - -@cindex completion -@cindex auto-completion -@cindex misspelled accounts treated as new - -In most financial programs, some sort of auto-completion is available to -save typing and improve accuracy. Ledger doesn't leave you hanging, -@code{ledger-mode} provides tab completion on all portions of an entry. -Type a portion of the payee and hit @code{}, and @code{ledger-mode} will -suggest a completion. When filling in the account type the first few -letters followed by a @code{} and the account will be filled in. For -example typing @code{ExAuF} would yield -@code{Expenses:Auto:Fuel} if you had previously used that account in -this journal. If there are more than one account with similar starting, -hitting @code{} multiple times will iterate through them. This is a good -habit to get in to prevent misspellings of accounts. Remember Ledger -does not validate the names of payees or account so a misspelled account -will be interpreted as a new account by ledger. - -@node Hiding Transactions, Automagically Adding new entries, Manual Entry Support, Working with entries -@subsubsection Hiding Transactions - -There are several ways to organize Ledger data files. You can use a -master file and @code{include} one file for each real bank or brokerage -account, separate files for major expense categories, a mix of those -ideas, or throw every transaction in to one giant file. The biggest -drawback to uing one file is that it can get confusing finding specific -transactions in the file. - -Ledger mode has a special transaction hiding mode that you can use to -hide all transactions except those that meet a regular expression you -provide. By default this command is bound to @code{C-c C-f}. EMACS -will ask for a regular expression, which at its simplest is just text -you want to match. For example, lets say you want to review the -transactions in your checking account named @code{"Assets:Checking"}. -Type @code{C-c C-f}, then type @code{Checking} in the minibuffer. EMACS -will hide all other transactions and highlight the remaining -transactions. You can edit them without fear that your other -transaction have had anything done, they are only hidden from view. - -The color used to highlight the xaction can be customized in the EMACS -customization menu. It is called @code{ledger-occur-xact-face}, and can -be changed to alter any charactistic of a font that you want. If you -don't want any highlighting, simply set -@code{ledger-occur-use-face-unfolded} to @code{nil} in the customization -menu. - -To clear the highlighting and show all transactions, type @code{C-c C-f} -again. - -@node Automagically Adding new entries, Clearing Transactions, Hiding Transactions, Working with entries -@subsubsection Automagically Adding new entries -@cindex new transactions in EMACS -@cindex EMACS, adding new transactions -@code{C-c C-a} will run the @code{ledger entry} command (@pxref{entry -and xact}) from within EMACS. When typed, the mini-buffer will appear -with the current year and month, waiting for you to enter the day and -the payee, and optionally, a commoditized amount. Ledger will generate -a new entry based on the most recent entry for that payee, using the -amount and accounts from that transaction. If you have a new amount -simply type the amount after the payee. For example, if your journal -contains an entry -@smallexample -2011/11/25 Viva Italiano - Expenses:Food $12.45 - Expenses:Tips $2.55 - Liabilities:MasterCard $-15.00 -@end smallexample -@noindent and you type @code{C-c C-a}, the mini-buffer will appear showing the -current year and month. If you complete the mini-buffer entry by typing -@smallexample -Entry: 2011/11/28 viva food 34 tip 7 -@end smallexample -@noindent EMACS will add the following entry to your journal: -@smallexample -2011/11/30 Viva Italiano - Expenses:Food $34.00 - Expenses:Tips $7.00 - Liabilities:MasterCard -@end smallexample -@noindent Notice that the entry will appear at the correct place in the journal -ordered by date, not at the bottom of the file. If you need to include -spaces in the payee name, then surrond the name of the payee with double -quotes, otherwise ledger will interpret the second part of the name as -an account. -@node Clearing Transactions, Calculating Values with EMACS Calc, Automagically Adding new entries, Working with entries -@subsubsection Clearing Transactions and Postings -@cindex clearing transactions in EMACS -@cindex EMACS, clear transaction -@code{C-c C-e} will place an asterisk after the date in the current -transaction. The tells ledger the transaction has been cleared through -your bank (or whatever else you want the concept to mean) -@smallexample -2011/11/25 Viva Italiano - Expenses:Food $12.45 - Expenses:Tips $2.55 - Liabilities:MasterCard $-15.00 -@end smallexample -@noindent becomes -@smallexample -2011/11/25 * Viva Italiano - Expenses:Food $12.45 - Expenses:Tips $2.55 - Liabilities:MasterCard $-15.00 -@end smallexample - -If, for some reason you need to clear a specific posting in the -transaction you can type @code{C-c C-c} and the posting at point will be -toggled. - -@node Calculating Values with EMACS Calc, , Clearing Transactions, Working with entries -@subsubsection Calculating Values with EMACS Calc - -EMACS come with a very powerful calculator built in. You can use it to -easily insert calculated amounts directly into your ledger buffer. From -the menu, select @code{Calc on Amount}. Calc will pull the current -amount to the top of the calc stack. Calulate the value as you normally -would with an RPN calculator. When you have the desired value on thetop -of the calc stack, press @code{y}, and calc will insert the value -in place of the previous amount. - - -@node Reconciling accounts, Generating Reports, Working with entries, Using EMACS -@subsection Reconciling accounts - -Enter the reconcile mode using the menu entry, or @code{C-c C-r}. Emacs -will prompt you for an account name, then display a second buffer with -all of the uncleared transactions. The reconcile buffer has several functions: - -@table @code - @item SPACE - toggles the cleared status of a transaction, and shows pending balance in the mini-buffer - @item RETURN - moves the cursor to that transaction in the ledger. - @item C-x C-s - to save changes (to the ledger file as well). - @item q - quit the reconcile mode - @item n p - next line or previous line - @item A - add entry - @item D - delete entry - @item t - change target reconciliation amount - @item g - reconcile new account - @item b - show cleared balance in mini-buffer - @item C-l - refresh display -@end table - -By default the reconcile mode uses transaction hiding to show only -transaction eligible for your reconcile. The reconcile widow itself will -only show a summary of uncleared transaction while the main buffer will -show all transaction meeting the regex, cleared or not. This behavior -can be disabled by setting @code{ledger-fold-on-reconcile} to nil in the -emacs customization menus. - -When you reconcile an account you nromally know the final balance you -are aiming at. When you enter the reconciliation mode ledger will ask -for a target balance. Enter the amount you are aiming for (the default -commodity can be chaged in the customization window). Each time you -toggle a posting to pending, ledger will calculate the new balance of -the account and display the new balance and the difference to make the -target. - -@node Generating Reports, , Reconciling accounts, Using EMACS -@subsection Generating Reports - -The ledger reports command asks the user to select a report to run then -creates a report buffer containing the results of running the associated -command line. This allows you to run frequently used reports without -retyping the command line, or writing shell scripts for simple one line -commands. - -To generate a report, select the @code{Run Reports} menu, or type -@code{C-c C-o C-r}. EMACS will prompt for a report name. If it -recognizes the name it will run the report again. If it is a new name, -or blank it will respond by giving you an example command line to edit. -Hitting return willrun the report and present it in a new buffer. - -If you have given it a new name, then @code{s} will save the report for -future use. - - -In a report buffer, the following keys are available: -@table @code -@item (space) -scroll up -@item e -edit the defined ledger reports -@item s -save a report definition based on the current report -@item q -quit the report (return to ledger buffer) -@item r -redo the report -@item k -kill the report buffer -@end table - - - - @node Transactions , Building Reports, Keeping a Journal, Top @chapter Transactions @menu -- cgit v1.2.3 From 70bbc81299704b57191b1313ea44bf955345079d Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Tue, 2 Apr 2013 11:11:20 -0700 Subject: Initial chapter on time-keeping in ledger3.texi --- doc/ledger3.texi | 34 ++++++++++++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 3382ab33..91dd794f 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -75,6 +75,7 @@ twinkling in their father's CRT. * Reporting Commands:: * Command-line Syntax:: * Budgeting and Forecasting:: +* Time Keeping:: * Value Expressions:: * Format Strings:: * Extending with Python:: @@ -6389,7 +6390,7 @@ weekly last august @end smallexample -@node Budgeting and Forecasting, Value Expressions, Command-line Syntax, Top +@node Budgeting and Forecasting, Time Keeping, Command-line Syntax, Top @chapter Budgeting and Forecasting @menu @@ -6485,8 +6486,37 @@ only, and not against the running total: ledger --forecast "d<[2010]" bal ^assets ^liabilities @end example +@node Time Keeping, Value Expressions, Budgeting and Forecasting, Top +@chapter Time Keeping -@node Value Expressions, Format Strings, Budgeting and Forecasting, Top + +Ledger directly supports ``timelog'' entries, which have this form: + +@smallexample + i 2013/03/28 22:13:00 ACCOUNT[ PAYEE] + o 2013/03/29 03:39:00 +@end smallexample + +This records a check-in to the given ACCOUNT, and a check-out. You can +be checked-in to multiple accounts at a time, if you wish, and they can +span multiple days (use @code{--day-break} to break them up in the +report). The number of seconds between is accumulated as time to that +ACCOUNT. If the checkout uses a capital ``O'', the transaction is marked +``cleared''. You can use an optional PAYEE for whatever meaning you like. + +Now, there are a few ways to generate this information. You can use the +@file{timeclock.el} package, which is part of Emacs. Or you can write a +simple script in whichever language you prefer to emit similar +information. Or you can use Org-mode's time-clocking abilities and the +org2tc script developed by John Wiegly. + +These timelog entries can appear in a separate file, or directly in your +main ledger file. The initial "i" and "o" count as Ledger "directives", +and are accepted anywhere that ordinary transactions are. + + + +@node Value Expressions, Format Strings, Time Keeping, Top @chapter Value Expressions Ledger uses value expressions to make calculations for many different -- cgit v1.2.3 From 2f3053401a043495860d6d6ee1febe48c3b537aa Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Sat, 6 Apr 2013 09:12:08 -0700 Subject: Minor grammar fix --- doc/ledger3.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 91dd794f..71b8b505 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -3951,7 +3951,7 @@ functions. @subsubsection The @code{convert} command The @code{convert} command parses a comma separated value (csv) file and outputs Ledger transactions. Many banks offer csv file -downloads. Unfortunately the file formats, aside the from commas, are +downloads. Unfortunately, the file formats, aside the from commas, are all different. The ledger @code{convert} command tries to help as much as it can. -- cgit v1.2.3 From 838266f79b07e46be7feeca63d78cf2b7b70599f Mon Sep 17 00:00:00 2001 From: George Kettleborough Date: Wed, 10 Apr 2013 10:53:06 +0100 Subject: Minor formatting fixes for Emacs and Org mode --- doc/ledger3.texi | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) (limited to 'doc/ledger3.texi') diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 71b8b505..3f099d93 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -1236,7 +1236,7 @@ For example, you do not need to tell Ledger about the accounts you use. Any time Ledger sees a posting involving an account it knows nothing about, it will create it@footnote{This also means if you misspell an account it will end up getting counted separately from what -you intended. The provided EMACS major mode provides for automatically +you intended. The provided Emacs major mode provides for automatically filling in account names.}. If you use a commodity that is new to Ledger, it will create that commodity, and determine its display characteristics (placement of the symbol before or after the amount, @@ -3925,7 +3925,7 @@ file whose formatting has gotten out of hand. @menu * Comma Separated Variable files:: * The lisp command:: -* EMACS org mode:: +* Emacs Org mode:: * The pricemap Command:: * The xml Command:: * prices and pricedb:: @@ -4039,11 +4039,11 @@ passed through @code{ledger print} a second time if you want to match on the new payee field. During the @code{ledger convert} run only the original payee name as specified in the csv data seems to be used. -@node The lisp command, EMACS org mode, Comma Separated Variable files, Reports in other Formats +@node The lisp command, Emacs Org mode, Comma Separated Variable files, Reports in other Formats @subsection The @code{lisp} command The @command{lisp} command outputs results in a form that can be read -directly by EMACS Lisp. The format of the @code{sexp} is: +directly by Emacs Lisp. The format of the @code{sexp} is: @smallexample ((BEG-POS CLEARED DATE CODE PAYEE @@ -4053,10 +4053,10 @@ directly by EMACS Lisp. The format of the @code{sexp} is: @noindent @code{emacs} can also be used as a synonym for @code{lisp} -@node EMACS org mode, The pricemap Command, The lisp command, Reports in other Formats -@subsection EMACS @code{org} Mode +@node Emacs Org mode, The pricemap Command, The lisp command, 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 +Emacs Org mode. More details on using Org mode can be found at @url{http://www.orgmode.org}. Org mode has a sub-system known as Babel which allows for literate @@ -4069,7 +4069,7 @@ have ledger commands embedded in a text file and have the output of ledger commands also appear in the text file. The output can be updated whenever any new ledger entries are added. -For instance, the following org mode text document snippet illustrates a +For instance, the following Org mode text document snippet illustrates a very naive but still useful of the @code{org+babel} system: @smallexample @@ -4110,7 +4110,7 @@ You can combine multiple source code blocks before executing ledger and do all kinds of other wonderful things with Babel (and org). -@subsection Org-mode with Babel +@subsection Org mode with Babel Using Babel, it is possible to record financial transactions conveniently in an org file and subsequently generate the financial @@ -4363,7 +4363,7 @@ 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 The pricemap Command, The xml Command, EMACS org mode, Reports in other Formats +@node The pricemap Command, The xml Command, Emacs Org mode, Reports in other Formats @subsection The @code{pricemap} Command If you have the @code{graphviz} graph visualization package installed, ledger @@ -4719,7 +4719,7 @@ commands. @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{xml} @tab Produce XML output of the register command -@item @code{emacs} @tab Produce EMACS lisp output +@item @code{emacs} @tab Produce Emacs lisp output @item @code{equity} @tab Print account balances as transactions @item @code{prices} @tab Print price history for matching commodities @item @code{pricedb} @tab Print price history for matching commodities in ledger readable format @@ -6507,7 +6507,7 @@ ACCOUNT. If the checkout uses a capital ``O'', the transaction is marked Now, there are a few ways to generate this information. You can use the @file{timeclock.el} package, which is part of Emacs. Or you can write a simple script in whichever language you prefer to emit similar -information. Or you can use Org-mode's time-clocking abilities and the +information. Or you can use Org mode's time-clocking abilities and the org2tc script developed by John Wiegly. These timelog entries can appear in a separate file, or directly in your -- cgit v1.2.3