;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,11 +7,11 @@ 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
        the hledger manual for common concepts and file formats.

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.

hledger/hledger.txt

@@ -7,11 +7,10 @@ NAME
        hledger - robust, friendly plain text accounting (CLI version)
 
 SYNOPSIS
-       hledger
+       hledger                              # show commmands list
-       hledger [-f FILE] COMMAND [OPTS] [ARGS]
+       hledger COMMAND     [OPTS] [ARGS]    # run built-in command
-       hledger [-f FILE] ADDONCMD -- [OPTS] [ARGS]
+       hledger ADDONCMD -- [OPTS] [ARGS]    # run add-on command from PATH
-
+DESCRIPTION
-INTRODUCTION
        hledger  is a robust, user-friendly, cross-platform set of programs for
        tracking money, time, or any other commodity,  using  double-entry  ac-
        counting  and  a  simple, editable file format.  hledger is inspired by
@@ -550,27 +549,10 @@ Command line tips
        hledger bal @foo.args.
 
        Inside the argument file, each line should contain just one  option  or
-       argument.  Also, don't use spaces except inside quotes (or you'll see a
+       argument.   Don't use spaces except inside quotes (or you'll see a con-
-       confusing error).  Ie, write = (or nothing) between a flag and its  ar-
+       fusing error); write = (or nothing) between a flag  and  its  argument.
-       gument.  Eg, bad:
-
-              assets -X USD
-
-       Good:
-
-              assets
-              -X=USD
-
        For the special characters mentioned above, use one less level of quot-
-       ing than you would at the command prompt.  Eg, bad:
+       ing than you would at the command prompt.
-
-              -X"$"
-
-       Good:
-
-              -X$
-
-       See also: Save frequently used options.
 
 Output
    Output destination
@@ -1627,11 +1609,12 @@ Journal
        READING DATA:
        Rewrite account names                      alias
        Comment out sections of the file           comment
+
+
        Declare file's  decimal  mark,  to  help   decimal-mark
        parse amounts accurately
        Include other data files                   include
        GENERATING DATA:
-
        Generate  recurring transactions or bud-   ~
        get goals
        Generate  extra  postings  on   existing   =
@@ -1699,12 +1682,13 @@ Journal
                   --budget.
        Other
        syntax:
+
+
        apply      Prepends  a  common parent account to all account names, in fol-   Y
        account    lowing entries until end of current file or end apply account.
        D          Sets a default commodity to use for  no-symbol  amounts;and,  if   Y,Y,N,N
                   there  is no commodity directive for this commodity: its decimal
                   mark, balancing precision, and display style, as above.
-
        Y          Sets a default year to use for any yearless dates, in  following   Y
                   entries until end of current file.
        =          Declares  an  auto posting rule that generates extra postings on   partly
@@ -2695,22 +2679,19 @@ Journal
        parentheses after an amount.  hledger ignores these.
 
    Virtual postings
-       A  posting with parentheses around the account name is called a virtual
+       A  posting with parentheses around the account name ((some:account)) is
-       posting or unbalanced posting, which means it is exempt from the  usual
+       called a unbalanced virtual posting.  Such postings do not  participate
-       rule that a transaction's postings must balance add up to zero.
+       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.
 
-       This  is  not  part of double entry bookkeeping, so you might choose to
+       A  posting  with  brackets  around the account name ([some:account]) is
-       avoid this feature.  Or you can use it sparingly  for  certain  special
+       called a balanced virtual posting.  The balanced virtual postings in  a
-       cases  where  it can be convenient.  Eg, you could set opening balances
+       transaction must add up to zero, just like ordinary postings, but sepa-
-       without using a balancing equity account:
+       rately from them.  These are not part of double entry  bookkeeping  ei-
-
+       ther, but they are at least balanced.  An example:
-              2022-01-01 opening balances
-                (assets:checking)   $1000
-                (assets:savings)    $2000
-
-       A posting with brackets around the account name is  called  a  balanced
-       virtual  posting.   The balanced virtual postings in a transaction must
-       add up to zero (separately from other postings).  Eg:
 
               2022-01-01 buy food with cash, update budget envelope subaccounts, & something else
                 assets:cash                    $-10  ; <- these balance each other
@@ -2720,13 +2701,9 @@ Journal
                 [assets:checking:available]     $10  ;   <-
                 (something:else)                 $5  ;     <- this is not required to balance
 
-       Postings whose account names are neither  parenthesised  nor  bracketed
+       Ordinary  postings,  whose  account names are neither parenthesised nor
-       are  called  real  postings.  You can exclude virtual postings from re-
+       bracketed, are called real postings.  You can exclude virtual  postings
-       ports with the -R/--real flag or a real:1 query.
+       from reports with the -R/--real flag or a real:1 query.
-
-       Downsides: violates double entry bookkeeping, can be used to avoid fig-
-       uring  out correct entries, makes your financial data less portable and
-       less trustworthy in an audit.
 
    Other Ledger directives
        These other Ledger directives are currently accepted but ignored.  This
@@ -2805,6 +2782,7 @@ CSV
 
        source                     optionally  declare  which  file  to read data
                                   from
+
        separator                  declare the field separator, instead of  rely-
                                   ing on file extension
        skip                       skip one or more header lines at start of file
@@ -2813,7 +2791,6 @@ CSV
                                   times
        newest-first               improve txn order  when:  there  are  multiple
                                   records, newest first, all with the same date
-
        intra-day-reversed         improve  txn  order when: same-day txns are in
                                   opposite order to the overall file
        decimal-mark               declare the decimal mark used in CSV  amounts,