!standard 3.2.1(6) 22-12-28 AI12-0449-1/03 !standard 3.2.1(9) !standard 3.3.1(6/3) !standard 3.3.2(4/3) !standard 3.5.2(9/3) !standard 3.5.5(15) !standard 3.6.2(17) !standard 3.7.1(14/3) !standard 3.11.1(10) !standard 4.5.10(21/5) !standard 4.6(57/4) !standard 4.7(4/4) !standard 5(2/3) !standard 5.1(1/5) !standard 5.2(14/3) !standard 5.2.1(5/5) !standard 5.5(8.1/5) !standard 5.6.1(5/5) !standard 6.1(10/3) !standard 6.5(22/5) !standard 7.3(9) !standard 9.7.1(20/3) !standard 9.8(24) !standard 10.2(33/5) !standard 12.3(28) !standard 13.10(4) !standard A.3.5(64/3) !standard A.7(13/2) !standard A.7(14/3) !standard A.8.2(1) !standard A.10(1/3) !standard A.10(2/3) !standard A.10.2(1) !standard A.10.6(11) !standard A.12.1(28/4) !standard A.18(6/4) !standard A.18(7/4) !standard B.1(47) !standard F(5/2) !standard M.1(2/2) !standard M.2(2/2) !class presentation 22-12-01 !status Amendment 1-2012 22-12-20 !status work item 22-12-01 !status received 22-11-04 !priority Low !difficulty Easy !subject Appearance of cross-references !summary Simplify cross-references that are redundant. Adopt a policy for cross-references in the RM so that we give them more consistently. !question The ISO editors have been applying a strict standard to cross-references in the text, not allowing some forms we have commonly used. At least some of the cross-references are redundant and could be simplified. Should this be done? (Yes.) !recommendation (See Summary.) !wording [Editor's note: The below changes are intended in the RM. Changes only for ISO versions are not mentioned here.] Modify 3.2.1(6): The defining_identifier of a type_declaration denotes the first subtype of the type. The known_discriminant_part, if any, defines the discriminants of the type (see 3.7[, "Discriminants"]). The remainder of the type_declaration defines the remaining characteristics of (the view of) the type. [Editor's note: Remove the title from the cross-reference. No one wil be surprised that discriminants are defined in a subclause named "Discriminants".] Modify 3.2.1(9): The definition of a type implicitly declares certain predefined operators that operate on the type, according to what classes the type belongs, as specified in 7.5[, "Operators and Expression Evaluation"]. [Editor's note: Remove the title from the cross-reference. No one wil be surprised that predefined operators are defined in a subclause named "Operators and something".] Modify 3.3.1(6/3): The rules for deferred constant declarations are given in [subclause ]7.4. The rules for full constant declarations are given in this subclause. Modify 3.3.2(4/3): The static_expression given for a number declaration shall be a static expression, as defined by [subclause ]4.9. [Editor's note: This one is on the cusp of needing a title, but the title would be very redundant. So I've left it out.] Modify 3.5.2(9/3): NOTE 2 A conventional character set such as EBCDIC can be declared as a character type; the internal codes of the characters can be specified by an enumeration_representation_clause as explained in [subclause ]13.4. Modify 3.5.5(15): -- For the types and subtypes declared in [subclause ]3.5.1 the following hold: Modify 3.6.2(17): Examples (using arrays declared in the examples of [subclause ]3.6.1): Modify 3.7.1(14/3): Examples (using types declared above in [subclause ]3.7): Modify 3.11.1(10): NOTE 2   There are rules that prevent premature uses of declarations that have a corresponding completion. The Elaboration_Checks of 6.11 prevent such uses at run time for subprograms, protected operations, tasks, and generic units. The {freezing }rules {(see }[of] 13.14{)}[, “Freezing Rules”] prevent, at compile time, premature uses of other entities such as private types and deferred constants. [Editor's note: We move the title into the text, eliminating the need for it.] Modify 4.5.10(21/5): ... with one logical thread of control (see {Clause}[clause] 9) associated with each subsequence. ... Modify 4.6(57/4): If an Accessibility_Check fails, Program_Error is raised. If a predicate check fails, the effect is as defined in [subclause ]3.2.4[, "Subtype Predicates"]. Any other check associated with a conversion raises Constraint_Error if it fails. [Editor's note: This is doubly redundant, and we recommend eliminating it all, just leaving the number. It's obviously a subclause, and it seems pretty obvious that a predicate check would be defined in a subclause named "predicates".] Modify 4.7(4/4): The evaluation of a qualified_expression evaluates the operand (and if of a universal type, converts it to the type determined by the subtype_mark) and checks that its value belongs to the subtype denoted by the subtype_mark. The exception Constraint_Error is raised if this check fails. Furthermore, if predicate checks are enabled for the subtype denoted by the subtype_mark, a check is performed as defined in [subclause ]3.2.4[, "Subtype Predicates"] that the value satifies the predicates of the subtype. Modify 5(2/3): This clause describes the general rules applicable to all statements. Some statements are discussed in later clauses: Procedure_call_statements and return statements are described in {Clause }6, “Subprograms”. Entry_call_statements, requeue_statements, delay_statements, accept_statements, select_statements, and abort_statements are described in {Clause} 9, "Tasks and Synchronization". Raise_statements are described in {Clause }11, "Exceptions", and code_statements in {Clause }13{, "Representation Issues"}. The remaining forms of statements are presented in this clause. [Editor's note: "Clause" is added as noted (this will happen via a tools change). The titles seem useful for many of these, so we leave them in the RM. However, Clause 13 is missing a title for some reason, and that looks really weird, so we add it in the RM.] Modify 5.1(1/5): ... A /parallel construct/ is a construct that introduces additional logical threads of control (see {Clause}[clause] 9) without creating a new task. Parallel loops (see 5.5) and parallel_block_statements (see 5.6.1) are parallel constructs. Modify 5.2(14/3): * If any part of the target is controlled, its value is adjusted as explained in [subclause ]7.6. Modify 5.2.1(5/5): For the execution of an assignment_statement with one or more target_names appearing in its expression, the variable_name V of the assignment_statement is evaluated first to determine the object denoted by V, and then the expression of the assignment_statement is evaluated with the evaluation of each target_name yielding a constant view of the [the ]target whose properties are otherwise identical to those of the view provided by V. The remainder of the execution of the assignment_statement is as given in [subclause ]8.2. [Editor's note: There is an extra "the" in the above which is also deleted.] Modify 5.5(8.1/5): ... each with its own separate logical thread of control (see {Clause}[clause] 9). ... Modify 5.6.1(5/5): ... each with its own separate logical thread of control (see {Clause}[clause] 9). ... Modify 6.1(10/3): The sequence of characters in an operator_symbol shall form a reserved word, a delimiter, or compound delimiter that corresponds to an operator belonging to one of the six categories of operators defined in [subclause ]4.5. Modify 6.5(22/5): A check is performed that the return value satisfies the predicates of the return subtype. If this check fails, the effect is as defined in [subclause ]3.2.4[, “Subtype Predicates”]. [Editor's note: See the note after 4.6(57/4) for why we remove everything extra.] Modify 7.3(9): If the declaration of a partial view includes a known_discriminant_part, then the full_type_declaration shall have a fully conforming (explicit) known_discriminant_part (see 6.3.1[, "Conformance Rules"]). The ancestor subtype may be unconstrained; the parent subtype of the full view is required to be constrained (see 3.7). [Editor's note: The definition of "conforming" probably would be found under "conformance", so the title doesn't add much; and the other cross-reference has no title, so we're inconsistent here.] Modify 9.7.1(20/3): An open terminate_alternative is selected if the conditions stated at the end of [subclause ]9.3 are satisfied. Modify 9.8(24): NOTE 3 Additional requirements associated with abort are given in D.6[, "Preemptive Abort"]. [Editor's note: The clause name doesn't add much here (abort requirements given in a clause named Something Abort, no one would think that. :-)] Modify 10.2(33/5): NOTE 3 An order of elaboration of library_items that is consistent with the partial ordering defined above does not always ensure that each library_unit_body is elaborated before any other compilation unit whose elaboration necessitates that the library_unit_body be already elaborated. (In particular, there is no requirement that the body of a library unit be elaborated as soon as possible after the library_unit_declaration is elaborated, unless the pragmas or aspects in [subclause ]10.2.1 are used.) Modify 12.3(28): T : Table(1 .. 5) := (10, 20, 30, 40, 50); N : Integer := Int_Vectors.Sigma(T); -- 150 -- (see 12.2[, "Generic Bodies"] for the body of Sigma) [Editor's note: The title doesn't add much here. We'd expect to find the body in a subclause about bodies.] Modify 13.10(4): NOTE 1 This attribute is provided to support the situation where a local object is to be inserted into a global linked data structure, when the programmer knows that it will always be removed from the data structure prior to exiting the object's scope. The Access attribute would be illegal in this case (see 3.10.2[, “Operations of Access Types”]). [Editor's note: The title here isn't adding much, we're already talking about access types. "Heart of Darkness" would be more helpful, but unofficial. :-)] Modify A.3.5(64/3): NOTE 2 The case insensitive equality comparison routines provided in A.4.10[, "String Comparison"] are also available for wide strings (see A.4.7). [Editor's note: The title is redundant, since one would expect to find string comparison routines in a subclause titled "String Comparision".] Modify A.7(13/2): Several file management operations are common to Sequential_IO, Direct_IO, Text_IO, Wide_Text_IO, and Wide_Wide_Text_IO. These operations are described in [subclause ]A.8.2 for sequential and direct files. Any additional effects concerning text input-output are described in [subclause ]A.10.2. Modify A.7(14/3): The exceptions that can be propagated by the execution of an input-output subprogram are defined in the package IO_Exceptions; the situations in which they can be propagated are described following the description of the subprogram (and in [subclause ]A.13). The exceptions Storage_Error and Program_Error may be propagated. (Program_Error can only be propagated due to errors made by the caller of the subprogram.) Finally, exceptions can be propagated in certain implementation-defined situations. Modify A.8.2(1): The procedures and functions described in this subclause provide for the control of external files; their declarations are repeated in each of the packages for sequential, direct, text, and stream input-output. For text input-output, the procedures Create, Open, and Reset have additional effects described in [subclause ]A.10.2. Modify A.10(1/3): This subclause describes the package Text_IO, which provides facilities for input and output in human-readable form. Each file is read or written sequentially, as a sequence of characters grouped into lines, and as a sequence of lines grouped into pages. The specification of the package is given below in [subclause ]A.10.1. Modify A.10(2/3): The facilities for file management given above, in [subclauses ]A.8.2 and A.8.3, are available for text input-output. In place of Read and Write, however, there are procedures Get and Put that input values of suitable types from text files, and output values to them. These values are provided to the Put procedures, and returned by the Get procedures, in a parameter Item. Several overloaded procedures of these names exist, for different types of Item. These Get procedures analyze the input sequences of characters based on lexical elements (see Clause 2) and return the corresponding values; the Put procedures output the given values as appropriate lexical elements. Procedures Get and Put are also available that input and output individual characters treated as character values rather than as lexical elements. Related to character input are procedures to look ahead at the next character without reading it, and to read a character “immediately” without waiting for an end-of-line to signal availability. Modify A.10.2(1): The only allowed file modes for text files are the modes In_File, Out_File, and Append_File. The subprograms given in [subclause ]A.8.2 for the control of external files, and the function End_Of_File given in [subclause ]A.8.3 for sequential input-output, are also available for text files. There is also a version of End_Of_File that refers to the current default input file. For text files, the procedures have the following additional effects: Modify A.10.6(11): In the examples, here and in [subclauses ]A.10.8 and A.10.9, the string quotes and the lower case letter b are not transferred: they are shown only to reveal the layout and spaces. Modify A.12.1(28/4): The subprograms given in [subclause ]A.8.2 for the control of external files (Create, Open, Close, Delete, Reset, Mode, Name, Form, and Is_Open, and Flush) are available for stream files. [Editor's note: This subclause has a number of other cross-references without the "subclause", not sure why this one is different.] Modify A.18(6/4): Certain subprograms declared within instances of some of the generic packages presented in this clause are said to perform indefinite insertion. These subprograms are those corresponding (in the sense of the copying described in [subclause ]12.3) to subprograms that have formal parameters of a generic formal indefinite type and that are identified as performing indefinite insertion in the subclause defining the generic package. Modify A.18(7/4): If a subprogram performs indefinite insertion, then certain run-time checks are performed as part of a call to the subprogram; if any of these checks fail, then the resulting exception is propagated to the caller and the container is not modified by the call. These checks are performed for each parameter corresponding (in the sense of the copying described in 12.3) to a parameter in the corresponding generic whose type is a generic formal indefinite type. The checks performed for a given parameter are those checks explicitly specified in [subclause ]4.8 that would be performed as part of the evaluation of an initialized allocator whose access type is declared immediately within the instance, where: [Editor's note: Again odd that one reference has "subclause" and the other does not.] Modify B.1(47): NOTE 4 {Machine code insertions can also be relevant for interfacing; see}[See also] 13.8[, "Machine Code Insertions"]. [Editor's note: We should explain why we're telling people to look somewhere else, not just assume the title is enough (especially as it is not included in ISO versions).] Modify F(5/2): {Other relevant facilities can be found in}[See also]: 3.5.9, “Fixed Point Types”; 3.5.10, “Operations of Fixed Point Types”; 4.6, “Type Conversions”; 13.3, “Operational and Representation Attributes”; A.10.9, “Input-Output for Real Types”; B.3, “Interfacing with C and C++”; B.4, “Interfacing with COBOL”; Annex G, “Numerics”. [Editor's note: Like B.1(47), this never explains why you might want to see any of these things. Ideally, we'd explain these in detail and not depend on the titles, but I don't have that much energy (and this is a rarely used Annex, so it's hard to justify the work).] Modify M.1(2/2): The behavior of implementations in implementation-defined situations shall be documented — see M.2[, “Implementation-Defined Characteristics”] for a listing. See 1.1.3(19). [Editor's note: The title doesn't add anything here. Note that this is defined in an AARM note given in 1.1.3.] Modify M.2(2/2): Whether or not each recommendation given in Implementation Advice is followed — see M.3[, “Implementation Advice”] for a listing. See 1.1.2(37). [Editor's note: The title doesn't add anything here. Note that this is defined in an AARM note given in 1.1.2.] No change to M.3(85/2): If an interface to C, COBOL, or Fortran is provided, the corresponding package or packages described in Annex B, “Interface to Other Languages” should also be provided. See B.2(13/3). [Editor's note: The title seems useful here. I've included this in the AI as it is defined in an AARM note given in B.2. Normally, we won't be putting any ISO-specific stuff into AARM notes, but in this (single) case we'll need to do that. So this serves as a reminder to make a change to that AARM note.] !discussion Cross-references in the RM (and thus the Standard) are not formatted consistently. Several different forms are used, and there doesn't seem to be any guidance to which form is appropriate. We've seen at least the following: ("nn" is a one or two digit number; "l" is a letter; "nn.nn" includes all of the subclause numbers with two or three numbers, and also those that start with a letter). Clause nn Annex l nn.nn nn l subclause nn.nn subclause nn.nn, "title" nn.nn, "title" nn, "title" l, "title" The JTC1 Directives, Part 2 only allow the first five forms (and the first two should capitalize "Clause" and "Annex"). The title of the subclause sometimes gives useful information. Therefore, we're recommending retaining it in the RM even while eliminating it from the FDIS, other than specific cases listed above. OTOH, we are recommending eliminating "subclause" from all wording, as it seems redundant in most cases, and in the few cases where it is not, including the title seems preferred. ----------- In order to improve the consistency of future cross-references, we recommend adopting drafting recommendations for cross-references. (This will be added to our existing drafting recommendation document.) We propose the following recommendation: Cross-references to other parts of the standard always should include the subclause number. (The @RefSecNum command should be used in the RM source). It should not include other information except as follows: [A] For a reference to an entire clause or annex, the number or latter should be prefixed by "Clause" or "Annex" (note: This should happen automatically as part of the @RefSecNum). The word "subclause" should NOT prefix the subclause number (it's mainly noise, everything is a subclause). [B] The command @RefSec includes the title of the annex, clause, or subclause along with the reference. This should only be used in three cases: [1] If the title of the subclause adds additional context to the cross-reference (such as the group of rules where an important rule is found). In particular, the title should not be given if the surrounding text includes the same information. [2] If the subclause number could be mistaken for a decimal number. That is never the case for parenthesized cross-references like "(see nn.nn)", and it rarely should be the case if the subclause number is prefixed with "in" (as in "given in nn.nn"). [3] If there are a number of cross-references in the same paragraph or adjacent paragraphs that include the title for reasons [1] or [2], then they all should (otherwise, the ones that do not have a title are jarring). Note that the Ada 2022 RM overuses titles in cross-references by these criteria; one should follow the above rules rather than existing practice when creating new cross-references. ----- [Editor's note to self: A new command @RefSecFullNum needs to be added in order to include "Clause" or "Annex" as needed ("Section" in order RMs). Occurrences of these in front of a @RefSecNum cross-ref should be deleted and the cross-ref changes to @RefSecFullNum. Do not use @Chg for this; any changes needed are implicit in the commands. Any occurrences of that term before a @RefSecNum or @RefSec needs to be deleted. There are four known ones in 4.5.10 (04A.MSS) as well as 5.1, 5.5, and 5.6.1 (05.MSS). Automatically generated cross-references in the annexes should use @RefSecFullNum (although many directly generate the references). For any @RefSec uses remaining in RM text after applying this AI, they need to be wrapped in an @ISODiff command of the form @ISODiff{ISOOnly=[@RefSecNum{title}],NotISO=[@RefSec{title}]} Only the references of 1.1.2 should not be changed that way. (And of course, AARM notes.)] !comment Only selected paragraphs are included below. !corrigendum 4.5.10(0) @dinsc See conflict file for details. !corrigendum 5.1(1/5) @drepl A @fa is either simple or compound. A @fa encloses no other @fa. A @fa can enclose @fas and other @fas. A @i is a construct that introduces additional logical threads of control (see clause 9) without creating a new task. Parallel loops (see 5.5) and @fas (see 5.6.1) are parallel constructs. @dby A @fa is either simple or compound. A @fa encloses no other @fa. A @fa can enclose @fas and other @fas. A @i is a construct that introduces additional logical threads of control (see Clause 9) without creating a new task. Parallel loops (see 5.5) and @fas (see 5.6.1) are parallel constructs. !corrigendum 5.2.1(0) @dinsc See conflict file for details. !corrigendum 5.5(8) @dinsa For the execution of a @fa with a @b @fa, the @fa is evaluated before each execution of the @fa; if the value of the @fa is True, the @fa is executed; if False, the execution of the @fa is complete. @dinst If the reserved word @b is present in the @fa of a @fa (a @i), the iterations are partitioned into one or more @i, each with its own separate logical thread of control (see Clause 9). If a @fa is present in a parallel loop, it is elaborated first, and the result of the elaboration determines the maximum number of chunks used for the parallel loop. If the @fa is an @i@fa, the elaboration evaluates the expression, and the value of the expression determines the maximum number of chunks. If a @fa is present, the elaboration elaborates the @fa, which defines the subtype of the chunk parameter, and the number of values in this subtype determines the maximum number of chunks. After elaborating the @fa, a check is made that the determined maximum number of chunks is greater than zero. If this check fails, Program_Error is raised. !corrigendum 5.6.1(0) @dinsc See conflict file for details. !corrigendum 6.5(22/5) @drepl A check is performed that the return value satisfies the predicates of the return subtype. If this check fails, the effect is as defined in subclause 3.2.4, "Subtype Predicates". @dby A check is performed that the return value satisfies the predicates of the return subtype. If this check fails, the effect is as defined in 3.2.4. !corrigendum 10.2(33/5) @drepl @xindent<@s9s that is consistent with the partial ordering defined above does not always ensure that each @fa is elaborated before any other compilation unit whose elaboration necessitates that the @fa be already elaborated. (In particular, there is no requirement that the body of a library unit be elaborated as soon as possible after the @fa is elaborated, unless the pragmas or aspects in subclause 10.2.1 are used.)>> @dby @xindent<@s9s that is consistent with the partial ordering defined above does not always ensure that each @fa is elaborated before any other compilation unit whose elaboration necessitates that the @fa be already elaborated. (In particular, there is no requirement that the body of a library unit be elaborated as soon as possible after the @fa is elaborated, unless the pragmas or aspects in 10.2.1 are used.)>> !ASIS No ASIS effect. !ACATS test This is only a presentation change, no tests are needed. !appendix ****************************************************************