diff --git a/hledger-api/hledger-api.1 b/hledger-api/hledger-api.1 index e9017ef99..df5c20ab5 100644 --- a/hledger-api/hledger-api.1 +++ b/hledger-api/hledger-api.1 @@ -1,5 +1,5 @@ -.TH "hledger\-api" "1" "March 2018" "hledger\-api 1.9.99" "hledger User Manuals" +.TH "hledger\-api" "1" "June 2018" "hledger\-api 1.9.99" "hledger User Manuals" diff --git a/hledger-api/hledger-api.txt b/hledger-api/hledger-api.txt index 192390745..acf0ee8a9 100644 --- a/hledger-api/hledger-api.txt +++ b/hledger-api/hledger-api.txt @@ -117,4 +117,4 @@ SEE ALSO -hledger-api 1.9.99 March 2018 hledger-api(1) +hledger-api 1.9.99 June 2018 hledger-api(1) diff --git a/hledger-lib/hledger_csv.5 b/hledger-lib/hledger_csv.5 index 4960266b9..767936603 100644 --- a/hledger-lib/hledger_csv.5 +++ b/hledger-lib/hledger_csv.5 @@ -1,5 +1,5 @@ -.TH "hledger_csv" "5" "March 2018" "hledger 1.9.99" "hledger User Manuals" +.TH "hledger_csv" "5" "June 2018" "hledger 1.9.99" "hledger User Manuals" diff --git a/hledger-lib/hledger_csv.txt b/hledger-lib/hledger_csv.txt index 804b3192e..687390ad4 100644 --- a/hledger-lib/hledger_csv.txt +++ b/hledger-lib/hledger_csv.txt @@ -249,4 +249,4 @@ SEE ALSO -hledger 1.9.99 March 2018 hledger_csv(5) +hledger 1.9.99 June 2018 hledger_csv(5) diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index a6784fdd4..57acb9a2c 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -1,6 +1,6 @@ .\"t -.TH "hledger_journal" "5" "March 2018" "hledger 1.9.99" "hledger User Manuals" +.TH "hledger_journal" "5" "June 2018" "hledger 1.9.99" "hledger User Manuals" @@ -825,50 +825,173 @@ simple strings. .PP A directive is a line in the journal beginning with a special keyword, that influences how the journal is processed. -Some directives may also have indented sub\-directives on the following -lines (\f[C]commodity\f[]). -.SS Directive scope, multiple files +hledger's directives are based on a subset of Ledger's, but there are +many differences (and also some differences between hledger versions). .PP -Directives vary in which journal entries they affect: -.IP \[bu] 2 -some form a begin/end pair, and affect the enclosed journal entries (and -included files): -.PD 0 -.P -.PD -\f[C]alias\f[] & \f[C]end\ aliases\f[]; \f[C]comment\f[] & +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. +.PP +.TS +tab(@); +lw(7.8n) lw(8.6n) lw(7.0n) lw(27.8n) lw(18.8n). +T{ +directive +T}@T{ +end directive +T}@T{ +subdirectives +T}@T{ +purpose +T}@T{ +can affect (as of 2018/06) +T} +_ +T{ +\f[C]account\f[] +T}@T{ +T}@T{ +any text +T}@T{ +declare an account name & optional account code +T}@T{ +account code: balance reports (except \f[C]balance\f[] single\-column +mode) +T} +T{ +\f[C]alias\f[] +T}@T{ +\f[C]end\ aliases\f[] +T}@T{ +T}@T{ +rewrite account names +T}@T{ +following inline/included entries until end of current file or end +directive +T} +T{ +\f[C]apply\ account\f[] +T}@T{ +\f[C]end\ apply\ account\f[] +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 +T} +T{ +\f[C]comment\f[] +T}@T{ \f[C]end\ comment\f[] -.IP \[bu] 2 -some affect the subsequent journal entries (and included files) in the -current file: -.PD 0 -.P -.PD -\f[C]alias\f[] or \f[C]comment\f[] without an end directive, \f[C]Y\f[] -.IP \[bu] 2 -some affect all journal entries (and included files) anywhere in the -current file: -.PD 0 -.P -.PD -\f[C]account\f[], \f[C]commodity\f[], \f[C]D\f[], \f[C]P\f[]. +T}@T{ +T}@T{ +ignore part of journal +T}@T{ +following inline/included entries until end of current file or end +directive +T} +T{ +\f[C]commodity\f[] +T}@T{ +T}@T{ +\f[C]format\f[] +T}@T{ +declare a commodity and its number notation & display style +T}@T{ +number notation: following entries in that commodity in all files; +display style: amounts of that commodity in reports +T} +T{ +\f[C]D\f[] +T}@T{ +T}@T{ +T}@T{ +declare a commodity, number notation & display style for commodityless +amounts +T}@T{ +commodity: all commodityless entries in all files; number notation: +following commodityless entries and entries in that commodity in all +files; display style: amounts of that commodity in reports +T} +T{ +\f[C]include\f[] +T}@T{ +T}@T{ +T}@T{ +include entries/directives from another file +T}@T{ +what the included directives affect +T} +T{ +\f[C]P\f[] +T}@T{ +T}@T{ +T}@T{ +declare a market price for a commodity +T}@T{ +amounts of that commodity in reports, when \-V is used +T} +T{ +\f[C]Y\f[] +T}@T{ +T}@T{ +T}@T{ +declare a year for yearless dates +T}@T{ +following inline/included entries until end of current file +T} +.TE .PP -It's important to note that directives can affect the current file and -child (included) files, but not sibling or parent (including) files. -This is by design, for simplicity and predictability of reports, but it -can be surprising at times. -Eg, in: -.IP -.nf -\f[C] -hledger\ \-f\ a.prices\ \-f\ b.journal -\f[] -.fi +And some definitions: .PP -the prices defined in a.prices will not be effective in b.journal (a -sibling file). -Instead, you have to include (or inline) a.prices in b.journal, or vice -versa. +.TS +tab(@); +lw(8.9n) lw(61.1n). +T{ +subdirective +T}@T{ +optional indented directive or unparsed text lines immediately following +a parent directive +T} +T{ +account code +T}@T{ +numeric code influencing account display order in most balance reports +T} +T{ +number notation +T}@T{ +how to interpret numbers when parsing journal entries (the identity of +the decimal separator character). +(Currently each commodity can have its own notation, even in the same +file.) +T} +T{ +display style +T}@T{ +how to display amounts of a commodity in reports (symbol side and +spacing, digit groups, decimal separator, decimal places) +T} +T{ +directive scope +T}@T{ +which entries and (when there are multiple files) which files are +affected by a directive +T} +.TE +.PP +As you can see, directives vary in which journal entries and files they +affect, and whether they are focussed on input (parsing) or output +(reports). +Some directives have multiple effects. +.PP +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 provides more simplicity and predictability, eg reports are not +changed by writing file options in a different order. +It can be surprising at times though. .SS Comment blocks .PP A line containing just \f[C]comment\f[] starts a commented region of the @@ -1047,11 +1170,24 @@ account\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 6000 \f[] .fi .PP -This affects account display order in reports: accounts with codes are -listed before accounts without codes, in increasing code order. -(Otherwise, accounts are listed alphabetically.) Account codes should be -all numeric digits, unique, and separated from the account name by at -least two spaces (since account names may contain single spaces). +This affects how accounts are sorted in account and balance reports: +accounts with codes are listed before accounts without codes, and in +increasing code order (instead of listing all accounts alphabetically). +Warning, this feature is incomplete; account codes do not yet affect +sort order in +.IP \[bu] 2 +the \f[C]accounts\f[] command +.IP \[bu] 2 +the \f[C]balance\f[] command's single\-column mode +.IP \[bu] 2 +flat mode balance reports (to work around this, declare account codes on +the subaccounts as well). +.IP \[bu] 2 +hledger\-web's sidebar +.PP +Account codes should be all numeric digits, unique, and separated from +the account name by at least two spaces (since account names may contain +single spaces). By convention, often the first digit indicates the type of account, as in this numbering scheme and the example above. In future, we might use this to recognize account types. @@ -1072,9 +1208,9 @@ account\ assets:bank:checking\ \ \ 1110 .fi .SS Rewriting accounts .PP -You can define aliases which rewrite your account names (after reading -the journal, before generating reports). -hledger's account aliases can be useful for: +You can define account alias rules which rewrite your account names, or +parts of them, before generating reports. +This can be useful for: .IP \[bu] 2 expanding shorthand account names to their full form, allowing easier data entry and a less verbose journal @@ -1086,6 +1222,10 @@ combining two accounts into one .IP \[bu] 2 customising reports .PP +Account aliases also rewrite account names in account directives. +They do not affect account names being entered via hledger add or +hledger\-web. +.PP See also Cookbook: Rewrite account names. .SS Basic aliases .PP @@ -1106,7 +1246,7 @@ command line. This affects all entries. It's useful for trying out aliases interactively. .PP -OLD and NEW are full account names. +OLD and NEW are case sensitive full account names. hledger will replace any occurrence of the old account name with the new one. Subaccounts are also affected. @@ -1216,16 +1356,22 @@ include\ personal.journal .PP Prior to hledger 1.0, legacy \f[C]account\f[] and \f[C]end\f[] spellings were also supported. +.PP +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. .SS Periodic transactions .PP Periodic transaction rules describe transactions that recur. -They allow you to generate future transactions for forecast reports -(with \f[C]\-\-forecast\f[]), without having to write them out -explicitly in the journal. +They allow you to generate future transactions for forecasting, without +having to write them out explicitly in the journal (with +\f[C]\-\-forecast\f[]). Secondly, they also can be used to define budget goals (with \f[C]\-\-budget\f[]). .PP -A periodic transaction rule looks like a regular journal entry, with the +A periodic transaction rule looks like a normal journal entry, with the date replaced by a tilde (\f[C]~\f[]) followed by a period expression (mnemonic: \f[C]~\f[] looks like a repeating sine wave): .IP @@ -1242,9 +1388,8 @@ date must fall on a natural boundary of the interval. Eg \f[C]monthly\ from\ 2018/1/1\f[] is valid, but \f[C]monthly\ from\ 2018/1/15\f[] is not. .PP -Also, if you write a transaction description or same\-line comment, it -must be separated from the period expression by \f[B]two or more -spaces\f[]. +If you write a transaction description or same\-line comment, it must be +separated from the period expression by \f[B]two or more spaces\f[]. Eg: .IP .nf @@ -1257,30 +1402,34 @@ Eg: \ \ \ \ income:acme\ inc \f[] .fi -.SS Generating forecasts with periodic transactions +.SS Forecasting with periodic transactions .PP With the \f[C]\-\-forecast\f[] flag, each periodic transaction rule -generates future transactions recurring at the specified interval, -beginning the day after the latest recorded journal transaction (or -today, if there are no transactions), and ending 6 months from today (or -at the report end date, if specified). -The generated transactions will appear in all reports. -They will have a \[lq]recur:\[rq] transaction tag added, with the -generating period expression as its value. +generates future transactions recurring at the specified interval. +These are not saved in the journal, but appear in all reports. +They will look like normal transactions, but with an extra tag named +\f[C]recur\f[], whose value is the generating period expression. .PP -This can be useful for forecasting balances into the future, and -experimenting with different scenarios, without having to write a lot of -journal entries. -It can also help with data entry (describe most of your transactions -with periodic rules, and every so often copy the output of -\f[C]print\ \-\-forecast\f[] to the journal). +Forecast transactions begin on or after the day after the latest normal +(non\-periodic) transaction in the journal, or today if there are none. .PP -You can generate one\-time transactions too; just write a period +They end on or before the report end date if specified, or 180 days from +today if unspecified. +.PP +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. +.PP +Forecasting can also help with data entry: describe most of your +transactions with periodic rules, and every so often copy the output of +\f[C]print\ \-\-forecast\f[] to the journal. +.PP +You can generate one\-time transactions too: just write a period expression specifying a date with no report interval. -You could use this to forecast an estimated transaction, that is -automatically deactivated once the actual transaction (or any other -transaction on or after that date) is recorded. -.SS Setting budget goals with periodic transactions +(You could also write a normal transaction with a future date, but +remember this disables forecast transactions on previous dates.) +.SS Budgeting with periodic transactions .PP With the \f[C]\-\-budget\f[] flag, currently supported by the balance command, each periodic transaction rule declares recurring budget goals @@ -1297,7 +1446,7 @@ Automated posting rules describe extra postings that should be added to certain transactions at report time, when the \f[C]\-\-auto\f[] flag is used. .PP -An automated posting rule looks like a regular journal entry, except the +An automated posting rule looks like a normal journal entry, except the first line is an equal sign (\f[C]=\f[]) followed by a query (mnemonic: \f[C]=\f[] looks like posting lines): .IP diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index 93a642e92..fe2360320 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -755,11 +755,97 @@ File: hledger_journal.info, Node: Directives, Next: Periodic transactions, Pr =============== A directive is a line in the journal beginning with a special keyword, -that influences how the journal is processed. Some directives may also -have indented sub-directives on the following lines ('commodity'). +that influences how the journal is processed. hledger's directives are +based on a subset of Ledger's, but there are many differences (and also +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. + +directiveend subdirectivespurpose can affect (as of + directive 2018/06) +----------------------------------------------------------------------------- +'account' any declare an account name & account code: + text optional account code balance reports + (except 'balance' + single-column + mode) +'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 +'commodity' 'format'declare a commodity and its number notation: + number notation & display following entries + style in that commodity + in all files; + display style: + amounts of that + commodity in + reports +'D' declare a commodity, number commodity: all + notation & display style commodityless + for commodityless amounts entries in all + files; number + notation: + following + commodityless + entries and + entries in that + commodity in all + files; display + style: amounts of + that commodity in + reports +'include' include entries/directives what the included + from another file directives affect +'P' declare a market price for amounts of that + 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 + + And some definitions: + +subdirectiveoptional indented directive or unparsed text lines + immediately following a parent directive +account numeric code influencing account display order in most +code balance reports +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 + + As you can see, directives vary in which journal entries and files +they affect, and whether they are focussed on input (parsing) or output +(reports). 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 provides +more simplicity and predictability, eg reports are not changed by +writing file options in a different order. It can be surprising at +times though. * Menu: -* Directive scope multiple files:: * Comment blocks:: * Including other files:: * Default year:: @@ -771,38 +857,9 @@ have indented sub-directives on the following lines ('commodity'). * Default parent account::  -File: hledger_journal.info, Node: Directive scope multiple files, Next: Comment blocks, Up: Directives +File: hledger_journal.info, Node: Comment blocks, Next: Including other files, Up: Directives -1.14.1 Directive scope, multiple files --------------------------------------- - -Directives vary in which journal entries they affect: - - * some form a begin/end pair, and affect the enclosed journal entries - (and included files): - 'alias' & 'end aliases'; 'comment' & 'end comment' - * some affect the subsequent journal entries (and included files) in - the current file: - 'alias' or 'comment' without an end directive, 'Y' - * some affect all journal entries (and included files) anywhere in - the current file: - 'account', 'commodity', 'D', 'P'. - - It's important to note that directives can affect the current file -and child (included) files, but not sibling or parent (including) files. -This is by design, for simplicity and predictability of reports, but it -can be surprising at times. Eg, in: - -hledger -f a.prices -f b.journal - - the prices defined in a.prices will not be effective in b.journal (a -sibling file). Instead, you have to include (or inline) a.prices in -b.journal, or vice versa. - - -File: hledger_journal.info, Node: Comment blocks, Next: Including other files, Prev: Directive scope multiple files, Up: Directives - -1.14.2 Comment blocks +1.14.1 Comment blocks --------------------- A line containing just 'comment' starts a commented region of the file, @@ -812,7 +869,7 @@ file) ends it. See also comments.  File: hledger_journal.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: Directives -1.14.3 Including other files +1.14.2 Including other files ---------------------------- You can pull in the content of additional files by writing an include @@ -829,7 +886,7 @@ include journal, timeclock or timedot files, but not CSV files.  File: hledger_journal.info, Node: Default year, Next: Declaring commodities, Prev: Including other files, Up: Directives -1.14.4 Default year +1.14.3 Default year ------------------- You can set a default year to be used for subsequent dates which don't @@ -855,7 +912,7 @@ Y2010 ; change default year to 2010  File: hledger_journal.info, Node: Declaring commodities, Next: Default commodity, Prev: Default year, Up: Directives -1.14.5 Declaring commodities +1.14.4 Declaring commodities ---------------------------- The 'commodity' directive declares commodities which may be used in the @@ -893,7 +950,7 @@ or more decimal digits).  File: hledger_journal.info, Node: Default commodity, Next: Market prices, Prev: Declaring commodities, Up: Directives -1.14.6 Default commodity +1.14.5 Default commodity ------------------------ The 'D' directive sets a default commodity (and display format), to be @@ -916,7 +973,7 @@ with a decimal point.  File: hledger_journal.info, Node: Market prices, Next: Declaring accounts, Prev: Default commodity, Up: Directives -1.14.7 Market prices +1.14.6 Market prices -------------------- The 'P' directive declares a market price, which is an exchange rate @@ -946,7 +1003,7 @@ another commodity using these prices.  File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Market prices, Up: Directives -1.14.8 Declaring accounts +1.14.7 Declaring accounts ------------------------- The 'account' directive predeclares account names. The simplest form is @@ -966,14 +1023,23 @@ account liabilities 2000 account revenues 4000 account expenses 6000 - This affects account display order in reports: accounts with codes -are listed before accounts without codes, in increasing code order. -(Otherwise, accounts are listed alphabetically.) Account codes should -be all numeric digits, unique, and separated from the account name by at -least two spaces (since account names may contain single spaces). By -convention, often the first digit indicates the type of account, as in -this numbering scheme and the example above. In future, we might use -this to recognize account types. + This affects how accounts are sorted in account and balance reports: +accounts with codes are listed before accounts without codes, and in +increasing code order (instead of listing all accounts alphabetically). +Warning, this feature is incomplete; account codes do not yet affect +sort order in + + * the 'accounts' command + * the 'balance' command's single-column mode + * flat mode balance reports (to work around this, declare account + codes on the subaccounts as well). + * hledger-web's sidebar + + Account codes should be all numeric digits, unique, and separated +from the account name by at least two spaces (since account names may +contain single spaces). By convention, often the first digit indicates +the type of account, as in this numbering scheme and the example above. +In future, we might use this to recognize account types. An account directive can also have indented subdirectives following it, which are currently ignored. Here is the full syntax: @@ -988,12 +1054,11 @@ account assets:bank:checking 1110  File: hledger_journal.info, Node: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: Directives -1.14.9 Rewriting accounts +1.14.8 Rewriting accounts ------------------------- -You can define aliases which rewrite your account names (after reading -the journal, before generating reports). hledger's account aliases can -be useful for: +You can define account alias rules which rewrite your account names, or +parts of them, before generating reports. This can be useful for: * expanding shorthand account names to their full form, allowing easier data entry and a less verbose journal @@ -1002,6 +1067,10 @@ be useful for: or combining two accounts into one * customising reports + Account aliases also rewrite account names in account directives. +They do not affect account names being entered via hledger add or +hledger-web. + See also Cookbook: Rewrite account names. * Menu: @@ -1013,7 +1082,7 @@ be useful for:  File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts -1.14.9.1 Basic aliases +1.14.8.1 Basic aliases ...................... To set an account alias, use the 'alias' directive in your journal file. @@ -1026,9 +1095,9 @@ alias OLD = NEW This affects all entries. It's useful for trying out aliases interactively. - OLD and NEW are full account names. hledger will replace any -occurrence of the old account name with the new one. Subaccounts are -also affected. Eg: + OLD and NEW are case sensitive full account names. hledger will +replace any occurrence of the old account name with the new one. +Subaccounts 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" @@ -1036,7 +1105,7 @@ alias checking = assets:bank:wells fargo:checking  File: hledger_journal.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Rewriting accounts -1.14.9.2 Regex aliases +1.14.8.2 Regex aliases ...................... There is also a more powerful variant that uses a regular expression, @@ -1061,7 +1130,7 @@ whitespace.  File: hledger_journal.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Rewriting accounts -1.14.9.3 Multiple aliases +1.14.8.3 Multiple aliases ......................... You can define as many aliases as you like using directives or @@ -1077,7 +1146,7 @@ following order:  File: hledger_journal.info, Node: end aliases, Prev: Multiple aliases, Up: Rewriting accounts -1.14.9.4 'end aliases' +1.14.8.4 'end aliases' ...................... You can clear (forget) all currently defined aliases with the 'end @@ -1088,8 +1157,8 @@ end aliases  File: hledger_journal.info, Node: Default parent account, Prev: Rewriting accounts, Up: Directives -1.14.10 Default parent account ------------------------------- +1.14.9 Default parent account +----------------------------- You can specify a parent account which will be prepended to all accounts within a section of the journal. Use the 'apply account' and 'end apply @@ -1121,6 +1190,11 @@ include personal.journal Prior to hledger 1.0, legacy 'account' and 'end' spellings were also supported. + 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. +  File: hledger_journal.info, Node: Periodic transactions, Next: Automated postings, Prev: Directives, Up: FILE FORMAT @@ -1128,12 +1202,11 @@ File: hledger_journal.info, Node: Periodic transactions, Next: Automated posti ========================== Periodic transaction rules describe transactions that recur. They allow -you to generate future transactions for forecast reports (with -'--forecast'), without having to write them out explicitly in the -journal. Secondly, they also can be used to define budget goals (with -'--budget'). +you to generate future transactions for forecasting, without having to +write them out explicitly in the journal (with '--forecast'). Secondly, +they also can be used to define budget goals (with '--budget'). - A periodic transaction rule looks like a regular journal entry, with + A periodic transaction rule looks like a normal journal entry, with the date replaced by a tilde ('~') followed by a period expression (mnemonic: '~' looks like a repeating sine wave): @@ -1145,9 +1218,8 @@ the date replaced by a tilde ('~') followed by a period expression 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. - Also, if you write a transaction description or same-line comment, it -must be separated from the period expression by *two or more spaces*. -Eg: + If you write a transaction description or same-line comment, it must +be separated from the period expression by *two or more spaces*. Eg: ; 2 or more spaces ; || @@ -1158,40 +1230,47 @@ Eg: * Menu: -* Generating forecasts with periodic transactions:: -* Setting budget goals with periodic transactions:: +* Forecasting with periodic transactions:: +* Budgeting with periodic transactions::  -File: hledger_journal.info, Node: Generating forecasts with periodic transactions, Next: Setting budget goals with periodic transactions, Up: Periodic transactions +File: hledger_journal.info, Node: Forecasting with periodic transactions, Next: Budgeting with periodic transactions, Up: Periodic transactions -1.15.1 Generating forecasts with periodic transactions ------------------------------------------------------- +1.15.1 Forecasting with periodic transactions +--------------------------------------------- With the '--forecast' flag, each periodic transaction rule generates -future transactions recurring at the specified interval, beginning the -day after the latest recorded journal transaction (or today, if there -are no transactions), and ending 6 months from today (or at the report -end date, if specified). The generated transactions will appear in all -reports. They will have a "recur:" transaction tag added, with the -generating period expression as its value. +future transactions recurring at the specified interval. These are not +saved in the journal, but appear in all reports. They will look like +normal transactions, but with an extra tag named 'recur', whose value is +the generating period expression. - This can be useful for forecasting balances into the future, and -experimenting with different scenarios, without having to write a lot of -journal entries. It can also help with data entry (describe most of -your transactions with periodic rules, and every so often copy the -output of 'print --forecast' to the journal). + Forecast transactions begin on or after the day after the latest +normal (non-periodic) transaction in the journal, or today if there are +none. - You can generate one-time transactions too; just write a period -expression specifying a date with no report interval. You could use -this to forecast an estimated transaction, that is automatically -deactivated once the actual transaction (or any other transaction on or -after that date) is recorded. + They end on or before the report end date if specified, or 180 days +from today if unspecified. + + 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 +transactions 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 +expression 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.)  -File: hledger_journal.info, Node: Setting budget goals with periodic transactions, Prev: Generating forecasts with periodic transactions, Up: Periodic transactions +File: hledger_journal.info, Node: Budgeting with periodic transactions, Prev: Forecasting with periodic transactions, Up: Periodic transactions -1.15.2 Setting budget goals with periodic transactions ------------------------------------------------------- +1.15.2 Budgeting with periodic transactions +------------------------------------------- With the '--budget' flag, currently supported by the balance command, each periodic transaction rule declares recurring budget goals for the @@ -1212,7 +1291,7 @@ File: hledger_journal.info, Node: Automated postings, Prev: Periodic transacti Automated posting rules describe extra postings that should be added to certain transactions at report time, when the '--auto' flag is used. - An automated posting rule looks like a regular journal entry, except + An automated posting rule looks like a normal journal entry, except the first line is an equal sign ('=') followed by a query (mnemonic: '=' looks like posting lines): @@ -1325,43 +1404,41 @@ Node: Tags26398 Ref: #tags26516 Node: Directives27918 Ref: #directives28061 -Node: Directive scope multiple files28517 -Ref: #directive-scope-multiple-files28705 -Node: Comment blocks29655 -Ref: #comment-blocks29839 -Node: Including other files30015 -Ref: #including-other-files30195 -Node: Default year30584 -Ref: #default-year30753 -Node: Declaring commodities31176 -Ref: #declaring-commodities31359 -Node: Default commodity32586 -Ref: #default-commodity32762 -Node: Market prices33398 -Ref: #market-prices33563 -Node: Declaring accounts34404 -Ref: #declaring-accounts34580 -Node: Rewriting accounts35927 -Ref: #rewriting-accounts36112 -Node: Basic aliases36716 -Ref: #basic-aliases36862 -Node: Regex aliases37552 -Ref: #regex-aliases37723 -Node: Multiple aliases38441 -Ref: #multiple-aliases38616 -Node: end aliases39114 -Ref: #end-aliases39261 -Node: Default parent account39362 -Ref: #default-parent-account39530 -Node: Periodic transactions40189 -Ref: #periodic-transactions40368 -Node: Generating forecasts with periodic transactions41609 -Ref: #generating-forecasts-with-periodic-transactions41890 -Node: Setting budget goals with periodic transactions42983 -Ref: #setting-budget-goals-with-periodic-transactions43264 -Node: Automated postings43723 -Ref: #automated-postings43877 -Node: EDITOR SUPPORT45017 -Ref: #editor-support45135 +Node: Comment blocks33917 +Ref: #comment-blocks34062 +Node: Including other files34238 +Ref: #including-other-files34418 +Node: Default year34807 +Ref: #default-year34976 +Node: Declaring commodities35399 +Ref: #declaring-commodities35582 +Node: Default commodity36809 +Ref: #default-commodity36985 +Node: Market prices37621 +Ref: #market-prices37786 +Node: Declaring accounts38627 +Ref: #declaring-accounts38803 +Node: Rewriting accounts40474 +Ref: #rewriting-accounts40659 +Node: Basic aliases41393 +Ref: #basic-aliases41539 +Node: Regex aliases42243 +Ref: #regex-aliases42414 +Node: Multiple aliases43132 +Ref: #multiple-aliases43307 +Node: end aliases43805 +Ref: #end-aliases43952 +Node: Default parent account44053 +Ref: #default-parent-account44219 +Node: Periodic transactions45103 +Ref: #periodic-transactions45282 +Node: Forecasting with periodic transactions46492 +Ref: #forecasting-with-periodic-transactions46735 +Node: Budgeting with periodic transactions47976 +Ref: #budgeting-with-periodic-transactions48215 +Node: Automated postings48674 +Ref: #automated-postings48828 +Node: EDITOR SUPPORT49967 +Ref: #editor-support50085  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index 36a0f728c..ec5954059 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -601,34 +601,97 @@ FILE FORMAT Directives A directive is a line in the journal beginning with a special keyword, - that influences how the journal is processed. Some directives may also - have indented sub-directives on the following lines (commodity). + that influences how the journal is processed. hledger's directives are + based on a subset of Ledger's, but there are many differences (and also + some differences between hledger versions). - Directive scope, multiple files - Directives vary in which journal entries they affect: + 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. - o some form a begin/end pair, and affect the enclosed journal entries - (and included files): - alias & end aliases; comment & end comment - o some affect the subsequent journal entries (and included files) in - the current file: - alias or comment without an end directive, Y + direc- end subdi- purpose can affect (as of + tive directive rec- 2018/06) + tives + ------------------------------------------------------------------------------------------------- + account any declare an account name & account code: bal- + text optional account code ance reports + (except balance + single-column mode) + alias end aliases rewrite account names following + inline/included + entries until end + of current file or + end directive + apply account end apply account prepend a common parent to following + account names inline/included + entries until end + of current file or + end directive + comment end comment ignore part of journal following + inline/included + entries 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; dis- + play style: amounts + of that commodity + in reports + D declare a commodity, number commodity: all com- + notation & display style for modityless entries + commodityless amounts in all files; num- + ber notation: fol- + lowing commodity- + less entries and + entries in that + commodity in all + files; display + style: amounts of + that commodity in + reports + include include entries/directives what the included + from another file directives affect + P declare a market price for a amounts of that + commodity commodity in + reports, when -V is + used + Y declare a year for yearless following + dates inline/included + entries until end + of current file - o some affect all journal entries (and included files) anywhere in the - current file: - account, commodity, D, P. + And some definitions: - It's important to note that directives can affect the current file and - child (included) files, but not sibling or parent (including) files. - This is by design, for simplicity and predictability of reports, but it - can be surprising at times. Eg, in: - hledger -f a.prices -f b.journal + subdirec- optional indented directive or unparsed text lines immedi- + tive ately following a parent directive + account numeric code influencing account display order in most bal- + code ance reports - the prices defined in a.prices will not be effective in b.journal (a - sibling file). Instead, you have to include (or inline) a.prices in - b.journal, or vice versa. + + + 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 + + As you can see, directives vary in which journal entries and files they + affect, and whether they are focussed on input (parsing) or output + (reports). 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- + vides more simplicity and predictability, eg reports are not changed by + 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, @@ -763,14 +826,26 @@ FILE FORMAT account revenues 4000 account expenses 6000 - This affects account display order in reports: accounts with codes are - listed before accounts without codes, in increasing code order. (Oth- - erwise, accounts are listed alphabetically.) Account codes should be - all numeric digits, unique, and separated from the account name by at - least two spaces (since account names may contain single spaces). By - convention, often the first digit indicates the type of account, as in - this numbering scheme and the example above. In future, we might use - this to recognize account types. + This affects how accounts are sorted in account and balance reports: + accounts with codes are listed before accounts without codes, and in + increasing code order (instead of listing all accounts alphabetically). + Warning, this feature is incomplete; account codes do not yet affect + sort order in + + o the accounts command + + o the balance command's single-column mode + + o flat mode balance reports (to work around this, declare account codes + on the subaccounts as well). + + o hledger-web's sidebar + + Account codes should be all numeric digits, unique, and separated from + the account name by at least two spaces (since account names may con- + tain single spaces). By convention, often the first digit indicates + the type of account, as in this numbering scheme and the example above. + In future, we might use this to recognize account types. An account directive can also have indented subdirectives following it, which are currently ignored. Here is the full syntax: @@ -783,9 +858,8 @@ FILE FORMAT some-tag:12345 Rewriting accounts - You can define aliases which rewrite your account names (after reading - the journal, before generating reports). hledger's account aliases can - be useful for: + You can define account alias rules which rewrite your account names, or + parts of them, before generating reports. This can be useful for: o expanding shorthand account names to their full form, allowing easier data entry and a less verbose journal @@ -797,11 +871,15 @@ 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-web. + See also Cookbook: Rewrite account names. Basic aliases - To set an account alias, use the alias directive in your journal file. - This affects all subsequent journal entries in the current file or its + To set an account alias, use the alias directive in your journal file. + This affects all subsequent journal entries in the current file or its included files. The spaces around the = are optional: alias OLD = NEW @@ -809,54 +887,54 @@ FILE FORMAT Or, you can use the --alias 'OLD=NEW' option on the command line. This affects all entries. It's useful for trying out aliases interactively. - OLD and NEW are full account names. hledger will replace any occur- - rence of the old account name with the new one. Subaccounts are also - affected. Eg: + OLD and NEW are case sensitive full account names. hledger will + replace any occurrence of the old account name with the new one. Sub- + accounts are also affected. Eg: alias checking = assets:bank:wells fargo:checking # rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" Regex aliases - There is also a more powerful variant that uses a regular expression, + There is also a more powerful variant that uses a regular expression, indicated by the forward slashes: alias /REGEX/ = REPLACEMENT or --alias '/REGEX/=REPLACEMENT'. - REGEX is a case-insensitive regular expression. Anywhere it matches - inside an account name, the matched part will be replaced by REPLACE- - MENT. If REGEX contains parenthesised match groups, these can be ref- + REGEX is a case-insensitive regular expression. Anywhere it matches + inside an account name, the matched part will be replaced by REPLACE- + MENT. If REGEX contains parenthesised match groups, these can be ref- erenced by the usual numeric backreferences in REPLACEMENT. Eg: alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 # rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" - Also note that REPLACEMENT continues to the end of line (or on command - line, to end of option argument), so it can contain trailing white- + Also note that REPLACEMENT continues to the end of line (or on command + line, to end of option argument), so it can contain trailing white- space. Multiple aliases - You can define as many aliases as you like using directives or com- - mand-line options. Aliases are recursive - each alias sees the result - of applying previous ones. (This is different from Ledger, where + You can define as many aliases as you like using directives or com- + mand-line options. Aliases are recursive - each alias sees the result + of applying previous ones. (This is different from Ledger, where aliases are non-recursive by default). Aliases are applied in the fol- lowing order: - 1. alias directives, most recently seen first (recent directives take + 1. alias directives, most recently seen first (recent directives take precedence over earlier ones; directives not yet seen are ignored) 2. alias options, in the order they appear on the command line end aliases - You can clear (forget) all currently defined aliases with the + You can clear (forget) all currently defined aliases with the end aliases directive: end aliases Default parent account - You can specify a parent account which will be prepended to all - accounts within a section of the journal. Use the apply account and + You can specify a parent account which will be prepended to all + accounts within a section of the journal. Use the apply account and end apply account directives like so: apply account home @@ -873,7 +951,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 @@ -882,19 +960,23 @@ 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 + account. + Periodic transactions Periodic transaction rules describe transactions that recur. They - allow you to generate future transactions for forecast reports (with - --forecast), without having to write them out explicitly in the jour- - nal. Secondly, they also can be used to define budget goals (with - --budget). + allow you to generate future transactions for forecasting, without hav- + ing to write them out explicitly in the journal (with --forecast). + Secondly, they also can be used to define budget goals (with --budget). - A periodic transaction rule looks like a regular journal entry, with - the date replaced by a tilde (~) followed by a period expression - (mnemonic: ~ looks like a repeating sine wave): + A periodic transaction rule looks like a normal journal entry, with the + date replaced by a tilde (~) followed by a period expression (mnemonic: + ~ looks like a repeating sine wave): ~ monthly expenses:rent $2000 @@ -904,9 +986,8 @@ FILE FORMAT 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. - Also, if you write a transaction description or same-line comment, it - must be separated from the period expression by two or more spaces. - Eg: + If you write a transaction description or same-line comment, it must be + separated from the period expression by two or more spaces. Eg: ; 2 or more spaces ; || @@ -915,28 +996,34 @@ FILE FORMAT assets:bank:checking $1500 income:acme inc - Generating forecasts with periodic transactions - With the --forecast flag, each periodic transaction rule generates - future transactions recurring at the specified interval, beginning the - day after the latest recorded journal transaction (or today, if there - are no transactions), and ending 6 months from today (or at the report - end date, if specified). The generated transactions will appear in all - reports. They will have a "recur:" transaction tag added, with the - generating period expression as its value. + Forecasting with periodic transactions + With the --forecast flag, each periodic transaction rule generates + future transactions recurring at the specified interval. These are not + saved in the journal, but appear in all reports. They will look like + normal transactions, but with an extra tag named recur, whose value is + the generating period expression. - This can be useful for forecasting balances into the future, and exper- - imenting with different scenarios, without having to write a lot of - journal entries. It can also help with data entry (describe most of - your transactions with periodic rules, and every so often copy the out- - put of print --forecast to the journal). + Forecast transactions begin on or after the day after the latest normal + (non-periodic) transaction in the journal, or today if there are none. - You can generate one-time transactions too; just write a period expres- - sion specifying a date with no report interval. You could use this to - forecast an estimated transaction, that is automatically deactivated - once the actual transaction (or any other transaction on or after that - date) is recorded. + They end on or before the report end date if specified, or 180 days + from today if unspecified. - Setting budget goals with periodic transactions + 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 + 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 + 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 @@ -951,9 +1038,9 @@ FILE FORMAT Automated posting rules describe extra postings that should be added to certain transactions at report time, when the --auto flag is used. - An automated posting rule looks like a regular journal entry, except - the first line is an equal sign (=) followed by a query (mnemonic: = - looks like posting lines): + An automated posting rule looks like a normal journal entry, except the + first line is an equal sign (=) followed by a query (mnemonic: = looks + like posting lines): = expenses:gifts budget:gifts *-1 @@ -1003,6 +1090,7 @@ EDITOR SUPPORT Textmate https://github.com/ledger/ledger/wiki/Using-TextMate-2 Text Wran- https://github.com/ledger/ledger/wiki/Edit- gler ing-Ledger-files-with-TextWrangler + Visual Stu- https://marketplace.visualstudio.com/items?item- dio Code Name=mark-hansen.hledger-vscode @@ -1031,4 +1119,4 @@ SEE ALSO -hledger 1.9.99 March 2018 hledger_journal(5) +hledger 1.9.99 June 2018 hledger_journal(5) diff --git a/hledger-lib/hledger_timeclock.5 b/hledger-lib/hledger_timeclock.5 index e6f95ebd0..1c8702a5d 100644 --- a/hledger-lib/hledger_timeclock.5 +++ b/hledger-lib/hledger_timeclock.5 @@ -1,5 +1,5 @@ -.TH "hledger_timeclock" "5" "March 2018" "hledger 1.9.99" "hledger User Manuals" +.TH "hledger_timeclock" "5" "June 2018" "hledger 1.9.99" "hledger User Manuals" diff --git a/hledger-lib/hledger_timeclock.txt b/hledger-lib/hledger_timeclock.txt index a825f7fd2..0f694a37f 100644 --- a/hledger-lib/hledger_timeclock.txt +++ b/hledger-lib/hledger_timeclock.txt @@ -77,4 +77,4 @@ SEE ALSO -hledger 1.9.99 March 2018 hledger_timeclock(5) +hledger 1.9.99 June 2018 hledger_timeclock(5) diff --git a/hledger-lib/hledger_timedot.5 b/hledger-lib/hledger_timedot.5 index 355d1fcc9..f389f1787 100644 --- a/hledger-lib/hledger_timedot.5 +++ b/hledger-lib/hledger_timedot.5 @@ -1,5 +1,5 @@ -.TH "hledger_timedot" "5" "March 2018" "hledger 1.9.99" "hledger User Manuals" +.TH "hledger_timedot" "5" "June 2018" "hledger 1.9.99" "hledger User Manuals" diff --git a/hledger-lib/hledger_timedot.txt b/hledger-lib/hledger_timedot.txt index dfb6ed436..23caf20ff 100644 --- a/hledger-lib/hledger_timedot.txt +++ b/hledger-lib/hledger_timedot.txt @@ -124,4 +124,4 @@ SEE ALSO -hledger 1.9.99 March 2018 hledger_timedot(5) +hledger 1.9.99 June 2018 hledger_timedot(5) diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 210f18315..f24cead87 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -1,5 +1,5 @@ -.TH "hledger\-ui" "1" "March 2018" "hledger\-ui 1.9.99" "hledger User Manuals" +.TH "hledger\-ui" "1" "June 2018" "hledger\-ui 1.9.99" "hledger User Manuals" diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index ea601e497..6473435bd 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -384,4 +384,4 @@ SEE ALSO -hledger-ui 1.9.99 March 2018 hledger-ui(1) +hledger-ui 1.9.99 June 2018 hledger-ui(1) diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index 9ec8a46cb..0bfa55750 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -1,5 +1,5 @@ -.TH "hledger\-web" "1" "March 2018" "hledger\-web 1.9.99" "hledger User Manuals" +.TH "hledger\-web" "1" "June 2018" "hledger\-web 1.9.99" "hledger User Manuals" diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index c53e076fe..d0067a7b9 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -248,4 +248,4 @@ SEE ALSO -hledger-web 1.9.99 March 2018 hledger-web(1) +hledger-web 1.9.99 June 2018 hledger-web(1) diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 3a241cf0e..f13bb4e1a 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "hledger" "1" "March 2018" "hledger 1.9.99" "hledger User Manuals" +.TH "hledger" "1" "June 2018" "hledger 1.9.99" "hledger User Manuals" diff --git a/hledger/hledger.txt b/hledger/hledger.txt index b42eff475..b7c798e42 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -2210,4 +2210,4 @@ SEE ALSO -hledger 1.9.99 March 2018 hledger(1) +hledger 1.9.99 June 2018 hledger(1)