Version 1.2 of ai12s/ai12-0442-1.txt
!standard 3.4(34) 22-05-05 AI12-0442-1/02
!standard 3.5(58)
!standard 3.5.5(12)
!standard 3.5.9(22)
!standard 3.5.9(24)
!standard 3.6.1(12)
!standard 3.9(27)
!standard 3.9.3(16)
!standard 3.9.4(26/2)
!standard 3.10.2(39)
!standard 4.3.5(85/5)
!standard 4.7(9)
!standard 4.8(15/3)
!standard 5.1(18/5)
!standard 5.2.1(8/5)
!standard 5.5(14)
!standard 6.1.1(43/3)
!standard 6.1.2(18/5)
!standard 7.3(18)
!standard 7.3(20/2)
!standard 7.3(20.1/2)
!standard 7.5(9/3)
!standard 7.6.1(24)
!standard 8.1(18)
!standard 8.5(4)
!standard 9.1(21/2)
!standard 9.2(8)
!standard 9.5.3(29)
!standard 9.6.1(90/5)
!standard 9.7.4(13)
!standard 9.8(22)
!standard 9.9(7)
!standard 10.1.1(27)
!standard 10.1.4(9)
!standard 10.2(34)
!standard 11.4.2(28/2)
!standard 11.5(29)
!standard 12.5.1(5.1/4)
!standard 12.5.1(6/3)
!standard 12.5.1(24/2)
!standard 12.5.1(25)
!standard 12.5.1(26)
!standard 12.5.2(9)
!standard 12.6(11)
!standard 12.6(16.1/2)
!standard 13.4(11/3)
!standard 13.9.2(14/2)
!standard 13.11(26)
!standard 13.11.4(33/3)
!standard 13.11.4(35/3)
!standard 13.13.2(57)
!standard A.4.3(107/3)
!standard A.5.2(50)
!standard A.16(127/2)
!standard A.16(131/2)
!standard A.16.1(37/2)
!standard A.18.3(164/2)
!standard B.3.1(60)
!standard B.4(112)
!standard C.3.1(23/2)
!standard C.7.2(31)
!standard C.7.2(32)
!standard D.2.5(18/2)
!standard D.3(21)
!standard D.5.1(19)
!standard E.2.2(18)
!standard E.4.2(12)
!standard H.5(7/2)
!class presentation 22-04-25
!status Amendment 1-2012 22-05-05
!status ARG Approved 14-0-0 22-05-05
!status work item 22-04-25
!status received 22-02-18
!priority Critical
!difficulty Medium
!subject Rewordings of notes
!summary
Many notes need to be reworded.
!question
ISO comment #16 includes a mention of the fact that the drafting rules do not
allow any requirements, recommendations, or permissions in notes. We of course
follow the spirit of that rule, but we do not follow the letter, which does
not allow any phrasing that might be mistook for one of these things.
We also need to reword many notes to avoid words and phrases that aren't
allowed at all ("must", "might", "could", "need") - see AI12-0445-1.
There are many notes that need rewording, and for many of them the rewordings
are complex.
!recommendation
Simple rewordings which simply replace an existing word with "can" are found
in AI12-0440-1. This AI contains the more complex rewordings necessary for the
remaining notes.
!wording
Modify 3.4(34):
NOTE 7 For an inherited subprogram, the subtype of a formal
parameter of the derived type {can be such that it has no}[need not have
any] value in common with the first subtype of the derived type.
[Replace "need not" -Editor.]
Modify 3.5(58):
NOTE 2 For a subtype of a scalar type, the result delivered by the
attributes Succ, Pred, and Value {can be outside}[might not belong to]
the subtype; similarly, the actual parameters of the attributes Succ,
Pred, and Image {are also allowed to be outside}[need not belong to]
the subtype.
["Might not" and "need not" are both on the ISO list (as opposed to the
Directives). AI12-0445-1 now defines "outside" for this use (it already appeared
in a pair of Implementation Permissions) - Editor.]
Modify 3.5.5(12):
NOTE 4 For a subtype of a discrete type, the result delivered by the
attribute Val {can be outside}[might not belong to] the subtype;
similarly, the actual parameter of the attribute Pos {is also allowed
to be outside}[need not belong to] the subtype. The following relations
are satisfied (in the absence of an exception) by these attributes:
["Might not" and "need not" are both on the ISO list; see 3.5 above - Editor.]
Modify 3.5.9(22):
NOTE The {specified bounds themselves can be outside the} base range
of an ordinary fixed point type [need not include
the specified bounds themselves] so that the range specification can be
given in a natural way, such as:
["Might not" and "need not" are both on the ISO list; see 3.5 above - Editor.]
Modify 3.5.9(24):
With 2's complement hardware, such a type {would typically}[could]
have a signed 16-bit representation, using 1 bit for the sign and
15 bits for fraction, resulting in a base range of -1.0 .. 1.0-2.0**(-15).
[Replace "could have" - Editor.]
Modify 3.6.1(12):
Board : Matrix(1 .. 8, 1 .. 8); --
Rectangle : Matrix(1 .. 20, 1 .. 30);
Inverse : Matrix(1 .. N, 1 .. N); --
["need not" is replaced - Editor.]
Modify 3.9(27):
NOTE 1 A type declared with the reserved word tagged {is}[should]
normally [be] declared in a package_specification, so that new primitive
subprograms can be declared for it.
[Replace "should". This is a usage recommendation, and could have been
moved unchanged to a new normative "Usage Advice" grouping - Editor.]
Modify 3.9.3(16):
NOTE 3 Notes on the example: Given the above abstract type, one
{can}[could then] derive various (nonabstract) extensions of the type,
representing alternative implementations of a set. One {possibility
is to}[might] use a bit vector, but impose an upper bound on the largest
element representable, while another possible implementation is a hash
table, trading off space for flexibility.
[Replace "might" and "could" - Editor.]
Modify 3.9.4(26/2):
This defines a Queue interface defining a queue of people. (A similar
design {is possible}[could be created] to define any kind of queue
simply by replacing Person_Name by an appropriate type.) The Queue
interface has four dispatching operations, Append, Remove_First,
Cur_Count, and Max_Count. The body of a class-wide operation, Transfer
is also shown. Every nonabstract extension of Queue {will}[must]
provide implementations for at least its four dispatching operations, as
they are abstract. Any object of a type derived from Queue {can}[may] be
passed to Transfer as either the From or the To operand. The two operands
{can be of different types in a}[need not be of the same type in any]
given call.
[Replacement for "May, "need not", "must", "could be" - this paragraph has
everything we're not supposed to say! - Editor.]
Modify 3.10.2(39):
NOTE 7 An implementation {can}[may] consider two access-to-subprogram
values to be unequal, even though they designate the same subprogram.
{For instance, this can happen}[This might be] because one points
directly to the subprogram, while the other points to a special prologue
that performs an Elaboration_Check and then jumps to the subprogram.
See 4.5.2.
[Replace "may" and "might".]
Modify 4.3.5(85/5):
-- A map aggregate where the values produced by the
-- iterated_element_association are of the same type as the key
-- ({hence}[eliminating the need for] a separate key_expression {is unnecessary}):
M := [for Key of Keys => Integer'Image (Key)];
[Replace "need". I tried "required", but it implies a requirement and thus
can't be used - Editor.]
Modify 4.7(9):
Part of the examples:
for J in Code'(Fix) .. Code'(Dec) loop ... --
for J in Code range Fix .. Dec loop ... --
for J in Code'(Fix) .. Dec loop ... --
[Replace "needed" - Editor.]
Modify 4.8(15/3):
NOTE 4 Implementations {can, if desired}[are permitted, but not
required], [to] provide garbage collection.
[Neither a permission nor a requirement should be mentioned here, just a
statement of fact - Editor.]
Modify 5.1(18/5):
During the execution of a parallel construct, it is a bounded error to
invoke an operation that is potentially blocking (see 9.5). Program_Error is
raised if the error is detected by the implementation; otherwise, the
execution of the potentially blocking operation {can either}[might] proceed
normally, or it {can}[might] result in the indefinite blocking of some or
all of the logical threads of control making up the current task.
[Replace "might" - Editor.]
Modify 5.2.1(8/5):
My_Complex_Array : array (1 .. Max) of Complex; --
...
--
My_Complex_Array (Count) := (Re => @.Re**2 - @.Im**2,
Im => 2.0 * @.Re * @.Im);
--
[Replace "needed" - Editor.]
Modify 5.5(14):
NOTE 2 {No separate}[An] object_declaration {is expected}[should not be
given] for a loop parameter, since the loop parameter is automatically
declared by the loop_parameter_specification. The scope of a loop
parameter extends from the loop_parameter_specification to the end of the
loop_statement, and the visibility rules are such that a loop
parameter is only visible within the sequence_of_statements of the loop.
[I tried "ought not", but that is considered a synomym for "shall not".
This really reads as a recommendation, which is not allowed in a note. We use
notes for recommendations to the programmer, but that is simply not allowed (and
probably would be considered inappropriate for a Standard at all) - Editor.]
Modify 6.1.1(43/3):
NOTE 1 A precondition is checked just before the call. If another
task can change any value that the precondition expression depends on,
the precondition {can evaluate to False}[need not hold] within the
subprogram or entry body.
["need not" is replaced - Editor.]
Modify 6.1.2(18/5):
The Global aspect for a callable entity defines the global variables that
{can}[might] be referenced as part of a call on the entity, including any
assertion expressions that apply to the call (even if not enabled),
{such as}[including] preconditions, postconditions, predicates, and type
invariants.
["including" is given twice here, I recommend changing the second one as
marked. It's annoying to re-read wording 'cause one sees mistakes never
before seen. - Editor.]
Modify 7.3(18):
NOTE 1 The partial view of a type as declared by a
private_type_declaration is defined to be a composite view (in 3.2).
The full view of the type {can}[might or might not] be {elementary
or }composite. A private extension is also composite, as is its full view.
["might or might not" is replaced by giving both possibilities - Editor.]
Modify 7.3(20/2):
NOTE 3 The ancestor type specified in a private_extension_declaration
and the parent type specified in the corresponding declaration of a record
extension given in the private part {can be different}[need not be the
same]. If the ancestor type is not an interface type, the parent type of
the full view can be any descendant of the ancestor type. In this case,
for a primitive subprogram that is inherited from the ancestor type and
not overridden, the formal parameter names and default expressions (if
any) come from the corresponding primitive subprogram of the specified
ancestor type, while the body comes from the corresponding primitive
subprogram of the parent type of the full view. See 3.9.2.
["need not" is replaced - Editor.]
Modify 7.3(20.1/2):
NOTE 4 If the ancestor type specified in a private_extension_declaration
is an interface type, the parent type can be any type so long as the full
view is a descendant of the ancestor type. The progenitor types specified
in a private_extension_declaration and the progenitor types specified in
the corresponding declaration of a record extension given in the
private part {are not necessarily}[need not be] the same - {it is only
necessary}[the only requirement is] that the private extension and the
record extension be descended from the same set of interfaces.
["need not" and "requirement" are replaced - Editor.]
Modify 7.5(9/3):
NOTE 1 While it is allowed to write initializations of limited
objects, such initializations never copy a limited object. The source
of such an assignment operation {will}[must] be an aggregate or
function_call, and such aggregates and function_calls {will}[must] be
built directly in the target object (see 7.6).
[Replace "must" - Editor.]
Modify 7.6.1(24):
NOTE 4 The Finalize procedure is called upon finalization of a
controlled object, even if Finalize was called earlier, either
explicitly or as part of an assignment; hence, if a controlled type is
visibly controlled (implying that its Finalize primitive is directly
callable), or is nonlimited (implying that assignment is allowed), its
Finalize procedure {is ideally}[should be] designed to have no ill
effect if it is applied a second time to the same object.
[Another usage recommendation (see 3.9 note) - Editor.]
Modify 8.1(18):
NOTE 3 For a declarative region that comes in multiple parts, the
text of the declarative region does not {include}[contain] any {of the}
text that {appears}[might appear] between the parts. Thus, when a portion
of a declarative region is said to extend from one place to another in
the declarative region, the portion does not contain any {of the} text
that {appears}[might appear] between the parts of the declarative region.
[Replace "might"; "can" does not work here, so a more significant rewrite - Editor.]
Modify 8.5(4):
NOTE 1 Renaming {can}[may] be used to resolve name conflicts and to act as
a shorthand. Renaming with a different identifier or operator_symbol
does not hide the old name; the new name and the old name {can}[need not] be
visible at {different}[the same] places.
[Replace "may" and "need not" - Editor.]
Modify 9.1(21/2):
NOTE 3 A task type is a limited type (see 7.5), and hence precludes
use of assignment_statements and predefined equality operators. If {a
programmer wants to write }an application {that stores and
exchanges}[needs to store and exchange] task identities, {they}[it] can
do so by defining an access type designating the corresponding task
objects and by using access values for identification purposes. Assignment
is available for such an access type as for any access type.
Alternatively, if the implementation supports the Systems Programming
Annex, the Identity attribute can be used for task identification (see
C.7.1).
["needs" is replaced (in the phrase "needs to", which is definitely on the ISO
blacklist) - Editor.]
Modify 9.2(8):
NOTE 2 If several tasks are activated together, the execution of any
of these tasks {can proceed without waiting until}[need not await] the
end of the activation of the other tasks.
["need not" is replaced - Editor.]
Modify 9.5.3(29):
NOTE 4 The condition of an entry_barrier is allowed to be evaluated
by an implementation more often than strictly necessary, even if the
evaluation {can}[might] have side effects. On the other hand, an
implementation {can avoid reevaluating}[need not reevaluate] the condition
if nothing it references was updated by an intervening protected
action on the protected object, even if the condition references some
global variable that {is}[might have been] updated by an action performed
from outside of a protected action.
[Replace "might" and "need not". The second "might" does not work with "can",
so a different rewording is needed - Editor.]
Modify 9.6.1(90/5):
NOTE 1 The implementation-defined time zone of package Calendar
{can}[may, but need not,] be the local time zone{, or it can be some other
time zone like UTC}. Local_Time_Offset always returns the difference
relative to the implementation-defined time zone of package Calendar. If
Local_Time_Offset does not raise Unknown_Zone_Error, UTC time can be
safely calculated (within the accuracy of the underlying time-base).
[Replace "may", eliminate "need not" - Editor.]
Modify 9.7.4(13):
select
delay 5.0;
Put_Line("Calculation does not converge");
then abort
--
--
Horribly_Complicated_Recursive_Function(X, Y);
end select;
["Should" not allowed in examples (I checked the Directives) - Editor.]
Modify 9.8(22):
NOTE 1 An abort_statement {is best}[should be] used only in situations
requiring unconditional termination.
[Another usage recommendation (see 3.9 note) - Editor.]
Modify 9.9(7):
NOTE 2 Within task units, {by}[algorithms] interrogating the attribute
E'Count {an algorithm can}[should take precautions to] allow for the
increase of the value of this attribute for incoming entry calls,
and its decrease, for example with timed_entry_calls. {A}[Also, a]
conditional_entry_call {can also}[may]
briefly increase this value, even if the conditional call is not accepted.
[Another usage recommendation (see 3.9 note) - Editor.]
Modify 10.1.1(27):
NOTE 1 A simple program {can}[may] consist of a single compilation unit.
A compilation {can have no}[need not have any] compilation units; for
example, its text can consist of pragmas.
[Replace "may" and "need not" - Editor.]
Modify 10.1.4(9):
NOTE 2 An implementation {can}[may] support a concept of a library, which
contains library_items. If multiple libraries are supported, the
implementation {can document}[has to define] how a single environment
is constructed when a compilation unit is submitted to the compiler.
Naming conflicts between different libraries {can, for example,}[might]
be resolved by treating each library
as the root of a hierarchy of child library units.
[Eliminates "has to define", which sounds like a requirement, as well as the usual
"may" and "might" fixes - Editor.]
Modify 10.2(34):
NOTE 4 A partition (active or otherwise) {does not necessarily}[need
not] have a main subprogram. In such a case, all the work done by the
partition would be done by elaboration of various library_items, and by
tasks created by that elaboration. Passive partitions, which cannot have
main subprograms, are defined in Annex E, "Distributed Systems".
["Need not" is replaced - Editor.]
Modify 11.4.2(28/2):
NOTE Normally, the boolean expression in a pragma Assert {does}[should]
not call functions that have significant side effects when the result of
the expression is True, so that the particular assertion policy in
effect will not affect normal operation of the program.
[Another usage recommendation (see 3.9 note) - Editor.]
Modify 11.5(29):
NOTE 1 There is no guarantee that a suppressed check is actually
removed; hence a pragma Suppress {is useful only to improve
efficiency}[should be used only for efficiency reasons].
[Remove recommendation - Editor.]
Modify 12.5.1(5.1/4):
The actual type for a formal derived type shall be a descendant of the
ancestor type and every progenitor of the formal type. [If the formal type is
nonlimited, the actual type shall be nonlimited. ]The actual type for a formal
derived type shall be tagged if and only if the formal derived type is a
private extension. If the reserved word synchronized appears in the
declaration of the formal derived type, the actual type shall be a
synchronized tagged type.
[See discussion after 12.5.1(26) for why we're making this change - Editor.]
Modify 12.5.1(6/3):
If a formal private or derived subtype is definite, then the actual subtype
shall also be definite. {If the formal type is nonlimited, the actual type
shall be nonlimited.}
[See discussion after 12.5.1(26) for why we're making this change - Editor.]
Delete 12.5.1(24/2 - 26):
NOTE 1 In accordance with the general rule that the actual type
shall belong to the category determined for the formal
(see 12.5, "Formal Types"):
* If the formal type is nonlimited, then so shall be the
actual;
* For a formal derived type, the actual shall be in the class rooted
at the ancestor subtype.
[As a note, this should not include "shall".
Tucker says this isn't a Note; it should be Redundant text. However, we have
such redundant text at the top of the subclause (not as formally described, but
definitely the same point). It appears this Note predates the formal use of
"category" and the associated rewrite of the introduction to this subclause
(the original Ada 95 wording used "class"). The AARM proof also gives the
reference to 12.5.
Additionally, we have a rule that the actual is a descendant of the ancestor
(it's marked as redundant, and the proof given is similar to the note above),
so the second bullet is explicitly stated and doesn't follow from anything.
Finally, 12.5.1(5.1/4), sentence 2 explicitly states that the actual has to be
nonlimited if the formal is (and this is not even marked as Redundant).
Unfortunately, it is unclear if that sentence applies to formal private types;
read literally, it does, but it is in a paragraph that otherwise only talks
about formal derived types. We therefore move it to 12.5.1(6/3) to make it
clear that it applies to both. If we were working on a new revision rather
than "minor" changes to an approved DIS, I would suggest moving the entirety
of 12.5.1(6) (with the new part) after 12.5.1(4) so that the rules that apply
to all private and derived formals appear before the ones that apply only to
derived formals. But that seems like a bit much as an editorial change.
One could also consider moving the "limited" sentence to 12.5, since
it appears to be written to apply to all formal types, but that is definitely
out of bounds at this time.)
Ultimately, there seems to be nothing in this note that isn't already stated
elsewhere (several times), and thus there is no reason to keep any of it,
even in the AARM (especially given that it is problematic). It is
deleted - Editor.]
Delete 12.5.2(9):
NOTE The actual type shall be in the class of types implied by the
syntactic category of the formal type definition (see 12.5, "
Formal Types"). For example, the actual for a
formal_modular_type_definition shall be a modular type.
[As a note, this should not include "shall".
Tucker says this isn't a Note; it should be Redundant text. However, we have
such redundant text at the top of the subclause (not quite as formally stated,
but definitely the same point). Moreover, the AARM proof essentially repeats
this note. As such, this note is completely redundant and should simply be
deleted - Editor.]
Modify 12.5.5(5/5):
Example of the use of a generic with a formal interface type, to establish a
standard interface that all tasks {will}[need to] implement so they can be
managed appropriately by an application-specific scheduler:
["need to" is replaced - Editor.]
Modify 12.6(11):
NOTE 1 The matching rules for formal subprograms state requirements
that are similar to those applying to subprogram_renaming_declarations
(see 8.5.4). In particular, the name of a parameter of the formal
subprogram {can be different from}[need not be the same as] that of the
corresponding parameter of the actual subprogram; similarly, for these
parameters, default_expressions need not correspond.
["need not" is replaced - Editor.]
Modify 12.6(16.1/2):
NOTE 7 The subprogram declared by a formal_abstract_subprogram_-
declaration is an abstract subprogram. All calls on a subprogram
declared by a formal_abstract_subprogram_declaration {are limited
to}[must be] dispatching calls. See 3.9.3.
[Replace "must" - Editor.]
Modify 13.4(11/3):
NOTE Attribute Enum_Rep {can}[may] be used to query the internal codes
used for an enumeration type; attribute Enum_Val {can}[may] be used to
convert from an internal code to an enumeration value. The other
attributes of the type, such as Succ, Pred, and Pos, are unaffected by
{an}[the] enumeration_representation_clause. For example, Pos always
returns the position number, not {an}[the] internal integer code that
{was}[might have been] specified in an enumeration_representation_clause.
[Fix "may", "might have been". Tuck suggested using "an" rather than "the" to
avoid implying that an enumeration_representation_clause always
exists - Editor.]
Modify 13.9.2(14/2):
NOTE 3 The Valid attribute {can}[may] be used to check the result of
calling an instance of Unchecked_Conversion (or any other operation
that can return invalid values). However, an exception handler {is
still useful}[should also be provided] because implementations are
permitted to raise Constraint_Error or Program_Error if they detect
the use of an invalid representation (see 13.9.1).
[Replace "may", usage recommendation (see 3.9 note) - Editor.]
Modify 13.11(26):
NOTE 1 A user-defined storage pool type can be obtained by extending
the Root_Storage_Pool type, and overriding the primitive subprograms
Allocate, Deallocate, and Storage_Size. A user-defined storage pool
can then be obtained by declaring an object of the type extension. The
user can override Initialize and Finalize if there is any {desire}[need]
for nontrivial initialization and finalization for a user-defined pool
type. For example, Finalize {can}[might] reclaim blocks of storage that
are allocated separately from the pool object itself.
[Replace "might" and "need" - Editor.]
Modify 13.11.4(33/3):
NOTE 1 A user-defined storage pool type that supports subpools can
be implemented by extending the Root_Storage_Pool_With_Subpools type,
and overriding the primitive subprograms Create_Subpool,
Allocate_From_Subpool, and Deallocate_Subpool. Create_Subpool {is
expected to}[should] call Set_Pool_Of_Subpool before returning the
subpool handle. To make use of such a pool, a user {can}[would] declare an
object of the type extension, use it to define the Storage_Pool
attribute of one or more access types, and then call Create_Subpool
to obtain subpool handles associated with the pool.
[Replace "should", "would" - Editor.]
Modify 13.11.4(35/3):
NOTE 3 The pool implementor {can}[should] override Default_Subpool_For_Pool
if {they want} the pool [is] to support a default subpool for the pool. The
implementor can override Deallocate if individual object reclamation
is to be supported, and can override Storage_Size if there is some
limit on the total size of the storage pool. The implementor can override
Initialize and Finalize if there is any {desire}[need] for nontrivial
initialization and finalization for the pool as a whole. For example,
Finalize {can}[might] reclaim blocks of storage that are allocated over and
above the space occupied by the pool object itself. The pool
implementor {can}[may] extend the Root_Subpool type as necessary to carry
additional information with each subpool provided by Create_Subpool.
[Replace "may", "might", "need", and "should". The grand slam - Editor.]
Modify 13.13.2(57):
NOTE 1 For a definite subtype S of a type T, only T'Write and T'Read
are {necessary}[needed] to pass an arbitrary value of the subtype
through a stream. For an indefinite subtype S of a type T, T'Output
and T'Input will normally be {necessary}[needed], since T'Write and
T'Read do not pass bounds, discriminants, or tags.
["needed" is replaced - Editor.]
Modify A.4.3(107/3):
NOTE 1 In the Index and Count functions taking Pattern and Mapping
parameters, {for there to be a match, }the actual String parameter
passed to Pattern {can contain only}[should comprise] characters
occurring as target characters of the mapping.
[Otherwise, the pattern will not match.]
[Rewrite to eliminate "should" - Editor.]
Modify A.5.2(50):
NOTE 3 A given implementation of the Random function in
Numerics.Float_Random {is not guaranteed to}[may or may not]
be capable of delivering the values 0.0 or 1.0. {Applications will be
more portable if they}[Portable applications should] assume
that these values, or values sufficiently close to them to behave
indistinguishably from them, can occur. If a sequence of random
integers from some fixed range is {necessary}[needed], the application
should use the Random function in an appropriate instantiation of
Numerics.Discrete_Random, rather than transforming the result of the
Random function in Numerics.Float_Random. However, some applications
with unusual requirements, such as for a sequence of random integers
each drawn from a different range, will find it more convenient to
transform the result of the floating point Random function. For M >=
1, the expression
[Replace "may or may not", "should", "need" - Editor.]
Modify A.16(127/2):
NOTE 1 The operations Containing_Directory, Full_Name, Simple_Name,
Base_Name, Extension, and Compose operate on file names, not external
files. The files identified by these operations do not {necessarily}[need to]
exist. Name_Error is raised only if the file name is malformed and cannot
possibly identify a file. Of these operations, only the result of
Full_Name depends on the current default directory; the result of the
others depends only on their parameters.
["need" is replaced - Editor.]
Modify A.16(131/2):
NOTE 5 To move a file or directory to a different location, use
Rename. Most target systems will allow renaming of files from one
directory to another. If the target file or directory {can}[might]
already exist, {delete} it [should be deleted] first.
[Replace "might" and "should" - Editor.]
Modify A.16.1(37/2):
NOTE 1 These operations operate on file names, not external files.
The files identified by these operations do not {necessarily}[need to]
exist. Name_Error is raised only as specified or if the file name is
malformed and cannot possibly identify a file. The result of these
operations depends only on their parameters.
["need" is replaced - Editor.]
Modify A.18.3(164/2):
NOTE Sorting a list never copies elements, and is a stable sort
(equal elements remain in the original order). This is different than
sorting an array or vector, which {will often}[may need to] copy
elements, and {hence} is probably not a stable sort.
[Replace "May need" - Editor.]
Modify B.3.1(60):
* the allocated object {can}[should] be freed by the programmer via a call
of Free, {rather than by calling a}[not by a called] C function.
[Reword to eliminate "should". The rest of Note 1 is modified in AI12-0440-1.]
Modify part of B.4(112):
-- Assume that a COBOL program has created a sequential file with
-- the following record structure, and that we {want}[need] to
-- process the records in an Ada program
Modify C.3.1(23/2):
NOTE 2 {For a}[A] protected object that has a (protected) procedure
attached to an interrupt{, the correct}[ should have a] ceiling
priority {is }at least as high as the highest processor priority at which
that interrupt will ever be delivered.
[Reword to eliminate "should", usage recommendation (see 3.9 note) - Editor.]
Modify C.7.2(31):
NOTE 1 An attribute always exists (after instantiation), and has the
initial value. {An implementation can avoid using}[It need not occupy]
memory {to store the attribute value} until the first operation that
[potentially] changes the attribute value. The same holds true after
Reinitialize.
[Rewrite to replace "need not" - Editor.]
Modify C.7.2(32):
NOTE 2 The result of the Reference function [should be used with
care; it] is always safe to use [that result] in the task body whose
attribute is being accessed. However, when the result is being used by
another task, the programmer {will want to}[must] make sure that the task whose
attribute is being accessed is not yet terminated. Failing to do so
{can}[could] make the program execution erroneous.
[Rewrite to eliminate multiple banned phrases - Editor.]
Modify D.2.1(12):
NOTE 2 An example of a possible implementation-defined execution
resource is a page of physical memory, which {must}[needs to] be loaded
with a particular page of virtual memory before a task can continue
execution.
[Replace "needs". This is a proper use of "must" to represent an external
constraint (in this case, by the hardware). At least I hope so - Editor.]
Modify D.2.5(18/2):
NOTE 1 Due to implementation constraints, the quantum value returned
by Actual_Quantum {can differ from}[might not be identical to] that set
with Set_Quantum.
[Getting rid of the "not" helps us use "can" here - Editor.]
Modify D.3(21):
NOTE 4 When specifying the ceiling of a protected object, [one should
choose] a {correct }value that is {one that is }at least as high
as the highest active priority
at which tasks can be executing when they call protected operations of
that object. In determining this value the following factors, which
can affect active priority, {are relevant}[should be considered]:
the effect of Set_Priority, nested protected operations, entry calls,
task activation, and other implementation-defined factors.
[Reword to eliminate "should" - Editor.]
Modify D.5.1(19):
NOTE 5 Changing the priorities of a set of tasks can be performed by
a series of calls to Set_Priority for each task separately. {This can
be done}[For this to work] reliably[, it should be done] within a
protected operation that has high enough ceiling priority to guarantee
that the operation completes without being preempted by any of the
affected tasks.
[Reword to eliminate "should" - Editor.]
Modify E.4.2(12):
* The Tape_Client procedure references only declarations in the Tapes
and Name_Server packages. Before using a tape for the first time, it
{will}[needs to] query the Name_Server for a system-wide identity for that
tape. From then on, it can use that identity to access the tape device.
[Replace "needs" - Editor.]
Modify E.2.2(18):
NOTE 1 A remote types library unit {is not necessarily}[need not be]
pure, and the types it defines {can}[may] include levels of indirection
implemented by using access types. User-specified Read and Write
attributes (see 13.13.2) provide for sending values of such a type
between active partitions, with Write marshalling the representation,
and Read unmarshalling any levels of indirection.
[Replace "may", "need not" - Editor.]
Modify H.5(7/2):
NOTE An operation that causes a task to be blocked within a foreign
language domain is not defined to be potentially blocking, and {is
unlikely to}[need not] be detected.
[Replace "need not" - Editor.]
[The !appendix has several further occurrences of the unallowed words that we
are not proposing to change at this time, and why we think no change is
needed - Editor.]
!discussion
To summarize the ISO rules from the Directives part 2 (often referred to as the
drafting standard):
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).
Recommendations use "should" preferably, or phrases involving forms of
"recommend" or "ought to".
Permissions should use "may" preferably, or phrases using forms of permit or allow.
"Might" is not allowed in this context. Negative forms are not allowed (no
"may not"); permissions must be positive. A quote: "Rather than using negative
permissions, either rewrite the sentence to state what is permitted, or rewrite
as a requirement/recommendation not to do something."
Possibility should use "can", or phrases using forms of "able" or "possible".
ISO has taken this further and does not want to see "might", "could", or
"need" at all; they assume that they are being used in one of the above
contexts. Since that is not a rule but rather a recommendation, we can be
selective in applying it to non-normative things like notes.
Note that while some phrases are given meanings, other uses of the words seem
to be allowed by the Directives. For instance, "necessary" is used in many
contexts in the Directives that are not requirements.
The editor checked the Directives and examples have the same
limitations on wording as notes, so examples have been included here.
---
The editor has created a file that contains just the non-normative notes and
examples. In this file, we have the following number of occurrences:
shall 5
may 64
should 25
permit 10 (including two "permissible")
require 58
recommend 8
ought 0
possible 17 -- This is OK in notes.
must 7
might 27
could 10
need 41
----
The first 3 words were explicitly mentioned in the comments, so they HAVE to
be eliminated. The remaining words probably should be eliminated if possible.
There are nearly 100 paragraphs here that we have to fix, and another hundred
that should be looked at. There is not a one-size-fits all solution. Many of
the occurrences of "may" and "might" could be replaced by "can", but certainly
not all. (Those "easy" cases are found in AI12-0440-1.)
---
We have several options for dealing with these notes.
First, since these are notes and examples, we have the option of eliminating
them completely, either from the ISO version only, or from both versions (in
which case the note probably would be moved to the AARM). But we ought to do
that only in cases where a rewording is not valuable for one reason or another.
Second, 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).
Therefore, simply changing the text of the RM (and therefore of the ISO
standard) is preferred so long as we have a rewording that
does 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
****************************************************************
Notes that need changing:
[I ignored the use of "needs" (in the sense of
desired - that word with that meaning is used extensively in the Directives)
and uses of "need" as a technical term (although some of them are shown in
this list). Some of these still need a suggested fix. Items added since
the original Tucker review are marked "Post-Tuck review".
Replacement of a single word with "can" have been moved to AI12-0440-1 (59
notes); some previously reviewed changes have been moved above.]
3.2.4 Subtype Predicates
Part of the Examples:
Text_IO (see A.10.1) could have used predicates to describe some common
exceptional conditions as follows:
["could have". I can't find a rewording that makes sense. Possibly we could
leave this one, since we were not explicitly asked to change any examples,
and this is expressing a hypothetical alternative, not any of the things not
allowed. But that's iffy.]
3.5.1 Enumeration Types
Examples
Examples of enumeration types and subtypes:
type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun);
type Month_Name is (January, February, March, April, May, June, July,
August, September, October, November, December);
["May" should be OK here. I hope. :-)]
9.11 Example of Tasking and Synchronization
Examples
The following example defines a buffer protected object to smooth variations
between the speed of output of a producing task and the speed of input of some
consuming task. For instance, the producing task might have the following
structure:
...
and the consuming task might have the following structure:
["Might" (in each); but no obvious alternative exists and no one should
confuse this for any sort of requirement. So I say leave it (the directives
ban using "might" in a requirement, not banning the word altogether. The
"House Style" has a stronger statement, but that's only a guideline.)]
E.4.2 Example of Use of a Remote Access-to-Class-Wide Type
-- Tape_Driver is not needed and thus not mentioned in the with_clause
[This use of "needed" is a use of a technical term and should not be changed.]
****************************************************************
Questions? Ask the ACAA Technical Agent