I've got a first cut for the next draft of SRFI 198, and I'm now
going backwards through recent messages to try to address the
points raised in them.

> From: Lassi Kortela <xxxxxx@lassi.io>
> Date: Tuesday, August 11, 2020 1:50 AM
>
>> Googling for [alphanumeric error codes] nailed it.  They pop up in
>> embedded devices with simple alphanumeric displays!
>
> True. Your links are illustrative. Also part numbers in catalogs.
>
> I don't know whether it's simply selection bias from the search terms,
> but all those links like to use the word "code". You say that DocBook
> also uses the that word. Hence we should probably adopt it.

Except in some cases as you note below, like the numbers for POSIX
errnos.  Though I'm not sure this should be made a standard convention
in the SRFI, vs. belonging in the Schemeregistry.

>> DocBook provides four elements for identifying the parts of an error
>> message: errorcode, for the alphanumeric error code (e.g., “–2”);
>> errorname, for the symbolic name of the error (e.g., “ENOENT”);
>> errortext, for the text of the error message (e.g., “file not
>> found”); and errortype, for the error type (e.g., “recoverable”).
>>
>> Maybe we should adopt these names.  DocBook has undergone a long
>> evolution already.
>
> I now strongly agree with 'code.

It would be helpful to come up with a 4th example in addition to
errnos, where I'm sticking to number due to your example below,
PostgreSQL where I say we punt the details to the Schemeregistry, and
for now I'm using 'SQLSTATE as a key for the '28P01 I'm using as an
example, and libsodium, which is too simple to have codes or numbers.

> 'text may be as good as 'message.

I prefer message, what it's supposed to do is much more clear, and
it's only 3 characters longer.  Since this is a standard key, I've
made note of this in the Issues.

> (foreign-status-ref st 'message)
> (foreign-status-ref st 'text)
>
> [...]
>
> OK, 'text seems as good as 'message and is a shorter word.
>
> The 'code and 'name combination is very clear indeed -- _in aggregate_:
>
> (raise-foreign-status
>   'code 128
>   'name 'ENETUNREACH
>   'text "Network is unreachable")
>
> (raise-foreign-status
>   'code 84
>   'name 'ERROR_OUT_OF_STRUCTURES
>   'text "Out of structures")
>
> [...]
>
> So it's no wonder they like it for manuals where errors are tabulated.
>
> But check out how unclear it is out of context:
>
> (if (eq? 'EINTR (foreign-status-ref st 'name))
>      ...)
>
> (if (= 4 (foreign-status-ref st 'code))
>      ...)
>
> Is name really a semi-cryptic symbol? Is code really a number?
>
> Worst of all, there's nothing obviously wrong with this:
>
> (if (eq? 'EINTR (foreign-status-ref st 'code))
>      ...)
>
> A caffeine-deficient code reviewer would not catch that mistake.
>
> By comparison, this is much more obvious:
>
> (if (eq? 'EINTR (foreign-status-ref st 'symbol))
>      ...)
>
> (if (= 4 (foreign-status-ref st 'number))
>      ...)
>
> And the mistake is much more obvious:
>
> (if (eq? 'EINTR (foreign-status-ref st 'number))
>      ...)
>
> Hence I would still go back to 'symbol and 'number for maximum clarity.

Thanks for thinking this through!  For errno I prefer keeping 'name,
and note it's the DocBook convention per the above.

> What to do about alphanumerics is not clear. I think we're blowing it
> out of proportion given the paucity of examples in software. We could
> either reuse 'symbol or add 'string or 'alphanumeric.
>
> As for a 'type field with values such as 'recoverable, that seems way
> generic. People could use 'recoverable? being #t or #f.

Agreed on both.

> [ 'severity, SQLSTATE ]
>
> "Each class belongs to one of four categories: "S" denotes "Success"
> (class 00), "W" denotes "Warning" (class 01), "N" denotes "No data"
> (class 02) and "X" denotes "Exception" (all other classes)."
>
> That category is basically a severity level. We could advise people who
> want to ship it to put it in the 'severity property.

Following, ah hem, Wikipedia for the moment, I'm using 'category.  But
'severity deserves serious consideration, and maybe elevation to an
SRFI level standard key.

- Harold