doc: clean up errors README, now published as hledger.org/ERRORS.html

hledger/test/errors/README.md

@@ -1,26 +1,51 @@
-hledger error messages are currently quite varied in format.
+# ERRORS
-Tools like flycheck-hledger parse them and need updating
-whenever they change ([#1436][]).
-Getting consistent high-quality errors and accurate flycheck region
-highlighting, not to mention LSP support, for all of our journal
-errors is a big project, but it's crowd-sourceable and every bit of
-progress brings immediate practical benefits.
 
-Here are journals/scripts for reproducing hledger's journal error messages.
+<div class=pagetoc>
-They are named similarly to [hledger check][]'s checks.
-In the CLI, execute them to see the error messages.
 
-In Emacs with [flycheck-hledger][],
+<!-- toc -->
-customize flycheck-hledger-* to enable all appropriate checks,
+</div>
-and open the files to see how flycheck handles them.
-Some files contain extra declarations to ease flycheck testing.
 
-[hledger check]:    https://hledger.org/hledger.html#check
+hledger produces a variety of error messages in different situations.
-[flycheck-hledger]: https://github.com/DamienCassou/flycheck-hledger
+They are intended first for humans and secondly for parsing by tools
-[flycheck-hledger-10]: https://github.com/DamienCassou/flycheck-hledger/pull/10
+like [flycheck-hledger][].
-[#1436]:            https://github.com/simonmichael/hledger/issues/1436
+Here we collect examples of these errors, which are listed below
+for reference, and also tested as part of our test suite.
+This document is the README in the [hledger/test/errors/][] directory,
+and also published as Developer docs > [ERRORS][] on hledger.org.
 
-## Goals
+Each error has 
+
+- a name (similar to [hledger check][] names when applicable)
+- an executable script in this directory which reproduces the error (like `balanced.j`)
+- which usually can also be used as a data file for manual testing (`hledger -f balanced.j check`)
+- sometimes supplementary data files (like `csvdateparse.csv.rules`)
+- an autogenerated shelltestrunner test (like `balanced.test`)
+
+To update this readme with the latest error messages, run `make readme`.
+To regenerate the shelltestrunner tests, run `make tests`.
+To test all of these error messages with hledger, run `make test`.
+To test these errors with flycheck-hledger,
+customize `flycheck-hledger-*` in Emacs to enable all appropriate checks,
+then open the data files to see how flycheck handles them.
+`C-c ! l` opens a pane for easy viewing.
+
+<!-- Use absolute urls as this page can be viewed on github or hledger.org. -->
+[hledger/test/errors/]:  https://github.com/simonmichael/hledger/tree/master/hledger/test/errors
+[ERRORS]:                https://hledger.org/ERRORS.html
+[hledger check]:         https://hledger.org/hledger.html#check
+[flycheck-hledger-home]: https://github.com/DamienCassou/flycheck-hledger
+[flycheck-hledger-10]:   https://github.com/DamienCassou/flycheck-hledger/pull/10
+[flycheck-hledger]:      https://hledger.org/editors.html#flycheck-hledger
+
+
+## Error improvement
+
+Work is ongoing to make our error messages more consistent and more useful
+([#1436](https://github.com/simonmichael/hledger/issues/1436),
+[#1885](https://github.com/simonmichael/hledger/pull/1885), 
+[#1886](https://github.com/simonmichael/hledger/pull/1886)..).
+This is a big project, and your help is welcome; every bit of progress
+counts, and this is a fast way to help users.
 
 - [x] ~~phase 1: update flycheck to detect journal errors of current hledger release (and keep a branch updated to detect errors of latest hledger master)~~
 - [x] ~~phase 2: survey/document current journal errors & status~~
@@ -37,18 +62,18 @@ Some files contain extra declarations to ease flycheck testing.
 - [x] ~~phase 13: decide/add error ids/explanations/web pages ? not needed~~
 - [ ] phase 14: support Language Server Protocol & Visual Code
 
-## Preferred error format
+## Standard error format
 
-Here is our current standard error message layout. 
+Here is our current preferred layout for error messages. 
-It is similar to the parse error messages we get from megaparsec.
+It is similar to the parse error messages we get from megaparsec
-(Easier to follow that than change it.):
+(since it's easier to follow that than change it):
 ```
 hledger: Error: FILE:LOCATION:
 EXCERPT
 EXPLANATION
 ```
 
-Notes (see also [#1436][]):
+Notes:
 
 - line 1 includes "hledger" (dropping this would require some effort), the word "Error", and the error position
 - FILE is the file path
@@ -64,7 +89,10 @@ Notes (see also [#1436][]):
   EXCERPT
   [DETAILS]
   ```
-- try https://github.com/mesabloo/diagnose / https://hackage.haskell.org/package/errata / https://hackage.haskell.org/package/chapelure later
+- try 
+  <https://github.com/mesabloo/diagnose>,
+  <https://hackage.haskell.org/package/errata>,
+  <https://hackage.haskell.org/package/chapelure> later ?
 
 ## Limitations
 
@@ -78,19 +106,20 @@ Here are some current limitations of hledger's error messages:
 - For the same reason, the excerpts we show in error messages are not the original data.
   Instead we show a synthetic rendering that is similar enough to be explanatory.
 
-## Current status
+
+## Error messages
 
 Here is the current status as of
 hledger (see version below) and flycheck-hledger g1310cb518.
-Click error names to see an example. Key:
+Click error names to see an example. The table headings mean:
 
-- std format - the error message follows a standard format (location on first line, megaparsec-like excerpt, explanation)
+- std format - the error message follows our standard error format
 - line       - correct line numbers are reported
 - column     - useful column numbers are reported
 - excerpt    - a useful excerpt is shown, ideally with the error highlighted (✓✓)
 - flycheck   - the current flycheck release (or a PR branch) recognises the error and highlights a useful region
 
-| error/check name                                      | std format | line | column | excerpt | flycheck |
+| error name                                            | std format | line | column | excerpt | flycheck |
 |-------------------------------------------------------|------------|------|--------|---------|----------|
 | [accounts](#accounts)                                 | ✓          | ✓    | ✓      | ✓✓      | ✓        |
 | [assertions](#assertions)                             | ✓          | ✓    | ✓      | ✓✓      | ✓        |
@@ -125,10 +154,6 @@ Click error names to see an example. Key:
 | [csvstdinrules](#csvstdinrules)                       |            |      |        |         |          |
 
 
-## Current error messages
-
-(To update: `make readme`)
-
 <!-- GENERATED: -->
 hledger 1.26.99-ga7b920750-20220715 error messages: