doc: update manuals

hledger-ui/hledger-ui.1

@@ -70,12 +70,13 @@ and also supports many of hledger\[aq]s general options:
 .IP
 .EX
 General input/data transformation flags:
-  \-f \-\-file=FILE            Read data from FILE, or from stdin if \-. Can be
+  \-f \-\-file=[FMT:]FILE      Read data from FILE, or from stdin if FILE is \-,
-                            specified more than once. If not specified, reads
+                            inferring format from extension or a FMT: prefix.
-                            from $LEDGER_FILE or $HOME/.hledger.journal.
+                            Can be specified more than once. If not specified,
-     \-\-rules\-file=RULEFILE  Use conversion rules from this file for
+                            reads from $LEDGER_FILE or $HOME/.hledger.journal.
+     \-\-rules=RULESFILE      Use rules defined in this rules file for
                             converting subsequent CSV/SSV/TSV files. If not
-                            specified, uses FILE.rules for each such FILE.
+                            specified, uses FILE.csv.rules for each FILE.csv.
      \-\-alias=A=B|/RGX/=RPL  transform account names from A to B, or by
                             replacing regular expression matches
      \-\-auto                 generate extra postings by applying auto posting
@@ -138,7 +139,6 @@ General output/reporting flags (supported by some commands):
      \-\-pretty[=YN]          Use box\-drawing characters in text output? Can be
                             \[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq].
                             If YN is specified, the equals is required.
-     \-\-debug=[1\-9]          show this level of debug output (default: 1)
 
 General help flags:
   \-h \-\-help                 show command line help
@@ -146,6 +146,7 @@ General help flags:
      \-\-info                 show the manual with info
      \-\-man                  show the manual with man
      \-\-version              show version information
+     \-\-debug=[1\-9]          show this level of debug output (default: 1)
 .EE
 .PP
 With hledger\-ui, the \f[CR]\-\-debug\f[R] option sends debug output to

hledger-ui/hledger-ui.info

@@ -81,12 +81,13 @@ Flags:
    and also supports many of hledger's general options:
 
 General input/data transformation flags:
-  -f --file=FILE            Read data from FILE, or from stdin if -. Can be
+  -f --file=[FMT:]FILE      Read data from FILE, or from stdin if FILE is -,
-                            specified more than once. If not specified, reads
+                            inferring format from extension or a FMT: prefix.
-                            from $LEDGER_FILE or $HOME/.hledger.journal.
+                            Can be specified more than once. If not specified,
-     --rules-file=RULEFILE  Use conversion rules from this file for
+                            reads from $LEDGER_FILE or $HOME/.hledger.journal.
+     --rules=RULESFILE      Use rules defined in this rules file for
                             converting subsequent CSV/SSV/TSV files. If not
-                            specified, uses FILE.rules for each such FILE.
+                            specified, uses FILE.csv.rules for each FILE.csv.
      --alias=A=B|/RGX/=RPL  transform account names from A to B, or by
                             replacing regular expression matches
      --auto                 generate extra postings by applying auto posting
@@ -149,7 +150,6 @@ General output/reporting flags (supported by some commands):
      --pretty[=YN]          Use box-drawing characters in text output? Can be
                             'y'/'yes' or 'n'/'no'.
                             If YN is specified, the equals is required.
-     --debug=[1-9]          show this level of debug output (default: 1)
 
 General help flags:
   -h --help                 show command line help
@@ -157,6 +157,7 @@ General help flags:
      --info                 show the manual with info
      --man                  show the manual with man
      --version              show version information
+     --debug=[1-9]          show this level of debug output (default: 1)
 
    With hledger-ui, the '--debug' option sends debug output to a
 'hledger-ui.log' file in the current directory.
@@ -532,34 +533,34 @@ Tag Table:
 Node: Top221
 Node: OPTIONS1872
 Ref: #options1970
-Node: MOUSE8150
+Node: MOUSE8240
-Ref: #mouse8245
+Ref: #mouse8335
-Node: KEYS8482
+Node: KEYS8572
-Ref: #keys8575
+Ref: #keys8665
-Node: SCREENS13230
+Node: SCREENS13320
-Ref: #screens13334
+Ref: #screens13424
-Node: Menu screen13970
+Node: Menu screen14060
-Ref: #menu-screen14091
+Ref: #menu-screen14181
-Node: Cash accounts screen14286
+Node: Cash accounts screen14376
-Ref: #cash-accounts-screen14463
+Ref: #cash-accounts-screen14553
-Node: Balance sheet accounts screen14647
+Node: Balance sheet accounts screen14737
-Ref: #balance-sheet-accounts-screen14863
+Ref: #balance-sheet-accounts-screen14953
-Node: Income statement accounts screen14983
+Node: Income statement accounts screen15073
-Ref: #income-statement-accounts-screen15204
+Ref: #income-statement-accounts-screen15294
-Node: All accounts screen15368
+Node: All accounts screen15458
-Ref: #all-accounts-screen15549
+Ref: #all-accounts-screen15639
-Node: Register screen15731
+Node: Register screen15821
-Ref: #register-screen15890
+Ref: #register-screen15980
-Node: Transaction screen18174
+Node: Transaction screen18264
-Ref: #transaction-screen18332
+Ref: #transaction-screen18422
-Node: Error screen19749
+Node: Error screen19839
-Ref: #error-screen19871
+Ref: #error-screen19961
-Node: WATCH MODE20115
+Node: WATCH MODE20205
-Ref: #watch-mode20232
+Ref: #watch-mode20322
-Node: ENVIRONMENT21691
+Node: ENVIRONMENT21781
-Ref: #environment21807
+Ref: #environment21897
-Node: BUGS21998
+Node: BUGS22088
-Ref: #bugs22081
+Ref: #bugs22171
 
 End Tag Table
 

