;doc: update manuals

hledger-ui/hledger-ui.1

@@ -134,8 +134,6 @@ General output/reporting flags (supported by some commands):
                             YYYY\-MM\-DD: value on given date
   \-c \-\-commodity\-style=S    Override a commodity\[aq]s display style.
                             Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq]
-     \-\-color=YN \-\-colour    Use ANSI color codes in text output? Can be
-                            \[aq]y\[aq]/\[aq]yes\[aq]/\[aq]always\[aq], \[aq]n\[aq]/\[aq]no\[aq]/\[aq]never\[aq] or \[aq]auto\[aq].
      \-\-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.
@@ -147,6 +145,8 @@ General help flags:
      \-\-man                  show the manual with man
      \-\-version              show version information
      \-\-debug=[1\-9]          show this much debug output (default: 1)
+     \-\-pager=YN             use a pager when needed ? y/yes (default) or n/no
+     \-\-color=YNA \-\-colour   use ANSI color ? y/yes, n/no, or auto (default)
 .EE
 .PP
 With hledger\-ui, the \f[CR]\-\-debug\f[R] option sends debug output to

hledger-ui/hledger-ui.info

@@ -145,8 +145,6 @@ General output/reporting flags (supported by some commands):
                             YYYY-MM-DD: value on given date
   -c --commodity-style=S    Override a commodity's display style.
                             Eg: -c '.' or -c '1.000,00 EUR'
-     --color=YN --colour    Use ANSI color codes in text output? Can be
-                            'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'.
      --pretty[=YN]          Use box-drawing characters in text output? Can be
                             'y'/'yes' or 'n'/'no'.
                             If YN is specified, the equals is required.
@@ -158,6 +156,8 @@ General help flags:
      --man                  show the manual with man
      --version              show version information
      --debug=[1-9]          show this much debug output (default: 1)
+     --pager=YN             use a pager when needed ? y/yes (default) or n/no
+     --color=YNA --colour   use ANSI color ? y/yes, n/no, or auto (default)
 
    With hledger-ui, the '--debug' option sends debug output to a
 'hledger-ui.log' file in the current directory.
@@ -540,20 +540,20 @@ above).
 Tag Table:
 Node: Top223
 Node: OPTIONS1874
-Node: MOUSE8391
+Node: MOUSE8397
-Node: KEYS8723
+Node: KEYS8729
-Node: SCREENS13551
+Node: SCREENS13557
-Node: Menu screen14291
+Node: Menu screen14297
-Node: Cash accounts screen14607
+Node: Cash accounts screen14613
-Node: Balance sheet accounts screen14968
+Node: Balance sheet accounts screen14974
-Node: Income statement accounts screen15304
+Node: Income statement accounts screen15310
-Node: All accounts screen15689
+Node: All accounts screen15695
-Node: Register screen16052
+Node: Register screen16058
-Node: Transaction screen18495
+Node: Transaction screen18501
-Node: Error screen20070
+Node: Error screen20076
-Node: WATCH MODE20436
+Node: WATCH MODE20442
-Node: ENVIRONMENT22012
+Node: ENVIRONMENT22018
-Node: BUGS22319
+Node: BUGS22325
 
 End Tag Table
 

hledger-ui/hledger-ui.txt

@@ -123,8 +123,6 @@ OPTIONS
                                           YYYY-MM-DD: value on given date
                 -c --commodity-style=S    Override a commodity's display style.
                                           Eg: -c '.' or -c '1.000,00 EUR'
-                   --color=YN --colour    Use ANSI color codes in text output? Can be
-                                          'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'.
                    --pretty[=YN]          Use box-drawing characters in text output? Can be
                                           'y'/'yes' or 'n'/'no'.
                                           If YN is specified, the equals is required.
@@ -136,6 +134,8 @@ OPTIONS
                    --man                  show the manual with man
                    --version              show version information
                    --debug=[1-9]          show this much debug output (default: 1)
