;doc: check: expand check descriptions

hledger/Hledger/Cli/Commands/Check.md

@@ -4,76 +4,90 @@ Check for various kinds of errors in your data.
 
 _FLAGS
 
-hledger provides a number of built-in correctness checks to help
+hledger provides a number of built-in correctness checks to help validate your data and prevent errors.
-prevent problems in your data. 
+Some are run automatically, some when you enable `--strict` mode;
-Some of these are run automatically; or,
+or you can run any of them on demand with this `check` command.
-you can use this `check` command to run them on demand,
+`check` produces no output and a zero exit code if all is well.
-with no output and a zero exit code if all is well.
+Eg:
-Specify their names (or a prefix) as argument(s).
-
-Some examples:
 
 ```cli
-hledger check      # basic checks
+hledger check                      # run basic checks
-hledger check -s   # basic + strict checks
+hledger check -s                   # run basic and strict checks
-hledger check ordereddates payees  # basic + two other checks
+hledger check ordereddates payees  # run basic checks and two others
 ```
 
 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.
-They are performed in the order they are shown here.
+Generally, they are performed in the order they are shown here (and only the first failure is reported).
-(Eg, an `ordereddates` failure takes precedence over an `assertions` failure).
 
-### Default checks
+### Basic checks
 
-These checks are always performed, 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](#data-formats),
-  with no syntax errors and no invalid include directives
+  with no syntax errors and no invalid include directives.
+  This ensures that all files exist and are readable.
 
 - **autobalanced** - all transactions are [balanced](#postings),
   after inferring missing amounts and conversion [costs] where possible,
-  and then converting to cost
+  and then 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.
+  This check can sometimes get in the way, eg when you are troubleshooting bookkeeping errors,
+  or parsing a journal fragment, so it can be disabled temporarily with `-I`/`--ignore-assertions`.
 
 ### Strict checks
 
-These additional checks are run when the `-s`/`--strict` ([strict mode])
+These additional checks are performed by any command when the `-s`/`--strict` flag is used (AKA [strict mode]). 
-flag is used with any command; or,
+They provide extra error-catching power when you are serious about keeping your data clean and free of typos:
-when they are given as arguments to the `check` command:
 
-- **balanced** - like `autobalanced`, but conversion costs will not be
+- **balanced** - like `autobalanced`, but in [conversion transactions](#recording-costs),
-  inferred, and must be written explicitly
+  costs must be written explicitly. This ensures some redundancy in the entry, guarding against typos.
 
-- **commodities** - all commodity symbols used 
+- **commodities** - all commodity symbols used [must be declared](#commodity-error-checking).
-  [have been declared](#commodity-error-checking)
+  This guards against forgetting or mistyping commodity symbols.
 
-- **accounts** - all account names used
+- **accounts** - all account names used [must be declared](#account-error-checking).
-  [have been declared](#account-error-checking)
+  This prevents the use of mistyped or outdated account names.
 
 ### Other checks
 
-These checks can be run by giving their names as arguments to `check`:
+These other checks are not wanted by everyone, but can be run using the `check` command:
 
-- **ordereddates** - within each file, transactions are ordered by date
+- **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`.
 
-- **payees** - all payees used by transactions [have been declared](#payee-directive)
+- **payees** - all payees used by transactions [must be declared](#payee-directive).
+  This will force you to always use known/declared payee names. 
+  For most people this is a bit too restrictive.
 
-- **tags** - all tags used by transactions [have been declared](#tag-directive)
+- **tags** - all tags used by transactions [must be declared](#tag-directive).
+  This prevents mistyped tag names.
 
-- **recentassertions** - all accounts with balance assertions have a
+- **recentassertions** - all accounts with balance assertions must have
-  balance assertion within 7 days of their latest posting
+  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`](#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
 
 You can build your own custom checks with [add-on command scripts].
-(See also [Cookbook > Scripting](scripting.html).)
+See also [Cookbook > Scripting](scripting.html).
 Here are some examples from [hledger/bin/](https://github.com/simonmichael/hledger/tree/master/bin):
 
 - **hledger-check-tagfiles** - all tag values containing / (a forward slash) exist as file paths
@@ -81,18 +95,6 @@ Here are some examples from [hledger/bin/](https://github.com/simonmichael/hledg
 - **hledger-check-fancyassertions** - more complex balance assertions are passing
 
 
-### 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.)
-
 [add-on command scripts]:    #add-on-commands
 [balance assertions]: #balance-assertions
 [strict mode]:        #strict-mode