diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index 2b9c4a013..fb00247d9 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 0c95914d1..f6dddb9ac 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 9eb4d5127..6e11febf8 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 0f013a851..63267fba7 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. + 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 + 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)