update embedded manuals

hledger-api/hledger-api.info

@@ -1,4 +1,4 @@
-This is hledger-api.info, produced by makeinfo version 6.0 from stdin.
+This is hledger-api.info, produced by makeinfo version 6.5 from stdin.
 
 
 File: hledger-api.info,  Node: Top,  Next: OPTIONS,  Up: (dir)

hledger-lib/hledger_csv.info

@@ -1,4 +1,4 @@
-This is hledger_csv.info, produced by makeinfo version 6.0 from stdin.
+This is hledger_csv.info, produced by makeinfo version 6.5 from stdin.
 
 
 File: hledger_csv.info,  Node: Top,  Next: CSV RULES,  Up: (dir)

hledger-lib/hledger_journal.5

@@ -274,7 +274,7 @@ Here's one suggestion:
 .PP
 .TS
 tab(@);
-lw(10.5n) lw(59.5n).
+lw(9.9n) lw(60.1n).
 T{
 status
 T}@T{
@@ -1103,6 +1103,68 @@ Glob patterns (\f[C]*\f[]) are not currently supported.
 .PP
 The \f[C]include\f[] directive can only be used in journal files.
 It can include journal, timeclock or timedot files, but not CSV files.
+.SH Periodic transactions
+.PP
+A periodic transaction starts with a tilde `~' in place of a date
+followed by a period expression:
+.IP
+.nf
+\f[C]
+~\ weekly
+\ \ assets:bank:checking\ \ \ $400\ ;\ paycheck
+\ \ income:acme\ inc
+\f[]
+.fi
+.PP
+Periodic transactions are used for budgeting and forecasting only, they
+have no effect without the \f[C]\-\-forecast\f[] or \f[C]\-\-budget\f[]
+option specified.
+For examples and details, see Budgeting and Forecasting.
+.SH Automated posting rules
+.PP
+Autopated posting rule starts with an equal sign `=' in place of a date,
+followed by a query:
+.IP
+.nf
+\f[C]
+=\ expenses:gifts
+\ \ \ \ budget:gifts\ \ *\-1
+\ \ \ \ assets:budget\ \ *1
+\f[]
+.fi
+.PP
+When \f[C]\-\-auto\f[] option is specified on the command line,
+automated posting rule will add its postings to all transactions that
+match the query.
+.PP
+If amount in the automated posting rule includes commodity name, new
+posting will be made in the given commodity, otherwise commodity of the
+matched transaction will be used.
+.PP
+When amount in the automated posting rule begins with the '*', amount
+will be treated as a multiplier that is applied to the amount of the
+first posting in the matched transaction.
+.PP
+In example above, every transaction in \f[C]expenses:gifts\f[] account
+will have two additional postings added to it: amount of the original
+gift will be debited from \f[C]budget:gifts\f[] and credited into
+\f[C]assets:budget\f[]:
+.IP
+.nf
+\f[C]
+;\ Original\ transaction
+2017\-12\-14
+\ \ expenses:gifts\ \ $20
+\ \ assets
+
+;\ With\ automated\ postings\ applied
+2017/12/14
+\ \ \ \ expenses:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ $20
+\ \ \ \ assets
+\ \ \ \ budget:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-20
+\ \ \ \ assets:budget\ \ \ \ \ \ \ \ \ \ \ \ \ \ $20
+\f[]
+.fi
 .SH EDITOR SUPPORT
 .PP
 Add\-on modes exist for various text editors, to make working with
@@ -1116,7 +1178,7 @@ files:
 .PP
 .TS
 tab(@);
-lw(16.5n) lw(51.5n).
+lw(16.5n) lw(53.5n).
 T{
 Emacs
 T}@T{

hledger-lib/hledger_journal.info

@@ -1,4 +1,4 @@
-This is hledger_journal.info, produced by makeinfo version 6.0 from
+This is hledger_journal.info, produced by makeinfo version 6.5 from
 stdin.
 
 
@@ -57,10 +57,12 @@ assisted by the helper modes for emacs or vim.
 * Menu:
 
 * FILE FORMAT::
+* Periodic transactions::
+* Automated posting rules::
 * EDITOR SUPPORT::
 
 
-File: hledger_journal.info,  Node: FILE FORMAT,  Next: EDITOR SUPPORT,  Prev: Top,  Up: Top
+File: hledger_journal.info,  Node: FILE FORMAT,  Next: Periodic transactions,  Prev: Top,  Up: Top
 
 1 FILE FORMAT
 *************
@@ -1054,9 +1056,67 @@ current file.  Glob patterns ('*') are not currently supported.
 include journal, timeclock or timedot files, but not CSV files.
 
 
-File: hledger_journal.info,  Node: EDITOR SUPPORT,  Prev: FILE FORMAT,  Up: Top
+File: hledger_journal.info,  Node: Periodic transactions,  Next: Automated posting rules,  Prev: FILE FORMAT,  Up: Top
 
-2 EDITOR SUPPORT
+2 Periodic transactions
+***********************
+
+A periodic transaction starts with a tilde '~' in place of a date
+followed by a period expression:
+
+~ weekly
+  assets:bank:checking   $400 ; paycheck
+  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.
+
+
+File: hledger_journal.info,  Node: Automated posting rules,  Next: EDITOR SUPPORT,  Prev: Periodic transactions,  Up: Top
+
+3 Automated posting rules
+*************************
+
+Autopated posting rule starts with an equal sign '=' in place of a date,
+followed by a query:
+
+= expenses:gifts
+    budget:gifts  *-1
+    assets:budget  *1
+
+   When '--auto' option is specified on the command line, automated
+posting rule will add its postings to all transactions that match the
+query.
+
+   If amount in the automated posting rule includes commodity name, new
+posting will be made in the given commodity, otherwise commodity of the
+matched transaction will be used.
+
+   When amount in the automated posting rule begins with the '*', amount
+will be treated as a multiplier that is applied to the amount of the
+first posting in the matched transaction.
+
+   In example above, every transaction in 'expenses:gifts' account will
+have two additional postings added to it: amount of the original gift
+will be debited from 'budget:gifts' and credited into 'assets:budget':
+
+; Original transaction
+2017-12-14
+  expenses:gifts  $20
+  assets
+
+; With automated postings applied
+2017/12/14
+    expenses:gifts             $20
+    assets
+    budget:gifts              $-20
+    assets:budget              $20
+
+
+File: hledger_journal.info,  Node: EDITOR SUPPORT,  Prev: Automated posting rules,  Up: Top
+
+4 EDITOR SUPPORT
 ****************
 
 Add-on modes exist for various text editors, to make working with
@@ -1078,85 +1138,89 @@ Code
 
 Tag Table:
 Node: Top76
-Node: FILE FORMAT2370
+Node: FILE FORMAT2424
-Ref: #file-format2494
+Ref: #file-format2555
-Node: Transactions2717
+Node: Transactions2778
-Ref: #transactions2838
+Ref: #transactions2899
-Node: Postings3522
+Node: Postings3583
-Ref: #postings3649
+Ref: #postings3710
-Node: Dates4644
+Node: Dates4705
-Ref: #dates4759
+Ref: #dates4820
-Node: Simple dates4824
+Node: Simple dates4885
-Ref: #simple-dates4950
+Ref: #simple-dates5011
-Node: Secondary dates5316
+Node: Secondary dates5377
-Ref: #secondary-dates5470
+Ref: #secondary-dates5531
-Node: Posting dates7033
+Node: Posting dates7094
-Ref: #posting-dates7162
+Ref: #posting-dates7223
-Node: Status8536
+Node: Status8597
-Ref: #status8656
+Ref: #status8717
-Node: Description10370
+Node: Description10425
-Ref: #description10508
+Ref: #description10563
-Node: Payee and note10827
+Node: Payee and note10882
-Ref: #payee-and-note10941
+Ref: #payee-and-note10996
-Node: Account names11183
+Node: Account names11238
-Ref: #account-names11326
+Ref: #account-names11381
-Node: Amounts11813
+Node: Amounts11868
-Ref: #amounts11949
+Ref: #amounts12004
-Node: Virtual Postings14540
+Node: Virtual Postings14595
-Ref: #virtual-postings14699
+Ref: #virtual-postings14754
-Node: Balance Assertions15919
+Node: Balance Assertions15974
-Ref: #balance-assertions16094
+Ref: #balance-assertions16149
-Node: Assertions and ordering16990
+Node: Assertions and ordering17045
-Ref: #assertions-and-ordering17176
+Ref: #assertions-and-ordering17231
-Node: Assertions and included files17876
+Node: Assertions and included files17931
-Ref: #assertions-and-included-files18117
+Ref: #assertions-and-included-files18172
-Node: Assertions and multiple -f options18450
+Node: Assertions and multiple -f options18505
-Ref: #assertions-and-multiple--f-options18704
+Ref: #assertions-and-multiple--f-options18759
-Node: Assertions and commodities18836
+Node: Assertions and commodities18891
-Ref: #assertions-and-commodities19071
+Ref: #assertions-and-commodities19126
-Node: Assertions and subaccounts19767
+Node: Assertions and subaccounts19822
-Ref: #assertions-and-subaccounts19999
+Ref: #assertions-and-subaccounts20054
-Node: Assertions and virtual postings20520
+Node: Assertions and virtual postings20575
-Ref: #assertions-and-virtual-postings20727
+Ref: #assertions-and-virtual-postings20782
-Node: Balance Assignments20869
+Node: Balance Assignments20924
-Ref: #balance-assignments21038
+Ref: #balance-assignments21093
-Node: Prices22157
+Node: Prices22213
-Ref: #prices22290
+Ref: #prices22346
-Node: Transaction prices22341
+Node: Transaction prices22397
-Ref: #transaction-prices22486
+Ref: #transaction-prices22542
-Node: Market prices24642
+Node: Market prices24698
-Ref: #market-prices24777
+Ref: #market-prices24833
-Node: Comments25737
+Node: Comments25793
-Ref: #comments25859
+Ref: #comments25915
-Node: Tags27101
+Node: Tags27157
-Ref: #tags27219
+Ref: #tags27275
-Node: Directives28621
+Node: Directives28677
-Ref: #directives28734
+Ref: #directives28790
-Node: Account aliases28927
+Node: Account aliases28983
-Ref: #account-aliases29071
+Ref: #account-aliases29127
-Node: Basic aliases29675
+Node: Basic aliases29731
-Ref: #basic-aliases29818
+Ref: #basic-aliases29874
-Node: Regex aliases30508
+Node: Regex aliases30564
-Ref: #regex-aliases30676
+Ref: #regex-aliases30732
-Node: Multiple aliases31394
+Node: Multiple aliases31450
-Ref: #multiple-aliases31566
+Ref: #multiple-aliases31622
-Node: end aliases32064
+Node: end aliases32120
-Ref: #end-aliases32204
+Ref: #end-aliases32260
-Node: account directive32305
+Node: account directive32361
-Ref: #account-directive32485
+Ref: #account-directive32541
-Node: apply account directive32781
+Node: apply account directive32837
-Ref: #apply-account-directive32977
+Ref: #apply-account-directive33033
-Node: Multi-line comments33636
+Node: Multi-line comments33692
-Ref: #multi-line-comments33826
+Ref: #multi-line-comments33882
-Node: commodity directive33954
+Node: commodity directive34010
-Ref: #commodity-directive34138
+Ref: #commodity-directive34194
-Node: Default commodity35010
+Node: Default commodity35066
-Ref: #default-commodity35183
+Ref: #default-commodity35239
-Node: Default year35720
+Node: Default year35776
-Ref: #default-year35885
+Ref: #default-year35941
-Node: Including other files36308
+Node: Including other files36364
-Ref: #including-other-files36465
+Ref: #including-other-files36521
-Node: EDITOR SUPPORT36862
+Node: Periodic transactions36918
-Ref: #editor-support36980
+Ref: #periodic-transactions37089
+Node: Automated posting rules37464
+Ref: #automated-posting-rules37642
+Node: EDITOR SUPPORT38751
+Ref: #editor-support38881
 
 End Tag Table

hledger-lib/hledger_journal.txt

@@ -211,10 +211,10 @@ FILE FORMAT
        status       meaning
        --------------------------------------------------------------------------
        uncleared    recorded but not yet reconciled; needs review
-       pending      tentatively reconciled (if needed, eg during a  big  recon-
+       pending      tentatively reconciled (if needed, eg during a big reconcil-
-                    ciliation)
+                    iation)
-       cleared      complete,  reconciled  as  far  as possible, and considered
+       cleared      complete, reconciled as far as possible, and considered cor-
-                    correct
+                    rect
 
        With this scheme, you would use -PC to see the current balance at  your
        bank,  -U  to  see  things which will probably hit your bank soon (like
@@ -811,6 +811,53 @@ FILE FORMAT
        The include directive can only  be  used  in  journal  files.   It  can
        include journal, timeclock or timedot files, but not CSV files.
 
+Periodic transactions
+       A  periodic transaction starts with a tilde `~' in place of a date fol-
+       lowed by a period expression:
+
+              ~ weekly
+                assets:bank:checking   $400 ; paycheck
+                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.
+
+Automated posting rules
+       Autopated posting rule starts with an equal sign  `='  in  place  of  a
+       date, followed by a query:
+
+              = expenses:gifts
+                  budget:gifts  *-1
+                  assets:budget  *1
+
+       When  --auto option is specified on the command line, automated posting
+       rule will add its postings to all transactions that match the query.
+
+       If amount in the automated posting rule includes  commodity  name,  new
+       posting will be made in the given commodity, otherwise commodity of the
+       matched transaction will be used.
+
+       When amount in the automated posting rule begins with the  '*',  amount
+       will  be  treated  as a multiplier that is applied to the amount of the
+       first posting in the matched transaction.
+
+       In example above, every transaction in expenses:gifts account will have
+       two  additional  postings added to it: amount of the original gift will
+       be debited from budget:gifts and credited into assets:budget:
+
+              ; Original transaction
+              2017-12-14
+                expenses:gifts  $20
+                assets
+
+              ; With automated postings applied
+              2017/12/14
+                  expenses:gifts             $20
+                  assets
+                  budget:gifts              $-20
+                  assets:budget              $20
+
 EDITOR SUPPORT
        Add-on modes exist for various text editors, to make working with jour-
        nal  files  easier.   They add colour, navigation aids and helpful com-
@@ -822,14 +869,14 @@ EDITOR SUPPORT
 
 
        Emacs              http://www.ledger-cli.org/3.0/doc/ledger-mode.html
-       Vim                https://github.com/ledger/ledger/wiki/Get-
+       Vim                https://github.com/ledger/ledger/wiki/Getting-started
-                          ting-started
        Sublime Text       https://github.com/ledger/ledger/wiki/Using-Sub-
                           lime-Text
        Textmate           https://github.com/ledger/ledger/wiki/Using-Text-
                           Mate-2
        Text Wrangler      https://github.com/ledger/ledger/wiki/Edit-
                           ing-Ledger-files-with-TextWrangler
+
        Visual    Studio   https://marketplace.visualstudio.com/items?item-
        Code               Name=mark-hansen.hledger-vscode
 

hledger-lib/hledger_timeclock.info

@@ -1,4 +1,4 @@
-This is hledger_timeclock.info, produced by makeinfo version 6.0 from
+This is hledger_timeclock.info, produced by makeinfo version 6.5 from
 stdin.
 
 

hledger-lib/hledger_timedot.info

@@ -1,4 +1,4 @@
-This is hledger_timedot.info, produced by makeinfo version 6.0 from
+This is hledger_timedot.info, produced by makeinfo version 6.5 from
 stdin.
 
 

hledger-ui/hledger-ui.1

@@ -136,8 +136,8 @@ multiperiod/multicolumn report by year
 .RE
 .TP
 .B \f[C]\-p\ \-\-period=PERIODEXP\f[]
-set start date, end date, and/or reporting interval all at once
+set start date, end date, and/or reporting interval all at once using
-(overrides the flags above)
+period expressions syntax (overrides the flags above)
 .RS
 .RE
 .TP
@@ -187,6 +187,21 @@ convert amounts to their market value on the report end date (using the
 most recent applicable market price, if any)
 .RS
 .RE
+.TP
+.B \f[C]\-\-forecast\f[]
+generate forecast transactions from [periodic
+transaction]((journal.html#periodic\-transactions) rules.
+Each periodic transaction rule will generate forecast transactions,
+beginning the day after the last recorded journal transaction, and
+ending 6 months from today, or at the specified report end date.
+.RS
+.RE
+.TP
+.B \f[C]\-\-auto\f[]
+apply automated posting rules to modify transactions where applicable
+(can combine with \[en]forecast).
+.RS
+.RE
 .PP
 When a reporting option appears more than once in the command line, the
 last one takes precedence.

hledger-ui/hledger-ui.info

@@ -1,4 +1,4 @@
-This is hledger-ui.info, produced by makeinfo version 6.0 from stdin.
+This is hledger-ui.info, produced by makeinfo version 6.5 from stdin.
 
 
 File: hledger-ui.info,  Node: Top,  Next: OPTIONS,  Up: (dir)
@@ -100,7 +100,7 @@ the data.
 '-p --period=PERIODEXP'
 
      set start date, end date, and/or reporting interval all at once
-     (overrides the flags above)
+     using period expressions syntax (overrides the flags above)
 '--date2'
 
      match the secondary date instead (see command help for other
@@ -131,6 +131,17 @@ the data.
 
      convert amounts to their market value on the report end date (using
      the most recent applicable market price, if any)
+'--forecast'
+
+     generate forecast transactions from [periodic
+     transaction]((journal.html#periodic-transactions) rules.  Each
+     periodic transaction rule will generate forecast transactions,
+     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 to modify transactions where
+     applicable (can combine with -forecast).
 
    When a reporting option appears more than once in the command line,
 the last one takes precedence.
@@ -371,17 +382,17 @@ Tag Table:
 Node: Top71
 Node: OPTIONS821
 Ref: #options918
-Node: KEYS3855
+Node: KEYS4350
-Ref: #keys3950
+Ref: #keys4445
-Node: SCREENS6909
+Node: SCREENS7404
-Ref: #screens6994
+Ref: #screens7489
-Node: Accounts screen7084
+Node: Accounts screen7579
-Ref: #accounts-screen7212
+Ref: #accounts-screen7707
-Node: Register screen9442
+Node: Register screen9937
-Ref: #register-screen9597
+Ref: #register-screen10092
-Node: Transaction screen11671
+Node: Transaction screen12166
-Ref: #transaction-screen11829
+Ref: #transaction-screen12324
-Node: Error screen12699
+Node: Error screen13194
-Ref: #error-screen12821
+Ref: #error-screen13316
 
 End Tag Table

hledger-ui/hledger-ui.txt

@@ -96,7 +96,7 @@ OPTIONS
 
        -p --period=PERIODEXP
               set  start date, end date, and/or reporting interval all at once
-              (overrides the flags above)
+              using period expressions syntax (overrides the flags above)
 
        --date2
               match the secondary date instead (see  command  help  for  other
@@ -128,6 +128,16 @@ OPTIONS
               convert amounts to their market value on  the  report  end  date
               (using the most recent applicable market price, if any)
 
+       --forecast
+              generate   forecast   transactions   from   [periodic   transac-
+              tion]((journal.html#periodic-transactions) rules.  Each periodic
+              transaction  rule will generate forecast transactions, 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  to  modify  transactions where
+              applicable (can combine with -forecast).
+
        When a reporting option appears more than once in the command line, the
        last one takes precedence.
 

hledger-web/hledger-web.1

@@ -191,8 +191,8 @@ multiperiod/multicolumn report by year
 .RE
 .TP
 .B \f[C]\-p\ \-\-period=PERIODEXP\f[]
-set start date, end date, and/or reporting interval all at once
+set start date, end date, and/or reporting interval all at once using
-(overrides the flags above)
+period expressions syntax (overrides the flags above)
 .RS
 .RE
 .TP
@@ -242,6 +242,21 @@ convert amounts to their market value on the report end date (using the
 most recent applicable market price, if any)
 .RS
 .RE
+.TP
+.B \f[C]\-\-forecast\f[]
+generate forecast transactions from [periodic
+transaction]((journal.html#periodic\-transactions) rules.
+Each periodic transaction rule will generate forecast transactions,
+beginning the day after the last recorded journal transaction, and
+ending 6 months from today, or at the specified report end date.
+.RS
+.RE
+.TP
+.B \f[C]\-\-auto\f[]
+apply automated posting rules to modify transactions where applicable
+(can combine with \[en]forecast).
+.RS
+.RE
 .PP
 When a reporting option appears more than once in the command line, the
 last one takes precedence.

hledger-web/hledger-web.info

@@ -1,4 +1,4 @@
-This is hledger-web.info, produced by makeinfo version 6.0 from stdin.
+This is hledger-web.info, produced by makeinfo version 6.5 from stdin.
 
 
 File: hledger-web.info,  Node: Top,  Next: OPTIONS,  Up: (dir)
@@ -145,7 +145,7 @@ options as shown above.
 '-p --period=PERIODEXP'
 
      set start date, end date, and/or reporting interval all at once
-     (overrides the flags above)
+     using period expressions syntax (overrides the flags above)
 '--date2'
 
      match the secondary date instead (see command help for other
@@ -176,6 +176,17 @@ options as shown above.
 
      convert amounts to their market value on the report end date (using
      the most recent applicable market price, if any)
+'--forecast'
+
+     generate forecast transactions from [periodic
+     transaction]((journal.html#periodic-transactions) rules.  Each
+     periodic transaction rule will generate forecast transactions,
+     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 to modify transactions where
+     applicable (can combine with -forecast).
 
    When a reporting option appears more than once in the command line,
 the last one takes precedence.

hledger-web/hledger-web.txt

@@ -141,7 +141,7 @@ OPTIONS
 
        -p --period=PERIODEXP
               set start date, end date, and/or reporting interval all at  once
-              (overrides the flags above)
+              using period expressions syntax (overrides the flags above)
 
        --date2
               match  the  secondary  date  instead (see command help for other
@@ -173,6 +173,16 @@ OPTIONS
               convert  amounts  to  their  market value on the report end date
               (using the most recent applicable market price, if any)
 
+       --forecast
+              generate   forecast   transactions   from   [periodic   transac-
+              tion]((journal.html#periodic-transactions) rules.  Each periodic
+              transaction rule will generate forecast transactions,  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  to  modify  transactions  where
+              applicable (can combine with -forecast).
+
        When a reporting option appears more than once in the command line, the
        last one takes precedence.
 

hledger/hledger.1

@@ -246,8 +246,8 @@ multiperiod/multicolumn report by year
 .RE
 .TP
 .B \f[C]\-p\ \-\-period=PERIODEXP\f[]
-set start date, end date, and/or reporting interval all at once
+set start date, end date, and/or reporting interval all at once using
-(overrides the flags above)
+period expressions syntax (overrides the flags above)
 .RS
 .RE
 .TP
@@ -297,6 +297,21 @@ convert amounts to their market value on the report end date (using the
 most recent applicable market price, if any)
 .RS
 .RE
+.TP
+.B \f[C]\-\-forecast\f[]
+generate forecast transactions from [periodic
+transaction]((journal.html#periodic\-transactions) rules.
+Each periodic transaction rule will generate forecast transactions,
+beginning the day after the last recorded journal transaction, and
+ending 6 months from today, or at the specified report end date.
+.RS
+.RE
+.TP
+.B \f[C]\-\-auto\f[]
+apply automated posting rules to modify transactions where applicable
+(can combine with \[en]forecast).
+.RS
+.RE
 .PP
 When a reporting option appears more than once in the command line, the
 last one takes precedence.
@@ -407,7 +422,7 @@ turn:
 .PP
 .TS
 tab(@);
-lw(10.7n) lw(33.2n) lw(26.1n).
+lw(10.3n) lw(33.5n) lw(26.2n).
 T{
 Reader:
 T}@T{
@@ -1433,6 +1448,19 @@ Sort by amount (total row amount, or by average if that is displayed),
 instead of account name (in flat mode)
 .RS
 .RE
+.TP
+.B \f[C]\-\-budget\f[]
+Treat periodic transaction as definition of a budget.
+Compare real balances to budget balances and show percentage of budget
+consumed.
+.RS
+.RE
+.TP
+.B \f[C]\-\-show\-unbudgeted\f[]
+When \[en]budget is used, display accounts that do not have budget
+defined
+.RS
+.RE
 .PP
 The balance command displays accounts and balances.
 It is hledger's most featureful and versatile command.
@@ -1641,6 +1669,108 @@ Balance\ changes\ in\ 2008:
 #\ Average\ is\ rounded\ to\ the\ dollar\ here\ since\ all\ journal\ amounts\ are
 \f[]
 .fi
+.SS Budgets
+.PP
+The \f[C]\-\-budget\f[] 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.
+.PP
+For example, you can take average monthly expenses in the common expense
+categories to construct a minimal monthly budget:
+.IP
+.nf
+\f[C]
+;;\ Budget
+~\ monthly
+\ \ income\ \ $2000
+\ \ expenses:food\ \ \ \ $400
+\ \ expenses:bus\ \ \ \ \ $50
+\ \ expenses:movies\ \ $30
+\ \ assets:bank:checking
+
+;;\ Two\ months\ worth\ of\ expenses
+2017\-11\-01
+\ \ income\ \ $1950
+\ \ expenses:food\ \ \ \ $396
+\ \ expenses:bus\ \ \ \ \ $49
+\ \ expenses:movies\ \ $30
+\ \ expenses:supplies\ \ $20
+\ \ assets:bank:checking
+
+2017\-12\-01
+\ \ income\ \ $2100
+\ \ expenses:food\ \ \ \ $412
+\ \ expenses:bus\ \ \ \ \ $53
+\ \ expenses:gifts\ \ \ $100
+\ \ assets:bank:checking
+\f[]
+.fi
+.PP
+You can now compare real balances with budget:
+.IP
+.nf
+\f[C]
+$\ hledge\ balance\ \-M\ \-\-budget
+Balance\ changes\ in\ 2017/11/01\-2017/12/31:
+
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\ 
+=======================++=================================================
+\ <unbudgeted>:expenses\ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\ 
+\ assets:bank:checking\ \ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\ 
+\ expenses:bus\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ \ \ $53\ [106%\ of\ $50]\ 
+\ expenses:food\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $412\ [103%\ of\ $400]\ 
+\ expenses:movies\ \ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ \ \ \ 0\ [0%\ of\ $30]\ 
+\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $2100\ [105%\ of\ $2000]\ 
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ 
+\f[]
+.fi
+.PP
+You can roll over unspent budgets to next period with
+\f[C]\-\-cumulative\f[]:
+.IP
+.nf
+\f[C]
+$\ hledger\ balance\ \-M\ \-\-budget\ \-\-cumulative
+Ending\ balances\ (cumulative)\ in\ 2017/11/01\-2017/12/31:
+
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12/31\ 
+=======================++=================================================
+\ <unbudgeted>:expenses\ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $120\ 
+\ assets:bank:checking\ \ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-5110\ [103%\ of\ $\-4960]\ 
+\ expenses:bus\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ $102\ [102%\ of\ $100]\ 
+\ expenses:food\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $808\ [101%\ of\ $800]\ 
+\ expenses:movies\ \ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ $30\ [50%\ of\ $60]\ 
+\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $4050\ [101%\ of\ $4000]\ 
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0
+\f[]
+.fi
+.PP
+Adding \f[C]\-\-show\-unbudgeted\f[] will allow you to see all the
+accounts for which budgets:
+.IP
+.nf
+\f[C]
+$\ hledger\ balance\ \-\-budget\ \-\-show\-unbudgeted
+Balance\ changes\ in\ 2017/11/01\-2017/12/31:
+
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\ 
+======================++=================================================
+\ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\ 
+\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ \ \ $53\ [106%\ of\ $50]\ 
+\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $412\ [103%\ of\ $400]\ 
+\ expenses:gifts\ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\ 
+\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ \ \ \ 0\ [0%\ of\ $30]\ 
+\ expenses:supplies\ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ 
+\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $2100\ [105%\ of\ $2000]\ 
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ 
+\f[]
+.fi
+.PP
+For more examples and details, see Budgeting and Forecasting.
 .SS Custom balance output
 .PP
 In simple (non\-multi\-column) balance reports, you can customise the

hledger/hledger.info

@@ -1,4 +1,4 @@
-This is hledger.info, produced by makeinfo version 6.0 from stdin.
+This is hledger.info, produced by makeinfo version 6.5 from stdin.
 
 
 File: hledger.info,  Node: Top,  Next: EXAMPLES,  Up: (dir)
@@ -201,7 +201,7 @@ by most hledger commands, run 'hledger -h'.
 '-p --period=PERIODEXP'
 
      set start date, end date, and/or reporting interval all at once
-     (overrides the flags above)
+     using period expressions syntax (overrides the flags above)
 '--date2'
 
      match the secondary date instead (see command help for other
@@ -232,6 +232,17 @@ by most hledger commands, run 'hledger -h'.
 
      convert amounts to their market value on the report end date (using
      the most recent applicable market price, if any)
+'--forecast'
+
+     generate forecast transactions from [periodic
+     transaction]((journal.html#periodic-transactions) rules.  Each
+     periodic transaction rule will generate forecast transactions,
+     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 to modify transactions where
+     applicable (can combine with -forecast).
 
    When a reporting option appears more than once in the command line,
 the last one takes precedence.
@@ -340,7 +351,7 @@ format automatically based on the file extension, or if that is not
 recognised, by trying each built-in "reader" in turn:
 
 Reader:     Reads:                              Used for file extensions:
----------------------------------------------------------------------------
+----------------------------------------------------------------------------
 'journal'   hledger's journal format, also      '.journal' '.j'
             some Ledger journals                '.hledger' '.ledger'
 'timeclock' timeclock files (precise time       '.timeclock'
@@ -1082,6 +1093,14 @@ Show accounts and their balances.  Aliases: b, bal.
 
      Sort by amount (total row amount, or by average if that is
      displayed), instead of account name (in flat mode)
+'--budget'
+
+     Treat periodic transaction as definition of a budget.  Compare real
+     balances to budget balances and show percentage of budget consumed.
+'--show-unbudgeted'
+
+     When -budget is used, display accounts that do not have budget
+     defined
 
    The balance command displays accounts and balances.  It is hledger's
 most featureful and versatile command.
@@ -1131,6 +1150,7 @@ $ hledger balance -p 2008/6 expenses --no-total
 * Flat mode::
 * Depth limited balance reports::
 * Multicolumn balance reports::
+* Budgets::
 * Custom balance output::
 * Colour support::
 * Output destination::
@@ -1170,7 +1190,7 @@ $ hledger balance -N --depth 1
                   $1  liabilities
 
 
-File: hledger.info,  Node: Multicolumn balance reports,  Next: Custom balance output,  Prev: Depth limited balance reports,  Up: balance
+File: hledger.info,  Node: Multicolumn balance reports,  Next: Budgets,  Prev: Depth limited balance reports,  Up: balance
 
 4.4.3 Multicolumn balance reports
 ---------------------------------
@@ -1270,9 +1290,99 @@ Balance changes in 2008:
 # Average is rounded to the dollar here since all journal amounts are
 
 
-File: hledger.info,  Node: Custom balance output,  Next: Colour support,  Prev: Multicolumn balance reports,  Up: balance
+File: hledger.info,  Node: Budgets,  Next: Custom balance output,  Prev: Multicolumn balance reports,  Up: balance
 
-4.4.4 Custom balance output
+4.4.4 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.
+
+   For example, you can take average monthly expenses in the common
+expense categories to construct a minimal monthly budget:
+
+;; Budget
+~ monthly
+  income  $2000
+  expenses:food    $400
+  expenses:bus     $50
+  expenses:movies  $30
+  assets:bank:checking
+
+;; Two months worth of expenses
+2017-11-01
+  income  $1950
+  expenses:food    $396
+  expenses:bus     $49
+  expenses:movies  $30
+  expenses:supplies  $20
+  assets:bank:checking
+
+2017-12-01
+  income  $2100
+  expenses:food    $412
+  expenses:bus     $53
+  expenses:gifts   $100
+  assets:bank:checking
+
+   You can now compare real balances with budget:
+
+$ hledge balance -M --budget
+Balance changes in 2017/11/01-2017/12/31:
+
+                       ||                2017/11                  2017/12 
+=======================++=================================================
+ <unbudgeted>:expenses ||                    $20                     $100 
+ assets:bank:checking  || $-2445 [99% of $-2480]  $-2665 [107% of $-2480] 
+ expenses:bus          ||       $49 [98% of $50]        $53 [106% of $50] 
+ expenses:food         ||     $396 [99% of $400]      $412 [103% of $400] 
+ expenses:movies       ||      $30 [100% of $30]            0 [0% of $30] 
+ income                ||   $1950 [98% of $2000]    $2100 [105% of $2000] 
+-----------------------++-------------------------------------------------
+                       ||                      0                        0 
+
+   You can roll over unspent budgets to next period with '--cumulative':
+
+$ hledger balance -M --budget --cumulative
+Ending balances (cumulative) in 2017/11/01-2017/12/31:
+
+                       ||             2017/11/30               2017/12/31 
+=======================++=================================================
+ <unbudgeted>:expenses ||                    $20                     $120 
+ assets:bank:checking  || $-2445 [99% of $-2480]  $-5110 [103% of $-4960] 
+ expenses:bus          ||       $49 [98% of $50]      $102 [102% of $100] 
+ expenses:food         ||     $396 [99% of $400]      $808 [101% of $800] 
+ expenses:movies       ||      $30 [100% of $30]         $30 [50% of $60] 
+ income                ||   $1950 [98% of $2000]    $4050 [101% of $4000] 
+-----------------------++-------------------------------------------------
+                       ||                      0                        0
+
+   Adding '--show-unbudgeted' will allow you to see all the accounts for
+which budgets:
+
+$ hledger balance --budget --show-unbudgeted
+Balance changes in 2017/11/01-2017/12/31:
+
+                      ||                2017/11                  2017/12 
+======================++=================================================
+ assets:bank:checking || $-2445 [99% of $-2480]  $-2665 [107% of $-2480] 
+ expenses:bus         ||       $49 [98% of $50]        $53 [106% of $50] 
+ expenses:food        ||     $396 [99% of $400]      $412 [103% of $400] 
+ expenses:gifts       ||                      0                     $100 
+ expenses:movies      ||      $30 [100% of $30]            0 [0% of $30] 
+ expenses:supplies    ||                    $20                        0 
+ income               ||   $1950 [98% of $2000]    $2100 [105% of $2000] 
+----------------------++-------------------------------------------------
+                      ||                      0                        0 
+
+   For more examples and details, see Budgeting and Forecasting.
+
+
+File: hledger.info,  Node: Custom balance output,  Next: Colour support,  Prev: Budgets,  Up: balance
+
+4.4.5 Custom balance output
 ---------------------------
 
 In simple (non-multi-column) balance reports, you can customise the
@@ -1332,7 +1442,7 @@ may be needed to get pleasing results.
 
 File: hledger.info,  Node: Colour support,  Next: Output destination,  Prev: Custom balance output,  Up: balance
 
-4.4.5 Colour support
+4.4.6 Colour support
 --------------------
 
 The balance command shows negative amounts in red, if:
@@ -1343,7 +1453,7 @@ The balance command shows negative amounts in red, if:
 
 File: hledger.info,  Node: Output destination,  Next: CSV output,  Prev: Colour support,  Up: balance
 
-4.4.6 Output destination
+4.4.7 Output destination
 ------------------------
 
 The balance, print, register and stats commands can write their output
@@ -1356,7 +1466,7 @@ $ hledger balance -o FILE  # write to FILE
 
 File: hledger.info,  Node: CSV output,  Prev: Output destination,  Up: balance
 
-4.4.7 CSV output
+4.4.8 CSV output
 ----------------
 
 The balance, print and register commands can write their output as CSV.
@@ -2264,129 +2374,131 @@ Node: OPTIONS3628
 Ref: #options3730
 Node: General options4046
 Ref: #general-options4171
-Node: Command options6490
+Node: Command options6985
-Ref: #command-options6641
+Ref: #command-options7136
-Node: Command arguments7039
+Node: Command arguments7534
-Ref: #command-arguments7193
+Ref: #command-arguments7688
-Node: Argument files7314
+Node: Argument files7809
-Ref: #argument-files7465
+Ref: #argument-files7960
-Node: Special characters7731
+Node: Special characters8226
-Ref: #special-characters7884
+Ref: #special-characters8379
-Node: Input files9303
+Node: Input files9798
-Ref: #input-files9439
+Ref: #input-files9934
-Node: Smart dates11402
+Node: Smart dates11904
-Ref: #smart-dates11543
+Ref: #smart-dates12045
-Node: Report start & end date12522
+Node: Report start & end date13024
-Ref: #report-start-end-date12692
+Ref: #report-start-end-date13194
-Node: Report intervals13757
+Node: Report intervals14259
-Ref: #report-intervals13920
+Ref: #report-intervals14422
-Node: Period expressions14321
+Node: Period expressions14823
-Ref: #period-expressions14478
+Ref: #period-expressions14980
-Node: For example16523
+Node: For example17025
-Ref: #for-example16666
+Ref: #for-example17168
-Node: Depth limiting18590
+Node: Depth limiting19092
-Ref: #depth-limiting18727
+Ref: #depth-limiting19229
-Node: Pivoting19069
+Node: Pivoting19571
-Ref: #pivoting19187
+Ref: #pivoting19689
-Node: Cost20863
+Node: Cost21365
-Ref: #cost20971
+Ref: #cost21473
-Node: Market value21089
+Node: Market value21591
-Ref: #market-value21224
+Ref: #market-value21726
-Node: Regular expressions22524
+Node: Regular expressions23026
-Ref: #regular-expressions22660
+Ref: #regular-expressions23162
-Node: QUERIES24021
+Node: QUERIES24523
-Ref: #queries24123
+Ref: #queries24625
-Node: COMMANDS28090
+Node: COMMANDS28592
-Ref: #commands28202
+Ref: #commands28704
-Node: accounts29185
+Node: accounts29687
-Ref: #accounts29283
+Ref: #accounts29785
-Node: activity30276
+Node: activity30778
-Ref: #activity30386
+Ref: #activity30888
-Node: add30745
+Node: add31248
-Ref: #add30844
+Ref: #add31347
-Node: balance33502
+Node: balance34008
-Ref: #balance33613
+Ref: #balance34119
-Node: Flat mode36770
+Node: Flat mode37548
-Ref: #flat-mode36895
+Ref: #flat-mode37673
-Node: Depth limited balance reports37315
+Node: Depth limited balance reports38093
-Ref: #depth-limited-balance-reports37516
+Ref: #depth-limited-balance-reports38294
-Node: Multicolumn balance reports37936
+Node: Multicolumn balance reports38714
-Ref: #multicolumn-balance-reports38145
+Ref: #multicolumn-balance-reports38909
-Node: Custom balance output42793
+Node: Budgets43598
-Ref: #custom-balance-output42975
+Ref: #budgets43745
-Node: Colour support45068
+Node: Custom balance output47361
-Ref: #colour-support45227
+Ref: #custom-balance-output47523
-Node: Output destination45400
+Node: Colour support49616
-Ref: #output-destination45556
+Ref: #colour-support49775
-Node: CSV output45826
+Node: Output destination49948
-Ref: #csv-output45943
+Ref: #output-destination50104
-Node: balancesheet46340
+Node: CSV output50374
-Ref: #balancesheet46476
+Ref: #csv-output50491
-Node: balancesheetequity48444
+Node: balancesheet50888
-Ref: #balancesheetequity48593
+Ref: #balancesheet51024
-Node: cashflow49382
+Node: balancesheetequity52992
-Ref: #cashflow49510
+Ref: #balancesheetequity53141
-Node: check-dates51422
+Node: cashflow53930
-Ref: #check-dates51549
+Ref: #cashflow54058
-Node: check-dupes51666
+Node: check-dates55970
-Ref: #check-dupes51791
+Ref: #check-dates56097
-Node: equity51928
+Node: check-dupes56214
-Ref: #equity52038
+Ref: #check-dupes56339
-Node: help52201
+Node: equity56476
-Ref: #help52302
+Ref: #equity56586
-Node: import53376
+Node: help56749
-Ref: #import53490
+Ref: #help56850
-Node: incomestatement54220
+Node: import57924
-Ref: #incomestatement54354
+Ref: #import58038
-Node: prices56307
+Node: incomestatement58768
-Ref: #prices56422
+Ref: #incomestatement58902
-Node: print56465
+Node: prices60855
-Ref: #print56575
+Ref: #prices60970
-Node: print-unique61421
+Node: print61013
-Ref: #print-unique61547
+Ref: #print61123
-Node: register61615
+Node: print-unique65969
-Ref: #register61742
+Ref: #print-unique66095
-Node: Custom register output66243
+Node: register66163
-Ref: #custom-register-output66372
+Ref: #register66290
-Node: register-match67669
+Node: Custom register output70791
-Ref: #register-match67803
+Ref: #custom-register-output70920
-Node: rewrite67986
+Node: register-match72217
-Ref: #rewrite68103
+Ref: #register-match72351
-Node: stats68172
+Node: rewrite72534
-Ref: #stats68275
+Ref: #rewrite72651
-Node: tags69156
+Node: stats72720
-Ref: #tags69254
+Ref: #stats72823
-Node: test69490
+Node: tags73705
-Ref: #test69574
+Ref: #tags73803
-Node: ADD-ON COMMANDS69942
+Node: test74039
-Ref: #add-on-commands70052
+Ref: #test74123
-Node: Official add-ons71339
+Node: ADD-ON COMMANDS74491
-Ref: #official-add-ons71479
+Ref: #add-on-commands74601
-Node: api71566
+Node: Official add-ons75888
-Ref: #api71655
+Ref: #official-add-ons76028
-Node: ui71707
+Node: api76115
-Ref: #ui71806
+Ref: #api76204
-Node: web71864
+Node: ui76256
-Ref: #web71953
+Ref: #ui76355
-Node: Third party add-ons71999
+Node: web76413
-Ref: #third-party-add-ons72174
+Ref: #web76502
-Node: diff72309
+Node: Third party add-ons76548
-Ref: #diff72406
+Ref: #third-party-add-ons76723
-Node: iadd72505
+Node: diff76858
-Ref: #iadd72619
+Ref: #diff76955
-Node: interest72702
+Node: iadd77054
-Ref: #interest72823
+Ref: #iadd77168
-Node: irr72918
+Node: interest77251
-Ref: #irr73016
+Ref: #interest77372
-Node: Experimental add-ons73094
+Node: irr77467
-Ref: #experimental-add-ons73246
+Ref: #irr77565
-Node: autosync73537
+Node: Experimental add-ons77643
-Ref: #autosync73649
+Ref: #experimental-add-ons77795
-Node: budget73888
+Node: autosync78086
-Ref: #budget74010
+Ref: #autosync78198
-Node: chart74076
+Node: budget78437
-Ref: #chart74193
+Ref: #budget78559
-Node: check74264
+Node: chart78625
-Ref: #check74366
+Ref: #chart78742
+Node: check78813
+Ref: #check78915
 
 End Tag Table

hledger/hledger.txt

@@ -170,7 +170,7 @@ OPTIONS
 
        -p --period=PERIODEXP
               set  start date, end date, and/or reporting interval all at once
-              (overrides the flags above)
+              using period expressions syntax (overrides the flags above)
 
        --date2
               match the secondary date instead (see  command  help  for  other
@@ -202,6 +202,16 @@ OPTIONS
               convert amounts to their market value on  the  report  end  date
               (using the most recent applicable market price, if any)
 
+       --forecast
+              generate   forecast   transactions   from   [periodic   transac-
+              tion]((journal.html#periodic-transactions) rules.  Each periodic
+              transaction  rule will generate forecast transactions, 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  to  modify  transactions where
+              applicable (can combine with -forecast).
+
        When a reporting option appears more than once in the command line, the
        last one takes precedence.
 
@@ -329,8 +339,6 @@ OPTIONS
        2009-1-1, 2009.1.1           arators allowed
        2009/1, 2009                 same  as above - a missing
                                     day or month defaults to 1
-
-
        1/1,     january,     jan,   relative  dates,   meaning
        this year                    january  1  of the current
                                     year
@@ -978,6 +986,15 @@ COMMANDS
               Sort by amount (total row amount, or by average if that is  dis-
               played), instead of account name (in flat mode)
 
+       --budget
+              Treat  periodic  transaction as definition of a budget.  Compare
+              real balances to budget balances and show percentage  of  budget
+              consumed.
+
+       --show-unbudgeted
+              When  -budget  is used, display accounts that do not have budget
+              defined
+
        The balance command displays accounts and balances.   It  is  hledger's
        most featureful and versatile command.
 
@@ -1139,6 +1156,90 @@ COMMANDS
 
               # Average is rounded to the dollar here since all journal amounts are
 
+   Budgets
+       The   --budget   flag  will  treat  all  [periodic  transaction]((jour-
+       nal.html#periodic-transactions) in your journal as  definition  of  the
+       budget  and allow you to compare real balances versus budgeted amounts.
+
+       For example, you can  take  average  monthly  expenses  in  the  common
+       expense categories to construct a minimal monthly budget:
+
+              ;; Budget
+              ~ monthly
+                income  $2000
+                expenses:food    $400
+                expenses:bus     $50
+                expenses:movies  $30
+                assets:bank:checking
+
+              ;; Two months worth of expenses
+              2017-11-01
+                income  $1950
+                expenses:food    $396
+                expenses:bus     $49
+                expenses:movies  $30
+                expenses:supplies  $20
+                assets:bank:checking
+
+              2017-12-01
+                income  $2100
+                expenses:food    $412
+                expenses:bus     $53
+                expenses:gifts   $100
+                assets:bank:checking
+
+       You can now compare real balances with budget:
+
+              $ hledge balance -M --budget
+              Balance changes in 2017/11/01-2017/12/31:
+
+                                     ||                2017/11                  2017/12
+              =======================++=================================================
+               <unbudgeted>:expenses ||                    $20                     $100
+               assets:bank:checking  || $-2445 [99% of $-2480]  $-2665 [107% of $-2480]
+               expenses:bus          ||       $49 [98% of $50]        $53 [106% of $50]
+               expenses:food         ||     $396 [99% of $400]      $412 [103% of $400]
+               expenses:movies       ||      $30 [100% of $30]            0 [0% of $30]
+               income                ||   $1950 [98% of $2000]    $2100 [105% of $2000]
+              -----------------------++-------------------------------------------------
+                                     ||                      0                        0
+
+       You can roll over unspent budgets to next period with --cumulative:
+
+              $ hledger balance -M --budget --cumulative
+              Ending balances (cumulative) in 2017/11/01-2017/12/31:
+
+                                     ||             2017/11/30               2017/12/31
+              =======================++=================================================
+               <unbudgeted>:expenses ||                    $20                     $120
+               assets:bank:checking  || $-2445 [99% of $-2480]  $-5110 [103% of $-4960]
+               expenses:bus          ||       $49 [98% of $50]      $102 [102% of $100]
+               expenses:food         ||     $396 [99% of $400]      $808 [101% of $800]
+               expenses:movies       ||      $30 [100% of $30]         $30 [50% of $60]
+               income                ||   $1950 [98% of $2000]    $4050 [101% of $4000]
+              -----------------------++-------------------------------------------------
+                                     ||                      0                        0
+
+       Adding  --show-unbudgeted  will  allow  you to see all the accounts for
+       which budgets:
+
+              $ hledger balance --budget --show-unbudgeted
+              Balance changes in 2017/11/01-2017/12/31:
+
+                                    ||                2017/11                  2017/12
+              ======================++=================================================
+               assets:bank:checking || $-2445 [99% of $-2480]  $-2665 [107% of $-2480]
+               expenses:bus         ||       $49 [98% of $50]        $53 [106% of $50]
+               expenses:food        ||     $396 [99% of $400]      $412 [103% of $400]
+               expenses:gifts       ||                      0                     $100
+               expenses:movies      ||      $30 [100% of $30]            0 [0% of $30]
+               expenses:supplies    ||                    $20                        0
+               income               ||   $1950 [98% of $2000]    $2100 [105% of $2000]
+              ----------------------++-------------------------------------------------
+                                    ||                      0                        0
+
+       For more examples and details, see Budgeting and Forecasting.
+
    Custom balance output
        In simple (non-multi-column) balance reports,  you  can  customise  the
        output with --format FMT: