From a29b70c93f7321530ca9752d2352d8edc2d7e4b2 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Tue, 22 Jan 2019 13:36:11 -0800 Subject: [PATCH] update generated manuals [ci skip] --- hledger-lib/hledger_journal.5 | 132 ++++++++----- hledger-lib/hledger_journal.info | 192 ++++++++++-------- hledger-lib/hledger_journal.txt | 108 ++++++----- hledger/hledger.1 | 113 ++++++++++- hledger/hledger.info | 202 +++++++++++++------ hledger/hledger.txt | 322 +++++++++++++++++++------------ 6 files changed, 697 insertions(+), 372 deletions(-) diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index d0d0c1e99..e3afcc2a0 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -1189,8 +1189,7 @@ The \f[C]\-V/\-\-value\f[] flag can be used to convert reported amounts to another commodity using these prices. .SS Declaring accounts .PP -\f[C]account\f[] directives can be used to pre\-declare some or all -accounts. +\f[C]account\f[] directives can be used to pre\-declare accounts. Though not required, they can provide several benefits: .IP \[bu] 2 They can document your intended chart of accounts, providing a @@ -1209,38 +1208,86 @@ sorting (eg Revenues to appear above Expenses). They help with account name completion in the add command, hledger\-iadd, hledger\-web, ledger\-mode etc. .PP -Here is the full syntax: -.IP -.nf -\f[C] -account\ ACCTNAME\ \ [ACCTTYPE] -\ \ [COMMENTS] -\f[] -.fi -.PP -The simplest form just declares a hledger\-style account name, eg: +The simplest form is just the word \f[C]account\f[] followed by a +hledger\-style account name, eg: .IP .nf \f[C] account\ assets:bank:checking \f[] .fi +.SS Account comments +.PP +Comments, beginning with a semicolon, optionally including tags, can be +written after the account name, and/or on following lines. +Eg: +.IP +.nf +\f[C] +account\ assets:bank:checking\ \ ;\ a\ comment +\ \ ;\ another\ comment +\ \ ;\ acctno:12345,\ a\ tag +\f[] +.fi +.PP +Tip: comments on the same line require hledger 1.12+. +If you need your journal to be compatible with older hledger versions, +write comments on the next line instead. +.SS Account subdirectives +.PP +We also allow (and ignore) Ledger\-style indented subdirectives, just +for compatibility.: +.IP +.nf +\f[C] +account\ assets:bank:checking +\ \ format\ blah\ blah\ \ ;\ <\-\ subdirective,\ ignored +\f[] +.fi +.PP +Here is the full syntax of account directives: +.IP +.nf +\f[C] +account\ ACCTNAME\ \ [ACCTTYPE]\ [;COMMENT] +\ \ [;COMMENTS] +\ \ [LEDGER\-STYLE\ SUBDIRECTIVES,\ IGNORED] +\f[] +.fi .SS Account types .PP -hledger recognises five types of account: asset, liability, equity, -revenue, expense. -This is useful for certain accounting\-aware reports, in particular -balancesheet, incomestatement and cashflow. +hledger recognises five types (or classes) of account: Asset, Liability, +Equity, Revenue, Expense. +This is used by a few accounting\-aware reports such as balancesheet, +incomestatement and cashflow. +.SS Auto\-detected account types .PP If you name your top\-level accounts with some variation of \f[C]assets\f[], \f[C]liabilities\f[]/\f[C]debts\f[], \f[C]equity\f[], \f[C]revenues\f[]/\f[C]income\f[], or \f[C]expenses\f[], their types are detected automatically. +.SS Account types declared with tags .PP -More generally, you can declare an account's type by adding one of the -letters \f[C]ALERX\f[] to its account directive, separated from the -account name by two or more spaces. -Eg: +More generally, you can declare an account's type with an account +directive, by writing a \f[C]type:\f[] tag in a comment, followed by one +of the words \f[C]Asset\f[], \f[C]Liability\f[], \f[C]Equity\f[], +\f[C]Revenue\f[], \f[C]Expense\f[], or one of the letters \f[C]ALERX\f[] +(case insensitive): +.IP +.nf +\f[C] +account\ assets\ \ \ \ \ \ \ ;\ type:Asset +account\ liabilities\ \ ;\ type:Liability +account\ equity\ \ \ \ \ \ \ ;\ type:Equity +account\ revenues\ \ \ \ \ ;\ type:Revenue +account\ expenses\ \ \ \ \ ;\ type:Expenses +\f[] +.fi +.SS Account types declared with account type codes +.PP +Or, you can write one of those letters separated from the account name +by two or more spaces, but this should probably be considered deprecated +as of hledger 1.13: .IP .nf \f[C] @@ -1251,46 +1298,29 @@ account\ revenues\ \ \ \ \ R account\ expenses\ \ \ \ \ X \f[] .fi +.SS Overriding auto\-detected types .PP -Note: if you ever override the types of those auto\-detected english -account names mentioned above, you might need to help the reports a bit: +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: .IP .nf \f[C] -;\ make\ "liabilities"\ not\ have\ the\ liability\ type,\ who\ knows\ why -account\ liabilities\ \ \ E +;\ make\ "liabilities"\ not\ have\ the\ liability\ type\ \-\ who\ knows\ why +account\ liabilities\ \ \ ;\ type:E -;\ better\ ensure\ some\ other\ account\ has\ the\ liability\ type,\ +;\ we\ need\ to\ ensure\ some\ other\ account\ has\ the\ liability\ type,\ ;\ otherwise\ balancesheet\ would\ still\ show\ "liabilities"\ under\ Liabilities\ -account\ \-\ \ \ \ \ \ \ \ \ \ \ \ \ L +account\ \-\ \ \ \ \ \ \ \ \ \ \ \ \ ;\ type:L \f[] .fi -.PP -) -.SS Account comments -.PP -An account directive can also have indented comments on following lines, -eg: -.IP -.nf -\f[C] -account\ assets:bank:checking -\ \ ;\ acctno:12345 -\ \ ;\ a\ comment -\f[] -.fi -.PP -We also allow (and ignore) Ledger\-style subdirectives, with no leading -semicolon, for compatibility. -.PP -Tags in account comments, like \f[C]acctno\f[] above, currently have no -effect. .SS Account display order .PP -Account directives also set the order in which accounts are displayed in -reports, the hledger\-ui accounts screen, the hledger\-web sidebar, etc. -Normally accounts are listed in alphabetical order, but if you have eg -these account directives in the journal: +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: .IP .nf \f[C] @@ -1302,7 +1332,7 @@ account\ expenses \f[] .fi .PP -you'll see those accounts listed in declaration order, not +you'll see those accounts displayed in declaration order, not alphabetically: .IP .nf diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index 2ffba36e2..69470b6f4 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -1055,8 +1055,8 @@ File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts 1.14.7 Declaring accounts ------------------------- -'account' directives can be used to pre-declare some or all accounts. -Though not required, they can provide several benefits: +'account' directives can be used to pre-declare accounts. Though not +required, they can provide several benefits: * They can document your intended chart of accounts, providing a reference. @@ -1070,38 +1070,80 @@ Though not required, they can provide several benefits: * They help with account name completion in the add command, hledger-iadd, hledger-web, ledger-mode etc. - Here is the full syntax: - -account ACCTNAME [ACCTTYPE] - [COMMENTS] - - The simplest form just declares a hledger-style account name, eg: + The simplest form is just the word 'account' followed by a +hledger-style account name, eg: account assets:bank:checking * Menu: -* Account types:: * Account comments:: +* Account subdirectives:: +* Account types:: * Account display order::  -File: hledger_journal.info, Node: Account types, Next: Account comments, Up: Declaring accounts +File: hledger_journal.info, Node: Account comments, Next: Account subdirectives, Up: Declaring accounts -1.14.7.1 Account types +1.14.7.1 Account comments +......................... + +Comments, beginning with a semicolon, optionally including tags, can be +written after the account name, and/or on following lines. Eg: + +account assets:bank:checking ; a comment + ; another comment + ; acctno:12345, a tag + + Tip: comments on the same line require hledger 1.12+. If you need +your journal to be compatible with older hledger versions, write +comments on the next line instead. + + +File: hledger_journal.info, Node: Account subdirectives, Next: Account types, Prev: Account comments, Up: Declaring accounts + +1.14.7.2 Account subdirectives +.............................. + +We also allow (and ignore) Ledger-style indented subdirectives, just for +compatibility.: + +account assets:bank:checking + format blah blah ; <- subdirective, ignored + + Here is the full syntax of account directives: + +account ACCTNAME [ACCTTYPE] [;COMMENT] + [;COMMENTS] + [LEDGER-STYLE SUBDIRECTIVES, IGNORED] + + +File: hledger_journal.info, Node: Account types, Next: Account display order, Prev: Account subdirectives, Up: Declaring accounts + +1.14.7.3 Account types ...................... -hledger recognises five types of account: asset, liability, equity, -revenue, expense. This is useful for certain accounting-aware reports, -in particular balancesheet, incomestatement and cashflow. +hledger recognises five types (or classes) of account: Asset, Liability, +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', 'liabilities'/'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 directive, 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): - If you name your top-level accounts with some variation of 'assets', -'liabilities'/'debts', 'equity', 'revenues'/'income', or 'expenses', -their types are detected automatically. +account assets ; type:Asset +account liabilities ; type:Liability +account equity ; type:Equity +account revenues ; type:Revenue +account expenses ; type:Expenses - More generally, you can declare an account's type by adding one of -the letters 'ALERX' to its account directive, separated from the account -name by two or more spaces. Eg: + 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 deprecated as of hledger 1.13: account assets A account liabilities L @@ -1109,47 +1151,27 @@ account equity E account revenues R account expenses X - Note: if you ever override the types of those auto-detected english -account names mentioned above, you might need to help the reports a bit: + Overriding auto-detected types 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 -account liabilities E +; make "liabilities" not have the liability type - who knows why +account liabilities ; type:E -; better ensure some other account has the liability type, +; we need to ensure some other account has the liability type, ; otherwise balancesheet would still show "liabilities" under Liabilities -account - L - - ) +account - ; type:L  -File: hledger_journal.info, Node: Account comments, Next: Account display order, Prev: Account types, Up: Declaring accounts +File: hledger_journal.info, Node: Account display order, Prev: Account types, Up: Declaring accounts -1.14.7.2 Account comments -......................... - -An account directive can also have indented comments on following lines, -eg: - -account assets:bank:checking - ; acctno:12345 - ; a comment - - We also allow (and ignore) Ledger-style subdirectives, with no -leading semicolon, for compatibility. - - Tags in account comments, like 'acctno' above, currently have no -effect. - - -File: hledger_journal.info, Node: Account display order, Prev: Account comments, Up: Declaring accounts - -1.14.7.3 Account display order +1.14.7.4 Account display order .............................. -Account directives also set the order in which accounts are displayed in -reports, the hledger-ui accounts screen, the hledger-web sidebar, etc. -Normally accounts are listed in alphabetical order, but if you have eg -these account directives in the journal: +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: account assets account liabilities @@ -1157,7 +1179,7 @@ account equity account revenues account expenses - you'll see those accounts listed in declaration order, not + you'll see those accounts displayed in declaration order, not alphabetically: $ hledger accounts -1 @@ -1605,35 +1627,37 @@ Node: Market prices38745 Ref: #market-prices38910 Node: Declaring accounts39751 Ref: #declaring-accounts39927 -Node: Account types40884 -Ref: #account-types41033 -Node: Account comments42107 -Ref: #account-comments42292 -Node: Account display order42613 -Ref: #account-display-order42786 -Node: Rewriting accounts43908 -Ref: #rewriting-accounts44093 -Node: Basic aliases44827 -Ref: #basic-aliases44973 -Node: Regex aliases45677 -Ref: #regex-aliases45848 -Node: Multiple aliases46566 -Ref: #multiple-aliases46741 -Node: end aliases47239 -Ref: #end-aliases47386 -Node: Default parent account47487 -Ref: #default-parent-account47653 -Node: Periodic transactions48537 -Ref: #periodic-transactions48719 -Node: Two spaces after the period expression49844 -Ref: #two-spaces-after-the-period-expression50089 -Node: Forecasting with periodic transactions50574 -Ref: #forecasting-with-periodic-transactions50864 -Node: Budgeting with periodic transactions52551 -Ref: #budgeting-with-periodic-transactions52790 -Node: Transaction Modifiers53249 -Ref: #transaction-modifiers53412 -Node: EDITOR SUPPORT55393 -Ref: #editor-support55511 +Node: Account comments40852 +Ref: #account-comments41015 +Node: Account subdirectives41410 +Ref: #account-subdirectives41605 +Node: Account types41918 +Ref: #account-types42102 +Node: Account display order43746 +Ref: #account-display-order43916 +Node: Rewriting accounts45045 +Ref: #rewriting-accounts45230 +Node: Basic aliases45964 +Ref: #basic-aliases46110 +Node: Regex aliases46814 +Ref: #regex-aliases46985 +Node: Multiple aliases47703 +Ref: #multiple-aliases47878 +Node: end aliases48376 +Ref: #end-aliases48523 +Node: Default parent account48624 +Ref: #default-parent-account48790 +Node: Periodic transactions49674 +Ref: #periodic-transactions49856 +Node: Two spaces after the period expression50981 +Ref: #two-spaces-after-the-period-expression51226 +Node: Forecasting with periodic transactions51711 +Ref: #forecasting-with-periodic-transactions52001 +Node: Budgeting with periodic transactions53688 +Ref: #budgeting-with-periodic-transactions53927 +Node: Transaction Modifiers54386 +Ref: #transaction-modifiers54549 +Node: EDITOR SUPPORT56530 +Ref: #editor-support56648  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index 88d751e35..1b1cf1d51 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -846,8 +846,8 @@ FILE FORMAT commodity using these prices. Declaring accounts - account directives can be used to pre-declare some or all accounts. - Though not required, they can provide several benefits: + account directives can be used to pre-declare accounts. Though not + required, they can provide several benefits: o They can document your intended chart of accounts, providing a refer- ence. @@ -865,27 +865,62 @@ FILE FORMAT o They help with account name completion in the add command, hledger-iadd, hledger-web, ledger-mode etc. - Here is the full syntax: - - account ACCTNAME [ACCTTYPE] - [COMMENTS] - - The simplest form just declares a hledger-style account name, eg: + The simplest form is just the word account followed by a hledger-style + account name, eg: account assets:bank:checking - Account types - hledger recognises five types of account: asset, liability, equity, - revenue, expense. This is useful for certain accounting-aware reports, - in particular balancesheet, incomestatement and cashflow. + Account comments + Comments, beginning with a semicolon, optionally including tags, can be + written after the account name, and/or on following lines. Eg: + account assets:bank:checking ; a comment + ; another comment + ; acctno:12345, a tag + + Tip: comments on the same line require hledger 1.12+. If you need your + journal to be compatible with older hledger versions, write comments on + the next line instead. + + Account subdirectives + We also allow (and ignore) Ledger-style indented subdirectives, just + for compatibility.: + + account assets:bank:checking + format blah blah ; <- subdirective, ignored + + Here is the full syntax of account directives: + + account ACCTNAME [ACCTTYPE] [;COMMENT] + [;COMMENTS] + [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 + 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. - More generally, you can declare an account's type by adding one of the - letters ALERX to its account directive, separated from the account name - by two or more spaces. Eg: + Account types declared with tags + More generally, you can declare an account's type with an account + directive, 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): + + account assets ; type:Asset + account liabilities ; type:Liability + account equity ; type:Equity + account revenues ; type:Revenue + 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- + cated as of hledger 1.13: account assets A account liabilities L @@ -893,37 +928,22 @@ FILE FORMAT account revenues R account expenses X - Note: if you ever override the types of those auto-detected english - account names mentioned above, you might need to help the reports a - bit: + Overriding auto-detected types + 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 - account liabilities E + ; make "liabilities" not have the liability type - who knows why + account liabilities ; type:E - ; better ensure some other account has the liability type, + ; we need to ensure some other account has the liability type, ; otherwise balancesheet would still show "liabilities" under Liabilities - account - L - - ) - - Account comments - An account directive can also have indented comments on following - lines, eg: - - account assets:bank:checking - ; acctno:12345 - ; a comment - - We also allow (and ignore) Ledger-style subdirectives, with no leading - semicolon, for compatibility. - - Tags in account comments, like acctno above, currently have no effect. + account - ; type:L Account display order - Account directives also set the order in which accounts are displayed - in reports, the hledger-ui accounts screen, the hledger-web sidebar, - etc. Normally accounts are listed in alphabetical order, but if you - have eg these account directives in the journal: + 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: account assets account liabilities @@ -931,8 +951,8 @@ FILE FORMAT account revenues account expenses - you'll see those accounts listed in declaration order, not alphabeti- - cally: + you'll see those accounts displayed in declaration order, not alphabet- + ically: $ hledger accounts -1 assets diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 7d94e20c4..184c38314 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -2318,13 +2318,112 @@ Report account names having the same leaf but different prefixes. An example: http://stefanorodighiero.net/software/hledger\-dupes.html .SS close .PP -Print closing/opening transactions that bring some or all account -balances to zero and back. -Can be useful for bringing asset/liability balances across file -boundaries, or for closing out income/expenses for a period. -This was formerly called \[lq]equity\[rq], as in Ledger, and that alias -is also accepted. -See close \[en]help for more. +close, equity +.PP +Prints a \[lq]closing balances\[rq] transaction and an \[lq]opening +balances\[rq] transaction, that bring account balances to and from zero, +respectively. +Useful for, eg: +.IP \[bu] 2 +bringing asset/liability balances forward into a new journal file +.IP \[bu] 2 +closing out revenues/expenses to retained earnings at the end of a +period +.PP +The closing transaction transfers balances to \[lq]equity:closing +balances\[rq]. +The opening transaction transfers balances from \[lq]equity:opening +balances\[rq]. +You can chose to print just one of the transactions by using the +\f[C]\-\-opening\f[] or \f[C]\-\-closing\f[] flag. +.PP +If you split your journal files by time (eg yearly), you will typically +run this command at the end of the year, and save the closing +transaction as last entry of the old file, and the opening transaction +as the first entry of the new file. +This makes the files self contained, so that correct balances are +reported no matter which of them are loaded. +Ie, if you load just one file, the balances are initialised correctly; +or if you load several files, the redundant closing/opening transactions +cancel each other out. +(They will show up in print or register reports; you can exclude them +with a query like +\f[C]not:desc:\[aq](opening|closing)\ balances\[aq]\f[].) +.PP +If you're running a business, you might also use this command to +\[lq]close the books\[rq] at the end of an accounting period, +transferring income statement account balances to retained earnings. +(You may want to change the equity account name to something like +\[lq]equity:retained earnings\[rq] for clarity.) +.PP +By default, the closing transaction is dated yesterday, the balances are +calculated as of end of yesterday, and the opening transaction is dated +today. +To close on some other date, use: +\f[C]hledger\ close\ \-e\ OPENINGDATE\f[]. +Eg, to close/open on the 2018/2019 boundary, use \f[C]\-e\ 2019\f[]. +You can also use \-p or \f[C]date:PERIOD\f[] (any starting date is +ignored). +.PP +Both transactions will include balance assertions for the +closed/reopened accounts. +You probably shouldn't use status or realness filters (like \-C or \-R +or \f[C]status:\f[]) with this command, or the generated balance +assertions will depend on these flags. +Likewise, if you run this command with \[en]auto, the balance assertions +will probably always require \[en]auto. +.PP +Examples: +.PP +Carrying asset/liability balances into a new file for 2019, all from +command line. +.PP +\f[I]Warning: we use \f[CI]>>\f[I] here to append; be careful not to +type a single \f[CI]>\f[I] which would wipe your journal!\f[] +.IP +.nf +\f[C] +$\ hledger\ close\ \-f\ 2018.journal\ \-e\ 2019\ assets\ liabilities\ \-\-opening\ >>2019.journal +$\ hledger\ close\ \-f\ 2018.journal\ \-e\ 2019\ assets\ liabilities\ \-\-closing\ >>2018.journal +\f[] +.fi +.PP +Now: +.IP +.nf +\f[C] +$\ hledger\ bs\ \-f\ 2019.journal\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ one\ file\ \-\ balances\ are\ correct +$\ hledger\ bs\ \-f\ 2018.journal\ \-f\ 2019.journal\ \ \ #\ two\ files\ \-\ balances\ still\ correct +$\ hledger\ bs\ \-f\ 2018.journal\ not:desc:closing\ \ #\ to\ see\ year\-end\ balances,\ must\ exclude\ closing\ txn +\f[] +.fi +.PP +Transactions spanning the closing date can complicate matters, breaking +balance assertions: +.IP +.nf +\f[C] +2018/12/30\ a\ purchase\ made\ in\ 2018,\ clearing\ the\ following\ year +\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ 5 +\ \ \ \ assets:bank:checking\ \ \-5\ \ ;\ [2019/1/2] +\f[] +.fi +.PP +Here's one way to resolve that: +.IP +.nf +\f[C] +;\ in\ 2018.journal: +2018/12/30\ a\ purchase\ made\ in\ 2018,\ clearing\ the\ following\ year +\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ 5 +\ \ \ \ liabilities:pending + +;\ in\ 2019.journal: +2019/1/2\ clearance\ of\ last\ year\[aq]s\ pending\ transactions +\ \ \ \ liabilities:pending\ \ \ \ 5\ =\ 0 +\ \ \ \ assets:checking +\f[] +.fi .SS files .PP List all files included in the journal. diff --git a/hledger/hledger.info b/hledger/hledger.info index 6621b5e2c..acda77529 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -1851,11 +1851,87 @@ File: hledger.info, Node: close, Next: files, Prev: check-dupes, Up: COMMAND 4.10 close ========== -Print closing/opening transactions that bring some or all account -balances to zero and back. Can be useful for bringing asset/liability -balances across file boundaries, or for closing out income/expenses for -a period. This was formerly called "equity", as in Ledger, and that -alias is also accepted. See close -help for more. +close, equity + + Prints a "closing balances" transaction and an "opening balances" +transaction, that bring account balances to and from zero, respectively. +Useful for, eg: + + * bringing asset/liability balances forward into a new journal file + * closing out revenues/expenses to retained earnings at the end of a + period + + The closing transaction transfers balances to "equity:closing +balances". The opening transaction transfers balances from +"equity:opening balances". You can chose to print just one of the +transactions by using the '--opening' or '--closing' flag. + + If you split your journal files by time (eg yearly), you will +typically run this command at the end of the year, and save the closing +transaction as last entry of the old file, and the opening transaction +as the first entry of the new file. This makes the files self +contained, so that correct balances are reported no matter which of them +are loaded. Ie, if you load just one file, the balances are initialised +correctly; or if you load several files, the redundant closing/opening +transactions cancel each other out. (They will show up in print or +register reports; you can exclude them with a query like +'not:desc:'(opening|closing) balances''.) + + If you're running a business, you might also use this command to +"close the books" at the end of an accounting period, transferring +income statement account balances to retained earnings. (You may want +to change the equity account name to something like "equity:retained +earnings" for clarity.) + + By default, the closing transaction is dated yesterday, the balances +are calculated as of end of yesterday, and the opening transaction is +dated today. To close on some other date, use: 'hledger close -e +OPENINGDATE'. Eg, to close/open on the 2018/2019 boundary, use '-e +2019'. You can also use -p or 'date:PERIOD' (any starting date is +ignored). + + Both transactions will include balance assertions for the +closed/reopened accounts. You probably shouldn't use status or realness +filters (like -C or -R or 'status:') with this command, or the generated +balance assertions will depend on these flags. Likewise, if you run +this command with -auto, the balance assertions will probably always +require -auto. + + Examples: + + Carrying asset/liability balances into a new file for 2019, all from +command line. + + _Warning: we use '>>' here to append; be careful not to type a single +'>' which would wipe your journal!_ + +$ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal +$ hledger close -f 2018.journal -e 2019 assets liabilities --closing >>2018.journal + + Now: + +$ hledger bs -f 2019.journal # one file - balances are correct +$ hledger bs -f 2018.journal -f 2019.journal # two files - balances still correct +$ hledger bs -f 2018.journal not:desc:closing # to see year-end balances, must exclude closing txn + + Transactions spanning the closing date can complicate matters, +breaking balance assertions: + +2018/12/30 a purchase made in 2018, clearing the following year + expenses:food 5 + assets:bank:checking -5 ; [2019/1/2] + + Here's one way to resolve that: + +; in 2018.journal: +2018/12/30 a purchase made in 2018, clearing the following year + expenses:food 5 + liabilities:pending + +; in 2019.journal: +2019/1/2 clearance of last year's pending transactions + liabilities:pending 5 = 0 + assets:checking  File: hledger.info, Node: files, Next: help, Prev: close, Up: COMMANDS @@ -2643,63 +2719,63 @@ Node: check-dupes61080 Ref: #check-dupes61204 Node: close61341 Ref: #close61449 -Node: files61779 -Ref: #files61880 -Node: help62021 -Ref: #help62121 -Node: import63195 -Ref: #import63309 -Node: incomestatement64039 -Ref: #incomestatement64173 -Node: prices66577 -Ref: #prices66692 -Node: print66964 -Ref: #print67074 -Node: print-unique71968 -Ref: #print-unique72094 -Node: register72162 -Ref: #register72289 -Node: Custom register output76790 -Ref: #custom-register-output76919 -Node: register-match78149 -Ref: #register-match78283 -Node: rewrite78466 -Ref: #rewrite78581 -Node: roi78650 -Ref: #roi78748 -Node: stats78864 -Ref: #stats78963 -Node: tags79833 -Ref: #tags79931 -Node: test80167 -Ref: #test80251 -Node: ADD-ON COMMANDS80959 -Ref: #add-on-commands81069 -Node: Official add-ons82356 -Ref: #official-add-ons82496 -Node: api82583 -Ref: #api82672 -Node: ui82724 -Ref: #ui82823 -Node: web82881 -Ref: #web82970 -Node: Third party add-ons83016 -Ref: #third-party-add-ons83191 -Node: diff83326 -Ref: #diff83423 -Node: iadd83522 -Ref: #iadd83636 -Node: interest83719 -Ref: #interest83840 -Node: irr83935 -Ref: #irr84033 -Node: Experimental add-ons84164 -Ref: #experimental-add-ons84316 -Node: autosync84596 -Ref: #autosync84707 -Node: chart84946 -Ref: #chart85065 -Node: check85136 -Ref: #check85238 +Node: files64891 +Ref: #files64992 +Node: help65133 +Ref: #help65233 +Node: import66307 +Ref: #import66421 +Node: incomestatement67151 +Ref: #incomestatement67285 +Node: prices69689 +Ref: #prices69804 +Node: print70076 +Ref: #print70186 +Node: print-unique75080 +Ref: #print-unique75206 +Node: register75274 +Ref: #register75401 +Node: Custom register output79902 +Ref: #custom-register-output80031 +Node: register-match81261 +Ref: #register-match81395 +Node: rewrite81578 +Ref: #rewrite81693 +Node: roi81762 +Ref: #roi81860 +Node: stats81976 +Ref: #stats82075 +Node: tags82945 +Ref: #tags83043 +Node: test83279 +Ref: #test83363 +Node: ADD-ON COMMANDS84071 +Ref: #add-on-commands84181 +Node: Official add-ons85468 +Ref: #official-add-ons85608 +Node: api85695 +Ref: #api85784 +Node: ui85836 +Ref: #ui85935 +Node: web85993 +Ref: #web86082 +Node: Third party add-ons86128 +Ref: #third-party-add-ons86303 +Node: diff86438 +Ref: #diff86535 +Node: iadd86634 +Ref: #iadd86748 +Node: interest86831 +Ref: #interest86952 +Node: irr87047 +Ref: #irr87145 +Node: Experimental add-ons87276 +Ref: #experimental-add-ons87428 +Node: autosync87708 +Ref: #autosync87819 +Node: chart88058 +Ref: #chart88177 +Node: check88248 +Ref: #check88350  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index ebd41094f..5f1ebe1f3 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -1646,26 +1646,102 @@ COMMANDS example: http://stefanorodighiero.net/software/hledger-dupes.html close - Print closing/opening transactions that bring some or all account bal- - ances to zero and back. Can be useful for bringing asset/liability - balances across file boundaries, or for closing out income/expenses for - a period. This was formerly called "equity", as in Ledger, and that - alias is also accepted. See close -help for more. + close, equity + + Prints a "closing balances" transaction and an "opening balances" + transaction, that bring account balances to and from zero, respec- + tively. Useful for, eg: + + o bringing asset/liability balances forward into a new journal file + + o closing out revenues/expenses to retained earnings at the end of a + period + + The closing transaction transfers balances to "equity:closing bal- + ances". The opening transaction transfers balances from "equity:open- + ing balances". You can chose to print just one of the transactions by + using the --opening or --closing flag. + + If you split your journal files by time (eg yearly), you will typically + run this command at the end of the year, and save the closing transac- + tion as last entry of the old file, and the opening transaction as the + first entry of the new file. This makes the files self contained, so + that correct balances are reported no matter which of them are loaded. + Ie, if you load just one file, the balances are initialised correctly; + or if you load several files, the redundant closing/opening transac- + tions cancel each other out. (They will show up in print or register + reports; you can exclude them with a query like not:desc:'(open- + ing|closing) balances'.) + + If you're running a business, you might also use this command to "close + the books" at the end of an accounting period, transferring income + statement account balances to retained earnings. (You may want to + change the equity account name to something like "equity:retained earn- + ings" for clarity.) + + By default, the closing transaction is dated yesterday, the balances + are calculated as of end of yesterday, and the opening transaction is + dated today. To close on some other date, use: hledger close -e OPEN- + INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. + You can also use -p or date:PERIOD (any starting date is ignored). + + Both transactions will include balance assertions for the + closed/reopened accounts. You probably shouldn't use status or real- + ness filters (like -C or -R or status:) with this command, or the gen- + erated balance assertions will depend on these flags. Likewise, if you + run this command with -auto, the balance assertions will probably + always require -auto. + + Examples: + + Carrying asset/liability balances into a new file for 2019, all from + command line. + + Warning: we use >> here to append; be careful not to type a single > + which would wipe your journal! + + $ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal + $ hledger close -f 2018.journal -e 2019 assets liabilities --closing >>2018.journal + + Now: + + $ hledger bs -f 2019.journal # one file - balances are correct + $ hledger bs -f 2018.journal -f 2019.journal # two files - balances still correct + $ hledger bs -f 2018.journal not:desc:closing # to see year-end balances, must exclude closing txn + + Transactions spanning the closing date can complicate matters, breaking + balance assertions: + + 2018/12/30 a purchase made in 2018, clearing the following year + expenses:food 5 + assets:bank:checking -5 ; [2019/1/2] + + Here's one way to resolve that: + + ; in 2018.journal: + 2018/12/30 a purchase made in 2018, clearing the following year + expenses:food 5 + liabilities:pending + + ; in 2019.journal: + 2019/1/2 clearance of last year's pending transactions + liabilities:pending 5 = 0 + assets:checking files - List all files included in the journal. With a REGEX argument, only - file names matching the regular expression (case sensitive) are shown. + List all files included in the journal. With a REGEX argument, only + file names matching the regular expression (case sensitive) are shown. help Show any of the hledger manuals. - The help command displays any of the main hledger manuals, in one of - several ways. Run it with no argument to list the manuals, or provide + The help command displays any of the main hledger manuals, in one of + several ways. Run it with no argument to list the manuals, or provide a full or partial manual name to select one. - hledger manuals are available in several formats. hledger help will - use the first of these display methods that it finds: info, man, - $PAGER, less, stdout (or when non-interactive, just stdout). You can + hledger manuals are available in several formats. hledger help will + use the first of these display methods that it finds: info, man, + $PAGER, less, stdout (or when non-interactive, just stdout). You can force a particular viewer with the --info, --man, --pager, --cat flags. $ hledger help @@ -1689,7 +1765,7 @@ COMMANDS ... import - Read new transactions added to each FILE since last run, and add them + Read new transactions added to each FILE since last run, and add them to the main journal file. --dry-run @@ -1699,28 +1775,28 @@ COMMANDS each one. So eg to add new transactions from all CSV files to the main journal, it's just: hledger import *.csv - New transactions are detected in the same way as print -new: by assum- + New transactions are detected in the same way as print -new: by assum- ing transactions are always added to the input files in increasing date order, and by saving .latest.FILE state files. - The -dry-run output is in journal format, so you can filter it, eg to + The -dry-run output is in journal format, so you can filter it, eg to see only uncategorised transactions: $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions incomestatement - This command displays a simple income statement, showing revenues and - expenses during a period. It assumes that these accounts are under a - top-level revenue or income or expense account (case insensitive, plu- - ral forms also allowed). Note this report shows all account balances - with normal positive sign (like conventional financial statements, + This command displays a simple income statement, showing revenues and + expenses during a period. It assumes that these accounts are under a + top-level revenue or income or expense account (case insensitive, plu- + ral forms also allowed). Note this report shows all account balances + with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). (is) --change show balance change in each period (default) --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports), instead of changes during periods -H --historical @@ -1754,8 +1830,8 @@ COMMANDS --sort-amount sort by amount instead of account code/name - This command displays a simple income statement. It currently assumes - that you have top-level accounts named income (or revenue) and expense + This command displays a simple income statement. It currently assumes + that you have top-level accounts named income (or revenue) and expense (plural forms also allowed.) $ hledger incomestatement @@ -1780,16 +1856,16 @@ COMMANDS 0 With a reporting interval, multiple columns will be shown, one for each - report period. Normally incomestatement shows revenues/expenses per - period, though as with multicolumn balance reports you can alter the + report period. Normally incomestatement shows revenues/expenses per + period, though as with multicolumn balance reports you can alter the report mode with --change/--cumulative/--historical. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. prices - Print market price directives from the journal. With -costs, also - print synthetic market prices based on transaction prices. With + Print market price directives from the journal. With -costs, also + print synthetic market prices based on transaction prices. With -inverted-costs, also print inverse prices based on transaction prices. Prices (and postings providing prices) can be filtered by a query. @@ -1797,7 +1873,7 @@ COMMANDS Show transactions from the journal. Aliases: p, txns. -m STR --match=STR - show the transaction whose description is most similar to STR, + show the transaction whose description is most similar to STR, and is most recent --new show only newer-dated transactions added in each file since last @@ -1810,7 +1886,7 @@ COMMANDS select the output format. Supported formats: txt, csv. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. $ hledger print @@ -1841,39 +1917,39 @@ COMMANDS it does not preserve directives or inter-transaction comments Normally, the journal entry's explicit or implicit amount style is pre- - served. Ie when an amount is omitted in the journal, it will be omit- - ted in the output. You can use the -x/--explicit flag to make all + served. Ie when an amount is omitted in the journal, it will be omit- + ted in the output. You can use the -x/--explicit flag to make all amounts explicit, which can be useful for troubleshooting or for making your journal more readable and robust against data entry errors. Note, - -x will cause postings with a multi-commodity amount (these can arise - when a multi-commodity transaction has an implicit amount) will be - split into multiple single-commodity postings, for valid journal out- + -x will cause postings with a multi-commodity amount (these can arise + when a multi-commodity transaction has an implicit amount) will be + split into multiple single-commodity postings, for valid journal out- put. - With -B/--cost, amounts with transaction prices are converted to cost + With -B/--cost, amounts with transaction prices are converted to cost using that price. This can be used for troubleshooting. - With -m/--match and a STR argument, print will show at most one trans- - action: the one one whose description is most similar to STR, and is - most recent. STR should contain at least two characters. If there is + With -m/--match and a STR argument, print will show at most one trans- + action: the one one whose description is most similar to STR, and is + most recent. STR should contain at least two characters. If there is no similar-enough match, no transaction will be shown. With --new, for each FILE being read, hledger reads (and writes) a spe- - cial state file (.latest.FILE in the same directory), containing the - latest transaction date(s) that were seen last time FILE was read. - When this file is found, only transactions with newer dates (and new - transactions on the latest date) are printed. This is useful for - ignoring already-seen entries in import data, such as downloaded CSV + cial state file (.latest.FILE in the same directory), containing the + latest transaction date(s) that were seen last time FILE was read. + When this file is found, only transactions with newer dates (and new + transactions on the latest date) are printed. This is useful for + ignoring already-seen entries in import data, such as downloaded CSV files. Eg: $ hledger -f bank1.csv print --new # shows transactions added since last print --new on this file - This assumes that transactions added to FILE always have same or - increasing dates, and that transactions on the same day do not get + This assumes that transactions added to FILE always have same or + increasing dates, and that transactions on the same day do not get reordered. See also the import command. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. Here's an example of print's CSV output: $ hledger print -Ocsv @@ -1890,20 +1966,20 @@ COMMANDS "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - o There is one CSV record per posting, with the parent transaction's + o There is one CSV record per posting, with the parent transaction's fields repeated. o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different order, etc.) - o The amount is separated into "commodity" (the symbol) and "amount" + o The amount is separated into "commodity" (the symbol) and "amount" (numeric quantity) fields. o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or greater amounts under debit.) print-unique @@ -1916,7 +1992,7 @@ COMMANDS show running total from report start date (default) -H --historical - show historical running total/balance (includes postings before + show historical running total/balance (includes postings before report start date) -A --average @@ -1927,18 +2003,18 @@ COMMANDS show postings' siblings instead -w N --width=N - set output width (default: terminal width or COLUMNS. -wN,M + set output width (default: terminal width or COLUMNS. -wN,M sets description width as well) -O FMT --output-format=FMT select the output format. Supported formats: txt, csv. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. The register command displays postings, one per line, and their running - total. This is typically used with a query selecting a particular + total. This is typically used with a query selecting a particular account, to see that account's activity: $ hledger register checking @@ -1947,8 +2023,8 @@ COMMANDS 2008/06/02 save assets:bank:checking $-1 $1 2008/12/31 pay off assets:bank:checking $-1 0 - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see only recent activity, with a historically accurate running balance: $ hledger register checking -b 2008/6 --historical @@ -1958,23 +2034,23 @@ COMMANDS The --depth option limits the amount of sub-account detail displayed. - The --average/-A flag shows the running average posting amount instead + The --average/-A flag shows the running average posting amount instead of the running total (so, the final number displayed is the average for - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one account and one commodity. - The --related/-r flag shows the other postings in the transactions of + The --related/-r flag shows the other postings in the transactions of the postings which would normally be shown. - With a reporting interval, register shows summary postings, one per + With a reporting interval, register shows summary postings, one per interval, aggregating the postings to each account: $ hledger register --monthly income 2008/01 income:salary $-1 $-1 2008/06 income:gifts $-1 $-2 - Periods with no activity, and summary postings with a zero amount, are + Periods with no activity, and summary postings with a zero amount, are not shown by default; use the --empty/-E flag to see them: $ hledger register --monthly income -E @@ -1991,7 +2067,7 @@ COMMANDS 2008/11 0 $-2 2008/12 0 $-2 - Often, you'll want to see just one line per interval. The --depth + Often, you'll want to see just one line per interval. The --depth option helps with this, causing subaccounts to be aggregated: $ hledger register --monthly assets --depth 1h @@ -1999,18 +2075,18 @@ COMMANDS 2008/06 assets $-1 0 2008/12 assets $-1 $-1 - Note when using report intervals, if you specify start/end dates these - will be adjusted outward if necessary to contain a whole number of - intervals. This ensures that the first and last intervals are full + Note when using report intervals, if you specify start/end dates these + will be adjusted outward if necessary to contain a whole number of + intervals. This ensures that the first and last intervals are full length and comparable to the others in the report. Custom register output - register uses the full terminal width by default, except on windows. - You can override this by setting the COLUMNS environment variable (not + register uses the full terminal width by default, except on windows. + You can override this by setting the COLUMNS environment variable (not a bash shell variable) or by using the --width/-w option. - The description and account columns normally share the space equally - (about half of (width - 40) each). You can adjust this by adding a + The description and account columns normally share the space equally + (about half of (width - 40) each). You can adjust this by adding a description width as part of -width's argument, comma-separated: --width W,D . Here's a diagram: @@ -2027,26 +2103,26 @@ COMMANDS $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, and set description width - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. register-match Print the one posting whose transaction description is closest to DESC, - in the style of the register command. Helps ledger-autosync detect + in the style of the register command. Helps ledger-autosync detect already-seen transactions when importing. rewrite Print all transactions, adding custom postings to the matched ones. roi - Shows time-weighted (TWR) and money-weighted (IRR) rate of return on + Shows time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. See roi --help for more. stats Show some journal statistics. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. $ hledger stats @@ -2061,61 +2137,61 @@ COMMANDS Accounts : 8 (depth 3) Commodities : 1 ($) - The stats command displays summary information for the whole journal, - or a matched part of it. With a reporting interval, it shows a report + The stats command displays summary information for the whole journal, + or a matched part of it. With a reporting interval, it shows a report for each report period. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. tags - List all the tag names used in the journal. With a TAGREGEX argument, - only tag names matching the regular expression (case insensitive) are + List all the tag names used in the journal. With a TAGREGEX argument, + only tag names matching the regular expression (case insensitive) are shown. With additional QUERY arguments, only transactions matching the query are considered. test Run built-in unit tests. - Prints test names and their results on stdout. If any test fails or + Prints test names and their results on stdout. If any test fails or gives an error, the exit code will be non-zero. - Test names include a group prefix. If a (exact, case sensitive) group - prefix, or a full test name is provided as the first argument, only + Test names include a group prefix. If a (exact, case sensitive) group + prefix, or a full test name is provided as the first argument, only that group or test is run. - If a numeric second argument is provided, it will set the randomness - seed, for repeatable results from tests using randomness (currently + If a numeric second argument is provided, it will set the randomness + seed, for repeatable results from tests using randomness (currently none of them). - This is mainly used by developers, but it's nice to be able to san- + This is mainly used by developers, but it's nice to be able to san- ity-check your installed hledger executable at any time. All tests are expected to pass - if you ever see otherwise, something has gone wrong, please report a bug! ADD-ON COMMANDS - hledger also searches for external add-on commands, and will include + hledger also searches for external add-on commands, and will include these in the commands list. These are programs or scripts in your PATH - whose name starts with hledger- and ends with a recognised file exten- + whose name starts with hledger- and ends with a recognised file exten- sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh). - Add-ons can be invoked like any hledger command, but there are a few + Add-ons can be invoked like any hledger command, but there are a few things to be aware of. Eg if the hledger-web add-on is installed, o hledger -h web shows hledger's help, while hledger web -h shows hledger-web's help. - o Flags specific to the add-on must have a preceding -- to hide them - from hledger. So hledger web --serve --port 9000 will be rejected; + o Flags specific to the add-on must have a preceding -- to hide them + from hledger. So hledger web --serve --port 9000 will be rejected; you must use hledger web -- --serve --port 9000. - o You can always run add-ons directly if preferred: + o You can always run add-ons directly if preferred: hledger-web --serve --port 9000. - Add-ons are a relatively easy way to add local features or experiment - with new ideas. They can be written in any language, but haskell - scripts have a big advantage: they can use the same hledger (and - haskell) library functions that built-in commands do, for command-line + Add-ons are a relatively easy way to add local features or experiment + with new ideas. They can be written in any language, but haskell + scripts have a big advantage: they can use the same hledger (and + haskell) library functions that built-in commands do, for command-line options, journal parsing, reporting, etc. Here are some hledger add-ons available: @@ -2133,7 +2209,7 @@ ADD-ON COMMANDS hledger-web provides a simple web interface. Third party add-ons - These are maintained separately, and usually updated shortly after a + These are maintained separately, and usually updated shortly after a hledger release. diff @@ -2141,7 +2217,7 @@ ADD-ON COMMANDS journal file and another. iadd - hledger-iadd is a curses-style, more interactive replacement for the + hledger-iadd is a curses-style, more interactive replacement for the add command. interest @@ -2149,19 +2225,19 @@ ADD-ON COMMANDS ing to various schemes. irr - hledger-irr calculates the internal rate of return of an investment + hledger-irr calculates the internal rate of return of an investment account, but it's superseded now by the built-in roi command. Experimental add-ons - These are available in source form in the hledger repo's bin/ direc- + These are available in source form in the hledger repo's bin/ direc- tory; installing them is pretty easy. They may be less mature and doc- - umented than built-in commands. Reading and tweaking these is a good + umented than built-in commands. Reading and tweaking these is a good way to start making your own! autosync hledger-autosync is a symbolic link for easily running ledger-autosync, - if installed. ledger-autosync does deduplicating conversion of OFX - data and some CSV formats, and can also download the data if your bank + if installed. ledger-autosync does deduplicating conversion of OFX + data and some CSV formats, and can also download the data if your bank offers OFX Direct Connect. chart @@ -2171,21 +2247,21 @@ ADD-ON COMMANDS hledger-check.hs checks more powerful account balance assertions. ENVIRONMENT - COLUMNS The screen width used by the register command. Default: the + COLUMNS The screen width used by the register command. Default: the full terminal width. LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- nal). FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.journal). BUGS - The need to precede addon command options with -- when invoked from + The need to precede addon command options with -- when invoked from hledger is awkward. When input data contains non-ascii characters, a suitable system locale @@ -2198,33 +2274,33 @@ BUGS In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger add. - Not all of Ledger's journal file syntax is supported. See file format + Not all of Ledger's journal file syntax is supported. See file format differences. - On large data files, hledger is slower and uses more memory than + On large data files, hledger is slower and uses more memory than Ledger. TROUBLESHOOTING - Here are some issues you might encounter when you run hledger (and - remember you can also seek help from the IRC channel, mail list or bug + Here are some issues you might encounter when you run hledger (and + remember you can also seek help from the IRC channel, mail list or bug tracker): Successfully installed, but "No command `hledger' found" stack and cabal install binaries into a special directory, which should - be added to your PATH environment variable. Eg on unix-like systems, + be added to your PATH environment variable. Eg on unix-like systems, that is ~/.local/bin and ~/.cabal/bin respectively. I set a custom LEDGER_FILE, but hledger is still using the default file - LEDGER_FILE should be a real environment variable, not just a shell - variable. The command env | grep LEDGER_FILE should show it. You may + LEDGER_FILE should be a real environment variable, not just a shell + variable. The command env | grep LEDGER_FILE should show it. You may need to use export. Here's an explanation. - "Illegal byte sequence" or "Invalid or incomplete multibyte or wide + "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors In order to handle non-ascii letters and symbols (like ), hledger needs an appropriate locale. This is usually configured system-wide; you can also configure it temporarily. The locale may need to be one that sup- - ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, + ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, I'm not sure yet). Here's an example of setting the locale temporarily, on ubuntu @@ -2243,7 +2319,7 @@ TROUBLESHOOTING $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile $ bash --login - If we preferred to use eg fr_FR.utf8, we might have to install that + If we preferred to use eg fr_FR.utf8, we might have to install that first: $ apt-get install language-pack-fr @@ -2264,7 +2340,7 @@ TROUBLESHOOTING 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) @@ -2278,7 +2354,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)