;doc: update manuals

hledger-ui/hledger-ui.1

@@ -1,5 +1,5 @@
 
-.TH "HLEDGER-UI" "1" "December 2021" "hledger-ui-1.24.99 " "hledger User Manuals"
+.TH "HLEDGER-UI" "1" "December 2021" "hledger-ui-1.25.99 " "hledger User Manuals"
 
 
 
@@ -7,7 +7,7 @@
 .PP
 hledger-ui is a terminal interface (TUI) for the hledger accounting
 tool.
-This manual is for hledger-ui 1.24.99.
+This manual is for hledger-ui 1.25.99.
 .SH SYNOPSIS
 .PP
 \f[C]hledger-ui [OPTIONS] [QUERYARGS]\f[R]

hledger-ui/hledger-ui.info

@@ -12,7 +12,7 @@ hledger-ui(1)
 *************
 
 hledger-ui is a terminal interface (TUI) for the hledger accounting
-tool.  This manual is for hledger-ui 1.24.99.
+tool.  This manual is for hledger-ui 1.25.99.
 
    'hledger-ui [OPTIONS] [QUERYARGS]'
 'hledger ui -- [OPTIONS] [QUERYARGS]'

hledger-ui/hledger-ui.txt

@@ -5,7 +5,7 @@ HLEDGER-UI(1)                hledger User Manuals                HLEDGER-UI(1)
 
 NAME
        hledger-ui  is  a  terminal  interface (TUI) for the hledger accounting
-       tool.  This manual is for hledger-ui 1.24.99.
+       tool.  This manual is for hledger-ui 1.25.99.
 
 SYNOPSIS
        hledger-ui [OPTIONS] [QUERYARGS]
@@ -548,4 +548,4 @@ SEE ALSO
 
 
 
-hledger-ui-1.24.99               December 2021                   HLEDGER-UI(1)
+hledger-ui-1.25.99               December 2021                   HLEDGER-UI(1)

hledger-web/hledger-web.1

@@ -1,12 +1,12 @@
 
-.TH "HLEDGER-WEB" "1" "December 2021" "hledger-web-1.24.99 " "hledger User Manuals"
+.TH "HLEDGER-WEB" "1" "December 2021" "hledger-web-1.25.99 " "hledger User Manuals"
 
 
 
 .SH NAME
 .PP
 hledger-web is a web interface (WUI) for the hledger accounting tool.
-This manual is for hledger-web 1.24.99.
+This manual is for hledger-web 1.25.99.
 .SH SYNOPSIS
 .PP
 \f[C]hledger-web [OPTIONS]\f[R]

hledger-web/hledger-web.info

@@ -12,7 +12,7 @@ hledger-web(1)
 **************
 
 hledger-web is a web interface (WUI) for the hledger accounting tool.
-This manual is for hledger-web 1.24.99.
+This manual is for hledger-web 1.25.99.
 
    'hledger-web [OPTIONS]'
 'hledger web -- [OPTIONS]'

hledger-web/hledger-web.txt

@@ -5,7 +5,7 @@ HLEDGER-WEB(1)               hledger User Manuals               HLEDGER-WEB(1)
 
 NAME
        hledger-web  is  a web interface (WUI) for the hledger accounting tool.
-       This manual is for hledger-web 1.24.99.
+       This manual is for hledger-web 1.25.99.
 
 SYNOPSIS
        hledger-web [OPTIONS]
@@ -585,4 +585,4 @@ SEE ALSO
 
 
 
-hledger-web-1.24.99              December 2021                  HLEDGER-WEB(1)
+hledger-web-1.25.99              December 2021                  HLEDGER-WEB(1)

hledger/hledger.1

@@ -1,6 +1,6 @@
 .\"t
 
-.TH "HLEDGER" "1" "December 2021" "hledger-1.24.99 " "hledger User Manuals"
+.TH "HLEDGER" "1" "December 2021" "hledger-1.25.99 " "hledger User Manuals"
 
 
 
@@ -9,7 +9,7 @@
 This is the command-line interface (CLI) for the hledger accounting
 tool.
 Here we also describe hledger\[aq]s concepts and file formats.
-This manual is for hledger 1.24.99.
+This manual is for hledger 1.25.99.
 .SH SYNOPSIS
 .PP
 \f[C]hledger\f[R]
@@ -706,8 +706,8 @@ Are all commodities declared with a \f[C]commodity\f[R] directive ?
 .IP \[bu] 2
 Are all commodity conversions declared explicitly ?
 .PP
