;update manuals

2020-11-05 11:00:17 -10:00 · 2020-11-05 11:00:17 -10:00 · b5656c5909
commit b5656c5909
parent f615c07d0f
3 changed files with 462 additions and 424 deletions
--- a/hledger/hledger.1
+++ b/hledger/hledger.1
@ -2680,11 +2680,8 @@ $ hledger balance
 .fi
 .PP
 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 \f[C]-S/--sort-amount\f[R], by their balance amount, largest
-first.
+indented below their parent, with accounts at each level of the tree
+sorted by declaration order if declared, then by account name.
 .PP
 \[dq]Boring\[dq] accounts, which contain a single interesting subaccount
 and no balance of their own, are elided into the following line for more
@ -2856,6 +2853,19 @@ 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 Sorting by amount
+.PP
+With \f[C]-S\f[R]/\f[C]--sort-amount\f[R], accounts with the largest
+(most positive) balances are shown first.
+For example, \f[C]hledger bal expenses -MAS\f[R] shows your biggest
+averaged monthly expenses first.
+.PP
+Revenues and liability balances are typically negative, however, so
+\f[C]-S\f[R] shows these in reverse order (largest last).
+To work around this, you can add \f[C]--invert\f[R] to flip the signs.
+Or, use one of the sign-flipping report like \f[C]balancesheet\f[R] or
+\f[C]incomestatement\f[R], which also support \f[C]-S\f[R].
+Eg: \f[C]hledger is -MAS\f[R].
 .SS Multicolumn balance report
 .PP
 Multicolumn or tabular balance reports are a very useful hledger
--- a/hledger/hledger.info
+++ b/hledger/hledger.info
@ -2183,6 +2183,7 @@ is used to ensure this (more below).
 * Flat mode::
 * Depth limited balance reports::
 * Percentages::
+* Sorting by amount::
 * Multicolumn balance report::
 * Budget report::
 * Output format::
@ -2211,9 +2212,8 @@ $ hledger balance
                   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
-'-S/--sort-amount', by their balance amount, largest first.
+indented below their parent, with accounts at each level of the tree
+sorted by declaration order if declared, then by account name.

   "Boring" accounts, which contain a single interesting subaccount and
 no balance of their own, are elided into the following line for more
@ -2341,7 +2341,7 @@ $ hledger balance -N -1
 show inclusive balances at the depth limit.


-File: hledger.info,  Node: Percentages,  Next: Multicolumn balance report,  Prev: Depth limited balance reports,  Up: balance
+File: hledger.info,  Node: Percentages,  Next: Sorting by amount,  Prev: Depth limited balance reports,  Up: balance

 3.5.6 Percentages
 -----------------
@ -2373,9 +2373,25 @@ 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
+File: hledger.info,  Node: Sorting by amount,  Next: Multicolumn balance report,  Prev: Percentages,  Up: balance

-3.5.7 Multicolumn balance report
+3.5.7 Sorting by amount
+-----------------------
+
+With '-S'/'--sort-amount', accounts with the largest (most positive)
+balances are shown first.  For example, 'hledger bal expenses -MAS'
+shows your biggest averaged monthly expenses first.
+
+   Revenues and liability balances are typically negative, however, so
+'-S' shows these in reverse order (largest last).  To work around this,
+you can add '--invert' to flip the signs.  Or, use one of the
+sign-flipping report like 'balancesheet' or 'incomestatement', which
+also support '-S'.  Eg: 'hledger is -MAS'.
+
+
+File: hledger.info,  Node: Multicolumn balance report,  Next: Budget report,  Prev: Sorting by amount,  Up: balance
+
+3.5.8 Multicolumn balance report
 --------------------------------

 Multicolumn or tabular balance reports are a very useful hledger
@ -2496,7 +2512,7 @@ bal -D --color=yes | less -RS'.

 File: hledger.info,  Node: Budget report,  Next: ,  Prev: Multicolumn balance report,  Up: balance

-3.5.8 Budget report
+3.5.9 Budget report
 -------------------

 With '--budget', extra columns are displayed showing budget goals for
