[272] 2022-12-29 19:25:35 JohanKotlinski wrote:

proposal - Relax documentation requirements of Ambiguous Conditions

Author:

Johan Kotlinski

Change Log:

2022-12-29: Initial proposal

Problem:

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

Solution:

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.

Proposal:

In section 4.1.2 Ambiguous Conditions, change "A system shall" to "A system should".

Reference implementation:

N/A

[r933] 2022-12-22 11:11:08 AntonErtl replies:

comment -

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.

[r934] 2022-12-28 22:31:03 JohanKotlinski replies:

comment -

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.

[r935] 2022-12-29 08:58:27 ruv replies:

comment -

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".

[r936] 2022-12-29 11:49:43 JohanKotlinski replies:

comment -

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.

[r937] 2022-12-29 18:05:36 JohanKotlinski replies:

comment -

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.