hledger-ui/hledger-ui.txt

@@ -59,12 +59,13 @@ OPTIONS
        and also supports many of hledger's general options:
 
               General input/data transformation flags:
-                -f --file=FILE            Read data from FILE, or from stdin if -. Can be
+                -f --file=[FMT:]FILE      Read data from FILE, or from stdin if FILE is -,
-                                          specified more than once. If not specified, reads
+                                          inferring format from extension or a FMT: prefix.
-                                          from $LEDGER_FILE or $HOME/.hledger.journal.
+                                          Can be specified more than once. If not specified,
-                   --rules-file=RULEFILE  Use conversion rules from this file for
+                                          reads from $LEDGER_FILE or $HOME/.hledger.journal.
+                   --rules=RULESFILE      Use rules defined in this rules file for
                                           converting subsequent CSV/SSV/TSV files. If not
-                                          specified, uses FILE.rules for each such FILE.
+                                          specified, uses FILE.csv.rules for each FILE.csv.
                    --alias=A=B|/RGX/=RPL  transform account names from A to B, or by
                                           replacing regular expression matches
                    --auto                 generate extra postings by applying auto posting
@@ -127,7 +128,6 @@ OPTIONS
                    --pretty[=YN]          Use box-drawing characters in text output? Can be
                                           'y'/'yes' or 'n'/'no'.
                                           If YN is specified, the equals is required.
-                   --debug=[1-9]          show this level of debug output (default: 1)
 
               General help flags:
                 -h --help                 show command line help
@@ -135,6 +135,7 @@ OPTIONS
                    --info                 show the manual with info
                    --man                  show the manual with man
                    --version              show version information
+                   --debug=[1-9]          show this level of debug output (default: 1)
 
        With  hledger-ui,  the  --debug  option  sends  debug   output   to   a
        hledger-ui.log file in the current directory.

hledger-web/hledger-web.1

@@ -121,12 +121,13 @@ hledger\-web also supports many of hledger\[aq]s general options:
 .IP
 .EX
 General input/data transformation flags:
-  \-f \-\-file=FILE            Read data from FILE, or from stdin if \-. Can be
+  \-f \-\-file=[FMT:]FILE      Read data from FILE, or from stdin if FILE is \-,
-                            specified more than once. If not specified, reads
+                            inferring format from extension or a FMT: prefix.
-                            from $LEDGER_FILE or $HOME/.hledger.journal.
+                            Can be specified more than once. If not specified,
-     \-\-rules\-file=RULEFILE  Use conversion rules from this file for
+                            reads from $LEDGER_FILE or $HOME/.hledger.journal.
+     \-\-rules=RULESFILE      Use rules defined in this rules file for
                             converting subsequent CSV/SSV/TSV files. If not
-                            specified, uses FILE.rules for each such FILE.
+                            specified, uses FILE.csv.rules for each FILE.csv.
      \-\-alias=A=B|/RGX/=RPL  transform account names from A to B, or by
                             replacing regular expression matches
      \-\-auto                 generate extra postings by applying auto posting
@@ -189,7 +190,6 @@ General output/reporting flags (supported by some commands):
      \-\-pretty[=YN]          Use box\-drawing characters in text output? Can be
                             \[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq].
                             If YN is specified, the equals is required.
-     \-\-debug=[1\-9]          show this level of debug output (default: 1)
 
 General help flags:
   \-h \-\-help                 show command line help
@@ -197,6 +197,7 @@ General help flags:
      \-\-info                 show the manual with info
      \-\-man                  show the manual with man
      \-\-version              show version information
