4 Documentation requirements

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.

4.1 System documentation

4.1.1 Implementation-defined options

The implementation-defined items in the following list represent characteristics and choices left to the discretion of the implementor, provided that the requirements of this standard are met. A system shall document the values for, or behaviors of, each item.

4.1.2 Ambiguous conditions

A system shall document the system action taken upon each of the general or specific ambiguous conditions identified in this standard. See 3.4.4 Possible actions on an ambiguous condition.

The following general ambiguous conditions could occur because of a combination of factors:

The following specific ambiguous conditions are noted in the glossary entries of the relevant words:

  • \x is not followed by two hexadecimal characters (6.2.2266 S\");
  • a \ is placed before any character, other than those defined in 6.2.2266 S\".

4.1.3 Other system documentation

A system shall provide the following information:

  • list of non-standard words using 6.2.2000 PAD (3.3.3.6 Other transient regions);
  • operator's terminal facilities available;
  • program data space available, in address units;
  • return stack space available, in cells;
  • stack space available, in cells;
  • system dictionary space required, in address units.

4.2 Program documentation

4.2.1 Environmental dependencies

A program shall document the following environmental dependencies, where they apply, and should document other known environmental dependencies:

4.2.2 Other program documentation

A program shall also document:

  • minimum operator's terminal facilities required;
  • whether a Standard System exists after the program is loaded.

ContributeContributions

ruvavatar of ruv [94] Executing compilation semanticsProposal2019-07-12 04:16:14

This contribution has been moved to the proposal section.

AntonErtlavatar of AntonErtl

This reply has been moved to the proposal section.
Accepted
Reply New Version

phisheepavatar of phisheep [268] Seemingly contradictory ambiguous condition?Request for clarification2022-09-08 07:51:27

While trying to document my ambiguous conditions, I came across this gem above:

"access to a deferred word, a word defined by 6.2.1173 DEFER, which was not defined by 6.2.1173 DEFER;"

It doesn't seem to mean anything. Do you know what it is supposed to mean?

AntonErtlavatar of AntonErtl

Confirmed. My guess is that the ambiguous conditions in DEFER! and DEFER@ were intended to be in this place.

phisheepavatar of phisheep

Thank you Anton. I propose we replace the current wording with:

"6.2.1171 DEFER@ 6.2.1175 DEFER! 6.2.0698 ACTION-OF or 6.2.1725 IS applied to a word which was not defined by 6.2.1173 DEFER"

Reply New Version

JohanKotlinskiavatar of JohanKotlinski [271] Comment2022-12-21 11:40:45

These documentation requirements seem burdensome and, in many cases, of little benefit to end users. I assume it is a holdover from ANS94. Is there any intent to relax this section in the future?

AntonErtlavatar of AntonErtl

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.

JohanKotlinskiavatar of JohanKotlinski

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.

ruvavatar of ruv

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

JohanKotlinskiavatar of JohanKotlinski

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.

JohanKotlinskiavatar of JohanKotlinski

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.

AntonErtlavatar of AntonErtl

My guess is that this section was added due to the options and ambiguous conditions in the standard, so how do you differentiate between a minimal and a maximal system? In theory, a user compares the program documentation with the system documentation to find out if the program runs on the system. In practice, nobody does that, and people just try out if the program runs on the system. And if it does not, users use debugging techniques to find out why rather than consulting the documentation. At least that's how I do it, and I have never heard about people who do it differently.

Looking at the VFX documentation, I don't find the standard-required system documentation in it. Maybe it exists somewhere, but the fact that it is not easy to find indicates that it is not really needed (and if it does not exist, that's an even stronger indication).

AntonErtlavatar of AntonErtl

One alternative would be to provide a way to supply the information in a way that a program can extract (and compare what the system provides with what the program requires. However, the environmental queries that have been a first step in that direction have been mostly implemented in the most useless way possible by a number of Forth systems, and programs have not made much use of them, so that approach is apparently not really attractive, either. So in Forth-2012 we decided to not introduce queries for the Forth-2012 variants of the wordsets and leave the existing ones as relating to the Forth-94 versions of the wordset.

An alternative theory is that the ENVIRONMENT? interface is just too cumbersome to be successful, but if there was really a big need for this kind of stuff, people would have jumped through that hoop.

JohanKotlinskiavatar of JohanKotlinski

Right... ENVIRONMENT? is a related topic indeed.

From my experience as software engineer, I know of two practical ways to make code portable between systems:

  1. avoid ambiguous behavior whenever possible.
  2. create a platform abstraction layer, that separates platform differences from the business logic.

As I see it, ENVIRONMENT? and section 4.1.2 do not really help towards either of those goals.

phisheepavatar of phisheep

I do not think the documentation requirements are particularly burdensome (having recently gone through the exercise myself), but now that the Exception word set is to be mandatory it could be considerably simplified. I propose replacing the opening paragraph of section 4.1.2 as follows:

"A system shall document the system action taken upon each of the general or specific ambiguous conditions identified in this standard if such action is other than one of the standard THROW codes in table 9.1. See 3.4.4 Possible actions on an ambiguous condition."

AntonErtlavatar of AntonErtl

This issue is superseded by the Proposal to relax the documentation requirements, so we are closing this one.

If any of the participants in the discussion wants to have a discussion of one of the other issues touched in this discussion, you are welcome to open a new topic about that.

Closed
Reply New Version

ruvavatar of ruv [338] Request for clarification2024-03-29 01:18:49

The section "4.1.2 Ambiguous conditions" says:

The following general ambiguous conditions could occur because of a combination of factors:

This wording seems unclear since in other places ambiguous conditions are declared using "to exist" rather than "to occur".

Don't you think this phrase should sound something like this:

  • The following general ambiguous conditions exist and could occur because of a combination of factors:
Reply New Version