;doc: update command docs

hledger/Hledger/Cli/Commands/Add.txt

@@ -1,6 +1,6 @@
 add
 
-Record new transactions with interactive prompting in the console.
+Add new transactions to a journal file, with interactive prompting.
 
 Flags:
      --no-new-accounts      don't allow creating new accounts
@@ -40,6 +40,8 @@ Notes:
   this symbol for you. It does not do this; we assume that if you are
   using a D directive you prefer not to see the commodity symbol
   repeated on amounts in the journal.
+- add creates entries in journal format; it won't work with timeclock or
+  timedot files.
 
 Examples:
 

hledger/Hledger/Cli/Commands/Aregister.txt

@@ -50,7 +50,7 @@ matches uniquely.
 
 Transactions involving subaccounts of this account will also be shown.
 aregister ignores depth limits, so its final total will always match a
-balance report with similar arguments.
+historical balance report with similar arguments.
 
 Any additional arguments form a query which will filter the transactions
 shown. Note some queries will disturb the running balance, causing it to

hledger/Hledger/Cli/Commands/Demo.txt

@@ -15,9 +15,6 @@ Use the -s/--speed SPEED option to set your preferred playback speed, eg
 -s4 to play at 4x original speed or -s.5 to play at half speed. The
 default speed is 2x.
 
-Other asciinema options can be added following a double dash, eg -- -i.1
-to limit pauses or -- -h to list asciinema's other options.
-
 During playback, several keys are available: SPACE to pause/unpause, .
 to step forward (while paused), CTRL-c quit.
 

hledger/Hledger/Cli/Commands/Import.txt

@@ -23,7 +23,7 @@ $ hledger import bank1-checking.csv bank1-savings.csv
 
 $ hledger import *.csv
 
-Import preview
+Import dry run
 
 It's useful to preview the import by running first with --dry-run, to
 sanity check the range of dates being imported, and to check the effect
@@ -40,7 +40,7 @@ $ hledger import --dry-run bank.csv | hledger -f- -I print unknown
 You could also run this repeatedly to see the effect of edits to your
 conversion rules:
 
-$ watchexec -- 'hledger import --dry-run bank.csv | hledger -f- -I print unknown'
+$ watchexec -- "hledger import --dry-run bank.csv | hledger -f- -I print unknown"
 
 Once the conversion and dates look good enough to import to your
 journal, perhaps with some manual fixups to follow, you would do the
@@ -164,30 +164,53 @@ directives or inferred from the journal's amounts.
 
 Related: CSV > Amount decimal places.
 
+Import archiving
+
+When importing from a CSV rules file (hledger import bank.rules), you
+can use the archive rule to enable automatic archiving of the data file.
+After a successful import, the data file (specified by source) will be
+moved to an archive folder (data/, next to the rules file,
+auto-created), and renamed similar to the rules file, with a date. This
+can be useful for troubleshooting, detecting variations in your banks'
+CSV data, regenerating entries with improved rules, etc.
+
+The archive rule also causes import to handle source glob patterns
+differently: when there are multiple matched files, it will pick the
+oldest, not the newest.
+
 Import special cases
 
-If you have a download whose file name varies, you could rename it to a
-fixed name after each download. Or you could use a CSV source rule with
-a suitable glob pattern, and import from the .rules file instead of the
-data file.
-
-Here's a situation where you would need to run import with care: say you
-download bank.csv, but forget to import it or delete it. And next month
-you download it again. This time your web browser may save it as
-bank (2).csv. So now each of these may have data not included in the
-other. And a source rule with a glob pattern would match only the most
-recent file. So in this case you should import from each one in turn, in
-the correct order, taking care to use the same filename each time:
-
-$ hledger import bank.csv
-$ mv 'bank (2).csv' bank.csv
-$ hledger import bank.csv
+Deduplication
 
 Here are two kinds of "deduplication" which import does not handle (and
-generally should not, since these can happen legitimately in financial
-data):
+should not, because these can happen legitimately in financial data):
 
 - Two or more of the new CSV records are identical, and generate
   identical new journal entries.
 - A new CSV record generates a journal entry identical to one(s) already
   in the journal.
+
+Varying file name
+
+If you have a download whose file name varies, you could rename it to a
+fixed name after each download. Or you could use a CSV source rule with
+a suitable glob pattern, and import from the .rules file.
+
+Multiple versions
+
+Say you download bank.csv, import it, but forget to delete it from your
+downloads folder. The next time you download it, your web browser will
+save it as (eg) bank (2).csv. The source rule's glob patterns are for
+just this situation: instead of specifying source bank.csv, specify
+source bank*.csv. Then hledger -f bank.rules CMD or
+hledger import bank.rules will automatically pick the newest matched
+file (bank (2).csv).
+
+Alternately, what if you download, but forget to import or delete, then
+download again ? Now each of bank.csv and bank (2).csv might contain
+data that's not in the other, and not in your journal. In this case,
+it's best to import each of them in turn, oldest first (otherwise,
+overlap detection could cause new records to be skipped). Enabling
+import archiving ensures this. Then
+hledger import bank.rules; hledger import bank.rules will import and
+archive first bank.csv, then bank (2).csv.

hledger/Hledger/Cli/Commands/Rewrite.txt

@@ -38,10 +38,10 @@ spaces between account and amount.
 
 More:
 
-$ hledger rewrite -- [QUERY]        --add-posting "ACCT  AMTEXPR" ...
-$ hledger rewrite -- ^income        --add-posting '(liabilities:tax)  *.33'
-$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts)  *-1"'
-$ hledger rewrite -- ^income        --add-posting '(budget:foreign currency)  *0.25 JPY; diversify'
+$ hledger rewrite [QUERY]        --add-posting "ACCT  AMTEXPR" ...
+$ hledger rewrite ^income        --add-posting '(liabilities:tax)  *.33'
+$ hledger rewrite expenses:gifts --add-posting '(budget:gifts)  *-1"'
+$ hledger rewrite ^income        --add-posting '(budget:foreign currency)  *0.25 JPY; diversify'
 
 Argument for --add-posting option is a usual posting of transaction with
 an exception for amount specification. More precisely, you can use '*'
@@ -71,12 +71,12 @@ Note that '=' (equality symbol) that is used instead of date in
 transactions you usually write. It indicates the query by which you want
 to match the posting to add new ones.
 
-$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal
+$ hledger rewrite -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal
 
 This is something similar to the commands pipeline:
 
-$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax)  *.33' \
-  | hledger rewrite -- -f - expenses:gifts      --add-posting 'budget:gifts  *-1'       \
+$ hledger rewrite -f input.journal '^income' --add-posting '(liabilities:tax)  *.33' \
+  | hledger rewrite -f - expenses:gifts      --add-posting 'budget:gifts  *-1'       \
                                                 --add-posting 'assets:budget  *1'       \
   > rewritten-tidy-output.journal
 
@@ -89,7 +89,7 @@ Diff output format
 To use this tool for batch modification of your journal files you may
 find useful output in form of unified diff.
 
-$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax)  *.33'
+$ hledger rewrite --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax)  *.33'
 
 Output might look like: