;doc: update manuals

hledger-ui/hledger-ui.1

@@ -521,19 +521,29 @@ Default: the full terminal width.
 .PP
 \f[B]LEDGER_FILE\f[R] The journal file path when not specified with
 \f[C]-f\f[R].
-Default: \f[C]\[ti]/.hledger.journal\f[R] (on windows, perhaps
-\f[C]C:/Users/USER/.hledger.journal\f[R]).
 .PP
-A typical value is \f[C]\[ti]/DIR/YYYY.journal\f[R], where DIR is a
+On unix computers, the default value is:
+\f[C]\[ti]/.hledger.journal\f[R].
+.PP
+A more typical value is something like
+\f[C]\[ti]/finance/YYYY.journal\f[R], where \f[C]\[ti]/finance\f[R] is a
 version-controlled finance directory and YYYY is the current year.
-Or \f[C]\[ti]/DIR/current.journal\f[R], where current.journal is a
+Or, \f[C]\[ti]/finance/current.journal\f[R], where current.journal is a
 symbolic link to YYYY.journal.
 .PP
-On Mac computers, you can set this and other environment variables in a
+The usual way to set this permanently is to add a command to one of your
-more thorough way that also affects applications started from the GUI
+shell\[aq]s startup files (eg \f[C]\[ti]/.profile\f[R]):
-(say, an Emacs dock icon).
+.IP
-Eg on MacOS Catalina I have a \f[C]\[ti]/.MacOSX/environment.plist\f[R]
+.nf
-file containing
+\f[C]
+export LEDGER_FILE=\[ti]/finance/current.journal\[ga]
+\f[R]
+.fi
+.PP
+On some Mac computers, there is a more thorough way to set environment
+variables, that will also affect applications started from the GUI (eg,
+Emacs started from a dock icon): In
+\f[C]\[ti]/.MacOSX/environment.plist\f[R], add an entry like:
 .IP
 .nf
 \f[C]
@@ -543,7 +553,22 @@ file containing
 \f[R]
 .fi
 .PP
-To see the effect you may need to \f[C]killall Dock\f[R], or reboot.
+For this to take effect you might need to \f[C]killall Dock\f[R], or
+reboot.
+.PP
+On Windows computers, the default value is probably
+\f[C]C:\[rs]Users\[rs]MyUserName\[rs].hledger.journal\f[R].
+You can change this by running a command like this in a powershell
+window:
+.IP
+.nf
+\f[C]
+> setx LEDGER_FILE \[dq]C:\[rs]Users\[rs]MyUserName\[rs]finance\[rs]2021.journal\[dq]
+\f[R]
+.fi
+.PP
+(Let us know if you need to be an Administrator, and if this persists
+across a reboot.)
 .SH FILES
 .PP
 Reads data from one or more files in hledger journal, timeclock,

hledger-ui/hledger-ui.info

@@ -564,24 +564,38 @@ File: hledger-ui.info,  Node: ENVIRONMENT,  Next: FILES,  Prev: TIPS,  Up: Top
 *COLUMNS* The screen width to use.  Default: the full terminal width.
 
    *LEDGER_FILE* The journal file path when not specified with '-f'.
-Default: '~/.hledger.journal' (on windows, perhaps
-'C:/Users/USER/.hledger.journal').
 
-   A typical value is '~/DIR/YYYY.journal', where DIR is a
+   On unix computers, the default value is: '~/.hledger.journal'.
-version-controlled finance directory and YYYY is the current year.  Or
-'~/DIR/current.journal', where current.journal is a symbolic link to
-YYYY.journal.
 
