From 67dde9d4ae10495f2dce39742303d56fd83767ac Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 24 Jan 2019 15:37:40 -0800 Subject: [PATCH] doc: regenerate manuals, removing some smart typography [ci skip] --- hledger-lib/hledger_csv.5 | 31 +- hledger-lib/hledger_journal.5 | 204 +++++++------ hledger-lib/hledger_timeclock.5 | 6 +- hledger-lib/hledger_timedot.5 | 12 +- hledger-ui/hledger-ui.1 | 61 ++-- hledger-ui/hledger-ui.txt | 6 +- hledger-web/hledger-web.1 | 18 +- hledger-web/hledger-web.txt | 2 +- hledger/hledger.1 | 518 ++++++++++++++++++++------------ hledger/hledger.info | 422 ++++++++++++++++---------- hledger/hledger.txt | 454 +++++++++++++++++----------- 11 files changed, 1052 insertions(+), 682 deletions(-) diff --git a/hledger-lib/hledger_csv.5 b/hledger-lib/hledger_csv.5 index d0850fed5..5018a1db7 100644 --- a/hledger-lib/hledger_csv.5 +++ b/hledger-lib/hledger_csv.5 @@ -29,7 +29,7 @@ conversion rules file named \f[C]FILE.csv.rules\f[] in the same directory. You can override this with the \f[C]\-\-rules\-file\f[] option. If the rules file does not exist, hledger will auto\-create one with -some example rules, which you'll need to adjust. +some example rules, which you\[aq]ll need to adjust. .PP At minimum, the rules file must identify the \f[C]date\f[] and \f[C]amount\f[] fields. @@ -90,7 +90,7 @@ ignored. \f[C]skip\f[]\f[I]\f[CI]N\f[I]\f[] .PP Skip this number of CSV records at the beginning. -You'll need this whenever your CSV data contains header lines. +You\[aq]ll need this whenever your CSV data contains header lines. Eg: .IP .nf @@ -104,8 +104,8 @@ skip\ 1 \f[C]date\-format\f[]\f[I]\f[CI]DATEFMT\f[I]\f[] .PP When your CSV date fields are not formatted like \f[C]YYYY/MM/DD\f[] (or -\f[C]YYYY\-MM\-DD\f[] or \f[C]YYYY.MM.DD\f[]), you'll need to specify -the format. +\f[C]YYYY\-MM\-DD\f[] or \f[C]YYYY.MM.DD\f[]), you\[aq]ll need to +specify the format. DATEFMT is a strptime\-like date parsing pattern, which must parse the date field values completely. Examples: @@ -140,7 +140,7 @@ date\-format\ %\-m/%\-d/%Y\ %l:%M\ %p .SS field list .PP \f[C]fields\f[]\f[I]\f[CI]FIELDNAME1\f[I]\f[], -\f[I]\f[CI]FIELDNAME2\f[I]\f[]\&... +\f[I]\f[CI]FIELDNAME2\f[I]\f[]... .PP This (a) names the CSV fields, in order (names may not contain whitespace; uninteresting names may be left blank), and (b) assigns them @@ -192,7 +192,7 @@ Field assignments can be used instead of or in addition to a field list. .PD 0 .P .PD -\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]\&... +\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]... .PP \f[C]if\f[] .PD 0 @@ -202,16 +202,16 @@ Field assignments can be used instead of or in addition to a field list. .PD 0 .P .PD -\f[I]\f[CI]PATTERN\f[I]\f[]\&... +\f[I]\f[CI]PATTERN\f[I]\f[]... .PD 0 .P .PD -\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]\&... +\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]... .PP This applies one or more field assignments, only to those CSV records matched by one of the PATTERNs. The patterns are case\-insensitive regular expressions which match -anywhere within the whole CSV record (it's not yet possible to match +anywhere within the whole CSV record (it\[aq]s not yet possible to match within a specific field). When there are multiple patterns they can be written on separate lines, unindented. @@ -244,7 +244,7 @@ banking\ thru\ software .PP Include another rules file at this point. \f[C]RULESFILE\f[] is either an absolute file path or a path relative to -the current file's directory. +the current file\[aq]s directory. Eg: .IP .nf @@ -261,9 +261,9 @@ Consider adding this rule if all of the following are true: you might be processing just one day of data, your CSV records are in reverse chronological order (newest first), and you care about preserving the order of same\-day transactions. -It usually isn't needed, because hledger autodetects the CSV order, but -when all CSV records have the same date it will assume they are oldest -first. +It usually isn\[aq]t needed, because hledger autodetects the CSV order, +but when all CSV records have the same date it will assume they are +oldest first. .SH CSV TIPS .SS CSV ordering .PP @@ -274,8 +274,9 @@ case where you might need \f[C]newest\-first\f[], see above). .PP Each journal entry will have two postings, to \f[C]account1\f[] and \f[C]account2\f[] respectively. -It's not yet possible to generate entries with more than two postings. -It's conventional and recommended to use \f[C]account1\f[] for the +It\[aq]s not yet possible to generate entries with more than two +postings. +It\[aq]s conventional and recommended to use \f[C]account1\f[] for the account whose CSV we are reading. .SS CSV amounts .PP diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index e3afcc2a0..07f573fc9 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -6,29 +6,31 @@ .SH NAME .PP -Journal \- hledger's default file format, representing a General Journal +Journal \- hledger\[aq]s default file format, representing a General +Journal .SH DESCRIPTION .PP -hledger's usual data source is a plain text file containing journal +hledger\[aq]s usual data source is a plain text file containing journal entries in hledger journal format. This file represents a standard accounting general journal. -I use file names ending in \f[C]\&.journal\f[], but that's not required. +I use file names ending in \f[C]\&.journal\f[], but that\[aq]s not +required. The journal file contains a number of transaction entries, each describing a transfer of money (or any commodity) between two or more named accounts, in a simple format readable by both hledger and humans. .PP -hledger's journal format is a compatible subset, mostly, of ledger's -journal format, so hledger can work with compatible ledger journal files -as well. -It's safe, and encouraged, to run both hledger and ledger on the same -journal file, eg to validate the results you're getting. +hledger\[aq]s journal format is a compatible subset, mostly, of +ledger\[aq]s journal format, so hledger can work with compatible ledger +journal files as well. +It\[aq]s safe, and encouraged, to run both hledger and ledger on the +same journal file, eg to validate the results you\[aq]re getting. .PP You can use hledger without learning any more about this file; just use the add or web commands to create and update it. Many users, though, also edit the journal file directly with a text editor, perhaps assisted by the helper modes for emacs or vim. .PP -Here's an example: +Here\[aq]s an example: .IP .nf \f[C] @@ -81,7 +83,7 @@ line or a semicolon) semicolon until end of line) .PP Then comes zero or more (but usually at least 2) indented lines -representing\&... +representing... .SS Postings .PP A posting is an addition of some amount to, or removal of some amount @@ -134,12 +136,12 @@ The primary date, on the left, is used by default; the secondary date, on the right, is used when the \f[C]\-\-date2\f[] flag is specified (\f[C]\-\-aux\-date\f[] or \f[C]\-\-effective\f[] also work). .PP -The meaning of secondary dates is up to you, but it's best to follow a -consistent rule. -Eg write the bank's clearing date as primary, and when needed, the date -the transaction was initiated as secondary. +The meaning of secondary dates is up to you, but it\[aq]s best to follow +a consistent rule. +Eg write the bank\[aq]s clearing date as primary, and when needed, the +date the transaction was initiated as secondary. .PP -Here's an example. +Here\[aq]s an example. Note that a secondary date will use the year of the primary date if unspecified. .IP @@ -203,14 +205,14 @@ $\ hledger\ \-f\ t.j\ register\ checking .fi .PP DATE should be a simple date; if the year is not specified it will use -the year of the transaction's date. +the year of the transaction\[aq]s date. You can set the secondary date similarly, with \f[C]date2:DATE2\f[]. The \f[C]date:\f[] or \f[C]date2:\f[] tags must have a valid simple date value if they are present, eg a \f[C]date:\f[] tag with no value is not allowed. .PP -Ledger's earlier, more compact bracketed date syntax is also supported: -\f[C][DATE]\f[], \f[C][DATE=DATE2]\f[] or \f[C][=DATE2]\f[]. +Ledger\[aq]s earlier, more compact bracketed date syntax is also +supported: \f[C][DATE]\f[], \f[C][DATE=DATE2]\f[] or \f[C][=DATE2]\f[]. hledger will attempt to parse any square\-bracketed sequence of the \f[C]0123456789/\-.=\f[] characters in this way. With this syntax, DATE infers its year from the transaction and DATE2 @@ -254,11 +256,11 @@ When reporting, you can filter by status with the \f[C]status:!\f[], and \f[C]status:*\f[] queries; or the U, P, C keys in hledger\-ui. .PP -Note, in Ledger and in older versions of hledger, the \[lq]unmarked\[rq] -state is called \[lq]uncleared\[rq]. +Note, in Ledger and in older versions of hledger, the "unmarked" state +is called "uncleared". As of hledger 1.3 we have renamed it to unmarked for clarity. .PP -To replicate Ledger and old hledger's behaviour of also matching +To replicate Ledger and old hledger\[aq]s behaviour of also matching pending, combine \-U and \-P. .PP Status marks are optional, but can be helpful eg for reconciling with @@ -268,9 +270,8 @@ status. Eg in Emacs ledger\-mode, you can toggle transaction status with C\-c C\-e, or posting status with C\-c C\-c. .PP -What \[lq]uncleared\[rq], \[lq]pending\[rq], and \[lq]cleared\[rq] -actually mean is up to you. -Here's one suggestion: +What "uncleared", "pending", and "cleared" actually mean is up to you. +Here\[aq]s one suggestion: .PP .TS tab(@); @@ -304,10 +305,10 @@ bank soon (like uncashed checks), and no flags to see the most up\-to\-date state of your finances. .SS Description .PP -A transaction's description is the rest of the line following the date -and status mark (or until a comment begins). -Sometimes called the \[lq]narration\[rq] in traditional bookkeeping, it -can be used for whatever you wish, or left blank. +A transaction\[aq]s description is the rest of the line following the +date and status mark (or until a comment begins). +Sometimes called the "narration" in traditional bookkeeping, it can be +used for whatever you wish, or left blank. Transaction descriptions can be queried, unlike comments. .SS Payee and note .PP @@ -380,8 +381,8 @@ Some examples: .PP As you can see, the amount format is somewhat flexible: .IP \[bu] 2 -amounts are a number (the \[lq]quantity\[rq]) and optionally a currency -symbol/commodity name (the \[lq]commodity\[rq]). +amounts are a number (the "quantity") and optionally a currency +symbol/commodity name (the "commodity"). .IP \[bu] 2 the commodity is a symbol, word, or phrase, on the left or right, with or without a separating space. @@ -400,8 +401,8 @@ from digit groups separator .IP \[bu] 2 scientific E\-notation is allowed. Be careful not to use a digit group separator character in scientific -notation, as it's not supported and it might get mistaken for a decimal -point. +notation, as it\[aq]s not supported and it might get mistaken for a +decimal point. (Declaring the digit group separator character explicitly with a commodity directive will prevent this.) .PP @@ -439,13 +440,13 @@ will be the maximum from all posting amounts in that commmodity or if there are no such amounts in the journal, a default format is used (like \f[C]$1000.00\f[]). .PP -Price amounts and amounts in \f[C]D\f[] directives usually don't affect -amount format inference, but in some situations they can do so +Price amounts and amounts in \f[C]D\f[] directives usually don\[aq]t +affect amount format inference, but in some situations they can do so indirectly. -(Eg when D's default commodity is applied to a commodity\-less amount, -or when an amountless posting is balanced using a price's commodity, or -when \-V is used.) If you find this causing problems, set the desired -format with a commodity directive. +(Eg when D\[aq]s default commodity is applied to a commodity\-less +amount, or when an amountless posting is balanced using a price\[aq]s +commodity, or when \-V is used.) If you find this causing problems, set +the desired format with a commodity directive. .SS Virtual Postings .PP When you parenthesise the account name in a posting, we call that a @@ -456,7 +457,7 @@ it is ignored when checking that the transaction is balanced it is excluded from reports when the \f[C]\-\-real/\-R\f[] flag is used, or the \f[C]real:1\f[] query. .PP -You could use this, eg, to set an account's opening balance without +You could use this, eg, to set an account\[aq]s opening balance without needing to use the \f[C]equity:opening\ balances\f[] account: .IP .nf @@ -490,7 +491,8 @@ which is more correct and provides better error checking. .SS Balance Assertions .PP hledger supports Ledger\-style balance assertions in journal files. -These look like \f[C]=EXPECTEDBALANCE\f[] following a posting's amount. +These look like \f[C]=EXPECTEDBALANCE\f[] following a posting\[aq]s +amount. Eg in this example we assert the expected dollar balance in accounts a and b after each posting: .IP @@ -515,7 +517,7 @@ You can disable them temporarily with the troubleshooting or for reading Ledger files. .SS Assertions and ordering .PP -hledger sorts an account's postings and assertions first by date and +hledger sorts an account\[aq]s postings and assertions first by date and then (for postings on the same day) by parse order. Note this is different from Ledger, which sorts assertions only by parse order. @@ -534,31 +536,31 @@ intra\-day balances. With included files, things are a little more complicated. Including preserves the ordering of postings and assertions. If you have multiple postings to an account on the same day, split -across different files, and you also want to assert the account's -balance on the same day, you'll have to put the assertion in the right -file. +across different files, and you also want to assert the account\[aq]s +balance on the same day, you\[aq]ll have to put the assertion in the +right file. .SS Assertions and multiple \-f options .PP -Balance assertions don't work well across files specified with multiple -\-f options. +Balance assertions don\[aq]t work well across files specified with +multiple \-f options. Use include or concatenate the files instead. .SS Assertions and commodities .PP The asserted balance must be a simple single\-commodity amount, and in -fact the assertion checks only this commodity's balance within the +fact the assertion checks only this commodity\[aq]s balance within the (possibly multi\-commodity) account balance. .PD 0 .P .PD This is how assertions work in Ledger also. -We could call this a \[lq]partial\[rq] balance assertion. +We could call this a "partial" balance assertion. .PP To assert the balance of more than one commodity in an account, you can -write multiple postings, each asserting one commodity's balance. +write multiple postings, each asserting one commodity\[aq]s balance. .PP You can make a stronger kind of balance assertion, by writing a double equals sign (\f[C]==EXPECTEDBALANCE\f[]). -This \[lq]complete\[rq] balance assertion asserts the absence of other +This "complete" balance assertion asserts the absence of other commodities (or, that their balance is 0, which to hledger is equivalent.) .IP @@ -581,8 +583,8 @@ equivalent.) \f[] .fi .PP -It's not yet possible to make a complete assertion about a balance that -has multiple commodities. +It\[aq]s not yet possible to make a complete assertion about a balance +that has multiple commodities. One workaround is to isolate each commodity into its own subaccount: .IP .nf @@ -605,7 +607,7 @@ the meaning of that would be unclear. .SS Assertions and subaccounts .PP Balance assertions do not count the balance from subaccounts; they check -the posted account's exclusive balance. +the posted account\[aq]s exclusive balance. For example: .IP .nf @@ -617,7 +619,7 @@ For example: \f[] .fi .PP -The balance report's flat mode shows these exclusive balances more +The balance report\[aq]s flat mode shows these exclusive balances more clearly: .IP .nf @@ -673,16 +675,16 @@ or when adjusting a balance to reality: \f[] .fi .PP -The calculated amount depends on the account's balance in the commodity -at that point (which depends on the previously\-dated postings of the -commodity to that account since the last balance assertion or +The calculated amount depends on the account\[aq]s balance in the +commodity at that point (which depends on the previously\-dated postings +of the commodity to that account since the last balance assertion or assignment). Note that using balance assignments makes your journal a little less explicit; to know the exact amount posted, you have to run hledger or do the calculations yourself, instead of just reading it. .SS Transaction prices .PP -Within a transaction, you can note an amount's price in another +Within a transaction, you can note an amount\[aq]s price in another commodity. This can be used to document the cost (in a purchase) or selling price (in a sale). @@ -736,8 +738,8 @@ hledger infer the price that balances the transaction: \f[C]{=UNITPRICE}\f[], which hledger currently ignores). .PP Use the \f[C]\-B/\-\-cost\f[] flag to convert amounts to their -transaction price's commodity, if any. -(mnemonic: \[lq]B\[rq] is from \[lq]cost Basis\[rq], as in Ledger). +transaction price\[aq]s commodity, if any. +(mnemonic: "B" is from "cost Basis", as in Ledger). Eg here is how \-B affects the balance report for the example above: .IP .nf @@ -754,7 +756,7 @@ $\ hledger\ bal\ \-N\ \-\-flat\ \-B Note \-B is sensitive to the order of postings when a transaction price is inferred: the inferred price will be in the commodity of the last amount. -So if example 3's postings are reversed, while the transaction is +So if example 3\[aq]s postings are reversed, while the transaction is equivalent, \-B shows something different: .IP .nf @@ -837,7 +839,8 @@ comma or end of line, with leading/trailing whitespace removed: \f[] .fi .PP -Note this means hledger's tag values can not contain commas or newlines. +Note this means hledger\[aq]s tag values can not contain commas or +newlines. Ending at commas means you can write multiple short tags on one line, comma separated: .IP @@ -849,13 +852,12 @@ comma separated: .PP Here, .IP \[bu] 2 -\[lq]\f[C]a\ comment\ containing\f[]\[rq] is just comment text, not a -tag +"\f[C]a\ comment\ containing\f[]" is just comment text, not a tag .IP \[bu] 2 -\[lq]\f[C]tag1\f[]\[rq] is a tag with no value +"\f[C]tag1\f[]" is a tag with no value .IP \[bu] 2 -\[lq]\f[C]tag2\f[]\[rq] is another tag, whose value is -\[lq]\f[C]some\ value\ ...\f[]\[rq] +"\f[C]tag2\f[]" is another tag, whose value is +"\f[C]some\ value\ ...\f[]" .PP Tags in a transaction comment affect the transaction and all of its postings, while tags in a posting comment affect only that posting. @@ -871,18 +873,19 @@ For example, the following transaction has three tags (\f[C]A\f[], \f[] .fi .PP -Tags are like Ledger's metadata feature, except hledger's tag values are -simple strings. +Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag +values are simple strings. .SS Directives .PP A directive is a line in the journal beginning with a special keyword, 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). +hledger\[aq]s directives are based on a subset of Ledger\[aq]s, but +there are many differences (and also some differences between hledger +versions). .PP -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. +Directives\[aq] behaviour and interactions can get a little bit complex, +so here is a table summarising the directives and their effects, with +links to more detailed docs. .PP .TS tab(@); @@ -1064,8 +1067,8 @@ The \f[C]include\f[] directive can only be used in journal files. It can include journal, timeclock or timedot files, but not CSV files. .SS Default year .PP -You can set a default year to be used for subsequent dates which don't -specify a year. +You can set a default year to be used for subsequent dates which +don\[aq]t specify a year. This is a line beginning with \f[C]Y\f[] followed by the year. Eg: .IP @@ -1105,7 +1108,7 @@ commodity\ 1,000.0000\ AAAA \f[] .fi .PP -or on multiple lines, using the \[lq]format\[rq] subdirective. +or on multiple lines, using the "format" subdirective. In this case the commodity symbol appears twice and should be the same in both places: .IP @@ -1134,7 +1137,7 @@ digits). .PP The \f[C]D\f[] directive sets a default commodity (and display format), to be used for amounts without a commodity symbol (ie, plain numbers). -(Note this differs from Ledger's default commodity directive.) The +(Note this differs from Ledger\[aq]s default commodity directive.) The commodity and display format will be applied to all subsequent commodity\-less amounts, or until the next \f[C]D\f[] directive. .IP @@ -1156,9 +1159,9 @@ written with a decimal point. .PP The \f[C]P\f[] directive declares a market price, which is an exchange rate between two commodities on a certain date. -(In Ledger, they are called \[lq]historical prices\[rq].) These are -often obtained from a stock exchange, cryptocurrency exchange, or the -foreign exchange market. +(In Ledger, they are called "historical prices".) These are often +obtained from a stock exchange, cryptocurrency exchange, or the foreign +exchange market. .PP Here is the format: .IP @@ -1198,7 +1201,7 @@ reference. They can store extra information about accounts (account numbers, notes, etc.) .IP \[bu] 2 -They can help hledger know your accounts' types (asset, liability, +They can help hledger know your accounts\[aq] types (asset, liability, equity, revenue, expense), useful for reports like balancesheet and incomestatement. .IP \[bu] 2 @@ -1268,7 +1271,7 @@ If you name your top\-level accounts with some variation of detected automatically. .SS Account types declared with tags .PP -More generally, you can declare an account's type with an account +More generally, you can declare an account\[aq]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[] @@ -1332,7 +1335,7 @@ account\ expenses \f[] .fi .PP -you'll see those accounts displayed in declaration order, not +you\[aq]ll see those accounts displayed in declaration order, not alphabetically: .IP .nf @@ -1358,13 +1361,14 @@ account\ other:zoo \f[] .fi .PP -would influence the position of \f[C]zoo\f[] among \f[C]other\f[]'s +would influence the position of \f[C]zoo\f[] among \f[C]other\f[]\[aq]s subaccounts, but not the position of \f[C]other\f[] among the top\-level accounts. This means: \- you will sometimes declare parent accounts (eg -\f[C]account\ other\f[] above) that you don't intend to post to, just to -customize their display order \- sibling accounts stay together (you -couldn't display \f[C]x:y\f[] in between \f[C]a:b\f[] and \f[C]a:c\f[]). +\f[C]account\ other\f[] above) that you don\[aq]t intend to post to, +just to customize their display order \- sibling accounts stay together +(you couldn\[aq]t display \f[C]x:y\f[] in between \f[C]a:b\f[] and +\f[C]a:c\f[]). .SS Rewriting accounts .PP You can define account alias rules which rewrite your account names, or @@ -1403,7 +1407,7 @@ alias\ OLD\ =\ NEW Or, you can use the \f[C]\-\-alias\ \[aq]OLD=NEW\[aq]\f[] option on the command line. This affects all entries. -It's useful for trying out aliases interactively. +It\[aq]s useful for trying out aliases interactively. .PP OLD and NEW are case sensitive full account names. hledger will replace any occurrence of the old account name with the new @@ -1549,8 +1553,8 @@ Eg \f[C]monthly\ from\ 2018/1/1\f[] is valid, but .PP Partial or relative dates (M/D, D, tomorrow, last week) in the period expression can work (useful or not). -They will be relative to today's date, unless a Y default year directive -is in effect, in which case they will be relative to Y/1/1. +They will be relative to today\[aq]s date, unless a Y default year +directive is in effect, in which case they will be relative to Y/1/1. .SS Two spaces after the period expression .PP If the period expression is followed by a transaction description, these @@ -1593,9 +1597,9 @@ journal, or today if there are no normal transactions. ends on the report end date if specified with \-e/\-p/date:, or 180 days from today. .PP -where \[lq]today\[rq] means the current date at report time. -The \[lq]later of\[rq] rule ensures that forecast transactions do not -overlap normal transactions in time; they will begin only after normal +where "today" means the current date at report time. +The "later of" rule ensures that forecast transactions do not overlap +normal transactions in time; they will begin only after normal transactions end. .PP Forecasting can be useful for estimating balances into the future, and @@ -1627,14 +1631,14 @@ and Forecasting. .PP Transaction modifier rules describe changes that should be applied automatically to certain transactions. -Currently, this means adding extra postings (also known as -\[lq]automated postings\[rq]). +Currently, this means adding extra postings (also known as "automated +postings"). Transaction modifiers are enabled by the \f[C]\-\-auto\f[] flag. .PP A transaction modifier rule looks quite like a normal transaction, except the first line is an equals sign followed by a query that matches certain postings (mnemonic: \f[C]=\f[] suggests matching). -And each \[lq]posting\[rq] is actually a posting\-generating rule: +And each "posting" is actually a posting\-generating rule: .IP .nf \f[C] @@ -1656,13 +1660,13 @@ The commodity symbol (if any) from the matched posting will be added to this. .IP \[bu] 2 a numeric multiplier, eg \f[C]*2\f[] (a star followed by a number N). -The matched posting's amount (and total price, if any) will be +The matched posting\[aq]s amount (and total price, if any) will be multiplied by N. .IP \[bu] 2 a multiplier with a commodity symbol, eg \f[C]*$2\f[] (a star, number N, and symbol S). -The matched posting's amount will be multiplied by N, and its commodity -symbol will be replaced with S. +The matched posting\[aq]s amount will be multiplied by N, and its +commodity symbol will be replaced with S. .PP Some examples: .IP diff --git a/hledger-lib/hledger_timeclock.5 b/hledger-lib/hledger_timeclock.5 index e00ccce44..80eb61df6 100644 --- a/hledger-lib/hledger_timeclock.5 +++ b/hledger-lib/hledger_timeclock.5 @@ -9,7 +9,7 @@ Timeclock \- the time logging format of timeclock.el, as read by hledger .SH DESCRIPTION .PP hledger can read timeclock files. -As with Ledger, these are (a subset of) timeclock.el's format, +As with Ledger, these are (a subset of) timeclock.el\[aq]s format, containing clock\-in and clock\-out entries as in the example below. The date is a simple date. The time format is HH:MM[:SS][+\-ZZZZ]. @@ -67,8 +67,8 @@ at the command line, use these bash aliases: .IP \[bu] 2 or use the old \f[C]ti\f[] and \f[C]to\f[] scripts in the ledger 2.x repository. -These rely on a \[lq]timeclock\[rq] executable which I think is just the -ledger 2 executable renamed. +These rely on a "timeclock" executable which I think is just the ledger +2 executable renamed. .SH "REPORTING BUGS" diff --git a/hledger-lib/hledger_timedot.5 b/hledger-lib/hledger_timedot.5 index 2c6e51d74..6f90a7c29 100644 --- a/hledger-lib/hledger_timedot.5 +++ b/hledger-lib/hledger_timedot.5 @@ -5,7 +5,7 @@ .SH NAME .PP -Timedot \- hledger's human\-friendly time logging format +Timedot \- hledger\[aq]s human\-friendly time logging format .SH DESCRIPTION .PP Timedot is a plain text format for logging dated, categorised quantities @@ -16,10 +16,10 @@ precise or too interruptive. It can be formatted like a bar chart, making clear at a glance where time was spent. .PP -Though called \[lq]timedot\[rq], this format is read by hledger as -commodityless quantities, so it could be used to represent dated -quantities other than time. -In the docs below we'll assume it's time. +Though called "timedot", this format is read by hledger as commodityless +quantities, so it could be used to represent dated quantities other than +time. +In the docs below we\[aq]ll assume it\[aq]s time. .SH FILE FORMAT .PP A timedot file contains a series of day entries. @@ -34,7 +34,7 @@ Quantities can be written as: .IP \[bu] 2 a sequence of dots (.) representing quarter hours. Spaces may optionally be used for grouping and readability. -Eg: \&.... +Eg: .... \&.. .IP \[bu] 2 an integral or decimal number, representing hours. diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 31b18c08d..0991dd001 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -20,17 +20,17 @@ other commodity, using double\-entry accounting and a simple, editable file format. hledger is inspired by and largely compatible with ledger(1). .PP -hledger\-ui is hledger's curses\-style interface, providing an efficient -full\-window text UI for viewing accounts and transactions, and some -limited data entry capability. -It is easier than hledger's command\-line interface, and sometimes +hledger\-ui is hledger\[aq]s curses\-style interface, providing an +efficient full\-window text UI for viewing accounts and transactions, +and some limited data entry capability. +It is easier than hledger\[aq]s command\-line interface, and sometimes quicker and more convenient than the web interface. .PP Note hledger\-ui has some different defaults: \- it generates -rule\-based transactions and postings by default (\[en]forecast and -\[en]auto are always on). +rule\-based transactions and postings by default (\-\-forecast and +\-\-auto are always on). \- it hides transactions dated in the future by default (change this -with \[en]future or the F key). +with \-\-future or the F key). Experimental. .PP Like hledger, it reads data from one or more files in hledger journal, @@ -57,7 +57,7 @@ use this custom display theme .RE .TP .B \f[C]\-\-register=ACCTREGEX\f[] -start in the (first) matched account's register screen +start in the (first) matched account\[aq]s register screen .RS .RE .TP @@ -96,7 +96,7 @@ Conversion rules file to use when reading CSV (default: FILE.rules) .RE .TP .B \f[C]\-\-separator=CHAR\f[] -Field separator to expect when reading CSV (default: `,') +Field separator to expect when reading CSV (default: \[aq],\[aq]) .RS .RE .TP @@ -264,7 +264,7 @@ Vi\-style (\f[C]h\f[]/\f[C]j\f[]/\f[C]k\f[]/\f[C]l\f[]) and Emacs\-style movement keys are also supported. A tip: movement speed is limited by your keyboard repeat rate, to move faster you may want to adjust it. -(If you're on a mac, the Karabiner app is one way to do that.) +(If you\[aq]re on a mac, the Karabiner app is one way to do that.) .PP With shift pressed, the cursor keys adjust the report period, limiting the transactions to be shown (by default, all are shown). @@ -272,9 +272,9 @@ the transactions to be shown (by default, all are shown). report period durations: year, quarter, month, week, day. Then, \f[C]shift\-left/right\f[] moves to the previous/next period. \f[C]t\f[] sets the report period to today. -With the \f[C]\-\-watch\f[] option, when viewing a \[lq]current\[rq] -period (the current day, week, month, quarter, or year), the period will -move automatically to track the current date. +With the \f[C]\-\-watch\f[] option, when viewing a "current" period (the +current day, week, month, quarter, or year), the period will move +automatically to track the current date. To set a non\-standard period, you can use \f[C]/\f[] and a \f[C]date:\f[] query. .PP @@ -299,8 +299,8 @@ convenient. Or, it cancels a minibuffer edit or help dialog in progress. .PP \f[C]CTRL\-l\f[] redraws the screen and centers the selection if -possible (selections near the top won't be centered, since we don't -scroll above the top). +possible (selections near the top won\[aq]t be centered, since we +don\[aq]t scroll above the top). .PP \f[C]g\f[] reloads from the data file(s) and updates the current screen and any previous screens. @@ -310,7 +310,7 @@ and any previous screens. Disabling balance assertions temporarily can be useful for troubleshooting. .PP -\f[C]a\f[] runs command\-line hledger's add command, and reloads the +\f[C]a\f[] runs command\-line hledger\[aq]s add command, and reloads the updated file. This allows some basic data entry. .PP @@ -333,7 +333,8 @@ Additional screen\-specific keys are described below. .SS Accounts screen .PP This is normally the first screen displayed. -It lists accounts and their balances, like hledger's balance command. +It lists accounts and their balances, like hledger\[aq]s balance +command. By default, it shows all accounts and their latest ending balances (including the balances of subaccounts). if you specify a query on the command line, it shows just the matched @@ -380,8 +381,8 @@ all three, the filter is removed.) balances are shown (hledger\-ui shows zero items by default, unlike command\-line hledger). .PP -Press \f[C]right\f[] or \f[C]enter\f[] to view an account's transactions -register. +Press \f[C]right\f[] or \f[C]enter\f[] to view an account\[aq]s +transactions register. .SS Register screen .PP This screen shows the transactions affecting a particular account, like @@ -392,7 +393,7 @@ the other account(s) involved, in abbreviated form. (If there are both real and virtual postings, it shows only the accounts affected by real postings.) .IP \[bu] 2 -the overall change to the current account's balance; positive for an +the overall change to the current account\[aq]s balance; positive for an inflow to this account, negative for an outflow. .IP \[bu] 2 the running historical total or period total for the current account, @@ -405,10 +406,10 @@ If the historical total is not disturbed by a filter query, it will be the running historical balance you would see on a bank register for the current account. .PP -Transactions affecting this account's subaccounts will be included in -the register if the accounts screen is in tree mode, or if it's in flat -mode but this account has subaccounts which are not shown due to a depth -limit. +Transactions affecting this account\[aq]s subaccounts will be included +in the register if the accounts screen is in tree mode, or if it\[aq]s +in flat mode but this account has subaccounts which are not shown due to +a depth limit. In other words, the register always shows the transactions contributing to the balance shown on the accounts screen. .PD 0 @@ -435,10 +436,10 @@ transaction in detail. .SS Transaction screen .PP This screen shows a single transaction, as a general journal entry, -similar to hledger's print command and journal format +similar to hledger\[aq]s print command and journal format (hledger_journal(5)). .PP -The transaction's date(s) and any cleared flag, transaction code, +The transaction\[aq]s date(s) and any cleared flag, transaction code, description, comments, along with all of its account postings are shown. Simple transactions have two postings, but there can be more (or in certain cases, fewer). @@ -449,9 +450,9 @@ In the title bar, the numbers in parentheses show your position within that account register. They will vary depending on which account register you came from (remember most transactions appear in multiple account registers). -The #N number preceding them is the transaction's position within the -complete unfiltered journal, which is a more stable id (at least until -the next reload). +The #N number preceding them is the transaction\[aq]s position within +the complete unfiltered journal, which is a more stable id (at least +until the next reload). .SS Error screen .PP This screen will appear if there is a problem, such as a parse error, @@ -479,7 +480,7 @@ perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). The need to precede options with \f[C]\-\-\f[] when invoked from hledger is awkward. .PP -\f[C]\-f\-\f[] doesn't work (hledger\-ui can't read from stdin). +\f[C]\-f\-\f[] doesn\[aq]t work (hledger\-ui can\[aq]t read from stdin). .PP \f[C]\-V\f[] affects only the accounts screen. .PP diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index b7ad748b9..cd92cb90d 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -23,9 +23,9 @@ DESCRIPTION web interface. Note hledger-ui has some different defaults: - it generates rule-based - transactions and postings by default (-forecast and -auto are always + transactions and postings by default (--forecast and --auto are always on). - it hides transactions dated in the future by default (change - this with -future or the F key). Experimental. + this with --future or the F key). Experimental. Like hledger, it reads data from one or more files in hledger journal, timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE, @@ -73,7 +73,7 @@ OPTIONS FILE.rules) --separator=CHAR - Field separator to expect when reading CSV (default: `,') + Field separator to expect when reading CSV (default: ',') --alias=OLD=NEW rename accounts named OLD to NEW diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index f07212d47..1d09c7413 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -20,7 +20,7 @@ other commodity, using double\-entry accounting and a simple, editable file format. hledger is inspired by and largely compatible with ledger(1). .PP -hledger\-web is hledger's web interface. +hledger\-web is hledger\[aq]s web interface. It starts a simple web application for browsing and adding transactions, and optionally opens it in a web browser window if possible. It provides a more user\-friendly UI than the hledger CLI or hledger\-ui @@ -42,8 +42,8 @@ timeclock, timedot, or CSV format specified with \f[C]\-f\f[], or perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). For more about this see hledger(1), hledger_journal(5) etc. .PP -By default, hledger\-web starts the web app in \[lq]transient mode\[rq] -and also opens it in your default web browser if possible. +By default, hledger\-web starts the web app in "transient mode" and also +opens it in your default web browser if possible. In this mode the web app will keep running for as long as you have it open in a browser window, and will exit after two minutes of inactivity (no requests and no browser windows viewing it). @@ -61,8 +61,9 @@ if you are running multiple hledger\-web instances. You can use \f[C]\-\-base\-url\f[] to change the protocol, hostname, port and path that appear in hyperlinks, useful eg for integrating hledger\-web within a larger website. -The default is \f[C]http://HOST:PORT/\f[] using the server's configured -host address and TCP port (or \f[C]http://HOST\f[] if PORT is 80). +The default is \f[C]http://HOST:PORT/\f[] using the server\[aq]s +configured host address and TCP port (or \f[C]http://HOST\f[] if PORT is +80). .PP With \f[C]\-\-file\-url\f[] you can set a different base url for static files, eg for better caching or cookie\-less serving on high performance @@ -90,7 +91,7 @@ Note: if invoking hledger\-web as a hledger subcommand, write \f[C]\-\-\f[] before options as shown above. .TP .B \f[C]\-\-serve\f[] -serve and log requests, don't browse or auto\-exit +serve and log requests, don\[aq]t browse or auto\-exit .RS .RE .TP @@ -134,7 +135,7 @@ Conversion rules file to use when reading CSV (default: FILE.rules) .RE .TP .B \f[C]\-\-separator=CHAR\f[] -Field separator to expect when reading CSV (default: `,') +Field separator to expect when reading CSV (default: \[aq],\[aq]) .RS .RE .TP @@ -302,7 +303,8 @@ perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). The need to precede options with \f[C]\-\-\f[] when invoked from hledger is awkward. .PP -\f[C]\-f\-\f[] doesn't work (hledger\-web can't read from stdin). +\f[C]\-f\-\f[] doesn\[aq]t work (hledger\-web can\[aq]t read from +stdin). .PP Query arguments and some hledger options are ignored. .PP diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index db841de8a..37ff40b93 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -106,7 +106,7 @@ OPTIONS FILE.rules) --separator=CHAR - Field separator to expect when reading CSV (default: `,') + Field separator to expect when reading CSV (default: ',') --alias=OLD=NEW rename accounts named OLD to NEW diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 184c38314..350d4e842 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -189,7 +189,7 @@ Conversion rules file to use when reading CSV (default: FILE.rules) .RE .TP .B \f[C]\-\-separator=CHAR\f[] -Field separator to expect when reading CSV (default: `,') +Field separator to expect when reading CSV (default: \[aq],\[aq]) .RS .RE .TP @@ -347,10 +347,10 @@ For more, see Save frequently used options. .SS Special characters in arguments and queries .PP In shell command lines, option and argument values which contain -\[lq]problematic\[rq] characters, ie spaces, and also characters -significant to your shell such as \f[C]<\f[], \f[C]>\f[], \f[C](\f[], -\f[C])\f[], \f[C]|\f[] and \f[C]$\f[], should be escaped by enclosing -them in quotes or by writing backslashes before the characters. +"problematic" characters, ie spaces, and also characters significant to +your shell such as \f[C]<\f[], \f[C]>\f[], \f[C](\f[], \f[C])\f[], +\f[C]|\f[] and \f[C]$\f[], should be escaped by enclosing them in quotes +or by writing backslashes before the characters. Eg: .PP \f[C]hledger\ register\ \-p\ \[aq]last\ year\[aq]\ "accounts\ receivable\ (receivable|payable)"\ amt:\\>100\f[]. @@ -371,7 +371,8 @@ or: When hledger runs an addon executable (eg you type \f[C]hledger\ ui\f[], hledger runs \f[C]hledger\-ui\f[]), it de\-escapes command\-line options and arguments once, so you might need to \f[I]triple\f[]\-escape. -Eg in bash, running the ui command and matching the dollar sign, it's: +Eg in bash, running the ui command and matching the dollar sign, +it\[aq]s: .PP \f[C]hledger\ ui\ cur:\[aq]\\\\$\[aq]\f[] .PP @@ -442,7 +443,7 @@ hledger is expected to handle unicode (non\-ascii) characters, but this requires a well\-configured environment. .PP To handle unicode characters in the command line or input data, a system -locale that can decode them must be configured (POSIX's default +locale that can decode them must be configured (POSIX\[aq]s default \f[C]C\f[] locale will not work). Eg in bash, you could do: .IP @@ -454,15 +455,15 @@ export\ LANG=en_US.UTF\-8 .PP See Troubleshooting for more about this. .PP -Unicode characters should appear correctly in hledger's output. +Unicode characters should appear correctly in hledger\[aq]s output. For the hledger and hledger\-ui tools, this requires that .IP \[bu] 2 your terminal supports unicode .IP \[bu] 2 -the terminal's font includes the required unicode glyphs +the terminal\[aq]s font includes the required unicode glyphs .IP \[bu] 2 -the terminal is configured to display \[lq]wide\[rq] characters as -double width (otherwise report alignment will be off) +the terminal is configured to display "wide" characters as double width +(otherwise report alignment will be off) .SS Input files .PP hledger reads transactions from a data file (and the add command writes @@ -495,11 +496,10 @@ $\ cat\ some.journal\ |\ hledger\ \-f\- \f[] .fi .PP -Usually the data file is in hledger's journal format, but it can also be -one of several other formats, listed below. +Usually the data file is in hledger\[aq]s journal format, but it can +also be one of several other formats, listed below. hledger detects the format automatically based on the file extension, or -if that is not recognised, by trying each built\-in \[lq]reader\[rq] in -turn: +if that is not recognised, by trying each built\-in "reader" in turn: .PP .TS tab(@); @@ -515,7 +515,7 @@ _ T{ \f[C]journal\f[] T}@T{ -hledger's journal format, also some Ledger journals +hledger\[aq]s journal format, also some Ledger journals T}@T{ \f[C]\&.journal\f[] \f[C]\&.j\f[] \f[C]\&.hledger\f[] \f[C]\&.ledger\f[] T} @@ -543,8 +543,8 @@ T} .TE .PP If needed (eg to ensure correct error messages when a file has the -\[lq]wrong\[rq] extension), you can force a specific reader/format by -prepending it to the file path with a colon. +"wrong" extension), you can force a specific reader/format by prepending +it to the file path with a colon. Examples: .IP .nf @@ -566,10 +566,11 @@ If you need those, either use the include directive, or concatenate the files, eg: \f[C]cat\ a.journal\ b.journal\ |\ hledger\ \-f\-\ CMD\f[]. .SS Smart dates .PP -hledger's user interfaces accept a flexible \[lq]smart date\[rq] syntax +hledger\[aq]s user interfaces accept a flexible "smart date" syntax (unlike dates in the journal file). -Smart dates allow some english words, can be relative to today's date, -and can have less\-significant date parts omitted (defaulting to 1). +Smart dates allow some english words, can be relative to today\[aq]s +date, and can have less\-significant date parts omitted (defaulting to +1). .PP Examples: .PP @@ -681,7 +682,8 @@ l l. T{ \f[C]\-b\ 2016/3/17\f[] T}@T{ -begin on St.\ Patrick's day 2016 +begin on St. +Patrick\[aq]s day 2016 T} T{ \f[C]\-e\ 12/1\f[] @@ -732,15 +734,16 @@ The \f[C]\-p/\-\-period\f[] option accepts period expressions, a shorthand way of expressing a start date, end date, and/or report interval all at once. .PP -Here's a basic period expression specifying the first quarter of 2009. +Here\[aq]s a basic period expression specifying the first quarter of +2009. Note, hledger always treats start dates as inclusive and end dates as exclusive: .PP \f[C]\-p\ "from\ 2009/1/1\ to\ 2009/4/1"\f[] .PP -Keywords like \[lq]from\[rq] and \[lq]to\[rq] are optional, and so are -the spaces, as long as you don't run two dates together. -\[lq]to\[rq] can also be written as \[lq]\-\[rq]. +Keywords like "from" and "to" are optional, and so are the spaces, as +long as you don\[aq]t run two dates together. +"to" can also be written as "\-". These are equivalent to the above: .PP .TS @@ -802,8 +805,8 @@ everything before january 1, 2009 T} .TE .PP -A single date with no \[lq]from\[rq] or \[lq]to\[rq] defines both the -start and end date like so: +A single date with no "from" or "to" defines both the start and end date +like so: .PP .TS tab(@); @@ -811,17 +814,17 @@ l l. T{ \f[C]\-p\ "2009"\f[] T}@T{ -the year 2009; equivalent to \[lq]2009/1/1 to 2010/1/1\[rq] +the year 2009; equivalent to "2009/1/1 to 2010/1/1" T} T{ \f[C]\-p\ "2009/1"\f[] T}@T{ -the month of jan; equivalent to \[lq]2009/1/1 to 2009/2/1\[rq] +the month of jan; equivalent to "2009/1/1 to 2009/2/1" T} T{ \f[C]\-p\ "2009/1/1"\f[] T}@T{ -just that day; equivalent to \[lq]2009/1/1 to 2009/1/2\[rq] +just that day; equivalent to "2009/1/1 to 2009/1/2" T} .TE .PP @@ -861,11 +864,11 @@ For example: tab(@); l. T{ -\f[C]\-p\ "weekly\ from\ 2009/1/1\ to\ 2009/4/1"\f[] \[en] starts on +\f[C]\-p\ "weekly\ from\ 2009/1/1\ to\ 2009/4/1"\f[] \-\- starts on 2008/12/29, closest preceeding Monday T} T{ -\f[C]\-p\ "monthly\ in\ 2008/11/25"\f[] \[en] starts on 2018/11/01 +\f[C]\-p\ "monthly\ in\ 2008/11/25"\f[] \-\- starts on 2018/11/01 T} T{ \f[C]\-p\ "quarterly\ from\ 2009\-05\-05\ to\ 2009\-06\-01"\f[] \- @@ -892,16 +895,15 @@ Examples: tab(@); l. T{ -\f[C]\-p\ "bimonthly\ from\ 2008"\f[] \[en] periods will have boundaries -on 2008/01/01, 2008/03/01, \&... +\f[C]\-p\ "bimonthly\ from\ 2008"\f[] \-\- periods will have boundaries +on 2008/01/01, 2008/03/01, ... T} T{ -\f[C]\-p\ "every\ 2\ weeks"\f[] \[en] starts on closest preceeding -Monday +\f[C]\-p\ "every\ 2\ weeks"\f[] \-\- starts on closest preceeding Monday T} T{ -\f[C]\-p\ "every\ 5\ month\ from\ 2009/03"\f[] \[en] periods will have -boundaries on 2009/03/01, 2009/08/01, \&... +\f[C]\-p\ "every\ 5\ month\ from\ 2009/03"\f[] \-\- periods will have +boundaries on 2009/03/01, 2009/08/01, ... T} .TE .PP @@ -920,29 +922,29 @@ Examples: tab(@); l. T{ -\f[C]\-p\ "every\ 2nd\ day\ of\ week"\f[] \[en] periods will go from Tue +\f[C]\-p\ "every\ 2nd\ day\ of\ week"\f[] \-\- periods will go from Tue to Tue T} T{ -\f[C]\-p\ "every\ Tue"\f[] \[en] same +\f[C]\-p\ "every\ Tue"\f[] \-\- same T} T{ -\f[C]\-p\ "every\ 15th\ day"\f[] \[en] period boundaries will be on 15th +\f[C]\-p\ "every\ 15th\ day"\f[] \-\- period boundaries will be on 15th of each month T} T{ -\f[C]\-p\ "every\ 2nd\ Monday"\f[] \[en] period boundaries will be on +\f[C]\-p\ "every\ 2nd\ Monday"\f[] \-\- period boundaries will be on second Monday of each month T} T{ -\f[C]\-p\ "every\ 11/05"\f[] \[en] yearly periods with boundaries on 5th +\f[C]\-p\ "every\ 11/05"\f[] \-\- yearly periods with boundaries on 5th of Nov T} T{ -\f[C]\-p\ "every\ 5th\ Nov"\f[] \[en] same +\f[C]\-p\ "every\ 5th\ Nov"\f[] \-\- same T} T{ -\f[C]\-p\ "every\ Nov\ 5th"\f[] \[en] same +\f[C]\-p\ "every\ Nov\ 5th"\f[] \-\- same T} .TE .PP @@ -977,9 +979,9 @@ will be displayed hierarchically in reports. .PP \f[C]\-\-pivot\f[] is a general option affecting all reports; you can think of hledger transforming the journal before any other processing, -replacing every posting's account name with the value of the specified -field on that posting, inheriting it from the transaction or using a -blank value if it's not present. +replacing every posting\[aq]s account name with the value of the +specified field on that posting, inheriting it from the transaction or +using a blank value if it\[aq]s not present. .PP An example: .IP @@ -1027,8 +1029,8 @@ $\ hledger\ balance\ \-\-pivot\ member\ tag:member=. \f[] .fi .PP -Another way (the acct: query matches against the pivoted \[lq]account -name\[rq]): +Another way (the acct: query matches against the pivoted "account +name"): .IP .nf \f[C] @@ -1050,9 +1052,9 @@ current market value. .P .PD Specifically, when there is a market price (P directive) for the -amount's commodity, dated on or before today's date (or the report end -date if specified), the amount will be converted to the price's -commodity. +amount\[aq]s commodity, dated on or before today\[aq]s date (or the +report end date if specified), the amount will be converted to the +price\[aq]s commodity. .PP When there are multiple applicable P directives, \-V chooses the most recent one, or in case of equal dates, the last\-parsed one. @@ -1102,16 +1104,16 @@ $\ hledger\ \-f\ t.j\ bal\ \-N\ euros\ \-V \f[] .fi .PP -Currently, hledger's \-V only uses market prices recorded with P +Currently, hledger\[aq]s \-V only uses market prices recorded with P directives, not transaction prices (unlike Ledger). .PP Currently, \-V has a limitation in multicolumn balance reports: it uses the market prices on the report end date for all columns. -(Instead of the prices on each column's end date.) +(Instead of the prices on each column\[aq]s end date.) .SS Combining \-B and \-V .PP -Using \-B/\[en]cost and \-V/\[en]value together is currently allowed, -but the results are probably not meaningful. +Using \-B/\-\-cost and \-V/\-\-value together is currently allowed, but +the results are probably not meaningful. Let us know if you find a use for this. .SS Output destination .PP @@ -1154,7 +1156,7 @@ account alias directives and options: \f[C]alias\ /REGEX/\ =\ REPLACEMENT\f[], \f[C]\-\-alias\ /REGEX/=REPLACEMENT\f[] .PP -hledger's regular expressions come from the regex\-tdfa library. +hledger\[aq]s regular expressions come from the regex\-tdfa library. In general they: .IP \[bu] 2 are case insensitive @@ -1186,8 +1188,8 @@ meaning to the shell and so must be escaped at least once more. See Special characters. .SH QUERIES .PP -One of hledger's strengths is being able to quickly report on precise -subsets of your data. +One of hledger\[aq]s strengths is being able to quickly report on +precise subsets of your data. Most commands accept an optional query expression, written as arguments after the command name, to filter the data by date, account name or other criteria. @@ -1285,13 +1287,13 @@ match (or display, depending on command) accounts at or above this depth .TP .B \f[B]\f[BC]note:REGEX\f[B]\f[] match transaction notes (part of description right of \f[C]|\f[], or -whole description when there's no \f[C]|\f[]) +whole description when there\[aq]s no \f[C]|\f[]) .RS .RE .TP .B \f[B]\f[BC]payee:REGEX\f[B]\f[] match transaction payee/payer names (part of description left of -\f[C]|\f[], or whole description when there's no \f[C]|\f[]) +\f[C]|\f[], or whole description when there\[aq]s no \f[C]|\f[]) .RS .RE .TP @@ -1377,7 +1379,7 @@ in flat mode: omit N leading account name parts .RE .PP This command lists account names, either declared with account -directives (\[en]declared), posted to (\[en]used), or both (default). +directives (\-\-declared), posted to (\-\-used), or both (default). With query arguments, only matched account names and account names referenced by matched postings are shown. It shows a flat list by default. @@ -1459,7 +1461,7 @@ $\ hledger\ activity\ \-\-quarterly Prompt for transactions and add them to the journal. .TP .B \f[C]\-\-no\-new\-accounts\f[] -don't allow creating new accounts; helps prevent typos when entering +don\[aq]t allow creating new accounts; helps prevent typos when entering account names .RS .RE @@ -1578,7 +1580,7 @@ show a row total column (in multicolumn mode) .RE .TP .B \f[C]\-N\ \-\-no\-total\f[] -don't show the final total row +don\[aq]t show the final total row .RS .RE .TP @@ -1588,7 +1590,7 @@ omit N leading account name parts (in flat mode) .RE .TP .B \f[C]\-\-no\-elide\f[] -don't squash boring parent accounts (in tree mode) +don\[aq]t squash boring parent accounts (in tree mode) .RS .RE .TP @@ -1603,6 +1605,12 @@ Supported formats: txt, csv, html. .RS .RE .TP +.B \f[C]\-\-transpose\f[] +transposes rows and columns in multi\-column reports. +Supported formats: txt, csv +.RS +.RE +.TP .B \f[C]\-o\ FILE\ \-\-output\-file=FILE\f[] write output to FILE. A file extension matching one of the above formats selects that format. @@ -1633,16 +1641,16 @@ transactions .RE .TP .B \f[C]\-\-show\-unbudgeted\f[] -with \[en]budget, show unbudgeted accounts also +with \-\-budget, show unbudgeted accounts also .RS .RE .PP -The balance command is hledger's most versatile command. +The balance command is hledger\[aq]s most versatile command. Note, despite the name, it is not always used for showing real\-world account balances; the more accounting\-aware balancesheet and incomestatement may be more convenient for that. .PP -By default, it displays all accounts, and each account's change in +By default, it displays all accounts, and each account\[aq]s change in balance during the entire period of the journal. Balance changes are calculated by adding up the postings in each account. @@ -1650,15 +1658,15 @@ You can limit the postings matched, by a query, to see fewer accounts, changes over a different time period, changes from only cleared transactions, etc. .PP -If you include an account's complete history of postings in the report, -the balance change is equivalent to the account's current ending -balance. -For a real\-world account, typically you won't have all transactions in -the journal; instead you'll have all transactions after a certain date, -and an \[lq]opening balances\[rq] transaction setting the correct -starting balance on that date. +If you include an account\[aq]s complete history of postings in the +report, the balance change is equivalent to the account\[aq]s current +ending balance. +For a real\-world account, typically you won\[aq]t have all transactions +in the journal; instead you\[aq]ll have all transactions after a certain +date, and an "opening balances" transaction setting the correct starting +balance on that date. Then the balance command will show real\-world account balances. -In some cases the \-H/\[en]historical flag is used to ensure this (more +In some cases the \-H/\-\-historical flag is used to ensure this (more below). .PP The balance command can produce several styles of report: @@ -1691,14 +1699,14 @@ At each level of the tree, accounts are sorted by account code if any, then by account name. Or with \f[C]\-S/\-\-sort\-amount\f[], by their balance amount. .PP -\[lq]Boring\[rq] accounts, which contain a single interesting subaccount -and no balance of their own, are elided into the following line for more +"Boring" accounts, which contain a single interesting subaccount and no +balance of their own, are elided into the following line for more compact output. -(Eg above, the \[lq]liabilities\[rq] account.) Use -\f[C]\-\-no\-elide\f[] to prevent this. +(Eg above, the "liabilities" account.) Use \f[C]\-\-no\-elide\f[] to +prevent this. .PP -Account balances are \[lq]inclusive\[rq] \- they include the balances of -any subaccounts. +Account balances are "inclusive" \- they include the balances of any +subaccounts. .PP Accounts which have zero balance (and no non\-zero subaccounts) are omitted. @@ -1751,12 +1759,13 @@ MAX truncates at this width (optional) FIELDNAME must be enclosed in parentheses, and can be one of: .RS 2 .IP \[bu] 2 -\f[C]depth_spacer\f[] \- a number of spaces equal to the account's +\f[C]depth_spacer\f[] \- a number of spaces equal to the account\[aq]s depth, or if MIN is specified, MIN * depth spaces. .IP \[bu] 2 -\f[C]account\f[] \- the account's name +\f[C]account\f[] \- the account\[aq]s name .IP \[bu] 2 -\f[C]total\f[] \- the account's balance/posted total, right justified +\f[C]total\f[] \- the account\[aq]s balance/posted total, right +justified .RE .PP Also, FMT can begin with an optional prefix to control how @@ -1775,10 +1784,10 @@ Eg in one\-line mode, \f[C]%(depth_spacer)\f[] has no effect, instead .PP Some example formats: .IP \[bu] 2 -\f[C]%(total)\f[] \- the account's total +\f[C]%(total)\f[] \- the account\[aq]s total .IP \[bu] 2 -\f[C]%\-20.20(account)\f[] \- the account's name, left justified, padded -to 20 characters and clipped at 20 characters +\f[C]%\-20.20(account)\f[] \- the account\[aq]s name, left justified, +padded to 20 characters and clipped at 20 characters .IP \[bu] 2 \f[C]%,%\-50(account)\ \ %25(total)\f[] \- account name padded to 50 characters, total padded to 20 characters, with multiple commodities @@ -1798,7 +1807,7 @@ the output is not being redirected or piped anywhere To see a flat list instead of the default hierarchical display, use \f[C]\-\-flat\f[]. In this mode, accounts (unless depth\-clipped) show their full names and -\[lq]exclusive\[rq] balance, excluding any subaccount balances. +"exclusive" balance, excluding any subaccount balances. In this mode, you can also use \f[C]\-\-drop\ N\f[] to omit the first few account name components. .IP @@ -1840,7 +1849,7 @@ There are three types of multicolumn balance report, showing different information: .IP "1." 3 By default: each column shows the sum of postings in that period, ie the -account's change of balance in that period. +account\[aq]s change of balance in that period. This is useful eg for a monthly income statement: .RS 4 .IP @@ -1914,8 +1923,8 @@ see the hierarchy, use \f[C]\-\-tree\f[]. With a reporting interval (like \f[C]\-\-quarterly\f[] above), the report start/end dates will be adjusted if necessary so that they encompass the displayed report periods. -This is so that the first and last periods will be \[lq]full\[rq] and -comparable to the others. +This is so that the first and last periods will be "full" and comparable +to the others. .PP The \f[C]\-E/\-\-empty\f[] flag does two things in multicolumn balance reports: first, the report will show all columns within the specified @@ -1932,7 +1941,7 @@ the total for each row. The \f[C]\-A/\-\-average\f[] flag adds a column showing the average value in each row. .PP -Here's an example of all three: +Here\[aq]s an example of all three: .IP .nf \f[C] @@ -1958,7 +1967,7 @@ Limitations: .PP In multicolumn reports the \f[C]\-V/\-\-value\f[] flag uses the market price on the report end date, for all columns (not the price on each -column's end date). +column\[aq]s end date). .PP Eliding of boring parent accounts in tree mode, as in the classic balance report, is not yet supported in multicolumn reports. @@ -1969,7 +1978,7 @@ goals for each account and period, if any. Budget goals are defined by periodic transactions. This is very useful for comparing planned and actual income, expenses, time usage, etc. -\[en]budget is most often combined with a report interval. +\-\-budget is most often combined with a report interval. .PP For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget: @@ -2009,24 +2018,52 @@ You can now see a monthly budget report: $\ hledger\ balance\ \-M\ \-\-budget Budget\ performance\ in\ 2017/11/01\-2017/12/31: -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\ -======================++================================================= -\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\ -\ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\ -\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ \ \ $53\ [106%\ of\ $50]\ -\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $412\ [103%\ of\ $400]\ -\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ \ \ \ 0\ [0%\ of\ $30]\ -\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $2100\ [105%\ of\ $2000]\ -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Nov\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Dec\ +======================++==================================================== +\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ +\ assets:bank\ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ +\ assets:bank:checking\ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ +\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $495\ [\ 103%\ of\ \ \ $480]\ \ \ \ $565\ [\ 118%\ of\ \ \ $480]\ +\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ $49\ [\ \ 98%\ of\ \ \ \ $50]\ \ \ \ \ $53\ [\ 106%\ of\ \ \ \ $50]\ +\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ $396\ [\ \ 99%\ of\ \ \ $400]\ \ \ \ $412\ [\ 103%\ of\ \ \ $400]\ +\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ $30\ [\ 100%\ of\ \ \ \ $30]\ \ \ \ \ \ \ 0\ [\ \ \ 0%\ of\ \ \ \ $30]\ +\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $1950\ [\ \ 98%\ of\ \ $2000]\ \ \ $2100\ [\ 105%\ of\ \ $2000]\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ \ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ \f[] .fi .PP By default, only accounts with budget goals during the report period are shown. -\f[C]\-\-show\-unbudgeted\f[] shows unbudgeted accounts as well. -Top\-level accounts with no budget goals anywhere below them are grouped -under \f[C]\f[]. +In the example above, transactions in \f[C]expenses:gifts\f[] and +\f[C]expenses:supplies\f[] are counted towards \f[C]expenses\f[] budget, +but accounts \f[C]expenses:gifts\f[] and \f[C]expenses:supplies\f[] are +not shown, as they don\[aq]t have any budgets. +.PP +You can use \f[C]\-\-show\-unbudgeted\f[] shows unbudgeted accounts as +well: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-M\ \-\-budget\ \-\-show\-unbudgeted +Budget\ performance\ in\ 2017/11/01\-2017/12/31: + +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Nov\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Dec\ +======================++==================================================== +\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ +\ assets:bank\ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ +\ assets:bank:checking\ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-2665\ [\ 107%\ of\ $\-2480]\ +\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $495\ [\ 103%\ of\ \ \ $480]\ \ \ \ $565\ [\ 118%\ of\ \ \ $480]\ +\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ $49\ [\ \ 98%\ of\ \ \ \ $50]\ \ \ \ \ $53\ [\ 106%\ of\ \ \ \ $50]\ +\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ $396\ [\ \ 99%\ of\ \ \ $400]\ \ \ \ $412\ [\ 103%\ of\ \ \ $400]\ +\ expenses:gifts\ \ \ \ \ \ \ ||\ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ +\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ $30\ [\ 100%\ of\ \ \ \ $30]\ \ \ \ \ \ \ 0\ [\ \ \ 0%\ of\ \ \ \ $30]\ +\ expenses:supplies\ \ \ \ ||\ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ +\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $1950\ [\ \ 98%\ of\ \ $2000]\ \ \ $2100\ [\ 105%\ of\ \ $2000]\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ \ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ +\f[] +.fi .PP You can roll over unspent budgets to next period with \f[C]\-\-cumulative\f[]: @@ -2036,16 +2073,18 @@ You can roll over unspent budgets to next period with $\ hledger\ balance\ \-M\ \-\-budget\ \-\-cumulative Budget\ performance\ in\ 2017/11/01\-2017/12/31: -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12/31\ -======================++================================================= -\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $120\ -\ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-5110\ [103%\ of\ $\-4960]\ -\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ $102\ [102%\ of\ $100]\ -\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $808\ [101%\ of\ $800]\ -\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ $30\ [50%\ of\ $60]\ -\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $4050\ [101%\ of\ $4000]\ -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Nov\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Dec\ +======================++==================================================== +\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-5110\ [\ 103%\ of\ $\-4960]\ +\ assets:bank\ \ \ \ \ \ \ \ \ \ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-5110\ [\ 103%\ of\ $\-4960]\ +\ assets:bank:checking\ ||\ $\-2445\ [\ \ 99%\ of\ $\-2480]\ \ $\-5110\ [\ 103%\ of\ $\-4960]\ +\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $495\ [\ 103%\ of\ \ \ $480]\ \ \ $1060\ [\ 110%\ of\ \ \ $960]\ +\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ $49\ [\ \ 98%\ of\ \ \ \ $50]\ \ \ \ $102\ [\ 102%\ of\ \ \ $100]\ +\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ $396\ [\ \ 99%\ of\ \ \ $400]\ \ \ \ $808\ [\ 101%\ of\ \ \ $800]\ +\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ $30\ [\ 100%\ of\ \ \ \ $30]\ \ \ \ \ $30\ [\ \ 50%\ of\ \ \ \ $60]\ +\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $1950\ [\ \ 98%\ of\ \ $2000]\ \ \ $4050\ [\ 101%\ of\ \ $4000]\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ \ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ \f[] .fi .PP @@ -2053,6 +2092,108 @@ Note, the \f[C]\-S/\-\-sort\-amount\f[] flag is not yet fully supported with \f[C]\-\-budget\f[]. .PP For more examples, see Budgeting and Forecasting. +.SS Nested budgets +.PP +You can add budgets to any account in your account hierarchy. +If you have budgets on both parent account and some of its children, +then budget(s) of the child account(s) would be added to the budget of +their parent, much like account balances behave. +.PP +In the most simple case this means that once you add a budget to any +account, all its parents would have budget as well. +.PP +To illustrate this, consider the following budget: +.IP +.nf +\f[C] +~\ monthly\ from\ 2019/01 +\ \ \ \ expenses:personal\ \ \ \ \ \ \ \ \ \ \ \ \ $1,000.00 +\ \ \ \ expenses:personal:electronics\ \ \ \ $100.00 +\ \ \ \ liabilities +\f[] +.fi +.PP +With this, monthly budget for electronics is defined to be $100 and +budget for personal expenses is an additional $1000, which implicity +means that budget for both \f[C]expenses:personal\f[] and +\f[C]expenses\f[] is $1100. +.PP +Transactions in \f[C]expenses:personal:electronics\f[] will be counted +both towards its $100 budget and $1100 of \f[C]expenses:personal\f[] , +and transactions in any other subaccount of \f[C]expenses:personal\f[] +would be counted towards only towards the budget of +\f[C]expenses:personal\f[]. +.PP +For example, let\[aq]s consider these transactions: +.IP +.nf +\f[C] +~\ monthly\ from\ 2019/01 +\ \ \ \ expenses:personal\ \ \ \ \ \ \ \ \ \ \ \ \ $1,000.00 +\ \ \ \ expenses:personal:electronics\ \ \ \ $100.00 +\ \ \ \ liabilities + +2019/01/01\ Google\ home\ hub +\ \ \ \ expenses:personal:electronics\ \ \ \ \ \ \ \ \ \ $90.00 +\ \ \ \ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-90.00 + +2019/01/02\ Phone\ screen\ protector +\ \ \ \ expenses:personal:electronics:upgrades\ \ \ \ \ \ \ \ \ \ $10.00 +\ \ \ \ liabilities + +2019/01/02\ Weekly\ train\ ticket +\ \ \ \ expenses:personal:train\ tickets\ \ \ \ \ \ \ $153.00 +\ \ \ \ liabilities + +2019/01/03\ Flowers +\ \ \ \ expenses:personal\ \ \ \ \ \ \ \ \ \ $30.00 +\ \ \ \ liabilities +\f[] +.fi +.PP +As you can see, we have transactions in +\f[C]expenses:personal:electronics:upgrades\f[] and +\f[C]expenses:personal:train\ tickets\f[], and since both of these +accounts are without explicitly defined budget, these transactions would +be counted towards budgets of \f[C]expenses:personal:electronics\f[] and +\f[C]expenses:personal\f[] accordingly: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-\-budget\ \-M +Budget\ performance\ in\ 2019/01: + +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Jan\ +===============================++=============================== +\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $283.00\ [\ \ 26%\ of\ \ $1100.00]\ +\ expenses:personal\ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $283.00\ [\ \ 26%\ of\ \ $1100.00]\ +\ expenses:personal:electronics\ ||\ \ $100.00\ [\ 100%\ of\ \ \ $100.00]\ +\ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-283.00\ [\ \ 26%\ of\ $\-1100.00]\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ +\f[] +.fi +.PP +And with \f[C]\-\-show\-unbudgeted\f[], we can get a better picture of +budget allocation and consumption: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-\-budget\ \-M\ \-\-show\-unbudgeted +Budget\ performance\ in\ 2019/01: + +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Jan\ +========================================++=============================== +\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $283.00\ [\ \ 26%\ of\ \ $1100.00]\ +\ expenses:personal\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ $283.00\ [\ \ 26%\ of\ \ $1100.00]\ +\ expenses:personal:electronics\ \ \ \ \ \ \ \ \ \ ||\ \ $100.00\ [\ 100%\ of\ \ \ $100.00]\ +\ expenses:personal:electronics:upgrades\ ||\ \ \ $10.00\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ +\ expenses:personal:train\ tickets\ \ \ \ \ \ \ \ ||\ \ $153.00\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ +\ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ $\-283.00\ [\ \ 26%\ of\ $\-1100.00]\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ 0\ [\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0]\ +\f[] +.fi .SS Output format .PP The balance command supports output destination and output format @@ -2111,7 +2252,7 @@ show a row total column (in multicolumn mode) .RE .TP .B \f[C]\-N\ \-\-no\-total\f[] -don't show the final total row +don\[aq]t show the final total row .RS .RE .TP @@ -2121,7 +2262,7 @@ omit N leading account name parts (in flat mode) .RE .TP .B \f[C]\-\-no\-elide\f[] -don't squash boring parent accounts (in tree mode) +don\[aq]t squash boring parent accounts (in tree mode) .RS .RE .TP @@ -2207,7 +2348,7 @@ Total: .SS cashflow .PP This command displays a simple cashflow statement, showing changes in -\[lq]cash\[rq] accounts. +"cash" accounts. It assumes that these accounts are under a top\-level \f[C]asset\f[] account (case insensitive, plural forms also allowed) and do not contain \f[C]receivable\f[] or \f[C]A/R\f[] in their name. @@ -2256,7 +2397,7 @@ show a row total column (in multicolumn mode) .RE .TP .B \f[C]\-N\ \-\-no\-total\f[] -don't show the final total row (in simple reports) +don\[aq]t show the final total row (in simple reports) .RS .RE .TP @@ -2266,7 +2407,7 @@ omit N leading account name parts (in flat mode) .RE .TP .B \f[C]\-\-no\-elide\f[] -don't squash boring parent accounts (in tree mode) +don\[aq]t squash boring parent accounts (in tree mode) .RS .RE .TP @@ -2311,29 +2452,23 @@ selection. .SS check\-dates .PP Check that transactions are sorted by increasing date. -With a query, only matched transactions' dates are checked. +With a query, only matched transactions\[aq] dates are checked. .SS check\-dupes .PP Report account names having the same leaf but different prefixes. An example: http://stefanorodighiero.net/software/hledger\-dupes.html .SS close .PP -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, +close, equity Prints a "closing balances" transaction and an "opening +balances" 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 +Useful for bringing asset/liability balances forward into a new journal +file, or for 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]. +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 \f[C]\-\-opening\f[] or \f[C]\-\-closing\f[] flag. .PP @@ -2350,11 +2485,11 @@ cancel each other out. 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. +If you\[aq]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 -\[lq]equity:retained earnings\[rq] for clarity.) +"equity:retained earnings".) .PP By default, the closing transaction is dated yesterday, the balances are calculated as of end of yesterday, and the opening transaction is dated @@ -2367,16 +2502,16 @@ 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 +You probably shouldn\[aq]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. +Likewise, if you run this command with \-\-auto, the balance assertions +will probably always require \-\-auto. .PP Examples: .PP Carrying asset/liability balances into a new file for 2019, all from -command line. +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[] @@ -2409,7 +2544,7 @@ balance assertions: \f[] .fi .PP -Here's one way to resolve that: +Here\[aq]s one way to resolve that: .IP .nf \f[C] @@ -2484,13 +2619,13 @@ just show the transactions to be imported The input files are specified as arguments \- no need to write \-f before each one. So eg to add new transactions from all CSV files to the main journal, -it's just: \f[C]hledger\ import\ *.csv\f[] +it\[aq]s just: \f[C]hledger\ import\ *.csv\f[] .PP -New transactions are detected in the same way as print \[en]new: by +New transactions are detected in the same way as print \-\-new: by assuming transactions are always added to the input files in increasing date order, and by saving \f[C]\&.latest.FILE\f[] state files. .PP -The \[en]dry\-run output is in journal format, so you can filter it, eg +The \-\-dry\-run output is in journal format, so you can filter it, eg to see only uncategorised transactions: .IP .nf @@ -2550,7 +2685,7 @@ show a row total column (in multicolumn mode) .RE .TP .B \f[C]\-N\ \-\-no\-total\f[] -don't show the final total row +don\[aq]t show the final total row .RS .RE .TP @@ -2560,7 +2695,7 @@ omit N leading account name parts (in flat mode) .RE .TP .B \f[C]\-\-no\-elide\f[] -don't squash boring parent accounts (in tree mode) +don\[aq]t squash boring parent accounts (in tree mode) .RS .RE .TP @@ -2615,10 +2750,10 @@ selection. .SS prices .PP Print market price directives from the journal. -With \[en]costs, also print synthetic market prices based on transaction +With \-\-costs, also print synthetic market prices based on transaction +prices. +With \-\-inverted\-costs, also print inverse prices based on transaction prices. -With \[en]inverted\-costs, also print inverse prices based on -transaction prices. Prices (and postings providing prices) can be filtered by a query. .SS print .PP @@ -2681,11 +2816,11 @@ $\ hledger\ print .PP The print command displays full journal entries (transactions) from the journal file in date order, tidily formatted. -print's output is always a valid hledger journal. +print\[aq]s output is always a valid hledger journal. It preserves all transaction information, but it does not preserve directives or inter\-transaction comments .PP -Normally, the journal entry's explicit or implicit amount style is +Normally, the journal entry\[aq]s explicit or implicit amount style is preserved. Ie when an amount is omitted in the journal, it will be omitted in the output. @@ -2731,7 +2866,7 @@ See also the import command. .PP This command also supports output destination and output format selection. -Here's an example of print's CSV output: +Here\[aq]s an example of print\[aq]s CSV output: .IP .nf \f[C] @@ -2751,19 +2886,19 @@ $\ hledger\ print\ \-Ocsv \f[] .fi .IP \[bu] 2 -There is one CSV record per posting, with the parent transaction's +There is one CSV record per posting, with the parent transaction\[aq]s fields repeated. .IP \[bu] 2 -The \[lq]txnidx\[rq] (transaction index) field shows which postings -belong to the same transaction. +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 order, etc.) .IP \[bu] 2 -The amount is separated into \[lq]commodity\[rq] (the symbol) and -\[lq]amount\[rq] (numeric quantity) fields. +The amount is separated into "commodity" (the symbol) and "amount" +(numeric quantity) fields. .IP \[bu] 2 -The numeric amount is repeated in either the \[lq]credit\[rq] or -\[lq]debit\[rq] column, for convenience. +The numeric amount is repeated in either the "credit" or "debit" column, +for convenience. (Those names are not accurate in the accounting sense; it just puts negative amounts under credit and zero or greater amounts under debit.) .SS print\-unique @@ -2787,12 +2922,12 @@ start date) .TP .B \f[C]\-A\ \-\-average\f[] show running average of posting amounts instead of total (implies -\[en]empty) +\-\-empty) .RS .RE .TP .B \f[C]\-r\ \-\-related\f[] -show postings' siblings instead +show postings\[aq] siblings instead .RS .RE .TP @@ -2817,7 +2952,7 @@ 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 account, to -see that account's activity: +see that account\[aq]s activity: .IP .nf \f[C] @@ -2890,7 +3025,7 @@ $\ hledger\ register\ \-\-monthly\ income\ \-E \f[] .fi .PP -Often, you'll want to see just one line per interval. +Often, you\[aq]ll want to see just one line per interval. The \f[C]\-\-depth\f[] option helps with this, causing subaccounts to be aggregated: .IP @@ -2918,8 +3053,8 @@ variable (not a bash shell variable) or by using the 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 -\[en]width's argument, comma\-separated: \f[C]\-\-width\ W,D\f[] . -Here's a diagram: +\-\-width\[aq]s argument, comma\-separated: \f[C]\-\-width\ W,D\f[] . +Here\[aq]s a diagram: .IP .nf \f[C] @@ -3011,7 +3146,7 @@ If a numeric second argument is provided, it will set the randomness seed, for repeatable results from tests using randomness (currently none of them). .PP -This is mainly used by developers, but it's nice to be able to +This is mainly used by developers, but it\[aq]s nice to be able to sanity\-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! @@ -3028,8 +3163,8 @@ Add\-ons can be invoked like any hledger command, but there are a few things to be aware of. Eg if the \f[C]hledger\-web\f[] add\-on is installed, .IP \[bu] 2 -\f[C]hledger\ \-h\ web\f[] shows hledger's help, while -\f[C]hledger\ web\ \-h\f[] shows hledger\-web's help. +\f[C]hledger\ \-h\ web\f[] shows hledger\[aq]s help, while +\f[C]hledger\ web\ \-h\f[] shows hledger\-web\[aq]s help. .IP \[bu] 2 Flags specific to the add\-on must have a preceding \f[C]\-\-\f[] to hide them from hledger. @@ -3065,8 +3200,8 @@ These are maintained separately, and usually updated shortly after a hledger release. .SS diff .PP -hledger\-diff shows differences in an account's transactions between one -journal file and another. +hledger\-diff shows differences in an account\[aq]s transactions between +one journal file and another. .SS iadd .PP hledger\-iadd is a curses\-style, more interactive replacement for the @@ -3078,11 +3213,11 @@ according to various schemes. .SS irr .PP hledger\-irr calculates the internal rate of return of an investment -account, but it's superseded now by the built\-in roi command. +account, but it\[aq]s superseded now by the built\-in roi command. .SS Experimental add\-ons .PP -These are available in source form in the hledger repo's bin/ directory; -installing them is pretty easy. +These are available in source form in the hledger repo\[aq]s bin/ +directory; installing them is pretty easy. They may be less mature and documented than built\-in commands. Reading and tweaking these is a good way to start making your own! .SS autosync @@ -3128,7 +3263,7 @@ not supported. In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger add. .PP -Not all of Ledger's journal file syntax is supported. +Not all of Ledger\[aq]s journal file syntax is supported. See file format differences. .PP On large data files, hledger is slower and uses more memory than Ledger. @@ -3138,8 +3273,8 @@ 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): .PP -\f[B]Successfully installed, but \[lq]No command `hledger' -found\[rq]\f[] +\f[B]Successfully installed, but "No command \[aq]hledger\[aq] +found"\f[] .PD 0 .P .PD @@ -3157,10 +3292,10 @@ file\f[] shell variable. The command \f[C]env\ |\ grep\ LEDGER_FILE\f[] should show it. You may need to use \f[C]export\f[]. -Here's an explanation. +Here\[aq]s an explanation. .PP -\f[B]\[lq]Illegal byte sequence\[rq] or \[lq]Invalid or incomplete -multibyte or wide character\[rq] errors\f[] +\f[B]"Illegal byte sequence" or "Invalid or incomplete multibyte or wide +character" errors\f[] .PD 0 .P .PD @@ -3169,9 +3304,9 @@ needs an appropriate locale. This is usually configured system\-wide; you can also configure it temporarily. The locale may need to be one that supports UTF\-8, if you built hledger -with GHC < 7.2 (or possibly always, I'm not sure yet). +with GHC < 7.2 (or possibly always, I\[aq]m not sure yet). .PP -Here's an example of setting the locale temporarily, on ubuntu +Here\[aq]s an example of setting the locale temporarily, on ubuntu gnu/linux: .IP .nf @@ -3186,7 +3321,8 @@ $\ LANG=en_US.utf8\ hledger\ \-f\ my.journal\ print\ \ \ #\ <\-\ use\ it\ for\ t \f[] .fi .PP -Here's one way to set it permanently, there are probably better ways: +Here\[aq]s one way to set it permanently, there are probably better +ways: .IP .nf \f[C] diff --git a/hledger/hledger.info b/hledger/hledger.info index acda77529..977ff6157 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -520,7 +520,7 @@ need to write the date _after_ the last day you want to include. Examples: -'-b 2016/3/17' begin on St. Patrick's day 2016 +'-b 2016/3/17' begin on St. Patrick's day 2016 '-e 12/1' end at the start of december 1st of the current year (11/30 will be the last date included) '-b thismonth' all transactions on or after the 1st of the current month '-p thismonth' all transactions in the current month @@ -1220,6 +1220,10 @@ Show accounts and their balances. Aliases: b, bal. '-O FMT --output-format=FMT' select the output format. Supported formats: txt, csv, html. +'--transpose' + + transposes rows and columns in multi-column reports. Supported + formats: txt, csv '-o FILE --output-file=FILE' write output to FILE. A file extension matching one of the above @@ -1585,42 +1589,158 @@ expense categories to construct a minimal monthly budget: $ hledger balance -M --budget Budget performance in 2017/11/01-2017/12/31: - || 2017/11 2017/12 -======================++================================================= - || $20 $100 - assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480] - expenses:bus || $49 [98% of $50] $53 [106% of $50] - expenses:food || $396 [99% of $400] $412 [103% of $400] - expenses:movies || $30 [100% of $30] 0 [0% of $30] - income || $1950 [98% of $2000] $2100 [105% of $2000] -----------------------++------------------------------------------------- - || 0 0 + || Nov Dec +======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] +----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] By default, only accounts with budget goals during the report period -are shown. '--show-unbudgeted' shows unbudgeted accounts as well. -Top-level accounts with no budget goals anywhere below them are grouped -under ''. +are shown. In the example above, transactions in 'expenses:gifts' and +'expenses:supplies' are counted towards 'expenses' budget, but accounts +'expenses:gifts' and 'expenses:supplies' are not shown, as they don't +have any budgets. + + You can use '--show-unbudgeted' shows unbudgeted accounts as well: + +$ hledger balance -M --budget --show-unbudgeted +Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec +======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:gifts || 0 $100 + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + expenses:supplies || $20 0 + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] +----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] You can roll over unspent budgets to next period with '--cumulative': $ hledger balance -M --budget --cumulative Budget performance in 2017/11/01-2017/12/31: - || 2017/11/30 2017/12/31 -======================++================================================= - || $20 $120 - assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960] - expenses:bus || $49 [98% of $50] $102 [102% of $100] - expenses:food || $396 [99% of $400] $808 [101% of $800] - expenses:movies || $30 [100% of $30] $30 [50% of $60] - income || $1950 [98% of $2000] $4050 [101% of $4000] -----------------------++------------------------------------------------- - || 0 0 + || Nov Dec +======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + expenses || $495 [ 103% of $480] $1060 [ 110% of $960] + expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] + expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] + expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] + income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] +----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] Note, the '-S/--sort-amount' flag is not yet fully supported with '--budget'. For more examples, see Budgeting and Forecasting. +* Menu: + +* Nested budgets:: + + +File: hledger.info, Node: Nested budgets, Up: Budget report + +4.4.7.1 Nested budgets +...................... + +You can add budgets to any account in your account hierarchy. If you +have budgets on both parent account and some of its children, then +budget(s) of the child account(s) would be added to the budget of their +parent, much like account balances behave. + + In the most simple case this means that once you add a budget to any +account, all its parents would have budget as well. + + To illustrate this, consider the following budget: + +~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + + With this, monthly budget for electronics is defined to be $100 and +budget for personal expenses is an additional $1000, which implicity +means that budget for both 'expenses:personal' and 'expenses' is $1100. + + Transactions in 'expenses:personal:electronics' will be counted both +towards its $100 budget and $1100 of 'expenses:personal' , and +transactions in any other subaccount of 'expenses:personal' would be +counted towards only towards the budget of 'expenses:personal'. + + For example, let's consider these transactions: + +~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + +2019/01/01 Google home hub + expenses:personal:electronics $90.00 + liabilities $-90.00 + +2019/01/02 Phone screen protector + expenses:personal:electronics:upgrades $10.00 + liabilities + +2019/01/02 Weekly train ticket + expenses:personal:train tickets $153.00 + liabilities + +2019/01/03 Flowers + expenses:personal $30.00 + liabilities + + As you can see, we have transactions in +'expenses:personal:electronics:upgrades' and 'expenses:personal:train +tickets', and since both of these accounts are without explicitly +defined budget, these transactions would be counted towards budgets of +'expenses:personal:electronics' and 'expenses:personal' accordingly: + +$ hledger balance --budget -M +Budget performance in 2019/01: + + || Jan +===============================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + liabilities || $-283.00 [ 26% of $-1100.00] +-------------------------------++------------------------------- + || 0 [ 0] + + And with '--show-unbudgeted', we can get a better picture of budget +allocation and consumption: + +$ hledger balance --budget -M --show-unbudgeted +Budget performance in 2019/01: + + || Jan +========================================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + expenses:personal:electronics:upgrades || $10.00 + expenses:personal:train tickets || $153.00 + liabilities || $-283.00 [ 26% of $-1100.00] +----------------------------------------++------------------------------- + || 0 [ 0] 4.4.8 Output format ------------------- @@ -1851,15 +1971,11 @@ File: hledger.info, Node: close, Next: files, Prev: check-dupes, Up: COMMAND 4.10 close ========== -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 +close, equity Prints a "closing balances" transaction and an "opening +balances" transaction that bring account balances to and from zero, +respectively. Useful for bringing asset/liability balances forward into +a new journal file, or for 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 @@ -1881,7 +1997,7 @@ register reports; you can exclude them with a query like "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.) +earnings".) By default, the closing transaction is dated yesterday, the balances are calculated as of end of yesterday, and the opening transaction is @@ -1900,7 +2016,7 @@ require -auto. Examples: Carrying asset/liability balances into a new file for 2019, all from -command line. +command line: _Warning: we use '>>' here to append; be careful not to type a single '>' which would wipe your journal!_ @@ -2660,122 +2776,124 @@ Node: Smart dates14210 Ref: #smart-dates14351 Node: Report start & end date15757 Ref: #report-start-end-date15929 -Node: Report intervals16994 -Ref: #report-intervals17159 -Node: Period expressions17560 -Ref: #period-expressions17720 -Node: Depth limiting21677 -Ref: #depth-limiting21821 -Node: Pivoting22163 -Ref: #pivoting22281 -Node: Cost23957 -Ref: #cost24065 -Node: Market value24183 -Ref: #market-value24318 -Node: Combining -B and -V25684 -Ref: #combining--b-and--v25847 -Node: Output destination25994 -Ref: #output-destination26156 -Node: Output format26439 -Ref: #output-format26591 -Node: Regular expressions26976 -Ref: #regular-expressions27113 -Node: QUERIES28474 -Ref: #queries28576 -Node: COMMANDS32538 -Ref: #commands32650 -Node: accounts33650 -Ref: #accounts33748 -Node: activity34994 -Ref: #activity35104 -Node: add35464 -Ref: #add35563 -Node: balance38224 -Ref: #balance38335 -Node: Classic balance report41418 -Ref: #classic-balance-report41591 -Node: Customising the classic balance report42960 -Ref: #customising-the-classic-balance-report43188 -Node: Colour support45262 -Ref: #colour-support45429 -Node: Flat mode45602 -Ref: #flat-mode45750 -Node: Depth limited balance reports46163 -Ref: #depth-limited-balance-reports46363 -Node: Multicolumn balance report46819 -Ref: #multicolumn-balance-report47017 -Node: Budget report52197 -Ref: #budget-report52340 -Ref: #output-format-155374 -Node: balancesheet55452 -Ref: #balancesheet55588 -Node: balancesheetequity57899 -Ref: #balancesheetequity58048 -Node: cashflow58585 -Ref: #cashflow58713 -Node: check-dates60836 -Ref: #check-dates60963 -Node: check-dupes61080 -Ref: #check-dupes61204 -Node: close61341 -Ref: #close61449 -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 +Node: Report intervals16995 +Ref: #report-intervals17160 +Node: Period expressions17561 +Ref: #period-expressions17721 +Node: Depth limiting21678 +Ref: #depth-limiting21822 +Node: Pivoting22164 +Ref: #pivoting22282 +Node: Cost23958 +Ref: #cost24066 +Node: Market value24184 +Ref: #market-value24319 +Node: Combining -B and -V25685 +Ref: #combining--b-and--v25848 +Node: Output destination25995 +Ref: #output-destination26157 +Node: Output format26440 +Ref: #output-format26592 +Node: Regular expressions26977 +Ref: #regular-expressions27114 +Node: QUERIES28475 +Ref: #queries28577 +Node: COMMANDS32539 +Ref: #commands32651 +Node: accounts33651 +Ref: #accounts33749 +Node: activity34995 +Ref: #activity35105 +Node: add35465 +Ref: #add35564 +Node: balance38225 +Ref: #balance38336 +Node: Classic balance report41526 +Ref: #classic-balance-report41699 +Node: Customising the classic balance report43068 +Ref: #customising-the-classic-balance-report43296 +Node: Colour support45370 +Ref: #colour-support45537 +Node: Flat mode45710 +Ref: #flat-mode45858 +Node: Depth limited balance reports46271 +Ref: #depth-limited-balance-reports46471 +Node: Multicolumn balance report46927 +Ref: #multicolumn-balance-report47125 +Node: Budget report52305 +Ref: #budget-report52448 +Node: Nested budgets57152 +Ref: #nested-budgets57264 +Ref: #output-format-160764 +Node: balancesheet60842 +Ref: #balancesheet60978 +Node: balancesheetequity63289 +Ref: #balancesheetequity63438 +Node: cashflow63975 +Ref: #cashflow64103 +Node: check-dates66226 +Ref: #check-dates66353 +Node: check-dupes66470 +Ref: #check-dupes66594 +Node: close66731 +Ref: #close66839 +Node: files70253 +Ref: #files70354 +Node: help70495 +Ref: #help70595 +Node: import71669 +Ref: #import71783 +Node: incomestatement72513 +Ref: #incomestatement72647 +Node: prices75051 +Ref: #prices75166 +Node: print75438 +Ref: #print75548 +Node: print-unique80442 +Ref: #print-unique80568 +Node: register80636 +Ref: #register80763 +Node: Custom register output85264 +Ref: #custom-register-output85393 +Node: register-match86623 +Ref: #register-match86757 +Node: rewrite86940 +Ref: #rewrite87055 +Node: roi87124 +Ref: #roi87222 +Node: stats87338 +Ref: #stats87437 +Node: tags88307 +Ref: #tags88405 +Node: test88641 +Ref: #test88725 +Node: ADD-ON COMMANDS89433 +Ref: #add-on-commands89543 +Node: Official add-ons90830 +Ref: #official-add-ons90970 +Node: api91057 +Ref: #api91146 +Node: ui91198 +Ref: #ui91297 +Node: web91355 +Ref: #web91444 +Node: Third party add-ons91490 +Ref: #third-party-add-ons91665 +Node: diff91800 +Ref: #diff91897 +Node: iadd91996 +Ref: #iadd92110 +Node: interest92193 +Ref: #interest92314 +Node: irr92409 +Ref: #irr92507 +Node: Experimental add-ons92638 +Ref: #experimental-add-ons92790 +Node: autosync93070 +Ref: #autosync93181 +Node: chart93420 +Ref: #chart93539 +Node: check93610 +Ref: #check93712  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 5f1ebe1f3..ada9547f8 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -135,7 +135,7 @@ OPTIONS FILE.rules) --separator=CHAR - Field separator to expect when reading CSV (default: `,') + Field separator to expect when reading CSV (default: ',') --alias=OLD=NEW rename accounts named OLD to NEW @@ -444,8 +444,8 @@ OPTIONS Examples: - -b 2016/3/17 begin on St. Patrick's day - 2016 + -b 2016/3/17 begin on St. Patrick's + day 2016 -e 12/1 end at the start of decem- ber 1st of the current year (11/30 will be the @@ -538,10 +538,10 @@ OPTIONS For example: - -p "weekly from 2009/1/1 to 2009/4/1" - - starts on 2008/12/29, closest preceed- - ing Monday - -p "monthly in 2008/11/25" - starts on + -p "weekly from 2009/1/1 to 2009/4/1" + -- starts on 2008/12/29, closest pre- + ceeding Monday + -p "monthly in 2008/11/25" -- starts on 2018/11/01 -p "quar- terly from 2009-05-05 to 2009-06-01" - @@ -561,14 +561,14 @@ OPTIONS Examples: - -p "bimonthly from 2008" - periods will - have boundaries on 2008/01/01, + -p "bimonthly from 2008" -- periods + will have boundaries on 2008/01/01, 2008/03/01, ... - -p "every 2 weeks" - starts on closest + -p "every 2 weeks" -- starts on closest preceeding Monday - -p "every 5 month from 2009/03" - peri- - ods will have boundaries on 2009/03/01, - 2009/08/01, ... + -p "every 5 month from 2009/03" -- + periods will have boundaries on + 2009/03/01, 2009/08/01, ... If you want intervals that start on arbitrary day of your choosing and span a week, month or year, you need to use any of the following: @@ -580,18 +580,18 @@ OPTIONS Examples: - -p "every 2nd day of week" - periods + -p "every 2nd day of week" -- periods will go from Tue to Tue - -p "every Tue" - same - -p "every 15th day" - period boundaries - will be on 15th of each month - -p "every 2nd Monday" - period bound- + -p "every Tue" -- same + -p "every 15th day" -- period bound- + aries will be on 15th of each month + -p "every 2nd Monday" -- period bound- aries will be on second Monday of each month - -p "every 11/05" - yearly periods with + -p "every 11/05" -- yearly periods with boundaries on 5th of Nov - -p "every 5th Nov" - same - -p "every Nov 5th" - same + -p "every 5th Nov" -- same + -p "every Nov 5th" -- same Show historical balances at end of 15th each month (N is exclusive end date): @@ -714,7 +714,7 @@ OPTIONS the prices on each column's end date.) Combining -B and -V - Using -B/-cost and -V/-value together is currently allowed, but the + Using -B/--cost and -V/--value together is currently allowed, but the results are probably not meaningful. Let us know if you find a use for this. @@ -918,7 +918,7 @@ COMMANDS in flat mode: omit N leading account name parts This command lists account names, either declared with account direc- - tives (-declared), posted to (-used), or both (default). With query + tives (--declared), posted to (--used), or both (default). With query arguments, only matched account names and account names referenced by matched postings are shown. It shows a flat list by default. With --tree, it uses indentation to show the account hierarchy. In flat @@ -1088,15 +1088,19 @@ COMMANDS -O FMT --output-format=FMT select the output format. Supported formats: txt, csv, html. + --transpose + transposes rows and columns in multi-column reports. 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. --pretty-tables use unicode to display prettier tables. --sort-amount - sort by amount instead of account code/name (in flat mode). + sort by amount instead of account code/name (in flat mode). With multiple columns, sorts by the row total, or by row average if that is displayed. @@ -1104,36 +1108,36 @@ COMMANDS display all amounts with reversed sign --budget - show performance compared to budget goals defined by periodic + show performance compared to budget goals defined by periodic transactions --show-unbudgeted - with -budget, show unbudgeted accounts also + with --budget, show unbudgeted accounts also The balance command is hledger's most versatile command. Note, despite - the name, it is not always used for showing real-world account bal- - ances; the more accounting-aware balancesheet and incomestatement may + the name, it is not always used for showing real-world account bal- + ances; the more accounting-aware balancesheet and incomestatement may be more convenient for that. By default, it displays all accounts, and each account's change in bal- ance during the entire period of the journal. Balance changes are cal- - culated by adding up the postings in each account. You can limit the - postings matched, by a query, to see fewer accounts, changes over a + culated by adding up the postings in each account. You can limit the + postings matched, by a query, to see fewer accounts, changes over a different time period, changes from only cleared transactions, etc. If you include an account's complete history of postings in the report, - the balance change is equivalent to the account's current ending bal- - ance. For a real-world account, typically you won't have all transac- + the balance change is equivalent to the account's current ending bal- + ance. For a real-world account, typically you won't have all transac- tions in the journal; instead you'll have all transactions after a cer- - tain date, and an "opening balances" transaction setting the correct - starting balance on that date. Then the balance command will show - real-world account balances. In some cases the -H/-historical flag is + tain date, and an "opening balances" transaction setting the correct + starting balance on that date. Then the balance command will show + real-world account balances. In some cases the -H/--historical flag is used to ensure this (more below). The balance command can produce several styles of report: Classic balance report - This is the original balance report, as found in Ledger. It usually + This is the original balance report, as found in Ledger. It usually looks like this: $ hledger balance @@ -1150,23 +1154,23 @@ COMMANDS -------------------- 0 - By default, accounts are displayed hierarchically, with subaccounts - indented below their parent. At each level of the tree, accounts are - sorted by account code if any, then by account name. Or with + By default, accounts are displayed hierarchically, with subaccounts + indented below their parent. At each level of the tree, accounts are + sorted by account code if any, then by account name. Or with -S/--sort-amount, by their balance amount. "Boring" accounts, which contain a single interesting subaccount and no - balance of their own, are elided into the following line for more com- - pact output. (Eg above, the "liabilities" account.) Use --no-elide to + balance of their own, are elided into the following line for more com- + pact output. (Eg above, the "liabilities" account.) Use --no-elide to prevent this. - Account balances are "inclusive" - they include the balances of any + Account balances are "inclusive" - they include the balances of any subaccounts. - Accounts which have zero balance (and no non-zero subaccounts) are + Accounts which have zero balance (and no non-zero subaccounts) are omitted. Use -E/--empty to show them. - A final total is displayed by default; use -N/--no-total to suppress + A final total is displayed by default; use -N/--no-total to suppress it, eg: $ hledger balance -p 2008/6 expenses --no-total @@ -1175,7 +1179,7 @@ COMMANDS $1 supplies Customising the classic balance report - You can customise the layout of classic balance reports with --for- + You can customise the layout of classic balance reports with --for- mat FMT: $ hledger balance --format "%20(account) %12(total)" @@ -1193,7 +1197,7 @@ COMMANDS 0 The FMT format string (plus a newline) specifies the formatting applied - to each account/balance pair. It may contain any suitable text, with + to each account/balance pair. It may contain any suitable text, with data fields interpolated like so: %[MIN][.MAX](FIELDNAME) @@ -1204,14 +1208,14 @@ COMMANDS o FIELDNAME must be enclosed in parentheses, and can be one of: - o depth_spacer - a number of spaces equal to the account's depth, or + o depth_spacer - a number of spaces equal to the account's depth, or if MIN is specified, MIN * depth spaces. o account - the account's name o total - the account's balance/posted total, right justified - Also, FMT can begin with an optional prefix to control how multi-com- + Also, FMT can begin with an optional prefix to control how multi-com- modity amounts are rendered: o %_ - render on multiple lines, bottom-aligned (the default) @@ -1220,7 +1224,7 @@ COMMANDS o %, - render on one line, comma-separated - There are some quirks. Eg in one-line mode, %(depth_spacer) has no + There are some quirks. Eg in one-line mode, %(depth_spacer) has no effect, instead %(account) has indentation built in. Experimentation may be needed to get pleasing results. @@ -1228,14 +1232,14 @@ COMMANDS o %(total) - the account's total - o %-20.20(account) - the account's name, left justified, padded to 20 + o %-20.20(account) - the account's name, left justified, padded to 20 characters and clipped at 20 characters - o %,%-50(account) %25(total) - account name padded to 50 characters, - total padded to 20 characters, with multiple commodities rendered on + o %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on one line - o %20(total) %2(depth_spacer)%-(account) - the default format for the + o %20(total) %2(depth_spacer)%-(account) - the default format for the single-column balance report Colour support @@ -1246,9 +1250,9 @@ COMMANDS o the output is not being redirected or piped anywhere Flat mode - To see a flat list instead of the default hierarchical display, use - --flat. In this mode, accounts (unless depth-clipped) show their full - names and "exclusive" balance, excluding any subaccount balances. In + To see a flat list instead of the default hierarchical display, use + --flat. In this mode, accounts (unless depth-clipped) show their full + names and "exclusive" balance, excluding any subaccount balances. In this mode, you can also use --drop N to omit the first few account name components. @@ -1257,8 +1261,8 @@ COMMANDS $1 supplies Depth limited balance reports - With --depth N or depth:N or just -N, balance reports show accounts - only to the specified numeric depth. This is very useful to summarise + With --depth N or depth:N or just -N, balance reports show accounts + only to the specified numeric depth. This is very useful to summarise a complex set of accounts and get an overview. $ hledger balance -N -1 @@ -1271,17 +1275,17 @@ COMMANDS inclusive balances at the depth limit. Multicolumn balance report - Multicolumn or tabular balance reports are a very useful hledger fea- - ture, and usually the preferred style. They share many of the above - features, but they show the report as a table, with columns represent- - ing time periods. This mode is activated by providing a reporting + Multicolumn or tabular balance reports are a very useful hledger fea- + ture, and usually the preferred style. They share many of the above + features, but they show the report as a table, with columns represent- + ing time periods. This mode is activated by providing a reporting interval. - There are three types of multicolumn balance report, showing different + There are three types of multicolumn balance report, showing different information: 1. By default: each column shows the sum of postings in that period, ie - the account's change of balance in that period. This is useful eg + the account's change of balance in that period. This is useful eg for a monthly income statement: $ hledger balance --quarterly income expenses -E @@ -1296,8 +1300,8 @@ COMMANDS -------------------++--------------------------------- || $-1 $1 0 0 - 2. With --cumulative: each column shows the ending balance for that - period, accumulating the changes across periods, starting from 0 at + 2. With --cumulative: each column shows the ending balance for that + period, accumulating the changes across periods, starting from 0 at the report start date: $ hledger balance --quarterly income expenses -E --cumulative @@ -1313,8 +1317,8 @@ COMMANDS || $-1 0 0 0 3. With --historical/-H: each column shows the actual historical ending - balance for that period, accumulating the changes across periods, - starting from the actual balance at the report start date. This is + balance for that period, accumulating the changes across periods, + starting from the actual balance at the report start date. This is useful eg for a multi-period balance sheet, and when you are showing only the data after a certain start date: @@ -1330,26 +1334,26 @@ COMMANDS ----------------------++------------------------------------- || 0 0 0 - Multicolumn balance reports display accounts in flat mode by default; + Multicolumn balance reports display accounts in flat mode by default; to see the hierarchy, use --tree. - With a reporting interval (like --quarterly above), the report - start/end dates will be adjusted if necessary so that they encompass + With a reporting interval (like --quarterly above), the report + start/end dates will be adjusted if necessary so that they encompass the displayed report periods. This is so that the first and last peri- ods will be "full" and comparable to the others. - The -E/--empty flag does two things in multicolumn balance reports: - first, the report will show all columns within the specified report - period (without -E, leading and trailing columns with all zeroes are - not shown). Second, all accounts which existed at the report start - date will be considered, not just the ones with activity during the + The -E/--empty flag does two things in multicolumn balance reports: + first, the report will show all columns within the specified report + period (without -E, leading and trailing columns with all zeroes are + not shown). Second, all accounts which existed at the report start + date will be considered, not just the ones with activity during the report period (use -E to include low-activity accounts which would oth- erwise would be omitted). The -T/--row-total flag adds an additional column showing the total for each row. - The -A/--average flag adds a column showing the average value in each + The -A/--average flag adds a column showing the average value in each row. Here's an example of all three: @@ -1373,20 +1377,20 @@ COMMANDS Limitations: In multicolumn reports the -V/--value flag uses the market price on the - report end date, for all columns (not the price on each column's end + report end date, for all columns (not the price on each column's end date). - Eliding of boring parent accounts in tree mode, as in the classic bal- + Eliding of boring parent accounts in tree mode, as in the classic bal- ance report, is not yet supported in multicolumn reports. Budget report - With --budget, extra columns are displayed showing budget goals for - each account and period, if any. Budget goals are defined by periodic - transactions. This is very useful for comparing planned and actual - income, expenses, time usage, etc. -budget is most often combined with - a report interval. + With --budget, extra columns are displayed showing budget goals for + each account and period, if any. Budget goals are defined by periodic + transactions. This is very useful for comparing planned and actual + income, expenses, time usage, etc. --budget is most often combined + with a report interval. - For example, you can take average monthly expenses in the common + For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget: ;; Budget @@ -1418,43 +1422,151 @@ COMMANDS $ hledger balance -M --budget Budget performance in 2017/11/01-2017/12/31: - || 2017/11 2017/12 - ======================++================================================= - || $20 $100 - assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480] - expenses:bus || $49 [98% of $50] $53 [106% of $50] - expenses:food || $396 [99% of $400] $412 [103% of $400] - expenses:movies || $30 [100% of $30] 0 [0% of $30] - income || $1950 [98% of $2000] $2100 [105% of $2000] - ----------------------++------------------------------------------------- - || 0 0 + || Nov Dec + ======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] + ----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] - By default, only accounts with budget goals during the report period - are shown. --show-unbudgeted shows unbudgeted accounts as well. - Top-level accounts with no budget goals anywhere below them are grouped - under . + By default, only accounts with budget goals during the report period + are shown. In the example above, transactions in expenses:gifts and + expenses:supplies are counted towards expenses budget, but accounts + expenses:gifts and expenses:supplies are not shown, as they don't have + any budgets. + + You can use --show-unbudgeted shows unbudgeted accounts as well: + + $ hledger balance -M --budget --show-unbudgeted + Budget performance in 2017/11/01-2017/12/31: + + || Nov Dec + ======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:gifts || 0 $100 + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + expenses:supplies || $20 0 + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] + ----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] You can roll over unspent budgets to next period with --cumulative: $ hledger balance -M --budget --cumulative Budget performance in 2017/11/01-2017/12/31: - || 2017/11/30 2017/12/31 - ======================++================================================= - || $20 $120 - assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960] - expenses:bus || $49 [98% of $50] $102 [102% of $100] - expenses:food || $396 [99% of $400] $808 [101% of $800] - expenses:movies || $30 [100% of $30] $30 [50% of $60] - income || $1950 [98% of $2000] $4050 [101% of $4000] - ----------------------++------------------------------------------------- - || 0 0 + || Nov Dec + ======================++==================================================== + assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + expenses || $495 [ 103% of $480] $1060 [ 110% of $960] + expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] + expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] + expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] + income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] + ----------------------++---------------------------------------------------- + || 0 [ 0] 0 [ 0] Note, the -S/--sort-amount flag is not yet fully supported with --bud- get. For more examples, see Budgeting and Forecasting. + Nested budgets + You can add budgets to any account in your account hierarchy. If you + have budgets on both parent account and some of its children, then bud- + get(s) of the child account(s) would be added to the budget of their + parent, much like account balances behave. + + In the most simple case this means that once you add a budget to any + account, all its parents would have budget as well. + + To illustrate this, consider the following budget: + + ~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + + With this, monthly budget for electronics is defined to be $100 and + budget for personal expenses is an additional $1000, which implicity + means that budget for both expenses:personal and expenses is $1100. + + Transactions in expenses:personal:electronics will be counted both + towards its $100 budget and $1100 of expenses:personal , and transac- + tions in any other subaccount of expenses:personal would be counted + towards only towards the budget of expenses:personal. + + For example, let's consider these transactions: + + ~ monthly from 2019/01 + expenses:personal $1,000.00 + expenses:personal:electronics $100.00 + liabilities + + 2019/01/01 Google home hub + expenses:personal:electronics $90.00 + liabilities $-90.00 + + 2019/01/02 Phone screen protector + expenses:personal:electronics:upgrades $10.00 + liabilities + + 2019/01/02 Weekly train ticket + expenses:personal:train tickets $153.00 + liabilities + + 2019/01/03 Flowers + expenses:personal $30.00 + liabilities + + As you can see, we have transactions in expenses:personal:electron- + ics:upgrades and expenses:personal:train tickets, and since both of + these accounts are without explicitly defined budget, these transac- + tions would be counted towards budgets of expenses:personal:electronics + and expenses:personal accordingly: + + $ hledger balance --budget -M + Budget performance in 2019/01: + + || Jan + ===============================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + liabilities || $-283.00 [ 26% of $-1100.00] + -------------------------------++------------------------------- + || 0 [ 0] + + And with --show-unbudgeted, we can get a better picture of budget allo- + cation and consumption: + + $ hledger balance --budget -M --show-unbudgeted + Budget performance in 2019/01: + + || Jan + ========================================++=============================== + expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + expenses:personal:electronics:upgrades || $10.00 + expenses:personal:train tickets || $153.00 + liabilities || $-283.00 [ 26% of $-1100.00] + ----------------------------------------++------------------------------- + || 0 [ 0] + Output format The balance command supports output destination and output format selection. @@ -1646,58 +1758,53 @@ COMMANDS example: http://stefanorodighiero.net/software/hledger-dupes.html close - close, equity + close, equity Prints a "closing balances" transaction and an "opening + balances" transaction that bring account balances to and from zero, + respectively. Useful for bringing asset/liability balances forward + into a new journal file, or for closing out revenues/expenses to + retained earnings at the end of a period. - 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 + 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- + 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 + 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.) + ings".) - 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. + 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- + 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. + 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. + 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 > + 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 @@ -1729,19 +1836,19 @@ COMMANDS 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 @@ -1765,7 +1872,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 @@ -1775,28 +1882,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 @@ -1830,8 +1937,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 @@ -1856,18 +1963,19 @@ 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 - -inverted-costs, also print inverse prices based on transaction prices. - Prices (and postings providing prices) can be filtered by a query. + 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. print Show transactions from the journal. Aliases: p, txns. @@ -1997,7 +2105,7 @@ COMMANDS -A --average show running average of posting amounts instead of total - (implies -empty) + (implies --empty) -r --related show postings' siblings instead @@ -2087,7 +2195,7 @@ COMMANDS 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: + description width as part of --width's argument, comma-separated: --width W,D . Here's a diagram: <--------------------------------- width (W) ----------------------------------> @@ -2285,7 +2393,7 @@ TROUBLESHOOTING remember you can also seek help from the IRC channel, mail list or bug tracker): - Successfully installed, but "No command `hledger' found" + 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, that is ~/.local/bin and ~/.cabal/bin respectively.