From 98d0cc9c1775ce10f018a1bd73b6888e14f8242f Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 8 Feb 2020 11:56:03 -0800 Subject: [PATCH] ;doc: regen manuals [ci skip] --- hledger-lib/hledger_journal.5 | 4 +- hledger-lib/hledger_journal.info | 123 ++++++----- hledger-lib/hledger_journal.txt | 314 +++++++++++++-------------- hledger/hledger.1 | 91 ++++---- hledger/hledger.info | 358 ++++++++++++++++--------------- hledger/hledger.txt | 186 +++++++--------- 6 files changed, 544 insertions(+), 532 deletions(-) diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index f786297c7..ea1c571b9 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -239,7 +239,7 @@ Here\[aq]s one suggestion: .PP .TS tab(@); -lw(9.9n) lw(60.1n). +lw(9.7n) lw(60.3n). T{ status T}@T{ @@ -1033,7 +1033,7 @@ And some definitions: .PP .TS tab(@); -lw(8.9n) lw(61.1n). +lw(6.0n) lw(64.0n). T{ subdirective T}@T{ diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index b494dca6e..ea5e891f1 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -913,16 +913,15 @@ account' apply account names inline/included And some definitions: -subdirectiveoptional indented directive line immediately following a - parent directive -number how to interpret numbers when parsing journal entries (the -notation identity of the decimal separator character). (Currently - each commodity can have its own notation, even in the same - file.) -display how to display amounts of a commodity in reports (symbol side -style and spacing, digit groups, decimal separator, decimal places) -directive which entries and (when there are multiple files) which files -scope are affected by a directive +subdirectiveoptional indented directive line immediately following a parent + directive +number how to interpret numbers when parsing journal entries (the +notationidentity of the decimal separator character). (Currently each + commodity can have its own notation, even in the same file.) +displayhow to display amounts of a commodity in reports (symbol side +style and spacing, digit groups, decimal separator, decimal places) +directivewhich entries and (when there are multiple files) which files +scope are affected by a directive As you can see, directives vary in which journal entries and files they affect, and whether they are focussed on input (parsing) or output @@ -1789,58 +1788,58 @@ Node: Balance assignments and prices29327 Ref: #balance-assignments-and-prices29499 Node: Directives29723 Ref: #directives29882 -Node: Comment blocks35561 -Ref: #comment-blocks35706 -Node: Including other files35882 -Ref: #including-other-files36062 -Node: Default year36470 -Ref: #default-year36639 -Node: Declaring commodities37046 -Ref: #declaring-commodities37229 -Node: Default commodity38890 -Ref: #default-commodity39066 -Node: Market prices39700 -Ref: #market-prices39865 -Node: Declaring accounts40706 -Ref: #declaring-accounts40882 -Node: Account comments41807 -Ref: #account-comments41970 -Node: Account subdirectives42394 -Ref: #account-subdirectives42589 -Node: Account types42902 -Ref: #account-types43086 -Node: Account display order44728 -Ref: #account-display-order44898 -Node: Rewriting accounts46049 -Ref: #rewriting-accounts46234 -Node: Basic aliases46960 -Ref: #basic-aliases47106 -Node: Regex aliases47810 -Ref: #regex-aliases47982 -Node: Combining aliases48700 -Ref: #combining-aliases48878 -Node: end aliases50154 -Ref: #end-aliases50302 -Node: Default parent account50403 -Ref: #default-parent-account50569 -Node: Periodic transactions51453 -Ref: #periodic-transactions51652 -Node: Periodic rule syntax53524 -Ref: #periodic-rule-syntax53730 -Node: Two spaces between period expression and description!54434 -Ref: #two-spaces-between-period-expression-and-description54753 -Node: Forecasting with periodic transactions55437 -Ref: #forecasting-with-periodic-transactions55742 -Node: Budgeting with periodic transactions57768 -Ref: #budgeting-with-periodic-transactions58007 -Node: Auto postings / transaction modifiers58456 -Ref: #auto-postings-transaction-modifiers58668 -Node: Auto postings and dates61153 -Ref: #auto-postings-and-dates61410 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions61585 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61960 -Node: Auto posting tags62338 -Ref: #auto-posting-tags62577 +Node: Comment blocks35530 +Ref: #comment-blocks35675 +Node: Including other files35851 +Ref: #including-other-files36031 +Node: Default year36439 +Ref: #default-year36608 +Node: Declaring commodities37015 +Ref: #declaring-commodities37198 +Node: Default commodity38859 +Ref: #default-commodity39035 +Node: Market prices39669 +Ref: #market-prices39834 +Node: Declaring accounts40675 +Ref: #declaring-accounts40851 +Node: Account comments41776 +Ref: #account-comments41939 +Node: Account subdirectives42363 +Ref: #account-subdirectives42558 +Node: Account types42871 +Ref: #account-types43055 +Node: Account display order44697 +Ref: #account-display-order44867 +Node: Rewriting accounts46018 +Ref: #rewriting-accounts46203 +Node: Basic aliases46929 +Ref: #basic-aliases47075 +Node: Regex aliases47779 +Ref: #regex-aliases47951 +Node: Combining aliases48669 +Ref: #combining-aliases48847 +Node: end aliases50123 +Ref: #end-aliases50271 +Node: Default parent account50372 +Ref: #default-parent-account50538 +Node: Periodic transactions51422 +Ref: #periodic-transactions51621 +Node: Periodic rule syntax53493 +Ref: #periodic-rule-syntax53699 +Node: Two spaces between period expression and description!54403 +Ref: #two-spaces-between-period-expression-and-description54722 +Node: Forecasting with periodic transactions55406 +Ref: #forecasting-with-periodic-transactions55711 +Node: Budgeting with periodic transactions57737 +Ref: #budgeting-with-periodic-transactions57976 +Node: Auto postings / transaction modifiers58425 +Ref: #auto-postings-transaction-modifiers58637 +Node: Auto postings and dates61122 +Ref: #auto-postings-and-dates61379 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions61554 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61929 +Node: Auto posting tags62307 +Ref: #auto-posting-tags62546  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index b9b5f291a..9cb567e92 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -710,49 +710,51 @@ FILE FORMAT And some definitions: - subdirec- optional indented directive line immediately following a par- - tive ent directive - number how to interpret numbers when parsing journal entries (the - notation identity of the decimal separator character). (Currently - each commodity can have its own notation, even in the same - file.) - display how to display amounts of a commodity in reports (symbol side - style and spacing, digit groups, decimal separator, decimal places) - directive which entries and (when there are multiple files) which files - scope are affected by a directive + 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- + tion modity can have its own notation, even in the same file.) + 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 + tive are affected by a directive + scope As you can see, directives vary in which journal entries and files they affect, and whether they are focussed on input (parsing) or output (re- ports). Some directives have multiple effects. - If you have a journal made up of multiple files, or pass multiple -f - options on the command line, note that directives which affect input - typically last only until the end of their defining file. This pro- + If you have a journal made up of multiple files, or pass multiple -f + options on the command line, note that directives which affect input + typically last only until the end of their defining file. This pro- vides more simplicity and predictability, eg reports are not changed by - writing file options in a different order. It can be surprising at + writing file options in a different order. It can be surprising at times though. 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 path/to/file.journal - If the path does not begin with a slash, it is relative to the current - file. The include file path may contain common glob patterns (e.g. + If the path does not begin with a slash, it is relative to the current + file. The include file path may contain common glob patterns (e.g. *). - The include directive can only be used in journal files. It can in- + The include directive can only be used in journal files. It can in- clude 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 @@ -774,18 +776,18 @@ 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 to expect when parsing input - - useful to disambiguate international number formats in your data. + - 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 format 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. @@ -798,8 +800,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 @@ -812,14 +814,14 @@ 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. 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 @@ -834,9 +836,9 @@ FILE FORMAT a decimal point. 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: @@ -847,16 +849,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/--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 @@ -866,20 +868,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 @@ -887,7 +889,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 @@ -901,7 +903,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 @@ -914,18 +916,18 @@ FILE FORMAT [LEDGER-STYLE SUBDIRECTIVES, IGNORED] Account types - hledger recognises five types (or classes) of account: Asset, Liabil- - ity, Equity, Revenue, Expense. This is used by a few accounting-aware + hledger recognises five types (or classes) of account: Asset, Liabil- + ity, Equity, Revenue, Expense. This is used by a few accounting-aware reports such as balancesheet, incomestatement and cashflow. Auto-detected account types If you name your top-level accounts with some variation of assets, lia- - bilities/debts, equity, revenues/income, or expenses, their types are + bilities/debts, equity, revenues/income, or expenses, their types are detected automatically. Account types declared with tags - More generally, you can declare an account's type with an account di- - rective, by writing a type: tag in a comment, followed by one of the + More generally, you can declare an account's type with an account di- + rective, by writing a type: tag in a comment, followed by one of the words Asset, Liability, Equity, Revenue, Expense, or one of the letters ALERX (case insensitive): @@ -936,8 +938,8 @@ FILE FORMAT account expenses ; type:Expenses Account types declared with account type codes - Or, you can write one of those letters separated from the account name - by two or more spaces, but this should probably be considered depre- + Or, you can write one of those letters separated from the account name + by two or more spaces, but this should probably be considered depre- cated as of hledger 1.13: account assets A @@ -947,7 +949,7 @@ FILE FORMAT account expenses X Overriding auto-detected types - If you ever override the types of those auto-detected english account + If you ever override the types of those auto-detected english account names mentioned above, you might need to help the reports a bit. Eg: ; make "liabilities" not have the liability type - who knows why @@ -958,8 +960,8 @@ FILE FORMAT account - ; type:L 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: @@ -981,20 +983,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 @@ -1012,14 +1014,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 @@ -1027,49 +1029,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: @@ -1080,22 +1082,22 @@ 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. 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 @@ -1112,7 +1114,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 @@ -1121,50 +1123,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 @@ -1176,17 +1178,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: @@ -1200,82 +1202,82 @@ 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 - With the --forecast flag, each periodic transaction rule generates fu- - ture transactions recurring at the specified interval. These are not - saved in the journal, but appear in all reports. They will look like + With the --forecast flag, each periodic transaction rule generates fu- + ture 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: - o generated-transaction:~ PERIODICEXPR - shows that this was generated + o generated-transaction:~ PERIODICEXPR - shows that this was generated by a periodic transaction rule, and the period - There is also a hidden tag, with an underscore prefix, which does not + There is also a hidden tag, with an underscore prefix, which does not appear in hledger's output: o _generated-transaction:~ PERIODICEXPR - This can be used to match transactions generated "just now", rather + This can be used to match transactions generated "just now", rather than generated in the past and saved to the journal. - 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 Budgeting and Fore- + For more details, see: balance: Budget report and Budgeting and Fore- casting. Auto postings / transaction modifiers 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 + 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 that matches cer- - tain postings (mnemonic: = suggests matching). And each "posting" is + the first line is an equals sign followed by a query that matches cer- + tain postings (mnemonic: = suggests matching). And each "posting" is actually a posting-generating rule: = QUERY @@ -1283,25 +1285,25 @@ FILE FORMAT ACCT [AMT] ... - These posting-generating rules look like normal postings, except the + These posting-generating 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. - A query term containing spaces must be enclosed in single or double - quotes, as on the command line. Eg, note the quotes around the second + A 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' @@ -1343,20 +1345,20 @@ FILE FORMAT assets:checking $20 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, transaction modifiers are applied / 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. @@ -1366,11 +1368,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 transaction modifier + Also, any transaction that has been changed by transaction modifier rules will have these tags added: o modified: - this transaction was modified @@ -1381,7 +1383,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) @@ -1395,7 +1397,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) diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 04e2e8ef2..df96fbdb7 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1117,7 +1117,7 @@ Examples: .PP .TS tab(@); -l l. +lw(24.2n) lw(45.8n). T{ \f[C]2004/10/1\f[R], \f[C]2004-01-01\f[R], \f[C]2004.9.1\f[R] T}@T{ @@ -1176,7 +1176,7 @@ results: .PP .TS tab(@); -l l. +lw(11.4n) lw(58.6n). T{ \f[C]201813\f[R] T}@T{ @@ -1230,12 +1230,11 @@ Examples: .PP .TS tab(@); -l l. +lw(11.9n) lw(58.1n). T{ \f[C]-b 2016/3/17\f[R] T}@T{ -begin on St. -Patrick\[aq]s day 2016 +begin on St.\ Patrick\[cq]s day 2016 T} T{ \f[C]-e 12/1\f[R] @@ -1362,21 +1361,21 @@ start and end date like so: .PP .TS tab(@); -l r. +l l. T{ \f[C]-p \[dq]2009\[dq]\f[R] T}@T{ -the year 2009; equivalent to \[dq]2009/1/1 to 2010/1/1\[dq] +the year 2009; equivalent to \[lq]2009/1/1 to 2010/1/1\[rq] T} T{ \f[C]-p \[dq]2009/1\[dq]\f[R] T}@T{ -the month of jan; equivalent to \[dq]2009/1/1 to 2009/2/1\[dq] +the month of jan; equivalent to \[lq]2009/1/1 to 2009/2/1\[rq] T} T{ \f[C]-p \[dq]2009/1/1\[dq]\f[R] T}@T{ -just that day; equivalent to \[dq]2009/1/1 to 2009/1/2\[dq] +just that day; equivalent to \[lq]2009/1/1 to 2009/1/2\[rq] T} .TE .PP @@ -1415,22 +1414,27 @@ For example: .PP .TS tab(@); -l. +lw(25.5n) lw(44.5n). T{ -\f[C]-p \[dq]weekly from 2009/1/1 to 2009/4/1\[dq]\f[R] -- starts on -2008/12/29, closest preceding Monday +\f[C]-p \[dq]weekly from 2009/1/1 to 2009/4/1\[dq]\f[R] +T}@T{ +starts on 2008/12/29, closest preceding Monday T} T{ -\f[C]-p \[dq]monthly in 2008/11/25\[dq]\f[R] -- starts on 2018/11/01 +\f[C]-p \[dq]monthly in 2008/11/25\[dq]\f[R] +T}@T{ +starts on 2018/11/01 T} T{ -\f[C]-p \[dq]quarterly from 2009-05-05 to 2009-06-01\[dq]\f[R] - starts -on 2009/04/01, ends on 2009/06/30, which are first and last days of Q2 -2009 +\f[C]-p \[dq]quarterly from 2009-05-05 to 2009-06-01\[dq]\f[R] +T}@T{ +starts on 2009/04/01, ends on 2009/06/30, which are first and last days +of Q2 2009 T} T{ -\f[C]-p \[dq]yearly from 2009-12-29\[dq]\f[R] - starts on 2009/01/01, -first day of 2009 +\f[C]-p \[dq]yearly from 2009-12-29\[dq]\f[R] +T}@T{ +starts on 2009/01/01, first day of 2009 T} .TE .PP @@ -1446,18 +1450,21 @@ Examples: .PP .TS tab(@); -l. +lw(25.5n) lw(44.5n). T{ -\f[C]-p \[dq]bimonthly from 2008\[dq]\f[R] -- periods will have -boundaries on 2008/01/01, 2008/03/01, ... +\f[C]-p \[dq]bimonthly from 2008\[dq]\f[R] +T}@T{ +periods will have boundaries on 2008/01/01, 2008/03/01, ... T} T{ -\f[C]-p \[dq]every 2 weeks\[dq]\f[R] -- starts on closest preceding -Monday +\f[C]-p \[dq]every 2 weeks\[dq]\f[R] +T}@T{ +starts on closest preceding Monday T} T{ -\f[C]-p \[dq]every 5 month from 2009/03\[dq]\f[R] -- periods will have -boundaries on 2009/03/01, 2009/08/01, ... +\f[C]-p \[dq]every 5 month from 2009/03\[dq]\f[R] +T}@T{ +periods will have boundaries on 2009/03/01, 2009/08/01, ... T} .TE .PP @@ -1473,31 +1480,41 @@ Examples: .PP .TS tab(@); -l. +lw(23.9n) lw(46.1n). T{ -\f[C]-p \[dq]every 2nd day of week\[dq]\f[R] -- periods will go from Tue -to Tue +\f[C]-p \[dq]every 2nd day of week\[dq]\f[R] +T}@T{ +periods will go from Tue to Tue T} T{ -\f[C]-p \[dq]every Tue\[dq]\f[R] -- same +\f[C]-p \[dq]every Tue\[dq]\f[R] +T}@T{ +same T} T{ -\f[C]-p \[dq]every 15th day\[dq]\f[R] -- period boundaries will be on -15th of each month +\f[C]-p \[dq]every 15th day\[dq]\f[R] +T}@T{ +period boundaries will be on 15th of each month T} T{ -\f[C]-p \[dq]every 2nd Monday\[dq]\f[R] -- period boundaries will be on -second Monday of each month +\f[C]-p \[dq]every 2nd Monday\[dq]\f[R] +T}@T{ +period boundaries will be on second Monday of each month T} T{ -\f[C]-p \[dq]every 11/05\[dq]\f[R] -- yearly periods with boundaries on -5th of Nov +\f[C]-p \[dq]every 11/05\[dq]\f[R] +T}@T{ +yearly periods with boundaries on 5th of Nov T} T{ -\f[C]-p \[dq]every 5th Nov\[dq]\f[R] -- same +\f[C]-p \[dq]every 5th Nov\[dq]\f[R] +T}@T{ +same T} T{ -\f[C]-p \[dq]every Nov 5th\[dq]\f[R] -- same +\f[C]-p \[dq]every Nov 5th\[dq]\f[R] +T}@T{ +same T} .TE .PP diff --git a/hledger/hledger.info b/hledger/hledger.info index c5f87f617..a2b46ef8f 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -1051,25 +1051,31 @@ omitted (defaulting to 1). Examples: -'2004/10/1', '2004-01-01', '2004.9.1' exact date, several separators allowed. Year is 4+ digits, month is 1-12, day is 1-31 -'2004' start of year -'2004/10' start of month -'10/1' month and day in current year -'21' day in current month -'october, oct' start of month in current year -'yesterday, today, tomorrow' -1, 0, 1 days from today -'last/this/next -1, 0, 1 periods from the current period +'2004/10/1', exact date, several separators allowed. Year +'2004-01-01', is 4+ digits, month is 1-12, day is 1-31 +'2004.9.1' +'2004' start of year +'2004/10' start of month +'10/1' month and day in current year +'21' day in current month +'october, oct' start of month in current year +'yesterday, today, -1, 0, 1 days from today +tomorrow' +'last/this/next -1, 0, 1 periods from the current period day/week/month/quarter/year' -'20181201' 8 digit YYYYMMDD with valid year month and day -'201812' 6 digit YYYYMM with valid year and month +'20181201' 8 digit YYYYMMDD with valid year month and + day +'201812' 6 digit YYYYMM with valid year and month Counterexamples - malformed digit sequences might give surprising results: -'201813' 6 digits with an invalid month is parsed as start of 6-digit year -'20181301' 8 digits with an invalid month is parsed as start of 8-digit year -'20181232' 8 digits with an invalid day gives an error -'201801012' 9+ digits beginning with a valid YYYYMMDD gives an error +'201813' 6 digits with an invalid month is parsed as start of + 6-digit year +'20181301' 8 digits with an invalid month is parsed as start of + 8-digit year +'20181232' 8 digits with an invalid day gives an error +'201801012' 9+ digits beginning with a valid YYYYMMDD gives an error  File: hledger.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: OPTIONS @@ -1100,11 +1106,15 @@ these accept the smart date syntax. Examples: -'-b 2016/3/17' begin on St. Patrick's day 2016 -'-e 12/1' end at the start of december 1st of the current year (11/30 will be the last date included) -'-b thismonth' all transactions on or after the 1st of the current month -'-p thismonth' all transactions in the current month -'date:2016/3/17-' the above written as queries instead +'-b begin on St. Patrick's day 2016 +2016/3/17' +'-e 12/1' end at the start of december 1st of the current year + (11/30 will be the last date included) +'-b all transactions on or after the 1st of the current month +thismonth' +'-p all transactions in the current month +thismonth' +'date:2016/3/17-'the above written as queries instead 'date:-12/1' 'date:thismonth-' 'date:thismonth' @@ -1163,9 +1173,9 @@ the earliest or latest transaction in your journal: A single date with no "from" or "to" defines both the start and end date like so: -'-p "2009"' the year 2009; equivalent to "2009/1/1 to 2010/1/1" -'-p "2009/1"' the month of jan; equivalent to "2009/1/1 to 2009/2/1" -'-p "2009/1/1"' just that day; equivalent to "2009/1/1 to 2009/1/2" +'-p "2009"' the year 2009; equivalent to “2009/1/1 to 2010/1/1” +'-p "2009/1"' the month of jan; equivalent to “2009/1/1 to 2009/2/1” +'-p "2009/1/1"' just that day; equivalent to “2009/1/1 to 2009/1/2” The argument of '-p' can also begin with, or be, a report interval expression. The basic report intervals are 'daily', 'weekly', @@ -1185,10 +1195,15 @@ date. For example: -'-p "weekly from 2009/1/1 to 2009/4/1"' - starts on 2008/12/29, closest preceding Monday -'-p "monthly in 2008/11/25"' - starts on 2018/11/01 -'-p "quarterly from 2009-05-05 to 2009-06-01"' - starts on 2009/04/01, ends on 2009/06/30, which are first and last days of Q2 2009 -'-p "yearly from 2009-12-29"' - starts on 2009/01/01, first day of 2009 +'-p "weekly from starts on 2008/12/29, closest preceding +2009/1/1 to 2009/4/1"' Monday +'-p "monthly in starts on 2018/11/01 +2008/11/25"' +'-p "quarterly from starts on 2009/04/01, ends on 2009/06/30, +2009-05-05 to which are first and last days of Q2 2009 +2009-06-01"' +'-p "yearly from starts on 2009/01/01, first day of 2009 +2009-12-29"' The following more complex report intervals are also supported: 'biweekly', 'bimonthly', 'every day|week|month|quarter|year', 'every N @@ -1199,9 +1214,11 @@ end on the last one, as described above. Examples: -'-p "bimonthly from 2008"' - periods will have boundaries on 2008/01/01, 2008/03/01, ... -'-p "every 2 weeks"' - starts on closest preceding Monday -'-p "every 5 month from 2009/03"' - periods will have boundaries on 2009/03/01, 2009/08/01, ... +'-p "bimonthly from periods will have boundaries on 2008/01/01, +2008"' 2008/03/01, ... +'-p "every 2 weeks"' starts on closest preceding Monday +'-p "every 5 month from periods will have boundaries on 2009/03/01, +2009/03"' 2009/08/01, ... If you want intervals that start on arbitrary day of your choosing and span a week, month or year, you need to use any of the following: @@ -1212,13 +1229,16 @@ Nth MMM [of year]', 'every MMM Nth [of year]'. Examples: -'-p "every 2nd day of week"' - periods will go from Tue to Tue -'-p "every Tue"' - same -'-p "every 15th day"' - period boundaries will be on 15th of each month -'-p "every 2nd Monday"' - period boundaries will be on second Monday of each month -'-p "every 11/05"' - yearly periods with boundaries on 5th of Nov -'-p "every 5th Nov"' - same -'-p "every Nov 5th"' - same +'-p "every 2nd day of periods will go from Tue to Tue +week"' +'-p "every Tue"' same +'-p "every 15th day"' period boundaries will be on 15th of each + month +'-p "every 2nd period boundaries will be on second Monday of +Monday"' each month +'-p "every 11/05"' yearly periods with boundaries on 5th of Nov +'-p "every 5th Nov"' same +'-p "every Nov 5th"' same Show historical balances at end of 15th each month (N is exclusive end date): @@ -3696,139 +3716,139 @@ Node: Regular expressions32899 Ref: #regular-expressions33056 Node: Smart dates34417 Ref: #smart-dates34568 -Node: Report start & end date35974 -Ref: #report-start-end-date36146 -Node: Report intervals37570 -Ref: #report-intervals37735 -Node: Period expressions38125 -Ref: #period-expressions38285 -Node: Depth limiting42240 -Ref: #depth-limiting42384 -Node: Pivoting42726 -Ref: #pivoting42849 -Node: Valuation44525 -Ref: #valuation44627 -Node: -B Cost44807 -Ref: #b-cost44918 -Node: -V Market value45116 -Ref: #v-market-value45290 -Node: -X Market value in specified commodity46722 -Ref: #x-market-value-in-specified-commodity46961 -Node: --value Flexible valuation47137 -Ref: #value-flexible-valuation47363 -Node: Effect of --value on reports51553 -Ref: #effect-of---value-on-reports51769 -Node: Combining -B -V -X --value56700 -Ref: #combining--b--v--x---value56883 -Node: COMMANDS56919 -Ref: #commands57027 -Node: accounts58111 -Ref: #accounts58209 -Node: activity58908 -Ref: #activity59018 -Node: add59401 -Ref: #add59500 -Node: balance62239 -Ref: #balance62350 -Node: Classic balance report63808 -Ref: #classic-balance-report63981 -Node: Customising the classic balance report65350 -Ref: #customising-the-classic-balance-report65578 -Node: Colour support67654 -Ref: #colour-support67821 -Node: Flat mode67994 -Ref: #flat-mode68142 -Node: Depth limited balance reports68555 -Ref: #depth-limited-balance-reports68740 -Node: Percentages69196 -Ref: #percentages69362 -Node: Multicolumn balance report70499 -Ref: #multicolumn-balance-report70679 -Node: Budget report75993 -Ref: #budget-report76136 -Node: Nested budgets81338 -Ref: #nested-budgets81450 -Ref: #output-format-184931 -Node: balancesheet85009 -Ref: #balancesheet85145 -Node: balancesheetequity86528 -Ref: #balancesheetequity86677 -Node: cashflow87238 -Ref: #cashflow87366 -Node: check-dates88462 -Ref: #check-dates88589 -Node: check-dupes88868 -Ref: #check-dupes88992 -Node: close89285 -Ref: #close89399 -Node: close usage90921 -Ref: #close-usage91014 -Node: commodities93827 -Ref: #commodities93954 -Node: descriptions94036 -Ref: #descriptions94164 -Node: diff94345 -Ref: #diff94451 -Node: files95498 -Ref: #files95598 -Node: help95745 -Ref: #help95845 -Node: import96926 -Ref: #import97040 -Node: Importing balance assignments97933 -Ref: #importing-balance-assignments98081 -Node: incomestatement98730 -Ref: #incomestatement98863 -Node: notes100267 -Ref: #notes100380 -Node: payees100506 -Ref: #payees100612 -Node: prices100770 -Ref: #prices100876 -Node: print101217 -Ref: #print101327 -Node: print-unique105971 -Ref: #print-unique106097 -Node: register106382 -Ref: #register106509 -Node: Custom register output110681 -Ref: #custom-register-output110810 -Node: register-match112072 -Ref: #register-match112206 -Node: rewrite112557 -Ref: #rewrite112672 -Node: Re-write rules in a file114527 -Ref: #re-write-rules-in-a-file114661 -Node: Diff output format115871 -Ref: #diff-output-format116040 -Node: rewrite vs print --auto117132 -Ref: #rewrite-vs.-print---auto117311 -Node: roi117867 -Ref: #roi117965 -Node: stats118977 -Ref: #stats119076 -Node: tags119864 -Ref: #tags119962 -Node: test120256 -Ref: #test120364 -Node: Add-on Commands121111 -Ref: #add-on-commands121228 -Node: ui122571 -Ref: #ui122659 -Node: web122713 -Ref: #web122816 -Node: iadd122932 -Ref: #iadd123043 -Node: interest123125 -Ref: #interest123232 -Node: ENVIRONMENT123472 -Ref: #environment123584 -Node: FILES124413 -Ref: #files-1124516 -Node: LIMITATIONS124729 -Ref: #limitations124848 -Node: TROUBLESHOOTING125590 -Ref: #troubleshooting125703 +Node: Report start & end date35929 +Ref: #report-start-end-date36101 +Node: Report intervals37539 +Ref: #report-intervals37704 +Node: Period expressions38094 +Ref: #period-expressions38254 +Node: Depth limiting42380 +Ref: #depth-limiting42524 +Node: Pivoting42866 +Ref: #pivoting42989 +Node: Valuation44665 +Ref: #valuation44767 +Node: -B Cost44947 +Ref: #b-cost45058 +Node: -V Market value45256 +Ref: #v-market-value45430 +Node: -X Market value in specified commodity46862 +Ref: #x-market-value-in-specified-commodity47101 +Node: --value Flexible valuation47277 +Ref: #value-flexible-valuation47503 +Node: Effect of --value on reports51693 +Ref: #effect-of---value-on-reports51909 +Node: Combining -B -V -X --value56840 +Ref: #combining--b--v--x---value57023 +Node: COMMANDS57059 +Ref: #commands57167 +Node: accounts58251 +Ref: #accounts58349 +Node: activity59048 +Ref: #activity59158 +Node: add59541 +Ref: #add59640 +Node: balance62379 +Ref: #balance62490 +Node: Classic balance report63948 +Ref: #classic-balance-report64121 +Node: Customising the classic balance report65490 +Ref: #customising-the-classic-balance-report65718 +Node: Colour support67794 +Ref: #colour-support67961 +Node: Flat mode68134 +Ref: #flat-mode68282 +Node: Depth limited balance reports68695 +Ref: #depth-limited-balance-reports68880 +Node: Percentages69336 +Ref: #percentages69502 +Node: Multicolumn balance report70639 +Ref: #multicolumn-balance-report70819 +Node: Budget report76133 +Ref: #budget-report76276 +Node: Nested budgets81478 +Ref: #nested-budgets81590 +Ref: #output-format-185071 +Node: balancesheet85149 +Ref: #balancesheet85285 +Node: balancesheetequity86668 +Ref: #balancesheetequity86817 +Node: cashflow87378 +Ref: #cashflow87506 +Node: check-dates88602 +Ref: #check-dates88729 +Node: check-dupes89008 +Ref: #check-dupes89132 +Node: close89425 +Ref: #close89539 +Node: close usage91061 +Ref: #close-usage91154 +Node: commodities93967 +Ref: #commodities94094 +Node: descriptions94176 +Ref: #descriptions94304 +Node: diff94485 +Ref: #diff94591 +Node: files95638 +Ref: #files95738 +Node: help95885 +Ref: #help95985 +Node: import97066 +Ref: #import97180 +Node: Importing balance assignments98073 +Ref: #importing-balance-assignments98221 +Node: incomestatement98870 +Ref: #incomestatement99003 +Node: notes100407 +Ref: #notes100520 +Node: payees100646 +Ref: #payees100752 +Node: prices100910 +Ref: #prices101016 +Node: print101357 +Ref: #print101467 +Node: print-unique106111 +Ref: #print-unique106237 +Node: register106522 +Ref: #register106649 +Node: Custom register output110821 +Ref: #custom-register-output110950 +Node: register-match112212 +Ref: #register-match112346 +Node: rewrite112697 +Ref: #rewrite112812 +Node: Re-write rules in a file114667 +Ref: #re-write-rules-in-a-file114801 +Node: Diff output format116011 +Ref: #diff-output-format116180 +Node: rewrite vs print --auto117272 +Ref: #rewrite-vs.-print---auto117451 +Node: roi118007 +Ref: #roi118105 +Node: stats119117 +Ref: #stats119216 +Node: tags120004 +Ref: #tags120102 +Node: test120396 +Ref: #test120504 +Node: Add-on Commands121251 +Ref: #add-on-commands121368 +Node: ui122711 +Ref: #ui122799 +Node: web122853 +Ref: #web122956 +Node: iadd123072 +Ref: #iadd123183 +Node: interest123265 +Ref: #interest123372 +Node: ENVIRONMENT123612 +Ref: #environment123724 +Node: FILES124553 +Ref: #files-1124656 +Node: LIMITATIONS124869 +Ref: #limitations124988 +Node: TROUBLESHOOTING125730 +Ref: #troubleshooting125843  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 1a57a3056..0a6a8e136 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -894,112 +894,94 @@ OPTIONS Examples: - 2004/10/1, 2004-01-01, exact date, several sepa- - 2004.9.1 rators allowed. Year is - 4+ digits, month is 1-12, - day is 1-31 - 2004 start of year - 2004/10 start of month - 10/1 month and day in current - year - 21 day in current month - october, oct start of month in current - year - yesterday, today, tomorrow -1, 0, 1 days from today - last/this/next -1, 0, 1 periods from the - day/week/month/quar- current period + 2004/10/1, 2004-01-01, exact date, several separators allowed. Year + 2004.9.1 is 4+ digits, month is 1-12, day is 1-31 + 2004 start of year + 2004/10 start of month + 10/1 month and day in current year + 21 day in current month + october, oct start of month in current year + yesterday, today, tomor- -1, 0, 1 days from today + row + last/this/next -1, 0, 1 periods from the current period + day/week/month/quar- ter/year - 20181201 8 digit YYYYMMDD with - valid year month and day - 201812 6 digit YYYYMM with valid - year and month + 20181201 8 digit YYYYMMDD with valid year month and day + 201812 6 digit YYYYMM with valid year and month Counterexamples - malformed digit sequences might give surprising re- sults: - 201813 6 digits with an invalid - month is parsed as start - of 6-digit year - 20181301 8 digits with an invalid - month is parsed as start - of 8-digit year - 20181232 8 digits with an invalid - day gives an error - 201801012 9+ digits beginning with a - valid YYYYMMDD gives an - error + 201813 6 digits with an invalid month is parsed as start of + 6-digit year + 20181301 8 digits with an invalid month is parsed as start of + 8-digit year + 20181232 8 digits with an invalid day gives an error + 201801012 9+ digits beginning with a valid YYYYMMDD gives an error Report start & end date - Most hledger reports show the full span of time represented by the + Most hledger reports show the full span of time represented by the journal data, by default. So, the effective report start and end dates - will be the earliest and latest transaction or posting dates found in + will be the earliest and latest transaction or posting dates found in the journal. - Often you will want to see a shorter time span, such as the current - month. You can specify a start and/or end date using -b/--begin, + Often you will want to see a shorter time span, such as the current + month. You can specify a start and/or end date using -b/--begin, -e/--end, -p/--period or a date: query (described below). All of these accept the smart date syntax. Some notes: - o As in Ledger, end dates are exclusive, so you need to write the date + o As in Ledger, end dates are exclusive, so you need to write the date after the last day you want to include. - o As noted in reporting options: among start/end dates specified with + o As noted in reporting options: among start/end dates specified with options, the last (i.e. right-most) option takes precedence. - o The effective report start and end dates are the intersection of the - start/end dates from options and that from date: queries. That is, - date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the + o The effective report start and end dates are the intersection of the + start/end dates from options and that from date: queries. That is, + date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the smallest common time span. Examples: - -b 2016/3/17 begin on St. Patrick's - day 2016 - -e 12/1 end at the start of decem- - ber 1st of the current - year (11/30 will be the - last date included) - -b thismonth all transactions on or af- - ter the 1st of the current - month - -p thismonth all transactions in the - current month - date:2016/3/17- the above written as - queries instead + -b 2016/3/17 begin on St. Patrick's day 2016 + -e 12/1 end at the start of december 1st of the current year + (11/30 will be the last date included) + -b thismonth all transactions on or after the 1st of the current month + -p thismonth all transactions in the current month + date:2016/3/17- the above written as queries instead date:-12/1 date:thismonth- date:thismonth Report intervals A report interval can be specified so that commands like register, bal- - ance and activity will divide their reports into multiple subperiods. - The basic intervals can be selected with one of -D/--daily, - -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- - plex intervals may be specified with a period expression. Report in- + ance and activity will divide their reports into multiple subperiods. + The basic intervals can be selected with one of -D/--daily, + -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- + plex intervals may be specified with a period expression. Report in- tervals can not be specified with a query. Period expressions - The -p/--period option accepts period expressions, a shorthand way of + The -p/--period option accepts period expressions, a shorthand way of expressing a start date, end date, and/or report interval all at once. - Here's a basic period expression specifying the first quarter of 2009. - Note, hledger always treats start dates as inclusive and end dates as + Here's a basic period expression specifying the first quarter of 2009. + Note, hledger always treats start dates as inclusive and end dates as exclusive: -p "from 2009/1/1 to 2009/4/1" - Keywords like "from" and "to" are optional, and so are the spaces, as - long as you don't run two dates together. "to" can also be written as + Keywords like "from" and "to" are optional, and so are the spaces, as + long as you don't run two dates together. "to" can also be written as "-". These are equivalent to the above: -p "2009/1/1 2009/4/1" - -p2009/1/1to2009/4/1 -p2009/1/1-2009/4/1 - Dates are smart dates, so if the current year is 2009, the above can + Dates are smart dates, so if the current year is 2009, the above can also be written as: -p "1/1 4/1" @@ -1013,48 +995,46 @@ OPTIONS 1, 2009 -p "from 2009/1" the same -p "from 2009" the same - -p "to 2009" everything before january + + -p "to 2009" everything before january 1, 2009 - A single date with no "from" or "to" defines both the start and end + A single date with no "from" or "to" defines both the start and end date like so: - -p "2009" the year 2009; equivalent + -p "2009" the year 2009; equivalent to "2009/1/1 to 2010/1/1" - -p "2009/1" the month of jan; equiva- + -p "2009/1" the month of jan; equiva- lent to "2009/1/1 to 2009/2/1" - -p "2009/1/1" just that day; equivalent + -p "2009/1/1" just that day; equivalent to "2009/1/1 to 2009/1/2" - The argument of -p can also begin with, or be, a report interval ex- + The argument of -p can also begin with, or be, a report interval ex- pression. The basic report intervals are daily, weekly, monthly, quar- - terly, or yearly, which have the same effect as the -D,-W,-M,-Q, or -Y - flags. Between report interval and start/end dates (if any), the word + terly, or yearly, which have the same effect as the -D,-W,-M,-Q, or -Y + flags. Between report interval and start/end dates (if any), the word in is optional. Examples: -p "weekly from 2009/1/1 to 2009/4/1" -p "monthly in 2008" -p "quarterly" - Note that weekly, monthly, quarterly and yearly intervals will always + Note that weekly, monthly, quarterly and yearly intervals will always start on the first day on week, month, quarter or year accordingly, and - will end on the last day of same period, even if associated period ex- + will end on the last day of same period, even if associated period ex- pression specifies different explicit start and end date. For example: - -p "weekly from 2009/1/1 to 2009/4/1" - -- starts on 2008/12/29, closest pre- - ceding Monday - -p "monthly in 2008/11/25" -- starts on - 2018/11/01 - -p "quarterly from 2009-05-05 to - 2009-06-01" - starts on 2009/04/01, - ends on 2009/06/30, which are first and - last days of Q2 2009 - -p "yearly from 2009-12-29" - starts on - 2009/01/01, first day of 2009 + -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon- + to 2009/4/1" day + -p "monthly in starts on 2018/11/01 + 2008/11/25" + -p "quarterly from starts on 2009/04/01, ends on 2009/06/30, + 2009-05-05 to 2009-06-01" which are first and last days of Q2 2009 + -p "yearly from starts on 2009/01/01, first day of 2009 + 2009-12-29" The following more complex report intervals are also supported: bi- weekly, bimonthly, every day|week|month|quarter|year, every N @@ -1065,14 +1045,11 @@ OPTIONS Examples: - -p "bimonthly from 2008" -- periods - will have boundaries on 2008/01/01, - 2008/03/01, ... - -p "every 2 weeks" -- starts on closest - preceding Monday - -p "every 5 month from 2009/03" -- pe- - riods will have boundaries on - 2009/03/01, 2009/08/01, ... + -p "bimonthly from 2008" periods will have boundaries on 2008/01/01, + 2008/03/01, ... + -p "every 2 weeks" starts on closest preceding Monday + -p "every 5 month from periods will have boundaries on 2009/03/01, + 2009/03" 2009/08/01, ... If you want intervals that start on arbitrary day of your choosing and span a week, month or year, you need to use any of the following: @@ -1083,18 +1060,17 @@ OPTIONS Examples: - -p "every 2nd day of week" -- periods - will go from Tue to Tue - -p "every Tue" -- same - -p "every 15th day" -- period bound- - aries will be on 15th of each month - -p "every 2nd Monday" -- period bound- - aries will be on second Monday of each - month - -p "every 11/05" -- yearly periods with - boundaries on 5th of Nov - -p "every 5th Nov" -- same - -p "every Nov 5th" -- same + -p "every 2nd day of periods will go from Tue to Tue + week" + + -p "every Tue" same + -p "every 15th day" period boundaries will be on 15th of each + month + -p "every 2nd Monday" period boundaries will be on second Monday of + each month + -p "every 11/05" yearly periods with boundaries on 5th of Nov + -p "every 5th Nov" same + -p "every Nov 5th" same Show historical balances at end of 15th each month (N is exclusive end date): @@ -1403,9 +1379,6 @@ OPTIONS ance (with -H) before report before report DATE/today or journal or journal start start - - - posting cost value at report value at report value at amounts (no end or today or journal end DATE/today report inter- @@ -1424,6 +1397,7 @@ OPTIONS report inter- end or today of or journal end DATE/today of val) sums of post- of sums of sums of post- ings postings ings + balances (with sums of costs value at period value at period value at report inter- ends of sums of ends of sums of DATE/today of val) postings postings sums of post-