diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index 30035e559..89db873a7 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -1374,7 +1374,7 @@ Secondly, they also can be used to define budget goals (with .PP A periodic transaction rule looks like a normal journal entry, with the date replaced by a tilde (\f[C]~\f[]) followed by a period expression -(mnemonic: \f[C]~\f[] looks like a repeating sine wave): +(mnemonic: \f[C]~\f[] looks like a recurring sine wave.): .IP .nf \f[C] @@ -1456,15 +1456,18 @@ Goals and actual performance can then be compared in budget reports. .PP For more details, see: balance: Budget report and Cookbook: Budgeting and Forecasting. -.SS Automated postings .PP -Automated posting rules describe extra postings that should be added to -certain transactions at report time, when the \f[C]\-\-auto\f[] flag is -used. + ## Transaction Modifiers .PP -An automated posting rule looks like a normal journal entry, except the -first line is an equal sign (\f[C]=\f[]) followed by a query (mnemonic: -\f[C]=\f[] looks like posting lines): +Transaction modifier rules describe changes that should be applied +automatically to certain transactions. +Currently, this means adding extra postings (also known as +\[lq]automated postings\[rq]). +Transaction modifiers are enabled by the \f[C]\-\-auto\f[] flag. +.PP +A transaction modifier rule looks a bit like a normal journal entry, +except the first line is an equal sign (\f[C]=\f[]) followed by a query +(mnemonic: \f[C]=\f[] suggests matching something.): .IP .nf \f[C] diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index e90374492..89cb42788 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -82,7 +82,6 @@ File: hledger_journal.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, Prev: To * Tags:: * Directives:: * Periodic transactions:: -* Automated postings::  File: hledger_journal.info, Node: Transactions, Next: Postings, Up: FILE FORMAT @@ -1197,7 +1196,7 @@ If account aliases are present, they are applied after the default parent account.  -File: hledger_journal.info, Node: Periodic transactions, Next: Automated postings, Prev: Directives, Up: FILE FORMAT +File: hledger_journal.info, Node: Periodic transactions, Prev: Directives, Up: FILE FORMAT 1.15 Periodic transactions ========================== @@ -1209,7 +1208,7 @@ they also can be used to define budget goals (with '--budget'). A periodic transaction rule looks like a normal journal entry, with the date replaced by a tilde ('~') followed by a period expression -(mnemonic: '~' looks like a repeating sine wave): +(mnemonic: '~' looks like a recurring sine wave.): ~ monthly expenses:rent $2000 @@ -1293,18 +1292,16 @@ compared in budget reports. For more details, see: balance: Budget report and Cookbook: Budgeting and Forecasting. - -File: hledger_journal.info, Node: Automated postings, Prev: Periodic transactions, Up: FILE FORMAT + ## Transaction Modifiers -1.16 Automated postings -======================= + 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. -Automated posting rules describe extra postings that should be added to -certain transactions at report time, when the '--auto' flag is used. - - An automated posting rule looks like a normal journal entry, except -the first line is an equal sign ('=') followed by a query (mnemonic: '=' -looks like posting lines): + A transaction modifier rule looks a bit like a normal journal entry, +except the first line is an equal sign ('=') followed by a query +(mnemonic: '=' suggests matching something.): = expenses:gifts budget:gifts *-1 @@ -1367,89 +1364,87 @@ Tag Table: Node: Top76 Node: FILE FORMAT2378 Ref: #file-format2502 -Node: Transactions2786 -Ref: #transactions2907 -Node: Postings3591 -Ref: #postings3718 -Node: Dates4713 -Ref: #dates4828 -Node: Simple dates4893 -Ref: #simple-dates5019 -Node: Secondary dates5385 -Ref: #secondary-dates5539 -Node: Posting dates7102 -Ref: #posting-dates7231 -Node: Status8605 -Ref: #status8725 -Node: Description10433 -Ref: #description10571 -Node: Payee and note10890 -Ref: #payee-and-note11004 -Node: Account names11246 -Ref: #account-names11389 -Node: Amounts11876 -Ref: #amounts12012 -Node: Virtual Postings15029 -Ref: #virtual-postings15188 -Node: Balance Assertions16408 -Ref: #balance-assertions16583 -Node: Assertions and ordering17479 -Ref: #assertions-and-ordering17665 -Node: Assertions and included files18365 -Ref: #assertions-and-included-files18606 -Node: Assertions and multiple -f options18939 -Ref: #assertions-and-multiple--f-options19193 -Node: Assertions and commodities19325 -Ref: #assertions-and-commodities19560 -Node: Assertions and subaccounts20256 -Ref: #assertions-and-subaccounts20488 -Node: Assertions and virtual postings21009 -Ref: #assertions-and-virtual-postings21216 -Node: Balance Assignments21358 -Ref: #balance-assignments21539 -Node: Transaction prices22659 -Ref: #transaction-prices22828 -Node: Comments25096 -Ref: #comments25230 -Node: Tags26400 -Ref: #tags26518 -Node: Directives27920 -Ref: #directives28063 -Node: Comment blocks33919 -Ref: #comment-blocks34064 -Node: Including other files34240 -Ref: #including-other-files34420 -Node: Default year34809 -Ref: #default-year34978 -Node: Declaring commodities35401 -Ref: #declaring-commodities35584 -Node: Default commodity36811 -Ref: #default-commodity36987 -Node: Market prices37623 -Ref: #market-prices37788 -Node: Declaring accounts38629 -Ref: #declaring-accounts38805 -Node: Rewriting accounts40476 -Ref: #rewriting-accounts40661 -Node: Basic aliases41395 -Ref: #basic-aliases41541 -Node: Regex aliases42245 -Ref: #regex-aliases42416 -Node: Multiple aliases43134 -Ref: #multiple-aliases43309 -Node: end aliases43807 -Ref: #end-aliases43954 -Node: Default parent account44055 -Ref: #default-parent-account44221 -Node: Periodic transactions45105 -Ref: #periodic-transactions45284 -Node: Forecasting with periodic transactions46494 -Ref: #forecasting-with-periodic-transactions46737 -Node: Budgeting with periodic transactions48424 -Ref: #budgeting-with-periodic-transactions48663 -Node: Automated postings49122 -Ref: #automated-postings49276 -Node: EDITOR SUPPORT50415 -Ref: #editor-support50533 +Node: Transactions2763 +Ref: #transactions2884 +Node: Postings3568 +Ref: #postings3695 +Node: Dates4690 +Ref: #dates4805 +Node: Simple dates4870 +Ref: #simple-dates4996 +Node: Secondary dates5362 +Ref: #secondary-dates5516 +Node: Posting dates7079 +Ref: #posting-dates7208 +Node: Status8582 +Ref: #status8702 +Node: Description10410 +Ref: #description10548 +Node: Payee and note10867 +Ref: #payee-and-note10981 +Node: Account names11223 +Ref: #account-names11366 +Node: Amounts11853 +Ref: #amounts11989 +Node: Virtual Postings15006 +Ref: #virtual-postings15165 +Node: Balance Assertions16385 +Ref: #balance-assertions16560 +Node: Assertions and ordering17456 +Ref: #assertions-and-ordering17642 +Node: Assertions and included files18342 +Ref: #assertions-and-included-files18583 +Node: Assertions and multiple -f options18916 +Ref: #assertions-and-multiple--f-options19170 +Node: Assertions and commodities19302 +Ref: #assertions-and-commodities19537 +Node: Assertions and subaccounts20233 +Ref: #assertions-and-subaccounts20465 +Node: Assertions and virtual postings20986 +Ref: #assertions-and-virtual-postings21193 +Node: Balance Assignments21335 +Ref: #balance-assignments21516 +Node: Transaction prices22636 +Ref: #transaction-prices22805 +Node: Comments25073 +Ref: #comments25207 +Node: Tags26377 +Ref: #tags26495 +Node: Directives27897 +Ref: #directives28040 +Node: Comment blocks33896 +Ref: #comment-blocks34041 +Node: Including other files34217 +Ref: #including-other-files34397 +Node: Default year34805 +Ref: #default-year34974 +Node: Declaring commodities35397 +Ref: #declaring-commodities35580 +Node: Default commodity36807 +Ref: #default-commodity36983 +Node: Market prices37619 +Ref: #market-prices37784 +Node: Declaring accounts38625 +Ref: #declaring-accounts38801 +Node: Rewriting accounts40472 +Ref: #rewriting-accounts40657 +Node: Basic aliases41391 +Ref: #basic-aliases41537 +Node: Regex aliases42241 +Ref: #regex-aliases42412 +Node: Multiple aliases43130 +Ref: #multiple-aliases43305 +Node: end aliases43803 +Ref: #end-aliases43950 +Node: Default parent account44051 +Ref: #default-parent-account44217 +Node: Periodic transactions45101 +Ref: #periodic-transactions45253 +Node: Forecasting with periodic transactions46464 +Ref: #forecasting-with-periodic-transactions46707 +Node: Budgeting with periodic transactions48394 +Ref: #budgeting-with-periodic-transactions48633 +Node: EDITOR SUPPORT50380 +Ref: #editor-support50498  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index 74c1c34e3..52446824e 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -708,12 +708,12 @@ FILE FORMAT file. The include file path may contain common glob patterns (e.g. *). - The include directive can only be used in journal files. It can + The include directive can only be used in journal files. It can include journal, timeclock or timedot files, but not CSV files. Default year - You can set a default year to be used for subsequent dates which don't - specify a year. This is a line beginning with Y followed by the year. + You can set a default year to be used for subsequent dates which don't + specify a year. This is a line beginning with Y followed by the year. Eg: Y2009 ; set default year to 2009 @@ -733,8 +733,8 @@ FILE FORMAT assets Declaring commodities - The commodity directive declares commodities which may be used in the - journal (though currently we do not enforce this). It may be written + The commodity directive declares commodities which may be used in the + journal (though currently we do not enforce this). It may be written on a single line, like this: ; commodity EXAMPLEAMOUNT @@ -744,8 +744,8 @@ FILE FORMAT ; separating thousands with comma. commodity 1,000.0000 AAAA - or on multiple lines, using the "format" subdirective. In this case - the commodity symbol appears twice and should be the same in both + or on multiple lines, using the "format" subdirective. In this case + the commodity symbol appears twice and should be the same in both places: ; commodity SYMBOL @@ -757,19 +757,19 @@ FILE FORMAT commodity INR format INR 9,99,99,999.00 - Commodity directives have a second purpose: they define the standard + Commodity directives have a second purpose: they define the standard display format for amounts in the commodity. Normally the display for- - mat is inferred from journal entries, but this can be unpredictable; - declaring it with a commodity directive overrides this and removes - ambiguity. Towards this end, amounts in commodity directives must - always be written with a decimal point (a period or comma, followed by + mat is inferred from journal entries, but this can be unpredictable; + declaring it with a commodity directive overrides this and removes + ambiguity. Towards this end, amounts in commodity directives must + always be written with a decimal point (a period or comma, followed by 0 or more decimal digits). Default commodity - The D directive sets a default commodity (and display format), to be + The D directive sets a default commodity (and display format), to be used for amounts without a commodity symbol (ie, plain numbers). (Note - this differs from Ledger's default commodity directive.) The commodity - and display format will be applied to all subsequent commodity-less + this differs from Ledger's default commodity directive.) The commodity + and display format will be applied to all subsequent commodity-less amounts, or until the next D directive. # commodity-less amounts should be treated as dollars @@ -784,9 +784,9 @@ FILE FORMAT a decimal point. Market prices - The P directive declares a market price, which is an exchange rate + The P directive declares a market price, which is an exchange rate between two commodities on a certain date. (In Ledger, they are called - "historical prices".) These are often obtained from a stock exchange, + "historical prices".) These are often obtained from a stock exchange, cryptocurrency exchange, or the foreign exchange market. Here is the format: @@ -797,25 +797,25 @@ FILE FORMAT o COMMODITYA is the symbol of the commodity being priced - o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com- + o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com- modity, giving the price in commodity B of one unit of commodity A. - These two market price directives say that one euro was worth 1.35 US + These two market price directives say that one euro was worth 1.35 US dollars during 2009, and $1.40 from 2010 onward: P 2009/1/1 $1.35 P 2010/1/1 $1.40 - The -V/--value flag can be used to convert reported amounts to another + The -V/--value flag can be used to convert reported amounts to another commodity using these prices. Declaring accounts - The account directive predeclares account names. The simplest form is + The account directive predeclares account names. The simplest form is account ACCTNAME, eg: account assets:bank:checking - Currently this mainly helps with account name autocompletion in eg + Currently this mainly helps with account name autocompletion in eg hledger add, hledger-iadd, hledger-web, and ledger-mode. In future it will also help detect misspelled accounts. @@ -827,10 +827,10 @@ FILE FORMAT account revenues 4000 account expenses 6000 - This affects how accounts are sorted in account and balance reports: - accounts with codes are listed before accounts without codes, and in + This affects how accounts are sorted in account and balance reports: + accounts with codes are listed before accounts without codes, and in increasing code order (instead of listing all accounts alphabetically). - Warning, this feature is incomplete; account codes do not yet affect + Warning, this feature is incomplete; account codes do not yet affect sort order in o the accounts command @@ -842,9 +842,9 @@ FILE FORMAT o hledger-web's sidebar - Account codes should be all numeric digits, unique, and separated from - the account name by at least two spaces (since account names may con- - tain single spaces). By convention, often the first digit indicates + Account codes should be all numeric digits, unique, and separated from + the account name by at least two spaces (since account names may con- + tain single spaces). By convention, often the first digit indicates the type of account, as in this numbering scheme and the example above. In future, we might use this to recognize account types. @@ -873,14 +873,14 @@ FILE FORMAT o customising reports Account aliases also rewrite account names in account directives. They - do not affect account names being entered via hledger add or + do not affect account names being entered via hledger add or hledger-web. See also Cookbook: Rewrite account names. Basic aliases - To set an account alias, use the alias directive in your journal file. - This affects all subsequent journal entries in the current file or its + To set an account alias, use the alias directive in your journal file. + This affects all subsequent journal entries in the current file or its included files. The spaces around the = are optional: alias OLD = NEW @@ -888,54 +888,54 @@ FILE FORMAT Or, you can use the --alias 'OLD=NEW' option on the command line. This affects all entries. It's useful for trying out aliases interactively. - OLD and NEW are case sensitive full account names. hledger will - replace any occurrence of the old account name with the new one. Sub- + OLD and NEW are case sensitive full account names. hledger will + replace any occurrence of the old account name with the new one. Sub- accounts are also affected. Eg: alias checking = assets:bank:wells fargo:checking # rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" Regex aliases - There is also a more powerful variant that uses a regular expression, + There is also a more powerful variant that uses a regular expression, indicated by the forward slashes: alias /REGEX/ = REPLACEMENT or --alias '/REGEX/=REPLACEMENT'. - REGEX is a case-insensitive regular expression. Anywhere it matches - inside an account name, the matched part will be replaced by REPLACE- - MENT. If REGEX contains parenthesised match groups, these can be ref- + REGEX is a case-insensitive regular expression. Anywhere it matches + inside an account name, the matched part will be replaced by REPLACE- + MENT. If REGEX contains parenthesised match groups, these can be ref- erenced by the usual numeric backreferences in REPLACEMENT. Eg: alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 # rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" - Also note that REPLACEMENT continues to the end of line (or on command - line, to end of option argument), so it can contain trailing white- + Also note that REPLACEMENT continues to the end of line (or on command + line, to end of option argument), so it can contain trailing white- space. Multiple aliases - You can define as many aliases as you like using directives or com- - mand-line options. Aliases are recursive - each alias sees the result - of applying previous ones. (This is different from Ledger, where + You can define as many aliases as you like using directives or com- + mand-line options. Aliases are recursive - each alias sees the result + of applying previous ones. (This is different from Ledger, where aliases are non-recursive by default). Aliases are applied in the fol- lowing order: - 1. alias directives, most recently seen first (recent directives take + 1. alias directives, most recently seen first (recent directives take precedence over earlier ones; directives not yet seen are ignored) 2. alias options, in the order they appear on the command line end aliases - You can clear (forget) all currently defined aliases with the + You can clear (forget) all currently defined aliases with the end aliases directive: end aliases Default parent account - You can specify a parent account which will be prepended to all - accounts within a section of the journal. Use the apply account and + You can specify a parent account which will be prepended to all + accounts within a section of the journal. Use the apply account and end apply account directives like so: apply account home @@ -952,7 +952,7 @@ FILE FORMAT home:food $10 home:cash $-10 - If end apply account is omitted, the effect lasts to the end of the + If end apply account is omitted, the effect lasts to the end of the file. Included files are also affected, eg: apply account business @@ -961,30 +961,30 @@ FILE FORMAT apply account personal include personal.journal - Prior to hledger 1.0, legacy account and end spellings were also sup- + Prior to hledger 1.0, legacy account and end spellings were also sup- ported. - A default parent account also affects account directives. It does not - affect account names being entered via hledger add or hledger-web. If - account aliases are present, they are applied after the default parent + A default parent account also affects account directives. It does not + affect account names being entered via hledger add or hledger-web. If + account aliases are present, they are applied after the default parent account. Periodic transactions - Periodic transaction rules describe transactions that recur. They + Periodic transaction rules describe transactions that recur. They allow you to generate future transactions for forecasting, without hav- - ing to write them out explicitly in the journal (with --forecast). + ing to write them out explicitly in the journal (with --forecast). Secondly, they also can be used to define budget goals (with --budget). A periodic transaction rule looks like a normal journal entry, with the date replaced by a tilde (~) followed by a period expression (mnemonic: - ~ looks like a repeating sine wave): + ~ looks like a recurring sine wave.): ~ monthly expenses:rent $2000 assets:bank:checking - There is an additional constraint on the period expression: the start - date must fall on a natural boundary of the interval. Eg + There is an additional constraint on the period expression: the start + date must fall on a natural boundary of the interval. Eg monthly from 2018/1/1 is valid, but monthly from 2018/1/15 is not. If you write a transaction description or same-line comment, it must be @@ -998,74 +998,77 @@ FILE FORMAT income:acme inc Forecasting with periodic transactions - With the --forecast flag, each periodic transaction rule generates + With the --forecast flag, each periodic transaction rule generates future transactions recurring at the specified interval. These are not - saved in the journal, but appear in all reports. They will look like - normal transactions, but with an extra tag named recur, whose value is + saved in the journal, but appear in all reports. They will look like + normal transactions, but with an extra tag named recur, whose value is the generating period expression. - Forecast transactions start on the first occurrence, and end on the - last occurrence, of their interval within the forecast period. The + Forecast transactions start on the first occurrence, and end on the + last occurrence, of their interval within the forecast period. The forecast period: o begins on the later of o the report start date if specified with -b/-p/date: - o the day after the latest normal (non-periodic) transaction in the + o the day after the latest normal (non-periodic) transaction in the journal, or today if there are no normal transactions. - o ends on the report end date if specified with -e/-p/date:, or 180 + o ends on the report end date if specified with -e/-p/date:, or 180 days from today. - where "today" means the current date at report time. The "later of" - rule ensures that forecast transactions do not overlap normal transac- + where "today" means the current date at report time. The "later of" + rule ensures that forecast transactions do not overlap normal transac- tions in time; they will begin only after normal transactions end. - Forecasting can be useful for estimating balances into the future, and - experimenting with different scenarios. Note the start date logic + Forecasting can be useful for estimating balances into the future, and + experimenting with different scenarios. Note the start date logic means that forecasted transactions are automatically replaced by normal transactions as you add those. Forecasting can also help with data entry: describe most of your trans- - actions with periodic rules, and every so often copy the output of + actions with periodic rules, and every so often copy the output of print --forecast to the journal. You can generate one-time transactions too: just write a period expres- - sion specifying a date with no report interval. (You could also write - a normal transaction with a future date, but remember this disables + sion specifying a date with no report interval. (You could also write + a normal transaction with a future date, but remember this disables forecast transactions on previous dates.) Budgeting with periodic transactions - With the --budget flag, currently supported by the balance command, - each periodic transaction rule declares recurring budget goals for the - specified accounts. Eg the first example above declares a goal of - spending $2000 on rent (and also, a goal of depositing $2000 into - checking) every month. Goals and actual performance can then be com- + With the --budget flag, currently supported by the balance command, + each periodic transaction rule declares recurring budget goals for the + specified accounts. Eg the first example above declares a goal of + spending $2000 on rent (and also, a goal of depositing $2000 into + checking) every month. Goals and actual performance can then be com- pared in budget reports. - For more details, see: balance: Budget report and Cookbook: Budgeting + For more details, see: balance: Budget report and Cookbook: Budgeting and Forecasting. - Automated postings - Automated posting rules describe extra postings that should be added to - certain transactions at report time, when the --auto flag is used. + ## Transaction Modifiers - An automated posting rule looks like a normal journal entry, except the - first line is an equal sign (=) followed by a query (mnemonic: = looks - like posting lines): + 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 a bit like a normal journal entry, + except the first line is an equal sign (=) followed by a query + (mnemonic: = suggests matching something.): = expenses:gifts budget:gifts *-1 assets:budget *1 - The posting amounts can be of the form *N, which means "the amount of - the matched transaction's first posting, multiplied by N". They can + The posting amounts can be of the form *N, which means "the amount of + the matched transaction's first posting, multiplied by N". They can also be ordinary fixed amounts. Fixed amounts with no commodity symbol - will be given the same commodity as the matched transaction's first + will be given the same commodity as the matched transaction's first posting. - This example adds a corresponding (unbalanced) budget posting to every + This example adds a corresponding (unbalanced) budget posting to every transaction involving the expenses:gifts account: = expenses:gifts @@ -1081,16 +1084,16 @@ FILE FORMAT (budget:gifts) $-20 assets - Like postings recorded by hand, automated postings participate in + Like postings recorded by hand, automated postings participate in transaction balancing, missing amount inference and balance assertions. 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: @@ -1109,7 +1112,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) @@ -1123,7 +1126,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)