From 21b3a56489d58d4921f2f20fa6712a50fc9c16a2 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 25 Apr 2018 08:57:33 -0700 Subject: [PATCH] doc: budget report: update --- hledger/hledger_balance.m4.md | 147 +++++++++++++++++----------------- 1 file changed, 73 insertions(+), 74 deletions(-) diff --git a/hledger/hledger_balance.m4.md b/hledger/hledger_balance.m4.md index 594e8607d..ea32d3e08 100644 --- a/hledger/hledger_balance.m4.md +++ b/hledger/hledger_balance.m4.md @@ -249,14 +249,79 @@ Currently, the [`-V/--value` flag](#market-value) has a limitation in multicolumn reports: it uses the market prices on the report end date for all columns. (Instead of the prices on each column's end date.) -### Budgets +### Custom balance output -With `--budget` and a [report interval](manual.html#report-intervals), -all [periodic transactions](journal.html#periodic-transactions) in your journal -with that interval, -active during the requested report period, -are interpreted as recurring budget goals for the specified accounts (and subaccounts), -and the report will show the difference between actual and budgeted balances. +You can customise the layout of simple (non-tabular) balance reports with `--format FMT`: + +```shell +$ hledger balance --format "%20(account) %12(total)" + assets $-1 + bank:saving $1 + cash $-2 + expenses $2 + food $1 + supplies $1 + income $-2 + gifts $-1 + salary $-1 + liabilities:debts $1 +--------------------------------- + 0 +``` + +The FMT format string (plus a newline) specifies the formatting +applied to each account/balance pair. It may contain any suitable +text, with data fields interpolated like so: + +`%[MIN][.MAX](FIELDNAME)` + +- MIN pads with spaces to at least this width (optional) +- MAX truncates at this width (optional) +- FIELDNAME must be enclosed in parentheses, and can be one of: + + - `depth_spacer` - a number of spaces equal to the account's depth, or if MIN is specified, MIN * depth spaces. + - `account` - the account's name + - `total` - the account's balance/posted total, right justified + +Also, FMT can begin with an optional prefix to control how +multi-commodity amounts are rendered: + +- `%_` - render on multiple lines, bottom-aligned (the default) +- `%^` - render on multiple lines, top-aligned +- `%,` - render on one line, comma-separated + +There are some quirks. Eg in one-line mode, `%(depth_spacer)` has no +effect, instead `%(account)` has indentation built in. + +Experimentation may be needed to get pleasing results. + +Some example formats: + +- `%(total)` - the account's total +- `%-20.20(account)` - the account's name, left justified, padded to 20 characters and clipped at 20 characters +- `%,%-50(account) %25(total)` - account name padded to 50 characters, total padded to 20 characters, with multiple commodities rendered on one line +- `%20(total) %2(depth_spacer)%-(account)` - the default format for the single-column balance report + +This command also supports [output destination](/manual.html#output-destination) and [output format](/manual.html#output-format) selection. + +### Colour support + +The balance command shows negative amounts in red, if: + +- the `TERM` environment variable is not set to `dumb` +- the output is not being redirected or piped anywhere + + +### Budget report + +With `--budget`, extra columns are displayed showing budget goals for each account and period, +and how the actual amounts compare with the goals. +Budget goals are defined by [periodic transactions](journal.html#periodic-transactions) in the journal. + +--budget is most often combined with a [report interval](manual.html#report-intervals). For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget: ```journal @@ -340,74 +405,8 @@ Balance changes in 2017/11/01-2017/12/31: ``` Note --budget first arrived in hledger in 1.5 and is still pretty young; -join the discussions on mail list and issue tracker to help us refine it. +join the discussions on mail list and issue tracker to help us refine it. Also, the `-S/--sort-amount` flag is not yet supported with --budget. For more examples, see [Budgeting and Forecasting](https://github.com/simonmichael/hledger/wiki/Budgeting and forecasting). -### Custom balance output - -You can customise the layout of simple (non-tabular) balance reports with `--format FMT`: - -```shell -$ hledger balance --format "%20(account) %12(total)" - assets $-1 - bank:saving $1 - cash $-2 - expenses $2 - food $1 - supplies $1 - income $-2 - gifts $-1 - salary $-1 - liabilities:debts $1 ---------------------------------- - 0 -``` - -The FMT format string (plus a newline) specifies the formatting -applied to each account/balance pair. It may contain any suitable -text, with data fields interpolated like so: - -`%[MIN][.MAX](FIELDNAME)` - -- MIN pads with spaces to at least this width (optional) -- MAX truncates at this width (optional) -- FIELDNAME must be enclosed in parentheses, and can be one of: - - - `depth_spacer` - a number of spaces equal to the account's depth, or if MIN is specified, MIN * depth spaces. - - `account` - the account's name - - `total` - the account's balance/posted total, right justified - -Also, FMT can begin with an optional prefix to control how -multi-commodity amounts are rendered: - -- `%_` - render on multiple lines, bottom-aligned (the default) -- `%^` - render on multiple lines, top-aligned -- `%,` - render on one line, comma-separated - -There are some quirks. Eg in one-line mode, `%(depth_spacer)` has no -effect, instead `%(account)` has indentation built in. - -Experimentation may be needed to get pleasing results. - -Some example formats: - -- `%(total)` - the account's total -- `%-20.20(account)` - the account's name, left justified, padded to 20 characters and clipped at 20 characters -- `%,%-50(account) %25(total)` - account name padded to 50 characters, total padded to 20 characters, with multiple commodities rendered on one line -- `%20(total) %2(depth_spacer)%-(account)` - the default format for the single-column balance report - -This command also supports [output destination](/manual.html#output-destination) and [output format](/manual.html#output-format) selection. - -### Colour support - -The balance command shows negative amounts in red, if: - -- the `TERM` environment variable is not set to `dumb` -- the output is not being redirected or piped anywhere - -