;doc: update manuals

hledger-lib/.date.m4

@@ -1,2 +1,2 @@
 m4_dnl Date to show in man pages. Updated by "Shake manuals"
-m4_define({{_monthyear_}}, {{January 2024}})m4_dnl
+m4_define({{_monthyear_}}, {{February 2024}})m4_dnl

hledger-ui/.date.m4

@@ -1,2 +1,2 @@
 m4_dnl Date to show in man pages. Updated by "Shake manuals"
-m4_define({{_monthyear_}}, {{January 2024}})m4_dnl
+m4_define({{_monthyear_}}, {{February 2024}})m4_dnl

hledger-ui/hledger-ui.1

@@ -1,5 +1,5 @@
 
-.TH "HLEDGER\-UI" "1" "January 2024" "hledger-ui-1.32.99 " "hledger User Manuals"
+.TH "HLEDGER\-UI" "1" "February 2024" "hledger-ui-1.32.99 " "hledger User Manuals"
 
 
 

hledger-ui/hledger-ui.info

@@ -673,44 +673,44 @@ Tag Table:
 Node: Top221
 Node: OPTIONS1830
 Ref: #options1928
-Node: General help options2951
+Node: General help options2956
-Ref: #general-help-options3100
+Ref: #general-help-options3105
-Node: General input options3382
+Node: General input options3387
-Ref: #general-input-options3567
+Ref: #general-input-options3572
-Node: General reporting options4224
+Node: General reporting options4229
-Ref: #general-reporting-options4388
+Ref: #general-reporting-options4393
-Node: MOUSE7778
+Node: MOUSE7783
-Ref: #mouse7873
+Ref: #mouse7878
-Node: KEYS8110
+Node: KEYS8115
-Ref: #keys8203
+Ref: #keys8208
-Node: SCREENS12858
+Node: SCREENS12863
-Ref: #screens12956
+Ref: #screens12961
-Node: Menu13536
+Node: Menu13541
-Ref: #menu13629
+Ref: #menu13634
-Node: Cash accounts13824
+Node: Cash accounts13829
-Ref: #cash-accounts13966
+Ref: #cash-accounts13971
-Node: Balance sheet accounts14150
+Node: Balance sheet accounts14155
-Ref: #balance-sheet-accounts14331
+Ref: #balance-sheet-accounts14336
-Node: Income statement accounts14451
+Node: Income statement accounts14456
-Ref: #income-statement-accounts14637
+Ref: #income-statement-accounts14642
-Node: All accounts14801
+Node: All accounts14806
-Ref: #all-accounts14947
+Ref: #all-accounts14952
-Node: Register15129
+Node: Register15134
-Ref: #register15253
+Ref: #register15258
-Node: Transaction17537
+Node: Transaction17542
-Ref: #transaction17660
+Ref: #transaction17665
-Node: Error19077
+Node: Error19082
-Ref: #error19171
+Ref: #error19176
-Node: TIPS19415
+Node: TIPS19420
-Ref: #tips19514
+Ref: #tips19519
-Node: Watch mode19556
+Node: Watch mode19561
-Ref: #watch-mode19663
+Ref: #watch-mode19668
-Node: Debug output21122
+Node: Debug output21127
-Ref: #debug-output21233
+Ref: #debug-output21238
-Node: ENVIRONMENT21445
+Node: ENVIRONMENT21450
-Ref: #environment21555
+Ref: #environment21560
-Node: BUGS21746
+Node: BUGS21751
-Ref: #bugs21829
+Ref: #bugs21834
 
 End Tag Table
 

hledger-ui/hledger-ui.txt

@@ -535,4 +535,4 @@ LICENSE
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-ui-1.32.99               January 2024                    HLEDGER-UI(1)
+hledger-ui-1.32.99               February 2024                   HLEDGER-UI(1)

hledger-web/.date.m4

@@ -1,2 +1,2 @@
 m4_dnl Date to show in man pages. Updated by "Shake manuals"
-m4_define({{_monthyear_}}, {{January 2024}})m4_dnl
+m4_define({{_monthyear_}}, {{February 2024}})m4_dnl

hledger-web/hledger-web.1

@@ -1,5 +1,5 @@
 
-.TH "HLEDGER\-WEB" "1" "January 2024" "hledger-web-1.32.99 " "hledger User Manuals"
+.TH "HLEDGER\-WEB" "1" "February 2024" "hledger-web-1.32.99 " "hledger User Manuals"
 
 
 

hledger-web/hledger-web.txt

@@ -549,4 +549,4 @@ LICENSE
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-web-1.32.99              January 2024                   HLEDGER-WEB(1)
+hledger-web-1.32.99              February 2024                  HLEDGER-WEB(1)

hledger/.date.m4

@@ -1,2 +1,2 @@
 m4_dnl Date to show in man pages. Updated by "Shake manuals"
-m4_define({{_monthyear_}}, {{January 2024}})m4_dnl
+m4_define({{_monthyear_}}, {{February 2024}})m4_dnl

hledger/hledger.1

@@ -1,6 +1,6 @@
 .\"t
 
-.TH "HLEDGER" "1" "January 2024" "hledger-1.32.99 " "hledger User Manuals"
+.TH "HLEDGER" "1" "February 2024" "hledger-1.32.99 " "hledger User Manuals"
 
 
 
@@ -141,13 +141,13 @@ in any of the supported file formats, which currently are:
 .PP
 .TS
 tab(@);
-lw(12.3n) lw(30.0n) lw(27.7n).
+lw(13.5n) lw(33.0n) lw(23.5n).
 T{
 Reader:
 T}@T{
 Reads:
 T}@T{
-Used for file extensions:
+Automatically used for files with extensions:
 T}
 _
 T{
@@ -174,10 +174,30 @@ T}
 T{
 \f[CR]csv\f[R]
 T}@T{
-CSV/SSV/TSV/character\-separated values, for data import
+Comma or other character separated values, for data import
 T}@T{
-\f[CR].csv\f[R] \f[CR].ssv\f[R] \f[CR].tsv\f[R] \f[CR].csv.rules\f[R]
+\f[CR].csv\f[R]
-\f[CR].ssv.rules\f[R] \f[CR].tsv.rules\f[R]
+T}
+T{
+\f[CR]ssv\f[R]
+T}@T{
+Semicolon separated values
+T}@T{
+\f[CR].ssv\f[R]
+T}
+T{
+\f[CR]tsv\f[R]
+T}@T{
+Tab separated values
+T}@T{
+\f[CR].tsv\f[R]
+T}
+T{
+\f[CR]rules\f[R]
+T}@T{
+CSV/SSV/TSV/other separated values, alternate way
+T}@T{
+\f[CR].rules\f[R]
 T}
 .TE
 .PP
@@ -193,10 +213,10 @@ messages.
 .PP
 You can also force a specific reader/format by prefixing the file path
 with the format and a colon.
-Eg, to read a .dat file as csv format:
+Eg, to read a .dat file containing tab separated values:
 .IP
 .EX
-$ hledger \-f csv:/some/csv\-file.dat stats
+$ hledger \-f tsv:/some/file.dat stats
 .EE
 .SS Standard input
 The file name \f[CR]\-\f[R] means standard input:
@@ -1403,18 +1423,43 @@ write a transaction \[dq]code\[dq], enclosed in parentheses.
 This is a good place to record a check number, or some other important
 transaction id or reference number.
 .SS Description
-A transaction\[aq]s description is the rest of the line following the
+After the date, status mark and/or code fields, the rest of the line (or
-date and status mark (or until a comment begins).
+until a comment is begun with \f[CR];\f[R]) is the transaction\[aq]s
-Sometimes called the \[dq]narration\[dq] in traditional bookkeeping, it
+description.
-can be used for whatever you wish, or left blank.
+Here you can describe the transaction (called the \[dq]narration\[dq] in
-Transaction descriptions can be queried, unlike comments.
+traditional bookkeeping), or you can record a payee/payer name, or you
+can leave it empty.
+.PP
+Transaction descriptions show up in print output and in register
+reports, and can be listed with the descriptions command.
+.PP
+You can query by description with \f[CR]desc:DESCREGEX\f[R], or pivot on
+description with \f[CR]\-\-pivot desc\f[R].
 .SS Payee and note
-You can optionally include a \f[CR]|\f[R] (pipe) character in
+Sometimes people want a dedicated payee/payer field that can be queried
-descriptions to subdivide the description into separate fields for
+and checked more strictly.
-payee/payer name on the left (up to the first \f[CR]|\f[R]) and an
+If you want that, you can write a \f[CR]|\f[R] (pipe) character in the
-additional note field on the right (after the first \f[CR]|\f[R]).
+description.
-This may be worthwhile if you need to do more precise querying and
+This divides it into a \[dq]payee\[dq] field on the left, and a
-pivoting by payee or by note.
+\[dq]note\[dq] field on the right.
+(Either can be empty.)
+.PP
+You can query these with \f[CR]payee:PAYEEREGEX\f[R] and
+\f[CR]note:NOTEREGEX\f[R], list their values with the payees and notes
+commands, or pivot on \f[CR]payee\f[R] or \f[CR]note\f[R].
+.PP
+Note: in transactions with no \f[CR]|\f[R] character, description,
+payee, and note all have the same value.
+Once a \f[CR]|\f[R] is added, they become distinct.
+(If you\[aq]d like to change this behaviour, please propose it on the
+mail list.)
+.PP
+If you want more strict error checking, you can declare the valid payee
+names with \f[CR]payee\f[R] directives, and then enforce these with
+\f[CR]hledger check payees\f[R].
+Note: because of the above, for this you\[aq]ll need to ensure every
+transaction description contains a \f[CR]|\f[R] and therefore a
+checkable payee name (even if it\[aq]s empty).
 .SS Transaction comments
 Text following \f[CR];\f[R], after a transaction description, and/or on
 indented lines immediately below it, form comments for that transaction.
