Review misleading error messages

[tripu]

In particular, those that are occurring lately because of the switch to HTTPS; we've had a few recently. Users don't notice that the error is a mere “s” missing (understandably), because the error messages are generic, and some times don't point to the corresponding publication rule, where the boilerplate is.

[plehegar]

A complementary way to fix error messages is to move them out of the software and put them in GitHub or a wiki. Ie point people to a page describing the error and, as always, allow folks to contribute to those pages.
Today, going from
"specberus": {
"status": "failure",
"errors": [
{
"key": "this-latest-shortname",
"type": {
"name": "headers.dl",
"section": "front-matter",
"rule": "docIDFormat"
}
}
]
},

to

https://github.com/w3c/specberus/blob/master/lib/l10n-en_GB.js#L45

isn't user friendly.

[tripu]

I agree that the errors we have now in JSON aren't good. But I personally prefer descriptive error messages to be contained in the software itself.

I started working on this in w3c/echidna#431 already.

Errors will look more or less like this:

• 👎 Error code “wrong-date”.
• 👎 HTTP resource not retrievable. The HTTP status from the remote server was: 404.

These changes are reformatting the errors in Echidna; but the same transformation I hope we can apply directly in Specberus.

[plehegar]

again, we should be able to point to a page for further information, so that we can easiuly extend the documentation beyond simple sentence.

[tripu]

@plehegar, the rules on w3.org/pubrules/doc are sometimes several sentences long, and include examples and suggested boilerplate. eg, eg. Do you think that's still not enough?

[plehegar]

there is no point from an error message to w3.org/pubrules/doc.

Here is an other example:
{ "key": "title",
"type": {
"name": "headers.h1-title",
"section": "front-matter",
"rule": "title" }
},

Basically, it's trying to tell me that <h1> text doesn't match <title>. It is reflected in The document's title must be in the title element and in an h1 element.. I had to look at the source code of the rule to understand that because the normalization doesn't like <br> elements in text content. At the minimum, we need to add a url in that JS object to point to http://www.w3.org/pubrules/doc/rules/?profile=CR#title. At best, http://www.w3.org/pubrules/doc/rules/?profile=CR#title should also point to https://github.com/w3c/specberus/blob/master/lib/rules/headers/h1-title.js .