;doc: update embedded manuals

hledger-lib/.date.m4

@@ -1,2 +1,2 @@
 m4_dnl Date to show in man pages. Updated by "Shake manuals"
-m4_define({{_monthyear_}}, {{September 2025}})m4_dnl
+m4_define({{_monthyear_}}, {{October 2025}})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_}}, {{September 2025}})m4_dnl
+m4_define({{_monthyear_}}, {{October 2025}})m4_dnl

hledger-ui/hledger-ui.1

@@ -1,5 +1,5 @@
 
-.TH "HLEDGER\-UI" "1" "September 2025" "hledger-ui-1.50.99 " "hledger User Manuals"
+.TH "HLEDGER\-UI" "1" "October 2025" "hledger-ui-1.50.99 " "hledger User Manuals"
 
 
 
@@ -250,6 +250,9 @@ screen and any previous screens.
 \f[CR]I\f[R] toggles balance assertion checking.
 Disabling balance assertions temporarily can be useful for
 troubleshooting.
+(If hledger\-ui was started with a \f[CR]\-\-pivot\f[R] option,
+re\-enabling balance assertions with the \f[CR]I\f[R] key also reloads
+the journal, like \f[CR]g\f[R].)
 .PP
 \f[CR]a\f[R] runs command\-line hledger\[aq]s add command, and reloads
 the updated file.
@@ -442,10 +445,6 @@ On some unix systems, increasing fs.inotify.max_user_watches or
 fs.file\-max parameters in /etc/sysctl.conf might help.
 (#836)
 .IP \[bu] 2
-It may not detect file changes made by certain tools, such as Jetbrains
-IDEs or gedit.
-(#1617)
-.IP \[bu] 2
 It may not detect changes made from outside a virtual machine, ie by an
 editor running on the host system.
 .IP \[bu] 2

hledger-ui/hledger-ui.info

@@ -256,7 +256,9 @@ any previous screens.  (With large files, this could cause a noticeable
 pause.)
 
    'I' toggles balance assertion checking.  Disabling balance assertions
-temporarily can be useful for troubleshooting.
+temporarily can be useful for troubleshooting.  (If hledger-ui was
+started with a '--pivot' option, re-enabling balance assertions with the
+'I' key also reloads the journal, like 'g'.)
 
    'a' runs command-line hledger's add command, and reloads the updated
 file.  This allows some basic data entry.
@@ -503,8 +505,6 @@ _However._  There are limitations/unresolved bugs with '--watch':
      configuration.  On some unix systems, increasing
      fs.inotify.max_user_watches or fs.file-max parameters in
      /etc/sysctl.conf might help.  (#836)
-   * It may not detect file changes made by certain tools, such as
-     Jetbrains IDEs or gedit.  (#1617)
    * It may not detect changes made from outside a virtual machine, ie
      by an editor running on the host system.
    * It may not detect file changes on certain less common filesystems.
@@ -558,19 +558,19 @@ Node: Top221
 Node: OPTIONS1869
 Node: MOUSE8755
 Node: KEYS9087
-Node: SCREENS14091
+Node: SCREENS14229
-Node: Menu screen14831
+Node: Menu screen14969
-Node: Cash accounts screen15147
+Node: Cash accounts screen15285
-Node: Balance sheet accounts screen15508
+Node: Balance sheet accounts screen15646
-Node: Income statement accounts screen15844
+Node: Income statement accounts screen15982
-Node: All accounts screen16229
+Node: All accounts screen16367
-Node: Register screen16592
+Node: Register screen16730
-Node: Transaction screen19035
+Node: Transaction screen19173
-Node: Error screen20215
+Node: Error screen20353
-Node: WATCH MODE20581
+Node: WATCH MODE20719
-Node: --watch problems21479
+Node: --watch problems21617
-Node: ENVIRONMENT22832
+Node: ENVIRONMENT22864
-Node: BUGS23065
+Node: BUGS23097
 
 End Tag Table
 

hledger-ui/hledger-ui.txt

@@ -223,7 +223,9 @@ KEYS
        pause.)
 
        I  toggles  balance  assertion  checking.  Disabling balance assertions
-       temporarily can be useful for troubleshooting.
+       temporarily can be useful  for  troubleshooting.   (If  hledger-ui  was
+       started  with a --pivot option, re-enabling balance assertions with the
+       I key also reloads the journal, like g.)
 
        a runs command-line hledger's add  command,  and  reloads  the  updated
        file.  This allows some basic data entry.
@@ -398,9 +400,6 @@ WATCH MODE
          tify.max_user_watches or fs.file-max parameters  in  /etc/sysctl.conf
          might help.  (#836)
 
-       o It  may  not  detect file changes made by certain tools, such as Jet-
-         brains IDEs or gedit.  (#1617)
-
        o It  may not detect changes made from outside a virtual machine, ie by
          an editor running on the host system.
 
@@ -461,4 +460,4 @@ LICENSE
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-ui-1.50.99              September 2025                   HLEDGER-UI(1)
+hledger-ui-1.50.99               October 2025                    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_}}, {{September 2025}})m4_dnl
+m4_define({{_monthyear_}}, {{October 2025}})m4_dnl

hledger-web/hledger-web.1

@@ -1,5 +1,5 @@
 
-.TH "HLEDGER\-WEB" "1" "September 2025" "hledger-web-1.50.99 " "hledger User Manuals"
+.TH "HLEDGER\-WEB" "1" "October 2025" "hledger-web-1.50.99 " "hledger User Manuals"
 
 
 

hledger-web/hledger-web.txt

@@ -480,4 +480,4 @@ LICENSE
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-web-1.50.99             September 2025                  HLEDGER-WEB(1)
+hledger-web-1.50.99              October 2025                   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_}}, {{September 2025}})m4_dnl
+m4_define({{_monthyear_}}, {{October 2025}})m4_dnl

hledger/hledger.1

@@ -1,6 +1,6 @@
 .\"t
 
-.TH "HLEDGER" "1" "September 2025" "hledger-1.50.99 " "hledger User Manuals"
+.TH "HLEDGER" "1" "October 2025" "hledger-1.50.99 " "hledger User Manuals"
 
 
 
@@ -458,157 +458,138 @@ Some queries can be expressed either with options or with arguments.
 Below are more tips for using the command line interface \- feel free to
 skip these until you need them.
 .SS Special characters
-Here we touch on shell escaping/quoting rules, and give some examples.
+In commands you type at the command line, certain characters have
-This is a slightly complicated topic which you may not need at first,
+special meaning and sometimes need to be \[dq]escaped\[dq] or
-but you should be aware of it, so you can return here when needed.
+\[dq]quoted\[dq], by prefixing backslashes or enclosing in quotes.
 .PP
 If you are able to minimise the use of special characters in your data,
-you won\[aq]t need escaping as much, and your command lines will be
+you won\[aq]t have to deal with this as much.
-simpler.
+For example, you could use hyphen \f[CR]\-\f[R] or underscore
-For example, avoiding spaces in account names, and using an ISO\-4217
+\f[CR]_\f[R] instead of spaces in account names, and you could use the
-currency code like \f[CR]USD\f[R] instead of the \f[CR]$\f[R] currency
+\f[CR]USD\f[R] currency code instead of the \f[CR]$\f[R] currency symbol
-symbol, can be helpful.
+in amounts.
 .PP
-But if you want to use spaced account names and \f[CR]$\f[R], go right
+But if you prefer to use spaced account names and \f[CR]$\f[R], it\[aq]s
-ahead; escaping isn\[aq]t a big deal.
+fine.
+Just be aware of this topic so you can check this doc when needed.
+(These examples are mostly tested on unix; some details might need to be
+adapted if you\[aq]re on Windows.)
 .SS Escaping shell special characters
-At the command line, characters which have special meaning for your
+These are some characters which may have special meaning to your shell
-shell must be \[dq]shell\-escaped\[dq] (AKA \[dq]quoted\[dq]) if you
+(the program which interprets command lines):
-want hledger to see them.
+.IP \[bu] 2
-Often these include space, \f[CR]<\f[R], \f[CR]>\f[R], \f[CR](\f[R],
+SPACE, \f[CR]<\f[R], \f[CR]>\f[R], \f[CR](\f[R], \f[CR])\f[R],
-\f[CR])\f[R], \f[CR]|\f[R], \f[CR]\[rs]\f[R], \f[CR]$\f[R] and/or
+\f[CR]|\f[R], \f[CR]\[rs]\f[R], \f[CR]%\f[R]
-\f[CR]%\f[R].
+.IP \[bu] 2
+\f[CR]$\f[R] if followed by a word character
 .PP
