;update manuals

2020-11-30 08:41:40 -08:00 · 2020-11-30 08:41:40 -08:00 · e983380098
commit e983380098
parent 679373c835
3 changed files with 241 additions and 158 deletions
--- a/hledger/hledger.1
+++ b/hledger/hledger.1
@ -3543,17 +3543,27 @@ check
 .P
 .PD
 Check for various kinds of errors in your data.
+\f[I]experimental\f[R]
 .PP
 hledger provides a number of built-in error checks to help prevent
 problems in your data.
-Some, but not all, of these are run automatically before all commands.
-You can also use this \f[C]check\f[R] command to run any of the
-available tests.
-They are named, and run, as follows:
+Some of these are run automatically; or, you can use this
+\f[C]check\f[R] command to run them on demand, with no output and a zero
+exit code if all is well.
+Some examples:
+.IP
+.nf
+\f[C]
+hledger check      # basic checks
+hledger check -s   # basic + strict checks
+hledger check ordereddates uniqueleafnames  # basic + specified checks
+\f[R]
+.fi
 .PP
-\f[C]hledger check\f[R] runs the basic checks, like all other commands,
-but with no output unless there is a problem.
-These are:
+Here are the checks currently available:
+.SS Basic checks
+.PP
+These are always run by this command and other commands:
 .IP \[bu] 2
 \f[B]parseable\f[R] - data files are well-formed and can be successfully
 parsed
@ -3562,41 +3572,51 @@ parsed
 missing amounts where necessary, and possibly converting commodities
 using transaction prices or automatically-inferred transaction prices
 .IP \[bu] 2
-\f[B]assertions\f[R] - all balance assertions are passing (except with
-\f[C]-I\f[R]/\f[C]--ignore-assertions\f[R])
+\f[B]assertions\f[R] - all balance assertions in the journal are
+passing.
+(This check can be disabled with
+\f[C]-I\f[R]/\f[C]--ignore-assertions\f[R].)
+.SS Strict checks
 .PP
-\f[C]hledger check --strict\f[R] also runs the additional \[dq]strict
-mode\[dq] checks, which are:
+These are always run by this and other commands when
+\f[C]-s\f[R]/\f[C]--strict\f[R] is used (strict mode):
 .IP \[bu] 2
 \f[B]accounts\f[R] - all account names used by transactions have been
 declared
 .IP \[bu] 2
 \f[B]commodities\f[R] - all commodity symbols used have been declared
+.SS Other checks
 .PP
-\f[C]hledger check CHECK1 CHECK2 ...\f[R] runs all of the named checks,
-in turn.
-This may be useful when neither the default nor strict checks are
-exactly what you want, or when you want to focus on a single check of
-interest.
-The arguments are standard lowercase names for the checks.
-Currently only these checks can be run in this way:
+These checks can be run by specifying their names as arguments to the
+check command:
 .IP \[bu] 2
-\f[B]dates\f[R] - transactions are ordered by date (similar to the old
-\f[C]check-dates\f[R] command)
+\f[B]ordereddates\f[R] - transactions are ordered by date (similar to
+the old \f[C]check-dates\f[R] command)
 .IP \[bu] 2
