Version 1.2 of ai12s/ai12-0438-1.txt

Unformatted version of ai12s/ai12-0438-1.txt version 1.2
Other versions for file ai12s/ai12-0438-1.txt

!standard 0.2(6) 22-05-05 AI12-0438-1/02
!standard 0.2(8)
!standard 0.2(14/2)
!standard 0.2(33)
!standard 0.2(36)
!standard A.18.2(237.7/5)
!standard A.18.3(151.6/5)
!standard A.18.4(75.7/5)
!standard A.18.7(98.18/5)
!standard A.18.10(218.6/5)
!standard C.7.2(30/2)
!class presentation 22-04-20
!status Amendment 1-2012 22-05-05
!status ARG Approved 14-0-0 22-05-05
!status work item 22-04-20
!status received 22-02-18
!priority Critical
!difficulty Medium
!subject Rewordings to remove "must"
!summary
Several paragraphs needed to be reworded to avoid using "must".
!question
ISO comment #20 says:
Verbal forms used to express provisions in the text do not always comply with the rules specified in the ISO/IEC Directives, Part 2. Do not use verbal forms ("could", "might", "need") that are not defined in the ISO/IEC Directives, Part 2.
Although this comment does not mention "must", it is mentioned in the directives as a form that should not be used. Should we fix any uses of "must"? (Yes.)
!recommendation
Replace "must" with "shall" where possible, and reword otherwise. This AI only contains changes that do not alter the meaning or understandability of the text. Other changes are found in AI12-0445-1.
!wording
Modify Introduction(6/2):
An Ada program is composed of one or more program units. Program units may be subprograms (which define executable algorithms), packages (which define collections of entities), task units (which define concurrent computations), protected units (which define operations for the coordinated sharing of data between tasks), or generic units (which define parameterized forms of packages and subprograms). Each program unit normally consists of two parts: a specification, containing the information that {is}[must be] visible to other units, and a body, containing the implementation details, which {are}[need] not [be] visible to other units. Most program units can be compiled separately.
[The Introduction is really non-normative material, but that wouldn't allow anything that could be mistaken as a requirement. Which would make it impossible to make the point at all. So we'll ignore that distinction here. I'm not sure if this text needs to appear in the ISO version, so we could eliminate it if the rewording isn't OK. - Editor]
Modify Introduction(8/2):
An Ada program will normally make use of a library of program units of general utility. The language provides means whereby individual organizations can construct their own libraries. All libraries are structured in a hierarchical manner; this enables the logical decomposition of a subsystem into individual components. The text of a separately compiled program unit {has to}[must] name the library units it requires.
Modify Introduction(14/2):
A protected unit is the basic unit for defining protected operations for the coordinated use of data shared between tasks. Simple mutual exclusion is provided automatically, and more elaborate sharing protocols can be defined. A protected operation can either be a subprogram or an entry. A protected entry specifies a Boolean expression (an entry barrier) that {has to}[must] be True before the body of the entry is executed. A protected unit may define a single protected object or a protected type permitting the creation of several similar objects.
Modify Introduction(33/2):
From any type a new type may be defined by derivation. A type, together with its derivatives (both direct and indirect) form a derivation class. Class-wide operations may be defined that accept as a parameter an operand of any type in a derivation class. For record and private types, the derivatives may be extensions of the parent type. Types that support these object-oriented capabilities of class-wide operations and type extension {have to}[must] be tagged, so that the specific type of an operand within a derivation class can be identified at run time. When an operation of a tagged type is applied to an operand whose specific type is not known until run time, implicit dispatching is performed based on the tag of the operand.
Modify Introduction(36/2):
Aspect clauses can be used to specify the mapping between types and features of an underlying machine. For example, the user can specify that objects of a given type {are to}[must] be represented with a given number of bits, or that the components of a record are to be represented using a given storage layout. Other features allow the controlled use of low level, nonportable, or implementation-dependent aspects, including the direct insertion of machine code.
Modify A.18.2(237.7/5):
If a stable vector is declared without specifying Base, the object {has to}[must] be initialized. The initializing expression of the stable vector, typically a call on To_Vector or Copy, determines the Length of the vector. The Length of a stable vector never changes after initialization.
{AARM Proof: Initialization is required as the type is indefinite, see 3.3.1.}
Modify A.18.3(151.6/5):
If a stable list is declared without specifying Base, the object {has to}[must] be initialized. The initializing expression of the stable list, typically a call on Copy, determines the Length of the list. The Length of a stable list never changes after initialization.
{AARM Proof: Initialization is required as the type is indefinite, see 3.3.1.}
Modify A.18.4(75.6/5):
If a stable map is declared without specifying Base, the object {has to}[must] be initialized. The initializing expression of the stable map, typically a call on Copy, determines the Length of the map. The Length of a stable map never changes after initialization.
{AARM Proof: Initialization is required as the type is indefinite, see 3.3.1.}
Modify A.18.7(98.18/5):
If a stable set is declared without specifying Base, the object {has to}[must] be initialized. The initializing expression of the stable set, typically a call on Copy, determines the Length of the set. The Length of a stable set never changes after initialization.
{AARM Proof: Initialization is required as the type is indefinite, see 3.3.1.}
Modify A.18.10(218.6/5):
If a stable tree is declared without specifying Base, the object {has to}[must] be initialized. The initializing expression of the stable tree, typically a call on Copy, determines the Node_Count of the tree. The Node_Count of a stable tree never changes after initialization.
{AARM Proof: Initialization is required as the type is indefinite, see 3.3.1.}
Modify C.7.2(30/2):
Some implementations are targeted to domains in which memory use at run time {has to}[must] be completely deterministic. For such implementations, it is recommended that the storage for task attributes will be pre-allocated statically and not from the heap. This can be accomplished by either placing restrictions on the number and the size of the attributes of a task, or by using the pre-allocated storage for the first N attribute objects, and the heap for the others. In the latter case, N should be documented.
!discussion
To summarize the relevant ISO rules from the Directives part 2:
Requirements use "shall" preferably, or phrases involving forms of "require", "has to", or "it is necessary". "Must" is not allowed (it can be used for external requirements, such as government laws, but that usually doesn't apply to us).
Other forms are not allowed to express requirements. The ISO House Rules document goes further and bans a number of other words completely. More on this topic can be found in AI12-0445-1.
---
We could consider making wording changes only for the ISO version (new commands would be needed in the formatter to support that if is done a lot
- currently, we can only do that on a full paragraph basis or with a few
macros - but new commands should not be hard to define and implement).
However, that would add complications to future maintenance (as we would need to somehow have both versions in any Corrigendum document, one for our use and one for the actual ISO Corrigendum). As such, we want to make any changes that do not clearly alter the meaning or harm the understandability of the text.
!ASIS
No ASIS effect.
!ACATS test
No ACATS test should be needed, no change in meaning is intended and these are notes anyway.
!appendix

****************************************************************



Questions? Ask the ACAA Technical Agent