;update manuals

hledger/hledger.1

@@ -2680,11 +2680,8 @@ $ hledger balance
 .fi
 .PP
 By default, accounts are displayed hierarchically, with subaccounts
-indented below their parent.
+indented below their parent, with accounts at each level of the tree
-At each level of the tree, accounts are sorted by account code if any,
+sorted by declaration order if declared, then by account name.
-then by account name.
-Or with \f[C]-S/--sort-amount\f[R], by their balance amount, largest
-first.
 .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

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
+indented below their parent, with accounts at each level of the tree
-sorted by account code if any, then by account name.  Or with
+sorted by declaration order if declared, then by account name.
-'-S/--sort-amount', by their balance amount, largest first.
 
    "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
+Node: Classic balance report75005
-Ref: #classic-balance-report75156
+Ref: #classic-balance-report75178
-Node: Customising the classic balance report76540
+Node: Customising the classic balance report76502
-Ref: #customising-the-classic-balance-report76768
+Ref: #customising-the-classic-balance-report76730
-Node: Colour support78844
+Node: Colour support78806
-Ref: #colour-support79011
+Ref: #colour-support78973
-Node: Flat mode79107
+Node: Flat mode79069
-Ref: #flat-mode79255
+Ref: #flat-mode79217
-Node: Depth limited balance reports79668
+Node: Depth limited balance reports79630
-Ref: #depth-limited-balance-reports79853
+Ref: #depth-limited-balance-reports79815
-Node: Percentages80309
+Node: Percentages80271
-Ref: #percentages80475
+Ref: #percentages80428
-Node: Multicolumn balance report81612
+Node: Sorting by amount81565
-Ref: #multicolumn-balance-report81792
+Ref: #sorting-by-amount81731
-Node: Budget report87389
+Node: Multicolumn balance report82239
-Ref: #budget-report87532
+Ref: #multicolumn-balance-report82425
-Node: Nested budgets92798
+Node: Budget report88022
-Ref: #nested-budgets92910
+Ref: #budget-report88165
-Ref: #output-format-296391
+Node: Nested budgets93431
-Node: balancesheet96588
+Ref: #nested-budgets93543
-Ref: #balancesheet96724
+Ref: #output-format-297026
-Node: balancesheetequity98236
+Node: balancesheet97223
-Ref: #balancesheetequity98385
+Ref: #balancesheet97359
-Node: cashflow99461
+Node: balancesheetequity98871
-Ref: #cashflow99589
+Ref: #balancesheetequity99020
-Node: check-dates100805
+Node: cashflow100096
-Ref: #check-dates100932
+Ref: #cashflow100224
-Node: check-dupes101211
+Node: check-dates101440
-Ref: #check-dupes101337
+Ref: #check-dates101567
-Node: close101630
+Node: check-dupes101846
-Ref: #close101738
+Ref: #check-dupes101972
-Node: close usage103260
+Node: close102265
-Ref: #close-usage103353
+Ref: #close102373
-Node: codes106166
+Node: close usage103895
-Ref: #codes106274
+Ref: #close-usage103988
-Node: commodities106986
+Node: codes106801
-Ref: #commodities107113
+Ref: #codes106909
-Node: descriptions107195
+Node: commodities107621
-Ref: #descriptions107323
+Ref: #commodities107748
-Node: diff107627
+Node: descriptions107830
-Ref: #diff107733
+Ref: #descriptions107958
-Node: files108780
+Node: diff108262
-Ref: #files108880
+Ref: #diff108368
-Node: help109027
+Node: files109415
-Ref: #help109127
+Ref: #files109515
-Node: import110208
+Node: help109662
-Ref: #import110322
+Ref: #help109762
-Node: Importing balance assignments111215
+Node: import110843
-Ref: #importing-balance-assignments111363
+Ref: #import110957
-Node: incomestatement112012
+Node: Importing balance assignments111850
-Ref: #incomestatement112145
+Ref: #importing-balance-assignments111998
-Node: notes113490
+Node: incomestatement112647
-Ref: #notes113603
+Ref: #incomestatement112780
-Node: payees113971
+Node: notes114125
-Ref: #payees114077
+Ref: #notes114238
-Node: prices114497
+Node: payees114606
-Ref: #prices114603
+Ref: #payees114712
-Node: print114944
+Node: prices115132
-Ref: #print115054
+Ref: #prices115238
-Node: print-unique119850
+Node: print115579
-Ref: #print-unique119976
+Ref: #print115689
-Node: register120261
+Node: print-unique120485
-Ref: #register120388
+Ref: #print-unique120611
-Node: Custom register output124837
+Node: register120896
-Ref: #custom-register-output124966
+Ref: #register121023
-Node: register-match126303
+Node: Custom register output125472
-Ref: #register-match126437
+Ref: #custom-register-output125601
-Node: rewrite126788
+Node: register-match126938
-Ref: #rewrite126903
+Ref: #register-match127072
-Node: Re-write rules in a file128758
+Node: rewrite127423
-Ref: #re-write-rules-in-a-file128892
+Ref: #rewrite127538
-Node: Diff output format130102
+Node: Re-write rules in a file129393
-Ref: #diff-output-format130271
+Ref: #re-write-rules-in-a-file129527
-Node: rewrite vs print --auto131363
+Node: Diff output format130737
-Ref: #rewrite-vs.-print---auto131542
+Ref: #diff-output-format130906
-Node: roi132098
+Node: rewrite vs print --auto131998
-Ref: #roi132196
+Ref: #rewrite-vs.-print---auto132177
-Node: stats133208
+Node: roi132733
-Ref: #stats133307
+Ref: #roi132831
-Node: tags134095
+Node: stats133843
-Ref: #tags134193
+Ref: #stats133942
-Node: test134712
+Node: tags134730
-Ref: #test134820
+Ref: #tags134828
-Node: Add-on commands135567
+Node: test135347
-Ref: #add-on-commands135684
+Ref: #test135455
-Node: ui137027
+Node: Add-on commands136202
-Ref: #ui137115
+Ref: #add-on-commands136319
-Node: web137169
+Node: ui137662
-Ref: #web137272
+Ref: #ui137750
-Node: iadd137388
+Node: web137804
-Ref: #iadd137499
+Ref: #web137907
-Node: interest137581
+Node: iadd138023
-Ref: #interest137688
+Ref: #iadd138134
-Node: ENVIRONMENT137928
+Node: interest138216
-Ref: #environment138040
+Ref: #interest138323
-Node: FILES139025
+Node: ENVIRONMENT138563
-Ref: #files-1139128
+Ref: #environment138675
-Node: LIMITATIONS139341
+Node: FILES139660
-Ref: #limitations139460
+Ref: #files-1139763
-Node: TROUBLESHOOTING140202
+Node: LIMITATIONS139976
-Ref: #troubleshooting140315
+Ref: #limitations140095
+Node: TROUBLESHOOTING140837
+Ref: #troubleshooting140950
 
 End Tag Table
 

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
+       dented below their parent, with accounts at  each  level  of  the  tree
-       sorted  by  account  code  if  any,  then  by  account  name.   Or with
+       sorted by declaration order if declared, then by account name.
-       -S/--sort-amount, by their balance amount, largest first.
 
        "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