Version 1.3 of ai12s/ai12-0429-1.txt

Unformatted version of ai12s/ai12-0429-1.txt version 1.3
Other versions for file ai12s/ai12-0429-1.txt

!standard 3.2.4(39/4)          21-06-07 AI12-0429-1/02
!standard 4.1.5(9/3)
!standard 4.1.6(19/3)
!standard 4.2.1(18/5)
!standard 4.3.4(22/5)
!standard 4.3.4(25/5)
!standard 4.3.4(29/5)
!standard 4.3.5(54/5)
!standard 4.3.5(67/5)
!standard 4.5.7(22/5)
!standard 4.5.7(23/5)
!standard 4.5.8(10/3)
!standard 4.5.8(12/3)
!standard 4.5.9(11/5)
!standard 4.5.10(35/5)
!standard 4.5.10(37/5)
!standard 4.5.10(39/5)
!standard 4.5.10(41/5)
!standard 4.5.10(43/5)
!standard 4.5.10(45/5)
!standard 4.5.10(47/5)
!standard 4.5.10(49/5)
!standard 5.2.1(6/5)
!standard 5.5.2(15/5)
!standard 5.5.2(16/3)
!standard 5.5.3(30/5)
!standard 5.5.3(34/5)
!standard 5.6.1(4/5)
!standard 5.6.1(5/5)
!standard 6.5.1(10/3)
!standard 6.7(6/2)
!standard 6.8(9/3)
!standard 7.3.2(25/5)
!standard 8.3.1(9/2)
!standard 8.3.1(16/2)
!standard 10.1.2(24/2)
!standard 10.1.2(31/2)
!standard 12.5.5(5/2)
!standard 12.5.5(7/2)
!standard A.4.2(67)
!standard A.10.8(26/3)
!standard A.10.9(40/1)
!standard F.3.2(71)
!class presentation
!status Amendment 1-2012 21-06-07
!status ARG Approved 13-0-2 21-06-03
!status work item 21-03-23
!status received 21-03-23
!priority Medium
!difficulty Medium
!subject Examples should have consistent lead-ins
!summary
Add, modify, and/or italicize the lead-ins to examples so that they are consistent in content and appearance.
!question
For essentially all features from Ada 95 and Ada 2005, if there is an "Examples" section there are one or more lead-ins that introduce each set of examples. This practice seems to have disappeared for newer features. It makes for an inconsistent treatment of examples. Should we add "lead-ins" where they are missing, and adjust for consistency of content and appearance? (Yes).
!recommendation
Adjust the "lead-ins" to various examples, and add those that are missing, so the content and appearance of the examples are consistent.
!wording
NOTE: We use /..../ to indicate the enclosed words are to be in italics.
Insert before paragraph 3.2.4(39/4):
/Examples of predicates applied to scalar types:/
4.1.5 User-Defined References
Insert before paragraph 4.1.5(9/3):
/Examples of the specification and use of generalized references:/
4.1.6 User-Defined Indexing Insert before paragraph 4.1.6(19/3):
/Examples of the specification and use of generalized indexing:/
4.2.1 User-Defined Literals Insert before paragraph 4.2.1(18/5):
/Examples of the specification and use of user-defined literals:/
4.3.4 Delta Aggregates Modify 4.3.4(22/5):
[Simple]/{Examples of} use {of delta aggregates} in a postcondition:/
Modify 4.3.4(25/5)
/{Examples where t}[T]he base expression [can be]{is} nontrivial:/
Modify 4.3.4(29/5)
/{Examples where t}[T]he base expression [may also be]{is} class-wide:/
4.3.5 Container Aggregates
Modify 4.3.5(54/5)
[Declarations of]/{Examples of specifying the Aggregate aspect for a} Set_Type, {a} Map_Type, and {a} Vector_Type:/
Modify 4.3.5(67/5) -- italicizing is the only change:
/Examples of container aggregates for Set_Type, Map_Type, and Vector_Type:/
4.5.7 Conditional Expressions Insert before paragraph 4.5.7(22/5):
/Example of use of an if_expression:/
Insert before paragraph 4.5.7(23/5):
/Example of use of a case_expression:/
4.5.8 Quantified Expressions
Modify 4.5.8(10/3):
[The]/{Example of a quantified expression as a} postcondition for a sorting routine on an array A with an index subtype T[ can be written]:/
Modify 4.5.8(12/3):
[The]/{Example of use of a quantified expression as an} assertion that a positive number is composite (as opposed to prime)[ can be written]:/
4.5.9 Declare Expressions
Modify 4.5.9(11/5):
[The]/{Example of use of a declare expression as a replacement} postcondition for Ada.Containers.Vectors."&" (see A.18.2)[ could have been written]:/
4.5.10 Reduction Expressions
Modify 4.5.10(35/5):
/{Example of a}[A]n expression function that returns its result as a [R]{r}eduction [E]{e}xpression:/
Modify 4.5.10(37/5)
/[An] {Example of a reduction} expression [function] that computes the Sine of X using a Taylor expansion:/
Modify 4.5.10(39/5)
/[A]{Example of a} reduction expression that outputs the sum of squares:/
Modify 4.5.10(41/5)
/[An] {Example of a reduction} expression [function]{used} to compute the value of Pi:/
Modify 4.5.10(43/5)
/{Example of a reduction expression used to c}[C]alculate the sum of elements of an array of integers:/
Modify 4.5.10(45/5)
/{Example of a reduction expression used to d}[D]etermine if all elements in a two-dimensional array of booleans are set to true:/
Modify 4.5.10(47/5)
/{Example of a reduction expression used to c}[C]alculate the minimum value of an array of integers in parallel:/
Modify 4.5.10(49/5)
/[A]{Example of a} parallel reduction expression used to calculate the mean of the elements of a two-dimensional array of subtype Matrix (see 3.6) that are greater than 100.0:/
5.2.1 Target Name Symbols
Insert before paragraph 5.2.1(6/5):
/Examples of the use of target name symbols:/
5.5.2 Generalized Loop Iteration
Insert before paragraph 5.5.2(15/5):
/Example of a parallel generalized loop over an array:/
Modify 5.5.2(16/3) -- only change is to italicize:
/For examples of use of generalized iterators, see A.18.33 and the corresponding container packages in A.18.2 and A.18.3./
5.5.3 Procedural Iterators
Modify 5.5.3(30/5) -- only change is to italicize:
/Example of iterating over a map from My_Key_Type to My_Element_Type (see A.18.4):/
Modify 5.5.3(34/5) -- only change is to italicize:
/Example of iterating over the environment variables (see A.17):/
5.6.1 Parallel Block Statements
Insert before paragraph 5.6.1(4/5):
/Example of a parallel block used to walk a binary tree in parallel:/
Insert before paragraph 5.6.1(5/5):
/Example of a parallel block used to search two halves of a string in parallel:/
6.5.1 Nonreturning Subprograms
Insert before paragraph 6.5.1(10/3):
/Example of a specification of a No_Return aspect:/
6.7 Null Procedures
Insert before paragraph 6.7(6/2):
/Example of the declaration of a null procedure:/
6.8 Expression Functions
Insert before paragraph 6.8(9/3):
/Example of an expression function:/
7.3.2 Type Invariants
Modify 7.3.2(25/5)
[A]/{Example of a} work scheduler where only urgent work can be scheduled for weekends:/
8.3.1 Overriding Indicators
Modify 8.3.1(9/2)
[The use of overriding_indicators allows the detection of errors at compile-time that otherwise might not be detected at all. For instance, we might declare]/{Example of use of an overriding indicator when declaring} a security queue derived from the Queue interface of 3.9.4[ as]:/
Modify 8.3.1(16/2) -- Italicize the following (and make one addition):
/The first four subprogram declarations guarantee that these subprograms will override the four subprograms inherited from the Queue interface. A misspelling in one of these subprograms will be detected {at compile time} by the implementation. Conversely, the declaration of Arrest guarantees that this is a new operation./
10.1.2 Context Clauses - With Clauses
Insert before paragraph 10.1.2(24/2):
/Examples of use of with clauses, limited with clauses, and private with clauses:/
Modify 10.2.1(31/2) -- Italicize the following:
/The limited_with_clause may be used to support mutually dependent abstractions that are split across multiple packages. In this case, an employee is assigned to a department, and a department has a manager who is an employee. If a with_clause with the reserved word private appears on one library unit and mentions a second library unit, it provides visibility to the second library unit, but restricts that visibility to the private part and body of the first unit. The compiler checks that no use is made of the second unit in the visible part of the first unit./
10.1.3 Subunits of Compilation Units
Modify 10.1.3(19)
/{Example that defines} [The] package Parent [is first written] without subunits:/
Modify 10.1.3(22)
/{Example showing how t}[T]he body of procedure Inner may be turned into a subunit by rewriting the package body as follows (with the declaration of Parent remaining the same):/
12.5.5 Formal Interface Types
Insert before paragraph 12.5.5(5/2):
/Example of the use of a generic with a formal interface type, to establish a standard interface that all tasks need to implement so they can be managed appropriately by an application-specific scheduler./
Delete paragraph 12.5.5(7/2):
This generic allows an application to establish a standard interface that all tasks need to implement so they can be managed appropriately by an application-specific scheduler.
A.4.2 Package Strings.Maps
Insert before paragraph A.4.2(67):
/Example of use of Strings.Maps.To_Mapping:/
A.10.8 Input-Output for Integer Types
Insert before paragraph A.10.8(26/3):
/Examples of use of an instantiation of Text_IO.Integer_IO:/
A.10.9 Input-Output for Real Types
Insert before paragraph A.10.9(41):
/Examples of use of an instantiation of Text_IO.Float_IO:/
F.3.2 Edited Output Generation
Modify F.3.2(71)
/{Examples of use of edited output; i}[I]n the result string values shown below, 'b' represents the space character[.]{:}/
!discussion
It is odd to read through the reference manual and see examples presented inconsistently. This AI is an attempt to unify the presentation of examples, by providing an italicized introductory sentence or phrase for each example or related set of examples.
!corrigendum 3.2.4(39/4)
!corrigendum 4.1.5(9/3)
!corrigendum 4.1.6(19/3)
!corrigendum 4.2.1(18/5)
!corrigendum 4.3.4(22/5)
!corrigendum 4.3.4(25/5)
!corrigendum 4.3.4(29/5)
!corrigendum 4.3.5(54/5)
!corrigendum 4.3.5(67/5)
!corrigendum 4.5.7(22/5)
!corrigendum 4.5.7(23/5)
!corrigendum 4.5.8(10/3)
Replace the paragraph:
The postcondition for a sorting routine on an array A with an index subtype T can be written:
by:
Example of a quantified expression as a postcondition for a sorting routine on an array A with an index subtype T:
!corrigendum 4.5.8(12/3)
Replace the paragraph:
The assertion that a positive number is composite (as opposed to prime) can be written:
by:
Example of use of a quantified expression as an} assertion that a positive number N is composite (as opposed to prime):
!corrigendum 4.5.9(0)
Insert new clause:
See the conflict file for the changes.
!corrigendum 4.5.10(0)
Insert new clause:
See the conflict file for the changes.
!corrigendum 5.2.1(6/5)
!corrigendum 5.5.2(15/5)
!corrigendum 5.5.2(16/3)
!corrigendum 5.5.3(30/5)
!corrigendum 5.5.3(34/5)
!corrigendum 5.6.1(4/5)
!corrigendum 5.6.1(5/5)
!corrigendum 6.5.1(10/3)
!corrigendum 6.7(6/2)
!corrigendum 6.8(9/3)
!corrigendum 7.3.2(25/5)
!corrigendum 8.3.1(9/2)
!corrigendum 8.3.1(16/2)
!corrigendum 10.1.2(24/2)
!corrigendum 10.1.2(31/2)
!corrigendum 12.5.5(5/2)
!corrigendum 12.5.5(7/2)
!corrigendum A.4.2(67)
Insert before the paragraph:
To_Mapping("ABCD", "ZZAB") returns a Character_Mapping that maps 'A' and 'B' to 'Z', 'C' to 'A', 'D' to 'B', and each other Character to itself.
the new paragraph:
Example of use of Strings.Maps.To_Mapping:
!corrigendum A.10.8(26/3)
Insert before the paragraph:
subtype Byte_Int is Integer range -127 .. 127; package Int_IO is new Integer_IO(Byte_Int); use Int_IO; -- default format used at instantiation, -- Default_Width = 4, Default_Base = 10
the new paragraph:
Examples of use of an instantiation of Text_IO.Integer_IO:
!corrigendum A.10.9(40/1)
Insert before the paragraph:
package Real_IO is new Float_IO(Real); use] Real_IO; --I< default format used at instantiation, Default_Exp = 3}
>
the new paragraph:
Examples of use of an instantiation of Text_IO.Float_IO:
!corrigendum F.3.2(71)
Replace the paragraph:
In the result string values shown below, 'b' represents the space character.
by:
Examples of use of edited output; in the result string values shown below, 'b' represents the space character:
!ASIS
No ASIS effect.
!ACATS test
As this is non-normative text, no ACATS tests are needed.
!appendix