@ -2619,7 +2635,7 @@ Budget performance in 2017/11/01-2017/12/31:

 File: hledger.info,  Node: Nested budgets,  Up: Budget report

-3.5.8.1 Nested budgets
+3.5.9.1 Nested budgets
 ......................

 You can add budgets to any account in your account hierarchy.  If you
@ -2704,8 +2720,8 @@ Budget performance in 2019/01:
 ----------------------------------------++-------------------------------
                                        ||        0 [                 0] 

-3.5.9 Output format
-------------------
+3.5.10 Output format
+--------------------

 This command also supports the output destination and output format
 options The output formats supported are 'txt', 'csv', (multicolumn
@ -4159,107 +4175,109 @@ Ref: #aregister-and-custom-posting-dates72410
 Ref: #output-format-173003
 Node: balance73408
 Ref: #balance73525
-Node: Classic balance report74983
-Ref: #classic-balance-report75156
-Node: Customising the classic balance report76540
-Ref: #customising-the-classic-balance-report76768
-Node: Colour support78844
-Ref: #colour-support79011
-Node: Flat mode79107
-Ref: #flat-mode79255
-Node: Depth limited balance reports79668
-Ref: #depth-limited-balance-reports79853
-Node: Percentages80309
-Ref: #percentages80475
-Node: Multicolumn balance report81612
-Ref: #multicolumn-balance-report81792
-Node: Budget report87389
-Ref: #budget-report87532
-Node: Nested budgets92798
-Ref: #nested-budgets92910
-Ref: #output-format-296391
-Node: balancesheet96588
-Ref: #balancesheet96724
-Node: balancesheetequity98236
-Ref: #balancesheetequity98385
-Node: cashflow99461
-Ref: #cashflow99589
-Node: check-dates100805
-Ref: #check-dates100932
-Node: check-dupes101211
-Ref: #check-dupes101337
-Node: close101630
-Ref: #close101738
-Node: close usage103260
-Ref: #close-usage103353
-Node: codes106166
-Ref: #codes106274
-Node: commodities106986
-Ref: #commodities107113
-Node: descriptions107195
-Ref: #descriptions107323
-Node: diff107627
-Ref: #diff107733
-Node: files108780
-Ref: #files108880
-Node: help109027
-Ref: #help109127
-Node: import110208
-Ref: #import110322
-Node: Importing balance assignments111215
-Ref: #importing-balance-assignments111363
-Node: incomestatement112012
-Ref: #incomestatement112145
-Node: notes113490
-Ref: #notes113603
-Node: payees113971
-Ref: #payees114077
-Node: prices114497
-Ref: #prices114603
-Node: print114944
-Ref: #print115054
-Node: print-unique119850
-Ref: #print-unique119976
-Node: register120261
-Ref: #register120388
-Node: Custom register output124837
-Ref: #custom-register-output124966
-Node: register-match126303
-Ref: #register-match126437
-Node: rewrite126788
-Ref: #rewrite126903
-Node: Re-write rules in a file128758
-Ref: #re-write-rules-in-a-file128892
-Node: Diff output format130102
-Ref: #diff-output-format130271
-Node: rewrite vs print --auto131363
-Ref: #rewrite-vs.-print---auto131542
-Node: roi132098
-Ref: #roi132196
-Node: stats133208
-Ref: #stats133307
-Node: tags134095
-Ref: #tags134193
-Node: test134712
-Ref: #test134820
-Node: Add-on commands135567
-Ref: #add-on-commands135684
-Node: ui137027
-Ref: #ui137115
-Node: web137169
-Ref: #web137272
-Node: iadd137388
-Ref: #iadd137499
-Node: interest137581
-Ref: #interest137688
-Node: ENVIRONMENT137928
-Ref: #environment138040
-Node: FILES139025
-Ref: #files-1139128
-Node: LIMITATIONS139341
-Ref: #limitations139460
-Node: TROUBLESHOOTING140202
-Ref: #troubleshooting140315
+Node: Classic balance report75005
+Ref: #classic-balance-report75178
+Node: Customising the classic balance report76502
+Ref: #customising-the-classic-balance-report76730
+Node: Colour support78806
+Ref: #colour-support78973
+Node: Flat mode79069
+Ref: #flat-mode79217
+Node: Depth limited balance reports79630
+Ref: #depth-limited-balance-reports79815
+Node: Percentages80271
+Ref: #percentages80428
+Node: Sorting by amount81565
+Ref: #sorting-by-amount81731
+Node: Multicolumn balance report82239
+Ref: #multicolumn-balance-report82425
+Node: Budget report88022
+Ref: #budget-report88165
+Node: Nested budgets93431
+Ref: #nested-budgets93543
+Ref: #output-format-297026
+Node: balancesheet97223
+Ref: #balancesheet97359
+Node: balancesheetequity98871
+Ref: #balancesheetequity99020
+Node: cashflow100096
+Ref: #cashflow100224
+Node: check-dates101440
+Ref: #check-dates101567
+Node: check-dupes101846
+Ref: #check-dupes101972
+Node: close102265
+Ref: #close102373
+Node: close usage103895
+Ref: #close-usage103988
+Node: codes106801
+Ref: #codes106909
+Node: commodities107621
+Ref: #commodities107748
+Node: descriptions107830
+Ref: #descriptions107958
+Node: diff108262
+Ref: #diff108368
+Node: files109415
+Ref: #files109515
+Node: help109662
+Ref: #help109762
+Node: import110843
+Ref: #import110957
+Node: Importing balance assignments111850
+Ref: #importing-balance-assignments111998
+Node: incomestatement112647
+Ref: #incomestatement112780
+Node: notes114125
+Ref: #notes114238
+Node: payees114606
+Ref: #payees114712
+Node: prices115132
+Ref: #prices115238
+Node: print115579
+Ref: #print115689
+Node: print-unique120485
+Ref: #print-unique120611
+Node: register120896
+Ref: #register121023
+Node: Custom register output125472
+Ref: #custom-register-output125601
+Node: register-match126938
+Ref: #register-match127072
+Node: rewrite127423
+Ref: #rewrite127538
+Node: Re-write rules in a file129393
+Ref: #re-write-rules-in-a-file129527
+Node: Diff output format130737
+Ref: #diff-output-format130906
+Node: rewrite vs print --auto131998
+Ref: #rewrite-vs.-print---auto132177
+Node: roi132733
+Ref: #roi132831
+Node: stats133843
+Ref: #stats133942
+Node: tags134730
+Ref: #tags134828
+Node: test135347
+Ref: #test135455
+Node: Add-on commands136202
+Ref: #add-on-commands136319
+Node: ui137662
+Ref: #ui137750
+Node: web137804
+Ref: #web137907
+Node: iadd138023
+Ref: #iadd138134
+Node: interest138216
+Ref: #interest138323
+Node: ENVIRONMENT138563
+Ref: #environment138675
+Node: FILES139660
+Ref: #files-1139763
+Node: LIMITATIONS139976
+Ref: #limitations140095
+Node: TROUBLESHOOTING140837
+Ref: #troubleshooting140950

 End Tag Table

--- a/hledger/hledger.txt
+++ b/hledger/hledger.txt
@ -1867,9 +1867,8 @@ COMMANDS
                                 0

       By default, accounts are displayed hierarchically, with subaccounts in-
-       dented 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, largest first.
+       dented below their parent, with accounts at  each  level  of  the  tree
+       sorted by declaration order if declared, then by account name.

       "Boring" accounts, which contain a single interesting subaccount and no
       balance of their own, are elided into the following line for more  com-
@ -2010,6 +2009,17 @@ COMMANDS
       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.

+   Sorting by amount
+       With  -S/--sort-amount,  accounts with the largest (most positive) bal-
+       ances are shown first.  For example, hledger bal  expenses  -MAS  shows
+       your biggest averaged monthly expenses first.
+
+       Revenues  and liability balances are typically negative, however, so -S
+       shows these in reverse order (largest last).  To work around this,  you
+       can  add  --invert to flip the signs.  Or, use one of the sign-flipping
+       report like balancesheet or incomestatement,  which  also  support  -S.
+       Eg: hledger is -MAS.
+
   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