-   On Mac computers, you can set this and other environment variables in
+   A more typical value is something like '~/finance/YYYY.journal',
-a more thorough way that also affects applications started from the GUI
+where '~/finance' is a version-controlled finance directory and YYYY is
-(say, an Emacs dock icon).  Eg on MacOS Catalina I have a
+the current year.  Or, '~/finance/current.journal', where
-'~/.MacOSX/environment.plist' file containing
+current.journal is a symbolic link to YYYY.journal.
+
+   The usual way to set this permanently is to add a command to one of
+your shell's startup files (eg '~/.profile'):
+
+export LEDGER_FILE=~/finance/current.journal`
+
+   On some Mac computers, there is a more thorough way to set
+environment variables, that will also affect applications started from
+the GUI (eg, Emacs started from a dock icon): In
+'~/.MacOSX/environment.plist', add an entry like:
 
 {
   "LEDGER_FILE" : "~/finance/current.journal"
 }
 
-   To see the effect you may need to 'killall Dock', or reboot.
+   For this to take effect you might need to 'killall Dock', or reboot.
+
+   On Windows computers, the default value is probably
+'C:\Users\MyUserName\.hledger.journal'.  You can change this by running
+a command like this in a powershell window:
+
+> setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal"
+
+   (Let us know if you need to be an Administrator, and if this persists
+across a reboot.)
 
 
 File: hledger-ui.info,  Node: FILES,  Next: BUGS,  Prev: ENVIRONMENT,  Up: Top
@@ -649,10 +663,10 @@ Node: Watch mode limitations18399
 Ref: #watch-mode-limitations18540
 Node: ENVIRONMENT19676
 Ref: #environment19787
-Node: FILES20594
+Node: FILES21095
-Ref: #files20693
+Ref: #files21194
-Node: BUGS20906
+Node: BUGS21407
-Ref: #bugs20983
+Ref: #bugs21484
 
 End Tag Table
 

hledger-ui/hledger-ui.txt

@@ -464,24 +464,39 @@ TIPS
 ENVIRONMENT
        COLUMNS The screen width to use.  Default: the full terminal width.
 
-       LEDGER_FILE The journal file path when not specified with -f.  Default:
+       LEDGER_FILE The journal file path when not specified with -f.
-       ~/.hledger.journal (on  windows,  perhaps  C:/Users/USER/.hledger.jour-
-       nal).
 
-       A  typical  value  is  ~/DIR/YYYY.journal,  where DIR is a version-con-
+       On unix computers, the default value is: ~/.hledger.journal.
-       trolled finance directory and YYYY is the current year.  Or  ~/DIR/cur-
-       rent.journal, where current.journal is a symbolic link to YYYY.journal.
 
-       On Mac computers, you can set this and other environment variables in a
+       A  more  typical  value is something like ~/finance/YYYY.journal, where
-       more  thorough  way that also affects applications started from the GUI
+       ~/finance is a version-controlled finance directory  and  YYYY  is  the
-       (say,  an  Emacs  dock  icon).   Eg  on  MacOS  Catalina   I   have   a
+       current  year.  Or, ~/finance/current.journal, where current.journal is
-       ~/.MacOSX/environment.plist file containing
+       a symbolic link to YYYY.journal.
+
+       The usual way to set this permanently is to add a  command  to  one  of
+       your shell's startup files (eg ~/.profile):
+
+              export LEDGER_FILE=~/finance/current.journal`
+
+       On  some Mac computers, there is a more thorough way to set environment
+       variables, that will also affect applications started from the GUI (eg,
+       Emacs started from a dock icon): In ~/.MacOSX/environment.plist, add an
+       entry like:
 
               {
                 "LEDGER_FILE" : "~/finance/current.journal"
               }
 
-       To see the effect you may need to killall Dock, or reboot.
+       For this to take effect you might need to killall Dock, or reboot.
+
+       On Windows computers, the default value  is  probably  C:\Users\MyUser-
+       Name\.hledger.journal.   You  can change this by running a command like
+       this in a powershell window:
+
+              > setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal"
+
+       (Let us know if you need to be an Administrator, and if  this  persists
+       across a reboot.)
 
 FILES
        Reads  data from one or more files in hledger journal, timeclock, time-

hledger-web/hledger-web.1

@@ -579,19 +579,29 @@ $ curl http://127.0.0.1:5000/add -X PUT -H \[aq]Content-Type: application/json\[
 .PP
 \f[B]LEDGER_FILE\f[R] The journal file path when not specified with
 \f[C]-f\f[R].
