diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5
index 2b9c4a01325..fb00247d9cb 100644
--- a/hledger-lib/hledger_journal.5
+++ b/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
diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info
index 0c95914d17d..f6dddb9acdc 100644
--- a/hledger-lib/hledger_journal.info
+++ b/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
diff --git a/hledger-lib/hledger_journal.m4.md b/hledger-lib/hledger_journal.m4.md
index 9eb4d5127af..6e11febf893 100644
--- a/hledger-lib/hledger_journal.m4.md
+++ b/hledger-lib/hledger_journal.m4.md
@@ -1229,12 +1229,14 @@ and
+
-## 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:
diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt
index 0f013a8515f..63267fba797 100644
--- a/hledger-lib/hledger_journal.txt
+++ b/hledger-lib/hledger_journal.txt
@@ -1195,15 +1195,16 @@ 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
@@ -1211,20 +1212,20 @@ FILE FORMAT
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)