diff --git a/hledger-lib/defs.m4 b/hledger-lib/defs.m4 index 0daeed0d9..ce8828c81 100644 --- a/hledger-lib/defs.m4 +++ b/hledger-lib/defs.m4 @@ -4,4 +4,4 @@ m4_dnl Program version. Updated by make setversion. m4_define({{_version_}}, {{1.19.99}})m4_dnl m4_dnl m4_dnl Date to show in man pages. Updated by make setdate. -m4_define({{_monthyear_}}, {{September 2020}})m4_dnl +m4_define({{_monthyear_}}, {{October 2020}})m4_dnl diff --git a/hledger-lib/hledger_csv.5 b/hledger-lib/hledger_csv.5 index adef3d115..af405a992 100644 --- a/hledger-lib/hledger_csv.5 +++ b/hledger-lib/hledger_csv.5 @@ -1,6 +1,6 @@ .\"t -.TH "hledger_csv" "5" "September 2020" "hledger 1.19.99" "hledger User Manuals" +.TH "hledger_csv" "5" "October 2020" "hledger 1.19.99" "hledger User Manuals" diff --git a/hledger-lib/hledger_csv.txt b/hledger-lib/hledger_csv.txt index 835e4f8af..e527d5992 100644 --- a/hledger-lib/hledger_csv.txt +++ b/hledger-lib/hledger_csv.txt @@ -922,4 +922,4 @@ SEE ALSO -hledger 1.19.99 September 2020 hledger_csv(5) +hledger 1.19.99 October 2020 hledger_csv(5) diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index 5c88cce86..9406f389e 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -1,6 +1,6 @@ .\"t -.TH "hledger_journal" "5" "September 2020" "hledger 1.19.99" "hledger User Manuals" +.TH "hledger_journal" "5" "October 2020" "hledger 1.19.99" "hledger User Manuals" @@ -950,6 +950,8 @@ versions). Directives\[aq] behaviour and interactions can get a little bit complex, so here is a table summarising the directives and their effects, with links to more detailed docs. +Note part of this table is hidden when viewed in a web browser - scroll +it sideways to see more. .PP .TS tab(@); @@ -984,8 +986,7 @@ T}@T{ T}@T{ rewrite account names T}@T{ -following inline/included entries until end of current file or end -directive +following entries until end of current file or end directive T} T{ \f[C]apply account\f[R] @@ -995,8 +996,7 @@ T}@T{ T}@T{ prepend a common parent to account names T}@T{ -following inline/included entries until end of current file or end -directive +following entries until end of current file or end directive T} T{ \f[C]comment\f[R] @@ -1006,8 +1006,7 @@ T}@T{ T}@T{ ignore part of journal T}@T{ -following inline/included entries until end of current file or end -directive +following entries until end of current file or end directive T} T{ \f[C]commodity\f[R] @@ -1017,7 +1016,7 @@ T}@T{ T}@T{ declare a commodity and its number notation & display style T}@T{ -number notation: following entries in that commodity in all files; +number notation: following entries in that commodity in all files ; display style: amounts of that commodity in reports T} T{ @@ -1057,7 +1056,7 @@ T}@T{ T}@T{ declare a year for yearless dates T}@T{ -following inline/included entries until end of current file +following entries until end of current file T} T{ \f[C]=\f[R] diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index d57eef769..9ecc086f0 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -888,7 +888,8 @@ some differences between hledger versions). Directives' behaviour and interactions can get a little bit complex, so here is a table summarising the directives and their effects, with -links to more detailed docs. +links to more detailed docs. Note part of this table is hidden when +viewed in a web browser - scroll it sideways to see more. directiveend subdirectivespurpose can affect (as of directive 2018/06) @@ -896,25 +897,22 @@ directiveend subdirectivespurpose can affect (as of 'account' any document account names, all entries in text declare account types & all files, before display order or after -'alias' 'end rewrite account names following - aliases' inline/included - entries until end - of current file - or end directive -'apply 'end prepend a common parent to following -account' apply account names inline/included - account' entries until end - of current file - or end directive -'comment''end ignore part of journal following - comment' inline/included - entries until end - of current file - or end directive +'alias' 'end rewrite account names following entries + aliases' until end of + current file or + end directive +'apply 'end prepend a common parent to following entries +account' apply account names until end of + account' current file or + end directive +'comment''end ignore part of journal following entries + comment' until end of + current file or + end directive 'commodity' 'format'declare a commodity and its number notation: number notation & display following entries style in that commodity - in all files; + in all files ; display style: amounts of that commodity in @@ -940,10 +938,9 @@ account' apply account names inline/included a commodity commodity in reports, when -V is used -'Y' declare a year for yearless following - dates inline/included - entries until end - of current file +'Y' declare a year for yearless following entries + dates until end of + current file '=' declare an auto posting all entries in rule, adding postings to parent/current/child other transactions files (but not @@ -1924,64 +1921,64 @@ Node: Balance assignments and prices30866 Ref: #balance-assignments-and-prices31038 Node: Directives31262 Ref: #directives31421 -Node: Directives and multiple files37112 -Ref: #directives-and-multiple-files37295 -Node: Comment blocks37959 -Ref: #comment-blocks38142 -Node: Including other files38318 -Ref: #including-other-files38498 -Node: Default year39422 -Ref: #default-year39591 -Node: Declaring commodities39998 -Ref: #declaring-commodities40181 -Node: Default commodity41987 -Ref: #default-commodity42173 -Node: Declaring market prices43062 -Ref: #declaring-market-prices43257 -Node: Declaring accounts44114 -Ref: #declaring-accounts44300 -Node: Account comments45225 -Ref: #account-comments45388 -Node: Account subdirectives45812 -Ref: #account-subdirectives46007 -Node: Account types46320 -Ref: #account-types46504 -Node: Account display order49550 -Ref: #account-display-order49720 -Node: Rewriting accounts50871 -Ref: #rewriting-accounts51056 -Node: Basic aliases51813 -Ref: #basic-aliases51959 -Node: Regex aliases52663 -Ref: #regex-aliases52835 -Node: Combining aliases53554 -Ref: #combining-aliases53747 -Node: Aliases and multiple files55023 -Ref: #aliases-and-multiple-files55232 -Node: end aliases55811 -Ref: #end-aliases55968 -Node: Default parent account56069 -Ref: #default-parent-account56237 -Node: Periodic transactions57121 -Ref: #periodic-transactions57296 -Node: Periodic rule syntax59168 -Ref: #periodic-rule-syntax59374 -Node: Two spaces between period expression and description!60078 -Ref: #two-spaces-between-period-expression-and-description60397 -Node: Forecasting with periodic transactions61081 -Ref: #forecasting-with-periodic-transactions61386 -Node: Budgeting with periodic transactions63441 -Ref: #budgeting-with-periodic-transactions63680 -Node: Auto postings64089 -Ref: #auto-postings64229 -Node: Auto postings and multiple files66408 -Ref: #auto-postings-and-multiple-files66612 -Node: Auto postings and dates66821 -Ref: #auto-postings-and-dates67095 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions67270 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions67621 -Node: Auto posting tags67963 -Ref: #auto-posting-tags68178 +Node: Directives and multiple files36919 +Ref: #directives-and-multiple-files37102 +Node: Comment blocks37766 +Ref: #comment-blocks37949 +Node: Including other files38125 +Ref: #including-other-files38305 +Node: Default year39229 +Ref: #default-year39398 +Node: Declaring commodities39805 +Ref: #declaring-commodities39988 +Node: Default commodity41794 +Ref: #default-commodity41980 +Node: Declaring market prices42869 +Ref: #declaring-market-prices43064 +Node: Declaring accounts43921 +Ref: #declaring-accounts44107 +Node: Account comments45032 +Ref: #account-comments45195 +Node: Account subdirectives45619 +Ref: #account-subdirectives45814 +Node: Account types46127 +Ref: #account-types46311 +Node: Account display order49357 +Ref: #account-display-order49527 +Node: Rewriting accounts50678 +Ref: #rewriting-accounts50863 +Node: Basic aliases51620 +Ref: #basic-aliases51766 +Node: Regex aliases52470 +Ref: #regex-aliases52642 +Node: Combining aliases53361 +Ref: #combining-aliases53554 +Node: Aliases and multiple files54830 +Ref: #aliases-and-multiple-files55039 +Node: end aliases55618 +Ref: #end-aliases55775 +Node: Default parent account55876 +Ref: #default-parent-account56044 +Node: Periodic transactions56928 +Ref: #periodic-transactions57103 +Node: Periodic rule syntax58975 +Ref: #periodic-rule-syntax59181 +Node: Two spaces between period expression and description!59885 +Ref: #two-spaces-between-period-expression-and-description60204 +Node: Forecasting with periodic transactions60888 +Ref: #forecasting-with-periodic-transactions61193 +Node: Budgeting with periodic transactions63248 +Ref: #budgeting-with-periodic-transactions63487 +Node: Auto postings63896 +Ref: #auto-postings64036 +Node: Auto postings and multiple files66215 +Ref: #auto-postings-and-multiple-files66419 +Node: Auto postings and dates66628 +Ref: #auto-postings-and-dates66902 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions67077 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions67428 +Node: Auto posting tags67770 +Ref: #auto-posting-tags67985  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index 277de3398..322c2c751 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -682,34 +682,32 @@ FILE FORMAT Directives' behaviour and interactions can get a little bit complex, so here is a table summarising the directives and their effects, with - links to more detailed docs. + links to more detailed docs. Note part of this table is hidden when + viewed in a web browser - scroll it sideways to see more. - direc- end di- subdi- purpose can affect (as of + direc- end di- subdi- purpose can affect (as of tive rective rec- 2018/06) tives ------------------------------------------------------------------------------------ - account any document account names, de- all entries in all - text clare account types & dis- files, before or + account any document account names, de- all entries in all + text clare account types & dis- files, before or play order after - alias end rewrite account names following in- - aliases line/included en- - tries until end of - current file or end + alias end rewrite account names following entries + aliases until end of cur- + rent file or end directive - apply end apply prepend a common parent to following in- - account account account names line/included en- - tries until end of - current file or end + apply end apply prepend a common parent to following entries + account account account names until end of cur- + rent file or end directive - comment end com- ignore part of journal following in- - ment line/included en- - tries until end of - current file or end + comment end com- ignore part of journal following entries + ment until end of cur- + rent file or end directive commod- format declare a commodity and its number notation: ity number notation & display following entries style in that commodity - in all files; dis- + in all files ; dis- play style: amounts of that commodity in reports @@ -731,32 +729,30 @@ FILE FORMAT commodity commodity in re- ports, when -V is used + Y declare a year for yearless following entries + dates until end of cur- + rent file - - Y declare a year for yearless following in- - dates line/included en- - tries until end of - current file - = declare an auto posting all entries in par- - rule, adding postings to ent/current/child + = declare an auto posting all entries in par- + rule, adding postings to ent/current/child other transactions files (but not sib- ling files, see #1212) And some definitions: - subdi- optional indented directive line immediately following a parent + subdi- optional indented directive line immediately following a parent rec- directive tive number how to interpret numbers when parsing journal entries (the iden- - nota- tity of the decimal separator character). (Currently each com- + nota- tity of the decimal separator character). (Currently each com- tion modity can have its own notation, even in the same file.) - dis- how to display amounts of a commodity in reports (symbol side + dis- how to display amounts of a commodity in reports (symbol side play and spacing, digit groups, decimal separator, decimal places) style - direc- which entries and (when there are multiple files) which files + direc- which entries and (when there are multiple files) which files tive are affected by a directive scope @@ -765,35 +761,35 @@ FILE FORMAT ports). Some directives have multiple effects. Directives and multiple files - If you use multiple -f/--file options, or the include directive, - hledger will process multiple input files. But note that directives + If you use multiple -f/--file options, or the include directive, + hledger will process multiple input files. But note that directives which affect input (see above) typically last only until the end of the file in which they occur. This may seem inconvenient, but it's intentional; it makes reports sta- - ble and deterministic, independent of the order of input. Otherwise - you could see different numbers if you happened to write -f options in - a different order, or if you moved includes around while cleaning up + ble and deterministic, independent of the order of input. Otherwise + you could see different numbers if you happened to write -f options in + a different order, or if you moved includes around while cleaning up your files. - It can be surprising though; for example, it means that alias direc- + It can be surprising though; for example, it means that alias direc- tives do not affect parent or sibling files (see below). Comment blocks - A line containing just comment starts a commented region of the file, + A line containing just comment starts a commented region of the file, and a line containing just end comment (or the end of the current file) ends it. See also comments. Including other files - You can pull in the content of additional files by writing an include + You can pull in the content of additional files by writing an include directive, like this: include FILEPATH - Only journal files can include, and only journal, timeclock or timedot + Only journal files can include, and only journal, timeclock or timedot files can be included (not CSV files, currently). - If the file path does not begin with a slash, it is relative to the + If the file path does not begin with a slash, it is relative to the current file's folder. A tilde means home directory, eg: include ~/main.journal. @@ -802,17 +798,17 @@ FILE FORMAT *.journal. There is limited support for recursive wildcards: **/ (the slash is re- - quired) matches 0 or more subdirectories. It's not super convenient - since you have to avoid include cycles and including directories, but + quired) matches 0 or more subdirectories. It's not super convenient + since you have to avoid include cycles and including directories, but this can be done, eg: include */**/*.journal. The path may also be prefixed to force a specific file format, overrid- - ing the file extension (as described in hledger.1 -> Input files): in- + ing the file extension (as described in hledger.1 -> Input files): in- clude timedot:~/notes/2020*.md. 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 @@ -834,19 +830,19 @@ FILE FORMAT Declaring commodities The commodity directive has several functions: - 1. It declares commodities which may be used in the journal. This is + 1. It declares commodities which may be used in the journal. This is currently not enforced, but can serve as documentation. - 2. It declares what decimal mark character (period or comma) to expect - when parsing input - useful to disambiguate international number - formats in your data. (Without this, hledger will parse both 1,000 + 2. It declares what decimal mark character (period or comma) to expect + when parsing input - useful to disambiguate international number + formats in your data. (Without this, hledger will parse both 1,000 and 1.000 as 1). - 3. It declares the amount display style to use in output - decimal and + 3. It declares the amount display style to use in output - decimal and digit group marks, number of decimal places, symbol placement etc. - You are likely to run into one of the problems solved by commodity di- - rectives, sooner or later, so it's a good idea to just always use them + You are likely to run into one of the problems solved by commodity di- + rectives, sooner or later, so it's a good idea to just always use them to declare your commodities. A commodity directive is just the word commodity followed by an amount. @@ -859,8 +855,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 @@ -873,22 +869,22 @@ FILE FORMAT format INR 1,00,00,000.00 The quantity of the amount does not matter; only the format is signifi- - cant. The number must include a decimal mark: either a period or a + cant. The number must include a decimal mark: either a period or a comma, followed by 0 or more decimal digits. - Note hledger normally uses banker's rounding, so 0.5 displayed with + Note hledger normally uses banker's rounding, so 0.5 displayed with zero decimal digits is "0". (More at Amount display style.) Default commodity - The D directive sets a default commodity, to be used for amounts with- + The D directive sets a default commodity, to be used for amounts with- out a commodity symbol (ie, plain numbers). This commodity will be ap- plied to all subsequent commodity-less amounts, or until the next D di- rective. (Note, this is different from Ledger's D.) - For compatibility/historical reasons, D also acts like a commodity di- + For compatibility/historical reasons, D also acts like a commodity di- rective, setting the commodity's display style (for output) and decimal mark (for parsing input). As with commodity, the amount must always be - written with a decimal mark (period or comma). If both directives are + written with a decimal mark (period or comma). If both directives are used, commodity's style takes precedence. The syntax is D AMOUNT. Eg: @@ -902,9 +898,9 @@ FILE FORMAT b Declaring market prices - The P directive declares a market price, which is an exchange rate be- - tween two commodities on a certain date. (In Ledger, they are called - "historical prices".) These are often obtained from a stock exchange, + The P directive declares a market price, which is an exchange rate be- + tween two commodities on a certain date. (In Ledger, they are called + "historical prices".) These are often obtained from a stock exchange, cryptocurrency exchange, or the foreign exchange market. Here is the format: @@ -915,16 +911,16 @@ 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 EUR $1.35 P 2010/1/1 EUR $1.40 - The -V, -X and --value flags use these market prices to show amount + The -V, -X and --value flags use these market prices to show amount values in another commodity. See Valuation. Declaring accounts @@ -934,20 +930,20 @@ FILE FORMAT o They can document your intended chart of accounts, providing a refer- ence. - o They can store extra information about accounts (account numbers, + o They can store extra information about accounts (account numbers, notes, etc.) - o They can help hledger know your accounts' types (asset, liability, - equity, revenue, expense), useful for reports like balancesheet and + o They can help hledger know your accounts' types (asset, liability, + equity, revenue, expense), useful for reports like balancesheet and incomestatement. - o They control account display order in reports, allowing non-alpha- + o They control account display order in reports, allowing non-alpha- betic sorting (eg Revenues to appear above Expenses). - o They help with account name completion in the add command, hledger- + o They help with account name completion in the add command, hledger- iadd, hledger-web, ledger-mode etc. - The simplest form is just the word account followed by a hledger-style + The simplest form is just the word account followed by a hledger-style account name, eg: account assets:bank:checking @@ -955,7 +951,7 @@ FILE FORMAT Account comments Comments, beginning with a semicolon, can be added: - o on the same line, after two or more spaces (because ; is allowed in + o on the same line, after two or more spaces (because ; is allowed in account names) o on the next lines, indented @@ -969,7 +965,7 @@ FILE FORMAT Same-line comments are not supported by Ledger, or hledger <1.13. Account subdirectives - We also allow (and ignore) Ledger-style indented subdirectives, just + We also allow (and ignore) Ledger-style indented subdirectives, just for compatibility.: account assets:bank:checking @@ -988,21 +984,21 @@ FILE FORMAT Asset, Liability, Equity, Revenue, Expense. These account types are important for controlling which accounts appear - in the balancesheet, balancesheetequity, incomestatement reports (and + in the balancesheet, balancesheetequity, incomestatement reports (and probably for other things in future). - Additionally, we recognise the Cash type, which is also an Asset, and - which causes accounts to appear in the cashflow report. ("Cash" here - means liquid assets, eg bank balances but typically not investments or + Additionally, we recognise the Cash type, which is also an Asset, and + which causes accounts to appear in the cashflow report. ("Cash" here + means liquid assets, eg bank balances but typically not investments or receivables.) Declaring account types Generally, to make these reports work you should declare your top-level accounts and their types, using account directives with type: tags. - The tag's value should be one of: Asset, Liability, Equity, Revenue, - Expense, Cash, A, L, E, R, X, C (all case insensitive). The type is - inherited by all subaccounts except where they override it. Here's a + The tag's value should be one of: Asset, Liability, Equity, Revenue, + Expense, Cash, A, L, E, R, X, C (all case insensitive). The type is + inherited by all subaccounts except where they override it. Here's a complete example: account assets ; type: Asset @@ -1014,8 +1010,8 @@ FILE FORMAT account expenses ; type: Expense Auto-detected account types - If you happen to use common english top-level account names, you may - not need to declare account types, as they will be detected automati- + If you happen to use common english top-level account names, you may + not need to declare account types, as they will be detected automati- cally using the following rules: If name matches regular account type is: @@ -1028,7 +1024,7 @@ FILE FORMAT ^(income|revenue)s?(:|$) Revenue ^expenses?(:|$) Expense - If account type is Asset and name does not contain regu- account type + If account type is Asset and name does not contain regu- account type lar expression: is: -------------------------------------------------------------------------- (investment|receivable|:A/R|:fixed) Cash @@ -1038,9 +1034,9 @@ FILE FORMAT Interference from auto-detected account types If you assign any account type, it's a good idea to assign all of them, - to prevent any confusion from mixing declared and auto-detected types. - Although it's unlikely to happen in real life, here's an example: with - the following journal, balancesheetequity shows "liabilities" in both + to prevent any confusion from mixing declared and auto-detected types. + Although it's unlikely to happen in real life, here's an example: with + the following journal, balancesheetequity shows "liabilities" in both Liabilities and Equity sections. Declaring another account as type:Li- ability would fix it: @@ -1052,8 +1048,8 @@ FILE FORMAT equity -2 Old account type syntax - In some hledger journals you might instead see this old syntax (the - letters ALERX, separated from the account name by two or more spaces); + In some hledger journals you might instead see this old syntax (the + letters ALERX, separated from the account name by two or more spaces); this is deprecated and may be removed soon: account assets A @@ -1063,8 +1059,8 @@ FILE FORMAT account expenses X Account display order - Account directives also set the order in which accounts are displayed, - eg in reports, the hledger-ui accounts screen, and the hledger-web + Account directives also set the order in which accounts are displayed, + eg in reports, the hledger-ui accounts screen, and the hledger-web sidebar. By default accounts are listed in alphabetical order. But if you have these account directives in the journal: @@ -1086,20 +1082,20 @@ FILE FORMAT Undeclared accounts, if any, are displayed last, in alphabetical order. - Note that sorting is done at each level of the account tree (within - each group of sibling accounts under the same parent). And currently, + Note that sorting is done at each level of the account tree (within + each group of sibling accounts under the same parent). And currently, this directive: account other:zoo - would influence the position of zoo among other's subaccounts, but not + would influence the position of zoo among other's subaccounts, but not the position of other among the top-level accounts. This means: - o you will sometimes declare parent accounts (eg account other above) + o you will sometimes declare parent accounts (eg account other above) that you don't intend to post to, just to customize their display or- der - o sibling accounts stay together (you couldn't display x:y in between + o sibling accounts stay together (you couldn't display x:y in between a:b and a:c). Rewriting accounts @@ -1117,14 +1113,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 hledger- + do not affect account names being entered via hledger add or hledger- web. See also 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 @@ -1132,49 +1128,49 @@ 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 re- - place any occurrence of the old account name with the new one. Subac- + OLD and NEW are case sensitive full account names. hledger will re- + place any occurrence of the old account name with the new one. Subac- counts 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. Combining aliases - You can define as many aliases as you like, using journal directives + You can define as many aliases as you like, using journal directives and/or command line options. - Recursive aliases - where an account name is rewritten by one alias, - then by another alias, and so on - are allowed. Each alias sees the + Recursive aliases - where an account name is rewritten by one alias, + then by another alias, and so on - are allowed. Each alias sees the effect of previously applied aliases. - In such cases it can be important to understand which aliases will be - applied and in which order. For (each account name in) each journal + In such cases it can be important to understand which aliases will be + applied and in which order. For (each account name in) each journal entry, we apply: - 1. alias directives preceding the journal entry, most recently parsed + 1. alias directives preceding the journal entry, most recently parsed first (ie, reading upward from the journal entry, bottom to top) - 2. --alias options, in the order they appeared on the command line + 2. --alias options, in the order they appeared on the command line (left to right). In other words, for (an account name in) a given journal entry: @@ -1185,20 +1181,20 @@ FILE FORMAT o aliases defined after/below the entry do not affect it. - This gives nearby aliases precedence over distant ones, and helps pro- - vide semantic stability - aliases will keep working the same way inde- + This gives nearby aliases precedence over distant ones, and helps pro- + vide semantic stability - aliases will keep working the same way inde- pendent of which files are being read and in which order. - In case of trouble, adding --debug=6 to the command line will show + In case of trouble, adding --debug=6 to the command line will show which aliases are being applied when. Aliases and multiple files - As explained at Directives and multiple files, alias directives do not + As explained at Directives and multiple files, alias directives do not affect parent or sibling files. Eg in this command, hledger -f a.aliases -f b.journal - account aliases defined in a.aliases will not affect b.journal. In- + account aliases defined in a.aliases will not affect b.journal. In- cluding the aliases doesn't work either: include a.aliases @@ -1220,14 +1216,14 @@ FILE FORMAT include c.journal ; also affected end aliases - You can clear (forget) all currently defined aliases with the end + 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 ac- - counts within a section of the journal. Use the apply account and end + You can specify a parent account which will be prepended to all ac- + counts within a section of the journal. Use the apply account and end apply account directives like so: apply account home @@ -1244,7 +1240,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 @@ -1253,50 +1249,50 @@ 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 al- - low hledger to generate temporary future transactions to help with - forecasting, so you don't have to write out each one in the journal, - and it's easy to try out different forecasts. Secondly, they are also + Periodic transaction rules describe transactions that recur. They al- + low hledger to generate temporary future transactions to help with + forecasting, so you don't have to write out each one in the journal, + and it's easy to try out different forecasts. Secondly, they are also used to define the budgets shown in budget reports. - Periodic transactions can be a little tricky, so before you use them, + Periodic transactions can be a little tricky, so before you use them, read this whole section - or at least these tips: - 1. Two spaces accidentally added or omitted will cause you trouble - + 1. Two spaces accidentally added or omitted will cause you trouble - read about this below. - 2. For troubleshooting, show the generated transactions with hledger - print --forecast tag:generated or hledger register --forecast + 2. For troubleshooting, show the generated transactions with hledger + print --forecast tag:generated or hledger register --forecast tag:generated. - 3. Forecasted transactions will begin only after the last non-fore- + 3. Forecasted transactions will begin only after the last non-fore- casted transaction's date. - 4. Forecasted transactions will end 6 months from today, by default. + 4. Forecasted transactions will end 6 months from today, by default. See below for the exact start/end rules. - 5. period expressions can be tricky. Their documentation needs im- + 5. period expressions can be tricky. Their documentation needs im- provement, but is worth studying. - 6. Some period expressions with a repeating interval must begin on a - natural boundary of that interval. Eg in weekly from DATE, DATE - must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an + 6. Some period expressions with a repeating interval must begin on a + natural boundary of that interval. Eg in weekly from DATE, DATE + must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an error. 7. Other period expressions with an interval are automatically expanded - to cover a whole number of that interval. (This is done to improve + to cover a whole number of that interval. (This is done to improve reports, but it also affects periodic transactions. Yes, it's a bit - inconsistent with the above.) Eg: ~ every 10th day of month from - 2020/01, which is equivalent to ~ every 10th day of month from + inconsistent with the above.) Eg: ~ every 10th day of month from + 2020/01, which is equivalent to ~ every 10th day of month from 2020/01/01, will be adjusted to start on 2019/12/10. Periodic rule syntax @@ -1308,17 +1304,17 @@ FILE FORMAT 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 monthly from + 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. - Partial or relative dates (M/D, D, tomorrow, last week) in the period - expression can work (useful or not). They will be relative to today's - date, unless a Y default year directive is in effect, in which case + Partial or relative dates (M/D, D, tomorrow, last week) in the period + expression can work (useful or not). They will be relative to today's + date, unless a Y default year directive is in effect, in which case they will be relative to Y/1/1. Two spaces between period expression and description! - If the period expression is followed by a transaction description, + If the period expression is followed by a transaction description, these must be separated by two or more spaces. This helps hledger know where the period expression ends, so that descriptions can not acciden- tally alter their meaning, as in this example: @@ -1332,67 +1328,67 @@ FILE FORMAT So, - o Do write two spaces between your period expression and your transac- + o Do write two spaces between your period expression and your transac- tion description, if any. - o Don't accidentally write two spaces in the middle of your period ex- + o Don't accidentally write two spaces in the middle of your period ex- pression. Forecasting with periodic transactions - The --forecast flag activates any periodic transaction rules in the - journal. They will generate temporary recurring transactions, which - are not saved in the journal, but will appear in all reports (eg + The --forecast flag activates any periodic transaction rules in the + journal. They will generate temporary recurring transactions, which + are not saved in the journal, but will appear in all reports (eg print). This can be useful for estimating balances into the future, or - experimenting with different scenarios. Or, it can be used as a data + experimenting with different scenarios. Or, it can be used as a data entry aid: describe recurring transactions, and every so often copy the output of print --forecast into the journal. - These transactions will have an extra tag indicating which periodic + These transactions will have an extra tag indicating which periodic rule generated them: generated-transaction:~ PERIODICEXPR. And a simi- - lar, hidden tag (beginning with an underscore) which, because it's - never displayed by print, can be used to match transactions generated + lar, hidden tag (beginning with an underscore) which, because it's + never displayed by print, can be used to match transactions generated "just now": _generated-transaction:~ PERIODICEXPR. - Periodic transactions are generated within some forecast period. By + Periodic transactions are generated within some forecast period. By default, this 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 6 + o ends on the report end date if specified with -e/-p/date:, or 6 months (180 days) from today. - This means that periodic transactions will begin only after the latest - recorded transaction. And a recorded transaction dated in the future - can prevent generation of periodic transactions. (You can avoid that + This means that periodic transactions will begin only after the latest + recorded transaction. And a recorded transaction dated in the future + can prevent generation of periodic transactions. (You can avoid that by writing the future transaction as a one-time periodic rule instead - put tilde before the date, eg ~ YYYY-MM-DD ...). Or, you can set your own arbitrary "forecast period", which can overlap - recorded transactions, and need not be in the future, by providing an - option argument, like --forecast=PERIODEXPR. Note the equals sign is + recorded transactions, and need not be in the future, by providing an + option argument, like --forecast=PERIODEXPR. Note the equals sign is required, a space won't work. PERIODEXPR is a period expression, which - can specify the start date, end date, or both, like in a date: query. - (See also hledger.1 -> Report start & end date). Some examples: + can specify the start date, end date, or both, like in a date: query. + (See also hledger.1 -> Report start & end date). Some examples: --forecast=202001-202004, --forecast=jan-, --forecast=2020. 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. See also: Budgeting and Forecasting. Auto postings - "Automated postings" or "auto postings" are extra postings which get - added automatically to transactions which match certain queries, de- + "Automated postings" or "auto postings" are extra postings which get + added automatically to transactions which match certain queries, de- fined by "auto posting rules", when you use the --auto flag. An auto posting rule looks a bit like a transaction: @@ -1402,27 +1398,27 @@ FILE FORMAT ... ACCOUNT [AMOUNT] - except the first line is an equals sign (mnemonic: = suggests match- - ing), followed by a query (which matches existing postings), and each - "posting" line describes a posting to be generated, and the posting + except the first line is an equals sign (mnemonic: = suggests match- + ing), followed by a query (which matches existing postings), and each + "posting" line describes a posting to be generated, and the posting amounts 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. - 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 + 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: = expenses:groceries 'expenses:dining out' @@ -1461,24 +1457,24 @@ FILE FORMAT Auto postings and multiple files An auto posting rule can affect any transaction in the current file, or - in any parent file or child file. Note, currently it will not affect + in any parent file or child file. Note, currently it will not affect sibling files (when multiple -f/--file are used - see #1212). Auto postings and dates - A posting date (or secondary date) in the matched posting, or (taking - precedence) a posting date in the auto posting rule itself, will also + A posting date (or secondary date) in the matched posting, or (taking + precedence) a posting date in the auto posting rule itself, will also be used in the generated posting. Auto postings and transaction balancing / inferred amounts / balance asser- tions Currently, auto postings are added: - o after missing amounts are inferred, and transactions are checked for + o after missing amounts are inferred, and transactions are checked for balancedness, o but before balance assertions are checked. - Note this means that journal entries must be balanced both before and + 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 for background. @@ -1488,11 +1484,11 @@ FILE FORMAT o generated-posting:= QUERY - shows this was generated by an auto post- ing rule, and the query - o _generated-posting:= QUERY - a hidden tag, which does not appear in + o _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 auto posting rules will + Also, any transaction that has been changed by auto posting rules will have these tags added: o modified: - this transaction was modified @@ -1503,7 +1499,7 @@ FILE FORMAT 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) @@ -1517,7 +1513,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) @@ -1525,4 +1521,4 @@ SEE ALSO -hledger 1.19.99 September 2020 hledger_journal(5) +hledger 1.19.99 October 2020 hledger_journal(5) diff --git a/hledger-lib/hledger_timeclock.5 b/hledger-lib/hledger_timeclock.5 index 5ea1c1454..df21d06db 100644 --- a/hledger-lib/hledger_timeclock.5 +++ b/hledger-lib/hledger_timeclock.5 @@ -1,5 +1,5 @@ -.TH "hledger_timeclock" "5" "September 2020" "hledger 1.19.99" "hledger User Manuals" +.TH "hledger_timeclock" "5" "October 2020" "hledger 1.19.99" "hledger User Manuals" diff --git a/hledger-lib/hledger_timeclock.txt b/hledger-lib/hledger_timeclock.txt index f03eefc5f..ee440c6e0 100644 --- a/hledger-lib/hledger_timeclock.txt +++ b/hledger-lib/hledger_timeclock.txt @@ -78,4 +78,4 @@ SEE ALSO -hledger 1.19.99 September 2020 hledger_timeclock(5) +hledger 1.19.99 October 2020 hledger_timeclock(5) diff --git a/hledger-lib/hledger_timedot.5 b/hledger-lib/hledger_timedot.5 index d048123f7..33bf011d8 100644 --- a/hledger-lib/hledger_timedot.5 +++ b/hledger-lib/hledger_timedot.5 @@ -1,5 +1,5 @@ -.TH "hledger_timedot" "5" "September 2020" "hledger 1.19.99" "hledger User Manuals" +.TH "hledger_timedot" "5" "October 2020" "hledger 1.19.99" "hledger User Manuals" diff --git a/hledger-lib/hledger_timedot.txt b/hledger-lib/hledger_timedot.txt index 3939a5454..c82216696 100644 --- a/hledger-lib/hledger_timedot.txt +++ b/hledger-lib/hledger_timedot.txt @@ -161,4 +161,4 @@ SEE ALSO -hledger 1.19.99 September 2020 hledger_timedot(5) +hledger 1.19.99 October 2020 hledger_timedot(5) diff --git a/hledger-ui/defs.m4 b/hledger-ui/defs.m4 index 0daeed0d9..ce8828c81 100644 --- a/hledger-ui/defs.m4 +++ b/hledger-ui/defs.m4 @@ -4,4 +4,4 @@ m4_dnl Program version. Updated by make setversion. m4_define({{_version_}}, {{1.19.99}})m4_dnl m4_dnl m4_dnl Date to show in man pages. Updated by make setdate. -m4_define({{_monthyear_}}, {{September 2020}})m4_dnl +m4_define({{_monthyear_}}, {{October 2020}})m4_dnl diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index be7be927b..5ad356459 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -1,5 +1,5 @@ -.TH "hledger-ui" "1" "September 2020" "hledger-ui 1.19.99" "hledger User Manuals" +.TH "hledger-ui" "1" "October 2020" "hledger-ui 1.19.99" "hledger User Manuals" diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index 8a64ed77d..95102d031 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -456,4 +456,4 @@ SEE ALSO -hledger-ui 1.19.99 September 2020 hledger-ui(1) +hledger-ui 1.19.99 October 2020 hledger-ui(1) diff --git a/hledger-web/defs.m4 b/hledger-web/defs.m4 index 0daeed0d9..ce8828c81 100644 --- a/hledger-web/defs.m4 +++ b/hledger-web/defs.m4 @@ -4,4 +4,4 @@ m4_dnl Program version. Updated by make setversion. m4_define({{_version_}}, {{1.19.99}})m4_dnl m4_dnl m4_dnl Date to show in man pages. Updated by make setdate. -m4_define({{_monthyear_}}, {{September 2020}})m4_dnl +m4_define({{_monthyear_}}, {{October 2020}})m4_dnl diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index ee84ad40c..a45819d76 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -1,5 +1,5 @@ -.TH "hledger-web" "1" "September 2020" "hledger-web 1.19.99" "hledger User Manuals" +.TH "hledger-web" "1" "October 2020" "hledger-web 1.19.99" "hledger User Manuals" diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index 8c36a1396..7f646873d 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -546,4 +546,4 @@ SEE ALSO -hledger-web 1.19.99 September 2020 hledger-web(1) +hledger-web 1.19.99 October 2020 hledger-web(1) diff --git a/hledger/defs.m4 b/hledger/defs.m4 index 0daeed0d9..ce8828c81 100644 --- a/hledger/defs.m4 +++ b/hledger/defs.m4 @@ -4,4 +4,4 @@ m4_dnl Program version. Updated by make setversion. m4_define({{_version_}}, {{1.19.99}})m4_dnl m4_dnl m4_dnl Date to show in man pages. Updated by make setdate. -m4_define({{_monthyear_}}, {{September 2020}})m4_dnl +m4_define({{_monthyear_}}, {{October 2020}})m4_dnl diff --git a/hledger/hledger.1 b/hledger/hledger.1 index b72f08323..0a4f25090 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "hledger" "1" "September 2020" "hledger 1.19.99" "hledger User Manuals" +.TH "hledger" "1" "October 2020" "hledger 1.19.99" "hledger User Manuals" diff --git a/hledger/hledger.txt b/hledger/hledger.txt index c9be99f23..10b72c89b 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -3460,4 +3460,4 @@ SEE ALSO -hledger 1.19.99 September 2020 hledger(1) +hledger 1.19.99 October 2020 hledger(1)