update embedded manuals

hledger-lib/hledger_journal.5

@@ -365,6 +365,10 @@ Some examples:
 .P
 .PD
 \f[C]EUR\ \-2.000.000,00\f[]
+.PD 0
+.P
+.PD
+\f[C]1\ 999\ 999.9455\f[]
 .PP
 As you can see, the amount format is somewhat flexible:
 .IP \[bu] 2
@@ -380,8 +384,11 @@ negative amounts with a commodity on the left can have the minus sign
 before or after it
 .IP \[bu] 2
 digit groups (thousands, or any other grouping) can be separated by
-commas (in which case period is used for decimal point) or periods (in
+space or comma or period and should be used as separator between all
-which case comma is used for decimal point)
+groups
+.IP \[bu] 2
+decimal part can be separated by comma or period and should be different
+from digit groups separator
 .PP
 You can use any of these variations when recording data.
 However, there is some ambiguous way of representing numbers like
@@ -1116,13 +1123,22 @@ followed by a period expression:
 \f[]
 .fi
 .PP
-Periodic transactions are used for budgeting and forecasting only, they
+Periodic transactions are used for forecasting and budgeting only, they
-have no effect without the \f[C]\-\-forecast\f[] or \f[C]\-\-budget\f[]
+have no effect unless the \f[C]\-\-forecast\f[] or \f[C]\-\-budget\f[]
-option specified.
+flag is used.
-For examples and details, see Budgeting and Forecasting.
+With \f[C]\-\-forecast\f[], 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 \f[C]balance\ \-\-budget\f[], each periodic transaction declares
+recurring budget goals for one or more accounts.
+.PD 0
+.P
+.PD
+For more details, see: balance > Budgeting, Budgeting and Forecasting.
 .SH Automated posting rules
 .PP
-Autopated posting rule starts with an equal sign `=' in place of a date,
+Automated posting rule starts with an equal sign `=' in place of a date,
 followed by a query:
 .IP
 .nf

hledger-lib/hledger_journal.info

@@ -348,6 +348,7 @@ commodity name.  Some examples:
 '-$1,000,000.00'
 'INR 9,99,99,999.00'
 'EUR -2.000.000,00'
+'1 999 999.9455'
 
    As you can see, the amount format is somewhat flexible:
 
@@ -360,8 +361,10 @@ commodity name.  Some examples:
    * negative amounts with a commodity on the left can have the minus
      sign before or after it
    * digit groups (thousands, or any other grouping) can be separated by
-     commas (in which case period is used for decimal point) or periods
+     space or comma or period and should be used as separator between
-     (in which case comma is used for decimal point)
+     all groups
+   * decimal part can be separated by comma or period and should be
+     different from digit groups separator
 
    You can use any of these variations when recording data.  However,
 there is some ambiguous way of representing numbers like '$1.000' and
@@ -1068,9 +1071,15 @@ followed by a period expression:
   assets:bank:checking   $400 ; paycheck
   income:acme inc
 
-   Periodic transactions are used for budgeting and forecasting only,
+   Periodic transactions are used for forecasting and budgeting only,
-they have no effect without the '--forecast' or '--budget' option
+they have no effect unless the '--forecast' or '--budget' flag is used.
-specified.  For examples and details, see Budgeting and Forecasting.
+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, Budgeting and Forecasting.
 
 
 File: hledger_journal.info,  Node: Automated posting rules,  Next: EDITOR SUPPORT,  Prev: Periodic transactions,  Up: Top
@@ -1078,7 +1087,7 @@ File: hledger_journal.info,  Node: Automated posting rules,  Next: EDITOR SUPPOR
 3 Automated posting rules
 *************************
 
-Autopated posting rule starts with an equal sign '=' in place of a date,
+Automated posting rule starts with an equal sign '=' in place of a date,
 followed by a query:
 
 = expenses:gifts
@@ -1162,65 +1171,65 @@ Node: Account names11244
 Ref: #account-names11387
 Node: Amounts11874
 Ref: #amounts12010
-Node: Virtual Postings14601
+Node: Virtual Postings14690
-Ref: #virtual-postings14760
+Ref: #virtual-postings14849
-Node: Balance Assertions15980
+Node: Balance Assertions16069
-Ref: #balance-assertions16155
+Ref: #balance-assertions16244
-Node: Assertions and ordering17051
+Node: Assertions and ordering17140
-Ref: #assertions-and-ordering17237
+Ref: #assertions-and-ordering17326
-Node: Assertions and included files17937
+Node: Assertions and included files18026
-Ref: #assertions-and-included-files18178
+Ref: #assertions-and-included-files18267
-Node: Assertions and multiple -f options18511
+Node: Assertions and multiple -f options18600
-Ref: #assertions-and-multiple--f-options18765
+Ref: #assertions-and-multiple--f-options18854
-Node: Assertions and commodities18897
+Node: Assertions and commodities18986
-Ref: #assertions-and-commodities19132
+Ref: #assertions-and-commodities19221
-Node: Assertions and subaccounts19828
+Node: Assertions and subaccounts19917
-Ref: #assertions-and-subaccounts20060
+Ref: #assertions-and-subaccounts20149
-Node: Assertions and virtual postings20581
+Node: Assertions and virtual postings20670
-Ref: #assertions-and-virtual-postings20788
+Ref: #assertions-and-virtual-postings20877
-Node: Balance Assignments20930
+Node: Balance Assignments21019
-Ref: #balance-assignments21099
+Ref: #balance-assignments21188
-Node: Prices22219
+Node: Prices22308
-Ref: #prices22352
+Ref: #prices22441
-Node: Transaction prices22403
+Node: Transaction prices22492
-Ref: #transaction-prices22548
+Ref: #transaction-prices22637
-Node: Market prices24704
+Node: Market prices24793
-Ref: #market-prices24839
+Ref: #market-prices24928
-Node: Comments25799
+Node: Comments25888
-Ref: #comments25921
+Ref: #comments26010
-Node: Tags27163
+Node: Tags27252
-Ref: #tags27281
+Ref: #tags27370
-Node: Directives28683
+Node: Directives28772
-Ref: #directives28796
+Ref: #directives28885
-Node: Account aliases28989
+Node: Account aliases29078
-Ref: #account-aliases29133
+Ref: #account-aliases29222
-Node: Basic aliases29737
+Node: Basic aliases29826
-Ref: #basic-aliases29880
+Ref: #basic-aliases29969
-Node: Regex aliases30570
+Node: Regex aliases30659
-Ref: #regex-aliases30738
+Ref: #regex-aliases30827
-Node: Multiple aliases31456
+Node: Multiple aliases31545
-Ref: #multiple-aliases31628
+Ref: #multiple-aliases31717
-Node: end aliases32126
+Node: end aliases32215
-Ref: #end-aliases32266
+Ref: #end-aliases32355
-Node: account directive32367
+Node: account directive32456
-Ref: #account-directive32547
+Ref: #account-directive32636
-Node: apply account directive32843
+Node: apply account directive32932
-Ref: #apply-account-directive33039
+Ref: #apply-account-directive33128
-Node: Multi-line comments33698
+Node: Multi-line comments33787
-Ref: #multi-line-comments33888
+Ref: #multi-line-comments33977
-Node: commodity directive34016
+Node: commodity directive34105
-Ref: #commodity-directive34200
+Ref: #commodity-directive34289
-Node: Default commodity35072
+Node: Default commodity35161
-Ref: #default-commodity35245
+Ref: #default-commodity35334
-Node: Default year35782
+Node: Default year35871
-Ref: #default-year35947
+Ref: #default-year36036
-Node: Including other files36370
+Node: Including other files36459
-Ref: #including-other-files36527
+Ref: #including-other-files36616
-Node: Periodic transactions36924
+Node: Periodic transactions37013
-Ref: #periodic-transactions37095
+Ref: #periodic-transactions37184
-Node: Automated posting rules37470
+Node: Automated posting rules37927
-Ref: #automated-posting-rules37648
+Ref: #automated-posting-rules38105
-Node: EDITOR SUPPORT38757
+Node: EDITOR SUPPORT39214
-Ref: #editor-support38887
+Ref: #editor-support39344
 
 End Tag Table

hledger-lib/hledger_journal.txt

@@ -260,6 +260,7 @@ FILE FORMAT
        -$1,000,000.00
        INR 9,99,99,999.00
        EUR -2.000.000,00
+       1 999 999.9455
 
        As you can see, the amount format is somewhat flexible:
 
@@ -275,8 +276,11 @@ FILE FORMAT
          before or after it
 
        o digit  groups  (thousands, or any other grouping) can be separated by
-         commas (in which case period is used for decimal  point)  or  periods
+         space or comma or period and should be used as separator between  all
-         (in which case comma is used for decimal point)
+         groups
+
+       o decimal  part  can be separated by comma or period and should be dif-
+         ferent from digit groups separator
 
        You can use any of these  variations  when  recording  data.   However,
        there  is  some  ambiguous  way of representing numbers like $1.000 and
@@ -819,12 +823,17 @@ Periodic transactions
                 assets:bank:checking   $400 ; paycheck
                 income:acme inc
 
-       Periodic transactions are used for budgeting and forecasting only, they
+       Periodic transactions are used for forecasting and budgeting only, they
-       have  no  effect  without  the --forecast or --budget option specified.
+       have no effect unless the --forecast or --budget flag  is  used.   With
-       For examples and details, see Budgeting and Forecasting.
+       --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, Budgeting and Forecasting.
 
 Automated posting rules
-       Autopated posting rule starts with an equal sign  `='  in  place  of  a
+       Automated posting rule starts with an equal sign  `='  in  place  of  a
        date, followed by a query:
 
               = expenses:gifts
@@ -870,13 +879,14 @@ EDITOR SUPPORT
 
        Emacs              http://www.ledger-cli.org/3.0/doc/ledger-mode.html
        Vim                https://github.com/ledger/ledger/wiki/Getting-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-ui/hledger-ui.1

@@ -188,18 +188,14 @@ most recent applicable market price, if any)
 .RS
 .RE
 .TP
-.B \f[C]\-\-forecast\f[]
+.B \f[C]\-\-auto\f[]
-generate forecast transactions from [periodic
+apply automated posting rules to modify transactions.
-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[]
+.B \f[C]\-\-forecast\f[]
-apply automated posting rules to modify transactions where applicable
+apply periodic transaction rules to generate future transactions, to 6
-(can combine with \[en]forecast).
+months from now or report end date.
 .RS
 .RE
 .PP

hledger-ui/hledger-ui.info

@@ -131,17 +131,13 @@ 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
+     apply automated posting rules to modify transactions.
-     applicable (can combine with -forecast).
+'--forecast'
+
+     apply periodic transaction 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.
@@ -382,17 +378,17 @@ Tag Table:
 Node: Top71
 Node: OPTIONS827
 Ref: #options924
-Node: KEYS4356
+Node: KEYS4093
-Ref: #keys4451
+Ref: #keys4188
-Node: SCREENS7410
+Node: SCREENS7147
-Ref: #screens7495
+Ref: #screens7232
-Node: Accounts screen7585
+Node: Accounts screen7322
-Ref: #accounts-screen7713
+Ref: #accounts-screen7450
-Node: Register screen9943
+Node: Register screen9680
-Ref: #register-screen10098
+Ref: #register-screen9835
-Node: Transaction screen12172
+Node: Transaction screen11909
-Ref: #transaction-screen12330
+Ref: #transaction-screen12067
-Node: Error screen13200
+Node: Error screen12937
-Ref: #error-screen13322
+Ref: #error-screen13059
 
 End Tag Table

hledger-ui/hledger-ui.txt

@@ -128,15 +128,11 @@ OPTIONS
               convert amounts to their market value on  the  report  end  date
               (using the most recent applicable market price, if any)
 
-       --forecast
+       --auto apply automated posting rules to modify transactions.
-              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
+       --forecast
-              applicable (can combine with -forecast).
+              apply  periodic  transaction  rules  to generate future transac-
+              tions, 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.

hledger-web/hledger-web.1

@@ -243,18 +243,14 @@ most recent applicable market price, if any)
 .RS
 .RE
 .TP
-.B \f[C]\-\-forecast\f[]
+.B \f[C]\-\-auto\f[]
-generate forecast transactions from [periodic
+apply automated posting rules to modify transactions.
-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[]
+.B \f[C]\-\-forecast\f[]
-apply automated posting rules to modify transactions where applicable
+apply periodic transaction rules to generate future transactions, to 6
-(can combine with \[en]forecast).
+months from now or report end date.
 .RS
 .RE
 .PP

hledger-web/hledger-web.info

@@ -176,17 +176,13 @@ 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
+     apply automated posting rules to modify transactions.
-     applicable (can combine with -forecast).
+'--forecast'
+
+     apply periodic transaction 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.

hledger-web/hledger-web.txt

@@ -173,15 +173,11 @@ OPTIONS
               convert  amounts  to  their  market value on the report end date
               (using the most recent applicable market price, if any)
 
-       --forecast
+       --auto apply automated posting rules to modify transactions.
-              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
+       --forecast
-              applicable (can combine with -forecast).
+              apply periodic transaction rules  to  generate  future  transac-
+              tions, 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.

hledger/hledger.1

@@ -298,18 +298,14 @@ most recent applicable market price, if any)
 .RS
 .RE
 .TP
-.B \f[C]\-\-forecast\f[]
+.B \f[C]\-\-auto\f[]
-generate forecast transactions from [periodic
+apply automated posting rules to modify transactions.
-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[]
+.B \f[C]\-\-forecast\f[]
-apply automated posting rules to modify transactions where applicable
+apply periodic transaction rules to generate future transactions, to 6
-(can combine with \[en]forecast).
+months from now or report end date.
 .RS
 .RE
 .PP
@@ -739,19 +735,29 @@ Note that \f[C]weekly\f[], \f[C]monthly\f[], \f[C]quarterly\f[] and
 month, quarter or year accordingly, and will end on the last day of same
 period, even if associated period expression specifies different
 explicit start and end date.
-.SS For example:
 .PP
+For example:
+.PP
+.TS
+tab(@);
+l.
+T{
 \f[C]\-p\ "weekly\ from\ 2009/1/1\ to\ 2009/4/1"\f[] \[en] starts on
 2008/12/29, closest preceeding Monday
+T}
+T{
 \f[C]\-p\ "monthly\ in\ 2008/11/25"\f[] \[en] starts on 2018/11/01
-.PD 0
+T}
-.P
+T{
-.PD
 \f[C]\-p\ "quarterly\ from\ 2009\-05\-05\ to\ 2009\-06\-01"\f[] \-
 starts on 2009/04/01, ends on 2009/06/30, which are first and last days
-of Q2 2009 \f[C]\-p\ "yearly\ from\ 2009\-12\-29"\f[] \- starts on
+of Q2 2009
-2009/01/01, first day of 2009
+T}
-\[em]\[em]\[em]\[em]\[em]\[em]\[em]\[em]\[em]\[em]\[em]\[em]\[em]\[em]
+T{
+\f[C]\-p\ "yearly\ from\ 2009\-12\-29"\f[] \- starts on 2009/01/01,
+first day of 2009
+T}
+.TE
 .PP
 The following more complex report intervals are also supported:
 \f[C]biweekly\f[], \f[C]bimonthly\f[],
@@ -919,15 +925,15 @@ The \f[C]\-B/\-\-cost\f[] flag converts amounts to their cost at
 transaction time, if they have a transaction price specified.
 .SS Market value
 .PP
-The \f[C]\-V/\-\-value\f[] flag converts the reported amounts to their
+The \f[C]\-V/\-\-value\f[] flag converts reported amounts to their
-market value on the report end date, using the most recent applicable
+current market value.
-market prices, when known.
 Specifically, when there is a market price (P directive) for the
-amount's commodity, dated on or before the report end date (see hledger
+amount's commodity, dated on or before today's date (or the report end
-\-> Report start & end date), the amount will be converted to the
+date if specified), the amount will be converted to the price's
-price's commodity.
+commodity.
-If multiple applicable prices are defined, the latest\-dated one is used
+.PP
-(and if dates are equal, the one last parsed).
+When there are multiple applicable P directives, \-V chooses the most
+recent one, or in case of equal dates, the last\-parsed one.
 .PP
 For example:
 .IP
@@ -976,8 +982,11 @@ $\ hledger\ \-f\ t.j\ bal\ euros\ \-V\ \-e\ 2016/12/21
 .PP
 Currently, hledger's \-V only uses market prices recorded with P
 directives, not transaction prices (unlike Ledger).
+.SS Combining \-B and \-V
 .PP
-Using \-B and \-V together is allowed.
+Using \-B/\[en]cost and \-V/\[en]value together is currently allowed,
+but the results are probably not meaningful.
+Let us know if you find a use for this.
 .SS Regular expressions
 .PP
 hledger uses regular expressions in a number of places:
@@ -1439,26 +1448,25 @@ A file extension matching one of the above formats selects that format.
 .RE
 .TP
 .B \f[C]\-\-pretty\-tables\f[]
-Use unicode to display prettier tables.
+use unicode to display prettier tables.
 .RS
 .RE
 .TP
 .B \f[C]\-\-sort\-amount\f[]
-Sort by amount (total row amount, or by average if that is displayed),
+sort by amount instead of account name (in flat mode).
-instead of account name (in flat mode)
+With multiple columns, sorts by the row total, or by row average if that
+is displayed.
 .RS
 .RE
 .TP
 .B \f[C]\-\-budget\f[]
-Treat periodic transaction as definition of a budget.
+show performance compared to budget goals defined by periodic
-Compare real balances to budget balances and show percentage of budget
+transactions
-consumed.
 .RS
 .RE
 .TP
 .B \f[C]\-\-show\-unbudgeted\f[]
-When \[en]budget is used, display accounts that do not have budget
+with \[en]budget, show unbudgeted accounts also
-defined
 .RS
 .RE
 .PP
@@ -1671,10 +1679,11 @@ Balance\ changes\ in\ 2008:
 .fi
 .SS Budgets
 .PP
-The \f[C]\-\-budget\f[] flag will treat all [periodic
+With \f[C]\-\-budget\f[] and a report interval, all periodic
-transaction]((journal.html#periodic\-transactions) in your journal as
+transactions in your journal with that interval, active during the
-definition of the budget and allow you to compare real balances versus
+requested report period, are interpreted as recurring budget goals for
-budgeted amounts.
+the specified accounts (and subaccounts), and the report will show the
+difference between actual and budgeted balances.
 .PP
 For example, you can take average monthly expenses in the common expense
 categories to construct a minimal monthly budget:
@@ -1707,11 +1716,11 @@ categories to construct a minimal monthly budget:
 \f[]
 .fi
 .PP
-You can now compare real balances with budget:
+You can now see a monthly budget performance report:
 .IP
 .nf
 \f[C]
-$\ hledge\ balance\ \-M\ \-\-budget
+$\ hledger\ balance\ \-M\ \-\-budget
 Balance\ changes\ in\ 2017/11/01\-2017/12/31:
 
 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\ 
@@ -1748,8 +1757,9 @@ Ending\ balances\ (cumulative)\ in\ 2017/11/01\-2017/12/31:
 \f[]
 .fi
 .PP
-Adding \f[C]\-\-show\-unbudgeted\f[] will allow you to see all the
+Accounts with no budget goals (not mentioned in the periodic
-accounts for which budgets:
+transactions) will be aggregated under \f[C]<unbudgeted>\f[], unless you
+add the \f[C]\-\-show\-unbudgeted\f[] flag to display them normally:
 .IP
 .nf
 \f[C]
@@ -2387,6 +2397,7 @@ valid journal output.
 .PP
 With \f[C]\-B\f[]/\f[C]\-\-cost\f[], amounts with transaction prices are
 converted to cost using that price.
+This can be used for troubleshooting.
 .PP
 With \f[C]\-m\f[]/\f[C]\-\-match\f[] and a STR argument, print will show
 at most one transaction: the one one whose description is most similar

hledger/hledger.info

@@ -125,11 +125,11 @@ File: hledger.info,  Node: OPTIONS,  Next: QUERIES,  Prev: EXAMPLES,  Up: Top
 * Report start & end date::
 * Report intervals::
 * Period expressions::
-* For example::
 * Depth limiting::
 * Pivoting::
 * Cost::
 * Market value::
+* Combining -B and -V::
 * Regular expressions::
 
 
@@ -232,17 +232,13 @@ 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
+     apply automated posting rules to modify transactions.
-     applicable (can combine with -forecast).
+'--forecast'
+
+     apply periodic transaction 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.
@@ -444,7 +440,7 @@ complex intervals may be specified with a period expression.  Report
 intervals can not be specified with a query, currently.
 
 
-File: hledger.info,  Node: Period expressions,  Next: For example,  Prev: Report intervals,  Up: OPTIONS
+File: hledger.info,  Node: Period expressions,  Next: Depth limiting,  Prev: Report intervals,  Up: OPTIONS
 
 2.10 Period expressions
 =======================
@@ -504,18 +500,12 @@ accordingly, and will end on the last day of same period, even if
 associated period expression specifies different explicit start and end
 date.
 
-
+   For example:
-File: hledger.info,  Node: For example,  Next: Depth limiting,  Prev: Period expressions,  Up: OPTIONS
 
-2.11 For example:
+'-p "weekly from 2009/1/1 to 2009/4/1"' - starts on 2008/12/29, closest preceeding Monday
-=================
+'-p "monthly in 2008/11/25"' - starts on 2018/11/01
-
+'-p "quarterly from 2009-05-05 to 2009-06-01"' - starts on 2009/04/01, ends on 2009/06/30, which are first and last days of Q2 2009
-'-p "weekly from 2009/1/1 to 2009/4/1"' - starts on 2008/12/29, closest
+'-p "yearly from 2009-12-29"' - starts on 2009/01/01, first day of 2009
-preceeding Monday '-p "monthly in 2008/11/25"' - starts on 2018/11/01
-'-p "quarterly from 2009-05-05 to 2009-06-01"' - starts on 2009/04/01,
-ends on 2009/06/30, which are first and last days of Q2 2009 '-p "yearly
-from 2009-12-29"' - starts on 2009/01/01, first day of 2009
-----------------------------
 
    The following more complex report intervals are also supported:
 'biweekly', 'bimonthly', 'every day|week|month|quarter|year', 'every N
@@ -558,9 +548,9 @@ start date and exclusive end date):
    'hledger register checking -p "every 3rd day of week"'
 
 
-File: hledger.info,  Node: Depth limiting,  Next: Pivoting,  Prev: For example,  Up: OPTIONS
+File: hledger.info,  Node: Depth limiting,  Next: Pivoting,  Prev: Period expressions,  Up: OPTIONS
 
-2.12 Depth limiting
+2.11 Depth limiting
 ===================
 
 With the '--depth N' option (short form: '-N'), commands like account,
@@ -572,7 +562,7 @@ less detail.  This flag has the same effect as a 'depth:' query argument
 
 File: hledger.info,  Node: Pivoting,  Next: Cost,  Prev: Depth limiting,  Up: OPTIONS
 
-2.13 Pivoting
+2.12 Pivoting
 =============
 
 Normally hledger sums amounts, and organizes them in a hierarchy, based
@@ -629,26 +619,26 @@ $ hledger balance --pivot member acct:.
 
 File: hledger.info,  Node: Cost,  Next: Market value,  Prev: Pivoting,  Up: OPTIONS
 
-2.14 Cost
+2.13 Cost
 =========
 
 The '-B/--cost' flag converts amounts to their cost at transaction time,
 if they have a transaction price specified.
 
 
-File: hledger.info,  Node: Market value,  Next: Regular expressions,  Prev: Cost,  Up: OPTIONS
+File: hledger.info,  Node: Market value,  Next: Combining -B and -V,  Prev: Cost,  Up: OPTIONS
 
-2.15 Market value
+2.14 Market value
 =================
 
-The '-V/--value' flag converts the reported amounts to their market
+The '-V/--value' flag converts reported amounts to their current market
-value on the report end date, using the most recent applicable market
+value.  Specifically, when there is a market price (P directive) for the
-prices, when known.  Specifically, when there is a market price (P
+amount's commodity, dated on or before today's date (or the report end
-directive) for the amount's commodity, dated on or before the report end
+date if specified), the amount will be converted to the price's
-date (see hledger -> Report start & end date), the amount will be
+commodity.
-converted to the price's commodity.  If multiple applicable prices are
+
-defined, the latest-dated one is used (and if dates are equal, the one
+   When there are multiple applicable P directives, -V chooses the most
-last parsed).
+recent one, or in case of equal dates, the last-parsed one.
 
    For example:
 
@@ -682,10 +672,18 @@ $ hledger -f t.j bal euros -V -e 2016/12/21
    Currently, hledger's -V only uses market prices recorded with P
 directives, not transaction prices (unlike Ledger).
 
-   Using -B and -V together is allowed.
+
+File: hledger.info,  Node: Combining -B and -V,  Next: Regular expressions,  Prev: Market value,  Up: OPTIONS
+
+2.15 Combining -B and -V
+========================
+
+Using -B/-cost and -V/-value together is currently allowed, but the
+results are probably not meaningful.  Let us know if you find a use for
+this.
 
 
-File: hledger.info,  Node: Regular expressions,  Prev: Market value,  Up: OPTIONS
+File: hledger.info,  Node: Regular expressions,  Prev: Combining -B and -V,  Up: OPTIONS
 
 2.16 Regular expressions
 ========================
@@ -1088,19 +1086,19 @@ Show accounts and their balances.  Aliases: b, bal.
      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
+     sort by amount instead of account name (in flat mode).  With
-     displayed), instead of account name (in flat mode)
+     multiple columns, sorts by the row total, or by row average if that
+     is displayed.
 '--budget'
 
-     Treat periodic transaction as definition of a budget.  Compare real
+     show performance compared to budget goals defined by periodic
-     balances to budget balances and show percentage of budget consumed.
+     transactions
 '--show-unbudgeted'
 
-     When -budget is used, display accounts that do not have budget
+     with -budget, show unbudgeted accounts also
-     defined
 
    The balance command displays accounts and balances.  It is hledger's
 most featureful and versatile command.
@@ -1295,10 +1293,11 @@ File: hledger.info,  Node: Budgets,  Next: Custom balance output,  Prev: Multico
 4.4.4 Budgets
 -------------
 
-The '--budget' flag will treat all [periodic
+With '--budget' and a report interval, all periodic transactions in your
-transaction]((journal.html#periodic-transactions) in your journal as
+journal with that interval, active during the requested report period,
-definition of the budget and allow you to compare real balances versus
+are interpreted as recurring budget goals for the specified accounts
-budgeted amounts.
+(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:
@@ -1327,9 +1326,9 @@ expense categories to construct a minimal monthly budget:
   expenses:gifts   $100
   assets:bank:checking
 
-   You can now compare real balances with budget:
+   You can now see a monthly budget performance report:
 
-$ hledge balance -M --budget
+$ hledger balance -M --budget
 Balance changes in 2017/11/01-2017/12/31:
 
                        ||                2017/11                  2017/12 
@@ -1359,8 +1358,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
+   Accounts with no budget goals (not mentioned in the periodic
-which budgets:
+transactions) will be aggregated under '<unbudgeted>', unless you add
+the '--show-unbudgeted' flag to display them normally:
 
 $ hledger balance --budget --show-unbudgeted
 Balance changes in 2017/11/01-2017/12/31:
@@ -1913,7 +1913,7 @@ arise when a multi-commodity transaction has an implicit amount) will be
 split into multiple single-commodity postings, for valid journal output.
 
    With '-B'/'--cost', amounts with transaction prices are converted to
-cost using that price.
+cost using that price.  This can be used for troubleshooting.
 
    With '-m'/'--match' and a STR argument, print will show at most one
 transaction: the one one whose description is most similar to STR, and
@@ -2372,88 +2372,88 @@ Node: EXAMPLES1888
 Ref: #examples1988
 Node: OPTIONS3634
 Ref: #options3736
-Node: General options4052
+Node: General options4060
-Ref: #general-options4177
+Ref: #general-options4185
-Node: Command options6991
+Node: Command options6736
-Ref: #command-options7142
+Ref: #command-options6887
-Node: Command arguments7540
+Node: Command arguments7285
-Ref: #command-arguments7694
+Ref: #command-arguments7439
-Node: Argument files7815
+Node: Argument files7560
-Ref: #argument-files7966
+Ref: #argument-files7711
-Node: Special characters8232
+Node: Special characters7977
-Ref: #special-characters8385
+Ref: #special-characters8130
-Node: Input files9804
+Node: Input files9549
-Ref: #input-files9940
+Ref: #input-files9685
-Node: Smart dates11910
+Node: Smart dates11655
-Ref: #smart-dates12051
+Ref: #smart-dates11796
-Node: Report start & end date13030
+Node: Report start & end date12775
-Ref: #report-start-end-date13200
+Ref: #report-start-end-date12945
-Node: Report intervals14265
+Node: Report intervals14010
-Ref: #report-intervals14428
+Ref: #report-intervals14173
-Node: Period expressions14829
+Node: Period expressions14574
-Ref: #period-expressions14986
+Ref: #period-expressions14734
-Node: For example17031
+Node: Depth limiting18691
-Ref: #for-example17174
+Ref: #depth-limiting18835
-Node: Depth limiting19098
+Node: Pivoting19177
-Ref: #depth-limiting19235
+Ref: #pivoting19295
-Node: Pivoting19577
+Node: Cost20971
-Ref: #pivoting19695
+Ref: #cost21079
-Node: Cost21371
+Node: Market value21197
-Ref: #cost21479
+Ref: #market-value21332
-Node: Market value21597
+Node: Combining -B and -V22515
-Ref: #market-value21732
+Ref: #combining--b-and--v22679
-Node: Regular expressions23032
+Node: Regular expressions22826
-Ref: #regular-expressions23168
+Ref: #regular-expressions22969
-Node: QUERIES24529
+Node: QUERIES24330
-Ref: #queries24631
+Ref: #queries24432
-Node: COMMANDS28598
+Node: COMMANDS28399
-Ref: #commands28710
+Ref: #commands28511
-Node: accounts29693
+Node: accounts29494
-Ref: #accounts29791
+Ref: #accounts29592
-Node: activity30784
+Node: activity30585
-Ref: #activity30894
+Ref: #activity30695
-Node: add31254
+Node: add31055
-Ref: #add31353
+Ref: #add31154
-Node: balance34014
+Node: balance33815
-Ref: #balance34125
+Ref: #balance33926
-Node: Flat mode37554
+Node: Flat mode37300
-Ref: #flat-mode37679
+Ref: #flat-mode37425
-Node: Depth limited balance reports38099
+Node: Depth limited balance reports37845
-Ref: #depth-limited-balance-reports38300
+Ref: #depth-limited-balance-reports38046
-Node: Multicolumn balance reports38720
+Node: Multicolumn balance reports38466
-Ref: #multicolumn-balance-reports38915
+Ref: #multicolumn-balance-reports38661
-Node: Budgets43604
+Node: Budgets43350
-Ref: #budgets43751
+Ref: #budgets43497
-Node: Custom balance output47367
+Node: Custom balance output47328
-Ref: #custom-balance-output47529
+Ref: #custom-balance-output47490
-Node: Colour support49622
+Node: Colour support49583
-Ref: #colour-support49781
+Ref: #colour-support49742
-Node: Output destination49954
+Node: Output destination49915
-Ref: #output-destination50110
+Ref: #output-destination50071
-Node: CSV output50380
+Node: CSV output50341
-Ref: #csv-output50497
+Ref: #csv-output50458
-Node: balancesheet50894
+Node: balancesheet50855
-Ref: #balancesheet51030
+Ref: #balancesheet50991
-Node: balancesheetequity52998
+Node: balancesheetequity52959
-Ref: #balancesheetequity53147
+Ref: #balancesheetequity53108
-Node: cashflow53936
+Node: cashflow53897
-Ref: #cashflow54064
+Ref: #cashflow54025
-Node: check-dates55976
+Node: check-dates55937
-Ref: #check-dates56103
+Ref: #check-dates56064
-Node: check-dupes56220
+Node: check-dupes56181
-Ref: #check-dupes56345
+Ref: #check-dupes56306
-Node: equity56482
+Node: equity56443
-Ref: #equity56592
+Ref: #equity56553
-Node: help56755
+Node: help56716
-Ref: #help56856
+Ref: #help56817
-Node: import57930
+Node: import57891
-Ref: #import58044
+Ref: #import58005
-Node: incomestatement58774
+Node: incomestatement58735
-Ref: #incomestatement58908
+Ref: #incomestatement58869
-Node: prices60861
+Node: prices60822
-Ref: #prices60976
+Ref: #prices60937
-Node: print61019
+Node: print60980
-Ref: #print61129
+Ref: #print61090
 Node: print-unique65975
 Ref: #print-unique66101
 Node: register66169

hledger/hledger.txt

@@ -202,15 +202,11 @@ OPTIONS
               convert amounts to their market value on  the  report  end  date
               (using the most recent applicable market price, if any)
 
-       --forecast
+       --auto apply automated posting rules to modify transactions.
-              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
+       --forecast
-              applicable (can combine with -forecast).
+              apply  periodic  transaction  rules  to generate future transac-
+              tions, 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.
@@ -459,12 +455,23 @@ OPTIONS
        expression specifies different explicit start and end date.
 
        For example:
-       -p "weekly from 2009/1/1 to 2009/4/1" - starts on  2008/12/29,  closest
+
-       preceeding Monday -p "monthly in 2008/11/25" - starts on 2018/11/01
+
-       -p "quarterly from 2009-05-05 to 2009-06-01"  -  starts  on 2009/04/01,
+       -p "weekly from 2009/1/1 to 2009/4/1" -
-       ends  on  2009/06/30,  which  are  first  and  last  days  of  Q2  2009
+       starts  on 2008/12/29, closest preceed-
-       -p "yearly from 2009-12-29"  -  starts on 2009/01/01, first day of 2009
+       ing Monday
-       ----------------------------
+       -p "monthly in 2008/11/25" - starts  on
+       2018/11/01
+
+
+
+       -p "quar-
+       terly from 2009-05-05 to 2009-06-01"  -
+       starts    on    2009/04/01,   ends   on
+       2009/06/30, which are  first  and  last
+       days of Q2 2009
+       -p "yearly from 2009-12-29" - starts on
+       2009/01/01, first day of 2009
 
        The  following  more  complex  report  intervals  are  also  supported:
        biweekly,         bimonthly,         every day|week|month|quarter|year,
@@ -582,13 +589,14 @@ OPTIONS
        if they have a transaction price specified.
 
    Market value
-       The -V/--value flag converts the reported amounts to their market value
+       The -V/--value flag converts reported amounts to their  current  market
-       on the report end date, using the most recent applicable market prices,
+       value.   Specifically,  when  there is a market price (P directive) for
-       when known.  Specifically, when there is a market price  (P  directive)
+       the amount's commodity, dated on or before today's date (or the  report
-       for the amount's commodity, dated on or before the report end date (see
+       end  date  if  specified),  the amount will be converted to the price's
-       hledger -> Report start & end date), the amount will  be  converted  to
+       commodity.
-       the  price's commodity.  If multiple applicable prices are defined, the
+
-       latest-dated one is used (and if dates are equal, the one last parsed).
+       When there are multiple applicable P directives, -V  chooses  the  most
+       recent one, or in case of equal dates, the last-parsed one.
 
        For example:
 
@@ -622,7 +630,10 @@ OPTIONS
        Currently, hledger's -V only uses market prices recorded with P  direc-
        tives, not transaction prices (unlike Ledger).
 
-       Using -B and -V together is allowed.
+   Combining -B and -V
+       Using  -B/-cost  and  -V/-value  together is currently allowed, but the
+       results are probably not meaningful.  Let us know if you find a use for
+       this.
 
    Regular expressions
        hledger uses regular expressions in a number of places:
@@ -980,20 +991,19 @@ COMMANDS
               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  dis-
+              sort by amount instead of account name  (in  flat  mode).   With
-              played), instead of account name (in flat mode)
+              multiple  columns,  sorts by the row total, or by row average if
+              that is displayed.
 
        --budget
