cosmetics

annotations/yo/classes/ambiguity.yo

@@ -1,5 +1,5 @@
-Defining objects may result in some unexpected surprises. Assume the following
-class interface is available:
+Calling constructors using parentheses may result in unexpected
+surprises. Assume the following class interface is available:
         verb(
     class Data
     {
@@ -13,8 +13,8 @@ class interface is available:
         )
 
 The intention is to define two objects of the class Data, using, respectively,
-the first and second constructors. Your code looks like this (and compiles
-correctly):
+the first and second constructors, while using parentheses in the object
+definitions. Your code looks like this (and compiles correctly):
         verb(
     #include "data.h"
     int main()
@@ -24,7 +24,7 @@ correctly):
     }
         )
 
-Now it's time to make some good use of the tt(Data) objects. You add two
+Now it's time to make some good use of the tt(Data) objects. Let's add two
 statements to tt(main):
             verb(
         d1.display();

annotations/yo/classes/arguments.yo

@@ -1,11 +1,11 @@
-The class tt(Person)'s constructor so far has no parameters. bf(C++) allows
-constructors to be defined with or without parameter lists. The arguments are
-supplied when an object is defined.
+The class tt(Person)'s constructor so far has not received any
+parameters. bf(C++) allows constructors to be defined with or without
+parameter lists. The arguments are supplied when an object is defined.
 
 For the class tt(Person) a constructor expecting three strings and a
-tt(size_t) might be useful. Representing, respectively, the
-person's name, address, phone number and mass. This constructor is (but see
-also section ref(MemberInitializers)):
+tt(size_t) might be useful. Representing, respectively, the person's name,
+address, phone number and mass. This constructor can be implemented like this
+(but see also section ref(MemberInitializers)):
         verb(
     Person::Person(string const &name, string const &address,
                    string const &phone, size_t mass)
@@ -69,9 +69,15 @@ automatically. Its implementation can be:
     }
         )
     Using constructors with and without arguments is illustrated next. The
-object tt(karel) is initialized by  the constructor defining a non-empty
-parameter list while the default constructor is used with the tt(anon)
-object:
+object tt(karel) is initialized by the constructor defining a non-empty
+parameter list while the default constructor is used for the tt(anon)
+object. When constructing objects using constructors requiring arguments you
+are advised to surround the arguments by curly braces. Parentheses can often
+also be used, and sometimes even em(have) to be used (cf. section
+ref(VECTOR)), but mindlessly using parentheses instead of curly braces may
+easily result in unexpected problems (cf. section ref(AMBIGUITY)). Hence the
+advice to prefer curly braces rather than parentheses. Here's the
+example showing two constructor-calls:
         verb(
     int main()
     {

annotations/yo/classes/construc.yo

@@ -1,10 +1,11 @@
-bf(C++) classes may contain two special categories of member functions which
-are essential to the proper working of the class. These categories are the
+bf(C++) classes usually contain two special categories of member functions
+which are essential to the proper working of classes. These categories are the
 constructors and the i(destructor). The em(destructor)'s primary task is to
 return memory allocated by an object to the common pool when an object goes
 `out of scope'.  Allocation of memory is discussed in chapter ref(MEMORY), and
-destructors are therefore be discussed in depth in that chapter.  In this
-chapter the emphasis is on the class's organization and its constructors.
+an in-depth coverage of destructors is therefore postponed until we reach that
+chapter.  In the current chapter the emphasis is on the class's internal
+organization and on its constructors.
 
 Constructors are recognized by their names which are equal to their class
 names.  Constructors do not specify return values, not even tt(void).  E.g.,
@@ -41,6 +42,6 @@ task shortly. The em(default constructor)hi(constructor: default) has no
 argument. It is defined by the compiler unless another constructor is defined
 and unless its definition is suppressed (cf. section ref(DEFAULTED)). If a
 default constructor is required in addition to another constructor then the
-default constructor must explicitly be defined as well. bf(C++)
-provides special syntax to do that as well, which is also covered by section
-ref(DEFAULTED).
+default constructor must explicitly be defined as well. bf(C++) provides
+special syntax to realize that without much effort, which is also covered by
+section ref(DEFAULTED).

annotations/yo/classtemplates.yo

@@ -1,6 +1,6 @@
 includefile(classtemplates/intro)
 
-    lsubsect(ARGDEDUCTION)(C++17: Template Argument Deduction)
+    lsubsect(ARGDEDUCTION)(Template Argument Deduction (C++17))
     includefile(classtemplates/argdeduction)
 
         subsubsect(Simple Definitions)

annotations/yo/first.yo

@@ -59,7 +59,7 @@ sect(Several additions to C's grammar)
     subsect(Binary constants)
     includefile(first/binary)
 
-    subsect((C++17) Selection statements with initializers)
+    subsect(Selection statements with initializers (C++17))
     includefile(first/selectinit)
 
     subsect(Attributes)

annotations/yo/first/binding.yo

@@ -17,7 +17,7 @@ tt(fun) returns a tt(struct) having two data fields:
     
     Return fun()
     {
-        return Return{1, 12.5};
+        return Return{ 1, 12.5 };
     }
         )
     (Briefly forward referencing to sections ref(PAIR) and ref(TUPLES): the