From: Tucker Taft
Sent: Tuesday, March 23, 2021  6:55 AM

The example in section 5.6.1 (Parallel Block Statements) is not preceded by our 
usual "Example of ..." lead in.  I would suggest, perhaps:

   Examples of recursive and nonrecursive uses of parallel block statements:

or simply:

   Examples of parallel block statements:

Another nit:

In RM 6.3.1, we have "Example of procedure body:" and "Example of a 
function body:" in the same set of examples.  It would seem we should add 
"a" to the first lead in.

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

From: Tucker Taft
Sent: Tuesday, March 23, 2021  6:58 AM

Another nit of about the same magnitude:  In RM 5.5.3 (Procedural Iterators)
the lead ins to the examples are not italicized (paragraphs 30/5 and 34/5).

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

From: Tucker Taft
Sent: Tuesday, March 23, 2021  7:23 AM

And yet another: In RM 5.5.2 (Generalized Loop Iteration) the example lead 
in is unlike most others.  It is a comment in the same font size as the 
example.  Normally the lead in is larger, italicized, and starts with 
"Example[s] of ...".  In this case I would suggest:  "Example of array 
component iterator:" and then remove the comment.

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

From: Randy Brukardt
Sent: Wednesday, March 24, 2021  12:30 AM

>The example in section 5.6.1 (Parallel Block Statements) is not 
>preceded by our usual "Example of ..." lead in.  I would suggest, perhaps:

This is the first I know of this lead-in being "usual". You're implying that 
all examples should be constructed that way, but I don't know of many (if
any) modern examples (Ada 2012 or later) that are. Certainly, no one has been
looking for that when examples were created and added to the RM.

For instance, 3.2.4 has a lead-in only for the large example, and not for the 
smaller ones that start the grouping. 4.5.10 has a heading, but they aren't 
described as examples (No "example of"), same with 4.5.8 and 4.5.9.
4.5.7 has no heading at all. That's just from a few probes into clauses that I 
know are relatively new.

If this is really supposed to be "usual", then someone (and that usually falls 
to the complainant :-) will have to look at ALL of the examples systematically 
and suggest changes. Doing so one at a time isn't going to do anything for 
consistency (if that's the goal).

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

From: Tucker Taft
Sent: Wednesday, March 24, 2021  8:36 AM

...

>If this is really supposed to be "usual", then someone (and that usually
>falls to the complainant :-) will have to look at ALL of the examples
>systematically and suggest changes. Doing so one at a time isn't going to do
>anything for consistency (if that's the goal).

Makes sense.  If you could create a homework item for this, I'll handle it as 
a background activity.   I'll try to provide a complete set of "lead ins" for 
all examples and we can decide whether we think they would be a useful 
addition.

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

From: John Barnes
Sent: Thursday, March 25, 2021  6:44 AM

I noticed an example where some reserved words are not in bold.  Do you want
to know about that?  It's not always easy to spot on a screen.

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

From: Randy Brukardt
Sent: Thursday, March 25, 2021  3:41 PM

Those are marked up by hand, so they're easy to miss. Please do tell me about
them (esp. before we finalize the draft!), I fix up some of those periodically
when I see them.

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

This came from WG 9 issue #97.

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

Questions? Ask the ACAA Technical Agent