Editorial suggestions from T. Taft

Various editorial suggestions from T. Taft.

Author: sttaft

content/courses/ada-idioms/chapters/abstract_data_machines.rst

@@ -83,7 +83,7 @@ following:
    - Operations
 
 The package declaration's private part and the package body may contain all
-the above, but one or the other (or both) will contain object declarations
+the above, but one or the other (or both) will contain variable declarations
 representing the abstraction's state.
 
 Consider the following ADM version of the package :ada:`Integer_Stacks`, now
@@ -115,14 +115,14 @@ version we declare the state in the package body.
     end Integer_Stack;
 
 Now there is no type presenting a :ada:`Stack` abstraction and the operations
-do not take a stack parameter because the package and its data is the instance
+do not take a stack parameter because the package and its data together are the instance
 of the abstraction. When using this idiom, there is only one stack of integers.
 That's why we changed the name of the package from :ada:`Integer_Stacks`, i.e.,
 from the plural form to the singular.
 
 As with the ADT idiom, clients of an ADM can only manipulate the encapsulated
 state indirectly, via the visible operations. The difference is that the state
-to be manipulated is no longer a formal parameter. For example:
+to be manipulated is no longer a formal parameter of the operations. For example:
 
 .. code-block:: ada
 
@@ -138,7 +138,7 @@ type :ada:`Stack` are manipulated:
     --  ...
     Push (Answers, 42);
 
-That call places the value 42 in the array :ada:`Answers.Values`, i.e., within
+That call places the value 42 in the (hidden) array :ada:`Answers.Values`, i.e., within
 the :ada:`Answers` variable. Clients can declare as many :ada:`Stack` objects
 as they require, each containing a distinct copy of the state defined by the
 type. In the ADM version, there is only one stack and therefore only one instance
@@ -170,13 +170,13 @@ The private section wasn't otherwise required when we chose to declare the data
 the package body.
 
 The ADM idiom applies information hiding to the internal state, like the
-ADT idiom, except that the state is not in objects. Also, like the
+ADT idiom, except that the state is not in objects declared in the client. Also, like the
 :ref:`Groups of Related Program Units <Ada_Idioms_Groups_Of_Related_Program_Units>`,
 the implementations of the visible subprograms are hidden in the package body,
 along with any non-visible entities required for their implementation.
 
 There are no constructor functions returning a value of the abstraction
-type because there is no such type with the ADM. However, there could be one or
+type because there is no such type within the ADM. However, there could be one or
 more initialization procedures, operating directly on the hidden state in the
 package private part or package body. In the :ada:`Stack` ADM there is no need
 because of the reasonable initial state, as is true with the ADT version.

content/courses/ada-idioms/chapters/abstract_data_types.rst

@@ -14,8 +14,9 @@ client compile-time visibility to the type's representation is both an
 advantage and a disadvantage. Visibility to the representation makes available
 the expressiveness of low-level syntax, such as array indexing and aggregates,
 but in so doing allows client source code to be dependent on the
-representation. In the vast majority of cases, the resulting economic and
-engineering disadvantages far outweigh the expressiveness advantages.
+representation. In many cases, the resulting economic and
+engineering disadvantages of visibility on the representation will
+outweigh the expressiveness advantages.
 
 For the sake of illustration, let's create a *stack* type that can contain
 values of type :ada:`Integer`. (We use type :ada:`Integer` purely for the sake
@@ -111,7 +112,7 @@ The ADT may also be abstract in the sense of object-oriented programming but
 that is an unrelated issue.
 
 In Ada we use *private types* to define abstract data types because private
-types make the type's name, but not the representation, visible to clients.
+types make the type's name, but not its representation, visible to clients.
 These types are composed using syntactical building blocks: a package
 declaration, separated into two parts, containing a type declared in two parts,
 and containing declarations for subprograms to manipulate objects of the type
@@ -203,7 +204,7 @@ The full type definition is in the package private part. Therefore, for
 any given object of the type, the representation details |mdash| the two
 record components in this example |mdash| can't be referenced in client code.
 Clients must instead only use the operations defined by the package, passing
-the client objects to the formal parameters. Only the bodies of these operations
+the client objects as the actual parameters. Only the bodies of these operations
 have compile-time visibility to the representation of the :ada:`Stack`
 parameters, so only they can implement the functionality for those parameters.
 
@@ -216,7 +217,7 @@ mentioned, basic operations such as assignment are allowed, unless the ADT is
 abstraction.
 
 You may, of course, also require other ancillary type declarations in the
-package, either for the implementation or as additional parameters for the
+package, either for the implementation or as types for additional parameters for the
 visible operations. The array type :ada:`Content` is an example of the
 former case. When it is strictly an implementation artifact, as in this
 case, it should be in the private part so that it's hidden from clients.
@@ -279,7 +280,7 @@ There may be cases when what looks like an accessor function is provided, when
 in fact the function computes the return value.  Similarly, there may be
 functions that simply return the value of a component but are part of the
 abstraction and happen to be implementable by returning the value of a
-component. For example, a real stacks ADT package would include a function
+component. For example, a real stack's ADT package would include a function
 indicating the extent of the object |mdash| that is, the number of values
 currently contained. In our example implementation the :ada:`Top` component happens to
 indicate that value, in addition to indicating the current top of the stack. The body

content/courses/ada-idioms/chapters/constructor_functions_for_abstract_data_types.rst

@@ -70,7 +70,7 @@ the type declaration itself. For procedures, that means they have formal
 parameters of the type. For functions, that means they either have formal
 parameters of the type, or return a value of the type, or both.
 
-Declaration with the same package as the type itself provides the
+Declaration within the same package as the type itself provides the
 compile-time visibility to the type's representation required to
 implement the subprograms.
 
@@ -136,7 +136,7 @@ Therefore, unless the extended child type is itself abstract, the type extension
 will be illegal. The compiler will reject the declaration of the child type,
 thus preventing this inappropriate constructor inheritance.
 
-For an example, both for the code and the Ada rules, consider this simple
+For an example, both to illustrate the code and the Ada rules, consider this simple
 package declaration that presents the tagged private type
 :ada:`Graphics.Shape`:
 
@@ -223,8 +223,7 @@ compile-time visibility that primitive operations have.
 
 Therefore, the specific solution is to declare constructor functions in a
 separate package that is a *child* of the package declaring the tagged type.
-The actual term is a *hierarchical library package* but *child* conveys the
-concept and is less of a mouthful.
+This takes advantage of the *hierarchical library units* capability introduced in Ada 95.
 
 Operations declared in a child package are not primitive operations for the
 type in the parent package, so they are not inherited when that type is
@@ -317,7 +316,8 @@ locating individual entities of interest, any decent IDE will make doing so
 trivial.)
 
 The alternative also loses the distinction between clients that use objects of
-the type and clients that create those objects, because the latter will have
+the type and clients that create those objects, because, with the child package
+approach, the latter will be the only clients that have
 context clauses for the constructor packages.
 
 

content/courses/ada-idioms/chapters/controlling_obj_initialization_creation.rst

@@ -24,7 +24,7 @@ most commonly used non-numeric type in the language. Sometimes a given type was
 initialization, e.g., numeric types. That wrapping approach is less common than
 in earlier versions of the language, given the comparatively more recent aspect
 :ada:`Default_Value` for scalar types, and :ada:`Default_Component_Value` for
-scalar components.
+scalar array components.
 
 These facilities are often sufficient to express an abstraction's initial
 state. For example, we can expect that container objects will be initially

content/courses/ada-idioms/chapters/programming_by_extension.rst

@@ -227,12 +227,12 @@ Notes
 -----
 
 This guideline will already be used when developing a subsystem (a set of
-related packages in a common hierarchy) as a structuring approach during
+related packages in an overall hierarchy) as a structuring approach during
 initial development. The idiom discussed here is yet another reason to use the
 private part, but in this case for the sake of the future, rather than initial,
 development.
 
-The very first version of Ada (Ada 83) did not have hierarchical packages so,
+The very first version of Ada (Ada 83) did not have hierarchical library units so,
 typically, anything not required in the private part was declared in the
 package body. Declaring them in the private part would only clutter the code
 that had to be there, without any benefit. The author's personal experience and