!standard  5.5(9)                               11-08-03    AI05-0262-1/02
!standard  6.1.1(0)
!standard 13.11(21)
!class presentation 11-07-27
!status Amendment 2012 11-07-27
!status work item 11-07-27
!status received 11-07-21
!priority Medium
!difficulty Easy
!subject Rewordings from the Second Editorial Review
!summary


Change wording of existing approved AIs as suggested by various
ARG members and the public during the second editorial review of the draft
standard.

!question

Some of the new wording in the standard is unnecessarily confusing.
Should we improve it? (Yes.)

!recommendation
(See Summary.)

!wording

[Note: /3 paragraph numbers are from draft 13.]

Add after 5.5(9):

Redundant[For details about the execution of a loop_statement with the
iteration_scheme being for iterator_specification, see 5.5.2.]

Modify 6.1.1(3/3):

This aspect specifies a class-wide precondition for {an operation of a tagged type}[a
callable entity] and its descendants; ...

Modify 6.1.1(5/3):

This aspect specifies a class-wide postcondition for {an operation of a tagged type}[a
callable entity] and its descendants; ...


Modify the start of 13.11(21.5/3):

For [one]{each} of the calls of Allocate described above, P
(equivalent to T'Storage_Pool) is passed as the Pool parameter. ...

!discussion

These wording changes seem to be an improvement in readability and
understandability, but are not intended to change the meaning of the words,
except in the case of clear mistakes. The latter are listed below:

6.1.1(3/3, 5/3): the term "descendant" is not defined for subprograms, so the original
wording is dubious. The formal definition in 6.1.1(18/3) is correct, but too wordy to use
in this introductory text.


!corrigendum 5.5(9)

@dinsa
For the execution of a @fa<loop_statement> with a @b<for> @fa<iteration_scheme>,
the @fa<loop_parameter_specification> is first elaborated. This
elaboration creates the loop parameter and elaborates the
@fa<discrete_subtype_definition>.
If the @fa<discrete_subtype_definition> defines a subtype with a null range,
the execution of the @fa<loop_statement> is complete. Otherwise, the
@fa<sequence_of_statements> is executed once for each value of the
discrete subtype defined by the @fa<discrete_subtype_definition> (or until
the loop is left as a consequence of a transfer of control).
Prior to each such iteration,
the corresponding value of the discrete subtype is assigned to the
loop parameter. These values are assigned in increasing order unless
the reserved word @b<reverse> is present, in which case the values
are assigned in decreasing order.
@dinst
For details about the execution of a @fa<loop_statement> with the
@fa<iteration_scheme> being @b<for> @fa<iterator_specification>, see 5.5.2.

!corrigendum 6.1.1(0)

@dinsc

Force a conflict; the real text is found in the conflict file.

!corrigendum 13.11(21)

@dinsa
If Storage_Pool is specified for an access type, then if Allocate can satisfy
the request, it should allocate a contiguous block of memory, and return the
address of the first storage element in Storage_Address. The block should
contain Size_In_Storage_Elements storage elements, and should be aligned
according to Alignment. The allocated storage should not be used for any other
purpose while the pool element remains in existence. If the request cannot be
satisfied, then Allocate should propagate an exception (such as Storage_Error).
If Allocate behaves in any other manner, then the program execution is
erroneous.
@dinst
For each of the calls of Allocate described above, @i<P> (equivalent to
@i<T>'Storage_Pool) is passed as the Pool parameter. The
Size_In_Storage_Elements parameter indicates the number of storage elements to
be allocated, and is no more than @i<D>'Max_Size_In_Storage_Elements, where
@i<D> is the designated subtype of @i<T>. The Alignment parameter is at least
@i<D>'Alignment if @i<D> is a specific type, and otherwise is at least the
alignment of the specific type identified by the tag of the object being
created. The Alignment parameter is no more than
@i<D>'Max_Alignment_For_Allocation. The result returned in the Storage_Address
parameter is used as the address of the allocated storage, which is a contiguous
block of memory of Size_In_Storage_Elements storage elements. Any exception
propagated by Allocate is propagated by the construct that contained the call.

!ACATS Test

None needed.

!ASIS

No change needed.

!appendix

From: Randy Brukardt
Sent: Monday, July 18, 2011  10:23 PM

Question of very low importance:

Grein, Christoph wrote:
...
> 5.5 seems incomplete.
> 5.5(7) says: "The loop_statement is complete when a transfer of
> control occurs that transfers control out of the loop, or, in the case
> of an iteration_scheme, as specified below."
> But there is nothing said about iterator_specification.
> Perhaps a reference to 5.5.2 should be added.

"iteration_scheme" clearly includes "iterator_specification", so there is
nothing missing in 5.5(7). The "completion" conditions for iterator
specifications are specified in 5.5.2(10/3, 11/3, and 13/3), so these are in
fact defined. "below" in technical writing generally means "anywhere after this
point in the text" (it is not restricted to the same subclause), and 5.5.2
surely follows 5.5, and even is part of the same clause (all being parts of
5.5), so there is nothing actually wrong here.

However, that is the pedantic answer. It probably wouldn't hurt to put a
cross-reference into the text somewhere. The best way to do that is less than
obvious, however.

We could stick something on the end of 5.5(7):

"The loop_statement is complete when a transfer of control occurs that transfers
control out of the loop, or, in the case of an iteration_scheme, as specified
below. (For iterator_specifications, see 5.5.2.)"

But that doesn't read well, because it seems to contradict "below". (Also see
the next item.)

An alternative is to put the text as a redundant paragraph following 5.5(9):

Redundant[For the details of iterator_specifications, see 5.5.2.]

That reads better, but it is common that part of the semantics of something is
in another clause in the Standard. So it's a bit weird to say this explicitly
here.

Finally, we could just make it an AARM note as above:

Discussion: For the details of iterator_specifications, see 5.5.2.

Any thoughts??

****************************************************************

From: Christoph Grein
Sent: Tuesday, July 19, 2011  1:37 AM

I tend to this solution:

> Redundant[For the details of iterator_specifications, see 5.5.2.]
>
> That reads better, but it is common that part of the semantics of
> something is in another clause in the Standard. So it's a bit weird to
> say this explicitly here.
> ...
> Any thoughts??

This provides the most information for the (non-language-lawyer) reader at the
correct place. After all, the RM is already hard enough to read.

****************************************************************

From: Christoph Grein
Sent: Thursday, July 21, 2011  2:04 AM

13.11(21.5/3) For [one]{each} of the calls of Allocate described above, P
(equivalent to T'Storage_Pool) is passed as the Pool parameter.

I think *one* is confusing here - it makes the reader wonder what about
the others. I think it should say *each* instead - or am I missing something?

****************************************************************

!topic Possible incorrect terminology in 6.1.1
!reference 6.1.1(3/3, 5/3), AARM 6.1.1(22.a/3)
!from Adam Beneschan 11-07-28
!discussion

6.1.1(3/3) says about Pre'Class, "This aspect specifies a class-wide
precondition for a callable entity and its descendants".  However,
nowhere in the RM is a "descendant" of a callable entity defined.
"Descendants" are defined for types, library units, and nodes in
Containers.Multiway_Trees, but not for subprograms.  Also, aside from
paragraphs 3 and 5, and possibly 22.a in the AARM, the term
"descendant" is never used to refer to anything besides a type,
library unit, or Multiway_Trees node.  Since paragraph 14 explains
just what the semantics are, I don't think the meaning of the RM is
unclear; but since paragraphs 3 and 5 are in a normative part of the
RM, the language they use should probably be correct.  

Side note: The glossary (appendix N) contains a definition of
"descendant", but that definition covers only the meaning that applies
to types, not the one that applies to library units.  I'm not sure if
this is a problem.

****************************************************************

From: Randy Brukardt
Sent: Saturday, July 30, 2011  1:21 AM

> 6.1.1(3/3) says about Pre'Class, "This aspect specifies a class-wide 
> precondition for a callable entity and its descendants".  However, 
> nowhere in the RM is a "descendant"
> of a callable entity defined.
> "Descendants" are defined for types, library units, and nodes in 
> Containers.Multiway_Trees, but not for subprograms.  Also, aside from 
> paragraphs 3 and 5, and possibly 22.a in the AARM, the term 
> "descendant" is never used to refer to anything besides a type, 
> library unit, or Multiway_Trees node.  Since paragraph 14 explains 
> just what the semantics are, I don't think the meaning of the RM is 
> unclear; but since paragraphs
> 3 and 5 are in a normative part of the RM, the language they use 
> should probably be correct.

Actually, the normative description of class-wide aspects applied to subprograms
(no entries can be primitive operations of a tagged type) is in
13.3.1(28/3) [this paragraph number may have changed since draft 12]:

If the aspect_mark includes 'Class, then:
...
if the associated entity is a primitive subprogram of a tagged type T, the
specification applies to the corresponding primitive subprogram of all descendants
of T.

The wording in 6.1.1(3/3) and 6.1.1(5/3) is intended to be a more informal
description. And I wouldn't call it "incorrect" (since the semantics are defined
formally elsewhere), just "undefined".

But I do agree that it is somewhat uncomfortable to have undefined terminology in
the normative wording, especially as it is the first description of the aspects.
Repeating 6.1.1(18/3) [probably was 14/3 in draft 12, but 6.1.1 was changed a lot
in Edinburgh] isn't helpful and would potentially cause a maintenance problem.

So I have no better idea than the current wording.

****************************************************************

From: Tucker Taft
Sent: Tuesday, August 2, 2011  11:16 AM

How about:

3/3
Pre'Class
This aspect specifies a class-wide precondition for an operation of a tagged
type and its descendants; ...

5/3
Post'Class
This aspect specifies a class-wide postcondition for an operation of a tagged
type and its descendants; ...

****************************************************************