+                   --pager=YN             use a pager when needed ? y/yes (default) or n/no
+                   --color=YNA --colour   use ANSI color ? y/yes, n/no, or auto (default)
 
        With  hledger-ui,  the  --debug  option  sends  debug   output   to   a
        hledger-ui.log file in the current directory.

hledger-web/hledger-web.1

@@ -185,8 +185,6 @@ General output/reporting flags (supported by some commands):
                             YYYY\-MM\-DD: value on given date
   \-c \-\-commodity\-style=S    Override a commodity\[aq]s display style.
                             Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq]
-     \-\-color=YN \-\-colour    Use ANSI color codes in text output? Can be
-                            \[aq]y\[aq]/\[aq]yes\[aq]/\[aq]always\[aq], \[aq]n\[aq]/\[aq]no\[aq]/\[aq]never\[aq] or \[aq]auto\[aq].
      \-\-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.
@@ -198,6 +196,8 @@ General help flags:
      \-\-man                  show the manual with man
      \-\-version              show version information
      \-\-debug=[1\-9]          show this much debug output (default: 1)
+     \-\-pager=YN             use a pager when needed ? y/yes (default) or n/no
+     \-\-color=YNA \-\-colour   use ANSI color ? y/yes, n/no, or auto (default)
 .EE
 .PP
 hledger\-web shows accounts with zero balances by default (like

hledger-web/hledger-web.info

@@ -190,8 +190,6 @@ General output/reporting flags (supported by some commands):
                             YYYY-MM-DD: value on given date
   -c --commodity-style=S    Override a commodity's display style.
                             Eg: -c '.' or -c '1.000,00 EUR'
-     --color=YN --colour    Use ANSI color codes in text output? Can be
-                            'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'.
      --pretty[=YN]          Use box-drawing characters in text output? Can be
                             'y'/'yes' or 'n'/'no'.
                             If YN is specified, the equals is required.
@@ -203,6 +201,8 @@ General help flags:
      --man                  show the manual with man
      --version              show version information
      --debug=[1-9]          show this much debug output (default: 1)
+     --pager=YN             use a pager when needed ? y/yes (default) or n/no
+     --color=YNA --colour   use ANSI color ? y/yes, n/no, or auto (default)
 
    hledger-web shows accounts with zero balances by default (like
 'hledger-ui', and unlike 'hledger').  Using the '-E/--empty' flag will
@@ -528,14 +528,14 @@ http://bugs.hledger.org), or on the #hledger chat or hledger mail list
 Tag Table:
 Node: Top225
 Node: OPTIONS2571
-Node: PERMISSIONS11103
+Node: PERMISSIONS11109
-Node: EDITING UPLOADING DOWNLOADING12454
+Node: EDITING UPLOADING DOWNLOADING12460
-Node: RELOADING13469
+Node: RELOADING13475
-Node: JSON API14036
+Node: JSON API14042
-Node: DEBUG OUTPUT19685
+Node: DEBUG OUTPUT19691
-Node: Debug output19837
+Node: Debug output19843
-Node: ENVIRONMENT20355
+Node: ENVIRONMENT20361
-Node: BUGS20591
+Node: BUGS20597
 
 End Tag Table
 

hledger-web/hledger-web.txt

@@ -167,8 +167,6 @@ OPTIONS
                                           YYYY-MM-DD: value on given date
                 -c --commodity-style=S    Override a commodity's display style.
                                           Eg: -c '.' or -c '1.000,00 EUR'
-                   --color=YN --colour    Use ANSI color codes in text output? Can be
-                                          'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'.
                    --pretty[=YN]          Use box-drawing characters in text output? Can be
                                           'y'/'yes' or 'n'/'no'.
                                           If YN is specified, the equals is required.
@@ -180,6 +178,8 @@ OPTIONS
                    --man                  show the manual with man
                    --version              show version information
                    --debug=[1-9]          show this much debug output (default: 1)
+                   --pager=YN             use a pager when needed ? y/yes (default) or n/no
+                   --color=YNA --colour   use ANSI color ? y/yes, n/no, or auto (default)
 
        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

@@ -420,8 +420,6 @@ General output/reporting flags (supported by some commands):
                             YYYY\-MM\-DD: value on given date
   \-c \-\-commodity\-style=S    Override a commodity\[aq]s display style.
                             Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq]
-     \-\-color=YN \-\-colour    Use ANSI color codes in text output? Can be
-                            \[aq]y\[aq]/\[aq]yes\[aq]/\[aq]always\[aq], \[aq]n\[aq]/\[aq]no\[aq]/\[aq]never\[aq] or \[aq]auto\[aq].
      \-\-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.
@@ -433,6 +431,8 @@ General help flags:
      \-\-man                  show the manual with man
      \-\-version              show version information
      \-\-debug=[1\-9]          show this much debug output (default: 1)
+     \-\-pager=YN             use a pager when needed ? y/yes (default) or n/no
+     \-\-color=YNA \-\-colour   use ANSI color ? y/yes, n/no, or auto (default)
 .EE
 .PP
 Usually hledger accepts any unambiguous flag prefix, eg you can write
@@ -961,6 +961,7 @@ Y
 T}@T{
 Y
 T}@T{
+Y
 T}@T{
 T}@T{
 T}@T{
@@ -1098,28 +1099,6 @@ override the file extension if needed:
 .EX
 $ hledger balancesheet \-o foo.txt \-O csv    # write CSV to foo.txt
 .EE
-.SS Paging
-On unix\-like systems, when displaying large output in the terminal,
-hledger tries to use a pager when appropriate: the one specified by the
-\f[CR]PAGER\f[R] environment variable, otherwise \f[CR]less\f[R] if
-available, otherwise \f[CR]more\f[R] if available.
-The pager shows one page of text at a time, and lets you scroll around
-to see more.
-While it is active, usually \f[CR]SPACE\f[R] shows the next page,
-\f[CR]q\f[R] quits, and \f[CR]?\f[R] shows more features.
-.PP
-The pager is expected to display ANSI color and text styling if
-possible.
-hledger adds \f[CR]R\f[R] to the \f[CR]LESS\f[R] and \f[CR]MORE\f[R]
-environment variables to enable this in \f[CR]less\f[R] (and in its
-\f[CR]more\f[R] compatibility mode).
-If you use a different pager, you might need to configure it similarly,
-to avoid seeing junk on screen.
-Or you can set the \f[CR]NO_COLOR\f[R] environment variable described
-below.
-.PP
-You can prevent the use of a pager by providing the
-\f[CR]\-\-no\-pager\f[R] flag at the command line, or in a config file.
 .PP
 Here are some notes about the various output formats.
 .SS Text output
@@ -1146,29 +1125,52 @@ Besides using a pager, helpful techniques for this situation include
 \f[CR]\-\-layout=bare\f[R], \f[CR]\-V\f[R], \f[CR]cur:\f[R],
 \f[CR]\-\-transpose\f[R], \f[CR]\-\-tree\f[R], \f[CR]\-\-depth\f[R],
 \f[CR]\-\-drop\f[R], switching to html output, etc.
+.SS Box\-drawing characters
+hledger draws simple table borders by default, to minimise the risk of
+display problems caused by a terminal/font not supporting box\-drawing
+characters.
 .PP
-(Help output uses a pager automatically when appropriate, but regular
+But your terminal and font probably do support them, so we recommend
-reports do not, currently.)
+using the \f[CR]\-\-pretty\f[R] flag to show prettier tables in the
-.SS Colour
+terminal.
-hledger tries to detect ANSI color and text styling support and use it
-when appropriate, though currently rather minimally: some reports show
-negative numbers in red, and help output uses bold text for emphasis.
-.PP
-You can override this in the usual ways.
-If the \f[CR]NO_COLOR\f[R] environment variable is set, colour will be
-disabled by default.
-Or you can use the \f[CR]\-\-color/\-\-colour\f[R] option with a
-\f[CR]y\f[R]/\f[CR]yes\f[R] value, or \f[CR]n\f[R]/\f[CR]no\f[R], to
-force colour on or off.
-(This option doesn\[aq]t work in a config file yet.)
-.SS Box\-drawing
-By default, hledger draws table borders using ascii characters, to
-minimise the chance of display problems.
-.PP
-If your terminal and font support box\-drawing characters (they probably
-do), you will probably want to use the \f[CR]\-\-pretty\f[R] flag to
-show prettier tables.
 This is a good flag to add to your hledger config file.
+.SS Colour
+hledger tries to automatically detect ANSI colour and text styling
+support and use it when appropriate.
+(Currently, it is used rather minimally: some reports show negative
+numbers in red, and help output uses bold text for emphasis.)
+.PP
+You can override this by setting the \f[CR]NO_COLOR\f[R] environment
+variable to disable it, or by using the \f[CR]\-\-color/\-\-colour\f[R]
+option, perhaps in your config file, with a \f[CR]y\f[R]/\f[CR]yes\f[R]
+or \f[CR]n\f[R]/\f[CR]no\f[R] value to force it on or off.
+.SS Paging
+In unix\-like environments, when displaying large output in the
+terminal, hledger tries to use a pager when appropriate.
+(Actually it does this for any output format displayed in the terminal,
+not just text.)
+You can prevent this with the \f[CR]\-\-pager=no\f[R] option, perhaps in
+your config file.
+.PP
+It will use the pager specified by the \f[CR]PAGER\f[R] environment
+variable, otherwise \f[CR]less\f[R] if available, otherwise
+\f[CR]more\f[R] if available.
+.PP
+The pager shows one page of text at a time, and lets you scroll around
+to see more.
+While it is active, usually \f[CR]SPACE\f[R] shows the next page,
+\f[CR]q\f[R] quits, and \f[CR]?\f[R] shows more features.
+(And in \f[CR]less\f[R], \f[CR]G\f[R] jumps to the end, which is useful
+when you are viewing register output.)
+.PP
+The pager is expected to display hledger\[aq]s ANSI colour and text
+styling.
+hledger adds \f[CR]R\f[R] to the \f[CR]LESS\f[R] and \f[CR]MORE\f[R]
+environment variables to enable this for \f[CR]less\f[R] and its
+\f[CR]more\f[R] compatibility mode.
+If you use a different pager, you might need to configure it similarly,
+to avoid seeing junk on screen.
+(Or you can disable colour, as described above.)
 .SS HTML output
 HTML output can be styled by an optional \f[CR]hledger.css\f[R] file in
 the same directory.
@@ -2352,18 +2354,29 @@ Tags hledger adds to indicate generated data:
  generated\-transaction  \-\- appears on generated periodic txns (with \-\-verbose\-tags)
  generated\-posting      \-\- appears on generated auto postings (with \-\-verbose\-tags)
  modified               \-\- appears on txns which have had auto postings added (with \-\-verbose\-tags)
-
+.EE
-Not displayed, but queryable:
+.PP
+These similar tags are also provided; they are not displayed, but can be
+relied on for querying:
+.IP
+.EX
  _generated\-transaction \-\- exists on generated periodic txns (always)
  _generated\-posting     \-\- exists on generated auto postings (always)
  _modified              \-\- exists on txns which have had auto postings added (always)
 .EE
 .PP
-Other tags hledger uses internally:
+The following non\-displayed tags are used internally by hledger, (1) to
+ignore redundant costs when balancing transactions, (2) when using
+\-\-infer\-costs, and (3) when using \-\-infer\-equity.
+Essentially they mark postings with costs which have corresponding
+equity conversion postings, and vice\-versa.
+They are queryable, but you should not rely on them for your reports:
 .IP
 .EX
- _cost\-matched          \-\- marks postings with a cost which have been matched with a nearby pair of equity conversion postings
+ _conversion\-matched    \-\- marks \[dq]matched conversion postings\[dq], which are to a V/Conversion account
- _conversion\-matched    \-\- marks equity conversion postings which have been matched with a nearby posting with a cost
+                           and have a nearby equivalent costful or potentially costful posting
+ _cost\-matched          \-\- marks \[dq]matched cost postings\[dq], which have or could have a cost
+                           that\[aq]s equivalent to nearby conversion postings
 .EE
 .SS Tag values
 Tags can have a value, which is any text after the colon up until a

hledger/hledger.txt

@@ -320,8 +320,6 @@ Options
                                           YYYY-MM-DD: value on given date
                 -c --commodity-style=S    Override a commodity's display style.
                                           Eg: -c '.' or -c '1.000,00 EUR'
-                   --color=YN --colour    Use ANSI color codes in text output? Can be
-                                          'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'.
                    --pretty[=YN]          Use box-drawing characters in text output? Can be
                                           'y'/'yes' or 'n'/'no'.
                                           If YN is specified, the equals is required.
@@ -333,6 +331,8 @@ Options
                    --man                  show the manual with man
                    --version              show version information
                    --debug=[1-9]          show this much debug output (default: 1)
+                   --pager=YN             use a pager when needed ? y/yes (default) or n/no
+                   --color=YNA --colour   use ANSI color ? y/yes, n/no, or auto (default)
 
        Usually hledger accepts any unambiguous flag prefix, eg you  can  write
        --tl instead of --tldr or --dry instead of --dry-run.
@@ -736,7 +736,7 @@ Output
 
        command                 txt     html     csv/tsv     fods     beancount      sql     json
        --------------------------------------------------------------------------------------------
-       aregister               Y       Y        Y                                           Y
+       aregister               Y       Y        Y           Y                               Y
        balance                 Y       Y        Y           Y                               Y
        balancesheet            Y       Y        Y           Y                               Y
        balancesheetequity      Y       Y        Y           Y                               Y
@@ -762,24 +762,6 @@ Output
 
               $ hledger balancesheet -o foo.txt -O csv    # write CSV to foo.txt
 
-   Paging
-       On unix-like systems, when displaying large  output  in  the  terminal,
-       hledger tries to use a pager when appropriate: the one specified by the
-       PAGER environment variable, otherwise less if available, otherwise more
-       if available.  The pager shows one page of text at a time, and lets you
-       scroll around to see more.  While it is active, usually SPACE shows the
-       next page, q quits, and ? shows more features.
-
-       The  pager is expected to display ANSI color and text styling if possi-
-       ble.  hledger adds R to the LESS and MORE environment variables to  en-
-       able  this  in less (and in its more compatibility mode).  If you use a
-       different pager, you might need to configure  it  similarly,  to  avoid
-       seeing  junk  on screen.  Or you can set the NO_COLOR environment vari-
-       able described below.
-
-       You can prevent the use of a pager by providing the --no-pager flag  at
-       the command line, or in a config file.
-
        Here are some notes about the various output formats.
 
    Text output
@@ -801,26 +783,46 @@ Output
        this  situation  include  --layout=bare, -V, cur:, --transpose, --tree,
        --depth, --drop, switching to html output, etc.
 
-       (Help  output  uses a pager automatically when appropriate, but regular
+   Box-drawing characters
-       reports do not, currently.)
+       hledger draws simple table borders by default, to minimise the risk  of
+       display  problems  caused by a terminal/font not supporting box-drawing
+       characters.
+
+       But your terminal and font probably do support them,  so  we  recommend
+       using  the --pretty flag to show prettier tables in the terminal.  This
+       is a good flag to add to your hledger config file.
 
    Colour
-       hledger tries to detect ANSI color and text styling support and use  it
+       hledger tries to automatically detect ANSI colour and text styling sup-
-       when  appropriate, though currently rather minimally: some reports show
+       port and use it when appropriate.  (Currently, it is used rather  mini-
-       negative numbers in red, and help output uses bold text for emphasis.
+       mally:  some reports show negative numbers in red, and help output uses
+       bold text for emphasis.)
 
-       You can override this in the usual ways.  If the  NO_COLOR  environment
+       You can override this by setting the NO_COLOR environment  variable  to
-       variable  is  set,  colour will be disabled by default.  Or you can use
+       disable  it,  or  by using the --color/--colour option, perhaps in your
-       the --color/--colour option with a  y/yes  value,  or  n/no,  to  force
+       config file, with a y/yes or n/no value to force it on or off.
-       colour on or off.  (This option doesn't work in a config file yet.)
 
-   Box-drawing
+   Paging
-       By default, hledger draws table borders using ascii characters, to min-
+       In unix-like environments, when displaying large output in  the  termi-
-       imise the chance of display problems.
+       nal,  hledger tries to use a pager when appropriate.  (Actually it does
+       this for any output format displayed in the terminal, not  just  text.)
+       You can prevent this with the --pager=no option, perhaps in your config
+       file.
 
-       If your terminal and font support box-drawing characters (they probably
+       It will use the pager specified by the PAGER environment variable, oth-
-       do),  you  will probably want to use the --pretty flag to show prettier
+       erwise less if available, otherwise more if available.
-       tables.  This is a good flag to add to your hledger config file.
+
+       The  pager shows one page of text at a time, and lets you scroll around
+       to see more.  While it is active, usually SPACE shows the next page,  q
+       quits,  and  ?  shows more features.  (And in less, G jumps to the end,
+       which is useful when you are viewing register output.)
+
+       The pager is  expected  to  display  hledger's  ANSI  colour  and  text
+       styling.   hledger adds R to the LESS and MORE environment variables to
+       enable this for less and its more compatibility mode.   If  you  use  a
+       different  pager,  you  might  need to configure it similarly, to avoid
+       seeing junk on screen.   (Or  you  can  disable  colour,  as  described
+       above.)
 
    HTML output
        HTML  output  can be styled by an optional hledger.css file in the same
@@ -1832,15 +1834,24 @@ Journal
                generated-posting      -- appears on generated auto postings (with --verbose-tags)
                modified               -- appears on txns which have had auto postings added (with --verbose-tags)
 
-              Not displayed, but queryable:
+       These similar tags are also provided; they are not displayed,  but  can
+       be relied on for querying:
+
                _generated-transaction -- exists on generated periodic txns (always)
                _generated-posting     -- exists on generated auto postings (always)
                _modified              -- exists on txns which have had auto postings added (always)
 
-       Other tags hledger uses internally:
+       The following non-displayed tags are used internally by hledger, (1) to
+       ignore  redundant  costs  when  balancing  transactions, (2) when using
+       --infer-costs, and (3) when  using  --infer-equity.   Essentially  they
+       mark  postings  with  costs  which have corresponding equity conversion
+       postings, and vice-versa.  They are queryable, but you should not  rely
+       on them for your reports:
 
-               _cost-matched          -- marks postings with a cost which have been matched with a nearby pair of equity conversion postings
+               _conversion-matched    -- marks "matched conversion postings", which are to a V/Conversion account
-               _conversion-matched    -- marks equity conversion postings which have been matched with a nearby posting with a cost
+                                         and have a nearby equivalent costful or potentially costful posting
+               _cost-matched          -- marks "matched cost postings", which have or could have a cost
+                                         that's equivalent to nearby conversion postings
 
    Tag values
        Tags  can  have  a  value, which is any text after the colon up until a