Re: Specification rules around error logging

If the requirement is a MAY or SHOULD then I think I agree that saying âyou may issue a messageâ is equivalent to saying âyou may call the user and commiserate with them and maybe offer them a tissue and a glass of wineââit a true statement but doesnât add anything to the specification requirements.

My guess is that we were trying to emulate other standards like XSLT that do specify specific error codes for specific error conditions defined in the specification.

Given that DITA is not, strictly speaking, a processing standard in the way that something like XSLT is, I think I agree with Robert that identifying error conditions is sufficient and we can let processors present whatever error messages they want when they are unable to recover from a potentially recoverable error.

If there are places where a processor MUST issue some kind of error message itâs probably appropriate to specify the error code for the purpose of application behavior consistency but I donât know that we have any such cases any more.

Cheers,

_____________________________________________

Eliot Kimber

Sr Staff Content Engineer

O: 512 554 9368

M: 512 554 9368

servicenow.com

LinkedIn | Twitter | YouTube | Facebook

From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> on behalf of Robert Anderson <robert.dan.anderson@oracle.com>
Date: Tuesday, December 13, 2022 at 2:09 PM
To: dita@lists.oasis-open.org <dita@lists.oasis-open.org>
Subject: [dita] Specification rules around error logging

[External Email]

Hi all,

This question is coming out of discussions with one of our better-known DITA implementors.

In DITA 1.0 and 1.1 we had cases where the specification said that applications SHOULD or MUST generate an error message for certain conditions, or simply declared that implementations do so. In DITA 1.2 we largely switched over to the verbose "implementations may (but need not) recover by generating an error message". In DITA 1.3, these were largely simplified to "MAY recover".

The question I got was - why do we have these statements at all? We already state that these are error conditions, in which case applications can respond as appropriate for their context. This is highlighted by the fact that these are all MAY rules, giving applications permission to respond as they wish.

So the question for the TC is, do we need these? If we clearly and directly state that something is an error, is there any benefit to telling processors they MAY warn about the error? I think it's true that an application could generate an error message for everyâ error condition found in DITA source, but could also silently recover from every error. Both responses are valid. What's important for the spec is that we clearly identify the error conditions, so that implementations can find them and make that choice.

For what it's worth, we have this in about ten spots in the specification today -- a mix of "MAY recover by", "can recover by", and "might give an error message".

Thanks,

Robert

dita message

[External Email]