doc: journal: mention "auto postings"; explain the #893 situation

[ci skip]

hledger-lib/hledger_journal.5

@@ -1659,13 +1659,14 @@ Goals and actual performance can then be compared in budget reports.
 For more details, see: balance: Budget report and Cookbook: Budgeting
 and Forecasting.
 .PP
-.SS Transaction Modifiers
+.SS Transaction modifiers
 .PP
 Transaction modifier rules describe changes that should be applied
 automatically to certain transactions.
-Currently, this means adding extra postings (also known as "automated
-postings").
-Transaction modifiers are enabled by the \f[C]\-\-auto\f[] flag.
+They can be enabled by using the \f[C]\-\-auto\f[] flag.
+Currently, just one kind of change is possible: adding extra postings.
+These rule\-generated postings are known as "automated postings" or
+"auto postings".
 .PP
 A transaction modifier rule looks quite like a normal transaction,
 except the first line is an equals sign followed by a query that matches
@@ -1681,8 +1682,7 @@ And each "posting" is actually a posting\-generating rule:
 \f[]
 .fi
 .PP
-The posting rules look just like normal postings, except the amount can
-be:
+These posting rules look like normal postings, except the amount can be:
 .IP \[bu] 2
 a normal amount with a commodity symbol, eg \f[C]$2\f[].
 This will be used as\-is.
@@ -1738,10 +1738,20 @@ $\ hledger\ print\ \-\-auto
 \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ $20
 \f[]
 .fi
+.SS Transaction modifiers and transaction balancing / inferred amounts /
+balance assertions
 .PP
-Postings added by transaction modifiers participate in transaction
-balancing, missing amount inference and balance assertions, like regular
-postings.
+Currently, transaction modifiers are applied / auto postings are added:
+.IP \[bu] 2
+after missing amounts are inferred, and transactions are checked for
+balancedness,
+.IP \[bu] 2
+but before balance assertions are checked.
+.PP
+This means that journal entries must be balanced both before and after
+auto postings are added.
+This has changed in hledger 1.12+.
+For some background discussion, see #893, #928, #938.
 .SH EDITOR SUPPORT
 .PP
 Add\-on modes exist for various text editors, to make working with

hledger-lib/hledger_journal.info

@@ -82,7 +82,7 @@ File: hledger_journal.info,  Node: FILE FORMAT,  Next: EDITOR SUPPORT,  Prev: To
 * Tags::
 * Directives::
 * Periodic transactions::
-* Transaction Modifiers::
+* Transaction modifiers::
 
 
 File: hledger_journal.info,  Node: Transactions,  Next: Postings,  Up: FILE FORMAT
@@ -1378,7 +1378,7 @@ If account aliases are present, they are applied after the default
 parent account.
 
 
-File: hledger_journal.info,  Node: Periodic transactions,  Next: Transaction Modifiers,  Prev: Directives,  Up: FILE FORMAT
+File: hledger_journal.info,  Node: Periodic transactions,  Next: Transaction modifiers,  Prev: Directives,  Up: FILE FORMAT
 
 1.15 Periodic transactions
 ==========================
@@ -1488,15 +1488,16 @@ compared in budget reports.
 and Forecasting.
 
 
-File: hledger_journal.info,  Node: Transaction Modifiers,  Prev: Periodic transactions,  Up: FILE FORMAT
+File: hledger_journal.info,  Node: Transaction modifiers,  Prev: Periodic transactions,  Up: FILE FORMAT
 
-1.16 Transaction Modifiers
+1.16 Transaction modifiers
 ==========================
 
 Transaction modifier rules describe changes that should be applied
-automatically to certain transactions.  Currently, this means adding
-extra postings (also known as "automated postings").  Transaction
-modifiers are enabled by the '--auto' flag.
+automatically to certain transactions.  They can be enabled by using the
+'--auto' flag.  Currently, just one kind of change is possible: adding
+extra postings.  These rule-generated postings are known as "automated
+postings" or "auto postings".
 
    A transaction modifier rule looks quite like a normal transaction,
 except the first line is an equals sign followed by a query that matches
@@ -1508,8 +1509,8 @@ is actually a posting-generating rule:
     ACCT  [AMT]
     ...
 
-   The posting rules look just like normal postings, except the amount
-can be:
+   These posting rules look like normal postings, except the amount can
+be:
 
    * a normal amount with a commodity symbol, eg '$2'.  This will be
      used as-is.
@@ -1553,9 +1554,26 @@ $ hledger print --auto
     assets:checking:gifts     -$20
     assets:checking            $20
 
-   Postings added by transaction modifiers participate in transaction
-balancing, missing amount inference and balance assertions, like regular
-postings.
+* Menu:
+
+* Transaction modifiers and transaction balancing / inferred amounts / balance assertions::
+
+
+File: hledger_journal.info,  Node: Transaction modifiers and transaction balancing / inferred amounts / balance assertions,  Up: Transaction modifiers
+
+1.16.1 Transaction modifiers and transaction balancing / inferred
+-----------------------------------------------------------------
+
+amounts / balance assertions Currently, transaction modifiers are
+applied / auto postings are added:
+
+   * after missing amounts are inferred, and transactions are checked
+     for balancedness,
+   * but before balance assertions are checked.
+
+   This means that journal entries must be balanced both before and
+after auto postings are added.  This has changed in hledger 1.12+.  For
+some background discussion, see #893, #928, #938.
 
 
 File: hledger_journal.info,  Node: EDITOR SUPPORT,  Prev: FILE FORMAT,  Up: Top
@@ -1685,9 +1703,11 @@ Node: Forecasting with periodic transactions52482
 Ref: #forecasting-with-periodic-transactions52772
 Node: Budgeting with periodic transactions54459
 Ref: #budgeting-with-periodic-transactions54698
-Node: Transaction Modifiers55157
+Node: Transaction modifiers55157
 Ref: #transaction-modifiers55320
-Node: EDITOR SUPPORT57301
-Ref: #editor-support57419
+Node: Transaction modifiers and transaction balancing / inferred amounts / balance assertions57312
+Ref: #transaction-modifiers-and-transaction-balancing-inferred-amounts-balance-assertions57627
+Node: EDITOR SUPPORT58034
+Ref: #editor-support58152
 
 End Tag Table

hledger-lib/hledger_journal.m4.md

@@ -1229,12 +1229,14 @@ and
 
 
 <a name="automated-postings"></a>
+<a name="auto-postings"></a>
 
-## Transaction Modifiers
+## Transaction modifiers
 
 Transaction modifier rules describe changes that should be applied automatically to certain transactions.
-Currently, this means adding extra postings (also known as "automated postings").
-Transaction modifiers are enabled by the `--auto` flag.
+They can be enabled by using the `--auto` flag.
+Currently, just one kind of change is possible: adding extra postings.
+These rule-generated postings are known as "automated postings" or "auto postings".
 
 A transaction modifier rule looks quite like a normal transaction,
 except the first line is an equals sign followed by a [query](manual.html#queries) that matches certain postings
@@ -1248,7 +1250,7 @@ And each "posting" is actually a posting-generating rule:
     ...
 ```
 
-The posting rules look just like normal postings, except the amount can be:
+These posting rules look like normal postings, except the amount can be:
 
 - a normal amount with a commodity symbol, eg `$2`. This will be used as-is.
 - a number, eg `2`. The commodity symbol (if any) from the matched posting will be added to this. 
@@ -1288,18 +1290,24 @@ $ hledger print --auto
     assets:checking            $20
 ```
 
+### Auto postings and transaction balancing / inferred amounts / balance assertions
 
-Postings added by transaction modifiers participate in
-[transaction balancing, missing amount inference](#postings)
-and [balance assertions](#balance-assertions),
-like regular postings.
+Currently, transaction modifiers are applied / auto postings are added:
+
+- after [missing amounts are inferred, and transactions are checked for balancedness](#postings),
+- but before [balance assertions](#balance-assertions) are checked.
+
+Note this means that journal entries must be balanced both before and
+after auto postings are added. This changed in hledger 1.12+; see
+[#893](https://github.com/simonmichael/hledger/issues/893) for
+background.
 
 # EDITOR SUPPORT
 
-Add-on modes exist for various text editors, to make working with journal
-files easier. They add colour, navigation aids and helpful commands.
-For hledger users who edit the journal file directly (the majority),
-using one of these modes is quite recommended.
+Add-on modes exist for various text editors, to make working with
+journal files easier. They add colour, navigation aids and helpful
+commands.  For hledger users who edit the journal file directly (the
+majority), using one of these modes is quite recommended.
 
 These were written with Ledger in mind, but also work with hledger files:
 

hledger-lib/hledger_journal.txt

@@ -1195,36 +1195,37 @@ FILE FORMAT
        and Forecasting.
 
 
-   Transaction Modifiers
+   Transaction modifiers
        Transaction  modifier  rules  describe  changes  that should be applied
-       automatically to certain transactions.  Currently,  this  means  adding
-       extra postings (also known as "automated postings").  Transaction modi-
-       fiers are enabled by the --auto flag.
-
-       A transaction modifier rule looks  quite  like  a  normal  transaction,
-       except  the  first  line  is  an  equals  sign followed by a query that
-       matches certain postings (mnemonic: =  suggests  matching).   And  each
+       automatically to certain transactions.  They can be  enabled  by  using
+       the  --auto  flag.   Currently,  just  one  kind of change is possible:
+       adding extra postings.  These  rule-generated  postings  are  known  as
+       "automated postings" or "auto postings".
+
+       A  transaction  modifier  rule  looks  quite like a normal transaction,
+       except the first line is an  equals  sign  followed  by  a  query  that
+       matches  certain  postings  (mnemonic:  = suggests matching).  And each
        "posting" is actually a posting-generating rule:
 
               = QUERY
                   ACCT  AMT
                   ACCT  [AMT]
                   ...
 
-       The posting rules look just like normal postings, except the amount can
+       These posting rules look like normal postings, except  the  amount  can
        be:
 
-       o a normal amount with a commodity symbol, eg $2.  This  will  be  used
+       o a  normal  amount  with a commodity symbol, eg $2.  This will be used
          as-is.
 
        o a number, eg 2.  The commodity symbol (if any) from the matched post-
          ing will be added to this.
 
-       o a numeric multiplier, eg *2 (a star followed by  a  number  N).   The
+       o a  numeric  multiplier,  eg  *2 (a star followed by a number N).  The
          matched posting's amount (and total price, if any) will be multiplied
          by N.
 
-       o a multiplier with a commodity symbol, eg *$2 (a star, number  N,  and
+       o a  multiplier  with a commodity symbol, eg *$2 (a star, number N, and
          symbol S).  The matched posting's amount will be multiplied by N, and
          its commodity symbol will be replaced with S.
 
@@ -1259,17 +1260,27 @@ FILE FORMAT
                   assets:checking:gifts     -$20
                   assets:checking            $20
 
-       Postings added by transaction modifiers participate in transaction bal-
-       ancing,  missing  amount inference and balance assertions, like regular
-       postings.
+   Transaction modifiers and transaction balancing / inferred amounts /
+       balance assertions
+
+       Currently, transaction modifiers are applied / auto postings are added:
+
+       o after missing amounts are inferred, and transactions are checked  for
+         balancedness,
+
+       o but before balance assertions are checked.
+
+       This  means that journal entries must be balanced both before and after
+       auto postings are added.  This has changed in hledger 1.12+.  For  some
+       background discussion, see #893, #928, #938.
 
 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-
-       mands.  For hledger users who  edit  the  journal  file  directly  (the
+       nal files easier.  They add colour, navigation aids  and  helpful  com-
+       mands.   For  hledger  users  who  edit  the journal file directly (the
        majority), using one of these modes is quite recommended.
 
-       These  were  written  with  Ledger  in mind, but also work with hledger
+       These were written with Ledger in mind,  but  also  work  with  hledger
        files:
 
 
@@ -1280,6 +1291,7 @@ EDITOR SUPPORT
        Sublime Text   https://github.com/ledger/ledger/wiki/Edit-
                       ing-Ledger-files-with-Sublime-Text-or-RubyMine
        Textmate       https://github.com/ledger/ledger/wiki/Using-TextMate-2
+
        Text   Wran-   https://github.com/ledger/ledger/wiki/Edit-
        gler           ing-Ledger-files-with-TextWrangler
        Visual  Stu-   https://marketplace.visualstudio.com/items?item-
@@ -1288,7 +1300,7 @@ EDITOR SUPPORT
 
 
 REPORTING BUGS
-       Report bugs at http://bugs.hledger.org (or on the #hledger IRC  channel
+       Report  bugs at http://bugs.hledger.org (or on the #hledger IRC channel
        or hledger mail list)
 
 
@@ -1302,7 +1314,7 @@ COPYRIGHT
 
 
 SEE ALSO
-       hledger(1),      hledger-ui(1),     hledger-web(1),     hledger-api(1),
+       hledger(1),     hledger-ui(1),     hledger-web(1),      hledger-api(1),
        hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
        dot(5), ledger(1)