Version 1.3 of ai12s/ai12-0449-1.txt
!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); --
--
[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)
Insert new clause:
See conflict file for details.
!corrigendum 5.1(1/5)
Replace the paragraph:
A statement is either simple or compound. A simple_statement
encloses no other statement. A compound_statement can enclose
simple_statements and other compound_statements.
A parallel construct is a construct that introduces additional
logical threads of control (see clause 9) without creating a new task.
Parallel loops (see 5.5) and parallel_block_statements (see
5.6.1) are parallel constructs.
by:
A statement is either simple or compound. A simple_statement
encloses no other statement. A compound_statement can enclose
simple_statements and other compound_statements.
A parallel construct is a construct that introduces additional
logical threads of control (see Clause 9) without creating a new task.
Parallel loops (see 5.5) and parallel_block_statements (see
5.6.1) are parallel constructs.
!corrigendum 5.2.1(0)
Insert new clause:
See conflict file for details.
!corrigendum 5.5(8)
Insert after the paragraph:
For the execution of a loop_statement with a while
iteration_scheme, the condition is evaluated before each execution
of the sequence_of_statements; if the value of the condition is True,
the sequence_of_statements is executed; if False, the execution of the
loop_statement is complete.
the new paragraph:
If the reserved word parallel is present in the iteration_scheme of
a loop_statement (a
parallel loop), the iterations are partitioned into one or more
chunks, each with its own separate logical thread of control (see
Clause 9). If a chunk_specification 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
chunk_specification is an integer_simple_expression, the
elaboration evaluates the expression, and the value of the expression
determines the maximum number of chunks. If a discrete_subtype_definition
is present, the elaboration elaborates the discrete_subtype_definition,
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 chunk_specification, 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)
Insert new clause:
See conflict file for details.
!corrigendum 6.5(22/5)
Replace the paragraph:
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".
by:
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)
Replace the paragraph:
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.)
by:
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
10.2.1 are used.)
!ASIS
No ASIS effect.
!ACATS test
This is only a presentation change, no tests are needed.
!appendix
****************************************************************
Questions? Ask the ACAA Technical Agent