@@ -2017,19 +2062,22 @@ they may contain tags, which are not ignored.
     ; a second comment line for posting 2
 .EE
 .SS Tags
-Tags are a way to add extra labels or labelled data to transactions,
+Tags are a way to add extra labels or data fields to transactions,
 postings, or accounts, which you can then search or pivot on.
 .PP
-They are written as a word (optionally hyphenated) immediately followed
+A tag is a word, optionally hyphenated, immediately followed by a full
-by a full colon, in a transaction or posting or account directive\[aq]s
+colon, in the comment of a transaction, a posting, or an account
-comment.
+directive.
-(This is an exception to the usual rule that things in comments are
+Eg: \f[CR]2024\-01\-01 a transaction   ; foo:\f[R] Note this is an
-ignored.)
+exception to the usual rule that things in comments are ignored.
-You can write multiple tags separated by comma, and/or you can add more
-comment lines and write more tags there.
 .PP
-Here five different tags are recorded: one on the checking account, two
+You can write multiple tags on one line, separated by comma.
-on the transaction, and two on the expenses posting:
+Or you can write each tag on its own comment line (no comma needed in
+this case).
+.PP
+For example, here are five different tags: one on the
+\f[CR]assets:checking\f[R] account, two on the transaction, and two on
+the \f[CR]expenses:food\f[R] posting:
 .IP
 .EX
 account assets:checking         ; accounttag:
@@ -2040,9 +2088,6 @@ account assets:checking         ; accounttag:
     expenses:food           $1  ; postingtag:, another\-posting\-tag:
 .EE
 .PP
-You can list tag names with \f[CR]hledger tags [NAMEREGEX]\f[R], or
-match by tag name with a \f[CR]tag:NAMEREGEX\f[R] query.
-.SS Tag inheritance
 Postings also inherit tags from their transaction and their account.
 And transactions also acquire tags from their postings (and
 postings\[aq] accounts).
@@ -2051,48 +2096,65 @@ tags (by inheriting from the account and transaction), and the
 transaction also has all five tags (by acquiring from the expenses
 posting).
 .SS Tag names
-Tag names are currently not very clearly specified; any sequence of
+Most non\-whitespace characters are allowed in tag names.
-non\-whitespace characters followed by a colon may work.
+Eg \f[CR]😀:\f[R] is a valid tag.
 .PP
-The following tag names are generated by hledger or have special
+You can list the tag names used in your journal with the tags command:
-significance to hledger, so you may want to avoid using them yourself:
+.PD 0
-.IP \[bu] 2
+.P
-\f[CR]balances\f[R] \-\- a balance assertions transaction generated by
+.PD
-close
+\f[CR]hledger tags [NAMEREGEX]\f[R]
-.IP \[bu] 2
-\f[CR]retain\f[R] \-\- a retain earnings transaction generated by close
-.IP \[bu] 2
-\f[CR]start\f[R] \-\- a opening balances, closing balances or balance
-assignment transaction generated by close
-.IP \[bu] 2
-\f[CR]generated\-transaction\f[R] \-\- a transaction generated by
-\-\-forecast
-.IP \[bu] 2
-\f[CR]generated\-posting\f[R] \-\- a posting generated by \-\-auto
-.IP \[bu] 2
-\f[CR]modified\f[R] \-\- a transaction which has had postings added by
-\-\-auto
-.IP \[bu] 2
-\f[CR]type\f[R] \-\- declares an account\[aq]s type in an account
-declaration
-.IP \[bu] 2
-\f[CR]t\f[R] \-\- stores the (user defined, single letter) type of a 15m
-unit of time parsed from timedot format
 .PP
-Some additional tag names with an underscore prefix are used internally
+In commands which use a query, you can match by tag name.
-and not displayed in reports (but can be matched by queries):
+Eg:
-.IP \[bu] 2
+.PD 0
-\f[CR]_generated\-transaction\f[R]
+.P
-.IP \[bu] 2
+.PD
-\f[CR]_generated\-posting\f[R]
+\f[CR]hledger print tag:NAMEREGEX\f[R]
-.IP \[bu] 2
+.PP
-\f[CR]_modified\f[R]
+You can declare valid tag names with the tag directive and then check
-.IP \[bu] 2
+them with the check command.
-\f[CR]_conversion\-matched\f[R]
+.SS Special tags
+Some tag names have special significance to hledger.
+There\[aq]s not much harm in using them yourself, but some could produce
+an error message, particularly the \f[CR]date:\f[R] tag.
+They are explained elsewhere, but here is a quick list for reference:
+.PP
+Tags you can set to influence hledger\[aq]s behaviour:
+.IP
+.EX
+ date                   \-\- overrides a posting\[aq]s date
+ date2                  \-\- overrides a posting\[aq]s secondary date
+ type                   \-\- declares an account\[aq]s type
+.EE
+.PP
+Tags hledger adds to indicate generated data:
+.IP
+.EX
+ t                      \-\- appears on postings generated by timedot letters
+ assert                 \-\- appears on txns generated by close \-\-assert
+ retain                 \-\- appears on txns generated by close \-\-retain
+ start                  \-\- appears on txns generated by close \-\-migrate/\-\-close/\-\-open/\-\-assign
+ 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)
+Not displayed, but queryable:
+ _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
+Tags hledger uses internally:
+.IP
+.EX
+ _conversion\-matched    \-\- exists on postings which have been matched with a nearby \[at]/\[at]\[at] cost annotation
+.EE
 .SS Tag values
 Tags can have a value, which is any text after the colon up until a
-comma or end of line (with surrounding whitespace removed).
+comma or end of line, with surrounding whitespace removed.
-Note this means that hledger tag values can not contain commas.
+Ending at comma allows us to write multiple tags on one line, but also
+means that tag values can not contain commas.
+.PP
 Eg in the following posting, the three tags\[aq] values are \[dq]value
 1\[dq], \[dq]value 2\[dq], and \[dq]\[dq] (empty) respectively:
 .IP
@@ -2100,14 +2162,21 @@ Eg in the following posting, the three tags\[aq] values are \[dq]value
     expenses:food   $10    ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz
 .EE
 .PP
-Note that tags can be repeated, and are additive rather than overriding:
+Multiple tags with the same name are additive rather than overriding:
 when the same tag name is seen again with a new value, the new
 name:value pair is added to the tags.
-(It is not possible to override a tag\[aq]s value or remove a tag.)
+It is not possible to override a previous tag\[aq]s value or remove a
+tag.
 .PP
-You can list a tag\[aq]s values with
+You can list all the values used for a particular tag in the journal
-\f[CR]hledger tags TAGNAME \-\-values\f[R], or match by tag value with a
+with
-\f[CR]tag:NAMEREGEX=VALUEREGEX\f[R] query.
+.PD 0
+.P
+.PD
+\f[CR]hledger tags TAGNAME \-\-values\f[R]
+.PP
+You can match on tag values with a query like
+\f[CR]tag:NAMEREGEX=VALUEREGEX\f[R]
 .SS Directives
 Besides transactions, there is something else you can put in a
 \f[CR]journal\f[R] file: directives.
@@ -2370,36 +2439,35 @@ Though not required, these declarations can provide several benefits:
 They can document your intended chart of accounts, providing a
 reference.
 .IP \[bu] 2
-In strict mode, they restrict which accounts may be posted to by
-transactions, which helps detect typos.
-.IP \[bu] 2
-They control account display order in reports, allowing non\-alphabetic
-sorting (eg Revenues to appear above Expenses).
-.IP \[bu] 2
-They help with account name completion (in hledger add, hledger\-web,
-hledger\-iadd, ledger\-mode, etc.)
-.IP \[bu] 2
 They can store additional account information as comments, or as tags
 which can be used to filter or pivot reports.
 .IP \[bu] 2
+They can restrict which accounts may be posted to by transactions, eg in
+strict mode, which helps prevent errors.
+.IP \[bu] 2
+They influence 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), affecting reports like balancesheet and
+equity, revenue, expense), enabling reports like balancesheet and
 incomestatement.
+.IP \[bu] 2
+They help with account name completion (in hledger add, hledger\-web,
+hledger\-iadd, ledger\-mode, etc.)
 .PP
 They are written as the word \f[CR]account\f[R] followed by a
-hledger\-style account name, eg:
+hledger\-style account name.
+Eg:
 .IP
 .EX
 account assets:bank:checking
 .EE
 .PP
-Note, however, that accounts declared in account directives are not
+Ledger\-style indented subdirectives are also accepted, but ignored:
-allowed to have surrounding brackets and parentheses, unlike accounts
-used in postings.
-So the following journal will not parse:
 .IP
 .EX
-account (assets:bank:checking)
+account assets:bank:checking
+  format subdirective  ; currently ignored
 .EE
 .SS Account comments
 Text following \f[B]two or more spaces\f[R] and \f[CR];\f[R] at the end
@@ -2415,14 +2483,6 @@ account assets:bank:checking    ; same\-line comment, at least 2 spaces before t
   ; next\-line comment
   ; some tags \- type:A, acctnum:12345
 .EE
-.SS Account subdirectives
-Ledger\-style indented subdirectives are also accepted, but currently
-ignored:
-.IP
-.EX
-account assets:bank:checking
-  format subdirective is ignored
-.EE
 .SS Account error checking
 By default, accounts need not be declared; they come into existence when
 a posting references them.
@@ -2453,10 +2513,9 @@ It\[aq]s currently not possible to declare \[dq]all possible
 subaccounts\[dq] with a wildcard; every account posted to must be
 declared.
 .SS Account display order
