;doc: update manuals

Author: simonmichael

hledger/hledger.1

@@ -730,36 +730,62 @@ quoting than you would at the command prompt.)
 .PP
 Argument files are now superseded by..
 .SS Config files
-hledger will read extra command line options from a
-\f[CR]hledger.conf\f[R] config file.
-These will be inserted early in the command line, so your later options
-can override them if needed.
-The config file can contain general options (which will be used with all
-commands that support them), and command\-specific options (or
-arguments).
-hledger.conf.sample is an example, which you can install as, eg,
-\f[CR]./hledger.conf\f[R] or \f[CR]$HOME/.hledger.conf\f[R].
-.PP
-To be precise, hledger looks for \f[CR]hledger.conf\f[R] in the current
-directory or above, or in your home directory (with a dotted name,
-\f[CR]\[ti]/.hledger.conf\f[R]), or finally in your XDG config directory
-(\f[CR]\[ti]/.config/hledger/hledger.conf\f[R]).
-Or you can select a particular config file by using the
-\f[CR]\-\-conf\f[R] option, or by adding a \f[CR]hledger \-\-conf\f[R]
-shebang line to a config file and executing it like a script (see the
-example file).
-You can inspect the finding and processing of config files with
-\f[CR]\-\-debug\f[R] or \f[CR]\-\-debug=8\f[R].
-.PP
-If you want to run hledger without a config file, to ensure standard
-defaults and behaviour, use the \f[CR]\-n/\-\-no\-conf\f[R] flag.
-This is recommended when using hledger in scripts, and when
-troubleshooting problems.
-.PP
-When both \f[CR]\-\-conf\f[R] and \f[CR]\-\-no\-conf\f[R] options are
-used, the last (right\-most) wins.
-.PP
-\f[I](in master, experimental)\f[R]
+As of hledger 1.40, you can optionally save command line options (or
+arguments) to be used when running hledger commands, in a config file.
+Here\[aq]s a small example:
+.IP
+.EX
+\f[I]# General options are listed first, one or more per line.\f[R]
+\f[I]# These will be used with all hledger commands that support them.\f[R]
+\-\-pretty
+
+\f[I]# Options following a \[ga][COMMANDNAME]\[ga] heading are used with that hledger command only.\f[R]
+\f[B][print]\f[R]
+\-\-explicit \-\-show\-costs
+.EE
+.PP
+To use a config file, specify it with the \f[CR]\-\-conf\f[R] option.
+Its options will be inserted near the start of your command line (so you
+can override them if needed).
+Or, you can add a \f[CR]hledger \-\-conf\f[R] shebang line to a config
+file and execute it like a script.
+.PP
+Or, you can set up an automatic config file that is used whenever you
+run hledger.
+This can be \f[CR]hledger.conf\f[R] in the current directory or above,
+or \f[CR].hledger.conf\f[R] in your home directory
+(\f[CR]\[ti]/.hledger.conf\f[R]), or \f[CR]hledger.conf\f[R] in your XDG
+config directory (\f[CR]\[ti]/.config/hledger/hledger.conf\f[R]).
+.PP
+You can ignore config files by adding the \f[CR]\-n/\-\-no\-conf\f[R]
+flag.
+This is useful when using hledger in scripts, or when troubleshooting.
+(When both \f[CR]\-\-conf\f[R] and \f[CR]\-\-no\-conf\f[R] options are
+used, the right\-most wins.)
+To inspect the processing of config files, use \f[CR]\-\-debug\f[R] or
+\f[CR]\-\-debug=8\f[R].
+.PP
+Here is another example config file you could start with:
+https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample
+.PP
+Automatic config files are convenient, but have a cost: it\[aq]s easy to
+change a report\[aq]s behaviour, or break scripts/applications which use
+hledger, in unintended ways that will surprise you later.
+They change the nature of hledger somewhat, making it less transparent
+and predictable.
+If you decide to use one, here are some tips:
+.IP \[bu] 2
+Be conservative about what you put in it.
+Try to consider the effect on all your reports.
+.IP \[bu] 2
+Whenever a hledger command does not work as expected, try it again with
+\f[CR]\-n\f[R].
+.IP \[bu] 2
+If that helps, you can run it with \f[CR]\-\-debug\f[R] to see how a
+config file affected it.
+.PP
+This feature has been added in hledger 1.40 and is considered
+\f[I]experimental\f[R].
 .SH Output
 .SS Output destination
 hledger commands send their output to the terminal by default.
@@ -8876,6 +8902,9 @@ Flags:
                             description closest to DESC
   \-r \-\-related              show postings\[aq] siblings instead
      \-\-invert               display all amounts with reversed sign
+     \-\-sort=FIELDS          sort by: date, desc, account, amount, absamount,
+                            or a comma\-separated combination of these. For a
+                            descending sort, prefix with \-. (Default: date)
   \-w \-\-width=N              set output width (default: terminal width or
                             $COLUMNS). \-wN,M sets description width as well.
      \-\-align\-all            guarantee alignment across all lines (slower)
@@ -8943,6 +8972,16 @@ For example, it can be used on an income account where amounts are
 normally displayed as negative numbers.
 It\[aq]s also useful to show postings on the checking account together
 with the related account:
+.PP
+The \f[CR]\-\-sort=FIELDS\f[R] flag sorts by the fields given, which can
+be any of \f[CR]account\f[R], \f[CR]amount\f[R], \f[CR]absamount\f[R],
+\f[CR]date\f[R], or \f[CR]desc\f[R]/\f[CR]description\f[R], optionally
+separated by commas.
+For example, \f[CR]\-\-sort account,amount\f[R] will group all
+transactions in each account, sorted by transaction amount.
+Each field can be negated by a preceding \f[CR]\-\f[R], so
+\f[CR]\-\-sort \-amount\f[R] will show transactions ordered from
+smallest amount to largest amount.
 .IP
 .EX
 $ hledger register \-\-related \-\-invert assets:checking