;doc: regen manuals

[ci skip]

hledger/Hledger/Cli/Commands/Balance.txt

@@ -160,6 +160,34 @@ $ hledger balance -N -1
 Flat-mode balance reports, which normally show exclusive balances, show
 inclusive balances at the depth limit.
 
+Percentages
+
+With -% or --percent, balance reports show each account's value
+expressed as a percentage of the column's total. This is useful to get
+an overview of the relative sizes of account balances. For example to
+obtain an overview of expenses:
+
+$ hledger balance expenses -%
+             100.0 %  expenses
+              50.0 %    food
+              50.0 %    supplies
+--------------------
+             100.0 %
+
+Note that --tree does not have an effect on -%. The percentages are
+always relative to the total sum of each column, they are never relative
+to the parent account.
+
+Since the percentages are relative to the columns sum, it is usually not
+useful to calculate percentages if the signs of the amounts are mixed.
+Although the results are technically correct, they are most likely
+useless. Especially in a balance report that sums up to zero (eg
+hledger balance -B) all percentage values will be zero.
+
+This flag does not work if the report contains any mixed commodity
+accounts. If there are mixed commodity accounts in the report be sure to
+use -V or -B to coerce the report into using a single commodity.
+
 Multicolumn balance report
 
 Multicolumn or tabular balance reports are a very useful hledger

hledger/Hledger/Cli/Commands/Balancesheet.txt

@@ -37,7 +37,7 @@ report mode with --change/--cumulative/--historical. Normally
 balancesheet shows historical ending balances, which is what you need
 for a balance sheet; note this means it ignores report begin dates (and
 -T/--row-total, since summing end balances generally does not make
-sense).
+sense). Instead of absolute values percentages can be displayed with -%.
 
 This command also supports output destination and output format
 selection.

hledger/Hledger/Cli/Commands/Cashflow.txt

@@ -27,7 +27,8 @@ Total:
 With a reporting interval, multiple columns will be shown, one for each
 report period. Normally cashflow shows changes in assets per period,
 though as with multicolumn balance reports you can alter the report mode
-with --change/--cumulative/--historical.
+with --change/--cumulative/--historical. Instead of absolute values
+percentages can be displayed with -%.
 
 This command also supports output destination and output format
 selection.

hledger/Hledger/Cli/Commands/Incomestatement.txt

@@ -36,7 +36,8 @@ Total:
 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 mode with --change/--cumulative/--historical.
+report mode with --change/--cumulative/--historical. Instead of absolute
+values percentages can be displayed with -%.
 
 This command also supports output destination and output format
 selection.

hledger/hledger.1

@@ -2083,6 +2083,41 @@ $ hledger balance -N -1
 .PP
 Flat-mode balance reports, which normally show exclusive balances, show
 inclusive balances at the depth limit.
+.SS Percentages
+.PP
+With \f[C]-%\f[R] or \f[C]--percent\f[R], balance reports show each
+account\[aq]s value expressed as a percentage of the column\[aq]s total.
+This is useful to get an overview of the relative sizes of account
+balances.
+For example to obtain an overview of expenses:
+.IP
+.nf
+\f[C]
+$ hledger balance expenses -%
+             100.0 %  expenses
+              50.0 %    food
+              50.0 %    supplies
+--------------------
+             100.0 %
+\f[R]
+.fi
+.PP
+Note that \f[C]--tree\f[R] does not have an effect on \f[C]-%\f[R].
+The percentages are always relative to the total sum of each column,
+they are never relative to the parent account.
+.PP
+Since the percentages are relative to the columns sum, it is usually not
+useful to calculate percentages if the signs of the amounts are mixed.
+Although the results are technically correct, they are most likely
+useless.
+Especially in a balance report that sums up to zero (eg
+\f[C]hledger balance -B\f[R]) all percentage values will be zero.
+.PP
+This flag does not work if the report contains any mixed commodity
+accounts.
+If there are mixed commodity accounts in the report be sure to use
+\f[C]-V\f[R] or \f[C]-B\f[R] to coerce the report into using a single
+commodity.
 .SS Multicolumn balance report
 .PP
 Multicolumn or tabular balance reports are a very useful hledger
@@ -2510,6 +2545,8 @@ Normally balancesheet shows historical ending balances, which is what
 you need for a balance sheet; note this means it ignores report begin
 dates (and \f[C]-T/--row-total\f[R], since summing end balances
 generally does not make sense).
+Instead of absolute values percentages can be displayed with
+\f[C]-%\f[R].
 .PP
 This command also supports output destination and output format
 selection.
@@ -2591,6 +2628,8 @@ report period.
 Normally cashflow shows changes in assets per period, though as with
 multicolumn balance reports you can alter the report mode with
 \f[C]--change\f[R]/\f[C]--cumulative\f[R]/\f[C]--historical\f[R].
