test: errors: doc updates

hledger/test/errors/README.md

@@ -49,7 +49,7 @@ Key:
 ## Current journal errors
 
 <!-- to update: erase the below then C-u M-! ./showall -->
-hledger 1.25.99-ge6bf04fce-20220316 error messages, last updated 2022-03-18:
+hledger 1.25, last updated 2022-03-18:
 
 ### parseable
 ```
@@ -88,7 +88,7 @@ hledger: /Users/simon/src/hledger/hledger/test/errors/./balanced.j:3-4
 could not balance this transaction:
 real postings' sum should be 0 but is: 1
 2022-01-01
-    a               1
+	a               1
 
 ```
 
@@ -99,8 +99,8 @@ could not balance this transaction:
 real postings' sum should be 0 but is:  1 A
 -1 B
 2022-01-01
-    a             1 A
-    b            -1 B
+	a             1 A
+	b            -1 B
 
 ```
 
@@ -109,7 +109,7 @@ real postings' sum should be 0 but is:  1 A
 hledger: balance assertion: /Users/simon/src/hledger/hledger/test/errors/./assertions.j:4:8
 transaction:
 2022-01-01
-    a               0 = 1
+	a               0 = 1
 
 assertion details:
 date:       2022-01-01
@@ -127,7 +127,7 @@ Error: undeclared account "a"
 in transaction at: /Users/simon/src/hledger/hledger/test/errors/./accounts.j:3-4
 
   2022-01-01
-      (a)               1
+	  (a)               1
 
 ```
 
@@ -137,7 +137,7 @@ Error: undeclared commodity "A"
 in transaction at: /Users/simon/src/hledger/hledger/test/errors/./commodities.j:5-6
 
   2022-01-01
-      (a)             A 1
+	  (a)             A 1
 
 ```
 
@@ -147,7 +147,7 @@ Error: undeclared payee "p"
 at: /Users/simon/src/hledger/hledger/test/errors/./payees.j:6-7
 
 > 2022-01-01 p
-      (a)             A 1
+	  (a)             A 1
 
 ```
 
@@ -157,10 +157,10 @@ Error: transaction date is out of order
 at /Users/simon/src/hledger/hledger/test/errors/./ordereddates.j:10-11:
 
   2022-01-02 p
-      (a)               1
+	  (a)               1
 
 > 2022-01-01 p
-      (a)               1
+	  (a)               1
 
 
 ```
@@ -176,3 +176,23 @@ seen in "a:c" in transaction at: /Users/simon/src/hledger/hledger/test/errors/./
 
 ```
 
+
+
+## Standard error format
+
+The proposed new format from [#1436][]. This is similar to megaparsec's pretty error output.
+
+```
+Error: [ID] FILE:LOCATION
+EXCERPT
+SUMMARY
+[DETAILS]
+```
+
+- begins with the word "Error"
+- ID is an optional error id, eg `HL1001` (in brackets ?). We might adopt these, similar to ShellCheck.
+- FILE is the file path.
+- LOCATION is `LINE[-ENDLINE][:COLUMN[-ENDCOLUMN]]					`
+- EXCERPT is a short visual snippet whenever possible, with the error region highlighted, line numbers, and colour when supported. This section must be easy for flycheck to ignore.
+- SUMMARY is a one line description/explanation of the problem. Currently we include contextual data in these for clarity, but it might be advantageous to use unchanging standard text.
+- DETAILS is optional additional details/advice when needed.