-You can also use the check command to run these and some additional
+You can use the check command to run individual checks -- the ones
-checks.
+listed above and some more.
 .SH TIME PERIODS
 .SS Smart dates
 .PP
@@ -1464,14 +1464,32 @@ Match real or virtual postings respectively.
 .PD
 Match unmarked, pending, or cleared transactions respectively.
 .PP
+\f[B]\f[CB]type:TYPECODES\f[B]\f[R]
+.PD 0
+.P
+.PD
+Match by account type (see Declaring accounts > Account types).
+\f[C]TYPECODES\f[R] is one or more of the single-letter account type
+codes \f[C]ALERXCV\f[R], case insensitive.
+Note \f[C]type:A\f[R] and \f[C]type:E\f[R] will also match their
+respective subtypes \f[C]C\f[R] (Cash) and \f[C]V\f[R] (Conversion).
+Certain kinds of account alias can disrupt account types, see Rewriting
+accounts > Aliases and account types.
+.PP
 \f[B]\f[CB]tag:REGEX[=REGEX]\f[B]\f[R]
 .PD 0
 .P
 .PD
 Match by tag name, and optionally also by tag value.
-(To match only by value, use \f[C]tag:.=REGEX\f[R].) Note that postings
+(To match only by value, use \f[C]tag:.=REGEX\f[R].)
-also inherit tags from their transaction, and transactions also acquire
+.PP
-tags from their postings, when querying.
+When querying by tag, note that:
+.IP \[bu] 2
+Accounts also inherit the tags of their parent accounts
+.IP \[bu] 2
+Postings also inherit the tags of their account and their transaction
+.IP \[bu] 2
+Transactions also acquire the tags of their postings.
 .PP
 (\f[B]\f[CB]inacct:ACCTNAME\f[B]\f[R]
 .PD 0
@@ -2934,6 +2952,10 @@ account name components.
 Account names can be depth-clipped with \f[C]depth:N\f[R] or
 \f[C]--depth N\f[R] or \f[C]-N\f[R].
 .PP
+With \f[C]--types\f[R], it also shows each account\[aq]s type, if
+it\[aq]s known.
+(See Declaring accounts > Account types.)
+.PP
 Examples:
 .IP
 .nf
@@ -7031,8 +7053,8 @@ write multiple postings, each asserting one commodity\[aq]s balance.
 .PP
 You can make a stronger \[dq]total\[dq] balance assertion by writing a
 double equals sign (\f[C]== EXPECTEDBALANCE\f[R]).
-This asserts that there are no other unasserted commodities in the
+This asserts that there are no other commodities in the account besides
-account (or, that their balance is 0).
+the asserted one (or at least, that their balance is 0).
 .IP
 .nf
 \f[C]
@@ -7695,18 +7717,18 @@ Though not required, these declarations can provide several benefits:
 They can document your intended chart of accounts, providing a
 reference.
 .IP \[bu] 2
+They control account display order in reports, allowing non-alphabetic
+sorting (eg Revenues to appear above Expenses).
+.IP \[bu] 2
 They can help hledger know your accounts\[aq] types (asset, liability,
 equity, revenue, expense), useful for reports like balancesheet and
 incomestatement.
 .IP \[bu] 2
-They control account display order in reports, allowing non-alphabetic
+They can store other account information, as comments or as tags which
-sorting (eg Revenues to appear above Expenses).
+can be used to filter reports.
 .IP \[bu] 2
-They can store extra information about accounts (account numbers, notes,
+They help with account name completion (in hledger add, hledger-web,
-etc.)
+hledger-iadd, ledger-mode, etc.)
-.IP \[bu] 2
-They help with account name completion in the add command, hledger-iadd,
-hledger-web, ledger-mode etc.
 .IP \[bu] 2
 In strict mode, they restrict which accounts may be posted to by
 transactions, which helps detect typos.
@@ -7763,13 +7785,14 @@ An example of both:
 .IP
 .nf
 \f[C]
-account assets:bank:checking  ; same-line comment, note 2+ spaces before ;
+account assets:bank:checking    ; same-line comment, note 2+ spaces required before ;
   ; next-line comment
-  ; another with tag, acctno:12345 (not used yet)
+  ; some tags, type:A, acctnum:12345
 \f[R]
 .fi
 .PP
-Same-line comments are not supported by Ledger, or hledger <1.13.
+Compatibility note: same-line comments are not supported by Ledger or
+hledger <1.13.
 .SS Account subdirectives
 .PP
 We also allow (and ignore) Ledger-style indented subdirectives, just for
@@ -7786,92 +7809,124 @@ Here is the full syntax of account directives:
 .IP
 .nf
 \f[C]
-account ACCTNAME  [ACCTTYPE] [;COMMENT]
+account ACCTNAME  [;type:ACCTTYPE] [COMMENT]
   [;COMMENTS]
   [LEDGER-STYLE SUBDIRECTIVES, IGNORED]
 \f[R]
 .fi
 .SS Account types
 .PP
-By adding a \f[C]type\f[R] tag to the account directive, with value
+hledger knows that accounts come in several types: assets, liabilities,
-\f[C]A\f[R], \f[C]L\f[R], \f[C]E\f[R], \f[C]R\f[R], \f[C]X\f[R],
+expenses and so on.
-\f[C]C\f[R], \f[C]V\f[R] (or if you prefer: \f[C]Asset\f[R],
+This enables easy reports like balancesheet and incomestatement, and
-\f[C]Liability\f[R], \f[C]Equity\f[R], \f[C]Revenue\f[R],
+filtering by account type with the \f[C]type:\f[R] query.
-\f[C]Expense\f[R], \f[C]Cash\f[R], \f[C]Conversion\f[R]), you can
-declare hledger accounts to be of a certain type:
-.IP \[bu] 2
-\f[B]asset\f[R], \f[B]liability\f[R], \f[B]equity\f[R],
-\f[B]revenue\f[R], \f[B]expense\f[R]
-.PD 0
-.P
-.PD
-the standard types in accounting, or
-.IP \[bu] 2
-\f[B]cash\f[R]
-.PD 0
-.P
-.PD
-a subtype of asset, used for liquid assets.
-.IP \[bu] 2
-\f[B]conversion\f[R]
-.PD 0
-.P
-.PD
-a subtype of equity, used for conversion postings
 .PP
-Declaring account types is a good idea, since it helps enable the easy
+As a convenience, hledger will detect these account types automatically
-balancesheet, balancesheetequity, incomestatement and cashflow reports,
+if you are using common english-language top-level account names
-and probably other things in future.
+(described below).
-As a convenience, when account types are not declared, hledger will try
+But generally we recommend you declare types explicitly, by adding a
-to guess them based on english-language account names.
+\f[C]type:\f[R] tag to your top-level account directives.
+Subaccounts will inherit the type of their parent.
+The tag\[aq]s value should be one of the five main account types:
+.IP \[bu] 2
+\f[C]A\f[R] or \f[C]Asset\f[R] (things you own)
+.IP \[bu] 2
+\f[C]L\f[R] or \f[C]Liability\f[R] (things you owe)
+.IP \[bu] 2
+\f[C]E\f[R] or \f[C]Equity\f[R] (investment/ownership; balanced
+counterpart of assets & liabilities)
+.IP \[bu] 2
+\f[C]R\f[R] or \f[C]Revenue\f[R] (what you received money from, AKA
+income; technically part of Equity)
+.IP \[bu] 2
+\f[C]X\f[R] or \f[C]Expense\f[R] (what you spend money on; technically
+part of Equity)
 .PP
-Here is a typical set of top-level account declarations (because of the
+or, it can be (these are used less often):
-aforementioned, with these account names the type tags are not strictly
+.IP \[bu] 2
-needed, but with non-english or non-standard account names, they will
+\f[C]C\f[R] or \f[C]Cash\f[R] (a subtype of Asset, indicating liquid
-be):
+assets for the cashflow report)
+.IP \[bu] 2
+\f[C]V\f[R] or \f[C]Conversion\f[R] (a subtype of Equity, for
+conversions (see CONVERSION & COST).)
+.PP
+Here is a typical set of account type declarations:
 .IP
 .nf
 \f[C]
-account assets       ; type: A
+account assets             ; type: A
-account liabilities  ; type: L
+account liabilities        ; type: L
-account equity       ; type: E
+account equity             ; type: E
-account revenues     ; type: R
+account revenues           ; type: R
-account expenses     ; type: X
+account expenses           ; type: X
 
-account assets:bank  ; type: C
+account assets:bank        ; type: C
-account assets:cash  ; type: C
+account assets:cash        ; type: C
+
+account equity:conversion  ; type: V
 \f[R]
 .fi
 .PP
-It\[aq]s not necessary to declare the type of subaccounts.
+Here are some tips for working with account types.
-(You can, if they are different from the parent, but this is not
+.IP \[bu] 2
-common.)
+The rules for inferring types from account names are as follows.
-.SS Auto-detected account types
+These are just a convenience that sometimes help new users get going; if
-.PP
+they don\[aq]t work for you, just ignore them and declare your account
-More about \[dq]guessing\[dq] account types: hledger tries to find at
+types.
-least one top level account in each of the six account types (Asset,
+See also Regular expressions.
-Liability, Equity, Revenue, Expense, Cash).
+Note the Cash regexp changed in hledger 1.24.99.2.
-When no accounts have been declared for a particular type, it tries to
+.RS 2
-auto-detect some accounts by name, using the regular expressions below.
-Note: if you declare any account\[aq]s type, it\[aq]s a good idea to
-declare an account for all six types, because a mix of declared and
-auto-detected types can cause confusing results.
-.PP
-The auto-detection rules are:
 .IP
 .nf
 \f[C]
- If account\[aq]s name matches this case insensitive regular expression:| its type is:
+If account\[aq]s name contains this (CI) regular expression:            | its type is:
-------------------------------------------------------------------- | ------------
+--------------------------------------------------------------------|-------------
- \[ha]assets?(:|$)                                                      | 
+\[ha]assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash
-   and does not contain regexp (investment|receivable|:A/R|:fixed)  | Cash
+\[ha]assets?(:|$)                                                       | Asset
-   otherwise                                                        | Asset
+\[ha](debts?|liabilit(y|ies))(:|$)                                      | Liability
- \[ha](debts?|liabilit(y|ies))(:|$)                                     | Liability
+\[ha]equity:(trad(e|ing)|conversion)s?(:|$)                             | Conversion
- \[ha]equity(:|$)                                                       | Equity
+\[ha]equity(:|$)                                                        | Equity
- \[ha](income|revenue)s?(:|$)                                           | Revenue
+\[ha](income|revenue)s?(:|$)                                            | Revenue
- \[ha]expenses?(:|$)                                                    | Expense
+\[ha]expenses?(:|$)                                                     | Expense
 \f[R]
 .fi
+.RE
+.IP \[bu] 2
+If you declare any account types, it\[aq]s a good idea to declare an
+account for each of them, because a mixture of declared and
+name-inferred types can disrupt certain reports.
+.IP \[bu] 2
+Certain uses of account aliases can disrupt account types.
+See Rewriting accounts > Aliases and account types.
+.IP \[bu] 2
+As mentioned above, subaccounts will inherit a type from their parent
+account.
+To be precise, an account\[aq]s type is decided by the first of these
+that exists:
+.RS 2
+.IP "1." 3
+A \f[C]type:\f[R] declaration for this account.
+.IP "2." 3
+A \f[C]type:\f[R] declaration in the parent accounts above it,
+preferring the nearest.
+.IP "3." 3
+An account type inferred from this account\[aq]s name.
+.IP "4." 3
+An account type inferred from a parent account\[aq]s name, preferring
+the nearest parent.
+.IP "5." 3
+Otherwise, it will have no type.
+.RE
+.IP \[bu] 2
+For troubleshooting, you can list accounts and their types with:
+.RS 2
+.IP
+.nf
+\f[C]
+$ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES]
+\f[R]
+.fi
+.RE
 .SS Account display order
 .PP
 Account directives also set the order in which accounts are displayed,
@@ -8139,6 +8194,28 @@ $ hledger print --alias old=\[dq]new  USD\[dq] | hledger -f- print
     other
 \f[R]
 .fi
+.SS Aliases and account types
+.PP
+If an account with a type declaration (see Declaring accounts > Account
+types) is renamed by an alias, normally the account type remains in
+effect.
+.PP
+However, renaming in a way that reshapes the account tree (eg renaming
+parent accounts but not their children, or vice versa) could prevent
+child accounts from inheriting the account type of their parents.
+.PP
+Secondly, if an account\[aq]s type is being inferred from its name,
+renaming it by an alias could prevent or alter that.
+.PP
+If you are using account aliases and the \f[C]type:\f[R] query is not
+matching accounts as you expect, try troubleshooting with the accounts
+command, eg something like:
+.IP
+.nf
+\f[C]
+$ hledger accounts --alias assets=bassetts type:a
+\f[R]
+.fi
 .SS Default parent account
 .PP
 You can specify a parent account which will be prepended to all accounts