+     \-\-debug=[1\-9]          show this level of debug output (default: 1)
 .EE
 .PP
 hledger\-web shows accounts with zero balances by default (like

hledger-web/hledger-web.info

@@ -126,12 +126,13 @@ but not route parsing.
    hledger-web also supports many of hledger's general options:
 
 General input/data transformation flags:
-  -f --file=FILE            Read data from FILE, or from stdin if -. Can be
+  -f --file=[FMT:]FILE      Read data from FILE, or from stdin if FILE is -,
-                            specified more than once. If not specified, reads
+                            inferring format from extension or a FMT: prefix.
-                            from $LEDGER_FILE or $HOME/.hledger.journal.
+                            Can be specified more than once. If not specified,
-     --rules-file=RULEFILE  Use conversion rules from this file for
+                            reads from $LEDGER_FILE or $HOME/.hledger.journal.
+     --rules=RULESFILE      Use rules defined in this rules file for
                             converting subsequent CSV/SSV/TSV files. If not
-                            specified, uses FILE.rules for each such FILE.
+                            specified, uses FILE.csv.rules for each FILE.csv.
      --alias=A=B|/RGX/=RPL  transform account names from A to B, or by
                             replacing regular expression matches
      --auto                 generate extra postings by applying auto posting
@@ -194,7 +195,6 @@ General output/reporting flags (supported by some commands):
      --pretty[=YN]          Use box-drawing characters in text output? Can be
                             'y'/'yes' or 'n'/'no'.
                             If YN is specified, the equals is required.
-     --debug=[1-9]          show this level of debug output (default: 1)
 
 General help flags:
   -h --help                 show command line help
@@ -202,6 +202,7 @@ General help flags:
      --info                 show the manual with info
      --man                  show the manual with man
      --version              show version information
+     --debug=[1-9]          show this level of debug output (default: 1)
 
    hledger-web shows accounts with zero balances by default (like
 'hledger-ui', and unlike 'hledger').  Using the '-E/--empty' flag will
@@ -524,22 +525,22 @@ Tag Table:
 Node: Top223
 Node: OPTIONS2569
 Ref: #options2674
-Node: PERMISSIONS10862
+Node: PERMISSIONS10952
-Ref: #permissions11001
+Ref: #permissions11091
-Node: EDITING UPLOADING DOWNLOADING12213
+Node: EDITING UPLOADING DOWNLOADING12303
-Ref: #editing-uploading-downloading12394
+Ref: #editing-uploading-downloading12484
-Node: RELOADING13228
+Node: RELOADING13318
-Ref: #reloading13362
+Ref: #reloading13452
-Node: JSON API13795
+Node: JSON API13885
-Ref: #json-api13910
+Ref: #json-api14000
-Node: DEBUG OUTPUT19444
+Node: DEBUG OUTPUT19534
-Ref: #debug-output19569
+Ref: #debug-output19659
-Node: Debug output19596
+Node: Debug output19686
-Ref: #debug-output-119697
+Ref: #debug-output-119787
-Node: ENVIRONMENT20114
+Node: ENVIRONMENT20204
-Ref: #environment20233
+Ref: #environment20323
-Node: BUGS20350
+Node: BUGS20440
-Ref: #bugs20434
+Ref: #bugs20524
 
 End Tag Table
 

hledger-web/hledger-web.txt

@@ -103,12 +103,13 @@ OPTIONS
        hledger-web also supports many of hledger's general options:
 
               General input/data transformation flags:
-                -f --file=FILE            Read data from FILE, or from stdin if -. Can be
+                -f --file=[FMT:]FILE      Read data from FILE, or from stdin if FILE is -,
-                                          specified more than once. If not specified, reads
+                                          inferring format from extension or a FMT: prefix.
-                                          from $LEDGER_FILE or $HOME/.hledger.journal.
+                                          Can be specified more than once. If not specified,
-                   --rules-file=RULEFILE  Use conversion rules from this file for
+                                          reads from $LEDGER_FILE or $HOME/.hledger.journal.
+                   --rules=RULESFILE      Use rules defined in this rules file for
                                           converting subsequent CSV/SSV/TSV files. If not
-                                          specified, uses FILE.rules for each such FILE.
+                                          specified, uses FILE.csv.rules for each FILE.csv.
                    --alias=A=B|/RGX/=RPL  transform account names from A to B, or by
                                           replacing regular expression matches
                    --auto                 generate extra postings by applying auto posting
@@ -171,7 +172,6 @@ OPTIONS
                    --pretty[=YN]          Use box-drawing characters in text output? Can be
                                           'y'/'yes' or 'n'/'no'.
                                           If YN is specified, the equals is required.
-                   --debug=[1-9]          show this level of debug output (default: 1)
 
               General help flags:
                 -h --help                 show command line help
@@ -179,6 +179,7 @@ OPTIONS
                    --info                 show the manual with info
                    --man                  show the manual with man
                    --version              show version information
+                   --debug=[1-9]          show this level of debug output (default: 1)
 
        hledger-web  shows  accounts  with  zero  balances  by  default   (like
        hledger-ui,  and  unlike  hledger).  Using the -E/--empty flag will re-

hledger/hledger.1

@@ -43,13 +43,15 @@ should answer it.
 It is detailed, so do skip ahead or skim when needed.
 You can read it on hledger.org, or as an info manual or man page on your
 system.
-You can also get it from hledger itself with
+You can also open a built\-in copy, at a point of interest, by running
 .PD 0
 .P
 .PD
-\f[CR]hledger \-\-man\f[R], \f[CR]hledger \-\-info\f[R] or
+\f[CR]hledger \-\-man [CMD]\f[R], \f[CR]hledger \-\-info [CMD]\f[R] or
 \f[CR]hledger help [TOPIC]\f[R].
 .PP
+(And for shorter help, try \f[CR]hledger \-\-tldr [CMD]\f[R].)
+.PP
 The main function of the hledger CLI is to read plain text files
 describing financial transactions, crunch the numbers, and print a
 useful report on the terminal (or save it as HTML, CSV, JSON or SQL).
@@ -338,17 +340,28 @@ without using \f[CR]hledger\f[R]: \f[CR]hledger\-ui \-\-watch\f[R] or
 \f[CR]hledger\-web \-\-serve\f[R].
 .SH Options
 Run \f[CR]hledger \-h\f[R] to see general command line help.
-The following general options are common to most hledger commands.
+Options can be written either before or after the command name.
-General options can be written either before or after the command name.
+These options are specific to the \f[CR]hledger\f[R] CLI:
+.IP
+.EX
+Flags:
+     \-\-conf=CONFFILE        Use extra options defined in this config file. If
+                            not specified, searches upward and in XDG config
+                            dir for hledger.conf (or .hledger.conf in $HOME).
+  \-n \-\-no\-conf              ignore any config file
+.EE
+.PP
+And the following general options are common to most hledger commands:
 .IP
 .EX
 General input/data transformation flags:
-  \-f \-\-file=FILE            Read data from FILE, or from stdin if \-. Can be
+  \-f \-\-file=[FMT:]FILE      Read data from FILE, or from stdin if FILE is \-,
-                            specified more than once. If not specified, reads
+                            inferring format from extension or a FMT: prefix.
-                            from $LEDGER_FILE or $HOME/.hledger.journal.
+                            Can be specified more than once. If not specified,
-     \-\-rules\-file=RULEFILE  Use conversion rules from this file for
+                            reads from $LEDGER_FILE or $HOME/.hledger.journal.
+     \-\-rules=RULESFILE      Use rules defined in this rules file for
                             converting subsequent CSV/SSV/TSV files. If not
-                            specified, uses FILE.rules for each such FILE.
+                            specified, uses FILE.csv.rules for each FILE.csv.
      \-\-alias=A=B|/RGX/=RPL  transform account names from A to B, or by
                             replacing regular expression matches
      \-\-auto                 generate extra postings by applying auto posting
@@ -411,7 +424,6 @@ General output/reporting flags (supported by some commands):
      \-\-pretty[=YN]          Use box\-drawing characters in text output? Can be
                             \[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq].
                             If YN is specified, the equals is required.
-     \-\-debug=[1\-9]          show this level of debug output (default: 1)
 
 General help flags:
   \-h \-\-help                 show command line help
@@ -419,6 +431,7 @@ General help flags:
      \-\-info                 show the manual with info
      \-\-man                  show the manual with man
      \-\-version              show version information
+     \-\-debug=[1\-9]          show this level of debug output (default: 1)
 .EE
 .PP
 Usually hledger accepts any unambiguous flag prefix, eg you can write
@@ -709,12 +722,40 @@ then reuse them by writing \f[CR]\[at]FILENAME\f[R] as a command line
 argument.
 Eg: \f[CR]hledger bal \[at]foo.args\f[R].
 .PP
-Inside the argument file, each line should contain just one option or
+(Inside the argument file, each line should contain just one option or
 argument.
-Don\[aq]t use spaces except inside quotes (or you\[aq]ll see a confusing
+Don\[aq]t use spaces except inside quotes; write \f[CR]=\f[R] or nothing
-error); write \f[CR]=\f[R] (or nothing) between a flag and its argument.
+between a flag and its argument.
 For the special characters mentioned above, use one less level of
-quoting than you would at the command prompt.
+quoting than you would at the command prompt.)
+.PP
+Argument files are now superseded by..
+.SS Config files
+hledger looks for a \f[CR]hledger.conf\f[R] file (or
+\f[CR].hledger.conf\f[R] in your home directory) in the current
+directory, then parent directories, then your XDG config directory
+(\f[CR]\[ti]/.config/hledger/\f[R]).
+Any command line options (or arguments) in this file will be added to
+your \f[CR]hledger\f[R] commands, near the start of the command line (so
+you can override them when needed).
+.PP
+Or you can specify a config file with the \f[CR]\-\-conf\f[R] option.
+Or you can add a \f[CR]hledger \-\-conf\f[R] shebang line to a config
+file and make it executable.
+.PP
+A hledger config file contains command line options, to be used with all
+commands that support them, and optionally command\-specific options in
+named sections.
+hledger.conf.sample is a sample demonstrating the syntax; you can
+install it as \f[CR]./hledger.conf\f[R] or
+\f[CR]$HOME/.hledger.conf\f[R] and customise it.
+.PP
+You can disable config files entirely by running with the
+\f[CR]\-n/\-\-no\-conf\f[R] flag.
+This will ensure hledger runs with standard defaults, useful when
+troubleshooting or when sharing examples with others.
+.PP
+\f[I](Added in 1.40; experimental)\f[R]
 .SH Output
 .SS Output destination
 hledger commands send their output to the terminal by default.
@@ -968,14 +1009,12 @@ colour will not be used;
 otherwise, colour will be used if the output (terminal or file) supports
 it.
 .SS Box\-drawing
-In terminal output, you can enable unicode box\-drawing characters to
+In terminal (text) output, to minimise the risk of display problems,
-render prettier tables:
+table borders are drawn using only ascii characters by default.
-.IP \[bu] 2
+.PP
-if the \f[CR]\-\-pretty\f[R] option is given a value of \f[CR]yes\f[R]
+To see tables with prettier unicode box\-drawing characters, add the
-or \f[CR]always\f[R] (or \f[CR]no\f[R] or \f[CR]never\f[R]), unicode
+\f[CR]\-\-pretty\f[R] flag.
-characters will (or will not) be used;
+This will also show outer borders and inter\-column borders.
-.IP \[bu] 2
-otherwise, unicode characters will not be used.
 .SS Paging
 When showing long output in the terminal, hledger will try to use the
 pager specified by the \f[CR]PAGER\f[R] environment variable, or
@@ -3659,8 +3698,8 @@ file, with an extra \f[CR].rules\f[R] extension added, in the same
 directory.
 Eg when asked to read \f[CR]foo/FILE.csv\f[R], hledger looks for
 \f[CR]foo/FILE.csv.rules\f[R].
-You can specify a different rules file with the
+You can specify a different rules file with the \f[CR]\-\-rules\f[R]
-\f[CR]\-\-rules\-file\f[R] option.
+option.
 .PP
 At minimum, the rules file must identify the date and amount fields, and
 often it also specifies the date format and how many header lines there
@@ -4548,8 +4587,8 @@ $ cat foo.dat | hledger \-f ssv:\- print
 If you use multiple \f[CR]\-f\f[R] options to read multiple CSV files at
 once, hledger will look for a correspondingly\-named rules file for each
 CSV file.
-But if you use the \f[CR]\-\-rules\-file\f[R] option, that rules file
+But if you specify a rules file with \f[CR]\-\-rules\f[R], that rules
-will be used for all the CSV files.
+file will be used for all the CSV files.
 .SS Reading files specified by rule
 Instead of specifying a CSV file in the command line, you can specify a
 rules file, as in \f[CR]hledger \-f foo.csv.rules CMD\f[R].
@@ -7811,10 +7850,10 @@ heading.
 .IP
 .EX
 Flags:
-  \-i            show the manual with info
+  \-i                show the manual with info
-  \-m            show the manual with man
+  \-m                show the manual with man
-  \-p            show the manual with $PAGER or less
+  \-p                show the manual with $PAGER or less
-                (less is always used if TOPIC is specified)
+                    (less is always used if TOPIC is specified)
 .EE
 .PP
 This command shows the hledger manual built in to your hledger
@@ -10410,11 +10449,11 @@ $ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-O csv \-\-la
 \[dq]Assets:US:ETrade\[dq],\[dq]USD\[dq],\[dq]5120.50\[dq]
 \[dq]Assets:US:ETrade\[dq],\[dq]VEA\[dq],\[dq]36.00\[dq]
 \[dq]Assets:US:ETrade\[dq],\[dq]VHT\[dq],\[dq]294.00\[dq]
-\[dq]total\[dq],\[dq]GLD\[dq],\[dq]70.00\[dq]
+\[dq]Total:\[dq],\[dq]GLD\[dq],\[dq]70.00\[dq]
-\[dq]total\[dq],\[dq]ITOT\[dq],\[dq]17.00\[dq]
+\[dq]Total:\[dq],\[dq]ITOT\[dq],\[dq]17.00\[dq]
-\[dq]total\[dq],\[dq]USD\[dq],\[dq]5120.50\[dq]
+\[dq]Total:\[dq],\[dq]USD\[dq],\[dq]5120.50\[dq]
-\[dq]total\[dq],\[dq]VEA\[dq],\[dq]36.00\[dq]
+\[dq]Total:\[dq],\[dq]VEA\[dq],\[dq]36.00\[dq]
-\[dq]total\[dq],\[dq]VHT\[dq],\[dq]294.00\[dq]
+\[dq]Total:\[dq],\[dq]VHT\[dq],\[dq]294.00\[dq]
 .EE
 .PP
 Bare layout will sometimes display an extra row for the no\-symbol

hledger/hledger.txt

@@ -26,9 +26,11 @@ DESCRIPTION
        use  hledger productively, but when you have a question about function-
        ality, this doc should answer it.  It is detailed, so do skip ahead  or
        skim when needed.  You can read it on hledger.org, or as an info manual
-       or  man  page  on your system.  You can also get it from hledger itself
+       or  man  page  on your system.  You can also open a built-in copy, at a
-       with
+       point of interest, by running
-       hledger --man, hledger --info or hledger help [TOPIC].
+       hledger --man [CMD], hledger --info [CMD] or hledger help [TOPIC].
+
+       (And for shorter help, try hledger --tldr [CMD].)
 
        The main function of the hledger CLI is to read plain  text  files  de-
        scribing financial transactions, crunch the numbers, and print a useful
@@ -241,17 +243,26 @@ Commands
        hledger-ui --watch or hledger-web --serve.
 
 Options
-       Run hledger -h to see general command line help.  The following general
+       Run  hledger -h to see general command line help.  Options can be writ-
-       options  are  common  to most hledger commands.  General options can be
+       ten either before or after the command name.  These  options  are  spe-
-       written either before or after the command name.
+       cific to the hledger CLI:
+
+              Flags:
+                   --conf=CONFFILE        Use extra options defined in this config file. If
+                                          not specified, searches upward and in XDG config
+                                          dir for hledger.conf (or .hledger.conf in $HOME).
+                -n --no-conf              ignore any config file
+
+       And the following general options are common to most hledger commands:
 
               General input/data transformation flags:
-                -f --file=FILE            Read data from FILE, or from stdin if -. Can be
+                -f --file=[FMT:]FILE      Read data from FILE, or from stdin if FILE is -,
-                                          specified more than once. If not specified, reads
+                                          inferring format from extension or a FMT: prefix.
-                                          from $LEDGER_FILE or $HOME/.hledger.journal.
+                                          Can be specified more than once. If not specified,
-                   --rules-file=RULEFILE  Use conversion rules from this file for
+                                          reads from $LEDGER_FILE or $HOME/.hledger.journal.
+                   --rules=RULESFILE      Use rules defined in this rules file for
                                           converting subsequent CSV/SSV/TSV files. If not
-                                          specified, uses FILE.rules for each such FILE.
+                                          specified, uses FILE.csv.rules for each FILE.csv.
                    --alias=A=B|/RGX/=RPL  transform account names from A to B, or by
                                           replacing regular expression matches
                    --auto                 generate extra postings by applying auto posting
@@ -314,7 +325,6 @@ Options
                    --pretty[=YN]          Use box-drawing characters in text output? Can be
                                           'y'/'yes' or 'n'/'no'.
                                           If YN is specified, the equals is required.
-                   --debug=[1-9]          show this level of debug output (default: 1)
 
               General help flags:
                 -h --help                 show command line help
@@ -322,15 +332,16 @@ Options
                    --info                 show the manual with info
                    --man                  show the manual with man
                    --version              show version information
+                   --debug=[1-9]          show this level of debug output (default: 1)
 
-       Usually hledger accepts any unambiguous flag prefix, eg you  can  write
+       Usually  hledger  accepts any unambiguous flag prefix, eg you can write
        --tl instead of --tldr or --dry instead of --dry-run.
 
-       If  the  same  option  appears more than once in a command, usually the
+       If the same option appears more than once in  a  command,  usually  the
        last (right-most) wins.
 
-       With most commands, arguments are interpreted as a hledger query  which
+       With  most commands, arguments are interpreted as a hledger query which
-       filter  the data.  Some queries can be expressed either with options or
+       filter the data.  Some queries can be expressed either with options  or
        with arguments.
 
        Below are more tips for using the command line interface - feel free to
@@ -338,10 +349,10 @@ Options
 
    Special characters
    Single escaping (shell metacharacters)
-       In shell command lines, characters significant to your shell - such  as
+       In  shell command lines, characters significant to your shell - such as
-       spaces,  <, >, (, ), |, $ and \ - should be "shell-escaped" if you want
+       spaces, <, >, (, ), |, $ and \ - should be "shell-escaped" if you  want
-       hledger to see them.  This is done by enclosing them in single or  dou-
+       hledger  to see them.  This is done by enclosing them in single or dou-
-       ble  quotes, or by writing a backslash before them.  Eg to match an ac-
+       ble quotes, or by writing a backslash before them.  Eg to match an  ac-
        count name containing a space:
 
               $ hledger register 'credit card'
@@ -350,17 +361,17 @@ Options
 
               $ hledger register credit\ card
 
-       Windows users should keep in mind that cmd treats  single  quote  as  a
+       Windows  users  should  keep  in mind that cmd treats single quote as a
-       regular  character,  so  you should be using double quotes exclusively.
+       regular character, so you should be using  double  quotes  exclusively.
        PowerShell treats both single and double quotes as quotes.
 
    Double escaping (regular expression metacharacters)
-       Characters significant in regular expressions (described below) -  such
+       Characters  significant in regular expressions (described below) - such
-       as  .,  ^,  $, [, ], (, ), |, and \ - may need to be "regex-escaped" if
+       as ., ^, $, [, ], (, ), |, and \ - may need to  be  "regex-escaped"  if
-       you don't want them to be interpreted by hledger's  regular  expression
+       you  don't  want them to be interpreted by hledger's regular expression
-       engine.   This  is  done  by writing backslashes before them, but since
+       engine.  This is done by writing backslashes  before  them,  but  since
-       backslash is typically also a shell metacharacter, both  shell-escaping
+       backslash  is typically also a shell metacharacter, both shell-escaping
-       and  regex-escaping will be needed.  Eg to match a literal $ sign while
+       and regex-escaping will be needed.  Eg to match a literal $ sign  while
        using the bash shell:
 
               $ hledger balance cur:'\$'
@@ -370,10 +381,10 @@ Options
               $ hledger balance cur:\\$
 
    Triple escaping (for add-on commands)
-       When you use hledger to run an external add-on command  (described  be-
+       When  you  use hledger to run an external add-on command (described be-
        low), one level of shell-escaping is lost from any options or arguments
-       intended  for  by  the  add-on command, so those need an extra level of
+       intended for by the add-on command, so those need  an  extra  level  of
-       shell-escaping.  Eg to match a literal $  sign  while  using  the  bash
+       shell-escaping.   Eg  to  match  a  literal $ sign while using the bash
        shell and running an add-on command (ui):
 
               $ hledger ui cur:'\\$'
@@ -389,14 +400,14 @@ Options
        double-escaped:   \\$
        triple-escaped:   \\\\$
 
-       Or,  you  can avoid the extra escaping by running the add-on executable
+       Or, you can avoid the extra escaping by running the  add-on  executable
        directly:
 
               $ hledger-ui cur:\\$
 
    Less escaping
        Options and arguments are sometimes used in places other than the shell
-       command line, where shell-escaping is not needed, so there  you  should
+       command  line,  where shell-escaping is not needed, so there you should
        use one less level of escaping.  Those places include:
 
        o an @argumentfile
@@ -410,8 +421,8 @@ Options
    Unicode characters
        hledger is expected to handle non-ascii characters correctly:
 
-       o they  should  be  parsed  correctly in input files and on the command
+       o they should be parsed correctly in input files  and  on  the  command
-         line, by all hledger tools (add, iadd, hledger-web's  search/add/edit
+         line,  by all hledger tools (add, iadd, hledger-web's search/add/edit
          forms, etc.)
 
        o they  should  be  displayed  correctly  by  all  hledger  tools,  and
@@ -419,40 +430,40 @@ Options
 
        This requires a well-configured environment.  Here are some tips:
 
-       o A system locale must be configured, and it must be one that  can  de-
+       o A  system  locale must be configured, and it must be one that can de-
-         code  the  characters being used.  In bash, you can set a locale like
+         code the characters being used.  In bash, you can set a  locale  like
-         this: export LANG=en_US.UTF-8.  There are some more details in  Trou-
+         this:  export LANG=en_US.UTF-8.  There are some more details in Trou-
-         bleshooting.   This step is essential - without it, hledger will quit
+         bleshooting.  This step is essential - without it, hledger will  quit
-         on encountering a non-ascii character (as with all GHC-compiled  pro-
+         on  encountering a non-ascii character (as with all GHC-compiled pro-
          grams).
 
-       o Your  terminal  software  (eg  Terminal.app, iTerm, CMD.exe, xterm..)
+       o Your terminal software (eg  Terminal.app,  iTerm,  CMD.exe,  xterm..)
          must support unicode.  On Windows, you may need to use Windows Termi-
          nal and/or enable UTF-8 support.
 
        o The terminal must be using a font which includes the required unicode
          glyphs.
 
-       o The terminal should be configured to display wide characters as  dou-
+       o The  terminal should be configured to display wide characters as dou-
          ble width (for report alignment).
 
-       o On  Windows, for best results you should run hledger in the same kind
+       o On Windows, for best results you should run hledger in the same  kind
-         of environment in which it was built.  Eg hledger built in the  stan-
+         of  environment in which it was built.  Eg hledger built in the stan-
-         dard  CMD.EXE  environment  (like  the binaries on our download page)
+         dard CMD.EXE environment (like the binaries  on  our  download  page)
-         might show display problems when run in a cygwin  or  msys  terminal,
+         might  show  display  problems when run in a cygwin or msys terminal,
          and vice versa.  (See eg #961).
 
    Regular expressions
-       A  regular  expression  (regexp) is a small piece of text where certain
+       A regular expression (regexp) is a small piece of  text  where  certain
-       characters (like ., ^, $, +, *, (), |, [], \)  have  special  meanings,
+       characters  (like  .,  ^, $, +, *, (), |, [], \) have special meanings,
-       forming  a  tiny  language for matching text precisely - very useful in
+       forming a tiny language for matching text precisely -  very  useful  in
-       hledger and elsewhere.  To learn all about them, visit  regular-expres-
+       hledger  and elsewhere.  To learn all about them, visit regular-expres-
        sions.info.
 
-       hledger  supports  regexps whenever you are entering a pattern to match
+       hledger supports regexps whenever you are entering a pattern  to  match
-       something, eg in  query  arguments,  account  aliases,  CSV  if  rules,
+       something,  eg  in  query  arguments,  account  aliases,  CSV if rules,
        hledger-web's search form, hledger-ui's / search, etc.  You may need to
-       wrap  them in quotes, especially at the command line (see Special char-
+       wrap them in quotes, especially at the command line (see Special  char-
        acters above).  Here are some examples:
 
        Account name queries (quoted for command line use):
@@ -508,51 +519,77 @@ Options
               &  %date   (29|30|31|01|02|03)$
 
    hledger's regular expressions
-       hledger's regular expressions come from  the  regex-tdfa  library.   If
+       hledger's  regular  expressions  come  from the regex-tdfa library.  If
-       they're  not doing what you expect, it's important to know exactly what
+       they're not doing what you expect, it's important to know exactly  what
        they support:
 
        1. they are case insensitive
 
-       2. they are infix matching (they do not need to match the entire  thing
+       2. they  are infix matching (they do not need to match the entire thing
           being matched)
 
        3. they are POSIX ERE (extended regular expressions)
 
        4. they also support GNU word boundaries (\b, \B, \<, \>)
 
-       5. backreferences  are supported when doing text replacement in account
+       5. backreferences are supported when doing text replacement in  account
-          aliases or CSV rules, where backreferences can be used  in  the  re-
+          aliases  or  CSV  rules, where backreferences can be used in the re-
           placement string to reference capturing groups in the search regexp.
           Otherwise, if you write \1, it will match the digit 1.
 
-       6. they  do  not  support mode modifiers ((?s)), character classes (\w,
+       6. they do not support mode modifiers ((?s)),  character  classes  (\w,
           \d), or anything else not mentioned above.
 
        Some things to note:
 
-       o In the alias directive and --alias option, regular  expressions  must
+       o In  the  alias directive and --alias option, regular expressions must
-         be  enclosed  in  forward  slashes  (/REGEX/).  Elsewhere in hledger,
+         be enclosed in forward  slashes  (/REGEX/).   Elsewhere  in  hledger,
          these are not required.
 
-       o In queries, to match a regular expression metacharacter like $  as  a
+       o In  queries,  to match a regular expression metacharacter like $ as a
-         literal  character,  prepend  a  backslash.  Eg to search for amounts
+         literal character, prepend a backslash.  Eg  to  search  for  amounts
          with the dollar sign in hledger-web, write cur:\$.
 
-       o On the command line, some metacharacters like $ have a special  mean-
+       o On  the command line, some metacharacters like $ have a special mean-
          ing to the shell and so must be escaped at least once more.  See Spe-
          cial characters.
 
    Argument files
        You can save a set of command line options and arguments in a file, and
-       then  reuse  them by writing @FILENAME as a command line argument.  Eg:
+       then reuse them by writing @FILENAME as a command line  argument.   Eg:
        hledger bal @foo.args.
 
-       Inside the argument file, each line should contain just one  option  or
+       (Inside  the argument file, each line should contain just one option or
-       argument.   Don't use spaces except inside quotes (or you'll see a con-
+       argument.  Don't use spaces except inside quotes; write  =  or  nothing
-       fusing error); write = (or nothing) between a flag  and  its  argument.
+       between  a flag and its argument.  For the special characters mentioned
-       For the special characters mentioned above, use one less level of quot-
+       above, use one less level of quoting than  you  would  at  the  command
-       ing than you would at the command prompt.
+       prompt.)
+
+       Argument files are now superseded by..
+
+   Config files
+       hledger  looks  for  a hledger.conf file (or .hledger.conf in your home
+       directory) in the current directory, then parent directories, then your
+       XDG config directory (~/.config/hledger/).  Any  command  line  options
+       (or  arguments)  in  this  file will be added to your hledger commands,
+       near the start of the command line  (so  you  can  override  them  when
+       needed).
+
+       Or  you  can  specify a config file with the --conf option.  Or you can
+       add a hledger --conf shebang line to a config file  and  make  it  exe-
+       cutable.
+
+       A  hledger  config  file contains command line options, to be used with
+       all commands that support them, and optionally command-specific options
+       in named sections.  hledger.conf.sample is a sample  demonstrating  the
+       syntax; you can install it as ./hledger.conf or $HOME/.hledger.conf and
+       customise it.
+
+       You  can disable config files entirely by running with the -n/--no-conf
+       flag.  This will ensure hledger runs  with  standard  defaults,  useful
+       when troubleshooting or when sharing examples with others.
+
+       (Added in 1.40; experimental)
 
 Output
    Output destination
@@ -681,13 +718,12 @@ Output
          ports it.
 
    Box-drawing
-       In terminal output, you can enable unicode  box-drawing  characters  to
+       In terminal (text) output, to minimise the risk  of  display  problems,
-       render prettier tables:
+       table borders are drawn using only ascii characters by default.
 
-       o if  the  --pretty  option is given a value of yes or always (or no or
+       To  see  tables  with  prettier unicode box-drawing characters, add the
-         never), unicode characters will (or will not) be used;
+       --pretty flag.  This will also show outer borders and inter-column bor-
-
+       ders.
-       o otherwise, unicode characters will not be used.
 
    Paging
        When showing long output in the terminal, hledger will try to  use  the
@@ -2879,7 +2915,7 @@ CSV
        By  default,  hledger  expects this rules file to be named like the CSV
        file, with an extra .rules extension added, in the same directory.   Eg
        when  asked to read foo/FILE.csv, hledger looks for foo/FILE.csv.rules.
-       You can specify a different rules file with the --rules-file option.
+       You can specify a different rules file with the --rules option.
 
        At minimum, the rules file must identify the date  and  amount  fields,
        and  often  it also specifies the date format and how many header lines
@@ -3573,8 +3609,8 @@ CSV
    Reading multiple CSV files
        If  you  use  multiple  -f  options to read multiple CSV files at once,
        hledger will look for a correspondingly-named rules file for  each  CSV
-       file.   But if you use the --rules-file option, that rules file will be
+       file.   But  if  you specify a rules file with --rules, that rules file
-       used for all the CSV files.
+       will be used for all the CSV files.
 
    Reading files specified by rule
        Instead of specifying a CSV file in the command line, you can specify a
@@ -6039,10 +6075,10 @@ Help commands
        insensitive) TOPIC argument, try to open it at that section heading.
 
               Flags:
-                -i            show the manual with info
+                -i                show the manual with info
-                -m            show the manual with man
+                -m                show the manual with man
-                -p            show the manual with $PAGER or less
+                -p                show the manual with $PAGER or less
-                              (less is always used if TOPIC is specified)
+                                  (less is always used if TOPIC is specified)
 
        This command shows the hledger manual built in  to  your  hledger  exe-
        cutable.   It can be useful when offline, or when you prefer the termi-
@@ -8279,11 +8315,11 @@ Advanced report commands
               "Assets:US:ETrade","USD","5120.50"
               "Assets:US:ETrade","VEA","36.00"
               "Assets:US:ETrade","VHT","294.00"
-              "total","GLD","70.00"
+              "Total:","GLD","70.00"
-              "total","ITOT","17.00"
+              "Total:","ITOT","17.00"
-              "total","USD","5120.50"
+              "Total:","USD","5120.50"
-              "total","VEA","36.00"
+              "Total:","VEA","36.00"
-              "total","VHT","294.00"
+              "Total:","VHT","294.00"
 
        Bare  layout will sometimes display an extra row for the no-symbol com-
        modity, because of zero  amounts  (hledger  treats  zeroes  as  commod-