;doc: update CLI usage texts

hledger/Hledger/Cli/Commands/Balance.txt

@@ -31,6 +31,7 @@ balance can show..
 -   or actual and planned balance changes (--budget)
 -   or value of balance changes (-V)
 -   or change of balance values (--valuechange)
+-   or unrealised capital gain/loss (--gain)
 
 ..in..
 
@@ -75,9 +76,9 @@ should also match their end balance at the end of the journal period
 (more on this below).
 
 Accounts are sorted by declaration order if any, and then alphabetically
-by account name. For instance, using examples/sample.journal:
+by account name. For instance (using examples/sample.journal):
 
-$ hledger bal
+$ hledger -f examples/sample.journal bal
                   $1  assets:bank:saving
                  $-2  assets:cash
                   $1  expenses:food
@@ -92,7 +93,7 @@ Accounts with a zero balance (and no non-zero subaccounts, in tree mode
 - see below) are hidden by default. Use -E/--empty to show them
 (revealing assets:bank:checking here):
 
-$ hledger -f examples/sample.journal  bal  -E
+$ hledger -f examples/sample.journal bal  -E
                    0  assets:bank:checking
                   $1  assets:bank:saving
                  $-2  assets:cash
@@ -113,7 +114,7 @@ You can show fewer accounts, a different time period, totals from
 cleared transactions only, etc. by using query arguments or options to
 limit the postings being matched. Eg:
 
-$ hledger bal --cleared assets date:200806
+$ hledger -f examples/sample.journal bal --cleared assets date:200806
                  $-2  assets:cash
 --------------------
                  $-2  
@@ -126,7 +127,7 @@ their full names visible, as in the examples above.
 With -t/--tree, the account hierarchy is shown, with subaccounts' "leaf"
 names indented below their parent:
 
-$ hledger balance
+$ hledger -f examples/sample.journal balance
                  $-1  assets
                   $1    bank:saving
                  $-2    cash
@@ -159,22 +160,29 @@ Notes:
 
 Depth limiting
 
-With a depth:N query, or --depth N option, or just -N, balance reports
+With a depth:NUM query, or --depth NUM option, or just -NUM (eg: -3)
-will show accounts only to the specified depth, hiding the deeper
+balance reports will show accounts only to the specified depth, hiding
-subaccounts. Account balances at the depth limit always include the
+the deeper subaccounts. This can be useful for getting an overview
-balances from any hidden subaccounts (even in list mode). This can be
+without too much detail.
-useful for getting an overview. Eg, limiting to depth 1:
 
-$ hledger balance -N -1
+Account balances at the depth limit always include the balances from any
+deeper subaccounts (even in list mode). Eg, limiting to depth 1:
+
+$ hledger -f examples/sample.journal balance -1
                  $-1  assets
                   $2  expenses
                  $-2  income
                   $1  liabilities
+--------------------
+                   0  
 
-You can also hide top-level account name parts, using --drop N. This can
+Dropping top-level accounts
-be useful for hiding repetitive top-level account names:
 
-$ hledger bal expenses --drop 1
+You can also hide one or more top-level account name parts, using
+--drop NUM. This can be useful for hiding repetitive top-level account
+names:
+
+$ hledger -f examples/sample.journal bal expenses --drop 1
                   $1  food
                   $1  supplies
 --------------------
@@ -187,7 +195,7 @@ With a report interval (set by the -D/--daily, -W/--weekly,
 shows a tabular report, with columns representing successive time
 periods (and a title):
 
-$ hledger balance --quarterly income expenses -E
+$ hledger -f examples/sample.journal bal --quarterly income expenses -E
 Balance changes in 2008:
 
                    ||  2008q1  2008q2  2008q3  2008q4 
@@ -306,7 +314,7 @@ Percentages
 With -%/--percent, balance reports show each account's value expressed
 as a percentage of the (column) total:
 
-$ hledger bal expenses -Q -%
+$ hledger -f examples/sample.journal bal expenses -Q -%
 Balance changes in 2008:
 
                    || 2008Q1   2008Q2  2008Q3  2008Q4 
@@ -382,7 +390,10 @@ The basic calculation to perform for each table cell. It is one of:
 -   --sum : sum the posting amounts (default)
 -   --budget : like --sum but also show a goal amount
 -   --valuechange : show the change in period-end historical balance
-    values
+    values (caused by deposits, withdrawals, and/or market price
+    fluctuations)
+-   --gain : show the unrealised capital gain/loss, (the current valued
+    balance minus each amount's original cost)
 
 Accumulation type:
 Which postings should be included in each cell's calculation. It is one
@@ -409,7 +420,7 @@ valuation commodity to use. It is one of:
 -   --value=cost[,COMM] : no valuation, show amounts converted to cost
 -   --value=then[,COMM] : show value at transaction dates
 -   --value=end[,COMM] : show value at period end date(s) (default with
-    --valuechange)
+    --valuechange, --gain)
 -   --value=now[,COMM] : show value at today's date
 -   --value=YYYY-MM-DD[,COMM] : show value at another date
 
@@ -752,7 +763,7 @@ For single-period balance reports displayed in the terminal (only), you
 can use --format FMT to customise the format and content of each line.
 Eg:
 
-$ hledger balance --format "%20(account) %12(total)"
+$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"
               assets          $-1
          bank:saving           $1
                 cash          $-2

hledger/Hledger/Cli/Commands/Close.txt

@@ -54,14 +54,17 @@ whichever is later.
 
 Unless you are running close on exactly the first day of the new period,
 you'll want to override the closing date. This is done by specifying a
-report period, where "last day of the report period" will be the closing
+report end date, where "last day of the report period" will be the
-date. The opening date is always the following day. So to close on
+closing date. The opening date is always the following day. So to close
-2020-12-31 and open on 2021-01-01, any of these work
+on (end of) 2020-12-31 and open on (start of) 2021-01-01, any of these
+will work:
 
--   -p 2020
+  end date argument   explanation
--   date:2020
+  ------------------- ------------------------------------------------
--   -e 2021-01-01 (remember -e specifies an exclusive end date)
+  -e 2021-01-01       end dates are exclusive
--   -e 2021
+  -e 2021             equivalent, per smart dates
+  -p 2020             equivalent, the period's begin date is ignored
+  date:2020           equivalent query
 
 Example: close asset/liability accounts for file transition
 
@@ -103,17 +106,17 @@ transactions, like this:
 ; 2019.journal
 2019-01-01 opening balances  ; earliest opening txn, no tag here
 ...
-2019-12-31 closing balances  ; close:2019
+2019-12-31 closing balances  ; clopen:2020
 ...
 
 ; 2020.journal
-2020-01-01 opening balances  ; open:2020
+2020-01-01 opening balances  ; clopen:2020
 ...
-2020-12-31 closing balances  ; close:2020
+2020-12-31 closing balances  ; clopen:2021
 ...
 
 ; 2021.journal
-2021-01-01 opening balances  ; open:2021
+2021-01-01 opening balances  ; clopen:2021
 ...
 
 Now with
@@ -125,15 +128,12 @@ include 2021.journal
 
 you could do eg:
 
-$ hledger -f all.journal reg -H checking not:tag:'open|close'
+$ hledger -f all.journal reg -H checking not:tag:clopen
     # all years checking register, hiding non-essential opening/closing txns
 
-$ hledger -f all.journal bs -p 2020 not:tag:close=2020
+$ hledger -f all.journal bs -p 2020 not:tag:clopen=2020
     # 2020 year end balances, suppressing 2020 closing txn
 
-$ hledger -f 2020.journal bs not:tag:close
-    # 2020 year end balances, easier case
-
 close and balance assertions
 
 The closing and opening transactions will include balance assertions,
@@ -171,22 +171,27 @@ single-day transactions):
 
 Example: close revenue/expense accounts to retained earnings
 
-Here, the opening transaction is supressed with --close, as it's
+For this, use --close to suppress the opening transaction, as it's not
-probably not needed. Also you'll want to use a different equity account
+needed. Also you'll want to change the equity account name to your
-name:
+equivalent of "equity:retained earnings".
 
-$ hledger close -f 2021.journal -p 2021Q1 --close --close-acct='equity:retained earnings' revenues expenses >> 2021.journal
+Closing 2021's first quarter revenues/expenses:
-    # close 2021 first quarter revenues/expenses
 
-Or, operating on the default journal:
+$ hledger close -f 2021.journal --close revenues expenses -p 2021Q1 \
+    --close-acct='equity:retained earnings' >> 2021.journal
 
-$ hledger close -p Q1 --close --close-acct='equity:retained earnings' revenues expenses >> $LEDGER_FILE
+The same, using the default journal and current year:
-    # close current year's first quarter revenues/expenses
 
-Now, eg:
+$ hledger close --close revenues expenses -p Q1 \
+    --close-acct='equity:retained earnings' >> $LEDGER_FILE
+
+Now, the first quarter's balance sheet should show a zero (unless you
+are using @/@@ notation without equity postings):
 
 $ hledger bse -p Q1
-    # Q1 full balance sheet, total should be zero
 
-$ hledger is -p Q1 not:'retained earnings'
+And we must suppress the closing transaction to see the first quarter's
-    # Q1 income statement, must suppress the closing txn
+income statement (using the description; not:'retained earnings' won't
+work here):
+
+$ hledger is -p Q1 not:desc:'closing balances'

hledger/Hledger/Cli/Commands/Help.txt

@@ -1,8 +1,12 @@
 help
 Show the hledger user manual in one of several formats, optionally
-positioned at a given TOPIC (if possible). TOPIC is any heading, or
+positioned at a given TOPIC (if possible).
-heading prefix, in the manual. Some examples: commands, print, 'auto
+
-postings', periodic.
+TOPIC is any heading in the manual, or the start of any heading (but not
+the middle). It is case insensitive.
+
+Some examples: commands, print, forecast, "auto postings",
+"commodity column".
 
 _FLAGS