diff options
Diffstat (limited to 'doc/ledger3.texi')
| -rw-r--r-- | doc/ledger3.texi | 571 |
1 files changed, 289 insertions, 282 deletions
diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 02454fdc..d5767efa 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -2265,11 +2265,12 @@ assert <VALUE EXPRESSION BOOLEAN RESULT> Defines the default account to use for balancing transactions. Normally, each transaction has at least two postings, which must balance to zero. Ledger allows you to leave one posting with no -amount and automatically calculate balance the transaction in the +amount and automatically balance the transaction in the posting. The @code{bucket} allows you to fill in all postings and automatically generate an additional posting to the bucket account -balancing the transaction. The following example set the -@samp{Assets:Checking} as the bucket: +balancing the transaction. If any transaction is unbalanced, it +will automatically be balanced against the @code{bucket} account. +The following example sets @samp{Assets:Checking} as the bucket: @smallexample @c input:validate bucket Assets:Checking @@ -2303,7 +2304,7 @@ Ledger will display the mapped payees in @command{print} and @item check @c instance_t::check_directive in textual.cc -A check can issue a warning if a condition is not met during Ledger's +A check issues a warning if a condition is not met during Ledger's run. @smallexample @@ -2315,7 +2316,7 @@ check <VALUE EXPRESSION BOOLEAN RESULT> Start a block comment, closed by @code{end comment}. @item commodity -Pre-declare commodity names. This only has effect if @option{--strict} +Pre-declare commodity names. This only has an effect if @option{--strict} or @option{--pedantic} is used (see below). @smallexample @c input:validate @@ -2324,8 +2325,8 @@ commodity CAD @end smallexample The @code{commodity} directive supports several optional -sub-directives, if they immediately follow the commodity directive and -if they begin with whitespace: +sub-directives, if they immediately follow the commodity directive +and---if they are on successive lines---begin with whitespace: @smallexample @c input:validate commodity $ @@ -2338,19 +2339,19 @@ commodity $ The @code{note} sub-directive associates a textual note with the commodity. At present this has no value other than documentation. -The @code{format} directive gives you a way to tell Ledger how to -format this commodity. In future using this directive will disable +The @code{format} sub-directive gives you a way to tell Ledger how to +format this commodity. In the future, using this directive will disable Ledger's observation of other ways that commodity is used, and will provide the ``canonical'' representation. -The @code{nomarket} directive states that the commodity's price should +The @code{nomarket} sub-directive states that the commodity's price should never be auto-downloaded. -The @code{default} directive marks this as the ``default'' commodity. +The @code{default} sub-directive marks this as the ``default'' commodity. @item define @c instance_t::define_directive in textual.cc -Allows you to define value expression for future use. For example: +Allows you to define value expressions for future use. For example: @smallexample @c input:validate define var_name=$100 @@ -2420,15 +2421,15 @@ Include the stated file as if it were part of the current file. @findex register The @code{payee} directive supports one optional sub-directive, if it -immediately follows the payee directive and if it begins with -whitespace: +immediately follows the payee directive and---if it is on a successive +line---begins with whitespace: @smallexample @c input:validate payee KFC alias KENTUCKY FRIED CHICKEN @end smallexample -The @code{alias} directive provides a regex which, if it matches +The @code{alias} sub-directive provides a regex which, if it matches a parsed payee, the declared payee name is substituted: @smallexample @@ -2489,12 +2490,15 @@ is the equivalent of: Income:Sales @end smallexample -Note that anything following @code{end apply tag} is ignored. placing -the name of the tag that is being closed is a simple way to keep -track. +@c TODO: the following paragraph seems to be false, the automated tests +@c fail, if anything appears after end apply tag. + +@c Note that anything following @code{end apply tag} is ignored. placing +@c the name of the tag that is being closed is a simple way to keep +@c track. @item tag -Pre-declares tag names. This only has effect if @option{--strict} or +Pre-declares tag names. This only has an effect if @option{--strict} or @option{--pedantic} is used (see below). @smallexample @c input:validate @@ -2503,8 +2507,8 @@ tag CSV @end smallexample The @code{tag} directive supports two optional sub-directives, if they -immediately follow the tag directive and if they begin with -whitespace: +immediately follow the tag directive and---if on a successive line---begin +with whitespace: @smallexample @c input:validate tag Receipt @@ -2512,12 +2516,12 @@ tag Receipt assert value != "foobar" @end smallexample -The @code{check} and @code{assert} directives warn or error +The @code{check} and @code{assert} sub-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 assertions are not called -if no value is given. +``value'' is bound to the value of the tag (which may be something else +but a string if typed metadata is used!). Such checks or assertions are +not called if no value is given. @item test @c instance_t::comment_directive in textual.cc @@ -2582,7 +2586,7 @@ C 1.00 Kb = 1024 bytes @item I, i, O, o, b, h These four relate to timeclock support, which permits Ledger to read -timelog files. See the timeclock's documentation for more info on the +timelog files. See timeclock's documentation for more info on the syntax of its timelog files. @end table @@ -2778,8 +2782,8 @@ primary date with an equals sign: What this auxiliary date means is entirely up to you. The only use Ledger has for it is that if you specify @option{--aux-date}, then all -reports and calculations (including pricing) will use the aux date as if -it were the primary date. +reports and calculations (including pricing) will use the auxiliary +date as if it were the primary date. @node Codes, Transaction state, Auxiliary dates, Transactions @section Codes @@ -2802,8 +2806,8 @@ you a place to put those codes: @findex --pending A transaction can have a ``state'': cleared, pending, or uncleared. -The default is uncleared. To mark a transaction cleared, put a * -before the payee, and after date or code: +The default is uncleared. To mark a transaction cleared, put an asterisk (*) +before the payee, after the date or code: @smallexample @c input:validate 2012-03-10 * KFC @@ -2821,7 +2825,7 @@ To mark it pending, use a !: @end smallexample What these mean is entirely up to you. The @option{--cleared} option -will limits to reports to only cleared items, while @option{--uncleared} +limits reports to only cleared items, while @option{--uncleared} shows both uncleared and pending items, and @option{--pending} shows only pending items. @@ -2861,7 +2865,7 @@ You can mark individual postings as cleared or pending, in case one @section Transaction notes After the payee, and after at least one tab or two spaces (or a space -and a tab, which Ledger calls this a ``hard separator''), you may +and a tab, which Ledger calls a ``hard separator''), you may introduce a note about the transaction using the @samp{;} character: @smallexample @c input:validate @@ -2886,7 +2890,7 @@ with whitespace: Assets:Cash @end smallexample -A transaction note is shared by all its postings. This becomes +A transaction's note is shared by all its postings. This becomes significant when querying for metadata (see below). To specify that a note belongs only to one posting, place it after a hard separator after the amount, or on its own line preceded by whitespace: @@ -2915,7 +2919,7 @@ typed metadata with postings and transactions (by which I mean all of a transaction's postings). This metadata can be queried, displayed, and used in calculations. -The are two forms of metadata: tags and tag/value pairs. +The are two forms of metadata: plain tags, and tag/value pairs. @menu * Metadata tags:: @@ -2927,7 +2931,7 @@ The are two forms of metadata: tags and tag/value pairs. @subsection Metadata tags To tag an item, put any word not containing whitespace between two -colons: +colons inside a comment: @smallexample @c input:validate 2012-03-10 * KFC @@ -3125,7 +3129,7 @@ A balance assignment has this form: @end smallexample This sets the amount of the second posting to whatever it would need -to be for the total in Assets:Cash to be $500.00 after the posting. +to be for the total in @samp{Assets:Cash} to be $500.00 after the posting. If the resulting amount is not $-20.00 in this case, it is an error. @node Resetting a balance, Balancing transactions, Balance assignments, Balance verification @@ -3145,7 +3149,7 @@ Since the second posting is also null, it's value will become the inverse of whatever amount is generated for the first posting. This is the only time in ledger when more than one posting's amount -may be empty---and then only because it's not true empty, it is +may be empty---and then only because it's not truly empty, it is indirectly provided by the balance assignment's value. @node Balancing transactions, , Resetting a balance, Balance verification @@ -3160,7 +3164,7 @@ As a consequence of all the above, consider the following transaction: @end smallexample What this says is: set the amount of the posting to whatever value is -needed so that Assets:Brokerage contains 10 AAPL. Then, because this +needed so that @samp{Assets:Brokerage} contains 10 AAPL. Then, because this posting must balance, ensure that its value is zero. This can only be true if Assets:Brokerage does indeed contain 10 AAPL at that point in the input file. @@ -3173,7 +3177,7 @@ anyway (unless you use a register report with @option{--empty}). @section Posting cost When you transfer a commodity from one account to another, sometimes -it get transformed during the transaction. This happens when you +it gets transformed during the transaction. This happens when you spend money on gas, for example, which transforms dollars into gallons of gasoline, or dollars into stocks in a company. @@ -3189,7 +3193,7 @@ example of a stock purchase: This is different from transferring 10 AAPL shares from one account to another, in this case you are @emph{exchanging} one commodity for -another. The resulting posting cost is $50.00 per share. +another. The resulting posting's cost is $50.00 per share. @node Explicit posting costs, Posting cost expressions, Posting cost, Transactions @section Explicit posting costs @@ -3232,7 +3236,7 @@ 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 @option{--market (-V)} +The only meaning a primary commodity has is that the @option{--market (-V)} flag will never convert a primary commodity into any other commodity. @option{--exchange @var{COMMODITY} (-X)} still will, however. @@ -3296,7 +3300,7 @@ happening in the case of an exceptional transaction, surround the @section Commodity prices @findex --lot-prices -When a transaction occurs that exchange one commodity for another, +When a transaction occurs that exchanges 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 @option{--lot-prices} @@ -3310,7 +3314,7 @@ For example, consider the stock sale given above: Assets:Brokerage:Cash @end smallexample -The commodity transferred into Assets:Brokerage is not actually 10 +The commodity transferred into @samp{Assets:Brokerage} is not actually 10 AAPL, but rather 10 AAPL @{$5.00@}. The figure in braces after the amount is called the ``lot price''. It's Ledger's way of remembering that this commodity was transferred through an exchange, and that @@ -3373,11 +3377,11 @@ but is not required to be used with them: It should be noted that this is a convenience only for cases where you buy and sell whole lots. The @{@{$500.00@}@} is @emph{not} an -attribute of commodity, whereas @{$5.00@} is. In fact, when you write +attribute of the commodity, whereas @{$5.00@} is. In fact, when you write @{@{$500.00@}@}, Ledger just divides that value by 10 and sees @{$50.00@}. So if you use the print command to look at this -transaction, you'll see the single form in the output. The double -price form is a shorthand only. +transaction, you'll see the single braces form in the output. +The double braces price form is a shorthand only. Plus, it comes with dangers. This works fine: @@ -3416,7 +3420,7 @@ But this does not do what you might expect: Income:Capital Gains $-125.00 @end smallexample -And in cases where the amounts do not divide into whole figure and +And in cases where the amounts do not divide into whole figures and must be rounded, the capital gains figure could be off by a cent. Use with caution. @@ -3508,7 +3512,7 @@ indicate a virtual cost: Income:Capital Gains $-125.00 @end smallexample -You can any combination of lot prices, dates or notes, in any order. +You can specify any combination of lot prices, dates or notes, in any order. They are all optional. To show all lot information in a report, use @option{--lots}. @@ -3526,7 +3530,7 @@ However, you can override this valuation logic by providing a commodity valuation expression in doubled parentheses. This expression must result in one of two values: either an amount to always be used as the per-share price for that commodity; or -a function taking three argument which is called to determine that +a function taking three arguments, which is called to determine that price. If you use the functional form, you can either specify a function @@ -3581,8 +3585,8 @@ indicate what is being desired. @end itemize 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. +valuation expressions, or just pass the arguments down to @samp{market} +after modifying them to suit your needs. @node Automated Transactions, , Lot value expressions, Transactions @section Automated Transactions @@ -3700,9 +3704,10 @@ This becomes: @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 automated transaction itself. This is done by using the string -$account, anywhere within the account part of the automated posting: +Sometimes you want to refer to the account that was matched +in some way within the automated transaction itself. This is +done by using the string @samp{$account}, anywhere within the +account part of the automated posting: @smallexample @c input:validate = food @@ -3793,7 +3798,7 @@ the generated posting. @cindex effective dates @findex --effective -In the real world transactions do not take place instantaneously. +In the real world, transactions do not take place instantaneously. Purchases can take several days to post to a bank account. And you may pay ahead for something for which you want to distribute costs. With Ledger you can control every aspect of the timing of a transaction. @@ -3862,12 +3867,12 @@ pick up from the co-op, even though you've already paid for them. Assets:Checking @end smallexample -This entry accomplishes this. Every month until you'll start with an +This entry accomplishes this. Every month you'll see an automatic $37.50 deficit like you should, while your checking account really knows that it debited $225 this month. -And using @option{--effective} option, initial date will be overridden -by effective dates. +And using the @option{--effective} option, the initial date will be overridden +by the effective dates. @smallexample @c command:6453542 $ ledger --effective register Groceries @@ -3905,7 +3910,7 @@ automated posting at the top of your ledger file: @smallexample @c input:C371854 ; This automated transaction will compute Huqúqu'lláh based on this -; journal's postings. Any that match will affect the +; journal's postings. Any accounts that match will affect the ; Liabilities:Huququ'llah account by 19% of the value of that posting. = /^(?:Income:|Expenses:(?:Business|Rent$|Furnishings|Taxes|Insurance))/ @@ -3951,14 +3956,14 @@ $ ledger balance Liabilities:Huquq $-95 Liabilities:Huququ'llah @end smallexample -This works fine, but omits one aspect of the law: that Huquq is only +This works fine, but omits one aspect of the law: that Huqúq 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: -@c TODO: fix this +@c TODO: fix this, it doesn't work any longer @smallexample $ ledger -Q -t "/Liab.*Huquq/?(a/P@{2.22 AU@}<=@{-1.0@}&a):a" bal liab @end smallexample @@ -3968,7 +3973,7 @@ 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: -@c TODO: fix this +@c TODO: fix this, it doesn't work any longer @smallexample $ ledger -Q -T "/Liab.*Huquq/?(O/P@{2.22 AU@}<=@{-1.0@}&O):O" bal liab @end smallexample @@ -4052,9 +4057,9 @@ which will print the balances of every account in your journal. $ -243.60 @end smallexample -Most times this is more than you want. Limiting the results to +Most times, this is more than you want. Limiting the results to specific accounts is as easy as entering the names of the accounts -after the command. +after the command: @smallexample @c command:06B2AD4 $ ledger balance -f drewr3.dat Auto MasterCard @@ -4068,7 +4073,7 @@ $ ledger balance -f drewr3.dat Auto MasterCard @end smallexample @noindent -note the implicit logical or between @samp{Auto} and +Note the implicit logical or between @samp{Auto} and @samp{Mastercard}. If you want the entire contents of a branch of your account tree, use @@ -4086,7 +4091,7 @@ $ ledger balance -f drewr3.dat Income $ -2,030.00 @end smallexample -You can use general regular expressions in nearly anyplace Ledger +You can use general regular expressions in nearly any place Ledger needs a string: @smallexample @c command:EAE389F @@ -4106,7 +4111,7 @@ $ ledger balance -f drewr3.dat Bo $ 20.00 Expenses:Books @end smallexample -This second example looks for any account with @samp{Bo}, which is +This second example looks for any account containing @samp{Bo}, which is @samp{Expenses:Books}. @cindex limit by payees @@ -4152,7 +4157,7 @@ October, sorted by total: @c TODO: does not validate with @c command:validate, because "last oct" is split at the space @smallexample -$ ledger -b "last oct" -f sample.dat -S T bal ^expenses +$ ledger -b "last oct" -S T bal ^expenses @end smallexample From left to right the options mean: Show transactions since last @@ -4201,7 +4206,7 @@ account'' postings; display only related postings whose account matches @samp{mastercard}, and base the calculation on postings matching @samp{^expenses}. -This works just as well for report the overall total, too: +This works just as well for reporting the overall total, too: @smallexample @c command:validate $ ledger -s -r --display "account=~/mastercard/" reg ^expenses @@ -4230,11 +4235,11 @@ allocation in ledger is not difficult but does require some additional effort to describe how the various assets you own contribute to the asset classes you want to track. -In our simple example we assume you want to apportion you assets into +In our simple example we assume you want to apportion your assets into the general categories of domestic and international equities (stocks) -and a combined category of bonds and cash. For illustrative purposes +and a combined category of bonds and cash. For illustrative purposes, we will use several publicly available mutual funds from Vanguard. -the three funds we will track are the Vanguard 500 IDX FD Signal +The three funds we will track are the Vanguard 500 IDX FD Signal (VIFSX), the Vanguard Target Retirement 2030 (VTHRX), and the Vanguard Short Term Federal Fund (VSGBX). Each of these funds allocates assets to different categories of the investment universe and in different @@ -4329,7 +4334,7 @@ tree, using a special formatter. The magic is in the formatter. The second line simply tells Ledger to print the partial account name indented by its depth in the tree. The third line is where we calculate and display the percentages. The -@code{display_total} command give the values of the total calculated +@code{display_total} command gives the values of the total calculated for the account in this line. The @code{parent.total} command gives the total for the next level up in the tree. @code{percent} formats their ratio as a percentage. The fourth line tells ledger to display @@ -4346,7 +4351,7 @@ nothing. @findex --limit @var{EXPR} @findex --display @var{EXPR} -If you have ``Gnuplot'' program installed, you can graph any of the +If you have the ``Gnuplot'' program installed, you can graph any of the above register reports. The script to do this is included in the ledger distribution, and is named @file{contrib/report}. Install @file{report} anywhere along your @env{PATH}, and then use @file{report} instead of @@ -4385,11 +4390,11 @@ report -J -l "Ua>=@{\$0.01@}" -d "d>=[last feb]" reg ^assets ^liab The last report uses both a calculation predicate @option{--limit @var{EXPR} (-l)} and a display predicate @option{--display @var{EXPR} -(-d)}. The calculation predicates limits the report to postings whose -amount is greater than $1 (which can only happen if the posting amount +(-d)}. The calculation predicate limits the report to postings whose +amount is greater than or equal to $1 (which can only happen if the posting amount is in dollars). The display predicate limits the transactions -@emph{displayed} to just those since last February, even those -transactions from before then will be computed as part of the balance. +@emph{displayed} to just those since last February, even though those +transactions from before will be computed as part of the balance. @node Reporting Commands, Command-line Syntax, Building Reports, Top @chapter Reporting Commands @@ -4424,7 +4429,7 @@ separately. @subsection The @command{equity} command @findex equity -The @command{equity} command prints out accounts balances as if they +The @command{equity} command prints out account balances as if they were transactions. This makes it easy to establish the starting balances for an account, such as when @ref{Archiving Previous Years}. @@ -4438,7 +4443,7 @@ The @command{register} command displays all the postings occurring in a single account, line by line. The account regex must be specified as the only argument to this command. If any regexes occur after the required account name, the register will contain only those -postings that match. Very useful for hunting down a particular +postings that match, which makes it very useful for hunting down a particular posting. The output from @command{register} is very close to what a typical @@ -4450,7 +4455,7 @@ 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{--amount-data (-j)} or @option{--total-data (-J)} to -your register command, in order to plot either the amount or total +your @command{register} command, in order to plot either the amount or total column, respectively. @node The @command{print} command, , The @command{register} command, Primary Financial Reports @@ -4491,8 +4496,8 @@ file whose formatting has gotten out of hand. @subsubsection The @command{csv} command @findex csv -The @command{csv} command will output print out the desired ledger -transactions in a csv format suitable for import into other programs. +The @command{csv} command prints the desired ledger +transactions in a csv format suitable for importing into other programs. You can specify the transactions to print using all the normal limiting and searching functions. @@ -4504,12 +4509,12 @@ limiting and searching functions. @findex --input-date-format @var{DATE_FORMAT} The @command{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 +and prints Ledger transactions. Many banks offer csv file downloads. +Unfortunately, the file formats, aside from the commas, are all different. The ledger @command{convert} command tries to help as much as it can. -Your banks csv files will have fields in different orders from other +Your bank's csv files will have fields in different orders from other banks, so there must be a way to tell Ledger what to expect. Insert a line at the beginning of the csv file that describes the fields to Ledger. @@ -4552,7 +4557,7 @@ $ ledger convert download.csv --input-date-format "%m/%d/%Y" Where the @option{--input-date-format @var{DATE_FORMAT}} option tells ledger how to interpret the dates. -Importing csv files is a lot of work, and but is very amenable to +Importing csv files is a lot of work, but is very amenable to scripting. If there are columns in the bank data you would like to keep in your @@ -4573,14 +4578,14 @@ is from the file above. @findex --account @var{STR} @findex --rich-data -The @command{convert} command accepts three options, the most important +The @command{convert} command accepts three options. The most important ones are @option{--invert} which inverts the amount field, and @option{--account @var{STR}} which you can use to specify the account to balance against and @option{--rich-data}. When using the rich-data -switch additional metadata is stored as tags. There is, for example, +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 @option{--file @var{FILE} (-f)} or -via environment variable @env{LEDGER_FILE}) this entry will not be +via the environment variable @env{LEDGER_FILE}) this entry will not be printed again. You can also use @command{convert} with @code{payee} and @code{account} @@ -4607,7 +4612,7 @@ used. @findex lisp @findex emacs -The @command{lisp} command outputs results in a form that can be read +The @command{lisp} command prints results in a form that can be read directly by Emacs Lisp. The format of the @code{sexp} is: @smallexample @@ -4638,7 +4643,7 @@ 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 Babel system: +a very naive but still useful application of the Babel system: @smallexample * A simple test of ledger in an org file @@ -4684,7 +4689,7 @@ Using Babel, it is possible to record financial transactions conveniently in an org file and subsequently generate the financial reports required. -As of Org-mode 7.01, Ledger support is provided. Check the Babel +As of Org mode 7.01, Ledger support is provided. Check the Babel documentation on Worg for instructions on how to achieve this but I currently do this directly as follows: @@ -4695,7 +4700,7 @@ I currently do this directly as follows: )) @end smallexample -Once Ledger support in Babel has been enabled, we can use proceed to +Once Ledger support in Babel has been enabled, we can proceed to include Ledger entries within an org file. There are three ways (at least) in which these can be included: @@ -4733,7 +4738,7 @@ The first two are described in more detail in this short tutorial. @node Embedded Ledger example with single source block, Multiple Ledger source blocks with @code{noweb}, Org mode with Babel, Org mode with Babel @subsubsection Embedded Ledger example with single source block -The easiest, albeit possibly less useful, way in which to use Ledger +The easiest, albeit possibly least 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: @@ -4972,10 +4977,10 @@ the running total of the assets in our ledger. @node Summary, , Generating a monthly register, Org mode with Babel @subsubsection Summary -This short tutorial shows how Ledger entries can be embedded in a org +This short tutorial shows how Ledger entries can be embedded in an org 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. +examples of more complex operations on a ledger. @node The @command{pricemap} command, The @command{xml} command, Org mode with Babel, Reports in other Formats @subsection The @command{pricemap} command @@ -4987,7 +4992,7 @@ commodities. The output file is in the ``dot'' format. This is probably not very interesting, unless you have many different commodities valued in terms of each other. For example, multiple -currencies and multiples investments valued in those currencies. +currencies and multiple investments valued in those currencies. @node The @command{xml} command, @command{prices} and @command{pricedb} commands, The @command{pricemap} command, Reports in other Formats @subsection The @command{xml} command @@ -5010,7 +5015,7 @@ The general format used for Ledger data is: @end smallexample The data stream is enclosed in a @code{ledger} tag, which contains a -series of one or more transactions. Each @code{xact} describes the +series of one or more transactions. Each @code{xact} describes one transaction and contains a series of one or more postings: @smallexample @@ -5055,7 +5060,7 @@ Within the @code{en:postings} tag is a series of one or more </posting> @end smallexample -This is a basic posting. It may also be begin with +This is a basic posting. It may also begin with @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 @@ -5157,7 +5162,7 @@ report, to display the running average price, or @option{--deviation (-D)} to show each price's deviation from that average. There is also a @command{pricedb} command which outputs the same -information as @command{prices}, but does in a format that can be +information as @command{prices}, but does so in a format that can be parsed by Ledger. This is useful for generating and tidying up pricedb database files. @@ -5179,7 +5184,7 @@ pricedb database files. @subsection @command{accounts} @findex accounts -The @command{accounts} reports all of the accounts in the journal. +The @command{accounts} command reports all of the accounts in the journal. Following the command with a regular expression will limit the output to accounts matching the regex. The output is sorted by name. Using the @option{--count} option will tell you how many entries use each account. @@ -5188,9 +5193,9 @@ accounts matching the regex. The output is sorted by name. Using the @subsection @command{payees} @findex payees -The @command{payees} reports all of the unique payees in the journal. +The @command{payees} command reports all of the unique payees in the journal. Using the @option{--count} option will tell you how many entries use -each payee. To filter the payees displayed you must use the prefix: +each payee. To filter the payees displayed you must use the prefix @@: @smallexample $ ledger payees @@Nic @@ -5213,7 +5218,7 @@ you how many entries use each commodity. @findex tags @findex --values -The @command{tags} reports all of the tags in the journal. The output +The @command{tags} command reports all of the tags in the journal. The output is sorted by name. Using the @option{--count} option will tell you how many entries use each tag. Using the @option{--values} option will report the values used by each tag. @@ -5303,7 +5308,7 @@ FIX THIS ENTRY @c FIXME thdox @section Basic Usage This chapter describes Ledger's features and options. You may wish to -survey this to get an overview before diving in to the @ref{Ledger +survey this to get an overview before diving into the @ref{Ledger Tutorial} and more detailed examples that follow. Ledger has a very simple command-line interface, named---enticingly @@ -5374,14 +5379,14 @@ Show all transactions with running total. Show transactions in csv format, for exporting to other programs. @item print -Print transaction in a ledger readable format. +Print transactions in a format readable by ledger. @item xml Produce XML output of the register command. @item lisp @itemx emacs -Produce Emacs lisp output. +Produce s-expression output, suitable for Emacs. @item equity Print account balances as transactions. @@ -5390,7 +5395,7 @@ Print account balances as transactions. Print price history for matching commodities. @item pricedb -Print price history for matching commodities in ledger readable format. +Print price history for matching commodities in a format readable by ledger. @item xact Generate transactions based on previous postings. @@ -5420,7 +5425,7 @@ Redirect output to @file{FILE}. @item --init-file @var{FILE} @itemx -i @var{FILE} -Specify options file. +Specify an options file. @item --account @var{STR} @itemx -a @var{STR} @@ -5435,22 +5440,22 @@ Specify default account @var{STR} for QIF file postings. @item --current @itemx -c -Display transaction on or before the current date. +Display only transactions on or before the current date. @item --begin @var{DATE} @itemx -b @var{DATE} -Begin reports on or after @var{DATE}. +Limit the processing to transactions on or after @var{DATE}. @item --end @var{DATE} @itemx -e @var{DATE} -Limit end date of transactions for report. +Limit the processing to transactions before @var{DATE}. @item --period @var{PERIOD_EXPRESSION} @itemx -p @var{PERIOD_EXPRESSION} -Set report period to @var{PERIOD_EXPRESSION}. +Limit the processing to transactions in @var{PERIOD_EXPRESSION}. @item --period-sort @var{VEXPR} -Sort postings within each period. +Sort postings within each period according to @var{VEXPR}. @item --cleared @itemx -C @@ -5469,7 +5474,7 @@ Display only real postings. @item --actual @itemx -L -Display only actual postings, not automated. +Display only actual postings, not automated ones. @item --related @itemx -r @@ -5479,17 +5484,17 @@ Display related postings. Display how close your postings meet your budget. @item --add-budget -Show un-budgeted postings. +Show unbudgeted postings. @item --unbudgeted -Show only un-budgeted postings. +Show only unbudgeted postings. @item --forecast @var{VEXPR} Project balances into the future. @item --limit @var{EXPR} @itemx -l @var{EXPR} -Limit postings in calculations. +Limit which postings are used in calculations by @var{EXPR}. @item --amount @var{EXPR} @itemx -t @var{EXPR} @@ -5516,7 +5521,8 @@ Accounts, tags or commodities not previously declared will cause errors. @item --check-payees Enable strict and pedantic checking for payees as well as accounts, -commodities and tags. +commodities and tags. This only works in conjunction with +@option{--strict} or @option{--pedantic}. @item --immediate Instruct ledger to evaluate calculations immediately rather than lazily. @@ -5542,18 +5548,21 @@ Report subtotals by payee. @item --empty @itemx -E -Include empty accounts in report. +Include empty accounts in the report. @item --weekly @itemx -W Report posting totals by week. +@item --quarterly +Report posting totals by quarter. + @item --yearly @itemx -Y Report posting totals by year. @item --dow -Report Posting totals by day of week. +Report posting totals by day of week. @item --sort @var{VEXPR} @itemx -S @var{VEXPR} @@ -5574,11 +5583,11 @@ Direct output to @var{FILE} pager program. @item --average @itemx -A -Report average posting value. +Report the average posting value. @item --deviation @itemx -D -Report each posting deviation from the average. +Report each posting's deviation from the average. @item --percent @itemx -% @@ -5591,21 +5600,21 @@ Produce a pivot table of the @var{TAG} type specified. @item --amount-data @itemx -j -Show only date and value column to format the output for plots. +Show only the date and value columns to format the output for plots. @item --plot-amount-format @var{FORMAT_STRING} Specify the format for the plot output. @item --total-data @itemx -J -Show only dates and totals to format the output for plots. +Show only the date and total columns to format the output for plots. @item --plot-total-format @var{FORMAT_STRING} Specify the format for the plot output. @item --display @var{EXPR} @itemx -d @var{EXPR} -Display only posting that meet the criteria in the @var{EXPR}. +Display only postings that meet the criteria in the @var{EXPR}. @item --date-format @var{DATE_FORMAT} @itemx -y @var{DATE_FORMAT} @@ -5616,11 +5625,7 @@ Change the basic date format used in reports. @itemx --register-format @var{FORMAT_STRING} @itemx --prices-format @var{FORMAT_STRING} @itemx -F @var{FORMAT_STRING} -Set reporting format. - -@item --wide -@itemx -w -Wide. +Set the reporting format for various reports. @item --anon Print the ledger register with anonymized accounts and payees, useful @@ -5661,7 +5666,7 @@ Group by day of weeks. @item --subtotal @itemx -s -Group posting together, similar to balance report. +Group postings together, similar to the balance report. @end ftable @@ -5679,10 +5684,10 @@ Set expected freshness of prices in @var{INT} minutes. @item --download @itemx -Q -Download quotes using named @file{getquote}. +Download quotes using the script named @file{getquote}. @item --getquote @var{FILE} -Sets path to a user defined script to download commodity prices. +Sets the path to a user-defined script to download commodity prices. @item --quantity @itemx -O @@ -5719,7 +5724,7 @@ Report net gain or loss for commodities that have a price history. @node Global Options, Session Options, Detailed Option Description, Detailed Option Description @subsection Global Options -Options for Ledger report affect three separate scopes of operation: +Options for Ledger reports affect three separate scopes of operation: Global, Session, and Report. In practice there is very little difference between these scopes. Ledger 3.0 contains provisions for GUIs, which would make use of the different scopes by keeping an @@ -5730,8 +5735,8 @@ sessions with multiple reports per session. @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 +use only command-line arguments to control Ledger. Useful for debugging +or testing small journal files not associated with your main financial database. @item --debug @var{CODE} @@ -5739,7 +5744,7 @@ FIX THIS ENTRY @c FIXME thdox @item --help @itemx -h -Display the info page for ledger. +Display the man page for ledger. @item --init-file @var{FILE} Specify the location of the init file. The default is @file{~/.ledgerrc}. @@ -5779,7 +5784,7 @@ $ ledger --options bal --cleared -f ~/ledger/test/input/drewr3.dat @noindent For the source column, a value starting with a @samp{-} or @samp{--} -indicated the source was a command line argument. It the entry starts +indicated the source was a command line argument. If the entry starts with a @samp{$}, 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}. @@ -5808,7 +5813,7 @@ FIX THIS ENTRY @c FIXME thdox @node Session Options, Report Options, Global Options, Detailed Option Description @subsection Session Options -Options for Ledger report affect three separate scopes of operation: +Options for Ledger reports affect three separate scopes of operation: Global, Session, and Report. In practice there is very little difference between these scopes. Ledger 3.0 contains provisions for GUIs, which would make use of the different scopes by keeping an @@ -5828,11 +5833,11 @@ FIX THIS ENTRY @c FIXME thdox @item --decimal-comma Direct Ledger to parse journals using the European standard comma as -decimal separator, vice a period. +a decimal separator, not the usual period. @item --download @itemx -Q -Direct Ledger to download prices using the script defined in +Direct Ledger to download prices using the script defined via the option @option{--getquote @var{FILE}}. @item --explicit @@ -5910,10 +5915,10 @@ 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 -@option{--strict} changes that behavior. While running +even if you have misspelled a commonly used one. The option +@option{--strict} changes that behavior. While running with @option{--strict}, Ledger interprets all cleared transactions as -correct, and if it finds a new account or commodity (same as +correct, and if it encounters 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. @@ -5937,7 +5942,7 @@ FIX THIS ENTRY @c FIXME thdox @node Report Options, Basic options, Session Options, Detailed Option Description @subsection Report Options -Options for Ledger report affect three separate scopes of operation: +Options for Ledger reports affect three separate scopes of operation: Global, Session, and Report. In practice there is very little difference between these scopes. Ledger 3.0 contains provisions for GUIs, which would make use of the different scopes by keeping an @@ -5965,11 +5970,11 @@ to @var{INT} characters. @item --actual @itemx -L -Report only real transactions, with no automated or virtual -transactions used. +Report only real transactions, ignoring all automated or virtual +transactions. @item --add-budget -Show only un-budgeted postings. +Show only unbudgeted postings. @item --amount @var{EXPR} @itemx -t @var{EXPR} @@ -5979,7 +5984,7 @@ arbitrary transformation to the postings. @item --amount-data @itemx -j -On a register report print only the dates and amount of postings. +On a register report print only the date and amount of postings. Useful for graphing and spreadsheet applications. @item --amount-width @var{INT} @@ -6034,12 +6039,12 @@ $ 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. +list all transactions since the beginning of December and print in +bold any posting greater than $100. @item --budget Only display budgeted items. In a register report this -displays transaction in the budget, in a balance report this displays +displays transactions in the budget, in a balance report this displays accounts in the budget (@pxref{Budgeting and Forecasting}). @item --budget-format @var{FORMAT_STRING} @@ -6060,7 +6065,7 @@ Group the register report by payee. @item --cleared @itemx -C -Consider only transaction that have been cleared for display and +Consider only transactions that have been cleared for display and calculation. @item --cleared-format @var{FORMAT_STRING} @@ -6097,7 +6102,7 @@ Specify the width of the @command{register} report in characters. @item --count Direct ledger to report the number of items when appended to the -commodities, accounts or payees command. +@command{commodities}, @command{accounts} or @command{payees} command. @item --csv-format @var{FORMAT_STRING} Specify the format to use for the @command{csv} report (@pxref{Format @@ -6126,8 +6131,8 @@ Transform the date of the transaction using @var{EXPR}. @item --date-format @var{DATE_FORMAT} @itemx -y @var{DATE_FORMAT} -Specify the format ledger should use to print dates (@pxref{Date and Time -Format Codes}). +Specify the format ledger should use to read and print dates +(@pxref{Date and Time Format Codes}). @item --date-width @var{INT} Specify the width, in characters, of the date column in the @@ -6138,8 +6143,9 @@ FIX THIS ENTRY @c ASK JOHN @item --dc Display register or balance in debit/credit format If you use -@option{--dc} with either the register (reg) or balance (bal) commands, -you will now get extra columns. The register goes from this: +@option{--dc} with either the @command{register} (reg) or +@command{balance} (bal) commands, you will now get extra columns. +The register goes from this: @smallexample 12-Mar-10 Employer Assets:Cash $100 $100 @@ -6196,9 +6202,9 @@ And with @option{--dc} it becomes this: @item --depth @var{INT} Limit the depth of the account tree. In a balance report, for example, -a @samp{--depth 2} statement will print balances only for account with +a @samp{--depth 2} statement will print balances only for accounts with two levels, i.e. @samp{Expenses:Entertainment} but not -@samp{Expenses:entertainemnt:Dining}. This is a display predicate, which +@samp{Expenses:Entertainment:Dining}. This is a display predicate, which means it only affects display, not the total calculations. @item --deviation @@ -6206,19 +6212,19 @@ Report each posting’s deviation from the average. It is only meaningful in the register and prices reports. @item --display @var{EXPR} -Display lines that satisfy the expression @var{EXPR}. +Display only lines that satisfy the expression @var{EXPR}. @item --display-amount @var{EXPR} -Apply a transformation to the @emph{displayed} amount. This occurs after +Apply a transformation to the @emph{displayed} amount. This happens after calculations occur. @item --display-total @var{EXPR} -Apply a transformation to the @emph{displayed} total. This occurs after +Apply a transformation to the @emph{displayed} total. This happens after calculations occur. @item --dow @itemx --days-of-week -Group transactions by the days of the week. +Group transactions by the day of the week. @smallexample @c command:validate $ ledger reg Expenses --dow --collapse @@ -6229,11 +6235,11 @@ Will print all Expenses totaled for each day of the week. @item --empty @itemx -E -Include empty accounts in the report. +Include empty accounts in the report and in average calculations. @item --end @var{DATE} Specify the end @var{DATE} for a transaction to be considered in the -report. +report. All transactions on or after this date are ignored. @item --equity Related to the @command{equity} command (@pxref{The @command{equity} @@ -6281,13 +6287,13 @@ transactions) in the report, in cases where you normally wouldn't want them. @item --group-by @var{EXPR} -Group transaction together in the @command{register} report. +Group transactions together in the @command{register} report. @var{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 @var{FORMAT_STRING} -Set the format for the headers that separate reports section of -a grouped report. Only has effect with a @option{--group-by @var{EXPR}} +Set the format for the headers that separates the report sections of +a grouped report. Only has an effect with a @option{--group-by @var{EXPR}} register report. @smallexample @@ -6316,9 +6322,9 @@ FIX THIS ENTRY @c FIXME thdox FIX THIS ENTRY @c FIXME thdox @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: +Use @code{Expected} amounts in calculations. In case you know +what amount a transaction should be, but the actual transaction has the +wrong value you can use metadata to specify the expected amount: @smallexample @c input:validate 2012-03-12 Paycheck @@ -6334,8 +6340,8 @@ Change the sign of all reported values. @item --limit @var{EXPR} @itemx -l @var{EXPR} -Only transactions that satisfy the expression will be considered in the -calculation. +Only transactions that satisfy @var{EXPR} are considered in +calculations and for display. @item --lot-dates Report the date on which each commodity in a balance report was @@ -6380,7 +6386,7 @@ Suppress any color TTY output. @item --no-rounding Don't output @samp{<Rounding>} postings. Note that this will cause the -running total to often not add up! It's main use is for +running total to often not add up! Its main use is for @option{--amount-data (-j)} and @option{--total-data (-J)} reports. @item --no-titles @@ -6390,7 +6396,7 @@ Suppress the output of group titles. Suppress printing the final total line in a balance report. @item --now @var{DATE} -Define the current date in case to you to do calculate in the past or +Define the current date in case you want to calculate in the past or future using @option{--current}. @item --only @var{FIXME} @@ -6417,15 +6423,15 @@ Use only postings that are marked pending. @item --percent @itemx -% -Calculate the percentage value of each account in a balance reports. -Only works for account that have a single commodity. +Calculate the percentage value of each account in balance reports. +Only works for accounts that have a single commodity. @item --period @var{PERIOD_EXPRESSION} Define a period expression that sets the time period during which transactions are to be accounted. For a @command{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. +For a @command{balance} report only those transactions will be accounted +in the final balances. @item --pivot @var{TAG} Produce a balance pivot report @emph{around} the given @var{TAG}. For @@ -6486,7 +6492,7 @@ Synonym for @samp{--period "quarterly"}. @item --raw In the @command{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 +interpreting. This can be useful for minor cleanups, like just aligning amounts. @item --real @@ -6498,7 +6504,7 @@ transactions. Define the output format for the @command{register} report. @item --related -In a register report show the related account. This is the other +In a @command{register} report show the related account. This is the other @emph{side} of the transaction. @item --related-all @@ -6524,14 +6530,14 @@ development testing. @item --sort @var{VEXPR} @itemx -S @var{VEXPR} -Sort the register report based on the value expression given to sort. +Sort the @command{register} report based on the value expression given to sort. @item --sort-all @var{FIXME} FIX THIS ENTRY @item --sort-xacts @var{VEXPR} @itemx --period-sort @var{VEXPR} -Sort the posting within transactions using the given value expression. +Sort the postings within transactions using the given value expression. @item --start-of-week @var{INT} Tell ledger to use a particular day of the week to start its ``weekly'' @@ -6544,7 +6550,7 @@ FIX THIS ENTRY @item --tail @var{INT} @itemx --last @var{INT} -Report only the last @var{INT} entries. Only useful on a register +Report only the last @var{INT} entries. Only useful in a @command{register} report. @item --time-report @@ -6569,7 +6575,7 @@ as it considers sub-names within the account name (that style is called ``abbreviate''). @item --unbudgeted -Show only un-budgeted postings. +Show only unbudgeted postings. @item --uncleared @itemx -U @@ -6600,8 +6606,8 @@ FIX THIS ENTRY @c FIXME thdox Synonym for @samp{--period "weekly"}. @item --wide -Let the register report use 132 columns. Identical to @samp{--columns -"132"}. +Let the register report use 132 columns instead of 80 (the default). +Identical to @samp{--columns "132"}. @item --yearly @itemx -Y @@ -6621,19 +6627,17 @@ variables}), instead of using actual command-line options: @item --help @itemx -h Print 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. +can be a handy way to remember which options do what. @item --version -@itemx -v Print 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 @var{FILE} @itemx -f @var{FILE} -Read @file{FILE} as a ledger file. @var{FILE} can be @samp{-} that is -a synonym of @samp{/dev/stdin}. This command may be used multiple +Read @file{FILE} as a ledger file. @var{FILE} can be @samp{-} which is +a synonym for @samp{/dev/stdin}. This command may be used multiple times. Typically, the environment variable @env{LEDGER_FILE} is set, rather than using this command-line option. @@ -6647,12 +6651,12 @@ goes to standard output. Causes @file{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 its own line. Here is an +on the command-line, but put each option on its own line. Here is an example init file: @smallexample --price-db ~/finance/.pricedb - +--wide ; ~/.ledgerrc ends here @end smallexample @@ -6689,7 +6693,7 @@ first matching transaction. (Note: This is different from using @item --end @var{DATE} @itemx -e @var{DATE} Constrain the report so that transactions on or after @var{DATE} are -not considered. The ending date is inclusive. +not considered. @item --period @var{PERIOD_EXPRESSION} @itemx -p @var{PERIOD_EXPRESSION} @@ -6697,7 +6701,7 @@ Set 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 @samp{last June} or @samp{next month}. For more using period +terms like @samp{last June} or @samp{next month}. For more details on period expressions, see @ref{Period Expressions}. @item --period-sort @var{VEXPR} @@ -6706,8 +6710,9 @@ 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 @c input:validate -$ ledger -M --period-sort -At reg ^Expenses +@c TODO: the parameter to --period-sort was -At, which doesn't seem to work any longer +@smallexample @c command:validate +$ ledger -M --period-sort total reg ^Expenses @end smallexample @item --cleared @@ -6728,8 +6733,8 @@ see @ref{Virtual postings} for more information). @item --actual @itemx -L -Display only actual postings, and not those created due to automated -postings. +Display only actual postings, and not those created by automated +transactions. @item --related @itemx -r @@ -6753,7 +6758,7 @@ And the register command was: $ ledger -f example.dat -r register food @end smallexample -The following would be output, showing the postings related to the +The following would be printed, showing the postings related to the posting that matched: @smallexample @c output:94C5675 @@ -6763,7 +6768,7 @@ posting that matched: @item --budget Useful for displaying how close your postings meet your budget. -@option{--add-budget} also shows un-budgeted postings, while +@option{--add-budget} also shows unbudgeted postings, while @option{--unbudgeted} shows only those. @option{--forecast @var{VEXPR}} is a related option that projects your budget into the future, showing how it will affect future balances. @xref{Budgeting and Forecasting}. @@ -6868,22 +6873,22 @@ Report posting totals by month. @item --yearly @itemx -Y -Report posting totals by year. For more complex period, using the +Report posting totals by year. For more complex periods, use @option{--period}. @c TODO end this sentence @item --period @var{PERIOD_EXPRESSION} Option described above. @item --dow -Report postings totals for each day of the week. This is an easy way +Report posting totals for each day of the week. This is an easy way to see if weekend spending is more than on weekdays. @item --sort @var{VEXPR} @itemx -S @var{VEXPR} Sort a report by comparing the values determined using the value -expression @var{VEXPR}. For example, using @samp{-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, +expression @var{VEXPR}. For example, using @samp{-S "-abs(total)"} in the +@command{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 @var{TAG} @@ -6928,7 +6933,7 @@ the parent account. @item --amount-data @itemx -j -Change the @command{register} report so that it outputs nothing but the +Change the @command{register} report so that it prints 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, @@ -6936,12 +6941,12 @@ etc. @item --total-data @itemx -J -Change the @command{register} report so that it outputs nothing but the -date and totals column, without commodities. +Change the @command{register} report so that it prints nothing but the +date and total columns, without commodities. @item --display @var{EXPR} @itemx -d @var{EXPR} -Limit which postings or accounts or actually displayed in a report. +Limit which postings or accounts are 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 @@ -7151,7 +7156,7 @@ 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{--amount @var{EXPR} (-t)} and @option{--total @var{VEXPR} (-T)} options. However, there are also -several ``default'' reports, which will satisfy most users basic +several ``default'' reports, which will satisfy most users' basic reporting needs: @ftable @code @@ -7259,7 +7264,7 @@ specific meta-data: Assets:Cash @end smallexample -This example demonstrates that your VALUE expression should be as +This example demonstrates that your value expression should be as symbolic as possible, using terms like 'amount' and 'date', rather than specific amounts and dates. Also, you should pass the amount along to the function 'market' so it can be further revalued if the user has @@ -7270,6 +7275,8 @@ which allows you to report most everything in EUR if you use @samp{-X EUR}, except for certain accounts or postings which should always be valuated in another currency. For example: +@c TODO is this example missing the actual line to get the effect? +@c it looks like it only contains a match, but no effect @smallexample @c input:validate = /^Assets:Brokerage:CAD$/ ; Always report the value of commodities in this account in @@ -7306,13 +7313,13 @@ these values: @itemize @item Register Report -For the register report, use the value of that commodity on the date of +For the @command{register} report, use the value of that commodity on the date of the posting being reported, with a @samp{<Revalued>} posting added at -the end of today's value is different from the value of the last +the end if today's value is different from the value of the last posting. @item Balance Report -For the balance report, use the value of that commodity as of today. +For the @command{balance} report, use the value of that commodity as of today. @end itemize @@ -7474,7 +7481,7 @@ payee. For example: These two periodic transactions give the usual monthly expenses, as well as one typical yearly expense. For help on finding out what your -average monthly expense is for any category, use a command like: +average monthly expenses are for any category, use a command like: @smallexample $ ledger -p "this year" --monthly --average balance ^expenses @@ -7498,7 +7505,7 @@ $ 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 +@option{--add-budget}. You can even see only the unbudgeted expenses using @option{--unbudgeted}: @smallexample @c command:validate @@ -7521,11 +7528,11 @@ $ ledger --forecast "T>@{\$-500.00@}" register ^assets ^liabilities @end smallexample This report continues outputting postings until the running total -is greater than $-500.00. A final posting is always output, to -show you what the total afterwards would be. +is greater than $-500.00. A final posting is always shown, to +inform you what the total afterwards would be. -Forecasting can also be used with the balance report, but by date -only, and not against the running total: +Forecasting can also be used with the @command{balance} report, +but by date only, and not against the running total: @smallexample @c command:validate $ ledger --forecast "d<[2010]" bal ^assets ^liabilities @@ -7545,21 +7552,21 @@ o 2013/03/29 03:39:00 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 @option{--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 @samp{O}, the transaction is -marked ``cleared''. You can use an optional PAYEE for whatever meaning -you like. +report). The number of seconds between check-in and check-out is accumulated +as time to that ACCOUNT. If the checkout uses a capital @samp{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 Wiegley. +the @samp{org2tc} script developed by John Wiegley. These timelog entries can appear in a separate file, or directly in -your main ledger file. The initial @samp{i} and @samp{o} count as -Ledger ``directives'', and are accepted anywhere that ordinary -transactions are. +your main ledger file. The initial @samp{i} and @samp{o} characters +count as Ledger ``directives'', and are accepted anywhere that +ordinary transactions are valid. @node Value Expressions, Format Strings, Time Keeping, Top @chapter Value Expressions @@ -7612,7 +7619,7 @@ while still calculating the running balance based on all transactions: $ ledger -d "d>[this month]" register checking @end smallexample -This advantage to this command's complexity is that it prints the +The advantage of 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 postings: @@ -7634,9 +7641,9 @@ $ ledger -b "this month" register checking @findex --total @var{VEXPR} 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 +For the @command{register} and @command{print} commands, these variables +relate to individual postings, and sometimes the account affected by a +posting. For the @command{balance} command, these variables relate to accounts, often with a subtle difference in meaning. The use of each variable for both is specified. @@ -7644,8 +7651,8 @@ variable for both is specified. @item t This maps to whatever the user specified with @option{--amount -@var{EXPR} (-t)}. In a register report, @option{--amount @var{EXPR} -(-t)} changes the value column; in a balance report, it has no meaning +@var{EXPR} (-t)}. In a @command{register} report, @option{--amount @var{EXPR} +(-t)} changes the value column; in a @command{balance} report, it has no meaning by default. If @option{--amount @var{EXPR} (-t)} was not specified, the current report style's value expression is used. @@ -7684,15 +7691,15 @@ The cost of a posting; the cost of an account, without its children. @item v -The market value of a posting, or an account without its children. +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 @samp{v-b}. @item l The depth (``level'') of an account. If an account has one parent, -it's depth is one. +its depth is one. @item n The index of a posting, or the count of postings affecting an @@ -7843,10 +7850,10 @@ posting. @item c/REGEX/ A regular expression that matches against the transaction code (the -text that occurs between parentheses before the payee name). +text that occurs between parentheses before the payee). @item e/REGEX/ -A regular expression that matches against a posting's note, or +A regular expression that matches against a posting's note or comment field. @item (EXPR) @@ -7855,7 +7862,7 @@ more complicated arguments to functions, or for overriding the natural precedence order of operators. @item [DATE] -Useful specifying a date in plain terms. For example, you could say +Useful for specifying a date in plain terms. For example, you could say @samp{[2004/06/01]}. @end table @@ -8038,8 +8045,8 @@ format string, exactly like those supported by @code{strftime}. For example: @samp{%[%Y/%m/%d %H:%M:%S]}. @item S -Insert the pathname of the file from which the transaction's data was -read. Only sensible in a register report. +Insert the path name of the file from which the transaction's data was +read. Only sensible in a @command{register} report. @item B Inserts the beginning character position of that transaction within the @@ -8072,8 +8079,8 @@ This is the same as @samp{%X}, except that it only displays a state character if all of the member postings have the same state. @item C -Inserts the transaction type. This is the value specified between -parenthesis on the first line of the transaction. +Inserts the transaction code. This is the value specified between +parentheses on the first line of the transaction. @item P Inserts the payee related to a posting. @@ -8159,7 +8166,7 @@ options: @node Colors, Quantities and Calculations, Field Widths, Formatting Functions and Codes @subsection Colors -The character based formatting ledger can do is limited to the ANSI +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 @@ -8300,10 +8307,10 @@ weekday, abbreviated Wed. weekday, full Wednesday. @item %d -day of the month (dd), zero padded 10. +day of the month (dd), zero padded up to 10. @item %e -day of the month (dd) 10. +day of the month (dd) , no leading zero up to 10. @item %j day of year, zero padded 000–366. @@ -8345,7 +8352,7 @@ Locale’s abbreviated month, for example @samp{02} might be abbreviated as @samp{Feb}. @item %B -Locale’s full month, variable length February. +Locale’s full month, variable length, e.g. February. @end table @@ -8398,7 +8405,7 @@ subsequent lines the width is given by @code{latterwidth}. If 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. +@code{colorize} is true, then ledger will honor color settings. @item join(STR) Replaces line feeds in @code{STR} with @samp{\n}. @@ -8422,7 +8429,7 @@ generated the posting. @table @code @item filename -name of ledger data file from whence posting came, abbreviated @samp{S}. +the name of ledger the data file from whence the posting came, abbreviated @samp{S}. @item beg_pos character position in @code{filename} where entry for posting begins, @@ -8463,16 +8470,16 @@ make sense later. 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. +like the Commodities that Amounts 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. -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. +Within the Journal live all the Transactions, Postings, and other +objects related to your data. There are also AutomatedTransactions +and PeriodicTransactions, etc. Here is how you would traverse all the postings in your data file: @@ -8520,7 +8527,7 @@ While the @emph{cooked} form is: 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 +When you traverse a Journal by iterating over 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: @@ -8630,7 +8637,7 @@ reused in other projects as needed. @item Commoditized Amounts (amount_t, commodity_t and friends) -An numerical abstraction combining multi-precision rational numbers (via +A 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). @@ -8686,7 +8693,7 @@ string (cash) down to the corresponding value expression @samp{(account @item Format strings -Format strings let you interpolate value expressions into string, with +Format strings let you interpolate value expressions into strings, 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 @@ -8728,7 +8735,7 @@ querying ad reporting on your data. @item Textual journal parser -There is a textual parser, wholly contained in textual.cc, which knows +There is a textual parser, wholly contained in @file{textual.cc}, which knows how 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. @@ -8736,7 +8743,7 @@ double-entry guarantee. @item Iterators Every journal object is ``iterable'', and these iterators are defined in -iterators.h and iterators.cc. This iteration logic is kept out of the +@file{iterators.h} and @file{iterators.cc}. This iteration logic is kept out of the basic journal objects themselves for the sake of modularity. @item Comparators @@ -8749,7 +8756,7 @@ the user passed to @option{--sort @var{VEXPR}}. Many reports bring pseudo-journal objects into existence, like postings which report totals in a @samp{Total} account. These objects are -created and managed by a temporaries_t object, which gets used in many +created and managed by a @code{temporaries_t} object, which gets used in many places by the reporting filters. @item Option handling @@ -8767,7 +8774,7 @@ a separate session. They are all owned by the global scope. @item Report objects -Every time you create report output, a report object is created to +Every time you create any report output, a report object is created to determine what you want to see. In the Ledger REPL, a new report object is created every time a command is executed. In CLI mode, only one report object ever comes into being, as Ledger immediately exits after @@ -8790,7 +8797,7 @@ 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 -@file{filters.h}, I see over 25 of them defined currently. +@file{filters.h}, there are over 25 of them defined currently. @item The filter chain @@ -8803,9 +8810,9 @@ 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 +This is the job of special ``leaf'' filters called 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 +a ``next'' filter to pass the data 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. @@ -8860,9 +8867,9 @@ journal files: In this example, there is a transaction date, a payee, or description of the transaction, and two postings. The postings show movement of one hundred dollars from an account within the Income hierarchy, to the -specified expense account. The name and meaning of these accounts in +specified expense account. The name and meaning of these accounts is arbitrary, with no preferences implied, although you will find it useful -to follow standard accounting practice (@pxref{Principles of Accounting +to follow standard accounting practices (@pxref{Principles of Accounting with Ledger}). Since an amount is missing from the second posting, it is assumed to be @@ -8910,7 +8917,7 @@ are covered here, though it must be said that sometimes, there are multiple ways to achieve a desired result. @emph{Note:} It is important to note that there must be at least two -spaces between the end of the post and the beginning of the amount +spaces between the end of the account and the beginning of the amount (including a commodity designator). @menu @@ -9048,7 +9055,7 @@ implied cost for you. You can also make the cost explicit using a @end smallexample Here the @dfn{per-unit cost} is given explicitly in the form of a cost -amount; and since cost amount are @emph{unobserved}, the use of six +amount; and since cost amounts are @emph{unobserved}, the use of six decimal places has no effect on how dollar amounts are displayed in the final report. You can also specify the @dfn{total cost}: @@ -9081,9 +9088,9 @@ posting automatically so that the transaction balances. In every transaction involving more than one commodity, there is always one which is the @dfn{primary commodity}. This commodity should be thought of as the exchange commodity, or the commodity used -to buy and sells units of the other commodity. In the fruit examples +to buy and sell units of the other commodity. In the fruit examples above, dollars are the primary commodity. This is decided by Ledger -on the placement of the commodity in the transaction: +based on the placement of the commodity in the transaction: @smallexample @c input:validate 2010/05/31 Sample Transaction @@ -9105,7 +9112,7 @@ play is in reports that use the @option{--market (-V)} or shown. If a transaction uses only one commodity, this commodity is also -considered a primary. In fact, when Ledger goes about ensures that +considered a primary. In fact, when Ledger goes about ensuring that all transactions balance to zero, it only ever asks this of primary commodities. @@ -9138,8 +9145,8 @@ nothing for a command line user. @subsection @command{source} @findex source -The @command{source} command take a journal file as an argument and -parses it checking for errors, no other reports are generated, and no +The @command{source} command takes 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. @@ -9240,7 +9247,7 @@ 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. +by the @samp{GenerateTests} harness for development testing. @item parse @var{VEXPR} @itemx expr @var{VEXPR} @@ -9334,13 +9341,13 @@ This is a debugging command. @subsection Testing Framework Ledger source ships with a fairly complete set of tests to verify that -all is well, and no old errors have been resurfaced. Tests are run +all is well, and no old errors have resurfaced. Tests are run individually with @file{ctest}. All tests can be run using @code{make check} or @code{ninja check} depending on which build tool you prefer. 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{test} subdirectory for the build. For example, @file{~/ledger/build/ledger/opt/test}. @menu @@ -9362,7 +9369,7 @@ build location. To execute a single test use @code{ctest -V -R regex}, where the regex matches the name of the test you want to build. There are nearly 300 tests stored under the @file{test} subdirectory -in main source distribution. They are broken into two broad +in the main source distribution. They are broken into two broad categories, baseline and regression. To run the @file{5FBF2ED8} test, for example, issue @samp{ctest -V -R "5FB"}. |