From abc53024fc62515060ddd81c002d6fbe67351666 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 18 Mar 2020 15:11:31 -0700 Subject: [PATCH] ;journal: doc: drop "transaction modifiers", just say "auto postings" --- doc/common.m4 | 2 +- hledger-lib/hledger_journal.m4.md | 44 ++++++++++++++++--------------- 2 files changed, 24 insertions(+), 22 deletions(-) diff --git a/doc/common.m4 b/doc/common.m4 index 4984e52e3..a0c4c1a4d 100644 --- a/doc/common.m4 +++ b/doc/common.m4 @@ -148,7 +148,7 @@ m4_define({{_reportingoptions_}}, {{ (using the most recent applicable [market price](journal.html#market-prices), if any) `--auto` -: apply [automated posting rules](journal.html#auto-postings-transaction-modifiers) to modify transactions. +: apply [automated posting rules](journal.html#auto-postings) to modify transactions. `--forecast` : generate future transactions from [periodic transaction](journal.html#periodic-transactions) rules, for the next 6 months or till report end date. diff --git a/hledger-lib/hledger_journal.m4.md b/hledger-lib/hledger_journal.m4.md index 4ea866a96..06d9bcda9 100644 --- a/hledger-lib/hledger_journal.m4.md +++ b/hledger-lib/hledger_journal.m4.md @@ -796,7 +796,7 @@ so here is a table summarising the directives and their effects, with links to m [`include`]: #including-other-files [`P`]: #market-prices [`Y`]: #default-year -[`=`]: #auto-postings-transaction-modifiers +[`=`]: #auto-postings And some definitions: @@ -1424,33 +1424,35 @@ and -## Auto postings / transaction modifiers +## Auto postings -Transaction modifier rules, AKA auto posting rules, describe changes to be applied automatically to certain matched transactions. -Currently just one kind of change is possible - adding extra postings, which we call "automated postings" or just "auto postings". -These rules become active when you use the `--auto` flag. - -A transaction modifier rule looks much like a normal transaction -except the first line is an equals sign followed by a -[query](hledger.html#queries) that matches certain postings -(mnemonic: `=` suggests matching). -And each "posting" is actually a posting-generating rule: +"Automated postings" or "auto postings" are extra postings which get +added automatically to transactions which match certain queries, +defined by "auto posting rules", when you use the `--auto` flag. +An auto posting rule looks a bit like a transaction: ```journal = QUERY ACCOUNT AMOUNT - ACCOUNT [AMOUNT] ... + ACCOUNT [AMOUNT] ``` - -These posting-generating rules look like normal postings, except the amount can be: +except the first line is an equals sign (mnemonic: `=` suggests matching), +followed by a [query](hledger.html#queries) (which matches existing postings), +and each "posting" line describes a posting to be generated, +and the posting amounts 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. -- 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. -- 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. +- a number, eg `2`. The commodity symbol (if any) from the matched + posting will be added to this. +- 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. +- 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. -A query term containing spaces must be enclosed in single or double +Any query term containing spaces must be enclosed in single or double quotes, as on the command line. Eg, note the quotes around the second query term below: ```journal = expenses:groceries 'expenses:dining out' @@ -1505,7 +1507,7 @@ will also be used in the generated posting. ### Auto postings and transaction balancing / inferred amounts / balance assertions -Currently, transaction modifiers are applied / auto postings are added: +Currently, auto postings are added: - after [missing amounts are inferred, and transactions are checked for balancedness](#postings), - but before [balance assertions](#balance-assertions) are checked. @@ -1517,14 +1519,14 @@ background. ### Auto posting tags -Postings added by transaction modifiers will have some extra [tags](#tags-1): +Automated postings will have some extra [tags](#tags-1): - `generated-posting:= QUERY` - shows this was generated by an auto posting rule, and the query - `_generated-posting:= QUERY` - a hidden tag, which does not appear in hledger's output. This can be used to match postings generated "just now", rather than generated in the past and saved to the journal. -Also, any transaction that has been changed by transaction modifier rules will have these tags added: +Also, any transaction that has been changed by auto posting rules will have these tags added: - `modified:` - this transaction was modified - `_modified:` - a hidden tag not appearing in the comment; this transaction was modified "just now".