-For example, to match an account name containing the phrase \[dq]credit
+So for example, to match an account name containing spaces, like
-card\[dq], don\[aq]t write this:
+\[dq]credit card\[dq], don\[aq]t write:
 .IP
 .EX
 $ hledger register credit card
 .EE
 .PP
-In that command, \[dq]credit\[dq] and \[dq]card\[dq] are treated as
+Instead, enclose the name in single quotes:
-separate query arguments (described below), so this would match accounts
-containing either word.
-Instead, enclose the phrase in double or single quotes:
 .IP
 .EX
-$ hledger register \[dq]credit card\[dq]
+$ hledger register \[aq]credit card\[aq]
 .EE
 .PP
-In Unix shells, writing a backslash before the character can also work.
+On unix or in Windows powershell, if you use double quotes your shell
-Eg:
+will silently treat \f[CR]$\f[R] as variable interpolation.
+So you should probably avoid double quotes, unless you want that
+behaviour, eg in a script:
+.IP
+.EX
+$ hledger register \[dq]assets:$SOMEACCT\[dq]
+.EE
+.PP
+But in an older Windows CMD.EXE window, you must use double quotes:
+.IP
+.EX
+C:\[rs]Users\[rs]Me> hledger register \[dq]credit card\[dq]
+.EE
+.PP
+On unix or in Windows powershell, as an alternative to quotes you can
+write a backslash before each special character:
 .IP
 .EX
 $ hledger register credit\[rs] card
 .EE
 .PP
-Some shell characters still have a special meaning inside double quotes,
+Finally, since hledger\[aq]s query arguments are regular expressions
-such as the dollar sign (\f[CR]$\f[R]).
+(described below), you could also fill that gap with \f[CR].\f[R] which
-Eg in \f[CR]\[dq]assets:$account\[dq]\f[R], the bash shell would replace
+matches any character:
-\f[CR]$account\f[R] with the value of a shell variable with that name.
-When you don\[aq]t want that, use single quotes, which escape more
-strongly:
 .IP
 .EX
-$ hledger balance \[aq]assets:$account\[aq]
+$ hledger register credit.card
 .EE
-.SS Escaping on Windows
-If you are using hledger in a Powershell or Command window on Microsoft
-Windows, the escaping rules are different:
-.IP \[bu] 2
-In a Powershell window (\f[CR]powershell\f[R], blue background), you
-must use double quotes or single quotes (not backslash).
-.IP \[bu] 2
-In a Command window (\f[CR]cmd\f[R], black background), you must use
-double quotes (not single quotes or backslash).
-.PP
-The next two sections were written for Unix\-like shells, so might need
-to be adapted if you\[aq]re using \f[CR]cmd\f[R] or
-\f[CR]powershell\f[R].
-(Edits welcome.)
 .SS Escaping regular expression special characters
-Many hledger arguments are regular expressions (described below), and
+Some characters also have special meaning in regular expressions, which
-these too have characters which cause special effects.
+hledger\[aq]s arguments often are.
-Some of those characters are \f[CR].\f[R], \f[CR]\[ha]\f[R],
+Those include:
-\f[CR]$\f[R], \f[CR][\f[R], \f[CR]]\f[R], \f[CR](\f[R], \f[CR])\f[R],
+.IP \[bu] 2
-\f[CR]|\f[R], and \f[CR]\[rs]\f[R].
+\f[CR].\f[R], \f[CR]\[ha]\f[R], \f[CR]$\f[R], \f[CR][\f[R],
-When you don\[aq]t want these to cause special effects, you can
+\f[CR]]\f[R], \f[CR](\f[R], \f[CR])\f[R], \f[CR]|\f[R], \f[CR]\[rs]\f[R]
-\[dq]regex\-escape\[dq] them by writing \f[CR]\[rs]\f[R] (a backslash)
-before them.
-But since backslash is also special to the shell, you may need to also
-shell\-escape the backslashes.
 .PP
-Eg, in the bash shell, to match a literal \f[CR]$\f[R] sign, you could
+To escape one of these, write \f[CR]\[rs]\f[R] before it.
-write:
+But note this is in addition to the shell escaping above.
+So for characters which are special to both shell and regular
+expressions, like \f[CR]\[rs]\f[R] and \f[CR]$\f[R], you will sometimes
+need two levels of escaping.
+.PP
+For example, a balance report that uses a \f[CR]cur:\f[R] query
+restricting it to just the $ currency, should be written like this:
 .IP
 .EX
 $ hledger balance cur:\[rs]\[rs]$
 .EE
 .PP
-or:
+Explanation:
+.IP "1." 3
+Add a backslash \f[CR]\[rs]\f[R] before the dollar sign \f[CR]$\f[R] to
+protect it from regular expressions (so it will be matched literally
+with no special meaning).
+.IP "2." 3
+Add another backslash before that backslash, to protect it from the
+shell (so the shell won\[aq]t consume it).
+.IP "3." 3
+\f[CR]$\f[R] doesn\[aq]t need to be protected from the shell in this
+case, because it\[aq]s not followed by a word character; but it would be
+harmless to do so.
+.PP
+But here\[aq]s another way to write that, which tends to be easier: add
+backslashes to escape from regular expressions, then enclose with quotes
+to escape from the shell:
 .IP
 .EX
-$ hledger balance \[aq]cur:\[rs]$\[aq]
+$ hledger balance cur:\[aq]\[rs]$\[aq]
-.EE
-.PP
-(The dollar sign is regex\-escaped by the backslash preceding it.
-Then that backslash is shell\-escaped by another backslash, or by single
-quotes.)
-.SS Escaping add\-on arguments
-When you run an external add\-on command with \f[CR]hledger\f[R]
-(described below), any options or arguments being passed through to the
-add\-on executable lose one level of shell\-escaping, so you must add an
-extra level of shell\-escaping to compensate.
-.PP
-Eg, in the bash shell, to run the \f[CR]ui\f[R] add\-on and match a
-literal \f[CR]$\f[R] sign, you need to write:
-.IP
-.EX
-$ hledger ui cur:\[aq]\[rs]\[rs]$\[aq]
-.EE
-.PP
-or:
-.IP
-.EX
-$ hledger ui cur:\[rs]\[rs]\[rs]\[rs]$
-.EE
-.PP
-If you are wondering why \f[I]four\f[R] backslashes:
-.IP \[bu] 2
-\f[CR]$\f[R] is unescaped
-.IP \[bu] 2
-\f[CR]\[rs]$\f[R] is regex\-escaped
-.IP \[bu] 2
-\f[CR]\[rs]\[rs]$\f[R] is regex\-escaped, then shell\-escaped
-.IP \[bu] 2
-\f[CR]\[rs]\[rs]\[rs]\[rs]$\f[R] is regex\-escaped, then shell\-escaped,
-then both slashes are shell\-escaped once more for hledger argument
-pass\-through.
-.PP
-Or you can avoid such triple\-escaping, by running the add\-on
-executable directly:
-.IP
-.EX
-$ hledger\-ui cur:\[rs]\[rs]$
 .EE
 .SS Escaping in other situations
 hledger options and arguments are sometimes used in places other than
-the command line, with different escaping rules.
+the command line, where the escaping/quoting rules are different.
-For example, backslash\-quoting generally does not work there.
+For example, backslash\-quoting may not be available.
-Here are some more tips.
+Here\[aq]s a quick reference:
 .PP
 .TS
 tab(@);
 lw(17.5n) lw(52.5n).
 T{
-In Windows \f[CR]cmd\f[R]
+In unix shell
 T}@T{
-Use double quotes
+Use single quotes and/or backslash (or double quotes for variable
+interpolation)
 T}
 T{
 In Windows \f[CR]powershell\f[R]
 T}@T{
-Use single or double quotes
+Use single quotes (or double quotes for variable interpolation)
+T}
+T{
+In Windows \f[CR]cmd\f[R]
+T}@T{
+Use double quotes
 T}
 T{
 In hledger\-ui\[aq]s filter prompt
@@ -623,14 +604,14 @@ T}
 T{
 In an argument file
 T}@T{
-Don\[aq]t use spaces, don\[aq]t shell\-escape, do regex\-escape when
+Don\[aq]t use spaces, don\[aq]t shell\-escape, do regex\-escape, write
-needed
+one argument/option per line
 T}
 T{
 In a config file
 T}@T{
 Use single or double quotes, and enclose the whole argument
-(\f[CR]\[dq]desc:a b\[dq]\f[R] not \f[CR]desc:\[dq]a b\[dq]\f[R])
+(\f[CR]\[aq]desc:a b\[aq]\f[R] not \f[CR]desc:\[aq]a b\[aq]\f[R])
 T}
 T{
 In \f[CR]ghci\f[R] (the Haskell REPL)
@@ -638,15 +619,6 @@ T}@T{
 Use double quotes, and enclose the whole argument
 T}
 .TE
-.SS Using a wild card
-When escaping a special character is too much hassle (or impossible),
-you can often just write \f[CR].\f[R] (period) instead.
-In regular expressions, this means \[dq]accept any character here\[dq].
-Eg:
-.IP
-.EX
-$ hledger register credit.card
-.EE
 .SS Unicode characters
 hledger is expected to handle non\-ascii characters correctly:
 .IP \[bu] 2
@@ -1866,7 +1838,7 @@ In english they are:
 .PP
 These will be discussed more in Account types below.
 In hledger docs you may see them referred to as A, L, E, R, X for short.
-.SS The two space delimiter
+.SS Two space delimiter
 Note the \f[B]two or more spaces\f[R] delimiter that\[aq]s sometimes
 required after account names.
 \ hledger\[aq]s account names, inherited from Ledger, are very
@@ -2381,46 +2353,139 @@ here.)
 .RE
 .SS Tags
 Tags are a way to add extra labels or data fields to transactions,
-postings, or accounts.
+postings, or accounts, which you can match with a \f[CR]tag:\f[R] query
-They are usually a word or hyphenated word, immediately followed by a
+in reports.
-full colon, written within the comment of a transaction, a posting, or
-an \f[CR]account\f[R] directive.
-(Yes, storing data in comments is slightly weird!)
-.PP
-You can write each tag on its own comment line, or multiple tags on one
-line, separated by commas.
-Tags can also have a value, which is any text after the colon until the
-next comma or end of line, excluding surrounding whitespace.
-(hledger tag values can\[aq]t contain commas.)
-If the same tag name appears multiple times in a comment, each
-name:value pair is preserved.
-.PP
-An example: in this journal there are six tags, one of them with a
-value:
-.IP
-.EX
-account assets:checking         ; accounttag:
-account expenses:food
-
-2017/1/16 bought groceries      ; transactiontag:
-    ; transactiontag2:
-    assets:checking        $\-1
-     ; posting\-tag\-1:, (belongs to the posting above)
-    expenses:food           $1  ; posting\-tag\-2:, posting\-tag\-3: with a value
-.EE
-.SS Querying with tags
-Tags are most often used to select a subset of data; you can match
-tagged things by tag name and or tag value with a \f[CR]tag:\f[R] query.
 (See queries below.)
 .PP
-When querying for tag names or values, note that postings inherit tags
+Tags are a single word or hyphenated word, immediately followed by a
-from their transaction and from their account, and transactions acquire
+full colon, written within a comment.
-tags from their postings.
+(Yes, storing data in comments is slightly weird.)
-So in the example above, \- the assets:checking posting effectively has
+Here\[aq]s a transaction with a tag:
-four tags (one of its own, one from the account, two from the
+.IP
-transaction) \- the expenses:food posting effectively has four tags (two
+.EX
-of its own, two from the transaction) \- the transaction effectively has
+2025\-01\-01 groceries        ; some\-tag:
-all six tags (two of its own, and two from each posting)
+    assets:checking
+    expenses:food       $1
+.EE
+.PP
+A tag can have a value, a single line of text written after the colon.
+Tag values can\[aq]t contain newlines.:
+.IP
+.EX
+2025\-01\-01 groceries        ; tag1: this is tag1\[aq]s value
+.EE
+.PP
+Multiple tags can be separated by comma.
+Tag values can\[aq]t contain commas.:
+.IP
+.EX
+2025\-01\-01 groceries        ; tag1:value 1, tag2:value 2, comment text
+.EE
+.PP
+A tag can have multiple values:
+.IP
+.EX
+2025\-01\-01 groceries        ; tag1:value 1, tag1:value 2
+.EE
+.PP
+You can write each tag on its own line of you prefer (but they still
+can\[aq]t contain commas):
+.IP
+.EX
+2025\-01\-01 groceries
+    ; tag1: value 1
+    ; tag2: value 2
+.EE
+.PP
+Tags can be attached to individual postings, rather than the overall
+transaction:
+.IP
+.EX
+2025\-01\-01 rent
+    assets:checking
+    expenses:rent       $1000  ; postingtag:
+.EE
+.PP
+Tags can be attached to accounts, in their account directive:
+.IP
+.EX
+account assets:checking    ; acct\-number: 123\-45\-6789
+.EE
+.SS Tag propagation
+In addition to what they are attached to, tags also affect related data
+in a few ways, allowing more powerful queries:
+.IP "1." 3
+Accounts \-> postings.
+Postings inherit tags from their account.
+.IP "2." 3
+Transactions \-> postings.
+Postings inherit tags from their transaction.
+.IP "3." 3
+Postings \-> transactions.
+Transactions also acquire the tags of their postings.
+\ 
+.PP
+So when you use a \f[CR]tag:\f[R] query to match whole transactions,
+individual postings, or accounts, it\[aq]s good to understand how tags
+behave.
+Here\[aq]s an example showing all three kinds of propagation:
+.IP
+.EX
+account assets:checking
+account expenses:food           ; atag:
+
+2025\-01\-01 groceries            ; ttag:
+    assets:checking             ; p1tag:
+    expenses:food           $1  ; p2tag:
+.EE
+.PP
+.TS
+tab(@);
+lw(13.3n) lw(13.8n) lw(43.0n).
+T{
+data part
+T}@T{
+has tags
+T}@T{
+explanation
+T}
+_
+T{
+assets:checking\ account
+T}@T{
+T}@T{
+no tags attached
+T}
+T{
+expenses:food account
+T}@T{
+atag
+T}@T{
+atag: in comment
+T}
+T{
+assets:checking posting
+T}@T{
+p1tag, ttag
+T}@T{
+p1tag: in comment, ttag acquired from transaction
+T}
+T{
+expenses:food posting
+T}@T{
+p2tag, atag, ttag
+T}@T{
+p2tag: in comment, atag from account, ttag from transaction
+T}
+T{
+groceries transaction
+T}@T{
+ttag, p1tag, p2tag, atag
+T}@T{
+ttag: in comment, p1tag from first posting, p2tag and atag from second
+posting
+T}
+.TE
 .SS Displaying tags
 You can use the \f[CR]tags\f[R] command to list tag names or values.
 .PP
@@ -2442,19 +2507,18 @@ For example, you could tag trip\-related transactions with
 categories.
 .SS Tag names
 What is allowed in a tag name ?
-Currently, most non\-whitespace characters.
+Most non\-whitespace characters.
 Eg \f[CR]😀:\f[R] is a valid tag.
 .PP
 For extra error checking, you can declare valid tag names with the
 \f[CR]tag\f[R] directive, and then enforce these with the
 \f[CR]check\f[R] command.
-.PP
 But note that tags are detected quite loosely at present, sometimes
 where you didn\[aq]t intend them.
-Eg \f[CR]; see https://foo.com\f[R] contains a \f[CR]https\f[R] tag with
+Eg a comment like \f[CR]; see https://foo.com\f[R] adds a
-value \f[CR]//foo.com\f[R].
+\f[CR]https\f[R] tag.
-.SS Special tags
+.PP
-Some tag names have special significance to hledger.
+There are several tag names which have special significance to hledger.
 They are explained elsewhere, but here\[aq]s a quick reference:
 .IP
 .EX
@@ -2964,7 +3028,7 @@ You can list accounts and their types, for troubleshooting:
 .RS 2
 .IP
 .EX
-$ hledger accounts \-\-types [ACCTPAT] [type:TYPECODES] [\-DEPTH] [\-\-positions]
+$ hledger accounts \-\-types [ACCTPAT] [type:TYPECODES] [\-DEPTH]
 .EE
 .RE
 .IP \[bu] 2
@@ -7213,8 +7277,8 @@ Some special cases:
 Colons appearing in PIVOTEXPR or in a pivoted tag value will generate
 account hierarchy.
 .IP \[bu] 2
-When pivoting a posting has multiple values for a tag, the pivoted value
+When pivoting a posting that has multiple values for a tag, the
-of that tag will be the first value.
+tag\[aq]s first value will be used as the pivoted value.
 .IP \[bu] 2
 When a posting has multiple commodities, the pivoted value of
 \[dq]comm\[dq]/\[dq]cur\[dq] will be \[dq]\[dq].
@@ -9400,23 +9464,40 @@ Flags:
      \-\-unused               list accounts declared but not used
      \-\-find                 list the first account matched by the first
                             argument (a case\-insensitive infix regexp)
-     \-\-types                also show account types when known
-     \-\-positions            also show where accounts were declared
      \-\-directives           show as account directives, for use in journals
+     \-\-locations            also show where accounts were declared
+     \-\-types                also show account types when known
   \-l \-\-flat                 list/tree mode: show accounts as a flat list
                             (default)
   \-t \-\-tree                 list/tree mode: show accounts as a tree
      \-\-drop=N               flat mode: omit N leading account name parts
 .EE
 .PP
-This command lists account names \- all of them by default.
+This command lists account names \- all of them by default, or just the
-or just the ones which have been used in transactions, or declared with
+ones which have been used in transactions (\f[CR]\-u/\-\-used\f[R]), or
-\f[CR]account\f[R] directives, or used but not declared, or declared but
+declared with \f[CR]account\f[R] directives
-not used, or just the first account name matched by a pattern.
+(\f[CR]\-d/\-\-declared\f[R]), or used but not declared
+(\f[CR]\-\-undeclared\f[R]), or declared but not used
+(\f[CR]\-\-unused\f[R]), or just the first one matched by a pattern
+(\f[CR]\-\-find\f[R], returning a non\-zero exit code if it fails).
 .PP
 You can add query arguments to select a subset of transactions or
 accounts.
 .PP
+With \f[CR]\-\-directives\f[R], it shows valid account directives which
+could be pasted into a journal file.
+This is useful together with \f[CR]\-\-undeclared\f[R] when updating
+your account declarations to satisfy \f[CR]hledger check accounts\f[R].
+.PP
+With \f[CR]\-\-locations\f[R], it also shows the file and line number of
+each account\[aq]s declaration, if any, and the account\[aq]s overall
+declaration order; these may be useful when troubleshooting account
+display order.
+.PP
+With \f[CR]\-\-types\f[R], it also shows each account\[aq]s type, if
+it\[aq]s known.
+(See Declaring accounts > Account types.)
+.PP
 It shows a flat list by default.
 With \f[CR]\-\-tree\f[R], it uses indentation to show the account
 hierarchy.
@@ -9425,25 +9506,6 @@ account name components.
 Account names can be depth\-clipped with \f[CR]depth:N\f[R] or
 \f[CR]\-\-depth N\f[R] or \f[CR]\-N\f[R].
 .PP
-With \f[CR]\-\-types\f[R], it also shows each account\[aq]s type, if
-it\[aq]s known.
-(See Declaring accounts > Account types.)
-.PP
-With \f[CR]\-\-positions\f[R], it also shows the file and line number of
-each account\[aq]s declaration, if any, and the account\[aq]s overall
-declaration order; these may be useful when troubleshooting account
-display order.
-.PP
-With \f[CR]\-\-directives\f[R], it shows valid account directives which
-could be pasted into a journal file.
-This is useful together with \f[CR]\-\-undeclared\f[R] when updating
-your account declarations to satisfy \f[CR]hledger check accounts\f[R].
-.PP
-The \f[CR]\-\-find\f[R] flag can be used to look up a single account
-name, in the same way that the \f[CR]aregister\f[R] command does.
-It returns the alphanumerically\-first matched account name, or if none
-can be found, it fails with a non\-zero exit code.
-.PP
 Examples:
 .IP
 .EX
@@ -9526,14 +9588,19 @@ Flags:
      \-\-declared             list commodities declared
      \-\-undeclared           list commodities used but not declared
      \-\-unused               list commodities declared but not used
+     \-\-find                 list the first commodity matched by the first
+                            argument (a case\-insensitive infix regexp)
 .EE
 .PP
 This command lists commodity symbols/names \- all of them by default, or
 just the ones which have been used in transactions or \f[CR]P\f[R]
 directives, or declared with \f[CR]commodity\f[R] directives, or used
-but not declared, or declared but not used.
+but not declared, or declared but not used, or just the first one
+matched by a pattern (with \f[CR]\-\-find\f[R], returning a non\-zero
+exit code if it fails).
 .PP
-You can add cur: query arguments to further limit the commodities.
+You can add \f[CR]cur:\f[R] query arguments to further limit the
+commodities.
 .SS descriptions
 List the unique descriptions used in transactions.
 .IP
@@ -9593,12 +9660,15 @@ Flags:
      \-\-declared             list payees declared
      \-\-undeclared           list payees used but not declared
      \-\-unused               list payees declared but not used
+     \-\-find                 list the first payee matched by the first
+                            argument (a case\-insensitive infix regexp)
 .EE
 .PP
 This command lists unique payee/payer names \- all of them by default,
 or just the ones which have been used in transaction descriptions, or
 declared with \f[CR]payee\f[R] directives, or used but not declared, or
-declared but not used.
+declared but not used, or just the first one matched by a pattern (with
+\f[CR]\-\-find\f[R], returning a non\-zero exit code if it fails).
 .PP
 The payee/payer name is the part of the transaction description before a
 | character (or if there is no |, the whole description).
@@ -9700,6 +9770,8 @@ Flags:
      \-\-declared             list tags declared
      \-\-undeclared           list tags used but not declared
      \-\-unused               list tags declared but not used
+     \-\-find                 list the first tag whose name is matched by the
+                            first argument (a case\-insensitive infix regexp)
      \-\-values               list tag values instead of tag names
      \-\-parsed               show them in the order they were parsed (mostly),
                             including duplicates
@@ -9708,13 +9780,14 @@ Flags:
 This command lists tag names \- all of them by default, or just the ones
 which have been used on transactions/postings/accounts, or declared with
 \f[CR]tag\f[R] directives, or used but not declared, or declared but not
-used.
+used, or just the first one matched by a pattern (with
+\f[CR]\-\-find\f[R], returning a non\-zero exit code if it fails).
 .PP
-You can add one TAGREGEX argument, to show only tags whose name is
+Note this command\[aq]s non\-standard first argument: it is a
-matched by this case\-insensitive, infix\-matching regular expression.
+case\-insensitive infix regular expression for matching tag names, which
-.PP
+limits the tags shown.
-After that, you can add query arguments to filter the transactions,
+Any additional arguments are standard query arguments, which limit the
-postings, or accounts providing tags.
+transactions, postings, or accounts providing tags.
 .PP
 With \f[CR]\-\-values\f[R], the tags\[aq] unique non\-empty values are
 listed instead.
@@ -9737,15 +9810,11 @@ Show full journal entries, representing transactions.
 Flags:
   \-x \-\-explicit             show all amounts explicitly
      \-\-invert               display all amounts with reversed sign
-     \-\-location             add tags showing file paths and line numbers
+     \-\-locations            add tags showing file paths and line numbers
   \-m \-\-match=DESC           fuzzy search for one recent transaction with
                             description closest to DESC
      \-\-new                  show only newer\-dated transactions added in each
                             file since last run
-     \-\-no\-lots              remove lot subaccounts and their balance
-                            assertions
-     \-\-no\-lots2             remove lot subaccounts and their costs and
-                            balance assertions (can produce unbalanced entries)
      \-\-round=TYPE           how much rounding or padding should be done when
                             displaying amounts ?
                             none \- show original decimal digits,
@@ -9791,7 +9860,7 @@ $ hledger print \-f examples/sample.journal date:200806
     expenses:supplies            $1
     assets:cash                 $\-2
 .EE
-.SS print explicitness
+.SS print amount explicitness
 Normally, whether posting amounts are implicit or explicit is preserved.
 For example, when an amount is omitted in the journal, it will not
 appear in the output.
@@ -9809,19 +9878,20 @@ The \f[CR]\-x\f[R]/\f[CR]\-\-explicit\f[R] flag will cause any postings
 with a multi\-commodity amount (which can arise when a multi\-commodity
 transaction has an implicit amount) to be split into multiple
 single\-commodity postings, keeping the output parseable.
