diff --git a/hledger/Hledger/Cli/Commands/Add.txt b/hledger/Hledger/Cli/Commands/Add.txt index 32cefe700..90e218f0a 100644 --- a/hledger/Hledger/Cli/Commands/Add.txt +++ b/hledger/Hledger/Cli/Commands/Add.txt @@ -24,8 +24,8 @@ Features: - You can also set the initial defaults with command line arguments. - Readline-style edit keys can be used during data entry. - The tab key will auto-complete whenever possible - accounts, - descriptions, dates (yesterday, today, tomorrow). If the input area - is empty, it will insert the default value. + payees/descriptions, dates (yesterday, today, tomorrow). If the + input area is empty, it will insert the default value. - If the journal defines a default commodity, it will be added to any bare numbers entered. - A parenthesised transaction code may be entered following a date. diff --git a/hledger/Hledger/Cli/Commands/Balance.txt b/hledger/Hledger/Cli/Commands/Balance.txt index b9f323a99..3d36bdc21 100644 --- a/hledger/Hledger/Cli/Commands/Balance.txt +++ b/hledger/Hledger/Cli/Commands/Balance.txt @@ -387,29 +387,21 @@ balances: Balance report types The balance command is quite flexible; here is the full detail on how to -control what it reports. There are three important option groups: +control what it reports. If the following seems complicated, don't +worry - this is for advanced reporting, and it does typically take some +time and experimentation to get clear on all these report modes. + +There are three important option groups: hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] ... -The first two are the most important: - -- calculation type selects the basic calculation to perform for each - table cell -- accumulation type says which postings should be included in each - cell's calculation - -Typically one or both of these are selected by default, so you don't -need to write them explicitly. Then - -- a valuation type can be added if you want to convert the basic - report to value or cost - Calculation type The basic calculation to perform for each table cell. It is one of: - --sum : sum the posting amounts (default) -- --budget : like --sum but also show a goal amount +- --budget : sum the amounts, but also show the budget goal amount + (for each account/period) - --valuechange : show the change in period-end historical balance values (caused by deposits, withdrawals, and/or market price fluctuations) @@ -418,36 +410,49 @@ The basic calculation to perform for each table cell. It is one of: Accumulation type -Which postings should be included in each cell's calculation. It is one -of: +How amounts should accumulate across report periods. Another way to say +it: which time period's postings should contribute to each cell's +calculation. It is one of: -- --change : postings from column start to column end, ie within the - cell's period. Typically used to see revenues/expenses. (default for - balance, incomestatement) +- --change : calculate with postings from column start to column end, + ie "just this column". Typically used to see revenues/expenses. + (default for balance, incomestatement) -- --cumulative : postings from report start to column end, eg to show - changes accumulated since the report's start date. Rarely used. +- --cumulative : calculate with postings from report start to column + end, ie "previous columns plus this column". Typically used to show + changes accumulated since the report's start date. Not often used. -- --historical/-H : postings from journal start to column end, ie all - postings from account creation to the end of the cell's period. - Typically used to see historical end balances of +- --historical/-H : calculate with postings from journal start to + column end, ie "all postings from before report start date until + this column's end". Typically used to see historical end balances of assets/liabilities/equity. (default for balancesheet, balancesheetequity, cashflow) Valuation type -Which kind of valuation, valuation date(s) and optionally a target -valuation commodity to use. It is one of: +Which kind of value or cost conversion should be applied, if any, before +displaying the report. It is one of: -- no valuation, show amounts in their original commodities (default) -- --value=cost[,COMM] : no valuation, show amounts converted to cost -- --value=then[,COMM] : show value at transaction dates -- --value=end[,COMM] : show value at period end date(s) (default with - --valuechange, --gain) -- --value=now[,COMM] : show value at today's date -- --value=YYYY-MM-DD[,COMM] : show value at another date +- no valuation type : don't convert to cost or value (default) +- --value=cost[,COMM] : convert amounts to cost (then optionally to + some other commodity) +- --value=then[,COMM] : convert amounts to market value on transaction + dates +- --value=end[,COMM] : convert amounts to market value on period end + date(s) + (default with --valuechange, --gain) +- --value=now[,COMM] : convert amounts to market value on today's date +- --value=YYYY-MM-DD[,COMM] : convert amounts to market value on + another date -or one of their aliases: --cost/-B, --market/-V or --exchange/-X. +or one of the equivalent simpler flags: + +- -B/--cost : like --value=cost (though, note --cost and --value are + independent options which can both be used at once) +- -V/--market : like --value=end +- -X COMM/--exchange COMM : like --value=end,COMM + +See Cost reporting and Valuation for more about these. Combining balance report types @@ -490,8 +495,8 @@ Budget report The --budget report type activates extra columns showing any budget goals for each account and period. The budget goals are defined by -periodic transactions. This is very useful for comparing planned and -actual income, expenses, time usage, etc. +periodic transactions. This is useful for comparing planned and actual +income, expenses, time usage, etc. For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget: @@ -749,21 +754,21 @@ select from multiple budgets defined in your journal. Data layout -The --layout option affects how balance reports show commodity symbols -and multi-commodity amounts, which can improve readability. It can also -normalise the data for easy consumption by other programs. It has four -possible values: +The --layout option affects how balance reports show multi-commodity +amounts and commodity symbols, which can improve readability. It can +also normalise the data for easy consumption by other programs. It has +four possible values: - --layout=wide[,WIDTH]: commodities are shown on a single line, - possibly elided to the specified width + optionally elided to WIDTH - --layout=tall: each commodity is shown on a separate line -- --layout=bare: amounts are shown as bare numbers, with commodity - symbols in a separate column +- --layout=bare: commodity symbols are in their own column, amounts + are bare numbers - --layout=tidy: data is normalised to easily-consumed "tidy" form, - with one row per data value (works only with CSV output) + with one row per data value -These --layout modes are supported with some but not all of the output -formats: +Here are the --layout modes supported by each output format; note only +CSV output supports all of them: - txt csv html json sql ------ ----- ----- ------ ------ ----- @@ -838,7 +843,7 @@ Examples: || VHT 106.00 18.00 170.00 294.00 - Bare layout also affects CSV output, which is useful for producing - data that is easier to consume, eg when making charts: + data that is easier to consume, eg for making charts: $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare "account","commodity","balance" @@ -856,10 +861,8 @@ Examples: - Tidy layout produces normalised "tidy data", where every variable has its own column and each row represents a single data point. See https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html - for more. - - This kind of output is the easiest to process with other software. - Here's how it looks: + for more. This is the easiest kind of data for other software to + consume. Here's how it looks: $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy "account","period","start_date","end_date","commodity","value" @@ -879,12 +882,6 @@ Examples: "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" - Currently tidy layout is supported only with CSV output. - - In tidy mode, row totals, row averages and column totals are not - shown (-T/--row-total and -A/--average flags are disabled and - -N/--no-total is enabled). - Useful balance reports Some frequently used balance options/reports are: diff --git a/hledger/Hledger/Cli/Commands/Stats.txt b/hledger/Hledger/Cli/Commands/Stats.txt index c903e08da..c310b4a1f 100644 --- a/hledger/Hledger/Cli/Commands/Stats.txt +++ b/hledger/Hledger/Cli/Commands/Stats.txt @@ -32,5 +32,5 @@ Market prices : 1000 (A) Run time : 0.12 s Throughput : 8342 txns/s -This command also supports output destination and output format -selection. +This command supports the -o/--output-file option (but not +-O/--output-format selection).