!standard 3.2.4(39/4) 21-05-24 AI12-0429-1/01 !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(41) !standard F.3.2(71) !class presentation !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 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. !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. ****************************************************************