;doc: update manuals

hledger-ui/hledger-ui.1

@@ -8,11 +8,14 @@
 hledger-ui - robust, friendly plain text accounting (TUI version)
 .SH SYNOPSIS
 .PP
-\f[V]hledger-ui [OPTIONS] [QUERYARGS]\f[R]
+\f[V]hledger-ui    [OPTS] [QUERYARGS]    # run directly\f[R]
+.PD 0
+.P
+.PD
+\f[V]hledger ui -- [OPTS] [QUERYARGS]    # run from hledger\f[R]
 .PD 0
 .P
 .PD
-\f[V]hledger ui -- [OPTIONS] [QUERYARGS]\f[R]
 .SH DESCRIPTION
 .PP
 This manual is for hledger\[aq]s terminal interface, version 1.29.99.

hledger-ui/hledger-ui.info

@@ -13,8 +13,8 @@ hledger-ui(1)
 
 hledger-ui - robust, friendly plain text accounting (TUI version)
 
-   'hledger-ui [OPTIONS] [QUERYARGS]'
+   'hledger-ui [OPTS] [QUERYARGS] # run directly'
-'hledger ui -- [OPTIONS] [QUERYARGS]'
+'hledger ui -- [OPTS] [QUERYARGS] # run from hledger'
 
    This manual is for hledger's terminal interface, version 1.29.99.
 See also the hledger manual for common concepts and file formats.
@@ -665,46 +665,46 @@ above).
 
 Tag Table:
 Node: Top223
-Node: OPTIONS1838
+Node: OPTIONS1866
-Ref: #options1936
+Ref: #options1964
-Node: General help options2959
+Node: General help options2987
-Ref: #general-help-options3108
+Ref: #general-help-options3136
-Node: General input options3390
+Node: General input options3418
-Ref: #general-input-options3575
+Ref: #general-input-options3603
-Node: General reporting options4277
+Node: General reporting options4305
-Ref: #general-reporting-options4441
+Ref: #general-reporting-options4469
-Node: MOUSE7831
+Node: MOUSE7859
-Ref: #mouse7926
+Ref: #mouse7954
-Node: KEYS8163
+Node: KEYS8191
-Ref: #keys8256
+Ref: #keys8284
-Node: SCREENS12769
+Node: SCREENS12797
-Ref: #screens12867
+Ref: #screens12895
-Node: Menu13447
+Node: Menu13475
-Ref: #menu13540
+Ref: #menu13568
-Node: Cash accounts13735
+Node: Cash accounts13763
-Ref: #cash-accounts13877
+Ref: #cash-accounts13905
-Node: Balance sheet accounts14061
+Node: Balance sheet accounts14089
-Ref: #balance-sheet-accounts14242
+Ref: #balance-sheet-accounts14270
-Node: Income statement accounts14362
+Node: Income statement accounts14390
-Ref: #income-statement-accounts14548
+Ref: #income-statement-accounts14576
-Node: All accounts14712
+Node: All accounts14740
-Ref: #all-accounts14858
+Ref: #all-accounts14886
-Node: Register15040
+Node: Register15068
-Ref: #register15164
+Ref: #register15192
-Node: Transaction17126
+Node: Transaction17154
-Ref: #transaction17249
+Ref: #transaction17277
-Node: Error18666
+Node: Error18694
-Ref: #error18760
+Ref: #error18788
-Node: TIPS19004
+Node: TIPS19032
-Ref: #tips19103
+Ref: #tips19131
-Node: Watch mode19145
+Node: Watch mode19173
-Ref: #watch-mode19252
+Ref: #watch-mode19280
-Node: Debug output20711
+Node: Debug output20739
-Ref: #debug-output20822
+Ref: #debug-output20850
-Node: ENVIRONMENT21034
+Node: ENVIRONMENT21062
-Ref: #environment21144
+Ref: #environment21172
-Node: BUGS21335
+Node: BUGS21363
-Ref: #bugs21418
+Ref: #bugs21446
 
 End Tag Table
 

hledger-ui/hledger-ui.txt

@@ -7,9 +7,8 @@ NAME
        hledger-ui - robust, friendly plain text accounting (TUI version)
 
 SYNOPSIS
