Digest #203 2022-12-30
2022-12-29: Initial proposal
Documenting all ambiguous conditions of a system can be burdensome for system implementers, while providing relatively little value to end-users.
Relax the 4.1.2 wording from "A system shall" to "A system should". In that way, partial or complete absence of this documentation will not make a system non-standard.
In section 4.1.2 Ambiguous Conditions, change "A system shall" to "A system should".
I agree. Currently nobody has announced a proposal to change the documentation requirements, though, and there have been no discussions in the committee about this. Maybe you want to make a proposal.
I notice that FORTH-83 Standard does not seem to have any document requirements whatsoever. That would be the extreme other end.
Would anyone agree that "removing chapter 4" is a reasonable proposal?
I would assume Chapter 4 was added for some compelling reason. But I am not able to find any rationale for it (this page is empty: https://forth.sourceforge.net/standard/dpans/dpansa4.htm), it is difficult to guess what the authors were aiming for.
Usually the required documentation plays small role for standard programs or standard-compliant libraries.
But this documentation is very important for system specific programs, to use the system in production, to compare different systems. The list of options itself is also very useful for understanding how systems may vary, and what points can be taken for consideration.
So, I would be against removing this section. Although, we can change the requirements from "shall" to "should". So, absence of this documentation will not make the system non-standard. But anyway, presence of this documentation shows better quality/support of the system.
See Chapter 2:
In this standard, "shall" states a requirement on a system or program; conversely, "shall not" is a prohibition; "need not" means "is not required to"; "should" describes a recommendation of the standard; and "may", depending on context, means "is allowed to" or "might happen".
ruv, thanks for your comment.
I think my main gripe with Chapter 4, is that it does not result in good documentation.
For reference, you can check Gforth manual, which I think is a honorable best-effort to abide by Chapter 4: https://www.complang.tuwien.ac.at/forth/gforth/Docs-html/core_002dambcond.html#core_002dambcond
Roughly speaking, this page contains 50 different variations of "it depends/do not know", this is not helpful for the user.
Thinking further, I am mostly irked by section 4.1.2. I will try to make a proposal, to change the "shall" of 4.1.2 to a "should". Thank you for your feedback.