-Default: \f[C]\[ti]/.hledger.journal\f[R] (on windows, perhaps
-\f[C]C:/Users/USER/.hledger.journal\f[R]).
 .PP
-A typical value is \f[C]\[ti]/DIR/YYYY.journal\f[R], where DIR is a
+On unix computers, the default value is:
+\f[C]\[ti]/.hledger.journal\f[R].
+.PP
+A more typical value is something like
+\f[C]\[ti]/finance/YYYY.journal\f[R], where \f[C]\[ti]/finance\f[R] is a
 version-controlled finance directory and YYYY is the current year.
-Or \f[C]\[ti]/DIR/current.journal\f[R], where current.journal is a
+Or, \f[C]\[ti]/finance/current.journal\f[R], where current.journal is a
 symbolic link to YYYY.journal.
 .PP
-On Mac computers, you can set this and other environment variables in a
+The usual way to set this permanently is to add a command to one of your
-more thorough way that also affects applications started from the GUI
+shell\[aq]s startup files (eg \f[C]\[ti]/.profile\f[R]):
-(say, an Emacs dock icon).
+.IP
-Eg on MacOS Catalina I have a \f[C]\[ti]/.MacOSX/environment.plist\f[R]
+.nf
-file containing
+\f[C]
+export LEDGER_FILE=\[ti]/finance/current.journal\[ga]
+\f[R]
+.fi
+.PP
+On some Mac computers, there is a more thorough way to set environment
+variables, that will also affect applications started from the GUI (eg,
+Emacs started from a dock icon): In
+\f[C]\[ti]/.MacOSX/environment.plist\f[R], add an entry like:
 .IP
 .nf
 \f[C]
@@ -601,7 +611,22 @@ file containing
 \f[R]
 .fi
 .PP
-To see the effect you may need to \f[C]killall Dock\f[R], or reboot.
+For this to take effect you might need to \f[C]killall Dock\f[R], or
+reboot.
+.PP
+On Windows computers, the default value is probably
+\f[C]C:\[rs]Users\[rs]MyUserName\[rs].hledger.journal\f[R].
+You can change this by running a command like this in a powershell
+window:
+.IP
+.nf
+\f[C]
+> setx LEDGER_FILE \[dq]C:\[rs]Users\[rs]MyUserName\[rs]finance\[rs]2021.journal\[dq]
+\f[R]
+.fi
+.PP
+(Let us know if you need to be an Administrator, and if this persists
+across a reboot.)
 .SH FILES
 .PP
 Reads data from one or more files in hledger journal, timeclock,

hledger-web/hledger-web.info

@@ -567,24 +567,38 @@ File: hledger-web.info,  Node: ENVIRONMENT,  Next: FILES,  Prev: JSON API,  Up:
 *************
 
 *LEDGER_FILE* The journal file path when not specified with '-f'.
-Default: '~/.hledger.journal' (on windows, perhaps
-'C:/Users/USER/.hledger.journal').
 
-   A typical value is '~/DIR/YYYY.journal', where DIR is a
+   On unix computers, the default value is: '~/.hledger.journal'.
-version-controlled finance directory and YYYY is the current year.  Or
-'~/DIR/current.journal', where current.journal is a symbolic link to
-YYYY.journal.
 