+Instead of absolute values percentages can be displayed with
+\f[C]-%\f[R].
 .PP
 This command also supports output destination and output format
 selection.
@@ -2942,6 +2981,8 @@ report period.
 Normally incomestatement shows revenues/expenses per period, though as
 with multicolumn balance reports you can alter the report mode with
 \f[C]--change\f[R]/\f[C]--cumulative\f[R]/\f[C]--historical\f[R].
+Instead of absolute values percentages can be displayed with
+\f[C]-%\f[R].
 .PP
 This command also supports output destination and output format
 selection.

hledger/hledger.info

@@ -1498,6 +1498,7 @@ is used to ensure this (more below).
 * Colour support::
 * Flat mode::
 * Depth limited balance reports::
+* Percentages::
 * Multicolumn balance report::
 * Budget report::
 * Output format::
@@ -1639,7 +1640,7 @@ $ hledger balance -p 2008/6 expenses -N --flat --drop 1
                   $1  supplies
 
 
-File: hledger.info,  Node: Depth limited balance reports,  Next: Multicolumn balance report,  Prev: Flat mode,  Up: balance
+File: hledger.info,  Node: Depth limited balance reports,  Next: Percentages,  Prev: Flat mode,  Up: balance
 
 4.4.5 Depth limited balance reports
 -----------------------------------
@@ -1658,9 +1659,41 @@ $ hledger balance -N -1
 show inclusive balances at the depth limit.
 
 
-File: hledger.info,  Node: Multicolumn balance report,  Next: Budget report,  Prev: Depth limited balance reports,  Up: balance
+File: hledger.info,  Node: Percentages,  Next: Multicolumn balance report,  Prev: Depth limited balance reports,  Up: balance
 
-4.4.6 Multicolumn balance report
+4.4.6 Percentages
+-----------------
+
+With '-%' or '--percent', balance reports show each account's value
+expressed as a percentage of the column's total.  This is useful to get
+an overview of the relative sizes of account balances.  For example to
+obtain an overview of expenses:
+
+$ hledger balance expenses -%
+             100.0 %  expenses
+              50.0 %    food
+              50.0 %    supplies
+--------------------
+             100.0 %
+
+   Note that '--tree' does not have an effect on '-%'.  The percentages
+are always relative to the total sum of each column, they are never
+relative to the parent account.
+
+   Since the percentages are relative to the columns sum, it is usually
+not useful to calculate percentages if the signs of the amounts are
+mixed.  Although the results are technically correct, they are most
+likely useless.  Especially in a balance report that sums up to zero (eg
+'hledger balance -B') all percentage values will be zero.
+
+   This flag does not work if the report contains any mixed commodity
+accounts.  If there are mixed commodity accounts in the report be sure
+to use '-V' or '-B' to coerce the report into using a single commodity.
+
+
+File: hledger.info,  Node: Multicolumn balance report,  Next: Budget report,  Prev: Percentages,  Up: balance
+
+4.4.7 Multicolumn balance report
 --------------------------------
 
 Multicolumn or tabular balance reports are a very useful hledger
@@ -1777,7 +1810,7 @@ balance report, is not yet supported in multicolumn reports.
 
 File: hledger.info,  Node: Budget report,  Next: ,  Prev: Multicolumn balance report,  Up: balance
 
-4.4.7 Budget report
+4.4.8 Budget report
 -------------------
 
 With '--budget', extra columns are displayed showing budget goals for
@@ -1900,7 +1933,7 @@ Budget performance in 2017/11/01-2017/12/31:
 
 File: hledger.info,  Node: Nested budgets,  Up: Budget report
 
-4.4.7.1 Nested budgets
+4.4.8.1 Nested budgets
 ......................
 
 You can add budgets to any account in your account hierarchy.  If you
@@ -1985,7 +2018,7 @@ Budget performance in 2019/01:
 ----------------------------------------++-------------------------------
                                         ||        0 [                 0] 
 
-4.4.8 Output format
+4.4.9 Output format
 -------------------
 
 The balance command supports output destination and output format
@@ -2034,7 +2067,8 @@ the report mode with '--change'/'--cumulative'/'--historical'.  Normally
 balancesheet shows historical ending balances, which is what you need
 for a balance sheet; note this means it ignores report begin dates (and
 '-T/--row-total', since summing end balances generally does not make
-sense).
+sense).  Instead of absolute values percentages can be displayed with
+'-%'.
 
    This command also supports output destination and output format
 selection.
@@ -2108,7 +2142,8 @@ Total:
    With a reporting interval, multiple columns will be shown, one for
 each report period.  Normally cashflow shows changes in assets per
 period, though as with multicolumn balance reports you can alter the
-report mode with '--change'/'--cumulative'/'--historical'.
+report mode with '--change'/'--cumulative'/'--historical'.  Instead of
+absolute values percentages can be displayed with '-%'.
 
    This command also supports output destination and output format
 selection.
@@ -2428,7 +2463,8 @@ Total:
    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 mode with '--change'/'--cumulative'/'--historical'.
+report mode with '--change'/'--cumulative'/'--historical'.  Instead of
+absolute values percentages can be displayed with '-%'.
 
    This command also supports output destination and output format
 selection.
@@ -3222,107 +3258,109 @@ Node: add46317
 Ref: #add46416
 Node: balance49161
 Ref: #balance49272
-Node: Classic balance report50714
+Node: Classic balance report50730
-Ref: #classic-balance-report50887
+Ref: #classic-balance-report50903
-Node: Customising the classic balance report52256
+Node: Customising the classic balance report52272
-Ref: #customising-the-classic-balance-report52484
+Ref: #customising-the-classic-balance-report52500
-Node: Colour support54560
+Node: Colour support54576
-Ref: #colour-support54727
+Ref: #colour-support54743
-Node: Flat mode54900
+Node: Flat mode54916
-Ref: #flat-mode55048
+Ref: #flat-mode55064
-Node: Depth limited balance reports55461
+Node: Depth limited balance reports55477
-Ref: #depth-limited-balance-reports55661
+Ref: #depth-limited-balance-reports55662
-Node: Multicolumn balance report56117
+Node: Percentages56118
-Ref: #multicolumn-balance-report56315
+Ref: #percentages56284
-Node: Budget report61629
+Node: Multicolumn balance report57421
-Ref: #budget-report61772
+Ref: #multicolumn-balance-report57601
-Node: Nested budgets66974
+Node: Budget report62915
-Ref: #nested-budgets67086
+Ref: #budget-report63058
-Ref: #output-format-170566
+Node: Nested budgets68260
-Node: balancesheet70644
+Ref: #nested-budgets68372
-Ref: #balancesheet70780
+Ref: #output-format-171852
-Node: balancesheetequity72095
+Node: balancesheet71930
-Ref: #balancesheetequity72244
+Ref: #balancesheet72066
-Node: cashflow72805
+Node: balancesheetequity73449
-Ref: #cashflow72933
+Ref: #balancesheetequity73598
-Node: check-dates73961
+Node: cashflow74159
-Ref: #check-dates74088
+Ref: #cashflow74287
-Node: check-dupes74367
+Node: check-dates75383
-Ref: #check-dupes74491
+Ref: #check-dates75510
-Node: close74784
+Node: check-dupes75789
-Ref: #close74898
+Ref: #check-dupes75913
-Node: commodities78485
+Node: close76206
-Ref: #commodities78612
+Ref: #close76320
-Node: descriptions78694
+Node: commodities79907
-Ref: #descriptions78822
+Ref: #commodities80034
-Node: diff79003
+Node: descriptions80116
-Ref: #diff79109
+Ref: #descriptions80244
-Node: files80156
+Node: diff80425
-Ref: #files80256
+Ref: #diff80531
-Node: help80403
+Node: files81578
-Ref: #help80503
+Ref: #files81678
-Node: import81584
+Node: help81825
-Ref: #import81698
+Ref: #help81925
-Node: Importing balance assignments82591
+Node: import83006
-Ref: #importing-balance-assignments82739
+Ref: #import83120
-Node: incomestatement83388
+Node: Importing balance assignments84013
-Ref: #incomestatement83521
+Ref: #importing-balance-assignments84161
-Node: notes84857
+Node: incomestatement84810
-Ref: #notes84970
+Ref: #incomestatement84943
-Node: payees85096
+Node: notes86347
-Ref: #payees85202
+Ref: #notes86460
-Node: prices85360
+Node: payees86586
-Ref: #prices85466
+Ref: #payees86692
-Node: print85807
+Node: prices86850
-Ref: #print85917
+Ref: #prices86956
-Node: print-unique90410
+Node: print87297
-Ref: #print-unique90536
+Ref: #print87407
-Node: register90821
+Node: print-unique91900
-Ref: #register90948
+Ref: #print-unique92026
-Node: Custom register output95120
+Node: register92311
-Ref: #custom-register-output95249
+Ref: #register92438
-Node: register-match96511
+Node: Custom register output96610
-Ref: #register-match96645
+Ref: #custom-register-output96739
-Node: rewrite96996
+Node: register-match98001
-Ref: #rewrite97111
+Ref: #register-match98135
-Node: Re-write rules in a file98966
+Node: rewrite98486
-Ref: #re-write-rules-in-a-file99100
+Ref: #rewrite98601
-Node: Diff output format100310
+Node: Re-write rules in a file100456
-Ref: #diff-output-format100479
+Ref: #re-write-rules-in-a-file100590
-Node: rewrite vs print --auto101571
+Node: Diff output format101800
-Ref: #rewrite-vs.-print---auto101750
+Ref: #diff-output-format101969
-Node: roi102306
+Node: rewrite vs print --auto103061
-Ref: #roi102404
+Ref: #rewrite-vs.-print---auto103240
-Node: stats103416
+Node: roi103796
-Ref: #stats103515
+Ref: #roi103894
-Node: tags104303
+Node: stats104906
-Ref: #tags104401
+Ref: #stats105005
-Node: test104695
+Node: tags105793
-Ref: #test104779
+Ref: #tags105891
-Node: ADD-ON COMMANDS105540
+Node: test106185
-Ref: #add-on-commands105650
+Ref: #test106269
-Node: Official add-ons106938
+Node: ADD-ON COMMANDS107030
-Ref: #official-add-ons107078
+Ref: #add-on-commands107140
-Node: ui107158
+Node: Official add-ons108428
-Ref: #ui107245
+Ref: #official-add-ons108568
-Node: web107299
+Node: ui108648
-Ref: #web107388
+Ref: #ui108735
-Node: Third party add-ons107434
+Node: web108789
-Ref: #third-party-add-ons107609
+Ref: #web108878
-Ref: #diff-1107768
+Node: Third party add-ons108924
-Node: iadd107867
+Ref: #third-party-add-ons109099
-Ref: #iadd107977
+Ref: #diff-1109258
-Node: interest108059
+Node: iadd109357
-Ref: #interest108180
+Ref: #iadd109467
-Node: irr108275
+Node: interest109549
-Ref: #irr108373
+Ref: #interest109670
-Node: Experimental add-ons108504
+Node: irr109765
-Ref: #experimental-add-ons108656
+Ref: #irr109863
-Node: autosync108904
+Node: Experimental add-ons109994
-Ref: #autosync109015
+Ref: #experimental-add-ons110146
-Node: chart109254
+Node: autosync110394
-Ref: #chart109373
+Ref: #autosync110505
-Node: check109444
+Node: chart110744
-Ref: #check109546
+Ref: #chart110863
+Node: check110934
+Ref: #check111036
 
 End Tag Table

