!standard 3.9(29) 22-12-16 AI12-0447-1/02 !standard 3.9.1(8) !standard 3.9.1(9) !standard 3.9.3(12) !standard 3.10.1(13) !standard 4.1.2(8) !standard 4.1.4(17/2) !standard 4.3.1(21) !standard 4.3.2(9) !standard 9.7.1(22) !standard 10.2.1(27) !standard 10.2.1(28) !standard 11.4.2(28/5) !standard 12.1(12) !standard 12.5.1(28) !standard 13.11.4(33/5) !standard A.5.2(50/5) !standard A.16(131/5) !standard C.3(29) !standard D.3(20) !standard D.5.1(18/3) !standard H.3.2(9/2) !standard H.3.2(11) !class presentation 22-11-30 !status Amendment 1-2012 22-12-14 !status ARG Approved 13-0-0 23-01-19 !status work item 15-06-04 !status received 15-04-28 !priority Low !difficulty Easy !subject More rewordings of notes !summary Reword some notes. !question The JTC1 Directives, Part 2, do not allow text that reads like a requirement or recommendation in Notes or Examples. !recommendation (See Summary.) !wording [Editor's note: The ISO editors flagged the phrases quoted at the start of the text in square brackets.] Modify 3.9(29): NOTE 3   Class-wide types are defined to have unknown discriminants (see 3.7). This means that{, by the rules in 3.7 for objects with unknown discriminants,} objects of a class-wide type {are illegal unless they are}[have to be] explicitly initialized (whether created by an object_declaration or an allocator), and that aggregates {are illegal unless they are}[have to be] explicitly qualified with a specific type when their expected type is class-wide. [“have to be”, twice. The fact that the language requires these (elsewhere) seems important, it’s not a statement of fact. We've already clearly marked that we are talking about a consequence and they still are not happy. Tucker suggests talking about "legal" and "illegal" instead, thus the rewording above.] Modify 3.9.1(8): NOTE 3   {By the rules given in 3.8, a}[A] name that denotes a component (including a discriminant) of the parent type is {illegal}[not allowed] within the record_extension_part. Similarly, a name that denotes a component defined within the record_extension_part is {illegal}[not allowed] within the record_extension_part. [It is permissible to use a]{A} name that denotes a discriminant of the record extension{ is legal}, providing {that it refers to a discriminant defined in}[there is] a new known_discriminant_part in the enclosing type declaration.[ (The full rule is given in 3.8.) ] [“It is permissible”. This isn’t talking about a permission anyway.] Modify 3.9.1(9): NOTE 4   {By the rules given in 8.3, each}[Each] visible component of a record extension {will}[has to] have a unique name, whether the component is (visibly) inherited from the parent type or declared in the record_extension_part[ (see 8.3)]. [“has to be”. The fact that the language requires this (elsewhere) seems important, it’s not a statement of fact.] Modify 3.9.3(12): NOTE 1   Abstractness is not inherited; {a type is abstract only if}[to declare an abstract type,] the reserved word abstract {is}[has to be] used in the declaration of the type extension. [“has to be”. The fact that this is necessary is the point, we need a substantial rewording.] Modify 3.10.1(13): NOTE 1   Within a declarative_part, an incomplete_type_declaration and a corresponding full_type_declaration cannot be separated by an intervening body. This is because{, by the rules given in 13.14,} a type {is illegal if it is not}[has to be] completely defined before it is frozen, and a body freezes all types declared prior to it in the same declarative_part[ (see 13.14)]. [“has to be”. The fact that the language requires this (elsewhere) seems important, it’s not a statement of fact.] Modify 4.1.2(8): NOTE 1   {By the rules given in 3.10.2, a}[A] slice is {illegal}[not permitted] as the prefix of an Access attribute_reference, even if the components or the array as a whole are aliased.[ See 3.10.2.] [“is not permitted”. We could have talked about impossibility, as in “cannot be used as the prefix”.] Modify 4.1.4(17/2): NOTE 2   {By the}[In] general{ rules given above}, {there is no expected type or profile for }the name in a prefix of an attribute_reference (or a range_attribute_reference){, which means that no context can be used to resolve the name}[ has to be resolved without using any context]. However, {by the rules given in 3.10.2 for}[in] the case of the Access attribute, the expected type for the attribute_reference {will}[has to] be a single access type, and the resolution of the name can {make use of the designated type or profile of this}[use the fact that the type of the object or the profile of the callable entity denoted by the prefix has to match the designated type or be type conformant with the designated profile of the] access type. [“has to be”, three times. Again, the fact that the language requires this seems important.] Modify 4.3.1(21): NOTE   {By the rules given above, for}[For] a record_aggregate with positional associations, expressions specifying discriminant values appear first {and in the same order as their corresponding discriminant_specifications, }since the known_discriminant_part {occurs}[is given] first in the declaration of the type[; they have to be in the same order as in the known_discriminant_part]. [“have to be”. This is clearly talking about a language requirement (given elsewhere).] Modify 4.3.2(9): NOTE 1   {By the rules given in 4.3.1, if}[If] all components of the value of the extension_aggregate are determined by the ancestor_part, then the record_component_association_list {will}[is required to] be simply null record. [“is required to be”; this is talking about a requirement imposed (on programmers) by rules in 7.3.1. Saying it is a “statement of fact” makes no sense; the programmer surely could write other things, they just wouldn’t be legal. Is "can only be null record" better than "will be simply null record"? **] Modify 9.7.1(22): NOTE   A selective_accept {can}[is allowed to] have several open delay_alternatives. A selective_accept {can}[is allowed to] have several open accept_alternatives for the same entry. [“is allowed to” (twice). “can” works here.] Modify 10.2.1(27): NOTE 1   A preelaborated library unit {can}[is allowed to] have nonpreelaborable children. [“is allowed to”. “can” works here.] Modify 10.2.1(28): NOTE 2   A library unit that is declared pure {can}[is allowed to] have impure children. [“is allowed to”. “can” works here.] Modify 11.4.2(28/5): NOTE Normally, the boolean expression in a pragma Assert {should}[does] 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. [This note was reworded into something that badly muddled the point. This is clearly a usage recommendation, and those cannot be notes (see !discussion for more on this point and how these are handled). This note will be omitted from the FDIS.] Modify 12.1(13): NOTE 3   A default_expression or default_name appearing in a generic_formal_part is not evaluated during elaboration of the generic_formal_part; instead, it is evaluated when used. {However, the}[(The] usual visibility rules apply to any name used in a default{, with name resolution performed based on the location of the name within the generic_formal_part.}[: the denoted declaration therefore has to be visible at the place of the expression.)] [“has to be”. As with 3.9.3, this is the point.] Modify 12.5.1(28): NOTE 2   If the formal has a discriminant_part, the actual can be either definite or indefinite. Otherwise, the actual {can only}[has to] be definite. [“has to be”.] Modify 13.11.4(33/5): 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 call Set_Pool_Of_Subpool before returning the subpool handle. To make use of such a pool, a user can declare an object of the type extension, {can }use it to define the Storage_Pool attribute of one or more access types, and then {can invoke}[call] Create_Subpool to obtain subpool handles associated with the pool. [“use it” was highlighted here, without comment. “can” applies to all of these here, maybe we have to be explicit as above.] Modify A.5.2(50/5): NOTE 3   A given implementation of the Random function in Numerics.Float_Random is not guaranteed to be capable of delivering the values 0.0 or 1.0. Applications will be more portable if they 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 range is necessary, [it is preferred that the application uses] {the application should use} one of the Random functions in an appropriate instantiation of Numerics.Discrete_Random, rather than transforming the result of the Random function in Numerics.Float_Random. ["it is preferred", with the following comment: "Preferred by whom? If this is a covert recommendation, please rephrase so it expresses a statement of fact." This is clearly a usage recommendation, and those cannot be notes (see !discussion for more on this point and how these are handled). This note will be omitted from the FDIS. We have partially reverted this wording to make the recommendation clear as there is no reason for it to be "covert". Note that the original wording also used "Portable applications should assume", but it not as clear that is an improvement over the rewording, so it was not changed.] Modify A.16(131/5): 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 already exist, {it should be deleted}[delete it] first. ["delete it first" was highlighted here, without comment. Not sure what the complaint is. However, this is clearly a usage recommendation, and indeed the original wording used "should" as given above, which we have reverted to. Usage recommendations cannot be notes (see !discussion for more on this point and how these are handled). This note will be omitted from the FDIS.] Modify C.3(29): NOTE 1   The default treatment for an interrupt can be to keep the interrupt pending or to deliver it to an implementation-defined handler. Examples of actions that an implementation-defined handler {can}[is allowed to] perform include aborting the partition, ignoring ({that is}[i.e.], discarding occurrences of) the interrupt, or queuing one or more occurrences of the interrupt for possible later delivery when a user-defined handler is attached to that interrupt. [“is allowed to”. See AI12-0453-1 for reasoning for "i.e." change.] Modify D.3(20): NOTE 3   {As described in C.3.1, a check is made whenever an interrupt is handled by one of the protected procedures of a protected object that its}[The] ceiling priority {is}[of a protected object has to be] in the Interrupt_Priority range[ if one of its procedures is to be used as an interrupt handler (see C.3)]. [“has to be”.] Modify D.5.1(18/3): NOTE 4   The rule for when Tasking_Error is raised for Set_Priority or Get_Priority is different from the rule for when Tasking_Error is raised on an entry call (see 9.5.3). In particular, [querying ]the priority of a completed or an abnormal task {can be queried}[is allowed,] so long as the task is not yet terminated, and [setting ]the priority of a task {can be set in}[is allowed for] any task state (including for terminated tasks). [“is allowed” (twice).] Modify H.3.2(9/2): NOTE 1   {Because reaching an inspection point is considered an external interaction relative to the values of the inspectable variables, the}[The] implementation {cannot}[is not allowed to] perform “dead store elimination” on the last assignment to {such }a variable prior to {an inspection point}[a point where the variable is inspectable]. Thus an inspection point has the effect of an implicit read of each of its inspectable objects. [“is not allowed”.] Modify H.3.2(11): NOTE 3   The identification of the mapping from source program objects to machine resources {can}[is allowed to] be in the form of an annotated object listing, in human-readable or tool-processable form. [“is allowed to be”.] !discussion The ISO editors flagged all of these phrases. The ISO editors did not flag text that talks about rules given elsewhere. We should be allowed to say something like "The rules of this subclause require" or "The rules of 7.8 prevent" (although we should try to avoid words like require when possible). Most of these notes do not make sense as simple statements of fact, since the point is that we (in this document) are requiring these facts. Otherwise, they would appear mysterious. ---- Some notes that the ISO editor's flagged defied useful rewording and do not appear in this AI. Instead, they have been removed from the FDIS. Many of these are usage recommendations. That is, they tell Ada users something that they "should" do. Recommendations are explicitly banned from notes. Moreover, we tried some rewording as "almost recommendations" in an earlier ISO update, but ISO complained about "covert recommendations" in their most recent comments. Therefore, additional attempts at rewording are likely to be futile. The best solution would be to create a new category, possibly "Usage Advice", and move all of these notes to that category. However, that requires care as the new wording would be normative (if unenforceable) so each note would have to be carefully examined for sloppy wording and minor untruths. Additionally, simply moving the notes that ISO flagged would potentially leave behind some additional notes that would fit well into the category. After all, all discussion aimed at Ada users has been jammed into notes in the RM, so there are many such notes. Deciding exactly which notes should be included in the new category (and the name for the category) is likely to take some time and discussion, so it is inappropriate at this point in the development of Ada 2022. We have gathered all of the currently known notes into a future Ada 2022 AI, and should plan to address this in a future Ada standard. Therefore, all of the "Usage Advice" notes will be left out of the FDIS (but will continue to appear in the RM as they currently are written). There are a few notes in this category that do appear in this AI. These notes are ones that we previously tried (and failed) to reword to ISO's satisfaction. We are recommending to revert/modify some of that previous rewording to make the meaning clearer; in particular, using "should" where that best carries the meaning. There is no reason to make the notes in the RM hard to understand because of failed updates. !corrigendum 3.9(29) @drepl @xindent<@s9 or an @fa), and that @fas have to be explicitly qualified with a specific type when their expected type is class-wide.>> @dby @xindent<@s9 or an @fa), and that @fas are illegal unless they are explicitly qualified with a specific type when their expected type is class-wide.>> !corrigendum 3.9.1(8) @drepl @xindent<@s9 that denotes a component (including a discriminant) of the parent type is not allowed within the @fa. Similarly, a @fa that denotes a component defined within the @fa is not allowed within the @fa. It is permissible to use a @fa that denotes a discriminant of the record extension, providing there is a new @fa in the enclosing type declaration. (The full rule is given in 3.8.)>> @dby @xindent<@s9 that denotes a component (including a discriminant) of the parent type is illegal within the @fa. Similarly, a @fa that denotes a component defined within the @fa is illegal within the @fa. A @fa that denotes a discriminant of the record extension is legal, providing that it refers to a discriminant defined in a new @fa in the enclosing type declaration.>> !corrigendum 3.9.1(9) @drepl @xindent<@s9 (see 8.3).>> @dby @xindent<@s9.>> !corrigendum 3.9.3(12) @drepl @xindent<@s9 has to be used in the declaration of the type extension.>> @dby @xindent<@s9 is used in the declaration of the type extension.>> !corrigendum 3.10.1(13) @drepl @xindent<@s9, an @fa and a corresponding @fa cannot be separated by an intervening body. This is because a type has to be completely defined before it is frozen, and a body freezes all types declared prior to it in the same @fa (see 13.14).>> @dby @xindent<@s9, an @fa and a corresponding @fa cannot be separated by an intervening body. This is because, by the rules given in 13.14, a type is illegal if it is not completely defined before it is frozen, and a body freezes all types declared prior to it in the same @fa.>> !corrigendum 4.1.2(8) @drepl @xindent<@s9 is not permitted as the @fa of an Access @fa, even if the components or the array as a whole are aliased.[ See 3.10.2.]>> @dby @xindent<@s9 is illegal as the @fa of an Access @fa, even if the components or the array as a whole are aliased.>> !corrigendum 4.1.4(17/2) @drepl @xindent<@s9 in a @fa of an @fa (or a @fa) has to be resolved without using any context. However, in the case of the Access attribute, the expected type for the @fa has to be a single access type, and the resolution of the @fa can use the fact that the type of the object or the profile of the callable entity denoted by the @fa has to match the designated type or be type conformant with the designated profile of the access type.>> @dby @xindent<@s9 in a @fa of an @fa (or a @fa), which means that no context can be used to resolve the @fa. However, by the rules given in 3.10.2 for the case of the Access attribute, the expected type for the @fa will be a single access type, and the resolution of the @fa can make use of the designated type or profile of this access type.>> !corrigendum 4.3.1(21) @drepl @xindent<@s9 with positional associations, expressions specifying discriminant values appear first since the @fa is given first in the declaration of the type; they have to be in the same order as in the @fa.>> @dby @xindent<@s9 with positional associations, expressions specifying discriminant values appear first and in the same order as their corresponding @fas, since the @fa occurs first in the declaration of the type.>> !corrigendum 4.3.2(9) @drepl @xindent<@s9 are determined by the @fa, then the @fa is required to be simply @b.>> @dby @xindent<@s9 are determined by the @fa, then the @fa will be simply @b.>> !corrigendum 9.7.1(22) @drepl @xindent<@s9 is allowed to have several open @fas. A @fa is allowed to have several open @fas for the same entry.>> @dby @xindent<@s9 can have several open @fas. A @fa can have several open @fas for the same entry.>> !corrigendum 10.2.1(27) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum 10.2.1(28) @drepl @xindent<@s9> @dby @xindent<@s9> !comment 11.4.2(28/5) ultimately is unchanged (the change given here is a !comment complete reversion, so it does not need to appear here. !corrigendum 12.1(13) @drepl @xindent<@s9 or @fa appearing in a @fa is not evaluated during elaboration of the @fa; instead, it is evaluated when used. (The usual visibility rules apply to any @fa used in a default: the denoted declaration therefore has to be visible at the place of the expression.)>> @dby @xindent<@s9 or @fa appearing in a @fa is not evaluated during elaboration of the @fa; instead, it is evaluated when used. However, the usual visibility rules apply to any @fa used in a default, with name resolution performed based on the location of the @fa within the @fa.>> !corrigendum 12.5.1(28) @drepl @xindent<@s9, the actual can be either definite or indefinite. Otherwise, the actual has to be definite.>> @dby @xindent<@s9, the actual can be either definite or indefinite. Otherwise, the actual can only be definite.>> !corrigendum 13.11.4(33/3) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum A.5.2(50/5) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum A.16(131/5) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum C.3(29) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum D.3(20) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum D.5.1(18/3) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum H.3.2(9/2) @drepl @xindent<@s9> @dby @xindent<@s9> !corrigendum H.3.2(11) @drepl @xindent<@s9> @dby @xindent<@s9> !ASIS No ASIS effect. !ACATS test These are just notes, no tests are needed. !appendix ****************************************************************