From e927e587e6981866afb1a7d32332da53e8bd38e3 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 31 Dec 2017 10:01:18 -0800 Subject: [PATCH] lib,cli: auto/forecast/budget option/docs cleanup, consistency --- doc/lib.m4 | 12 +++++------- hledger-lib/hledger_journal.m4.md | 12 +++++++++--- hledger/Hledger/Cli/CliOptions.hs | 4 ++-- hledger/Hledger/Cli/Commands/Balance.hs | 8 ++++---- hledger/hledger_balance.m4.md | 23 +++++++++++++++-------- 5 files changed, 35 insertions(+), 24 deletions(-) diff --git a/doc/lib.m4 b/doc/lib.m4 index 5f128899f..6ab4626e3 100644 --- a/doc/lib.m4 +++ b/doc/lib.m4 @@ -156,14 +156,12 @@ m4_define({{_reportingoptions_}}, {{ : convert amounts to their market value on the report end date (using the most recent applicable [market price](journal.html#market-prices), if any) -`--forecast` -: generate forecast transactions from [periodic transaction](journal.html#periodic-transactions) rules. -Each periodic transaction rule will generate [forecast transactions](budgeting-and-forecasting.html#forecasting), -beginning the day after the last recorded journal transaction, -and ending 6 months from today, or at the specified report end date. - `--auto` -: apply [automated posting rules](journal.html#automated-posting-rules) to modify transactions where applicable (can combine with --forecast). +: apply [automated posting rules](journal.html#automated-posting-rules) to modify transactions. + +`--forecast` +: apply [periodic transaction](journal.html#periodic-transactions) rules to generate future transactions, to 6 months from now or report end date. + When a reporting option appears more than once in the command line, the last one takes precedence. diff --git a/hledger-lib/hledger_journal.m4.md b/hledger-lib/hledger_journal.m4.md index 9d0bb45e2..8d8622b28 100644 --- a/hledger-lib/hledger_journal.m4.md +++ b/hledger-lib/hledger_journal.m4.md @@ -865,12 +865,18 @@ A periodic transaction starts with a tilde ‘~’ in place of a date followed b income:acme inc ``` -Periodic transactions are used for budgeting and forecasting only, they have no effect without the `--forecast` or `--budget` option specified. -For examples and details, see [Budgeting and Forecasting](budgeting-and-forecasting.html). +Periodic transactions are used for forecasting and budgeting only, they have no effect unless the `--forecast` or `--budget` flag is used. +With `--forecast`, each periodic transaction rule generates recurring forecast transactions +at the specified interval, beginning the day after the last recorded journal transaction +and ending 6 months from today, or at the specified report end date. +With `balance --budget`, each periodic transaction declares recurring budget goals for one or more accounts. +For more details, see: +[balance > Budgeting](manual.html#budgeting), +[Budgeting and Forecasting](budgeting-and-forecasting.html). # Automated posting rules -Autopated posting rule starts with an equal sign '=' in place of a date, followed by a [query](manual.html#queries): +Automated posting rule starts with an equal sign '=' in place of a date, followed by a [query](manual.html#queries): ```journal = expenses:gifts budget:gifts *-1 diff --git a/hledger/Hledger/Cli/CliOptions.hs b/hledger/Hledger/Cli/CliOptions.hs index 1a4ac89ed..530515cb5 100644 --- a/hledger/Hledger/Cli/CliOptions.hs +++ b/hledger/Hledger/Cli/CliOptions.hs @@ -155,8 +155,8 @@ reportflags = [ ,flagNone ["empty","E"] (setboolopt "empty") "show items with zero amount, normally hidden" ,flagNone ["cost","B"] (setboolopt "cost") "convert amounts to their cost at transaction time (using the transaction price, if any)" ,flagNone ["value","V"] (setboolopt "value") "convert amounts to their market value on the report end date (using the most recent applicable market price, if any)" - ,flagNone ["forecast"] (setboolopt "forecast") "apply periodic transaction rules to generate future transactions, 6 months into the future or to report end date" - ,flagNone ["auto"] (setboolopt "auto") "apply automated posting rules to modify transactions where applicable (can combine with --forecast)" + ,flagNone ["auto"] (setboolopt "auto") "apply automated posting rules to modify transactions" + ,flagNone ["forecast"] (setboolopt "forecast") "apply periodic transaction rules to generate future transactions, to 6 months from now or report end date" ] -- | Common output-related flags: --output-file, --output-format... diff --git a/hledger/Hledger/Cli/Commands/Balance.hs b/hledger/Hledger/Cli/Commands/Balance.hs index af82da9e7..d346f0cb3 100644 --- a/hledger/Hledger/Cli/Commands/Balance.hs +++ b/hledger/Hledger/Cli/Commands/Balance.hs @@ -283,10 +283,10 @@ balancemode = (defCommandMode $ ["balance"] ++ aliases) { -- also accept but don ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "omit N leading account name parts (in flat mode)" ,flagNone ["no-elide"] (\opts -> setboolopt "no-elide" opts) "don't squash boring parent accounts (in tree mode)" ,flagReq ["format"] (\s opts -> Right $ setopt "format" s opts) "FORMATSTR" "use this custom line format (in simple reports)" - ,flagNone ["pretty-tables"] (\opts -> setboolopt "pretty-tables" opts) "use unicode when displaying tables" - ,flagNone ["sort-amount","S"] (\opts -> setboolopt "sort-amount" opts) "sort by amount instead of account name" - ,flagNone ["budget"] (setboolopt "budget") "compute budget from periodic transactions and compare real balances to it" - ,flagNone ["show-unbudgeted"] (setboolopt "show-unbudgeted") "show full names of accounts not mentioned in budget" + ,flagNone ["pretty-tables"] (\opts -> setboolopt "pretty-tables" opts) "use unicode to display prettier tables" + ,flagNone ["sort-amount","S"] (\opts -> setboolopt "sort-amount" opts) "sort by amount instead of account name (in flat mode). With multiple columns, sorts by the row total, or by row average if that is displayed." + ,flagNone ["budget"] (setboolopt "budget") "show performance compared to budget goals defined by periodic transactions" + ,flagNone ["show-unbudgeted"] (setboolopt "show-unbudgeted") "with --budget, show unbudgeted accounts also" ] ++ outputflags ,groupHidden = [] diff --git a/hledger/hledger_balance.m4.md b/hledger/hledger_balance.m4.md index 6ef0dcac4..2777bb765 100644 --- a/hledger/hledger_balance.m4.md +++ b/hledger/hledger_balance.m4.md @@ -42,16 +42,16 @@ txt, csv. : write output to FILE. A file extension matching one of the above formats selects that format. `--pretty-tables` -: Use unicode to display prettier tables. +: use unicode to display prettier tables. `--sort-amount` -: Sort by amount (total row amount, or by average if that is displayed), instead of account name (in flat mode) +: sort by amount instead of account name (in flat mode). With multiple columns, sorts by the row total, or by row average if that is displayed. `--budget` -: Treat [periodic transaction](journal.html#periodic-transactions) as definition of a budget. Compare real balances to budget balances and show percentage of budget consumed. +: show performance compared to budget goals defined by [periodic transactions](journal.html#periodic-transactions) `--show-unbudgeted` -: When --budget is used, display accounts that do not have budget defined +: with --budget, show unbudgeted accounts also The balance command displays accounts and balances. It is hledger's most featureful and versatile command. @@ -244,7 +244,12 @@ Balance changes in 2008: ### Budgets -The `--budget` flag will treat all [periodic transaction](journal.html#periodic-transactions) in your journal as definition of the budget and allow you to compare real balances versus budgeted amounts. +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. For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget: ```journal @@ -273,9 +278,9 @@ For example, you can take average monthly expenses in the common expense categor assets:bank:checking ``` -You can now compare real balances with budget: +You can now see a monthly budget performance report: ```shell -$ hledge balance -M --budget +$ hledger balance -M --budget Balance changes in 2017/11/01-2017/12/31: || 2017/11 2017/12 @@ -307,7 +312,9 @@ Ending balances (cumulative) in 2017/11/01-2017/12/31: || 0 0 ``` -Adding `--show-unbudgeted` will allow you to see all the accounts for which budgets: +Accounts with no budget goals (not mentioned in the periodic transactions) +will be aggregated under ``, unless you add the +`--show-unbudgeted` flag to display them normally: ```shell $ hledger balance --budget --show-unbudgeted Balance changes in 2017/11/01-2017/12/31: