Proposal: Relax documentation requirements of Ambiguous Conditions

"Documenting all ambiguous conditions of a system can be burdensome for system implementers, while providing relatively little value to end-users."

As an end user, I want the documentation for all ambiguous conditions. I don't want to have to discover them while creating an application, then go to a support site, or, worse yet, have to read the source, for which I may not even have a license!

znmeb, thank you for your feedback. Out of curiosity, could you give some example documentation of ambiguous conditions that you like to use?

znmeb writes:

As an end user, I want the documentation for all ambiguous conditions.

Do you think that less systems will provide this documentation if this documentation will no longer be required (but only recommended) for a standard system?

znmeb writes:

I don't want to have to discover them while creating an application

Just take into account that if your application relies on some specific behavior in an ambiguous condition, then your application has an environmental dependency.

See Chapter 3: "A program that requires a system to provide words or techniques not defined in this standard has an environmental dependency". So, if a program requires a system to have some specific capability beyond minimal, or behavior, which is not defined by the standard, then this program has an environmental dependency.

A standard program without environmental dependencies does not need to know what is the system behavior in any ambiguous condition.

OTOH, to choose a system for use in production you probably need to know what is the system behavior in certain cases. For example, how to handle a case of "addressing a region not listed in 3.3.3 Data space" (including a case when the address is not mapped to physical memory at all).

If a system does not provide the documentation for a specific behavior or feature that a program requires, then this system just does not formally meet the environmental dependencies of the program. Why should it make the system non standard?

We discussed this issue at the meeting on 2023-02-17. We decided to proceed this proposal to CfV status, in order to hear more feedback from the wider community once the voting actually works.

The issue at hand is: Has the information in your favourite Forth system's documentation about ambiguous conditions really ever been of use to you, or is it just busywork for system implementors?

By the way, the introduction of Chapter 4 already allows to not specify a particular behavior in an ambiguous condition case, but it still requires to explain reasons.

The preprogrammed answers make no sense in this case.

What I want to say that is that ciforth doesn't conform to the standard requirements of documentation. The only documentation is that if you invoke an ambiguous condition, the operating system will crash the program. There is an exception. If you depend on a ciforth documented behaviour, that is not guaranteed by the standard, you have a ciforth dependancy, and you are entitled to report defects against that behaviour.

Actually the requirement as it stands is too severe. The behaviour on actual ambiguous conditions is not necessarily under the control of the Forth implementor. The original wording required a massive retesting for each new release of MS-Windows, possibly for security releases as well. This proposal is actually a confirmation of existing practice.

This proposal is just wording change, and it affects neither existing Forth systems nor existing programs.

After this change in the standard, new Forth systems (or new versions) are allowed to provide less documentation than before this change, but are not obligated to do it. Therefore, a system cannot avoid implementing this proposal, and cannot fail to implement this proposal.

Concerning programmers/users. If a user has ever used the system's documentation about ambiguous conditions — does that mean that they have used this proposal or not used this proposal?

Yes, the choices on the ballot do not fit the proposal.

For programmers, good choices would be:

• I have looked into a system's documentation for ambiguous conditions, and found it helpful.
• I have never found a system's documentation for ambiguous conditions helpful (possibly because I never looked there).

For systems, good choices would be:

• <system>'s documentation satisfies the requirements.
• <system>'s documentation will document the behaviour of the system on all ambiguous conditions in 4.1.2 even if it is not required.
• At some point <system>'s documentation will not document the behaviour of the system on all ambiguous conditions in 4.1.2 if it is not required.

Note that the three choices for the system are not all mutually exclusive. So checkboxes are more appropriate than a drop-down menu or radio buttons. And of course the committee member starting the CfV must have a way to specify the choices. Plus, for other votes, it should be possible to specify system versions for some choices.

I would rather recommend to continue the work to remove ambiguous conditions from the standard, so that words become more predictable. That will also reduce the burden of documentation without making programmers scratch their heads what's going to happen in these cases.

I still propose to reduce the number of ambiguous conditions the standard allows, but when the standard allows these, having documentation about these is helpful.

There is an inconsistency in the section 4.1.2 Ambiguous conditions, which says:

A system shall document the system action taken upon each of the general or specific ambiguous conditions identified in this standard.

and the the introduction into the chapter 4 Documentation requirements, which says:

When it is impossible or infeasible for a system or program to define a particular behavior itself, it is permissible to state that the behavior is unspecifiable and to explain the circumstances and reasons why this is so.

(emphasis mine in both cases)

If 4.1.2 will say "should" instead of "shall" — the inconsistency will be eliminated. Another way is to add into 4.1.2 the option "or state that the behavior is unspecifiable". Probably, it is also better to use either "system action" or "behavior" in both cases.

We should take into account that it's impossible to document the behavior in some cases because it depends on many factors. For example: "An ambiguous condition exists if an incorrectly typed data object is encountered" — what behavior can be documented in this case?

For example, SP-Forth/4 documents behavior in some ambiguous conditions, but not in all (see online version, source code). In SP-Forth, we will continue do document behavior in some ambiguous conditions.

Personally, I usually don't consult the documentation, but test the system interactively, and in some rare case I view the corresponding source code.