Re: Error message style guide

Peter Eisentraut <peter_e(at)gmx(dot)net> writes:
> I would prefer leaving the formatting to client and have the backend
> provide a more semantic-type "markup". For example the newline character
> could be considered a paragraph break and within the paragraph the text
> just flows. (We could hack up some line-breaking logic in psql.)

I could live with that ... anyone have a hard time with it?

> Or a
> really fancy solution: Use the Unicode characters for line and paragraph
> breaks. *Really* fancy, admittedly.

I don't think this will fly; we'd have to express the Unicode characters
as octal escapes in the error message calls, no? Way too ugly.

If you think that putting soft line breaks and para breaks into message
texts would be useful, I'd lean to using \n and \f to do it. But the
simpler way you mentioned first seems sufficient.

>> Nonetheless I'm not sure that avoiding references to system calls will
>> improve matters. In particular, for cases that are really "can't
>> happen" situations (eg, we are normally not expecting select(2) to
>> fail), I'm not seeing the advantage of avoiding the reference.

> It was mostly meant as a broad hint not to write "open() failed", which
> can clearly be written more user-friendly without loss of information.
> For less obvious cases we can use a mixed style. Say 'could not
> synchronize file "%s" with disk (fsync failed)'. That tells people at
> least that it's got something to do with their I/O subsystem.

There are some places where we mention the syscall so that we can spell
out the exact parameters that were passed, for possible debugging use.
But this could probably be pushed to the "detail" message. So instead
of
IpcMemoryCreate: shmget(key=%d, size=%u, 0%o) failed: %m
(plus a long hint)
perhaps
Primary: Could not create shared memory segment: %m
Detail: Failed syscall was shmget(key=%d, size=%u, 0%o)
Hint: as before
Seem good?

BTW: in this particular case I notice that the code is set up to
generate different hints depending on the value of errno. One could
fake this in my original proposal using conditional expressions:

ereport(...,
(errno == EINVAL) ? errhint(...) : 0,
(errno == ENOMEM) ? errhint(...) : 0,
...);

This seems notationally klugy though. I wonder whether it's worth
making errhint's signature be
errhint(bool condition, const char *fmt, ...)
with the hint used only if the bool parameter is true.

regards, tom lane