;doc: update command help

hledger/Hledger/Cli/Commands/Add.txt

@@ -36,35 +36,27 @@ Features:
 -   Input prompts are displayed in a different colour when the terminal
     supports it.
 
-Example (see https://hledger.org/add.html for a detailed tutorial):
+Notes:
 
-$ hledger add
+-   If you enter a number with no commodity symbol, and you have
-Adding transactions to journal file /src/hledger/examples/sample.journal
+    declared a default commodity with a D directive, you might expect
-Any command line arguments will be used as defaults.
+    add to add this symbol for you. It does not do this; we assume that
-Use tab key to complete, readline keys to edit, enter to accept defaults.
+    if you are using a D directive you prefer not to see the commodity
-An optional (CODE) may follow transaction dates.
+    symbol repeated on amounts in the journal.
-An optional ; COMMENT may follow descriptions or amounts.
-If you make a mistake, enter < at any prompt to go one step backward.
-To end a transaction, enter . when prompted.
-To quit, enter . at a date prompt or press control-d or control-c.
-Date [2015/05/22]: 
-Description: supermarket
-Account 1: expenses:food
-Amount  1: $10
-Account 2: assets:checking
-Amount  2 [$-10.0]: 
-Account 3 (or . or enter to finish this transaction): .
-2015/05/22 supermarket
-    expenses:food             $10
-    assets:checking        $-10.0
 
-Save this transaction to the journal ? [y]: 
+Examples:
-Saved.
-Starting the next transaction (. or ctrl-D/ctrl-C to quit)
-Date [2015/05/22]: <CTRL-D> $
 
-If you enter a number with no commodity symbol, and you have declared a
+-   Record new transactions, saving to the default journal file:
-default commodity with a D directive, you might expect add to add this
+
-symbol for you. It does not do this; we assume that if you are using a D
+    hledger add
-directive you prefer not to see the commodity symbol repeated on amounts
+
-in the journal.
+-   Add transactions to 2024.journal, but also load 2023.journal for
+    completions:
+
+    hledger add --file 2024.journal --file 2023.journal
+
+-   Provide answers for the first four prompts:
+
+    hledger add today 'best buy' expenses:supplies '$20'
+
+There is a detailed tutorial at https://hledger.org/add.html.

hledger/Hledger/Cli/Commands/Balance.txt

@@ -336,6 +336,9 @@ Notes:
 -   The --transpose flag can be used to exchange rows and columns.
 -   The --pivot FIELD option causes a different transaction field to be
     used as "account name". See PIVOTING.
+-   The --summary-only flag (--summary also works) hides all but the
+    Total and Average columns (those should be enabled with --row-total
+    and -A/--average).
 
 Multi-period reports with many periods can be too wide for easy viewing
 in the terminal. Here are some ways to handle that:

hledger/Hledger/Cli/Commands/Check.txt

@@ -4,91 +4,102 @@ Check for various kinds of errors in your data.
 
 _FLAGS
 
-hledger provides a number of built-in error checks to help prevent
+hledger provides a number of built-in correctness checks to help
-problems in your data. Some of these are run automatically; or, you can
+validate your data and prevent errors. Some are run automatically, some
-use this check command to run them on demand, with no output and a zero
+when you enable --strict mode; or you can run any of them on demand by
-exit code if all is well. Specify their names (or a prefix) as
+providing them as arguments to the check command. check produces no
-argument(s).
+output and a zero exit code if all is well. Eg:
 
-Some examples:
+hledger check                      # run basic checks
-
+hledger check -s                   # run basic and strict checks
-hledger check      # basic checks
+hledger check ordereddates payees  # run basic checks and two others
-hledger check -s   # basic + strict checks
-hledger check ordereddates payees  # basic + two other checks
 
 If you are an Emacs user, you can also configure flycheck-hledger to run
 these checks, providing instant feedback as you edit the journal.
 
-Here are the checks currently available:
+Here are the checks currently available. Generally, they are performed
+in the order they are shown here (and only the first failure is
+reported).
 
-Default checks
+Basic checks
 
-These checks are run automatically by (almost) all hledger commands:
+These important checks are performed by default, by almost all hledger
+commands:
 
 -   parseable - data files are in a supported format, with no syntax
-    errors and no invalid include directives.
+    errors and no invalid include directives. This ensures that all
+    files exist and are readable.
 
--   autobalanced - all transactions are balanced, after converting to
+-   autobalanced - all transactions are balanced, after inferring
-    cost. Missing amounts and missing costs are inferred automatically
+    missing amounts and conversion costs where possible, and then
-    where possible.
+    converting to cost. This ensures that each individual transaction is
+    well formed.
 
 -   assertions - all balance assertions in the journal are passing.
-    (This check can be disabled with -I/--ignore-assertions.)
+    Balance assertions are like canaries in your journal, they catch
+    many problems. They can get in the way sometimes; you can disable
+    them temporarily with -I/--ignore-assertions (unless overridden with
+    -s/--strict or hledger check assertions).
 
 Strict checks
 
-These additional checks are run when the -s/--strict (strict mode) flag
+These additional checks are performed by any command when the
-is used. Or, they can be run by giving their names as arguments to
+-s/--strict flag is used (strict mode). Strict mode always enables the
-check:
+balance assertions check, also. These provide extra error-catching power
+when you are serious about keeping your data clean and free of typos:
 
--   balanced - all transactions are balanced after converting to cost,
+-   balanced - like autobalanced, but in conversion transactions, costs
-    without inferring missing costs. If conversion costs are required,
+    must be written explicitly. This ensures some redundancy in the
-    they must be explicit.
+    entry, which helps prevent typos.
 
--   accounts - all account names used by transactions have been declared
+-   commodities - all commodity symbols used must be declared. This
+    guards against mistyping or omitting commodity symbols.
 
--   commodities - all commodity symbols used have been declared
+-   accounts - all account names used must be declared. This prevents
+    the use of mis-spelled or outdated account names.
 
 Other checks
 
-These checks can be run only by giving their names as arguments to
+These other checks are not wanted by everyone, but can be run using the
-check. They are more specialised and not desirable for everyone:
+check command:
 
--   ordereddates - transactions are ordered by date within each file
+-   ordereddates - within each file, transactions are ordered by date.
+    This is a simple and effective error catcher, and you should use it.
+    Alas! not everyone wants it. If you do, use
+    hledger check -s ordereddates. When enabled, this check is performed
+    early, before balance assertions (because copy-pasted dates are
+    often the root cause of balance assertion failures).
 
--   payees - all payees used by transactions have been declared
+-   payees - all payees used by transactions must be declared. This will
+    force you to always use known/declared payee names. For most people
+    this is a bit too restrictive.
 
--   recentassertions - all accounts with balance assertions have a
+-   tags - all tags used by transactions must be declared. This prevents
-    balance assertion within 7 days of their latest posting
+    mistyped tag names.
 
--   tags - all tags used by transactions have been declared
+-   recentassertions - all accounts with balance assertions must have a
+    balance assertion within the last 7 days before their latest
+    posting. This encourages you to add balance assertions fairly
+    regularly for your active asset/liability accounts, which in turn
+    should encourage you to check and reconcile with their real world
+    balances fairly regularly. close --assert can be helpful. (The older
+    balance assertions become redundant; you can remove them
+    periodically, or leave them in place, perhaps commented, as
+    documentation.)
 
--   uniqueleafnames - all account leaf names are unique
+-   uniqueleafnames - no two accounts may have the same leaf name. The
+    leaf name is the last colon-separated part of an account name, eg
+    checking in assets:bank:checking. This encourages you to keep those
+    unique, effectively giving each account a short name which is easier
+    to remember and to type in reporting commands.
 
 Custom checks
 
-A few more checks are are available as separate add-on commands, in
+You can build your own custom checks with add-on command scripts. See
-https://github.com/simonmichael/hledger/tree/master/bin:
+also Cookbook > Scripting. Here are some examples from hledger/bin/:
 
 -   hledger-check-tagfiles - all tag values containing / (a forward
     slash) exist as file paths
 
 -   hledger-check-fancyassertions - more complex balance assertions are
     passing
-
-You could make similar scripts to perform your own custom checks. See:
-Cookbook -> Scripting.
-
-More about specific checks
-
-hledger check recentassertions will complain if any balance-asserted
-account has postings more than 7 days after its latest balance
-assertion. This aims to prevent the situation where you are regularly
-updating your journal, but forgetting to check your balances against the
-real world, then one day must dig back through months of data to find an
-error. It assumes that adding a balance assertion requires/reminds you
-to check the real-world balance. (That may not be true if you
-auto-generate balance assertions from bank data; in that case, I
-recommend to import transactions uncleared, and when you manually review
-and clear them, also check the latest assertion against the real-world
-balance.)

hledger/Hledger/Cli/Commands/Help.txt

@@ -1,31 +1,31 @@
 help
 
-Show the hledger user manual in the terminal, with info, man, or a
+Show the hledger user manual with info, man, or a pager. With a (case
-pager. With a TOPIC argument, open it at that topic if possible. TOPIC
+insensitive) TOPIC argument, try to open it at that section heading.
-can be any heading in the manual, or a heading prefix, case insensitive.
-Eg: commands, print, forecast, journal, amount, "auto postings".
 
 _FLAGS
 
-This command shows the hledger manual built in to your hledger version.
+This command shows the hledger manual built in to your hledger
-It can be useful when offline, or when you prefer the terminal to a web
+executable. It can be useful when offline, or when you prefer the
-browser, or when the appropriate hledger manual or viewing tools are not
+terminal to a web browser, or when the appropriate hledger manual or
-installed on your system.
+viewers are not installed properly on your system.
 
-By default it chooses the best viewer found in $PATH, trying (in this
+By default it chooses the best viewer found in $PATH, trying in this
-order): info, man, $PAGER, less, more. You can force the use of info,
+order: info, man, $PAGER, less, more, stdout. (If a TOPIC is specified,
-man, or a pager with the -i, -m, or -p flags, If no viewer can be found,
+$PAGER and more are not tried.) You can force the use of info, man, or a
-or the command is run non-interactively, it just prints the manual to
+pager with the -i, -m, or -p flags. If no viewer can be found, or if
-stdout.
+running non-interactively, it just prints the manual to stdout.
 
-If using info, note that version 6 or greater is needed for TOPIC
+When using info, TOPIC can match either the full heading or a prefix. If
-lookup. If you are on mac you will likely have info 4.8, and should
+your info --version is < 6, you'll need to upgrade it, eg with
-consider installing a newer version, eg with brew install texinfo
+'brew install texinfo' on mac.
-(#1770).
+
+When using man or less, TOPIC must match the full heading. For a prefix
+match, you can write 'TOPIC.*'.
 
 Examples
 
-$ hledger help --help      # show how the help command works
+$ hledger help -h                 # show the help command's usage
-$ hledger help             # show the hledger manual with info, man or $PAGER
+$ hledger help                    # show the manual with info, man or $PAGER
-$ hledger help journal     # show the journal topic in the hledger manual
+$ hledger help 'time periods'     # show the manual's "Time periods" topic
-$ hledger help -m journal  # show it with man, even if info is installed
+$ hledger help 'time periods' -m  # use man, even if info is installed

hledger/Hledger/Cli/Commands/Import.txt

@@ -21,7 +21,7 @@ hledger import bank.csv or perhaps hledger import *.csv.
 Note you can import from any file format, though CSV files are the most
 common import source, and these docs focus on that case.
 
-Deduplication
+Date skipping
 
 import tries to import only the transactions which are new since the
 last import, ignoring any that it has seen in previous runs. So if your
@@ -29,53 +29,55 @@ bank's CSV includes the last three months of data, you can download and
 import it every month (or week, or day) and only the new transactions
 will be imported each time.
 
-It works as follows. For each imported FILE (usually CSV, but they could
+It works as follows: for each imported FILE,
-be any of hledger's input formats):
 
--   It tries to recall the latest date seen previously, reading it from
+-   It tries to read the latest date previously seen, from .latest.FILE
-    a hidden .latest.FILE in the same directory.
+    in the same directory
--   Then it processes FILE, ignoring any transactions on or before the
+-   Then it processes FILE, ignoring transactions on or before that date
-    "latest seen" date.
 
-And after a successful import, it updates the .latest.FILE(s) for next
+And after a successful import, unless --dry-run was used, it updates the
-time (unless --dry-run was used).
+.latest.FILE(s) for next time. This is a simple system that works for
+most real-world CSV files; it assumes the following are true, or true
+enough:
 
-This is a limited kind of deduplication, let's call it "date skipping".
+1.  the name of the input file is stable across successive downloads
-Within each input file, it avoids reprocessing the same dates across
+2.  new items always have the newest dates
-successive runs. This is a simple system that works for most real-world
+3.  item dates are stable across downloads
-CSV files; it assumes these are true, or true enough:
+4.  the order of same-date items is stable across downloads.
 
-1.  new items always have the newest dates
+Tips:
-2.  item dates are stable across successive downloads
-3.  the order of same-date items is stable across downloads
-4.  the name of the input file is stable across downloads
 
-If you have a bank whose CSV dates or ordering occasionally change, you
+-   To help ensure a stable file name, remember you can use a CSV rules
-can reduce the chance of this happening in new transactions by importing
+    file as an input file.
-more often, and in old transactions it doesn't matter. And remember you
-can use CSV rules files as input, which is one way to ensure a stable
-file name.
 
-import doesn't detect other kinds of duplication, such as duplicate
+-   If you have a bank whose CSV dates or ordering occasionally change,
-transactions within a single run. (In part, because legitimate duplicate
+    you can reduce the chance of this happening in new transactions by
-transactions can easily occur in real-world data.) So, say you
+    importing more often. (If it happens in old transactions, that's
-downloaded but forgot to import bank.1.csv, and a week later you
+    harmless.)
-downloaded bank.2.csv with overlapping data. Now you should not import
+
-both of these at once (hledger import bank.1.csv bank.2.csv); the
+Note this is just one kind of "deduplication": not reprocessing the same
-overlapping transactions which appear twice would not be deduplicated
+dates across successive runs. import doesn't detect other kinds of
-since this is considered a single import. Instead, import these files
+duplication, such as the same transaction appearing multiple times
-one at a time, and also use the same filename each time for a common
+within a single run, or a new transaction that looks identical to a
-"latest seen" state:
+transaction already in the journal. (Because these can happen
+legitimately in real-world data.)
+
+Here's a situation where you need to run import with care: say you
+download but forget to import bank.1.csv, and a week later you download
+bank.2.csv with some overlapping data. You should not process both of
+these as a single import (hledger import bank.1.csv bank.2.csv), because
+the overlapping transactions would not be deduplicated. Instead, import
+one file at a time, using the same filename each time:
 
 $ mv bank.1.csv bank.csv; hledger import bank.csv
 $ mv bank.2.csv bank.csv; hledger import bank.csv
 
-Normally you can ignore the .latest.* files, but if needed, you can
+Normally you don't need to think about .latest.* files, but you can
-delete them (to make all transactions unseen), or construct/modify them
+create or modify them to catch up to a certain date, or delete them to
-(to catch up to a certain date). The format is just a single ISO-format
+mark all transactions as new. Their format is a single ISO-format
-date (YYYY-MM-DD), possibly repeated on multiple lines. It means "I have
+YYYY-MM-DD date, optionally repeated on multiple lines, meaning "I have
-seen transactions up to this date, and this many of them occurring on
+seen the transactions before this date, and this many of them on this
-that date".
+date".
 
 hledger print --new also uses and updates these .latest.* files, but it
 is less often used.
@@ -118,7 +120,10 @@ $ hledger print IMPORTFILE [--new] >> $LEDGER_FILE
 (If you think import should leave amounts implicit like print does,
 please test it and send a pull request.)
 
-Commodity display styles
+Import and commodity styles
 
-Imported amounts will be formatted according to the canonical commodity
+Amounts in entries added by import will be formatted according to the
-styles (declared or inferred) in the main journal file.
+journal's canonical commodity styles, as declared by commodity
+directives or inferred from the journal's amounts.
+
+Related: CSV > Amount decimal places.