doc: extend with budget addon section

bin/hledger-budget.hs

@@ -5,6 +5,17 @@
   --package text
 -}
 {-# LANGUAGE OverloadedStrings #-}
+{-
+
+hledger-budget REPORT-COMMAND [--no-offset] [--no-buckets] [OPTIONS...]
+
+Perform some subset of reports available in core hledger but process automated
+and periodic transactions. Also simplify tree of accounts to ease view of
+"budget buckets".
+
+This addon tries to simulate behavior of "ledger --budget".
+
+-}
 import Control.Arrow (first)
 import Data.Maybe
 import Data.List

hledger/doc/commands.m4.md

@@ -1014,6 +1014,133 @@ update according to list of input files specified via `--file` options and
 Be careful. Whole transaction being re-formatted in a style of output from
 `hledger print`.
 
+## budget
+This tool helps to get reports useful for planning and tracking the budget.
+
+For people familiar with [`ledger`
+budgeting](http://www.ledger-cli.org/3.0/doc/ledger3.html#Budgeting) may
+consider this tool as an alias to `ledger --budget`.
+
+With this tool you may either use so called periodic transactions that being
+issued with each new period or use a family of approaches with automated
+transactions. You may want to look at [budgeting section of
+plaintextaccounting](http://plaintextaccounting.org/#budgeting).
+
+Periodic transaction that being interpreted by this tool may look like:
+
+```ledger
+~ monthly from 2017/3
+    income:salary  $-4,000.00
+    expenses:taxes  $1,000
+    expenses:housing:rent  $1,200
+    expenses:grocery  $400
+    expenses:leisure  $200
+    expenses:health  $200
+    expenses  $100
+    assets:savings
+```
+
+Header of such entries starts with `'~'` (tilde symbol) following by an
+interval with an effect period when transactions should be injected.
+
+Effect of declaring such periodic transaction is:
+
+- Transactions will be injected at the beginning of each period. I.e. for
+  monthly it will always refer to 1st day of month.
+- Injected transaction will have inverted amounts to offset existing associated
+  expenses. I.e. for this example negative balance indicates how much you have
+  within your budget and positive amounts indicates how far you off from your
+  budget.
+- Set of accounts across of all periodic transactions will form kinda buckets
+  where rest of the accounts will be sorted into. Each account not mentioned in
+  any of periodic transaction will be dropped without changing of balance for
+  parent account. I.e. for this example postings for `expenses:leisure:movie`
+  will contribute to the  balance of `expenses:leisure` only in reports.
+
+Note that beside a periodic transaction all automated transactions will be
+handled in a similar way how they are handled in `rewrite` command.
+
+### Bucketing
+It is very common to have more expense accounts than budget
+"envelopes"/"buckets". For this reason all periodic transactions are treated as
+a source of information about your budget "buckets".
+
+I.e. example from previous section will build a sub-tree of accounts that look like
+
+```
+assets:savings
+expenses
+  taxes
+  housing:rent
+  grocery
+  leisure
+  health
+income:salary
+```
+
+All accounts used in your transactions journal files will be classified
+according to that tree to contribute to an appropriate bucket of budget.
+
+Everything else will be collected under virtual account `<unbucketed>` to give
+you an idea of what parts of your accounts tree is not budgeted. For example
+`liabilities` will contributed to that entry.
+
+### Reports
+You can use `budget` command to produce next reports:
+
+- `balance` - the most important one to track how you follow your budget. If
+  you use month-based budgeting you may want to use `--monthly` and
+  `--row-total` option to see how you are doing through the months. You also
+  may find it useful to add `--tree` option to see aggregated totals per
+  intermediate node of accounts tree.
+- `register` - might be useful if you want to see long history (ex. `--weekly`)
+  that is too wide to fit into your terminal.
+- `print` - this is mostly to check what actually happens. But you may use it
+  if you prefer to generate budget transactions and store it in a separate
+  journal for some less popular budgeting scheme.
+
+### Extra options for reports
+You may tweak behavior of this command with additional options `--no-offset` and `--no-bucketing`.
+
+- Don't use these options if your budgeting schema includes both periodic
+  transactions, and "bucketing". Unless you want to figure out how your
+  budgeting might look like. You may find helpful values of average column from
+  report
+
+```shell
+$ hledger budget -- bal --period 'monthly to last month' --no-offset --average
+```
+
+- Use `--no-offset` and `--no-bucketing` if your schema fully relies on
+  automated transactions and hand-crafted budgeting transactions. In this mode
+  only automated transactions will be processed. I.e. when you journal looks
+  something like
+
+```ledger
+= ^expenses:food
+  budget:gifts  *-1
+  assets:budget  *1
+
+2017/1/1 Budget for Jan
+  assets:bank  $-1000
+  budget:gifts  $200
+  budget:misc
+```
+
+- Use `--no-bucketing` only if you want to produce a valid journal. For example
+  when you want to pass it as an input for other `hledger` command. Most people
+  will find this useless.
+
+### Recommendations
+- Automated transaction should follow same rules that usual transactions follow
+  (i.e. keep balance for real and balanced virtual postings).
+- Don't change the balance of real asset and liability accounts for which you
+  usually put assertions. Keep in mind that `hledger` do not apply modification
+  transactions.
+- In periodic transactions to offset your budget use either top-level account
+  like `Assets` or introduce a "virtual" one like `Assets:Bank:Budget` that
+  will be a child to the one you want to offset.
+
 ## ui
 Curses-style interface, see [hledger-ui](hledger-ui.html).