-   On Mac computers, you can set this and other environment variables in
+   A more typical value is something like '~/finance/YYYY.journal',
-a more thorough way that also affects applications started from the GUI
+where '~/finance' is a version-controlled finance directory and YYYY is
-(say, an Emacs dock icon).  Eg on MacOS Catalina I have a
+the current year.  Or, '~/finance/current.journal', where
-'~/.MacOSX/environment.plist' file containing
+current.journal is a symbolic link to YYYY.journal.
+
+   The usual way to set this permanently is to add a command to one of
+your shell's startup files (eg '~/.profile'):
+
+export LEDGER_FILE=~/finance/current.journal`
+
+   On some Mac computers, there is a more thorough way to set
+environment variables, that will also affect applications started from
+the GUI (eg, Emacs started from a dock icon): In
+'~/.MacOSX/environment.plist', add an entry like:
 
 {
   "LEDGER_FILE" : "~/finance/current.journal"
 }
 
-   To see the effect you may need to 'killall Dock', or reboot.
+   For this to take effect you might need to 'killall Dock', or reboot.
+
+   On Windows computers, the default value is probably
+'C:\Users\MyUserName\.hledger.journal'.  You can change this by running
+a command like this in a powershell window:
+
+> setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal"
+
+   (Let us know if you need to be an Administrator, and if this persists
+across a reboot.)
 
 
 File: hledger-web.info,  Node: FILES,  Next: BUGS,  Prev: ENVIRONMENT,  Up: Top
@@ -629,10 +643,10 @@ Node: JSON API12838
 Ref: #json-api12952
 Node: ENVIRONMENT18442
 Ref: #environment18558
-Node: FILES19291
+Node: FILES19792
-Ref: #files19391
+Ref: #files19892
-Node: BUGS19604
+Node: BUGS20105
-Ref: #bugs19682
+Ref: #bugs20183
 
 End Tag Table
 

hledger-web/hledger-web.txt

@@ -512,24 +512,39 @@ JSON API
               $ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json
 
 ENVIRONMENT
-       LEDGER_FILE The journal file path when not specified with -f.  Default:
+       LEDGER_FILE The journal file path when not specified with -f.
-       ~/.hledger.journal (on  windows,  perhaps  C:/Users/USER/.hledger.jour-
-       nal).
 
-       A  typical  value  is  ~/DIR/YYYY.journal,  where DIR is a version-con-
+       On unix computers, the default value is: ~/.hledger.journal.
-       trolled finance directory and YYYY is the current year.  Or  ~/DIR/cur-
-       rent.journal, where current.journal is a symbolic link to YYYY.journal.
 
-       On Mac computers, you can set this and other environment variables in a
+       A  more  typical  value is something like ~/finance/YYYY.journal, where
-       more  thorough  way that also affects applications started from the GUI
+       ~/finance is a version-controlled finance directory  and  YYYY  is  the
-       (say,  an  Emacs  dock  icon).   Eg  on  MacOS  Catalina   I   have   a
+       current  year.  Or, ~/finance/current.journal, where current.journal is
-       ~/.MacOSX/environment.plist file containing
+       a symbolic link to YYYY.journal.
+
+       The usual way to set this permanently is to add a  command  to  one  of
+       your shell's startup files (eg ~/.profile):
+
+              export LEDGER_FILE=~/finance/current.journal`
+
+       On  some Mac computers, there is a more thorough way to set environment
+       variables, that will also affect applications started from the GUI (eg,
+       Emacs started from a dock icon): In ~/.MacOSX/environment.plist, add an
+       entry like:
 
               {
                 "LEDGER_FILE" : "~/finance/current.journal"
               }
 
-       To see the effect you may need to killall Dock, or reboot.
+       For this to take effect you might need to killall Dock, or reboot.
+
+       On Windows computers, the default value  is  probably  C:\Users\MyUser-
+       Name\.hledger.journal.   You  can change this by running a command like
+       this in a powershell window:
+
+              > setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal"
+
+       (Let us know if you need to be an Administrator, and if  this  persists
+       across a reboot.)
 
 FILES
        Reads  data from one or more files in hledger journal, timeclock, time-

hledger/hledger.1

@@ -507,19 +507,29 @@ See Special characters.
 .PP
 \f[B]LEDGER_FILE\f[R] The journal file path when not specified with
 \f[C]-f\f[R].
-Default: \f[C]\[ti]/.hledger.journal\f[R] (on windows, perhaps
-\f[C]C:/Users/USER/.hledger.journal\f[R]).
 .PP