-       hledger-ui [OPTIONS] [QUERYARGS]
+       hledger-ui    [OPTS] [QUERYARGS]    # run directly
-       hledger ui -- [OPTIONS] [QUERYARGS]
+       hledger ui -- [OPTS] [QUERYARGS]    # run from hledger
-
 DESCRIPTION
        This  manual is for hledger's terminal interface, version 1.29.99.  See
        also the hledger manual for common concepts and file formats.

hledger-web/hledger-web.1

@@ -8,19 +8,22 @@
 hledger-web - robust, friendly plain text accounting (Web version)
 .SH SYNOPSIS
 .PP
-\f[V]hledger-web [OPTIONS]                  # run temporarily & browse\f[R]
+\f[V]hledger-web             [OPTS] [ARGS]    # run temporarily & open browser\f[R]
 .PD 0
 .P
 .PD
-\f[V]hledger-web --serve [OPTIONS]          # run without stopping\f[R]
+\f[V]hledger-web --serve     [OPTS] [ARGS]    # run without stopping\f[R]
 .PD 0
 .P
 .PD
-\f[V]hledger-web --serve-api [OPTIONS]      # run JSON server only\f[R]
+\f[V]hledger-web --serve-api [OPTS] [ARGS]    # run HTTP JSON server only\f[R]
+.PD 0
+.P
+.PD
+\f[V]hledger web --          [OPTS] [ARGS]    # run from hledger\f[R]
 .PD 0
 .P
 .PD
-\f[V]hledger web -- [OPTIONS] [QUERYARGS]\f[R] # start from hledger
 .SH DESCRIPTION
 .PP
 This manual is for hledger\[aq]s web interface, version 1.29.99.

hledger-web/hledger-web.info

@@ -13,10 +13,10 @@ hledger-web(1)
 
 hledger-web - robust, friendly plain text accounting (Web version)
 
-   'hledger-web [OPTIONS] # run temporarily & browse'
+   'hledger-web [OPTS] [ARGS] # run temporarily & open browser'
-'hledger-web --serve [OPTIONS] # run without stopping'
+'hledger-web --serve [OPTS] [ARGS] # run without stopping'
-'hledger-web --serve-api [OPTIONS] # run JSON server only'
+'hledger-web --serve-api [OPTS] [ARGS] # run HTTP JSON server only'
-'hledger web -- [OPTIONS] [QUERYARGS]' # start from hledger
+'hledger web -- [OPTS] [ARGS] # run from hledger'
 
    This manual is for hledger's web interface, version 1.29.99.  See
 also the hledger manual for common concepts and file formats.
@@ -648,30 +648,30 @@ http://bugs.hledger.org), or on the #hledger chat or hledger mail list
 
 Tag Table:
 Node: Top225
-Node: OPTIONS2702
+Node: OPTIONS2715
-Ref: #options2807
+Ref: #options2820
-Node: General help options6118
+Node: General help options6131
-Ref: #general-help-options6268
+Ref: #general-help-options6281
-Node: General input options6550
+Node: General input options6563
-Ref: #general-input-options6736
+Ref: #general-input-options6749
-Node: General reporting options7438
+Node: General reporting options7451
-Ref: #general-reporting-options7603
+Ref: #general-reporting-options7616
-Node: PERMISSIONS10993
+Node: PERMISSIONS11006
-Ref: #permissions11132
+Ref: #permissions11145
-Node: EDITING UPLOADING DOWNLOADING12344
+Node: EDITING UPLOADING DOWNLOADING12357
-Ref: #editing-uploading-downloading12525
+Ref: #editing-uploading-downloading12538
-Node: RELOADING13359
+Node: RELOADING13372
-Ref: #reloading13493
+Ref: #reloading13506
-Node: JSON API13926
+Node: JSON API13939
-Ref: #json-api14041
+Ref: #json-api14054
-Node: DEBUG OUTPUT19529
+Node: DEBUG OUTPUT19542
-Ref: #debug-output19654
+Ref: #debug-output19667
-Node: Debug output19681
+Node: Debug output19694
-Ref: #debug-output-119782
+Ref: #debug-output-119795
-Node: ENVIRONMENT20199
+Node: ENVIRONMENT20212
-Ref: #environment20318
+Ref: #environment20331
-Node: BUGS20435
+Node: BUGS20448
-Ref: #bugs20519
+Ref: #bugs20532
 
 End Tag Table
 

hledger-web/hledger-web.txt

@@ -7,47 +7,47 @@ NAME
        hledger-web - robust, friendly plain text accounting (Web version)
 
 SYNOPSIS