hledger/hledger.txt

@@ -1454,6 +1454,33 @@ COMMANDS
        Flat-mode balance reports, which normally show exclusive balances, show
        inclusive balances at the depth limit.
 
+   Percentages
+       With  -%  or  --percent,  balance reports show each account's value ex-
+       pressed as a percentage of the column's total.  This is useful  to  get
+       an  overview of the relative sizes of account balances.  For example to
+       obtain an overview of expenses:
+
+              $ hledger balance expenses -%
+                           100.0 %  expenses
+                            50.0 %    food
+                            50.0 %    supplies
+              --------------------
+                           100.0 %
+
+       Note that --tree does not have an effect on -%.   The  percentages  are
+       always  relative  to the total sum of each column, they are never rela-
+       tive to the parent account.
+
+       Since the percentages are relative to the columns sum,  it  is  usually
+       not  useful  to  calculate  percentages if the signs of the amounts are
+       mixed.  Although the results are technically  correct,  they  are  most
+       likely  useless.   Especially  in a balance report that sums up to zero
+       (eg hledger balance -B) all percentage values will be zero.
+
+       This flag does not work if the report contains any mixed commodity  ac-
+       counts.  If there are mixed commodity accounts in the report be sure to
+       use -V or -B to coerce the report into using a single commodity.
+
    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
@@ -1804,7 +1831,8 @@ COMMANDS
        ancesheet shows historical ending balances, which is what you need  for
        a  balance  sheet;  note  this means it ignores report begin dates (and
        -T/--row-total, since summing end  balances  generally  does  not  make
-       sense).
+       sense).   Instead  of absolute values percentages can be displayed with
+       -%.
 
        This command also supports output destination and output format  selec-
        tion.
@@ -1868,7 +1896,8 @@ COMMANDS
        With a reporting interval, multiple columns will be shown, one for each
        report period.  Normally cashflow shows changes in assets  per  period,
        though  as  with  multicolumn  balance reports you can alter the report
-       mode with --change/--cumulative/--historical.
+       mode with --change/--cumulative/--historical.  Instead of absolute val-
+       ues percentages can be displayed with -%.
 
        This  command also supports output destination and output format selec-
        tion.
@@ -2127,7 +2156,8 @@ COMMANDS
        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 mode with --change/--cumulative/--historical.
+       report  mode with --change/--cumulative/--historical.  Instead of abso-
+       lute values percentages can be displayed with -%.
 
        This command also supports output destination and output format  selec-
        tion.