-A typical value is \f[C]\[ti]/DIR/YYYY.journal\f[R], where DIR is a
+On unix computers, the default value is:
+\f[C]\[ti]/.hledger.journal\f[R].
+.PP
+A more typical value is something like
+\f[C]\[ti]/finance/YYYY.journal\f[R], where \f[C]\[ti]/finance\f[R] is a
 version-controlled finance directory and YYYY is the current year.
-Or \f[C]\[ti]/DIR/current.journal\f[R], where current.journal is a
+Or, \f[C]\[ti]/finance/current.journal\f[R], where current.journal is a
 symbolic link to YYYY.journal.
 .PP
-On Mac computers, you can set this and other environment variables in a
+The usual way to set this permanently is to add a command to one of your
-more thorough way that also affects applications started from the GUI
+shell\[aq]s startup files (eg \f[C]\[ti]/.profile\f[R]):
-(say, an Emacs dock icon).
+.IP
-Eg on MacOS Catalina I have a \f[C]\[ti]/.MacOSX/environment.plist\f[R]
+.nf
-file containing
+\f[C]
+export LEDGER_FILE=\[ti]/finance/current.journal\[ga]
+\f[R]
+.fi
+.PP
+On some Mac computers, there is a more thorough way to set environment
+variables, that will also affect applications started from the GUI (eg,
+Emacs started from a dock icon): In
+\f[C]\[ti]/.MacOSX/environment.plist\f[R], add an entry like:
 .IP
 .nf
 \f[C]
@@ -529,7 +539,22 @@ file containing
 \f[R]
 .fi
 .PP
-To see the effect you may need to \f[C]killall Dock\f[R], or reboot.
+For this to take effect you might need to \f[C]killall Dock\f[R], or
+reboot.
+.PP
+On Windows computers, the default value is probably
+\f[C]C:\[rs]Users\[rs]MyUserName\[rs].hledger.journal\f[R].
+You can change this by running a command like this in a powershell
+window:
+.IP
+.nf
+\f[C]
+> setx LEDGER_FILE \[dq]C:\[rs]Users\[rs]MyUserName\[rs]finance\[rs]2021.journal\[dq]
+\f[R]
+.fi
+.PP
+(Let us know if you need to be an Administrator, and if this persists
+across a reboot.)
 .PP
 \f[B]COLUMNS\f[R] The screen width used by the register command.
 Default: the full terminal width.
@@ -2520,6 +2545,10 @@ the file extension, if needed:
 $ hledger balancesheet -o foo.txt -O csv    # write CSV to foo.txt
 \f[R]
 .fi
+.SS CSV output
+.IP \[bu] 2
+In CSV output, digit group marks (such as thousands separators) are
+disabled automatically.
 .SS HTML output
 .IP \[bu] 2
 HTML output can be styled by an optional \f[C]hledger.css\f[R] file in
@@ -8706,6 +8735,9 @@ comma).
 Field names may not contain spaces.
 Spaces before/after field names are optional.
 .IP \[bu] 2
+Field names may contain \f[C]_\f[R] (underscore) or \f[C]-\f[R]
+(hyphen).
+.IP \[bu] 2
 If the CSV contains column headings, it\[aq]s a good idea to use these,
 suitably modified, as the basis for your field names (eg lower-cased,
 with underscores instead of spaces).
@@ -8782,10 +8814,13 @@ Assigning to \f[C]date\f[R] sets the transaction date.
 \f[C]commentN\f[R], where N is a number, sets the Nth posting\[aq]s
 comment.
 .PP
-Tips: - You can assign multi-line comments by writing literal
+Tips:
-\f[C]\[rs]n\f[R] in the code.
+.IP \[bu] 2
+You can assign multi-line comments by writing literal \f[C]\[rs]n\f[R]
+in the code.
 A comment starting with \f[C]\[rs]n\f[R] will begin on a new line.
-- Comments can contain tags, as usual.
+.IP \[bu] 2
+Comments can contain tags, as usual.
 .SS account field
 .PP
 Assigning to \f[C]accountN\f[R], where N is 1 to 99, sets the account