-.SS print amount style
+.SS print alignment
 Amounts are shown right\-aligned within each transaction (but not
-aligned across all transactions; you can do that with ledger\-mode in
+aligned across all transactions; you can achieve that with ledger\-mode
-Emacs).
+in Emacs).
+.SS print amount style
+Amounts will be displayed mostly in their commodity\[aq]s display style,
+with standardised symbol placement, decimal mark, and digit group marks.
+This does not apply to their decimal digits; \f[CR]print\f[R] normally
+shows the same decimal digits that are recorded in each journal entry.
 .PP
-Amounts will be (mostly) normalised to their commodity display style:
+You can override the decimal precisions with \f[CR]print\f[R]\[aq]s
-their symbol placement, decimal mark, and digit group marks will be made
+special \f[CR]\-\-round\f[R] option (\f[I]since 1.32\f[R]).
-consistent.
+\f[CR]\-\-round\f[R] tries to show amounts with their commodities\[aq]
-By default, decimal digits are shown as they are written in the journal.
+standard decimal precisions, increasingly strongly:
-.PP
-With the \f[CR]\-\-round\f[R] (\f[I]Added in 1.32\f[R]) option,
-\f[CR]print\f[R] will try increasingly hard to display decimal digits
-according to the commodity display styles:
 .IP \[bu] 2
 \f[CR]\-\-round=none\f[R] show amounts with original precisions
 (default)
@@ -9834,17 +9904,18 @@ significant digits
 .IP \[bu] 2
 \f[CR]\-\-round=all\f[R] round all amounts and costs
 .PP
-\f[CR]soft\f[R] is good for non\-lossy cleanup, formatting amounts more
+\f[CR]soft\f[R] is good for non\-lossy cleanup, displaying more
-consistently where it\[aq]s safe to do so.
+consistent decimals where possible, without making entries unbalanced.
 .PP
-\f[CR]hard\f[R] and \f[CR]all\f[R] can cause \f[CR]print\f[R] to show
+\f[CR]hard\f[R] or \f[CR]all\f[R] can be good for stronger cleanup, when
-invalid unbalanced journal entries; they may be useful eg for stronger
+decimal rounding is wanted.
-cleanup, with manual fixups when needed.
+Note rounding can produce unbalanced journal entries, perhaps requiring
+manual fixup.
 .SS print parseability
-print\[aq]s output is usually a valid hledger journal, and you can
+Normally, print\[aq]s output is a valid hledger journal, which you can
-process it again with a second hledger command.
+\[dq]pipe\[dq] to a second hledger command for further processing.
-This can be useful for certain kinds of search (though the same can be
+This is sometimes convenient for achieving certain kinds of query
-achieved with \f[CR]expr:\f[R] queries now):
+(though less needed now that queries have become more powerful):
 .IP
 .EX
 # Show running total of food expenses paid from cash.
@@ -9852,15 +9923,21 @@ achieved with \f[CR]expr:\f[R] queries now):
 $ hledger print assets:cash | hledger \-f\- \-I reg expenses:food
 .EE
 .PP
-There are some situations where print\[aq]s output can become
+But here are some things which can cause print\[aq]s output to become
 unparseable:
 .IP \[bu] 2
-Value reporting affects posting amounts but not balance assertion or
+\f[CR]\-\-round\f[R] (see above) can disrupt transaction balancing.
-balance assignment amounts, potentially causing those to fail.
 .IP \[bu] 2
-Auto postings can generate postings with too many missing amounts.
+Account aliases or pivoting can disrupt account names, balance
+assertions, or balance assignments.
 .IP \[bu] 2
-Account aliases can generate bad account names.
+Value reporting also can disrupt balance assertions or balance
+assignments.
+.IP \[bu] 2
+Auto postings can generate too many amountless postings.
+.IP \[bu] 2
+\f[CR]\-\-infer\-costs or \-\-infer\-equity\f[R] can generate
+too\-complex redundant costs.
 .SS print, other features
 With \f[CR]\-B\f[R]/\f[CR]\-\-cost\f[R], amounts with costs are shown
 converted to cost.
@@ -9882,8 +9959,8 @@ DESC should contain at least two characters.
 If there is no similar\-enough match, no transaction will be shown and
 the program exit code will be non\-zero.
 .PP
-With \f[CR]\-\-location\f[R], print adds the source file and line number
+With \f[CR]\-\-locations\f[R], print adds the source file and line
-to every transaction, as a tag.
+number to every transaction, as a tag.
 .SS print output format
 This command also supports the output destination and output format
 options The output formats supported are \f[CR]txt\f[R],
@@ -10003,25 +10080,21 @@ As a quick rule of thumb: \- use \f[CR]aregister\f[R] for reviewing and
 reconciling real\-world asset/liability accounts \- use
 \f[CR]register\f[R] for reviewing detailed revenues/expenses.
 .PP
-\f[CR]aregister\f[R] requires one argument: the account to report on.
+Note this command\[aq]s non\-standard, and required, first argument; it
-You can write either the full account name, or a case\-insensitive
+specifies the account whose register will be shown.
-regular expression which will select the alphabetically first matched
+You can write the account\[aq]s name, or (to save typing) a
-account.
+case\-insensitive infix regular expression matching the name, which
-.PP
+selects the alphabetically first matched account.
-When there are multiple matches, the alphabetically\-first choice can be
+(For example, if you have \f[CR]assets:personal checking\f[R] and
-surprising; eg if you have \f[CR]assets:per:checking 1\f[R] and
+\f[CR]assets:business checking\f[R], \f[CR]hledger areg checking\f[R]
-\f[CR]assets:biz:checking 2\f[R] accounts,
+would select \f[CR]assets:business checking\f[R].)
-\f[CR]hledger areg checking\f[R] would select
-\f[CR]assets:biz:checking 2\f[R].
-It\[aq]s just a convenience to save typing, so if in doubt, write the
-full account name, or a distinctive substring that matches uniquely.
 .PP
 Transactions involving subaccounts of this account will also be shown.
 \f[CR]aregister\f[R] ignores depth limits, so its final total will
 always match a historical balance report with similar arguments.
 .PP
-Any additional arguments form a query which will filter the transactions
+Any additional arguments are standard query arguments, which will limit
-shown.
+the transactions shown.
 Note some queries will disturb the running balance, causing it to be
 different from the account\[aq]s real\-world running balance.
 .PP

hledger/hledger.txt

@@ -356,138 +356,117 @@ Options
        skip these until you need them.
 
    Special characters
-       Here  we touch on shell escaping/quoting rules, and give some examples.
+       In  commands you type at the command line, certain characters have spe-
-       This is a slightly complicated topic which you may not need  at  first,
+       cial meaning and sometimes need to be "escaped" or "quoted", by prefix-
-       but you should be aware of it, so you can return here when needed.
+       ing backslashes or enclosing in quotes.
 
        If you are able to minimise the use of special characters in your data,
-       you  won't  need  escaping as much, and your command lines will be sim-
+       you won't have to deal with this as much.  For example, you  could  use
-       pler.  For example, avoiding spaces in  account  names,  and  using  an
+       hyphen  -  or  underscore _ instead of spaces in account names, and you
-       ISO-4217  currency  code like USD instead of the $ currency symbol, can
+       could use the USD currency code instead of the  $  currency  symbol  in
-       be helpful.
+       amounts.
 
-       But if you want to use spaced account names and $, go right ahead;  es-
+       But  if  you prefer to use spaced account names and $, it's fine.  Just
-       caping isn't a big deal.
+       be aware of this topic so you can check this doc when  needed.   (These
+       examples  are  mostly  tested  on  unix;  some details might need to be
+       adapted if you're on Windows.)
 
    Escaping shell special characters
-       At  the  command  line,  characters which have special meaning for your
+       These are some characters which may have special meaning to your  shell
-       shell must be "shell-escaped" (AKA "quoted") if you want hledger to see
+       (the program which interprets command lines):
-       them.  Often these include space, <, >, (, ), |, \, $ and/or %.
 
-       For example, to match an account name  containing  the  phrase  "credit
+       o SPACE, <, >, (, ), |, \, %
-       card", don't write this:
+
+       o $ if followed by a word character
+
+       So  for  example,  to  match  an  account  name containing spaces, like
+       "credit card", don't write:
 
               $ hledger register credit card
 
-       In  that command, "credit" and "card" are treated as separate query ar-
+       Instead, enclose the name in single quotes:
-       guments (described below), so this would match accounts containing  ei-
-       ther word.  Instead, enclose the phrase in double or single quotes:
 
-              $ hledger register "credit card"
+              $ hledger register 'credit card'
 
-       In Unix shells, writing a backslash before the character can also work.
+       On unix or in Windows powershell, if you use double quotes  your  shell
-       Eg:
+       will  silently treat $ as variable interpolation.  So you should proba-
+       bly avoid double quotes, unless  you  want  that  behaviour,  eg  in  a
+       script:
+
+              $ hledger register "assets:$SOMEACCT"
+
+       But in an older Windows CMD.EXE window, you must use double quotes:
+
+              C:\Users\Me> hledger register "credit card"
+
+       On  unix  or in Windows powershell, as an alternative to quotes you can
+       write a backslash before each special character:
 
               $ hledger register credit\ card
 
-       Some  shell  characters  still  have  a  special  meaning inside double
+       Finally, since hledger's query arguments are regular  expressions  (de-
-       quotes, such as the dollar sign ($).  Eg in "assets:$account", the bash
+       scribed  below),  you could also fill that gap with . which matches any
-       shell would replace $account with the value of a  shell  variable  with
+       character:
-       that  name.   When you don't want that, use single quotes, which escape
-       more strongly:
 
-              $ hledger balance 'assets:$account'
+              $ hledger register credit.card
-
-   Escaping on Windows
-       If you are using hledger in a Powershell or Command window on Microsoft
-       Windows, the escaping rules are different:
-
-       o In a Powershell window (powershell, blue background),  you  must  use
-         double quotes or single quotes (not backslash).
-
-       o In  a  Command  window  (cmd,  black background), you must use double
-         quotes (not single quotes or backslash).
-
-       The next two sections were written for Unix-like shells, so might  need
-       to be adapted if you're using cmd or powershell.  (Edits welcome.)
 
    Escaping regular expression special characters
-       Many  hledger  arguments are regular expressions (described below), and
+       Some characters also have special meaning in regular expressions, which
-       these too have characters which cause special effects.  Some  of  those
+       hledger's arguments often are.  Those include:
-       characters  are  .,  ^,  $,  [, ], (, ), |, and \.  When you don't want
-       these to cause special effects, you can "regex-escape" them by  writing
-       \  (a  backslash)  before them.  But since backslash is also special to
-       the shell, you may need to also shell-escape the backslashes.
 
-       Eg, in the bash shell, to match a literal $ sign, you could write:
+       o ., ^, $, [, ], (, ), |, \
+
+       To escape one of these, write \ before it.  But note this is  in  addi-
+       tion  to the shell escaping above.  So for characters which are special
+       to both shell and regular expressions, like \ and $, you will sometimes
+       need two levels of escaping.
+
+       For example, a balance report that uses a cur: query restricting it  to
+       just the $ currency, should be written like this:
 
               $ hledger balance cur:\\$
 
-       or:
+       Explanation:
 
-              $ hledger balance 'cur:\$'
+       1. Add  a backslash \ before the dollar sign $ to protect it from regu-
+          lar expressions (so it will be matched  literally  with  no  special
+          meaning).
 
-       (The dollar sign is regex-escaped by the backslash preceding it.   Then
+       2. Add  another backslash before that backslash, to protect it from the
-       that  backslash  is  shell-escaped  by  another backslash, or by single
+          shell (so the shell won't consume it).
-       quotes.)
 
-   Escaping add-on arguments
+       3. $ doesn't need to be protected from the shell in this case,  because
-       When you run an external add-on command with hledger (described below),
+          it's  not  followed by a word character; but it would be harmless to
-       any options or arguments being passed through to the add-on  executable
+          do so.
-       lose  one  level  of  shell-escaping, so you must add an extra level of
-       shell-escaping to compensate.
 
-       Eg, in the bash shell, to run the ui add-on and match a literal $ sign,
+       But here's another way to write that, which tends  to  be  easier:  add
-       you need to write:
+       backslashes  to  escape  from  regular  expressions,  then enclose with
+       quotes to escape from the shell:
 
-              $ hledger ui cur:'\\$'
+              $ hledger balance cur:'\$'
-
-       or:
-
-              $ hledger ui cur:\\\\$
-
-       If you are wondering why four backslashes:
-
-       o $ is unescaped
-
-       o \$ is regex-escaped
-
-       o \\$ is regex-escaped, then shell-escaped
-
-       o \\\\$ is regex-escaped, then shell-escaped,  then  both  slashes  are
-         shell-escaped once more for hledger argument pass-through.
-
-       Or you can avoid such triple-escaping, by running the add-on executable
-       directly:
-
-              $ hledger-ui cur:\\$
 
    Escaping in other situations
        hledger options and arguments are sometimes used in places  other  than
-       the command line, with different escaping rules.   For  example,  back-
+       the  command line, where the escaping/quoting rules are different.  For
-       slash-quoting generally does not work there.  Here are some more tips.
+       example, backslash-quoting may not be available.  Here's a quick refer-
+       ence:
 
+       In unix shell       Use single quotes and/or backslash (or double quotes
+                           for variable interpolation)
+       In Windows power-   Use single quotes (or double quotes for variable in-
+       shell               terpolation)
        In Windows cmd      Use double quotes
-       In Windows power-   Use single or double quotes
-       shell
        In   hledger-ui's   Use single or double quotes
        filter prompt
        In  hledger-web's   Use single or double quotes
        search form
        In  an   argument   Don't  use  spaces, don't shell-escape, do regex-es-
-       file                cape when needed
+       file                cape, write one argument/option per line
        In a config file    Use single or double quotes, and enclose  the  whole
-                           argument ("desc:a b" not desc:"a b")
+                           argument ('desc:a b' not desc:'a b')
        In    ghci   (the   Use double quotes, and enclose the whole argument
        Haskell REPL)
 
-   Using a wild card
-       When  escaping  a special character is too much hassle (or impossible),
-       you can often just write . (period) instead.  In  regular  expressions,
-       this means "accept any character here".  Eg:
-
-              $ hledger register credit.card
-
    Unicode characters
        hledger is expected to handle non-ascii characters correctly:
 
@@ -1430,7 +1409,7 @@ Journal
        These  will  be discussed more in Account types below.  In hledger docs
        you may see them referred to as A, L, E, R, X for short.
 
-   The two space delimiter
+   Two space delimiter
        Note the two or more spaces delimiter that's sometimes  required  after
        account  names.    hledger's  account names, inherited from Ledger, are
        very permissive; they may contain pretty much any kind of text, includ-
@@ -1864,43 +1843,84 @@ Journal
 
    Tags
        Tags are a way to add extra labels  or  data  fields  to  transactions,
-       postings, or accounts.  They are usually a word or hyphenated word, im-
+       postings,  or  accounts,  which  you can match with a tag: query in re-
-       mediately followed by a full colon, written within  the  comment  of  a
+       ports.  (See queries below.)
-       transaction, a posting, or an account directive.  (Yes, storing data in
-       comments is slightly weird!)
 
-       You can write each tag on its own comment line, or multiple tags on one
+       Tags are a single word or hyphenated word, immediately  followed  by  a
-       line,  separated  by  commas.  Tags can also have a value, which is any
+       full  colon,  written within a comment.  (Yes, storing data in comments
-       text after the colon until the next comma or  end  of  line,  excluding
+       is slightly weird.)  Here's a transaction with a tag:
-       surrounding whitespace.  (hledger tag values can't contain commas.)  If
-       the  same tag name appears multiple times in a comment, each name:value
-       pair is preserved.
 
-       An example: in this journal there are six tags,  one  of  them  with  a
+              2025-01-01 groceries        ; some-tag:
-       value:
+                  assets:checking
+                  expenses:food       $1
 
-              account assets:checking         ; accounttag:
+       A tag can have a value, a single line of text written after the  colon.
-              account expenses:food
+       Tag values can't contain newlines.:
 
-              2017/1/16 bought groceries      ; transactiontag:
+              2025-01-01 groceries        ; tag1: this is tag1's value
-                  ; transactiontag2:
-                  assets:checking        $-1
-                   ; posting-tag-1:, (belongs to the posting above)
-                  expenses:food           $1  ; posting-tag-2:, posting-tag-3: with a value
 
-   Querying with tags
+       Multiple tags can be separated by comma.  Tag values can't contain com-
-       Tags  are  most  often  used  to select a subset of data; you can match
+       mas.:
-       tagged things by tag name and or tag value with  a  tag:  query.   (See
-       queries below.)
 
-       When  querying for tag names or values, note that postings inherit tags
+              2025-01-01 groceries        ; tag1:value 1, tag2:value 2, comment text
-       from their transaction and from their account, and transactions acquire
+
-       tags from their postings.  So in the example above, - the assets:check-
+       A tag can have multiple values:
-       ing posting effectively has four tags (one of its own, one from the ac-
+
-       count, two from the transaction) -  the  expenses:food  posting  effec-
+              2025-01-01 groceries        ; tag1:value 1, tag1:value 2
-       tively  has  four tags (two of its own, two from the transaction) - the
+
-       transaction effectively has all six tags (two of its own, and two  from
+       You  can  write  each tag on its own line of you prefer (but they still
-       each posting)
+       can't contain commas):
+
+              2025-01-01 groceries
+                  ; tag1: value 1
+                  ; tag2: value 2
+
+       Tags can be attached to individual postings, rather  than  the  overall
+       transaction:
+
+              2025-01-01 rent
+                  assets:checking
+                  expenses:rent       $1000  ; postingtag:
+
+       Tags can be attached to accounts, in their account directive:
+
+              account assets:checking    ; acct-number: 123-45-6789
+
+   Tag propagation
+       In addition to what they are attached to, tags also affect related data
+       in a few ways, allowing more powerful queries:
+
+       1. Accounts -> postings.  Postings inherit tags from their account.
+
+       2. Transactions -> postings.  Postings inherit tags from their transac-
+          tion.
+
+       3. Postings  ->  transactions.   Transactions  also acquire the tags of
+          their postings.
+
+       So when you use a tag: query to match  whole  transactions,  individual
+       postings, or accounts, it's good to understand how tags behave.  Here's
+       an example showing all three kinds of propagation:
+
+              account assets:checking
+              account expenses:food           ; atag:
+
+              2025-01-01 groceries            ; ttag:
+                  assets:checking             ; p1tag:
+                  expenses:food           $1  ; p2tag:
+
+       data part       has tags         explanation
+       -----------------------------------------------------------------------------
+       assets:check-                    no tags attached
+       ing account
+       expenses:food   atag             atag: in comment
+       account
+       assets:check-   p1tag, ttag      p1tag:   in  comment,  ttag  acquired  from
+       ing posting                      transaction
+       expenses:food   p2tag,   atag,   p2tag:  in comment, atag from account, ttag
+       posting         ttag             from transaction
+       groceries       ttag,   p1tag,   ttag: in comment, p1tag from first posting,
+       transaction     p2tag, atag      p2tag and atag from second posting
 
    Displaying tags
        You can use the tags command to list tag names or values.
@@ -1921,19 +1941,17 @@ Journal
        account categories.
 
    Tag names
-       What is allowed in a tag name ?  Currently, most non-whitespace charac-
+       What is allowed in a tag name ?  Most non-whitespace characters.  Eg  :
-       ters.  Eg : is a valid tag.
+       is a valid tag.
 
        For  extra error checking, you can declare valid tag names with the tag
-       directive, and then enforce these with the check command.
+       directive, and then enforce these with the  check  command.   But  note
+       that  tags  are  detected quite loosely at present, sometimes where you
+       didn't intend them.  Eg a comment like ;  see  https://foo.com  adds  a
+       https tag.
 
-       But  note  that  tags  are detected quite loosely at present, sometimes
+       There are several tag names which have special significance to hledger.
-       where you didn't intend them.  Eg  ;  see  https://foo.com  contains  a
+       They are explained elsewhere, but here's a quick reference:
-       https tag with value //foo.com.
-
-   Special tags
-       Some  tag  names  have  special  significance to hledger.  They are ex-
-       plained elsewhere, but here's a quick reference:
 
                type                   -- declares an account's type
                date                   -- overrides a posting's date
@@ -2217,7 +2235,7 @@ Journal
 
        o You can list accounts and their types, for troubleshooting:
 
-                $ hledger accounts --types [ACCTPAT] [type:TYPECODES] [-DEPTH] [--positions]
+                $ hledger accounts --types [ACCTPAT] [type:TYPECODES] [-DEPTH]
 
        o It's  a  good  idea  to declare at least one account for each account
          type.  Having some types declared and some inferred can disrupt  cer-
@@ -5567,8 +5585,8 @@ Pivoting
        o Colons appearing in PIVOTEXPR or in a pivoted tag value will generate
          account hierarchy.
 
-       o When pivoting a posting has multiple values for a  tag,  the  pivoted
+       o When pivoting a posting that has multiple values for a tag, the tag's
-         value of that tag will be the first value.
+         first value will be used as the pivoted value.
 
        o When  a  posting  has  multiple  commodities,  the  pivoted  value of
          "comm"/"cur" will be "".  Also when an unrecognised tag name or field
@@ -7321,43 +7339,40 @@ Basic report commands
                    --unused               list accounts declared but not used
                    --find                 list the first account matched by the first
                                           argument (a case-insensitive infix regexp)
-                   --types                also show account types when known
-                   --positions            also show where accounts were declared
                    --directives           show as account directives, for use in journals
+                   --locations            also show where accounts were declared
+                   --types                also show account types when known
                 -l --flat                 list/tree mode: show accounts as a flat list
                                           (default)
                 -t --tree                 list/tree mode: show accounts as a tree
                    --drop=N               flat mode: omit N leading account name parts
 
-       This command lists account names - all of them by default.  or just the
+       This command lists account names - all of them by default, or just  the
-       ones which have been used in transactions, or declared with account di-
+       ones which have been used in transactions (-u/--used), or declared with
-       rectives, or used but not declared, or declared but not used,  or  just
+       account  directives  (-d/--declared), or used but not declared (--unde-
-       the first account name matched by a pattern.
+       clared), or declared but not used (--unused), or  just  the  first  one
+       matched  by  a  pattern  (--find,  returning a non-zero exit code if it
+       fails).
 
        You can add query arguments to select a subset of transactions  or  ac-
        counts.
 
-       It shows a flat list by default.  With --tree, it uses  indentation  to
-       show  the account hierarchy.  In flat mode you can add --drop N to omit
-       the  first  few  account  name  components.   Account  names   can   be
-       depth-clipped with depth:N or --depth N or -N.
-
-       With  --types,  it also shows each account's type, if it's known.  (See
-       Declaring accounts > Account types.)
-
-       With --positions, it also shows the file and line number  of  each  ac-
-       count's  declaration, if any, and the account's overall declaration or-
-       der; these may be useful when troubleshooting account display order.
-
        With  --directives,  it  shows  valid account directives which could be
        pasted into a journal file.  This is useful together with  --undeclared
        when  updating  your  account declarations to satisfy hledger check ac-
        counts.
 
-       The  --find  flag  can be used to look up a single account name, in the
+       With --locations, it also shows the file and line number  of  each  ac-
-       same way that the aregister command does.  It returns the  alphanumeri-
+       count's  declaration, if any, and the account's overall declaration or-
-       cally-first  matched  account  name,  or if none can be found, it fails
+       der; these may be useful when troubleshooting account display order.
-       with a non-zero exit code.
+
+       With --types, it also shows each account's type, if it's  known.   (See
+       Declaring accounts > Account types.)
+
+       It  shows  a flat list by default.  With --tree, it uses indentation to
+       show the account hierarchy.  In flat mode you can add --drop N to  omit
+       the   first   few  account  name  components.   Account  names  can  be
+       depth-clipped with depth:N or --depth N or -N.
 
        Examples:
 
@@ -7428,11 +7443,14 @@ Basic report commands
                    --declared             list commodities declared
                    --undeclared           list commodities used but not declared
                    --unused               list commodities declared but not used
+                   --find                 list the first commodity matched by the first
+                                          argument (a case-insensitive infix regexp)
 
        This command lists commodity symbols/names - all of them by default, or
        just the ones which have been used in transactions or P directives,  or
        declared  with  commodity  directives, or used but not declared, or de-
-       clared but not used.
+       clared but not used, or just the first one matched by a  pattern  (with
+       --find, returning a non-zero exit code if it fails).
 
        You can add cur: query arguments to further limit the commodities.
 
@@ -7485,11 +7503,14 @@ Basic report commands
                    --declared             list payees declared
                    --undeclared           list payees used but not declared
                    --unused               list payees declared but not used
+                   --find                 list the first payee matched by the first
+                                          argument (a case-insensitive infix regexp)
 
        This  command  lists unique payee/payer names - all of them by default,
        or just the ones which have been used in transaction  descriptions,  or
        declared  with  payee directives, or used but not declared, or declared
-       but not used.
+       but not used, or just the first one matched by a pattern (with  --find,
+       returning a non-zero exit code if it fails).
 
        The  payee/payer name is the part of the transaction description before
        a | character (or if there is no |, the whole description).
@@ -7580,6 +7601,8 @@ Basic report commands
                    --declared             list tags declared
                    --undeclared           list tags used but not declared
                    --unused               list tags declared but not used
+                   --find                 list the first tag whose name is matched by the
+                                          first argument (a case-insensitive infix regexp)
                    --values               list tag values instead of tag names
                    --parsed               show them in the order they were parsed (mostly),
                                           including duplicates
@@ -7587,13 +7610,13 @@ Basic report commands
        This command lists tag names - all of them by default, or just the ones
        which  have  been  used  on transactions/postings/accounts, or declared
        with tag directives, or used but not  declared,  or  declared  but  not
-       used.
+       used,  or just the first one matched by a pattern (with --find, return-
+       ing a non-zero exit code if it fails).
 
-       You  can  add  one  TAGREGEX  argument, to show only tags whose name is
+       Note this command's non-standard first argument: it is a  case-insensi-
-       matched by this case-insensitive, infix-matching regular expression.
+       tive  infix regular expression for matching tag names, which limits the
-
+       tags shown.  Any additional arguments  are  standard  query  arguments,
-       After that, you can add query arguments  to  filter  the  transactions,
+       which limit the transactions, postings, or accounts providing tags.
-       postings, or accounts providing tags.
 
        With --values, the tags' unique non-empty values are listed instead.
 
@@ -7614,15 +7637,11 @@ Standard report commands
               Flags:
                 -x --explicit             show all amounts explicitly
                    --invert               display all amounts with reversed sign
-                   --location             add tags showing file paths and line numbers
+                   --locations            add tags showing file paths and line numbers
                 -m --match=DESC           fuzzy search for one recent transaction with
                                           description closest to DESC
                    --new                  show only newer-dated transactions added in each
                                           file since last run
-                   --no-lots              remove lot subaccounts and their balance
-                                          assertions
-                   --no-lots2             remove lot subaccounts and their costs and
-                                          balance assertions (can produce unbalanced entries)
                    --round=TYPE           how much rounding or padding should be done when
                                           displaying amounts ?
                                           none - show original decimal digits,
@@ -7665,7 +7684,7 @@ Standard report commands
                   expenses:supplies            $1
                   assets:cash                 $-2
 
-   print explicitness
+   print amount explicitness
        Normally,  whether  posting  amounts  are  implicit or explicit is pre-
        served.  For example, when an amount is omitted in the journal, it will
        not appear in the output.  Similarly, if a conversion cost  is  implied
@@ -7681,19 +7700,20 @@ Standard report commands
        plicit amount) to be split  into  multiple  single-commodity  postings,
        keeping the output parseable.
 
-   print amount style
+   print alignment
        Amounts  are  shown  right-aligned  within  each  transaction  (but not
-       aligned across all transactions; you can do that  with  ledger-mode  in
+       aligned across all transactions; you can achieve that with  ledger-mode
-       Emacs).
+       in Emacs).
 
-       Amounts  will  be (mostly) normalised to their commodity display style:
+   print amount style
-       their symbol placement, decimal mark, and digit  group  marks  will  be
+       Amounts  will  be  displayed mostly in their commodity's display style,
-       made  consistent.   By  default,  decimal  digits are shown as they are
+       with standardised symbol  placement,  decimal  mark,  and  digit  group
-       written in the journal.
+       marks.   This  does  not  apply to their decimal digits; print normally
+       shows the same decimal digits that are recorded in each journal entry.
 
-       With the --round (Added in 1.32) option, print  will  try  increasingly
+       You can override the decimal precisions with  print's  special  --round
-       hard  to  display  decimal  digits  according  to the commodity display
+       option (since 1.32).  --round tries to show amounts with their commodi-
-       styles:
+       ties' standard decimal precisions, increasingly strongly:
 
        o --round=none show amounts with original precisions (default)
 
@@ -7704,31 +7724,38 @@ Standard report commands
 
        o --round=all round all amounts and costs
 
-       soft  is  good  for  non-lossy cleanup, formatting amounts more consis-
+       soft is good for non-lossy cleanup, displaying more consistent decimals
-       tently where it's safe to do so.
+       where possible, without making entries unbalanced.
 
-       hard and all can cause print to show  invalid  unbalanced  journal  en-
+       hard or all can be good for stronger cleanup, when decimal rounding  is
-       tries;  they  may be useful eg for stronger cleanup, with manual fixups
+       wanted.   Note rounding can produce unbalanced journal entries, perhaps
-       when needed.
+       requiring manual fixup.
 
    print parseability
-       print's output is usually a valid hledger journal, and you can  process
+       Normally, print's output is a valid  hledger  journal,  which  you  can
-       it again with a second hledger command.  This can be useful for certain
+       "pipe"  to  a  second  hledger command for further processing.  This is
-       kinds  of  search  (though  the same can be achieved with expr: queries
+       sometimes convenient for achieving certain kinds of query (though  less
-       now):
+       needed now that queries have become more powerful):
 
               # Show running total of food expenses paid from cash.
               # -f- reads from stdin. -I/--ignore-assertions is sometimes needed.
               $ hledger print assets:cash | hledger -f- -I reg expenses:food
 
-       There are some situations where print's output can become unparseable:
+       But  here  are some things which can cause print's output to become un-
+       parseable:
 
-       o Value reporting affects posting amounts but not balance assertion  or
+       o --round (see above) can disrupt transaction balancing.
-         balance assignment amounts, potentially causing those to fail.
 
-       o Auto postings can generate postings with too many missing amounts.
+       o Account aliases or pivoting can disrupt account names, balance asser-
+         tions, or balance assignments.
 
-       o Account aliases can generate bad account names.
+       o Value reporting also can disrupt balance assertions  or  balance  as-
+         signments.
+
+       o Auto postings can generate too many amountless postings.
+
+       o --infer-costs  or  --infer-equity  can generate too-complex redundant
+         costs.
 
    print, other features
        With -B/--cost, amounts with costs are shown converted to cost.
@@ -7746,7 +7773,7 @@ Standard report commands
        characters.  If there is no similar-enough match, no  transaction  will
        be shown and the program exit code will be non-zero.
 
-       With --location, print adds the source file and line  number  to  every
+       With  --locations,  print adds the source file and line number to every
        transaction, as a tag.
 
    print output format
@@ -7858,23 +7885,22 @@ Standard report commands
        ister for reviewing and reconciling real-world asset/liability accounts
        - use register for reviewing detailed revenues/expenses.
 
-       aregister requires one argument: the account to  report  on.   You  can
+       Note  this  command's  non-standard,  and  required, first argument; it
-       write  either  the full account name, or a case-insensitive regular ex-
+       specifies the account whose register will be shown.  You can write  the
-       pression which will select the alphabetically first matched account.
+       account's  name,  or  (to save typing) a case-insensitive infix regular
-
+       expression matching the name, which selects  the  alphabetically  first
-       When there are multiple matches, the alphabetically-first choice can be
+       matched  account.   (For  example, if you have assets:personal checking
-       surprising; eg if you have assets:per:checking 1 and  assets:biz:check-
+       and assets:business checking, hledger areg checking  would  select  as-
-       ing  2 accounts, hledger areg checking would select assets:biz:checking
+       sets:business checking.)
-       2.  It's just a convenience to save typing, so if in doubt,  write  the
-       full account name, or a distinctive substring that matches uniquely.
 
        Transactions  involving subaccounts of this account will also be shown.
        aregister ignores depth limits, so its final total will always match  a
        historical balance report with similar arguments.
 
-       Any  additional  arguments  form a query which will filter the transac-
+       Any additional arguments are standard query arguments, which will limit
-       tions shown.  Note some queries will disturb the running balance, caus-
+       the  transactions  shown.   Note  some queries will disturb the running
-       ing it to be different from the account's real-world running balance.
+       balance, causing it to be different from the account's real-world  run-
+       ning balance.
 
        An  example: this shows the transactions and historical running balance
        during july, in the first account whose name contains "checking":
@@ -10713,4 +10739,4 @@ LICENSE
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-1.50.99                 September 2025                      HLEDGER(1)
+hledger-1.50.99                  October 2025                       HLEDGER(1)