-              Treat  periodic  transaction as definition of a budget.  Compare
+              show performance compared to budget goals  defined  by  periodic
-              real balances to budget balances and show percentage  of  budget
+              transactions
-              consumed.
 
        --show-unbudgeted
-              When  -budget  is used, display accounts that do not have budget
+              with -budget, show unbudgeted accounts also
-              defined
 
        The  balance  command  displays accounts and balances.  It is hledger's
        most featureful and versatile command.
@@ -1157,9 +1167,11 @@ COMMANDS
               # Average is rounded to the dollar here since all journal amounts are
 
    Budgets
-       The   --budget   flag  will  treat  all  [periodic  transaction]((jour-
+       With --budget and a report interval, all periodic transactions in  your
-       nal.html#periodic-transactions) in your journal as  definition  of  the
+       journal  with that interval, active during the requested report period,
-       budget  and allow you to compare real balances versus budgeted amounts.
+       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:
@@ -1188,9 +1200,9 @@ COMMANDS
                 expenses:gifts   $100
                 assets:bank:checking
 
-       You can now compare real balances with budget:
+       You can now see a monthly budget performance report:
 
-              $ hledge balance -M --budget
+              $ hledger balance -M --budget
               Balance changes in 2017/11/01-2017/12/31:
 
                                      ||                2017/11                  2017/12
@@ -1220,8 +1232,9 @@ COMMANDS
               -----------------------++-------------------------------------------------
                                      ||                      0                        0
 
-       Adding  --show-unbudgeted  will  allow  you to see all the accounts for
+       Accounts  with  no budget goals (not mentioned in the periodic transac-
-       which budgets:
+       tions) will be  aggregated  under  <unbudgeted>,  unless  you  add  the
+       --show-unbudgeted flag to display them normally:
 
               $ hledger balance --budget --show-unbudgeted
               Balance changes in 2017/11/01-2017/12/31:
@@ -1696,7 +1709,7 @@ COMMANDS
        put.
 
        With -B/--cost, amounts with transaction prices are converted  to  cost
-       using that price.
+       using that price.  This can be used for troubleshooting.
 
        With  -m/--match and a STR argument, print will show at most one trans-
        action: the one one whose description is most similar to  STR,  and  is