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].
@@ -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,6 +332,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)
 
        Usually  hledger  accepts any unambiguous flag prefix, eg you can write
        --tl instead of --tldr or --dry instead of --dry-run.
@@ -548,11 +559,37 @@ Options
        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
@@ -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-