!standard 3.4(34) 22-05-25 AI12-0442-1/03 !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(44/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 9.9(8) !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/5) !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) !standard M(1/3) !standard M.1(1/2) !standard M.2(1/2) !standard M.3(1/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 {can also 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 {can also 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" - Editor.] Modify 3.6.1(12): Board : Matrix(1 .. 8, 1 .. 8); -- see 3.6 Rectangle : Matrix(1 .. 20, 1 .. 30); Inverse : Matrix(1 .. N, 1 .. N); -- N {can be nonstatic}[need not be static] ["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}[might use] a hash table, trading off space for flexibility. [Replace "might" (twice) 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.9.4(33/2): An interface such as Queue can be used directly as the parent of a new type (as shown here), or can be used as a progenitor when a type is derived. In either case, the primitive operations of the interface are inherited. For Queue, the implementation of the four inherited routines {will be required to}[must] be provided. Inside the call of Transfer, calls will dispatch to the implementations of Append and Remove_First for type Fast_Food_Queue. 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 ... -- qualification {is necessary}[needed] for either Fix or Dec for J in Code range Fix .. Dec loop ... -- qualification unnecessary for J in Code'(Fix) .. Dec loop ... -- qualification unnecessary for Dec [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; -- See 3.3.2, 3.8. ... -- Square the element in the Count (see 3.3.1) position: My_Complex_Array (Count) := (Re => @.Re**2 - @.Im**2, Im => 2.0 * @.Re * @.Im); -- A target_name can be used multiple times and as a prefix if {desired}[needed]. [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(44/5): NOTE For an example of the use of these aspects[ and attributes], see the Vector container definition in A.18.2. 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 -- This calculation {is expected to}[should] finish in 5.0 seconds; -- if not, it is assumed to diverge. 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 9.9(8): NOTE 3 Within protected units, {by}[algorithms] interrogating the attribute E'Count in the entry_barrier for the entry E {an algorithm can}[should take precautions to] allow for the evaluation of the condition of the barrier both before and after queuing a given caller. [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/5): 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], {it is preferred that }the application [should use]{uses one of} the Random function{s} 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". This includes a usage recommendation, see the note at 3.9. See below for why we're deleting the "however" part. - Editor.] Delete A.5.2(51). Modify A.5.2(52): {AARM Reason: One might think that a simple transformation of the result of the floating point Random function such as Integer(Float(M) * Random(G)) mod M) would give a uniform distribution. But this is only true if the period of the underlying generator is a multiple of M. (This usually requires that M be a power of two.) In other cases, the mod operation maps slightly more random values to a some result values than others. It is easy to see this: consider a 4-bit random integer (with a range of 0 .. 15). If one mods this by 6 to get a value in 0 .. 5 (to which one would add 1 to get the value of a die roll), 3 values would be mapped to each value 0 .. 3, but only 2 values would be mapped to 4 and 5. Even when the input is uniformly distributed, the output clearly is not. A similar effect occurs regardless of the number of bits in the random integer. Since it takes care to get this right, users should use the provided functions (which presumably do this correctly - AI12-0144-1 contains a correct algorithm) and resist the urge to "roll-their-own".} {NOTE 4: }[transforms the result of Random(G) to an integer uniformly distributed over the range 0 .. M–1; it is valid even if Random delivers 0.0 or 1.0. Each value of the result range is possible, provided that M is not too large. ]Exponentially distributed (floating point) random numbers with mean and standard deviation 1.0 can be obtained by the transformation [We delete the text about tranforming the result of the float random to get uniformly distributed integers. There are two problems with this: * First, since AI12-0144-1 added a dedicated routine to handle the supposed "unusual requirement" as described here, it doesn't make sense to explain a different way to do that operation. * Second, the given transformation does not provide a uniformly distributed result unless M is a power of two (on a 2's complement machine). The result is close to uniformly distributed, but the difference can matter if enough random values are generated. (The new AARM note attempts to explain why.) The newly provided function presumably does give a true uniform distribution (assuming the underlying generator does) - AI12-0144-1 gives a correct algorithm used in an open source SSH implementation - so it is way better to use that. - 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 {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.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 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 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.] Modify M(1/3): The Ada language allows for certain target machine dependences in a controlled manner. Each Ada implementation {is required to}[must] document many characteristics and properties of the target system. This Reference Manual contains specific documentation requirements. In addition, many characteristics that require documentation are identified throughout this Reference Manual as being implementation defined. Finally, this Reference Manual requires documentation of whether implementation advice is followed. The following subclauses provide summaries of these documentation requirements. Modify M.1(1/2): In addition to implementation-defined characteristics, each Ada implementation {is required to}[must] document various properties of the implementation: Modify M.2(1/2): The Ada language allows for certain machine dependences in a controlled manner. Each Ada implementation {is required to}[must] document all implementation-defined characteristics: Modify M.3(1/2): This Reference Manual sometimes gives advice about handling certain target machine dependences. Each Ada implementation {is required to}[must] document whether that advice is followed: [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. !comment Only a few changes are defined with Corrigendum sections. !corrigendum 3.5.5(12) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum 3.5.9(22) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum 3.5.9(24) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum 3.9.4(26/2) @drepl This defines a Queue interface defining a queue of people. (A similar design 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 non-abstract extension of Queue must provide implementations for at least its four dispatching operations, as they are abstract. Any object of a type derived from Queue may be passed to Transfer as either the From or the To operand. The two operands need not be of the same type in any given call. @dby This defines a Queue interface defining a queue of people. (A similar design is possible 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 provide implementations for at least its four dispatching operations, as they are abstract. Any object of a type derived from Queue can be passed to Transfer as either the From or the To operand. The two operands can be of different types in a given call. !corrigendum 3.9.4(33/2) @drepl An interface such as Queue can be used directly as the parent of a new type (as shown here), or can be used as a progenitor when a type is derived. In either case, the primitive operations of the interface are inherited. For Queue, the implementation of the four inherited routines must be provided. Inside the call of Transfer, calls will dispatch to the implementations of Append and Remove_First for type Fast_Food_Queue. @dby An interface such as Queue can be used directly as the parent of a new type (as shown here), or can be used as a progenitor when a type is derived. In either case, the primitive operations of the interface are inherited. For Queue, the implementation of the four inherited routines will be required to be provided. Inside the call of Transfer, calls will dispatch to the implementations of Append and Remove_First for type Fast_Food_Queue. !corrigendum 4.3.5(0) @dinsc See the conflict file for the changes. !corrigendum 5.1(15) @dinsa The execution of a @fa consists of the execution of the individual @fas in succession until the @fa is completed. @dinss Within a parallel construct, if a transfer of control out of the construct is initiated by one of the logical threads of control, an attempt is made to @i all other logical threads of control initiated by the parallel construct. Once all other logical threads of control of the construct either complete or are canceled, the transfer of control occurs. If two or more logical threads of control of the same construct initiate such a transfer of control concurrently, one of them is chosen arbitrarily and the others are canceled. When a logical thread of control is canceled, the cancellation causes it to complete as though it had performed a transfer of control to the point where it would have finished its execution. Such a cancellation is deferred while the logical thread of control is executing within an abort-deferred operation (see 9.8), and may be deferred further, but not past a point where the logical thread initiates a new nested parallel construct or reaches an exception handler that is outside such an abort-deferred operation. @s8<@i> 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 proceed normally, or it can result in the indefinite blocking of some or all of the logical threads of control making up the current task. !corrigendum 5.2.1(0) @dinsc See the conflict file for the changes. !corrigendum 6.1.2(0) @dinsc See the conflict file for the changes. !corrigendum 9.1(21/2) @drepl @xindent<@s9s and predefined equality operators. If an application needs to store and exchange task identities, 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).>> @dby @xindent<@s9s and predefined equality operators. If a programmer wants to write an application that stores and exchanges task identities, they 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).>> !corrigendum 9.6.1(90/2) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum 9.9(7) @drepl @xindent<@s9s. Also, a @fa may briefly increase this value, even if the conditional call is not accepted.>> @dby @xindent<@s9s. A @fa can also briefly increase this value, even if the conditional call is not accepted.>> !corrigendum 9.9(8) @drepl @xindent<@s9 of the barrier both before and after queuing a given caller.>> @dby @xindent<@s9 of the barrier both before and after queuing a given caller.>> !corrigendum 10.1.1(27) @drepl @xindent<@s9 need not have any compilation units; for example, its text can consist of @fas.>> @dby @xindent<@s9 can have no compilation units; for example, its text can consist of @fas.>> !corrigendum 10.1.4(9) @drepl @xindent<@s9, which contains @fas. If multiple libraries are supported, the implementation has to define how a single environment is constructed when a compilation unit is submitted to the compiler. Naming conflicts between different libraries might be resolved by treating each library as the root of a hierarchy of child library units.>> @dby @xindent<@s9, which contains @fas. If multiple libraries are supported, the implementation can document how a single environment is constructed when a compilation unit is submitted to the compiler. Naming conflicts between different libraries can, for example, be resolved by treating each library as the root of a hierarchy of child library units.>> !corrigendum 10.2(34) @drepl @xindent<@s9s, and by tasks created by that elaboration. Passive partitions, which cannot have main subprograms, are defined in Annex E, "Distributed Systems".>> @dby @xindent<@s9s, and by tasks created by that elaboration. Passive partitions, which cannot have main subprograms, are defined in Annex E, "Distributed Systems".>> !corrigendum 11.5(29) @drepl @xindent<@s9 Suppress should be used only for efficiency reasons.>> @dby @xindent<@s9 Suppress is useful only to improve efficiency.>> !corrigendum 12.5.5(5/2) @dinsb @xcode<@b Root_Work_Item @b;> @dinst @i !corrigendum 12.6(11) @drepl @xindent<@s9s (see 8.5.4). In particular, the name of a parameter of the formal subprogram [need not be the same as that of the corresponding parameter of the actual subprogram; similarly, for these parameters, @fas need not correspond.>> @dby @xindent<@s9s (see 8.5.4). In particular, the name of a parameter of the formal subprogram can be different from that of the corresponding parameter of the actual subprogram; similarly, for these parameters, @fas can be different.>> !corrigendum 12.6(16.1/2) @drepl @xindent<@s9 is an abstract subprogram. All calls on a subprogram declared by a @fa must be dispatching calls. See 3.9.3.>> @dby @xindent<@s9 is an abstract subprogram. All calls on a subprogram declared by a @fa are limited to dispatching calls. See 3.9.3.>> !corrigendum 13.4(11/5) @drepl @xindent<@s9. For example, Pos always returns the position number, not the internal integer code that might have been specified in an @fa.>> @dby @xindent<@s9. For example, Pos always returns the position number, not {an}[the] internal integer code that {was}[might have been] specified in an @fa.>> !corrigendum 13.9.2(14/2) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum 13.11(26) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum 13.11.4(33/3) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum 13.11.4(35/3) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum 13.13.2(57) @drepl @xindent<@s9, only @i'Write and @i'Read are needed to pass an arbitrary value of the subtype through a stream. For an indefinite subtype S of a type @i, @i'Output and @i'Input will normally be needed, since @i'Write and @i'Read do not pass bounds, discriminants, or tags.>> @dby @xindent<@s9, only @i'Write and @i'Read are necessary to pass an arbitrary value of the subtype through a stream. For an indefinite subtype S of a type @i, @i'Output and @i'Input will normally be necessary, since @i'Write and @i'Read do not pass bounds, discriminants, or tags.>> !corrigendum A.4.3(107/3) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum A.5.2(50) @drepl @xindent<@s9= 1, the expression>> @dby @xindent<@s9> !corrigendum A.16(131/2) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum B.3.1(60) @drepl @xbullet @dby @xbullet !corrigendum D.2.5(18/2) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum D.3(21) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum D.5.1(19) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum E.2.2(18) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum H.5(7/2) @drepl @xindent<@s9> @dby @xindent<@s9> !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. :-)] 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.] **************************************************************** From: Randy Brukardt Sent: Friday, May 6, 2022 11:34 PM The following items have come up since our meeting yesterday, that either were not covered in the AIs or were changed from the AI version because of the "typo" comments. Given that time is short before the FDIS needs to be delivered, I will go ahead with these items unless someone makes an objection to one of them, in which case we'll discuss it here. I'm providing these so there are no surprises. [Just the cases that are relevant to this AI are shown here - Editor.] #3 Brad's comment on 9.1(21/2) [AI12-0442-1]: Brad wrote: "An application can't want things." The original fix was just to replace "needs" with "wants", but his point is reasonable (at least for Ada programs :-). So a more extensive fix is needed. Brad's actual suggestion changed from second person to third person in the middle, so I changed his suggestion to the below. I ended up using "they", since ISO doesn't allow gender-specific words or pronouns. "It" doesn't work as we're talking about a human now. 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). ---- #4 Jeff's comment on C.7.2(31) [Also AI12-0442-1] Jeff wrote: "!'m not sure what you're trying to say, I think either the "not" should stay or "until" should become "before", though the former seems more likely." The "not" can't stay, as that would still read like a negative permission (which is not allowed, at least not until the next edition of the Directives). I didn't think there was any simple fix that made any sense, so I ended up reordering the entire sentence. 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. I dropped "potentially" since this is a runtime action, and thus it would be possible for the implementation to notice the default value being assigned and continue to avoid materializing the attribute. It's already a "possibility" statement because of the "can", we don't have to repeat that. ****************************************************************