-       hledger-web [OPTIONS]                  # run temporarily & browse
+       hledger-web              [OPTS]  [ARGS]     #  run  temporarily  & open
-       hledger-web --serve [OPTIONS]          # run without stopping
+       browser
-       hledger-web --serve-api [OPTIONS]      # run JSON server only
+       hledger-web --serve     [OPTS] [ARGS]    # run without stopping
-       hledger web -- [OPTIONS] [QUERYARGS] # start from hledger
+       hledger-web --serve-api [OPTS] [ARGS]    # run HTTP JSON server only
-
+       hledger web --          [OPTS] [ARGS]    # run from hledger
 DESCRIPTION
-       This  manual is for hledger's web interface, version 1.29.99.  See also
+       This manual is for hledger's web interface, version 1.29.99.  See  also
        the hledger manual for common concepts and file formats.
 
-       hledger is a robust, user-friendly, cross-platform set of programs  for
+       hledger  is a robust, user-friendly, cross-platform set of programs for
-       tracking  money,  time,  or any other commodity, using double-entry ac-
+       tracking money, time, or any other commodity,  using  double-entry  ac-
-       counting and a simple, editable file format.  hledger  is  inspired  by
+       counting  and  a  simple, editable file format.  hledger is inspired by
-       and  largely  compatible  with  ledger(1), and largely interconvertible
+       and largely compatible with  ledger(1),  and  largely  interconvertible
        with beancount(1).
 
-       hledger-web is a simple web application for browsing and adding  trans-
+       hledger-web  is a simple web application for browsing and adding trans-
-       actions.   It  provides a more user-friendly UI than the hledger CLI or
+       actions.  It provides a more user-friendly UI than the hledger  CLI  or
-       hledger-ui TUI, showing more at once  (accounts,  the  current  account
+       hledger-ui  TUI,  showing  more  at once (accounts, the current account
        register, balance charts) and allowing history-aware data entry, inter-
        active searching, and bookmarking.
 
-       hledger-web also lets you share a journal with multiple users, or  even
+       hledger-web  also lets you share a journal with multiple users, or even
-       the  public  web.   There is no access control, so if you need that you
+       the public web.  There is no access control, so if you  need  that  you
-       should put it behind a suitable  web  proxy.   As  a  small  protection
+       should  put  it  behind  a  suitable  web proxy.  As a small protection
-       against  data  loss  when  running an unprotected instance, it writes a
+       against data loss when running an unprotected  instance,  it  writes  a
        numbered backup of the main journal file (only) on every edit.
 
-       Like hledger, it reads from (and appends to) a journal  file  specified
+       Like  hledger,  it reads from (and appends to) a journal file specified
-       by    the    LEDGER_FILE    environment    variable    (defaulting   to
+       by   the    LEDGER_FILE    environment    variable    (defaulting    to
-       $HOME/.hledger.journal); or you can specify files with -f options.   It
+       $HOME/.hledger.journal);  or you can specify files with -f options.  It
-       can  also  read timeclock files, timedot files, or any CSV/SSV/TSV file
+       can also read timeclock files, timedot files, or any  CSV/SSV/TSV  file
        with a date field.  (See hledger(1) -> Input for details.)
 
        hledger-web can be run in three modes:
 
        o Transient mode (the default): your default web browser will be opened
-         to  show  the  app if possible, and the app exits automatically after
+         to show the app if possible, and the app  exits  automatically  after
-         two minutes of inactivity (no requests received and no  open  browser
+         two  minutes  of inactivity (no requests received and no open browser
          windows viewing it).
 
-       o With  --serve:  the  app runs without stopping, and without opening a
+       o With --serve: the app runs without stopping, and  without  opening  a
          browser.
 
        o With --serve-api: only the JSON API is served.
@@ -57,7 +57,7 @@ DESCRIPTION
 
 OPTIONS
        Command-line options and arguments may be used to set an initial filter
-       on the data.  These filter options are not shown in the web UI, but  it
+       on  the data.  These filter options are not shown in the web UI, but it
        will be applied in addition to any search query entered there.
 
        hledger-web provides the following options:
@@ -66,7 +66,7 @@ OPTIONS
               serve and log requests, don't browse or auto-exit after timeout
 
        --serve-api
-              like  --serve,  but  serve  only  the  JSON web API, without the
+              like --serve, but serve only  the  JSON  web  API,  without  the
               server-side web UI
 
        --host=IPADDR
@@ -76,61 +76,61 @@ OPTIONS
               listen on this TCP port (default: 5000)
 
        --socket=SOCKETFILE
-              use a unix domain socket file to listen for requests instead  of
+              use  a unix domain socket file to listen for requests instead of
-              a  TCP socket.  Implies --serve.  It can only be used if the op-
+              a TCP socket.  Implies --serve.  It can only be used if the  op-
               erating system can provide this type of socket.
 
        --base-url=URL
-              set the base url (default: http://IPADDR:PORT).   Note:  affects
+              set  the  base url (default: http://IPADDR:PORT).  Note: affects
-              url  generation but not route parsing.  Can be useful if running
+              url generation but not route parsing.  Can be useful if  running
               behind a reverse web proxy that does path rewriting.
 
        --file-url=URL
               set the static files url (default: BASEURL/static).  hledger-web
-              normally  serves static files itself, but if you wanted to serve
+              normally serves static files itself, but if you wanted to  serve
-              them from another server for efficiency, you would set  the  url
+              them  from  another server for efficiency, you would set the url
               with this.
 
        --capabilities=CAP[,CAP..]
-              enable  the  view,  add,  and/or  manage  capabilities (default:
+              enable the  view,  add,  and/or  manage  capabilities  (default:
               view,add)
 
        --capabilities-header=HTTPHEADER
-              read capabilities to enable from a  HTTP  header,  like  X-Sand-
+              read  capabilities  to  enable  from a HTTP header, like X-Sand-
               storm-Permissions (default: disabled)
 
-       --test run  hledger-web's  tests  and exit.  hspec test runner args may
+       --test run hledger-web's tests and exit.  hspec test  runner  args  may
               follow a --, eg: hledger-web --test -- --help
 
-       By default the server listens on IP address 127.0.0.1, accessible  only
+       By  default the server listens on IP address 127.0.0.1, accessible only
-       to  local  requests.   You  can  use  --host  to change this, eg --host
+       to local requests.  You can  use  --host  to  change  this,  eg  --host
        0.0.0.0 to listen on all configured addresses.
 
-       Similarly, use --port to set a TCP port other than 5000, eg if you  are
+       Similarly,  use --port to set a TCP port other than 5000, eg if you are
        running multiple hledger-web instances.
 
        Both of these options are ignored when --socket is used.  In this case,
-       it creates an AF_UNIX socket file at the supplied path  and  uses  that
+       it  creates  an  AF_UNIX socket file at the supplied path and uses that
-       for  communication.   This  is  an  alternative way of running multiple
+       for communication.  This is an  alternative  way  of  running  multiple
-       hledger-web instances behind a reverse proxy that  handles  authentica-
+       hledger-web  instances  behind a reverse proxy that handles authentica-
-       tion  for  different  users.   The path can be derived in a predictable
+       tion for different users.  The path can be  derived  in  a  predictable
        way, eg by using the username within the path.  As an example, nginx as
-       reverse  proxy  can use the variable $remote_user to derive a path from
+       reverse proxy can use the variable $remote_user to derive a  path  from
-       the username used  in  a  HTTP  basic  authentication.   The  following
+       the  username  used  in  a  HTTP  basic  authentication.  The following
-       proxy_pass  directive  allows  access to all hledger-web instances that
+       proxy_pass directive allows access to all  hledger-web  instances  that
        created a socket in /tmp/hledger/:
 
                 proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;
 
-       You can use --base-url to change the protocol, hostname, port and  path
+       You  can use --base-url to change the protocol, hostname, port and path
        that appear in hyperlinks, useful eg for integrating hledger-web within
-       a larger website.  The default is http://HOST:PORT/ using the  server's
+       a  larger website.  The default is http://HOST:PORT/ using the server's
        configured host address and TCP port (or http://HOST if PORT is 80).
 
-       With  --file-url  you can set a different base url for static files, eg
+       With --file-url you can set a different base url for static  files,  eg
        for better caching or cookie-less serving on high performance websites.
 
-       hledger-web also supports many of hledger's general  options  (and  the
+       hledger-web  also  supports  many of hledger's general options (and the
        hledger manual's command line tips also apply here):
 
    General help options
@@ -153,7 +153,7 @@ OPTIONS
               $LEDGER_FILE or $HOME/.hledger.journal)
 
        --rules-file=RULESFILE
-              Conversion  rules  file  to  use  when  reading  CSV   (default:
+              Conversion   rules  file  to  use  when  reading  CSV  (default:
               FILE.rules)
 
        --separator=CHAR
@@ -172,7 +172,7 @@ OPTIONS
               assignments)
 
        -s --strict
-              do extra error checking (check that all posted accounts are  de-
+              do  extra error checking (check that all posted accounts are de-
               clared)
 
    General reporting options
@@ -200,7 +200,7 @@ OPTIONS
               multiperiod/multicolumn report by year
 
        -p --period=PERIODEXP
-              set  start date, end date, and/or reporting interval all at once
+              set start date, end date, and/or reporting interval all at  once
               using period expressions syntax
 
        --date2
@@ -208,7 +208,7 @@ OPTIONS
               fects)
 
        --today=DATE
-              override   today's  date  (affects  relative  smart  dates,  for
+              override  today's  date  (affects  relative  smart  dates,   for
               tests/examples)
 
        -U --unmarked
@@ -227,21 +227,21 @@ OPTIONS
               hide/aggregate accounts or postings more than NUM levels deep
 
        -E --empty
-              show items with zero amount, normally hidden (and vice-versa  in
+              show  items with zero amount, normally hidden (and vice-versa in
               hledger-ui/hledger-web)
 
        -B --cost
               convert amounts to their cost/selling amount at transaction time
 
        -V --market
-              convert  amounts to their market value in default valuation com-
+              convert amounts to their market value in default valuation  com-
               modities
 
        -X --exchange=COMM
               convert amounts to their market value in commodity COMM
 
        --value
-              convert amounts to cost or  market  value,  more  flexibly  than
+              convert  amounts  to  cost  or  market value, more flexibly than
               -B/-V/-X
 
        --infer-equity
@@ -251,38 +251,38 @@ OPTIONS
               infer costs from conversion equity postings
 
        --infer-market-prices
-              use  costs as additional market prices, as if they were P direc-
+              use costs as additional market prices, as if they were P  direc-
               tives
 
        --forecast
-              generate transactions from periodic rules,  between  the  latest
+              generate  transactions  from  periodic rules, between the latest
-              recorded  txn  and  6 months from today, or during the specified
+              recorded txn and 6 months from today, or  during  the  specified
-              PERIOD (= is required).  Auto posting rules will be  applied  to
+              PERIOD  (=  is required).  Auto posting rules will be applied to
-              these  transactions  as  well.  Also, in hledger-ui make future-
+              these transactions as well.  Also, in  hledger-ui  make  future-
               dated transactions visible.
 
-       --auto generate extra postings by applying auto posting  rules  to  all
+       --auto generate  extra  postings  by applying auto posting rules to all
               txns (not just forecast txns)
 
        --verbose-tags
-              add  visible tags indicating transactions or postings which have
+              add visible tags indicating transactions or postings which  have
               been generated/modified
 
        --commodity-style
-              Override the commodity style in the  output  for  the  specified
+              Override  the  commodity  style  in the output for the specified
               commodity.  For example 'EUR1.000,00'.
 
        --color=WHEN (or --colour=WHEN)
-              Should  color-supporting  commands  use ANSI color codes in text
+              Should color-supporting commands use ANSI color  codes  in  text
-              output.  'auto' (default): whenever stdout seems to be a  color-
+              output.   'auto' (default): whenever stdout seems to be a color-
-              supporting  terminal.  'always' or 'yes': always, useful eg when
+              supporting terminal.  'always' or 'yes': always, useful eg  when
-              piping output into  'less  -R'.   'never'  or  'no':  never.   A
+              piping  output  into  'less  -R'.   'never'  or  'no': never.  A
               NO_COLOR environment variable overrides this.
 
        --pretty[=WHEN]
-              Show  prettier  output,  e.g.  using unicode box-drawing charac-
+              Show prettier output, e.g.  using  unicode  box-drawing  charac-
-              ters.  Accepts 'yes' (the default) or 'no' ('y', 'n',  'always',
+              ters.   Accepts 'yes' (the default) or 'no' ('y', 'n', 'always',
-              'never'  also  work).   If  you provide an argument you must use
+              'never' also work).  If you provide an  argument  you  must  use
               '=', e.g.  '--pretty=yes'.
 
        When a reporting option appears more than once in the command line, the
@@ -291,13 +291,13 @@ OPTIONS
        Some reporting options can also be written as query arguments.
 
 PERMISSIONS
-       By  default,  hledger-web  allows  anyone  who can reach it to view the
+       By default, hledger-web allows anyone who can  reach  it  to  view  the
        journal and to add new transactions, but not to change existing data.
 
        You can restrict who can reach it by
 
-       o setting the IP address it listens on (see --host above).  By  default
+       o setting  the IP address it listens on (see --host above).  By default
-         it  listens  on  127.0.0.1,  accessible to all users on the local ma-
+         it listens on 127.0.0.1, accessible to all users  on  the  local  ma-
          chine.
 
        o putting it behind an authenticating proxy, using eg apache or nginx
@@ -307,44 +307,44 @@ PERMISSIONS
        You can restrict what the users who reach it can do, by
 
        o using the --capabilities=CAP[,CAP..] flag when you start it, enabling
-         one  or  more  of  the  following capabilities.  The default value is
+         one or more of the following  capabilities.   The  default  value  is
          view,add:
 
          o view - allows viewing the journal file and all included files
 
          o add - allows adding new transactions to the main journal file
 
-         o manage - allows editing, uploading or downloading the main  or  in-
+         o manage  -  allows editing, uploading or downloading the main or in-
            cluded files
 
-       o using  the  --capabilities-header=HTTPHEADER  flag  to specify a HTTP
+       o using the --capabilities-header=HTTPHEADER flag  to  specify  a  HTTP
-         header from which it will read capabilities to  enable.   hledger-web
+         header  from  which it will read capabilities to enable.  hledger-web
-         on  Sandstorm  uses  the  X-Sandstorm-Permissions header to integrate
+         on Sandstorm uses the  X-Sandstorm-Permissions  header  to  integrate
          with Sandstorm's permissions.  This is disabled by default.
 
 EDITING, UPLOADING, DOWNLOADING
-       If you enable the manage capability mentioned above, you'll see  a  new
+       If  you  enable the manage capability mentioned above, you'll see a new
-       "spanner"  button  to the right of the search form.  Clicking this will
+       "spanner" button to the right of the search form.  Clicking  this  will
-       let you edit, upload, or download the journal file or any files it  in-
+       let  you edit, upload, or download the journal file or any files it in-
        cludes.
 
-       Note,  unlike any other hledger command, in this mode you (or any visi-
+       Note, unlike any other hledger command, in this mode you (or any  visi-
        tor) can alter or wipe the data files.
 
-       Normally whenever a file is changed in this way,  hledger-web  saves  a
+       Normally  whenever  a  file is changed in this way, hledger-web saves a
-       numbered  backup  (assuming  file permissions allow it, the disk is not
+       numbered backup (assuming file permissions allow it, the  disk  is  not
-       full, etc.)  hledger-web is not aware of version control systems,  cur-
+       full,  etc.)  hledger-web is not aware of version control systems, cur-
-       rently;  if  you  use one, you'll have to arrange to commit the changes
+       rently; if you use one, you'll have to arrange to  commit  the  changes
        yourself (eg with a cron job or a file watcher like entr).
 
-       Changes which would leave the journal file(s) unparseable or  non-valid
+       Changes  which would leave the journal file(s) unparseable or non-valid
-       (eg  with  failing balance assertions) are prevented.  (Probably.  This
+       (eg with failing balance assertions) are prevented.   (Probably.   This
        needs re-testing.)
 
 RELOADING
        hledger-web detects changes made to the files by other means (eg if you
-       edit  it  directly,  outside  of hledger-web), and it will show the new
+       edit it directly, outside of hledger-web), and it  will  show  the  new
-       data when you reload the page or navigate to a new page.  If  a  change
+       data  when  you reload the page or navigate to a new page.  If a change
        makes a file unparseable, hledger-web will display an error message un-
        til the file has been fixed.
 
@@ -352,8 +352,8 @@ RELOADING
        that both machine clocks are roughly in step.)
 
 JSON API
-       In  addition to the web UI, hledger-web also serves a JSON API that can
+       In addition to the web UI, hledger-web also serves a JSON API that  can
-       be used to get data or add new transactions.  If you want the JSON  API
+       be  used to get data or add new transactions.  If you want the JSON API
        only, you can use the --serve-api flag.  Eg:
 
               $ hledger-web -f examples/sample.journal --serve-api
@@ -370,7 +370,7 @@ JSON API
               /accounttransactions/ACCOUNTNAME
 
        Eg, all account names in the journal (similar to the accounts command).
-       (hledger-web's JSON does not include newlines, here we  use  python  to
+       (hledger-web's  JSON  does  not include newlines, here we use python to
        prettify it):
 
               $ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
@@ -411,25 +411,25 @@ JSON API
                                       "aprice": null,
               ...
 
-       Most  of  the  JSON corresponds to hledger's data types; for details of
+       Most of the JSON corresponds to hledger's data types;  for  details  of
-       what the fields mean, see the Hledger.Data.Json haddock docs and  click
+       what  the fields mean, see the Hledger.Data.Json haddock docs and click
-       on  the various data types, eg Transaction.  And for a higher level un-
+       on the various data types, eg Transaction.  And for a higher level  un-
        derstanding, see the journal docs.
 
        In some cases there is outer JSON corresponding to a "Report" type.  To
-       understand  that,  go to the Hledger.Web.Handler.MiscR haddock and look
+       understand that, go to the Hledger.Web.Handler.MiscR haddock  and  look
-       at the source for the appropriate handler to see what it  returns.   Eg
+       at  the  source for the appropriate handler to see what it returns.  Eg
        for /accounttransactions it's getAccounttransactionsR, returning a "ac-
-       countTransactionsReport ...".  Looking up the haddock for that  we  can
+       countTransactionsReport  ...".   Looking up the haddock for that we can
-       see  that  /accounttransactions  returns  an AccountTransactionsReport,
+       see that  /accounttransactions  returns  an  AccountTransactionsReport,
-       which consists of a report title and a list  of  AccountTransactionsRe-
+       which  consists  of a report title and a list of AccountTransactionsRe-
        portItem (etc).
 
-       You  can  add  a  new  transaction to the journal with a PUT request to
+       You can add a new transaction to the journal  with  a  PUT  request  to
-       /add, if hledger-web was started with the add  capability  (enabled  by
+       /add,  if  hledger-web  was started with the add capability (enabled by
        default).  The payload must be the full, exact JSON representation of a
-       hledger transaction (partial data won't do).  You can get  sample  JSON
+       hledger  transaction  (partial data won't do).  You can get sample JSON
-       from  hledger-web's  /transactions  or /accounttransactions, or you can
+       from hledger-web's /transactions or /accounttransactions,  or  you  can
        export it with hledger-lib, eg like so:
 
               .../hledger$ stack ghci hledger-lib
@@ -525,28 +525,28 @@ JSON API
                   "tstatus": "Unmarked"
               }
 
-       And  here's how to test adding it with curl.  This should add a new en-
+       And here's how to test adding it with curl.  This should add a new  en-
        try to your journal:
 
               $ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json
 
 DEBUG OUTPUT
    Debug output
-       You can add --debug[=N] to the command line to  log  debug  output.   N
+       You  can  add  --debug[=N]  to the command line to log debug output.  N
        ranges from 1 (least output, the default) to 9 (maximum output).  Typi-
-       cally you would start with 1 and increase until you are seeing  enough.
+       cally  you would start with 1 and increase until you are seeing enough.
-       Debug  output  goes  to stderr, interleaved with the requests logged on
+       Debug output goes to stderr, interleaved with the  requests  logged  on
        stdout.  To capture debug output in a log file instead, you can usually
        redirect stderr, eg:
        hledger-web --debug=3 2>hledger-web.log.
 
 ENVIRONMENT
-       LEDGER_FILE  The  main  journal  file  to  use  when not specified with
+       LEDGER_FILE The main journal  file  to  use  when  not  specified  with
        -f/--file.  Default: $HOME/.hledger.journal.
 
 BUGS
        We  welcome  bug  reports  in  the  hledger  issue  tracker  (shortcut:
-       http://bugs.hledger.org),  or on the #hledger chat or hledger mail list
+       http://bugs.hledger.org), or on the #hledger chat or hledger mail  list
        (https://hledger.org/support).
 
        Some known issues:

hledger/hledger.1

@@ -9,16 +9,19 @@
 hledger - robust, friendly plain text accounting (CLI version)
 .SH SYNOPSIS
 .PP
-\f[V]hledger\f[R]
+\f[V]hledger                              # show commmands list\f[R]
 .PD 0
 .P
 .PD
-\f[V]hledger [-f FILE] COMMAND [OPTS] [ARGS]\f[R]
+\f[V]hledger COMMAND     [OPTS] [ARGS]    # run built-in command\f[R]
 .PD 0
 .P
 .PD
-\f[V]hledger [-f FILE] ADDONCMD -- [OPTS] [ARGS]\f[R]
+\f[V]hledger ADDONCMD -- [OPTS] [ARGS]    # run add-on command from PATH\f[R]
-.SH INTRODUCTION
+.PD 0
+.P
+.PD
+.SH DESCRIPTION
 .PP
 hledger is a robust, user-friendly, cross-platform set of programs for
 tracking money, time, or any other commodity, using double-entry
@@ -728,45 +731,10 @@ Eg: \f[V]hledger bal \[at]foo.args\f[R].
 .PP
 Inside the argument file, each line should contain just one option or
 argument.
-Also, don\[aq]t use spaces except inside quotes (or you\[aq]ll see a
+Don\[aq]t use spaces except inside quotes (or you\[aq]ll see a confusing
-confusing error).
+error); write \f[V]=\f[R] (or nothing) between a flag and its argument.
-Ie, write = (or nothing) between a flag and its argument.
-Eg, bad:
-.IP
-.nf
-\f[C]
-assets -X USD
-\f[R]
-.fi
-.PP
-Good:
-.IP
-.nf
-\f[C]
-assets
--X=USD
-\f[R]
-.fi
-.PP
 For the special characters mentioned above, use one less level of
 quoting than you would at the command prompt.
-Eg, bad:
-.IP
-.nf
-\f[C]
--X\[dq]$\[dq]
-\f[R]
-.fi
-.PP
-Good:
-.IP
-.nf
-\f[C]
--X$
-\f[R]
-.fi
-.PP
-See also: Save frequently used options.
 .SH Output
 .SS Output destination
 .PP
@@ -3719,31 +3687,24 @@ parentheses after an amount.
 hledger ignores these.
 .SS Virtual postings
 .PP
-A posting with parentheses around the account name is called a
+A posting with parentheses around the account name
-\f[I]virtual posting\f[R] or \f[I]unbalanced posting\f[R], which means
+(\f[V](some:account)\f[R]) is called a \f[I]unbalanced virtual
-it is exempt from the usual rule that a transaction\[aq]s postings must
+posting\f[R].
-balance add up to zero.
+Such postings do not participate in transaction balancing.
+(And if you write them without an amount, a zero amount is always
+inferred.)
+These can occasionally be convenient for special circumstances, but they
+violate double entry bookkeeping and make your data less portable across
+applications, so many people avoid using them at all.
 .PP
-This is not part of double entry bookkeeping, so you might choose to
+A posting with brackets around the account name
-avoid this feature.
+(\f[V][some:account]\f[R]) is called a \f[I]balanced virtual
-Or you can use it sparingly for certain special cases where it can be
+posting\f[R].
-convenient.
+The balanced virtual postings in a transaction must add up to zero, just
-Eg, you could set opening balances without using a balancing equity
+like ordinary postings, but separately from them.
-account:
+These are not part of double entry bookkeeping either, but they are at
-.IP
+least balanced.
-.nf
+An example:
-\f[C]
-2022-01-01 opening balances
-  (assets:checking)   $1000
-  (assets:savings)    $2000
-\f[R]
-.fi
-.PP
-A posting with brackets around the account name is called a
-\f[I]balanced virtual posting\f[R].
-The balanced virtual postings in a transaction must add up to zero
-(separately from other postings).
-Eg:
 .IP
 .nf
 \f[C]
@@ -3757,14 +3718,10 @@ Eg:
 \f[R]
 .fi
 .PP
-Postings whose account names are neither parenthesised nor bracketed are
+Ordinary postings, whose account names are neither parenthesised nor
-called \f[I]real postings\f[R].
+bracketed, are called \f[I]real postings\f[R].
 You can exclude virtual postings from reports with the
 \f[V]-R/--real\f[R] flag or a \f[V]real:1\f[R] query.
-.PP
-Downsides: violates double entry bookkeeping, can be used to avoid
-figuring out correct entries, makes your financial data less portable
-and less trustworthy in an audit.
 .SS Other Ledger directives
 .PP
 These other Ledger directives are currently accepted but ignored.