-\f[B]leafnames\f[R] - all account leaf names are unique ((similar to the
-old \f[C]check-dupes\f[R] command)
+\f[B]uniqueleafnames\f[R] - all account leaf names are unique (similar
+to the old \f[C]check-dupes\f[R] command)
 .PP
-See also:
+This command would run all of the checks above:
+.IP
+.nf
+\f[C]
+$ hledger check -s ordereddates uniqueleafnames
+\f[R]
+.fi
+.SS Addon checks
 .PP
-Some checks are shipped as addon scripts for now (cf
-https://github.com/simonmichael/hledger/tree/master/bin, and Cookbook ->
-Scripting):
+Some checks are not yet integrated with this command, but are available
+as [addon commands] in
+https://github.com/simonmichael/hledger/tree/master/bin:
 .IP \[bu] 2
-\f[B]tagfiles\f[R] - all tag values containing / (a forward slash) exist
-as file paths
+\f[B]hledger-check-tagfiles\f[R] - all tag values containing / (a
+forward slash) exist as file paths
 .IP \[bu] 2
-\f[B]fancyassertions\f[R] - more complex balance assertions are passing
+\f[B]hledger-check-fancyassertions\f[R] - more complex balance
+assertions are passing
+.PP
+You could make your own similar scripts to perform custom checks;
+Cookbook -> Scripting may be helpful.
 .SS close
 .PP
 close, equity
--- a/hledger/hledger.info
+++ b/hledger/hledger.info
@ -2972,52 +2972,95 @@ File: hledger.info,  Node: check,  Next: close,  Prev: cashflow,  Up: COMMANDS
 =========

 check
-Check for various kinds of errors in your data.
+Check for various kinds of errors in your data.  _experimental_

   hledger provides a number of built-in error checks to help prevent
-problems in your data.  Some, but not all, of these are run
-automatically before all commands.  You can also use this 'check'
-command to run any of the available tests.  They are named, and run, as
-follows:
+problems in your data.  Some of these are run automatically; or, you can
+use this 'check' command to run them on demand, with no output and a
+zero exit code if all is well.  Some examples:

-   'hledger check' runs the basic checks, like all other commands, but
-with no output unless there is a problem.  These are:
+hledger check      # basic checks
+hledger check -s   # basic + strict checks
+hledger check ordereddates uniqueleafnames  # basic + specified checks
+
+   Here are the checks currently available:
+
+* Menu:
+
+* Basic checks::
+* Strict checks::
+* Other checks::
+* Addon checks::
+
+
+File: hledger.info,  Node: Basic checks,  Next: Strict checks,  Up: check
+
+3.9.1 Basic checks
+------------------
+
+These are always run by this command and other commands:

   * *parseable* - data files are well-formed and can be successfully
     parsed
+
   * *autobalanced* - all transactions are balanced, inferring missing
     amounts where necessary, and possibly converting commodities using
     transaction prices or automatically-inferred transaction prices
-   * *assertions* - all balance assertions are passing (except with
-     '-I'/'--ignore-assertions')

-   'hledger check --strict' also runs the additional "strict mode"
-checks, which are:
+   * *assertions* - all balance assertions in the journal are passing.
+     (This check can be disabled with '-I'/'--ignore-assertions'.)
+
+
+File: hledger.info,  Node: Strict checks,  Next: Other checks,  Prev: Basic checks,  Up: check
+
+3.9.2 Strict checks
+-------------------
+
+These are always run by this and other commands when '-s'/'--strict' is
+used (strict mode):

   * *accounts* - all account names used by transactions have been
     declared
+
   * *commodities* - all commodity symbols used have been declared

-   'hledger check CHECK1 CHECK2 ...' runs all of the named checks, in
-turn.  This may be useful when neither the default nor strict checks are
-exactly what you want, or when you want to focus on a single check of
-interest.  The arguments are standard lowercase names for the checks.
-Currently only these checks can be run in this way:
+
+File: hledger.info,  Node: Other checks,  Next: Addon checks,  Prev: Strict checks,  Up: check

-   * *dates* - transactions are ordered by date (similar to the old
-     'check-dates' command)
-   * *leafnames* - all account leaf names are unique ((similar to the
-     old 'check-dupes' command)
+3.9.3 Other checks
+------------------

-   See also:
+These checks can be run by specifying their names as arguments to the
+check command:

-   Some checks are shipped as addon scripts for now (cf
-https://github.com/simonmichael/hledger/tree/master/bin, and Cookbook ->
-Scripting):
+   * *ordereddates* - transactions are ordered by date (similar to the
+     old 'check-dates' command)

-   * *tagfiles* - all tag values containing / (a forward slash) exist as
-     file paths
-   * *fancyassertions* - more complex balance assertions are passing
+   * *uniqueleafnames* - all account leaf names are unique (similar to
+     the old 'check-dupes' command)
+
+   This command would run all of the checks above:
+
+$ hledger check -s ordereddates uniqueleafnames
+
+
+File: hledger.info,  Node: Addon checks,  Prev: Other checks,  Up: check
+
+3.9.4 Addon checks
+------------------
+
+Some checks are not yet integrated with this command, but are available
+as [addon commands] in
+https://github.com/simonmichael/hledger/tree/master/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 your own similar scripts to perform custom checks;
+Cookbook -> Scripting may be helpful.


 File: hledger.info,  Node: close,  Next: codes,  Prev: check,  Up: COMMANDS
@ -4574,80 +4617,88 @@ Node: cashflow104183
 Ref: #cashflow104305
 Node: check105521
 Ref: #check105624
-Node: close107565
-Ref: #close107667
-Node: close usage109189
-Ref: #close-usage109282
-Node: codes112095
-Ref: #codes112203
-Node: commodities112915
-Ref: #commodities113042
-Node: descriptions113124
-Ref: #descriptions113252
-Node: diff113556
-Ref: #diff113662
-Node: files114709
-Ref: #files114809
-Node: help114956
-Ref: #help115056
-Node: import116137
-Ref: #import116251
-Node: Importing balance assignments117173
-Ref: #importing-balance-assignments117354
-Node: Commodity display styles118003
-Ref: #commodity-display-styles118174
-Node: incomestatement118303
-Ref: #incomestatement118436
-Node: notes119781
-Ref: #notes119894
-Node: payees120262
-Ref: #payees120368
-Node: prices120788
-Ref: #prices120894
-Node: print121235
-Ref: #print121345
-Node: print-unique126141
-Ref: #print-unique126267
-Node: register126552
-Ref: #register126679
-Node: Custom register output131128
-Ref: #custom-register-output131257
-Node: register-match132594
-Ref: #register-match132728
-Node: rewrite133079
-Ref: #rewrite133194
-Node: Re-write rules in a file135049
-Ref: #re-write-rules-in-a-file135183
-Node: Diff output format136393
-Ref: #diff-output-format136562
-Node: rewrite vs print --auto137654
-Ref: #rewrite-vs.-print---auto137833
-Node: roi138389
-Ref: #roi138487
-Node: stats150697
-Ref: #stats150796
-Node: tags151584
-Ref: #tags151682
-Node: test152201
-Ref: #test152309
-Node: Add-on commands153056
-Ref: #add-on-commands153173
-Node: ui154516
-Ref: #ui154604
-Node: web154658
-Ref: #web154761
-Node: iadd154877
-Ref: #iadd154988
-Node: interest155070
-Ref: #interest155177
-Node: ENVIRONMENT155417
-Ref: #environment155529
-Node: FILES156514
-Ref: #files-1156617
-Node: LIMITATIONS156830
-Ref: #limitations156949
-Node: TROUBLESHOOTING157691
-Ref: #troubleshooting157804
+Node: Basic checks106228
+Ref: #basic-checks106344
+Node: Strict checks106837
+Ref: #strict-checks106976
+Node: Other checks107219
+Ref: #other-checks107356
+Node: Addon checks107755
+Ref: #addon-checks107870
+Node: close108324
+Ref: #close108426
+Node: close usage109948
+Ref: #close-usage110041
+Node: codes112854
+Ref: #codes112962
+Node: commodities113674
+Ref: #commodities113801
+Node: descriptions113883
+Ref: #descriptions114011
+Node: diff114315
+Ref: #diff114421
+Node: files115468
+Ref: #files115568
+Node: help115715
+Ref: #help115815
+Node: import116896
+Ref: #import117010
+Node: Importing balance assignments117932
+Ref: #importing-balance-assignments118113
+Node: Commodity display styles118762
+Ref: #commodity-display-styles118933
+Node: incomestatement119062
+Ref: #incomestatement119195
+Node: notes120540
+Ref: #notes120653
+Node: payees121021
+Ref: #payees121127
+Node: prices121547
+Ref: #prices121653
+Node: print121994
+Ref: #print122104
+Node: print-unique126900
+Ref: #print-unique127026
+Node: register127311
+Ref: #register127438
+Node: Custom register output131887
+Ref: #custom-register-output132016
+Node: register-match133353
+Ref: #register-match133487
+Node: rewrite133838
+Ref: #rewrite133953
+Node: Re-write rules in a file135808
+Ref: #re-write-rules-in-a-file135942
+Node: Diff output format137152
+Ref: #diff-output-format137321
+Node: rewrite vs print --auto138413
+Ref: #rewrite-vs.-print---auto138592
+Node: roi139148
+Ref: #roi139246
+Node: stats151456
+Ref: #stats151555
+Node: tags152343
+Ref: #tags152441
+Node: test152960
+Ref: #test153068
+Node: Add-on commands153815
+Ref: #add-on-commands153932
+Node: ui155275
+Ref: #ui155363
+Node: web155417
+Ref: #web155520
+Node: iadd155636
+Ref: #iadd155747
+Node: interest155829
+Ref: #interest155936
+Node: ENVIRONMENT156176
+Ref: #environment156288
+Node: FILES157273
+Ref: #files-1157376
+Node: LIMITATIONS157589
+Ref: #limitations157708
+Node: TROUBLESHOOTING158450
+Ref: #troubleshooting158563

 End Tag Table

--- a/hledger/hledger.txt
+++ b/hledger/hledger.txt
@ -2557,15 +2557,21 @@ COMMANDS

   check
       check
-       Check for various kinds of errors in your data.
+       Check for various kinds of errors in your data.  experimental

       hledger  provides  a  number  of  built-in error checks to help prevent
-       problems in your data.  Some, but not all, of these are  run  automati-
-       cally  before all commands.  You can also use this check command to run
-       any of the available tests.  They are named, and run, as follows:
+       problems in your data.  Some of these are run  automatically;  or,  you
+       can  use this check command to run them on demand, with no output and a
+       zero exit code if all is well.  Some examples:

-       hledger check runs the basic checks, like all other commands, but  with
-       no output unless there is a problem.  These are:
+              hledger check      # basic checks
+              hledger check -s   # basic + strict checks
+              hledger check ordereddates uniqueleafnames  # basic + specified checks
+
+       Here are the checks currently available:
+
+   Basic checks
+       These are always run by this command and other commands:

       o parseable - data files are well-formed and can be successfully parsed

@ -2573,38 +2579,44 @@ COMMANDS
         amounts  where  necessary,  and possibly converting commodities using
         transaction prices or automatically-inferred transaction prices

-       o assertions - all balance assertions are passing (except with -I/--ig-
-         nore-assertions)
+       o assertions - all balance  assertions  in  the  journal  are  passing.
+         (This check can be disabled with -I/--ignore-assertions.)

-       hledger check --strict also runs the additional "strict  mode"  checks,
-       which are:
+   Strict checks
+       These  are  always  run  by this and other commands when -s/--strict is
+       used (strict mode):

       o accounts - all account names used by transactions have been declared

       o commodities - all commodity symbols used have been declared

-       hledger  check CHECK1 CHECK2 ... runs all of the named checks, in turn.
-       This may be useful when neither the default nor strict checks  are  ex-
-       actly what you want, or when you want to focus on a single check of in-
-       terest.  The arguments are standard lowercase  names  for  the  checks.
-       Currently only these checks can be run in this way:
+   Other checks
+       These checks can be run by specifying their names as arguments  to  the
+       check command:

-       o dates  -  transactions are ordered by date (similar to the old check-
-         dates command)
+       o ordereddates  -  transactions are ordered by date (similar to the old
+         check-dates command)

-       o leafnames - all account leaf names are unique ((similar  to  the  old
-         check-dupes command)
+       o uniqueleafnames - all account leaf names are unique (similar  to  the
+         old check-dupes command)

-       See also:
+       This command would run all of the checks above:

-       Some    checks   are   shipped   as   addon   scripts   for   now   (cf
-       https://github.com/simonmichael/hledger/tree/master/bin,  and  Cookbook
-       -> Scripting):
+              $ hledger check -s ordereddates uniqueleafnames

-       o tagfiles  -  all  tag  values containing / (a forward slash) exist as
-         file paths
+   Addon checks
+       Some checks are not yet integrated with this command, but are available
+       as      [addon       commands]       in       https://github.com/simon-
+       michael/hledger/tree/master/bin:

-       o fancyassertions - more complex balance assertions are passing
+       o hledger-check-tagfiles  -  all  tag  values  containing  / (a forward
+         slash) exist as file paths
+
+       o hledger-check-fancyassertions - more complex balance  assertions  are
+         passing
+
+       You could make your own similar scripts to perform custom checks; Cook-
+       book -> Scripting may be helpful.

   close
       close, equity