-The order in which account directives are written influences the order
+Account directives also cause hledger to display accounts in a
-in which accounts appear in reports, hledger\-ui, hledger\-web etc.
+particular order, not just alphabetically.
-By default accounts appear in alphabetical order, but if you add these
+Eg, here is a conventional ordering for the top\-level accounts:
-account directives to the journal file:
 .IP
 .EX
 account assets
@@ -2466,10 +2525,10 @@ account revenues
 account expenses
 .EE
 .PP
-those accounts will be displayed in declaration order:
+Now hledger displays them in that order:
 .IP
 .EX
-$ hledger accounts \-1
+$ hledger accounts
 assets
 liabilities
 equity
@@ -2477,27 +2536,23 @@ revenues
 expenses
 .EE
 .PP
-Any undeclared accounts are displayed last, in alphabetical order.
+If there are undeclared accounts, those will be displayed last, in
+alphabetical order.
 .PP
-Sorting is done at each level of the account tree, within each group of
+Sorting is done within each group of sibling accounts, at each level of
-sibling accounts under the same parent.
+the account tree.
-And currently, this directive:
+Eg, a declaration like \f[CR]account parent:child\f[R] influences
-.IP
+\f[CR]child\f[R]\[aq]s position among its siblings.
-.EX
-account other:zoo
-.EE
 .PP
-would influence the position of \f[CR]zoo\f[R] among
+Note, it does not affect \f[CR]parent\f[R]\[aq]s position; for that, you
-\f[CR]other\f[R]\[aq]s subaccounts, but not the position of
+need an \f[CR]account parent\f[R] declaration.
-\f[CR]other\f[R] among the top\-level accounts.
+.PP
-This means:
+Sibling accounts are always displayed together; hledger won\[aq]t
-.IP \[bu] 2
+display \f[CR]x:y\f[R] in between \f[CR]a:b\f[R] and \f[CR]a:c\f[R].
-you will sometimes declare parent accounts (eg \f[CR]account other\f[R]
+.PP
-above) that you don\[aq]t intend to post to, just to customize their
+An account directive both declares an account as a valid posting target,
-display order
+and declares its display order; you can\[aq]t easily do one without the
-.IP \[bu] 2
+other.
-sibling accounts stay together (you couldn\[aq]t display \f[CR]x:y\f[R]
-in between \f[CR]a:b\f[R] and \f[CR]a:c\f[R]).
 .SS Account types
 hledger knows that accounts come in several types: assets, liabilities,
 expenses and so on.
@@ -2507,9 +2562,8 @@ filtering by account type with the \f[CR]type:\f[R] query.
 As a convenience, hledger will detect these account types automatically
 if you are using common english\-language top\-level account names
 (described below).
-But generally we recommend you declare types explicitly, by adding a
+But it\[aq]s more robust to declare accounts\[aq] types explicitly, by
-\f[CR]type:\f[R] tag to your top\-level account directives.
+adding \f[CR]type:\f[R] tags to their 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[CR]A\f[R] or \f[CR]Asset\f[R] (things you own)
@@ -2533,6 +2587,7 @@ assets for the cashflow report)
 \f[CR]V\f[R] or \f[CR]Conversion\f[R] (a subtype of Equity, for
 conversions (see Cost reporting).)
 .PP
+Subaccounts inherit their parent\[aq]s type, or they can override it.
 Here is a typical set of account type declarations:
 .IP
 .EX
@@ -3017,8 +3072,8 @@ Any indented subdirectives are currently ignored.
 The \[dq]tags\[dq] check will report an error if any undeclared tag name
 is used.
 It is quite easy to accidentally create a tag through normal use of
-colons in comments(#comments]; if you want to prevent this, you can
+colons in comments; if you want to prevent this, you can declare and
-declare and check your tags .
+check your tags .
 .SS Periodic transactions
 The \f[CR]\[ti]\f[R] directive declares a \[dq]periodic rule\[dq] which
 generates temporary extra transactions, usually recurring at some

hledger/hledger.txt

@@ -97,17 +97,21 @@ Input
        Usually the data file is in hledger's journal format, but it can be  in
        any of the supported file formats, which currently are:
 
-       Reader:        Reads:                           Used for file extensions:
+       Reader:         Reads:                              Automatically  used for
+                                                           files with extensions:
        -----------------------------------------------------------------------------
-       journal        hledger journal files and some   .journal .j .hledger .ledger
+       journal         hledger journal  files  and  some   .journal   .j  .hledger
-                      Ledger  journals, for transac-
+                       Ledger journals, for transactions   .ledger
-                      tions
+       timeclock       timeclock files, for precise time   .timeclock
-       timeclock      timeclock files,  for  precise   .timeclock
+                       logging
-                      time logging
        timedot         timedot  files,  for  approximate   .timedot
                        time logging
-       csv            CSV/SSV/TSV/character-sepa-      .csv  .ssv  .tsv  .csv.rules
+       csv             Comma  or  other  character sepa-   .csv
-                      rated values, for data import    .ssv.rules .tsv.rules
+                       rated values, for data import
+       ssv             Semicolon separated values          .ssv
+       tsv             Tab separated values                .tsv
+       rules           CSV/SSV/TSV/other separated  val-   .rules
+                       ues, alternate way
 
        These formats are described in more detail below.
 
@@ -118,9 +122,10 @@ Input
        relevant error messages.
 
        You can also force a specific reader/format by prefixing the file  path
-       with the format and a colon.  Eg, to read a .dat file as csv format:
+       with  the  format  and a colon.  Eg, to read a .dat file containing tab
+       separated values:
 
-              $ hledger -f csv:/some/csv-file.dat stats
+              $ hledger -f tsv:/some/file.dat stats
 
    Standard input
        The file name - means standard input:
@@ -1055,18 +1060,38 @@ Journal
        or reference number.
 
    Description
-       A  transaction's description is the rest of the line following the date
+       After  the  date,  status mark and/or code fields, the rest of the line
-       and status mark (or until a  comment  begins).   Sometimes  called  the
+       (or until a comment is begun with ;) is the transaction's  description.
-       "narration" in traditional bookkeeping, it can be used for whatever you
+       Here you can describe the transaction (called the "narration" in tradi-
-       wish,  or  left blank.  Transaction descriptions can be queried, unlike
+       tional  bookkeeping),  or you can record a payee/payer name, or you can
-       comments.
+       leave it empty.
+
+       Transaction descriptions show up in print output and  in  register  re-
+       ports, and can be listed with the descriptions command.
+
+       You  can query by description with desc:DESCREGEX, or pivot on descrip-
+       tion with --pivot desc.
 
    Payee and note
-       You can optionally include a | (pipe) character in descriptions to sub-
+       Sometimes people want a dedicated payee/payer field that can be queried
-       divide the description into separate fields for payee/payer name on the
+       and checked more strictly.  If you want that, you can write a |  (pipe)
-       left (up to the first |) and an additional note field on the right (af-
+       character  in the description.  This divides it into a "payee" field on
-       ter the first |).  This may be worthwhile if you need to do  more  pre-
+       the left, and a "note" field on the right.  (Either can be empty.)
-       cise querying and pivoting by payee or by note.
+
+       You can query these  with  payee:PAYEEREGEX  and  note:NOTEREGEX,  list
+       their  values  with the payees and notes commands, or pivot on payee or
+       note.
+
+       Note: in transactions with no | character, description, payee, and note
+       all have the same value.  Once a | is added, they become distinct.  (If
+       you'd like to change this behaviour, please  propose  it  on  the  mail
+       list.)
+
+       If you want more strict error checking, you can declare the valid payee
+       names  with payee directives, and then enforce these with hledger check
+       payees.  Note: because of the above, for this  you'll  need  to  ensure
+       every  transaction  description  contains a | and therefore a checkable
+       payee name (even if it's empty).
 
    Transaction comments
        Text following ;, after a transaction description, and/or  on  indented
@@ -1584,17 +1609,20 @@ Journal
                   ; a second comment line for posting 2
 
    Tags
-       Tags  are  a  way to add extra labels or labelled data to transactions,
+       Tags are a way to add extra labels  or  data  fields  to  transactions,
        postings, or accounts, which you can then search or pivot on.
 
-       They are written as a word (optionally hyphenated) immediately followed
+       A  tag is a word, optionally hyphenated, immediately followed by a full
-       by a full colon, in a transaction or  posting  or  account  directive's
+       colon, in the comment of a transaction, a posting, or an account direc-
-       comment.   (This  is an exception to the usual rule that things in com-
+       tive.  Eg: 2024-01-01 a transaction   ; foo: Note this is an  exception
-       ments are ignored.)  You can write multiple tags  separated  by  comma,
+       to the usual rule that things in comments are ignored.
-       and/or you can add more comment lines and write more tags there.
 
-       Here five different tags are recorded: one on the checking account, two
+       You  can  write  multiple tags on one line, separated by comma.  Or you
-       on the transaction, and two on the expenses posting:
+       can write each tag on its own comment line (no  comma  needed  in  this
+       case).
+
+       For  example,  here are five different tags: one on the assets:checking
+       account, two on the transaction, and two on the expenses:food posting:
 
               account assets:checking         ; accounttag:
 
@@ -1603,10 +1631,6 @@ Journal
                   assets:checking        $-1
                   expenses:food           $1  ; postingtag:, another-posting-tag:
 
-       You  can  list tag names with hledger tags [NAMEREGEX], or match by tag
-       name with a tag:NAMEREGEX query.
-
-   Tag inheritance
        Postings also inherit tags from their transaction  and  their  account.
        And  transactions  also acquire tags from their postings (and postings'
        accounts).  So in the example above, the expenses  posting  effectively
@@ -1615,57 +1639,69 @@ Journal
        posting).
 
    Tag names
-       Tag names are currently not very clearly  specified;  any  sequence  of
+       Most non-whitespace characters are allowed in tag names.   Eg  :  is  a
-       non-whitespace characters followed by a colon may work.
+       valid tag.
 
-       The  following  tag names are generated by hledger or have special sig-
+       You can list the tag names used in your journal with the tags command:
-       nificance to hledger, so you may want to avoid using them yourself:
+       hledger tags [NAMEREGEX]
 
-       o balances -- a balance assertions transaction generated by close
+       In commands which use a query, you can match by tag name.  Eg:
+       hledger print tag:NAMEREGEX
 
-       o retain -- a retain earnings transaction generated by close
+       You  can  declare valid tag names with the tag directive and then check
+       them with the check command.
 
-       o start -- a opening balances, closing balances or  balance  assignment
+   Special tags
-         transaction generated by close
+       Some tag names have special significance to hledger.  There's not  much
+       harm  in  using them yourself, but some could produce an error message,
+       particularly the date: tag.  They are explained elsewhere, but here  is
+       a quick list for reference:
 
-       o generated-transaction -- a transaction generated by --forecast
+       Tags you can set to influence hledger's behaviour:
 
-       o generated-posting -- a posting generated by --auto
+               date                   -- overrides a posting's date
+               date2                  -- overrides a posting's secondary date
+               type                   -- declares an account's type
 
-       o modified -- a transaction which has had postings added by --auto
+       Tags hledger adds to indicate generated data:
 
-       o type -- declares an account's type in an account declaration
+               t                      -- appears on postings generated by timedot letters
+               assert                 -- appears on txns generated by close --assert
+               retain                 -- appears on txns generated by close --retain
+               start                  -- appears on txns generated by close --migrate/--close/--open/--assign
+               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)
+              Not displayed, but queryable:
+               _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)
 
-       o t  --  stores the (user defined, single letter) type of a 15m unit of
+       Tags hledger uses internally:
-         time parsed from timedot format
 
-       Some additional tag names with an underscore prefix are used internally
+               _conversion-matched    -- exists on postings which have been matched with a nearby @/@@ cost annotation
-       and not displayed in reports (but can be matched by queries):
-
-       o _generated-transaction
-
-       o _generated-posting
-
-       o _modified
-
-       o _conversion-matched
 
    Tag values
        Tags  can  have  a  value, which is any text after the colon up until a
-       comma  or end of line (with surrounding whitespace removed).  Note this
+       comma or end of line, with surrounding whitespace removed.   Ending  at
-       means that hledger tag values can not contain commas.  Eg in  the  fol-
+       comma allows us to write multiple tags on one line, but also means that
-       lowing posting, the three tags' values are "value 1", "value 2", and ""
+       tag values can not contain commas.
-       (empty) respectively:
+
+       Eg  in  the  following  posting,  the three tags' values are "value 1",
+       "value 2", and "" (empty) respectively:
 
                   expenses:food   $10    ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz
 
-       Note  that  tags can be repeated, and are additive rather than overrid-
+       Multiple tags with the same name are additive rather  than  overriding:
-       ing: when the same tag name is seen again with a  new  value,  the  new
+       when  the  same  tag  name  is  seen  again  with  a new value, the new
-       name:value  pair is added to the tags.  (It is not possible to override
+       name:value pair is added to the tags.  It is not possible to override a
-       a tag's value or remove a tag.)
+       previous tag's value or remove a tag.
 
-       You can list a tag's values with  hledger  tags  TAGNAME  --values,  or
+       You can list all the values used for a particular tag  in  the  journal
-       match by tag value with a tag:NAMEREGEX=VALUEREGEX query.
+       with
+       hledger tags TAGNAME --values
+
+       You can match on tag values with a query like tag:NAMEREGEX=VALUEREGEX
 
    Directives
        Besides  transactions, there is something else you can put in a journal
@@ -1775,32 +1811,31 @@ Journal
        o They can document your intended chart of accounts, providing a refer-
          ence.
 
-       o In strict mode, they restrict which accounts  may  be  posted  to  by
+       o They can store additional account information as comments, or as tags
-         transactions, which helps detect typos.
+         which can be used to filter or pivot reports.
 
-       o They  control  account  display order in reports, allowing non-alpha-
+       o They can restrict which accounts may be posted to by transactions, eg
+         in strict mode, which helps prevent errors.
+
+       o They influence account display order in reports, allowing  non-alpha-
          betic sorting (eg Revenues to appear above Expenses).
 
+       o They  can  help  hledger know your accounts' types (asset, liability,
+         equity, revenue, expense), enabling reports like balancesheet and in-
+         comestatement.
+
        o They help with account name completion (in hledger add,  hledger-web,
          hledger-iadd, ledger-mode, etc.)
 
-       o They can store additional account information as comments, or as tags
-         which can be used to filter or pivot reports.
-
-       o They  can  help  hledger know your accounts' types (asset, liability,
-         equity, revenue, expense), affecting reports  like  balancesheet  and
-         incomestatement.
-
        They  are  written  as the word account followed by a hledger-style ac-
-       count name, eg:
+       count name.  Eg:
 
               account assets:bank:checking
 
-       Note, however, that accounts declared in account directives are not al-
+       Ledger-style indented subdirectives are also accepted, but ignored:
-       lowed to have surrounding brackets  and  parentheses,  unlike  accounts
-       used in postings.  So the following journal will not parse:
 
-              account (assets:bank:checking)
+              account assets:bank:checking
+                format subdirective  ; currently ignored
 
    Account comments
        Text following two or more spaces and ; at the end of an account direc-
@@ -1815,13 +1850,6 @@ Journal
                 ; next-line comment
                 ; some tags - type:A, acctnum:12345
 
-   Account subdirectives
-       Ledger-style indented subdirectives are also  accepted,  but  currently
-       ignored:
-
-              account assets:bank:checking
-                format subdirective is ignored
-
    Account error checking
        By  default,  accounts  need  not be declared; they come into existence
        when a posting references them.   This  is  convenient,  but  it  means
@@ -1849,10 +1877,9 @@ Journal
          with a wildcard; every account posted to must be declared.
 
    Account display order
-       The order in which account directives are written influences the  order
+       Account directives also cause hledger to display accounts in a particu-
-       in  which  accounts appear in reports, hledger-ui, hledger-web etc.  By
+       lar order, not just alphabetically.  Eg, here is a conventional  order-
-       default accounts appear in alphabetical order, but if you add these ac-
+       ing for the top-level accounts:
-       count directives to the journal file:
 
               account assets
               account liabilities
@@ -1860,31 +1887,31 @@ Journal
               account revenues
               account expenses
 
-       those accounts will be displayed in declaration order:
+       Now hledger displays them in that order:
 
-              $ hledger accounts -1
+              $ hledger accounts
               assets
               liabilities
               equity
               revenues
               expenses
 
-       Any undeclared accounts are displayed last, in alphabetical order.
+       If  there are undeclared accounts, those will be displayed last, in al-
+       phabetical order.
 
-       Sorting is done at each level of the account tree, within each group of
+       Sorting is done within each group of sibling accounts, at each level of
-       sibling accounts under the same parent.  And currently, this directive:
+       the account tree.  Eg, a declaration like account  parent:child  influ-
+       ences child's position among its siblings.
 
-              account other:zoo
+       Note,  it  does not affect parent's position; for that, you need an ac-
+       count parent declaration.
 
-       would influence the position of zoo among other's subaccounts, but  not
+       Sibling accounts are always displayed together; hledger  won't  display
-       the position of other among the top-level accounts.  This means:
+       x:y in between a:b and a:c.
 
-       o you  will  sometimes declare parent accounts (eg account other above)
+       An  account  directive both declares an account as a valid posting tar-
-         that you don't intend to post to, just to customize their display or-
+       get, and declares its display order; you can't easily  do  one  without
-         der
+       the other.
-
-       o sibling accounts stay together (you couldn't display x:y  in  between
-         a:b and a:c).
 
    Account types
        hledger knows that accounts come in several types: assets, liabilities,
@@ -1893,10 +1920,9 @@ Journal
 
        As a convenience, hledger will detect these account types automatically
        if you are using common english-language top-level account  names  (de-
-       scribed  below).   But generally we recommend you declare types explic-
+       scribed  below).   But  it's more robust to declare accounts' types ex-
-       itly, by adding a type: tag to your top-level account directives.  Sub-
+       plicitly, by adding type: tags to their account directives.  The  tag's
-       accounts will inherit the type of their parent.  The tag's value should
+       value should be one of the five main account types:
-       be one of the five main account types:
 
        o A or Asset (things you own)
 
@@ -1918,7 +1944,8 @@ Journal
        o V  or  Conversion (a subtype of Equity, for conversions (see Cost re-
          porting).)
 
-       Here is a typical set of account type declarations:
+       Subaccounts inherit their parent's type, or they can override it.  Here
+       is a typical set of account type declarations:
 
               account assets             ; type: A
               account liabilities        ; type: L
@@ -2328,8 +2355,8 @@ Journal
 
        The "tags" check will report an error if any  undeclared  tag  name  is
        used.  It is quite easy to accidentally create a tag through normal use
-       of colons in comments(#comments]; if you want to prevent this, you  can
+       of colons in comments; if you want to prevent this, you can declare and
-       declare and check your tags .
+       check your tags .
 
    Periodic transactions
        The  ~  directive  declares a "periodic rule" which generates temporary
@@ -8930,4 +8957,4 @@ LICENSE
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-1.32.99                  January 2024                       HLEDGER(1)
+hledger-1.32.99                  February 2024                      HLEDGER(1)