;doc: update manuals

hledger-ui/hledger-ui.1

@@ -302,12 +302,6 @@ There\[aq]s not yet any visual reminder when cost or value mode is
 active; for now pressing \f[C]b\f[R] \f[C]b\f[R] \f[C]v\f[R] should
 reliably reset to normal mode.
 .PP
-With \f[C]--watch\f[R] active, if you save an edit to the journal file
-while viewing the transaction screen in cost or value mode, the
-\f[C]B\f[R]/\f[C]V\f[R] keys will stop working.
-To work around, press \f[C]g\f[R] to force a manual reload, or exit the
-transaction screen.
-.PP
 \f[C]q\f[R] quits the application.
 .PP
 Additional screen-specific keys are described below.
@@ -439,6 +433,58 @@ when you press g to reload.
 Once you have fixed the problem, press g again to reload and resume
 normal operation.
 (Or, you can press escape to cancel the reload attempt.)
+.SH TIPS
+.SS Watch mode
+.PP
+One of hledger-ui\[aq]s best features is the auto-reloading
+\f[C]--watch\f[R] mode.
+With this flag, it will update the display automatically whenever
+changes are saved to the data files.
+.PP
+This is very useful when reconciling.
+A good workflow is to have your bank\[aq]s online register open in a
+browser window, for reference; the journal file open in an editor
+window; and hledger-ui in watch mode in a terminal window, eg:
+.IP
+.nf
+\f[C]
+$ hledger-ui --watch --register checking -C
+\f[R]
+.fi
+.PP
+As you mark things cleared in the editor, you can see the effect
+immediately without having to context switch.
+This leaves more mental bandwidth for your accounting.
+Of course you can still interact with hledger-ui when needed, eg to
+toggle cleared mode, or to explore the history.
+.SS Watch mode limitations
+.PP
+There are situations in which it won\[aq]t work, ie the display will not
+update when you save a change (because the underlying \f[C]inotify\f[R]
+library does not support it).
+Here are some that we know of:
+.IP \[bu] 2
+Certain editors: saving with \f[C]gedit\f[R], and perhaps any Gnome
+application, won\[aq]t be detected (#1617).
+Jetbrains IDEs, such as IDEA, also may not work (#911).
+.IP \[bu] 2
+Certain unusual filesystems might not be supported.
+(All the usual ones on unix, mac and windows are supported.)
+.PP
+In such cases, the workaround is to switch to the hledger-ui window and
+press \f[C]g\f[R] each time you want it to reload.
+(Actually, see #1617 for another workaround, and let us know if it works
+for you.)
+.PP
+If you leave \f[C]hledger-ui --watch\f[R] running for days, on certain
+platforms (?), perhaps with many transactions in your journal (?),
+perhaps with large numbers of other files present (?), you may see it
+gradually using more and more memory and CPU over time, as seen in
+\f[C]top\f[R] or Activity Monitor or Task Manager.
+.PP
+A workaround is to \f[C]q\f[R]uit and restart it, or to suspend it
+(\f[C]CTRL-z\f[R]) and restart it (\f[C]fg\f[R]) if your shell supports
+that.
 .SH ENVIRONMENT
 .PP
 \f[B]COLUMNS\f[R] The screen width to use.

hledger-ui/hledger-ui.info

@@ -3,7 +3,7 @@ from stdin.
 
 INFO-DIR-SECTION User Applications
 START-INFO-DIR-ENTRY
-* hledger-ui: (hledger-ui/hledger-ui).  Terminal UI for the hledger accounting tool.
+* hledger-ui: (hledger-ui).  Terminal UI for the hledger accounting tool.
 END-INFO-DIR-ENTRY
 
 
@@ -45,6 +45,7 @@ enable "forecast mode".
 * OPTIONS::
 * KEYS::
 * SCREENS::
+* TIPS::
 * ENVIRONMENT::
 * FILES::
 * BUGS::
@@ -308,17 +309,12 @@ screen, press `/', and add `date:-7/30' to the query.
 active; for now pressing `b' `b' `v' should reliably reset to normal
 mode.
 
-   With `--watch' active, if you save an edit to the journal file while
-viewing the transaction screen in cost or value mode, the `B'/`V' keys
-will stop working. To work around, press `g' to force a manual reload,
-or exit the transaction screen.
-
    `q' quits the application.
 
    Additional screen-specific keys are described below.
 
 
-File: hledger-ui.info,  Node: SCREENS,  Next: ENVIRONMENT,  Prev: KEYS,  Up: Top
+File: hledger-ui.info,  Node: SCREENS,  Next: TIPS,  Prev: KEYS,  Up: Top
 
 3 SCREENS
 *********
@@ -463,9 +459,75 @@ again to reload and resume normal operation. (Or, you can press escape
 to cancel the reload attempt.)
 
 
-File: hledger-ui.info,  Node: ENVIRONMENT,  Next: FILES,  Prev: SCREENS,  Up: Top
+File: hledger-ui.info,  Node: TIPS,  Next: ENVIRONMENT,  Prev: SCREENS,  Up: Top
 
-4 ENVIRONMENT
+4 TIPS
+******
+
+* Menu:
+
+* Watch mode::
+* Watch mode limitations::
+
+
+File: hledger-ui.info,  Node: Watch mode,  Next: Watch mode limitations,  Up: TIPS
+
+4.1 Watch mode
+==============
+
+One of hledger-ui's best features is the auto-reloading `--watch' mode.
+With this flag, it will update the display automatically whenever
+changes are saved to the data files.
+
+   This is very useful when reconciling. A good workflow is to have your
+bank's online register open in a browser window, for reference; the
+journal file open in an editor window; and hledger-ui in watch mode in a
+terminal window, eg:
+
+
+$ hledger-ui --watch --register checking -C
+
+   As you mark things cleared in the editor, you can see the effect
+immediately without having to context switch. This leaves more mental
+bandwidth for your accounting. Of course you can still interact with
+hledger-ui when needed, eg to toggle cleared mode, or to explore the
+history.
+
+
+File: hledger-ui.info,  Node: Watch mode limitations,  Prev: Watch mode,  Up: TIPS
+
+4.2 Watch mode limitations
+==========================
+
+There are situations in which it won't work, ie the display will not
+update when you save a change (because the underlying `inotify' library
+does not support it). Here are some that we know of:
+
+   * Certain editors: saving with `gedit', and perhaps any Gnome
+     application, won't be detected (#1617). Jetbrains IDEs, such as
+     IDEA, also may not work (#911).
+
+   * Certain unusual filesystems might not be supported. (All the usual
+     ones on unix, mac and windows are supported.)
+
+
+   In such cases, the workaround is to switch to the hledger-ui window
+and press `g' each time you want it to reload. (Actually, see #1617 for
+another workaround, and let us know if it works for you.)
+
+   If you leave `hledger-ui --watch' running for days, on certain
+platforms (?), perhaps with many transactions in your journal (?),
+perhaps with large numbers of other files present (?), you may see it
+gradually using more and more memory and CPU over time, as seen in
+`top' or Activity Monitor or Task Manager.
+
+   A workaround is to `q'uit and restart it, or to suspend it
+(`CTRL-z') and restart it (`fg') if your shell supports that.
+
+
+File: hledger-ui.info,  Node: ENVIRONMENT,  Next: FILES,  Prev: TIPS,  Up: Top
+
+5 ENVIRONMENT
 *************
 
 *COLUMNS* The screen width to use. Default: the full terminal width.
@@ -494,7 +556,7 @@ GUI (say, an Emacs dock icon). Eg on MacOS Catalina I have a
 
 File: hledger-ui.info,  Node: FILES,  Next: BUGS,  Prev: ENVIRONMENT,  Up: Top
 
-5 FILES
+6 FILES
 *******
 
 Reads data from one or more files in hledger journal, timeclock,
@@ -505,7 +567,7 @@ timedot, or CSV format specified with `-f', or `$LEDGER_FILE', or
 
 File: hledger-ui.info,  Node: BUGS,  Prev: FILES,  Up: Top
 
-6 BUGS
+7 BUGS
 ******
 
 The need to precede options with `--' when invoked from hledger is
@@ -533,26 +595,32 @@ program is restarted.
 
 
 Tag Table:
-Node: Top243
+Node: Top232
-Node: OPTIONS1636
+Node: OPTIONS1634
-Ref: #options1733
+Ref: #options1731
-Node: KEYS6128
+Node: KEYS6126
-Ref: #keys6223
+Ref: #keys6221
-Node: SCREENS10519
+Node: SCREENS10270
-Ref: #screens10624
+Ref: #screens10368
-Node: Accounts screen10714
+Node: Accounts screen10458
-Ref: #accounts-screen10842
+Ref: #accounts-screen10586
-Node: Register screen13046
+Node: Register screen12790
-Ref: #register-screen13201
+Ref: #register-screen12945
-Node: Transaction screen15196
+Node: Transaction screen14940
-Ref: #transaction-screen15354
+Ref: #transaction-screen15098
-Node: Error screen16221
+Node: Error screen15965
-Ref: #error-screen16343
+Ref: #error-screen16087
-Node: ENVIRONMENT16585
+Node: TIPS16329
-Ref: #environment16699
+Ref: #tips16428
-Node: FILES17504
+Node: Watch mode16480
-Ref: #files17603
+Ref: #watch-mode16597
-Node: BUGS17816
+Node: Watch mode limitations17341
-Ref: #bugs17893
+Ref: #watch-mode-limitations17482
+Node: ENVIRONMENT18615
+Ref: #environment18726
+Node: FILES19531
+Ref: #files19630
+Node: BUGS19843
+Ref: #bugs19920
 
 End Tag Table

hledger-ui/hledger-ui.txt

@@ -276,55 +276,50 @@ KEYS
        There's not yet any visual reminder when cost or value mode is  active;
        for now pressing b b v should reliably reset to normal mode.
 
-       With  --watch  active,  if  you  save an edit to the journal file while
-       viewing the transaction screen in cost or value mode, the B/V keys will
-       stop  working.   To  work  around, press g to force a manual reload, or
-       exit the transaction screen.
-
        q quits the application.
 
        Additional screen-specific keys are described below.
 
 SCREENS
    Accounts screen
-       This is normally the first screen displayed.   It  lists  accounts  and
+       This  is  normally  the  first screen displayed.  It lists accounts and
-       their  balances,  like hledger's balance command.  By default, it shows
+       their balances, like hledger's balance command.  By default,  it  shows
-       all accounts and their latest ending balances (including  the  balances
+       all  accounts  and their latest ending balances (including the balances
-       of  subaccounts).  If you specify a query on the command line, it shows
+       of subaccounts).  If you specify a query on the command line, it  shows
        just the matched accounts and the balances from matched transactions.
 
-       Account names are shown as a flat list by default; press  t  to  toggle
+       Account  names  are  shown as a flat list by default; press t to toggle
-       tree  mode.   In  list  mode,  account balances are exclusive of subac-
+       tree mode.  In list mode, account  balances  are  exclusive  of  subac-
-       counts, except where subaccounts are  hidden  by  a  depth  limit  (see
+       counts,  except  where  subaccounts  are  hidden  by a depth limit (see
-       below).   In  tree  mode,  all account balances are inclusive of subac-
+       below).  In tree mode, all account balances  are  inclusive  of  subac-
        counts.
 
-       To see less detail, press a number key, 1 to 9, to set a  depth  limit.
+       To  see  less detail, press a number key, 1 to 9, to set a depth limit.
        Or use - to decrease and +/= to increase the depth limit.  0 shows even
-       less detail, collapsing all accounts to a single total.  To remove  the
+       less  detail, collapsing all accounts to a single total.  To remove the
-       depth  limit,  set  it  higher than the maximum account depth, or press
+       depth limit, set it higher than the maximum  account  depth,  or  press
        ESCAPE.
 
        H toggles between showing historical balances or period balances.  His-
-       torical  balances  (the  default) are ending balances at the end of the
+       torical balances (the default) are ending balances at the  end  of  the
-       report period, taking into account all transactions  before  that  date
+       report  period,  taking  into account all transactions before that date
-       (filtered  by  the  filter query if any), including transactions before
+       (filtered by the filter query if any),  including  transactions  before
-       the start of the report period.  In other  words,  historical  balances
+       the  start  of  the report period.  In other words, historical balances
-       are  what  you  would  see on a bank statement for that account (unless
+       are what you would see on a bank statement  for  that  account  (unless
-       disturbed by a filter  query).   Period  balances  ignore  transactions
+       disturbed  by  a  filter  query).   Period balances ignore transactions
        before the report start date, so they show the change in balance during
        the report period.  They are more useful eg when viewing a time log.
 
        U toggles filtering by unmarked status, including or excluding unmarked
        postings in the balances.  Similarly, P toggles pending postings, and C
-       toggles cleared postings.  (By default, balances include all  postings;
+       toggles  cleared postings.  (By default, balances include all postings;
-       if  you  activate  one  or  two status filters, only those postings are
+       if you activate one or two status  filters,  only  those  postings  are
        included; and if you activate all three, the filter is removed.)
 
        R toggles real mode, in which virtual postings are ignored.
 
-       Z toggles nonzero mode, in which only accounts  with  nonzero  balances
+       Z  toggles  nonzero  mode, in which only accounts with nonzero balances
-       are  shown (hledger-ui shows zero items by default, unlike command-line
+       are shown (hledger-ui shows zero items by default, unlike  command-line
        hledger).
 
        Press right or enter to view an account's transactions register.
@@ -333,66 +328,110 @@ SCREENS
        This screen shows the transactions affecting a particular account, like
        a check register.  Each line represents one transaction and shows:
 
-       o the  other  account(s)  involved, in abbreviated form.  (If there are
+       o the other account(s) involved, in abbreviated form.   (If  there  are
-         both real and virtual postings, it shows only the  accounts  affected
+         both  real  and virtual postings, it shows only the accounts affected
          by real postings.)
 
-       o the  overall change to the current account's balance; positive for an
+       o the overall change to the current account's balance; positive for  an
          inflow to this account, negative for an outflow.
 
        o the running historical total or period total for the current account,
-         after  the  transaction.  This can be toggled with H.  Similar to the
+         after the transaction.  This can be toggled with H.  Similar  to  the
-         accounts screen, the historical total  is  affected  by  transactions
+         accounts  screen,  the  historical  total is affected by transactions
-         (filtered  by  the  filter query) before the report start date, while
+         (filtered by the filter query) before the report  start  date,  while
          the period total is not.  If the historical total is not disturbed by
-         a  filter  query, it will be the running historical balance you would
+         a filter query, it will be the running historical balance  you  would
          see on a bank register for the current account.
 
-       Transactions affecting this account's subaccounts will be  included  in
+       Transactions  affecting  this account's subaccounts will be included in
        the register if the accounts screen is in tree mode, or if it's in list
-       mode but this account has subaccounts which are  not  shown  due  to  a
+       mode  but  this  account  has  subaccounts which are not shown due to a
-       depth  limit.   In  other words, the register always shows the transac-
+       depth limit.  In other words, the register always  shows  the  transac-
-       tions contributing to the balance shown on the accounts  screen.   Tree
+       tions  contributing  to the balance shown on the accounts screen.  Tree
        mode/list mode can be toggled with t here also.
 
-       U  toggles  filtering  by  unmarked  status, showing or hiding unmarked
+       U toggles filtering by unmarked  status,  showing  or  hiding  unmarked
        transactions.  Similarly, P toggles pending transactions, and C toggles
-       cleared  transactions.  (By default, transactions with all statuses are
+       cleared transactions.  (By default, transactions with all statuses  are
-       shown; if you activate one or two status filters, only  those  transac-
+       shown;  if  you activate one or two status filters, only those transac-
        tions are shown; and if you activate all three, the filter is removed.)
 
        R toggles real mode, in which virtual postings are ignored.
 
-       Z toggles nonzero mode, in which only transactions  posting  a  nonzero
+       Z  toggles  nonzero  mode, in which only transactions posting a nonzero
-       change  are  shown (hledger-ui shows zero items by default, unlike com-
+       change are shown (hledger-ui shows zero items by default,  unlike  com-
        mand-line hledger).
 
        Press right (or enter) to view the selected transaction in detail.
 
    Transaction screen
-       This screen shows a single transaction, as  a  general  journal  entry,
+       This  screen  shows  a  single transaction, as a general journal entry,
-       similar  to  hledger's  print command and journal format (hledger_jour-
+       similar to hledger's print command and  journal  format  (hledger_jour-
        nal(5)).
 
-       The transaction's date(s)  and  any  cleared  flag,  transaction  code,
+       The  transaction's  date(s)  and  any  cleared  flag, transaction code,
-       description,  comments,  along  with  all  of  its account postings are
+       description, comments, along with  all  of  its  account  postings  are
-       shown.  Simple transactions have two postings, but there  can  be  more
+       shown.   Simple  transactions  have two postings, but there can be more
        (or in certain cases, fewer).
 
-       up  and  down will step through all transactions listed in the previous
+       up and down will step through all transactions listed in  the  previous
-       account register screen.  In the title bar, the numbers in  parentheses
+       account  register screen.  In the title bar, the numbers in parentheses
-       show  your  position  within  that  account  register.   They will vary
+       show your position  within  that  account  register.   They  will  vary
        depending on which account register you came from (remember most trans-
        actions appear in multiple account registers).  The #N number preceding
        them is the transaction's position within the complete unfiltered jour-
        nal, which is a more stable id (at least until the next reload).
 
    Error screen
-       This  screen  will appear if there is a problem, such as a parse error,
+       This screen will appear if there is a problem, such as a  parse  error,
-       when you press g to reload.  Once you have fixed the problem,  press  g
+       when  you  press g to reload.  Once you have fixed the problem, press g
        again to reload and resume normal operation.  (Or, you can press escape
        to cancel the reload attempt.)
 
+TIPS
+   Watch mode
+       One  of  hledger-ui's best features is the auto-reloading --watch mode.
+       With this flag, it  will  update  the  display  automatically  whenever
+       changes are saved to the data files.
+
+       This  is very useful when reconciling.  A good workflow is to have your
+       bank's online register open in a browser  window,  for  reference;  the
+       journal  file open in an editor window; and hledger-ui in watch mode in
+       a terminal window, eg:
+
+              $ hledger-ui --watch --register checking -C
+
+       As you mark things cleared in the editor, you can see the effect  imme-
+       diately  without  having  to  context  switch.  This leaves more mental
+       bandwidth for your accounting.  Of course you can still  interact  with
+       hledger-ui  when  needed,  eg to toggle cleared mode, or to explore the
+       history.
+
+   Watch mode limitations
+       There are situations in which it won't work, ie the  display  will  not
+       update  when  you save a change (because the underlying inotify library
+       does not support it).  Here are some that we know of:
+
+       o Certain editors: saving with gedit, and perhaps  any  Gnome  applica-
+         tion,  won't be detected (#1617).  Jetbrains IDEs, such as IDEA, also
+         may not work (#911).
+
+       o Certain unusual filesystems might not be supported.  (All  the  usual
+         ones on unix, mac and windows are supported.)
+
+       In such cases, the workaround is to switch to the hledger-ui window and
+       press g each time you want it to  reload.   (Actually,  see  #1617  for
+       another workaround, and let us know if it works for you.)
+
+       If  you leave hledger-ui --watch running for days, on certain platforms
+       (?), perhaps with many transactions in your journal (?),  perhaps  with
+       large  numbers  of  other  files  present (?), you may see it gradually
+       using more and more memory and CPU over time, as seen in top or  Activ-
+       ity Monitor or Task Manager.
+
+       A  workaround  is to quit and restart it, or to suspend it (CTRL-z) and
+       restart it (fg) if your shell supports that.
+
 ENVIRONMENT
        COLUMNS The screen width to use.  Default: the full terminal width.
 

hledger-web/hledger-web.info

@@ -3,7 +3,7 @@ from stdin.
 
 INFO-DIR-SECTION User Applications
 START-INFO-DIR-ENTRY
-* hledger-web: (hledger-web/hledger-web).  Web UI/API for the hledger accounting tool.
+* hledger-web: (hledger-web).  Web UI/API for the hledger accounting tool.
 END-INFO-DIR-ENTRY
 
 
@@ -612,22 +612,22 @@ awkward.
 
 
 Tag Table:
-Node: Top247
+Node: Top235
-Node: OPTIONS1887
+Node: OPTIONS1875
-Ref: #options1992
+Ref: #options1980
-Node: PERMISSIONS9405
+Node: PERMISSIONS9393
-Ref: #permissions9544
+Ref: #permissions9532
-Node: EDITING UPLOADING DOWNLOADING10756
+Node: EDITING UPLOADING DOWNLOADING10744
-Ref: #editing-uploading-downloading10937
+Ref: #editing-uploading-downloading10925
-Node: RELOADING11768
+Node: RELOADING11756
-Ref: #reloading11902
+Ref: #reloading11890
-Node: JSON API12334
+Node: JSON API12322
-Ref: #json-api12448
+Ref: #json-api12436
-Node: ENVIRONMENT17937
+Node: ENVIRONMENT17925
-Ref: #environment18053
+Ref: #environment18041
-Node: FILES18785
+Node: FILES18773
-Ref: #files18885
+Ref: #files18873
-Node: BUGS19098
+Node: BUGS19086
-Ref: #bugs19176
+Ref: #bugs19164
 
 End Tag Table

hledger/hledger.1

@@ -296,6 +296,11 @@ or:
 $ hledger register credit\[rs] card
 \f[R]
 .fi
+.PP
+Windows users should keep in mind that \f[C]cmd\f[R] treats single quote
+as a regular character, so you should be using double quotes
+exclusively.
+PowerShell treats both single and double quotes as quotes.
 .SS Double escaping (regular expression metacharacters)
 .PP
 Characters significant in regular expressions (described below) - such
@@ -657,6 +662,8 @@ Are all accounts posted to, declared with an \f[C]account\f[R] directive
 .IP \[bu] 2
 Are all commodities declared with a \f[C]commodity\f[R] directive ?
 (Commodity error checking)
+.IP \[bu] 2
+Are all commodity conversions declared explicitly ?
 .PP
 You can also use the check command to run these and some additional
 checks.
@@ -754,6 +761,7 @@ T}@T{
 9+ digits beginning with a valid YYYYMMDD gives an error
 T}
 .TE
+.PP
 .SS Report start & end date
 .PP
 By default, most hledger reports will show the full span of time
@@ -1140,18 +1148,171 @@ This flag has the same effect as a \f[C]depth:\f[R] query argument (so
 \f[C]-2\f[R], \f[C]--depth=2\f[R] or \f[C]depth:2\f[R] are equivalent).
 .SH QUERIES
 .PP
-One of hledger\[aq]s strengths is being able to quickly report on
+One of hledger\[aq]s strengths is being able to quickly report on a
-precise subsets of your data.
+precise subset of your data.
-Most commands accept an optional query expression, written as arguments
+Most hledger commands accept optional query arguments to restrict their
-after the command name, to filter the data by date, account name or
+scope.
-other criteria.
+The syntax is as follows:
-The syntax is similar to a web search: one or more space-separated
+.IP \[bu] 2
-search terms, quotes to enclose whitespace, prefixes to match specific
+Zero or more space-separated query terms.
-fields, a not: prefix to negate the match.
+These are most often account name substrings:
+.RS 2
 .PP
-We do not yet support arbitrary boolean combinations of search terms;
+\f[C]utilities food:groceries\f[R]
-instead most commands show transactions/postings/accounts which match
+.RE
-(or negatively match):
+.IP \[bu] 2
+Terms with spaces or other special characters should be enclosed in
+quotes:
+.RS 2
+.PP
+\f[C]\[dq]personal care\[dq]\f[R]
+.RE
+.IP \[bu] 2
+Regular expressions are also supported:
+.RS 2
+.PP
+\f[C]\[dq]\[ha]expenses\[rs]b\[dq] \[dq]accounts (payable|receivable)\[dq]\f[R]
+.RE
+.IP \[bu] 2
+Add a query type prefix to match other parts of the data:
+.RS 2
+.PP
+\f[C]date:202012- desc:amazon cur:USD amt:\[dq]>100\[dq] status:\f[R]
+.RE
+.IP \[bu] 2
+Add a \f[C]not:\f[R] prefix to negate a term:
+.RS 2
+.PP
+\f[C]not:cur:USD\f[R]
+.RE
+.SS Query types
+.PP
+Here are the types of query term available.
+Remember these can also be prefixed with \f[B]\f[CB]not:\f[B]\f[R] to
+convert them into a negative match.
+.PP
+\f[B]\f[CB]acct:REGEX\f[B], \f[CB]REGEX\f[B]\f[R]
+.PD 0
+.P
+.PD
+Match account names containing this (case insensitive) regular
+expression.
+This is the default query type when there is no prefix, and regular
+expression syntax is typically not needed, so usually we just write an
+account name substring, like \f[C]expenses\f[R] or \f[C]food\f[R].
+.PP
+\f[B]\f[CB]amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N\f[B]\f[R]
+.PD 0
+.P
+.PD
+Match postings with a single-commodity amount equal to, less than, or
+greater than N.
+(Postings with multi-commodity amounts are not tested and will always
+match.) The comparison has two modes: if N is preceded by a + or - sign
+(or is 0), the two signed numbers are compared.
+Otherwise, the absolute magnitudes are compared, ignoring sign.
+.PP
+\f[B]\f[CB]code:REGEX\f[B]\f[R]
+.PD 0
+.P
+.PD
+Match by transaction code (eg check number).
+.PP
+\f[B]\f[CB]cur:REGEX\f[B]\f[R]
+.PD 0
+.P
+.PD
+Match postings or transactions including any amounts whose
+currency/commodity symbol is fully matched by REGEX.
+(For a partial match, use \f[C].*REGEX.*\f[R]).
+Note, to match special characters which are regex-significant, you need
+to escape them with \f[C]\[rs]\f[R].
+And for characters which are significant to your shell you may need one
+more level of escaping.
+So eg to match the dollar sign:
+.PD 0
+.P
+.PD
+\f[C]hledger print cur:\[rs]\[rs]$\f[R].
+.PP
+\f[B]\f[CB]desc:REGEX\f[B]\f[R]
+.PD 0
+.P
+.PD
+Match transaction descriptions.
+.PP
+\f[B]\f[CB]date:PERIODEXPR\f[B]\f[R]
+.PD 0
+.P
+.PD
+Match dates (or with the \f[C]--date2\f[R] flag, secondary dates) within
+the specified period.
+PERIODEXPR is a period expression with no report interval.
+Examples:
+.PD 0
+.P
+.PD
+\f[C]date:2016\f[R], \f[C]date:thismonth\f[R], \f[C]date:2/1-2/15\f[R],
+\f[C]date:2021-07-27..nextquarter\f[R].
+.PP
+\f[B]\f[CB]date2:PERIODEXPR\f[B]\f[R]
+.PD 0
+.P
+.PD
+Match secondary dates within the specified period (independent of the
+\f[C]--date2\f[R] flag).
+.PP
+\f[B]\f[CB]depth:N\f[B]\f[R]
+.PD 0
+.P
+.PD
+Match (or display, depending on command) accounts at or above this
+depth.
+.PP
+\f[B]\f[CB]note:REGEX\f[B]\f[R]
+.PD 0
+.P
+.PD
+Match transaction notes (the part of the description right of
+\f[C]|\f[R], or the whole description if there\[aq]s no \f[C]|\f[R]).
+.PP
+\f[B]\f[CB]payee:REGEX\f[B]\f[R]
+.PD 0
+.P
+.PD
+Match transaction payee/payer names (the part of the description left of
+\f[C]|\f[R], or the whole description if there\[aq]s no \f[C]|\f[R]).
+.PP
+\f[B]\f[CB]real:, real:0\f[B]\f[R]
+.PD 0
+.P
+.PD
+Match real or virtual postings respectively.
+.PP
+\f[B]\f[CB]status:, status:!, status:*\f[B]\f[R]
+.PD 0
+.P
+.PD
+Match unmarked, pending, or cleared transactions respectively.
+.PP
+\f[B]\f[CB]tag:REGEX[=REGEX]\f[B]\f[R]
+.PD 0
+.P
+.PD
+Match by tag name, and optionally also by tag value.
+(To match only by value, use \f[C]tag:.=REGEX\f[R].) Note that postings
+also inherit tags from their transaction, and transactions also acquire
+tags from their postings, when querying.
+.PP
+(\f[B]\f[CB]inacct:ACCTNAME\f[B]\f[R]
+.PD 0
+.P
+.PD
+A special query term used automatically in hledger-web only: tells
+hledger-web to show the transaction register for an account.)
+.SS Combining query terms
+.PP
+Most commands select things which match:
 .IP \[bu] 2
 any of the description terms AND
 .IP \[bu] 2
@@ -1161,7 +1322,7 @@ any of the status terms AND
 .IP \[bu] 2
 all the other terms.
 .PP
-The print command instead shows transactions which:
+while the print command shows transactions which:
 .IP \[bu] 2
 match any of the description terms AND
 .IP \[bu] 2
@@ -1171,89 +1332,49 @@ have no postings matching any of the negative account terms AND
 .IP \[bu] 2
 match all the other terms.
 .PP
-The following kinds of search terms can be used.
+You can do more powerful queries (such as AND-ing two like terms) by
-Remember these can also be prefixed with \f[B]\f[CB]not:\f[B]\f[R], eg
+running a first query with \f[C]print\f[R], and piping the result into a
-to exclude a particular subaccount.
+second hledger command.
-.TP
+Eg: how much of food expenses was paid with cash ?
-\f[B]\f[R]\f[C]REGEX\f[R]\f[B], \f[R]\f[C]acct:REGEX\f[R]\f[B]\f[R]
+.IP
-match account names by this regular expression.
+.nf
-(With no prefix, \f[C]acct:\f[R] is assumed.)
+\f[C]
-same as above
+$ hledger print assets:cash | hledger f- -I balance expenses:food
-.TP
+\f[R]
-\f[B]\f[R]\f[C]amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N\f[R]\f[B]\f[R]
+.fi
-match postings with a single-commodity amount that is equal to, less
-than, or greater than N.
-(Multi-commodity amounts are not tested, and will always match.) The
-comparison has two modes: if N is preceded by a + or - sign (or is 0),
-the two signed numbers are compared.
-Otherwise, the absolute magnitudes are compared, ignoring sign.
-.TP
-\f[B]\f[R]\f[C]code:REGEX\f[R]\f[B]\f[R]
-match by transaction code (eg check number)
-.TP
-\f[B]\f[R]\f[C]cur:REGEX\f[R]\f[B]\f[R]
-match postings or transactions including any amounts whose
-currency/commodity symbol is fully matched by REGEX.
-(For a partial match, use \f[C].*REGEX.*\f[R]).
-Note, to match characters which are regex-significant, like the dollar
-sign (\f[C]$\f[R]), you need to prepend \f[C]\[rs]\f[R].
-And when using the command line you need to add one more level of
-quoting to hide it from the shell, so eg do:
-\f[C]hledger print cur:\[aq]\[rs]$\[aq]\f[R] or
-\f[C]hledger print cur:\[rs]\[rs]$\f[R].
-.TP
-\f[B]\f[R]\f[C]desc:REGEX\f[R]\f[B]\f[R]
-match transaction descriptions.
-.TP
-\f[B]\f[R]\f[C]date:PERIODEXPR\f[R]\f[B]\f[R]
-match dates within the specified period.
-PERIODEXPR is a period expression (with no report interval).
-Examples: \f[C]date:2016\f[R], \f[C]date:thismonth\f[R],
-\f[C]date:2000/2/1-2/15\f[R], \f[C]date:lastweek-\f[R].
-If the \f[C]--date2\f[R] command line flag is present, this matches
-secondary dates instead.
-(Report intervals will adjust start/end dates to preceding/following
-subperiod boundaries.)
-.TP
-\f[B]\f[R]\f[C]date2:PERIODEXPR\f[R]\f[B]\f[R]
-match secondary dates within the specified period.
-.TP
-\f[B]\f[R]\f[C]depth:N\f[R]\f[B]\f[R]
-match (or display, depending on command) accounts at or above this depth
-.TP
-\f[B]\f[R]\f[C]note:REGEX\f[R]\f[B]\f[R]
-match transaction notes (part of description right of \f[C]|\f[R], or
-whole description when there\[aq]s no \f[C]|\f[R])
-.TP
-\f[B]\f[R]\f[C]payee:REGEX\f[R]\f[B]\f[R]
-match transaction payee/payer names (part of description left of
-\f[C]|\f[R], or whole description when there\[aq]s no \f[C]|\f[R])
-.TP
-\f[B]\f[R]\f[C]real:, real:0\f[R]\f[B]\f[R]
-match real or virtual postings respectively
-.TP
-\f[B]\f[R]\f[C]status:, status:!, status:*\f[R]\f[B]\f[R]
-match unmarked, pending, or cleared transactions respectively
-.TP
-\f[B]\f[R]\f[C]tag:REGEX[=REGEX]\f[R]\f[B]\f[R]
-match by tag name, and optionally also by tag value.
-Note a tag: query is considered to match a transaction if it matches any
-of the postings.
-Also remember that postings inherit the tags of their parent
-transaction.
 .PP
-The following special search term is used automatically in hledger-web,
+If you are interested in full boolean expressions for queries, see #203.
-only:
+.SS Queries and command options
-.TP
-\f[B]\f[R]\f[C]inacct:ACCTNAME\f[R]\f[B]\f[R]
-tells hledger-web to show the transaction register for this account.
-Can be filtered further with \f[C]acct\f[R] etc.
 .PP
-Some of these can also be expressed as command-line options (eg
+Some queries can also be expressed as command-line options:
-\f[C]depth:2\f[R] is equivalent to \f[C]--depth 2\f[R]).
+\f[C]depth:2\f[R] is equivalent to \f[C]--depth 2\f[R],
-Generally you can mix options and query arguments, and the resulting
+\f[C]date:2020\f[R] is equivalent to \f[C]-p 2020\f[R], etc.
-query will be their intersection (perhaps excluding the
+When you mix command options and query arguments, generally the
-\f[C]-p/--period\f[R] option).
+resulting query is their intersection.
+.SS Queries and account aliases
+.PP
+When account names are rewritten with \f[C]--alias\f[R] or
+\f[C]alias\f[R], \f[C]acct:\f[R] will match either the old or the new
+account name.
+.SS Queries and valuation
+.PP
+When amounts are converted to other commodities in cost or value
+reports, \f[C]cur:\f[R] and \f[C]amt:\f[R] match the old commodity
+symbol and the old amount quantity, not the new ones (except in hledger
+1.22.0 where it\[aq]s reversed, see #1625).
+.SS Querying with account aliases
+.PP
+When account names are rewritten with \f[C]--alias\f[R] or
+\f[C]alias\f[R], note that \f[C]acct:\f[R] will match either the old or
+the new account name.
+.SS Querying with cost or value
+.PP
+When amounts are converted to other commodities in cost or value
+reports, note that \f[C]cur:\f[R] matches the new commodity symbol, and
+not the old one, and \f[C]amt:\f[R] matches the new quantity, and not
+the old one.
+Note: this changed in hledger 1.22, previously it was the reverse, see
+the discussion at #1625.
 .SH COSTING
 .PP
 The \f[C]-B/--cost\f[R] flag converts amounts to their cost or sale
@@ -2783,6 +2904,9 @@ With \f[C]-S/--sort-amount\f[R], accounts with the largest (most
 positive) balances are shown first.
 Eg: \f[C]hledger bal expenses -MAS\f[R] shows your biggest averaged
 monthly expenses first.
+When more than one commodity is present, they will be sorted by the
+alphabetically earliest commodity first, and then by subsequent
+commodities (if an amount is missing a commodity, it is treated as 0).
 .PP
 Revenues and liability balances are typically negative, however, so
 \f[C]-S\f[R] shows these in reverse order.
@@ -3255,7 +3379,7 @@ Budget performance in 2020-01-01..2020-01-15:
                ||     $400 [80% of $500] 
 \f[R]
 .fi
-.SS Nested budgets
+.SS Budgets and subaccounts
 .PP
 You can add budgets to any account in your account hierarchy.
 If you have budgets on both parent account and some of its children,
@@ -3357,6 +3481,34 @@ Budget performance in 2019/01:
                                         ||        0 [                 0] 
 \f[R]
 .fi
+.SS Selecting budget goals
+.PP
+The budget report evaluates periodic transaction rules to generate
+special \[dq]goal transactions\[dq], which generate the goal amounts for
+each account in each report subperiod.
+When troubleshooting, you can use the print command to show these as
+forecasted transactions:
+.IP
+.nf
+\f[C]
+$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated
+\f[R]
+.fi
+.PP
+By default, the budget report uses all available periodic transaction
+rules to generate goals.
+This includes rules with a different report interval from your report.
+Eg if you have daily, weekly and monthly periodic rules, all of these
+will contribute to the goals in a monthly budget report.
+.PP
+You can select a subset of periodic rules by providing an argument to
+the \f[C]--budget\f[R] flag.
+\f[C]--budget=DESCPAT\f[R] will match all periodic rules whose
+description contains DESCPAT, a case-insensitive substring (not a
+regular expression or query).
+This means you can give your periodic rules descriptions (remember that
+two spaces are needed), and then select from multiple budgets defined in
+your journal.
 .SS Customising single-period balance reports
 .PP
 For single-period balance reports displayed in the terminal (only), you
@@ -4871,6 +5023,28 @@ Using roi to compute total return of investment in stocks:
 https://github.com/simonmichael/hledger/blob/master/examples/roi-unrealised.ledger
 .IP \[bu] 2
 Cookbook -> Return on Investment
+.SS Spaces and special characters in \f[C]--inv\f[R] and \f[C]--pnl\f[R]
+.PP
+Note that \f[C]--inv\f[R] and \f[C]--pnl\f[R]\[aq]s argument is a query,
+and queries could have several space-separated terms (see QUERIES).
+.PP
+To indicate that all search terms form single command-line argument, you
+will need to put them in quotes (see Special characters):
+.IP
+.nf
+\f[C]
+$ hledger roi --inv \[aq]term1 term2 term3 ...\[aq]
+\f[R]
+.fi
+.PP
+If any query terms contain spaces themselves, you will need an extra
+level of nested quoting, eg:
+.IP
+.nf
+\f[C]
+$ hledger roi --inv=\[dq]\[aq]Assets:Test 1\[aq]\[dq] --pnl=\[dq]\[aq]Equity:Unrealized Profit and Loss\[aq]\[dq]
+\f[R]
+.fi
 .SS Semantics of \f[C]--inv\f[R] and \f[C]--pnl\f[R]
 .PP
 Query supplied to \f[C]--inv\f[R] has to match all transactions that are