Index: doc/user/user.tex
===================================================================
--- doc/user/user.tex	(revision e55ca0532660df6b168cbfe023499f87bda57a53)
+++ doc/user/user.tex	(revision 9fd971261b416940675a43d484b27561490d06e4)
@@ -11,6 +11,6 @@
 %% Created On       : Wed Apr  6 14:53:29 2016
 %% Last Modified By : Peter A. Buhr
-%% Last Modified On : Fri Apr  8 11:40:53 2016
-%% Update Count     : 42
+%% Last Modified On : Sun Apr 10 22:50:15 2016
+%% Update Count     : 72
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -21,5 +21,5 @@
 
 % Latex packages used in the document.
-\usepackage[T1]{fontenc}
+\usepackage[T1]{fontenc}                                % allow Latin1 (extended ASCII) characters
 \usepackage{textcomp}
 \usepackage[latin1]{inputenc}
@@ -31,6 +31,6 @@
 \usepackage{footmisc}
 \usepackage{comment}
-\usepackage{latexsym}					% \Box
-\usepackage{mathptmx}					% better math font with "times"
+\usepackage{latexsym}                                   % \Box
+\usepackage{mathptmx}                                   % better math font with "times"
 \usepackage[pagewise]{lineno}
 \renewcommand{\linenumberfont}{\scriptsize\sffamily}
@@ -41,15 +41,17 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-% Names used in the document.
-
-\newcommand{\CS}{C\raisebox{-0.9ex}{\large$^\sharp$}\xspace}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
 % Bespoke macros used in the document.
 \input{common}
 
-\setcounter{secnumdepth}{3}     % number subsubsections
-\setcounter{tocdepth}{3}		% subsubsections in table of contents
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% Names used in the document.
+
+\newcommand{\CS}{C\raisebox{-0.9ex}{\large$^\sharp$}\xspace}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\setcounter{secnumdepth}{3}                             % number subsubsections
+\setcounter{tocdepth}{3}                                % subsubsections in table of contents
 \makeindex
 
@@ -58,5 +60,5 @@
 \begin{document}
 \pagestyle{headings}
-\linenumbers					% comment out to turn off line numbering
+\linenumbers                                            % comment out to turn off line numbering
 
 \title{\Huge
@@ -72,5 +74,6 @@
 }% author
 \date{
-DRAFT\\\today
+DRAFT \\
+\today
 }% date
 
@@ -100,7 +103,7 @@
 
 \CFA\footnote{Pronounced ``C-for-all'', and written \CFA, CFA, or \CFL.} is a modern general-purpose programming-language, designed an as evolutionary step forward from the C programming language.
-The syntax of the \CFA language builds from that of C, and should look immediately familiar to C programmers.
+The syntax of the \CFA language builds from C, and should look immediately familiar to C programmers.
 % Any language feature that is not described here can be assumed to be using the standard C11 syntax.
-\CFA has added many modern programming-language features, which directly leads to increased safety and productivity, while maintaining interoperability with existing C programs, and maintaining C-like performance.
+\CFA adds many modern programming-language features, which directly leads to increased safety and productivity, while maintaining interoperability with existing C programs and maintaining C-like performance.
 Like C, \CFA is a statically typed, procedural language with a low-overhead runtime, meaning there is no global garbage-collection.
 The primary new features include parametric-polymorphism routines and types, exceptions, concurrency, and modules.
@@ -113,5 +116,5 @@
 New programs can be written in \CFA using a combination of C and \CFA features.
 \CC had a similar goal 30 years ago, but has struggled over the intervening time to incorporate modern programming-language features because of early design choices.
-\CFA has 30 years of hindsight and a much cleaner starting point than \CC.
+\CFA has 30 years of hindsight and clean starting point.
 
 Like \CC, there may be both an old and new ways to achieve the same effect.
@@ -138,8 +141,8 @@
 \end{quote2}
 Both programs output the same result.
-While the \CFA I/O looks similar to the \CC style of output, there are several important differences, such as automatic spacing between variables as in Python (see also~\VRef{s:IOLibrary}).
+While the \CFA I/O looks similar to the \CC output style, there are several important differences, such as automatic spacing between variables as in Python (see also~\VRef{s:IOLibrary}).
 
 This document is a reference manual for the \CFA programming language, targeted at \CFA programmers.
-Implementers may also refer to the \CFA Programming Language Specification for details about the language syntax and semantics.
+Implementers may refer to the \CFA Programming Language Specification for details about the language syntax and semantics.
 In its current state, this document covers the intended core features of the language.
 Changes to the syntax and additional features are expected to be included in later revisions.
@@ -153,8 +156,8 @@
 The original \CFA project~\cite{Ditchfield92} extended the C type system with parametric polymorphism and overloading, as opposed to the \CC approach of object-oriented extensions to the C type-system.
 A first implementation of the core Cforall language was created~\cite{Bilson03,Esteves04}, but at the time there was little interesting in extending C, so work did not continue.
-As the saying goes, ``What goes around, comes around'', and there is now renewed interest in the C programming language, so the \CFA project has been restarted.
-
-
-\section{Motivation: Why fix C?}
+As the saying goes, ``What goes around, comes around'', and there is now renewed interest in the C programming language because of legacy code-bases, so the \CFA project has been restarted.
+
+
+\section{Why fix C?}
 
 Even with all its problems, C is a very popular programming language because it allows writing software at virtually any level in a computer system without restriction.
@@ -173,5 +176,5 @@
 Java~\cite{Java8}, Go~\cite{Go}, Rust~\cite{Rust} and D~\cite{D} are examples of the revolutionary approach for modernizing C/\CC, resulting in a new language rather than an extension of the descendent.
 These languages have different syntax and semantics from C, and do not interoperate directly with C, largely because of garbage collection.
-As a result, there is a significant learning curve to move to these languages, and C legacy-code must be complete rewritten.
+As a result, there is a significant learning curve to move to these languages, and C legacy-code must be rewritten.
 These costs can be prohibitive for many companies with a large software base in C/\CC, and many programmers that require retraining to a new programming language.
 
@@ -190,5 +193,5 @@
 This feature allows users of \CFA to take advantage of the existing panoply of C libraries from inside their \CFA code.
 In fact, one of the biggest issues for any new programming language is establishing a minimum level of library code to support a large body of activities.
-Programming-language developers often state that adequate library support costs many times more than designing and implementing the language itself.
+Programming-language developers often state that adequate library support takes more work than designing and implementing the language itself.
 Like \CC, \CFA starts with immediate access to all exiting C libraries, and in many cases, can easily wrap library routines with simpler and safer interfaces, at very low cost.
 
@@ -197,10 +200,9 @@
 Whereas, \CFA wraps each of these routines into one with the common name \lstinline@abs@.
 \begin{lstlisting}
+char abs( char );
 extern "C" {
-#include <stdlib.h>			// provide C prototype for integer "abs" routine
+int abs( int );				// use default C routine for int
 } // extern "C"
-
-char abs( char );
-long int abs( long int );	// @{\CFA}@ overload name "abs" for other types
+long int abs( long int );
 long long int abs( long long int );
 float abs( float );
@@ -219,5 +221,5 @@
 The name ``\lstinline@abs@'' evokes the notion of absolute value, and many mathematical types provide the notion of absolute value.
 Hence, knowing the name \lstinline@abs@ should be sufficient to apply it to any type where it is applicable.
-The time savings and safety of using one name uniformly versus @N@ unique names should not be underestimated.
+The time savings and safety of using one name uniformly versus $N$ unique names should not be underestimated.
 
 
@@ -273,5 +275,5 @@
 the type suffixes \lstinline@U@, \lstinline@L@, etc. may start with an underscore \lstinline@1_U@, \lstinline@1_ll@ or \lstinline@1.0E10_f@.
 \end{enumerate}
-It is significantly easier to read and type long constants when they are broken up into smaller groupings (most cultures use comma or period among digits for the same purpose).
+It is significantly easier to read and enter long constants when they are broken up into smaller groupings (most cultures use comma or period among digits for the same purpose).
 This extension is backwards compatible, matches with the use of underscore in variable names, and appears in Ada and Java.
 
@@ -290,5 +292,5 @@
 \begin{lstlisting}
 int (*f())[ 10 ] {...};
-... (*f())[ 3 ] += 1;		// definition mimics usage
+... (*f())[  3 ] += 1;	// definition mimics usage
 \end{lstlisting}
 Essentially, the return type is wrapped around the routine name in successive layers (like an onion).
@@ -299,13 +301,4 @@
 The only exception is bit field specification, which always appear to the right of the base type.
 C and the new \CFA declarations may appear together in the same program block, but cannot be mixed within a specific declaration.
-Unsupported are K\&R C declarations where the base type defaults to \lstinline@int@, if no type is specified\footnote{
-At least one type specifier shall be given in the declaration specifiers in each declaration, and in the specifier-qualifier list in each structure declaration and type name~\cite[\S~6.7.2(2)]{C11}},
-e.g.:
-\begin{lstlisting}
-x;					// int x
-*y;					// int *y
-f( p1, p2 );		// int f( int p1, int p2 );
-f( p1, p2 ) {}		// int f( int p1, int p2 ) {}
-\end{lstlisting}
 
 In \CFA declarations, the same tokens are used as in C: the character \lstinline@*@ is used to indicate a pointer, square brackets \lstinline@[@\,\lstinline@]@ are used to represent an array, and parentheses \lstinline@()@ are used to indicate a routine parameter.
@@ -333,5 +326,5 @@
 * [ 10 ] double v;
 struct s {
-int f0:3;
+	int f0:3;
 	* int f1;
 	[ 10 ] * int f2;
@@ -363,10 +356,4 @@
 \end{quote2}
 
-As stated above, the two styles of declaration may appear together in the same block.
-Therefore, a programmer has the option of either continuing to use traditional C declarations or take advantage of the new style.
-Clearly, both styles need to be supported for some time due to existing C-style header-files, particularly for UNIX systems.
-In general, mixing declaration styles in a routine or even a translation unit is not recommended, as it makes a program more difficult to read.
-Therefore, it is suggested that an entire translation unit be written in one declaration style or the other.
-
 All type qualifiers, i.e., \lstinline@const@ and \lstinline@volatile@, are used in the normal way with the new declarations but appear left to right, e.g.:
 \begin{quote2}
@@ -411,4 +398,18 @@
 \end{quote2}
 
+Unsupported are K\&R C declarations where the base type defaults to \lstinline@int@, if no type is specified\footnote{
+At least one type specifier shall be given in the declaration specifiers in each declaration, and in the specifier-qualifier list in each structure declaration and type name~\cite[\S~6.7.2(2)]{C11}},
+e.g.:
+\begin{lstlisting}
+x;						// int x
+*y;						// int *y
+f( p1, p2 );			// int f( int p1, int p2 );
+f( p1, p2 ) {}			// int f( int p1, int p2 ) {}
+\end{lstlisting}
+
+As stated above, the two styles of declaration may appear together in the same block.
+Therefore, a programmer has the option of either continuing to use traditional C declarations or take advantage of the new style.
+Clearly, both styles need to be supported for some time due to existing C-style header-files, particularly for UNIX systems.
+
 
 \section{Type Operators}
@@ -448,10 +449,10 @@
 Declaration qualifiers can only appear at the start of a routine definition, e.g.:
 \begin{lstlisting}
-extern [ int x ] g( int y ) {}
+extern [ int x ] g( int y ) {@\,@}
 \end{lstlisting}
 Lastly, if there are no output parameters or input parameters, the brackets and/or parentheses must still be specified;
 in both cases the type is assumed to be void as opposed to old style C defaults of int return type and unknown parameter types, respectively, as in:
 \begin{lstlisting}
-[ ] g();					// no input or output parameters
+[@\,@] g(@\,@);				// no input or output parameters
 [ void ] g( void );			// no input or output parameters
 \end{lstlisting}
@@ -568,5 +569,5 @@
 \section{Named and Default Arguments}
 
-Named and default arguments~\cite{Hardgrave76}.\footnote{
+Named and default arguments~\cite{Hardgrave76}\footnote{
 Francez~\cite{Francez77} proposed a further extension to the named-parameter passing style, which specifies what type of communication (by value, by reference, by name) the argument is passed to the routine.}
 are two mechanisms to simplify routine call.
@@ -836,108 +837,4 @@
 
 Currently, there are no \Index{lambda} expressions, i.e., unnamed routines because routine names are very important to properly select the correct routine.
-
-
-\section{Incompatible}
-
-The following incompatibles exist between C and \CFA, and are similar to Annex C for \CC~\cite{ANSI14:C++}.
-
-\begin{enumerate}
-\item
-Change type of character literal \lstinline@int@ to \lstinline@char@.
-This change allows overloading differentiation argument type matching, e.g.:
-\begin{lstlisting}
-int function( int i );
-int function( char c );
-function( 'x' );
-\end{lstlisting}
-It is preferable that this call match the second version of function rather than the first. \\
-Effect on original feature: Change to semantics of well-defined feature. ISO C programs which depend on
-\begin{lstlisting}
-sizeof('x') == sizeof(int)
-\end{lstlisting}
-will not work the same as C++ programs. \\
-Difficulty of converting: Simple. \\
-How widely used: Programs which depend upon sizeof('x') are probably rare.
-
-\item
-Change: String literals made \lstinline@const@ \\
-The type of a string literal is changed from \lstinline@array of char@ to \lstinline@array of const char@.
-The type of a wide string literal is changed from \lstinline@array of wchar_t@ to \lstinline@array of const wchar_t@. \\
-Rationale: This avoids calling an inappropriate overloaded function, which might expect to be able to modify its argument.
-Effect on original feature: Change to semantics of well-defined feature. \\
-Difficulty of converting: Simple syntactic transformation, because string literals can be converted to \lstinline@char*;@ (4.2).
-The most common cases are handled by a new but deprecated standard conversion:
-\begin{lstlisting}
-char* p = "abc"; // valid in C, deprecated in C++
-char* q = expr ? "abc" : "de"; // valid in C, invalid in C++
-\end{lstlisting}
-How widely used: Programs that have a legitimate reason to treat string literals as pointers to potentially modifiable memory are probably rare.
-
-\item
-Change: C++ does not have \emph{tentative definitions} as in C.
-E.g., at file scope,
-\begin{lstlisting}
-int i;
-int i;
-\end{lstlisting}
-is valid in C, invalid in C++.
-This makes it impossible to define mutually referential file-local static
-objects, if initializers are restricted to the syntactic forms of C. For example,
-\begin{lstlisting}
-struct X { int i; struct X *next; };
-static struct X a;
-static struct X b = { 0, &a };
-static struct X a = { 1, &b };
-\end{lstlisting}
-Rationale: This avoids having different initialization rules for builtin types and userdefined types.
-Effect on original feature: Deletion of semantically welldefined feature. \\
-Difficulty of converting: Semantic transformation.
-In C++, the initializer for one of a set of mutuallyreferential filelocal static objects must invoke a function call to achieve the initialization.
-How widely used: Seldom.
-
-\item
-Change: A struct is a scope in C++, not in C \\
-Rationale: Class scope is crucial to C++, and a struct is a class. \\
-Effect on original feature: Change to semantics of well-defined feature. \\
-Difficulty of converting: Semantic transformation. \\
-How widely used: C programs use struct extremely frequently, but the change is only noticeable when struct, enumeration, or enumerator names are referred to outside the struct.
-The latter is probably rare.
-
-\CFA is C \emph{incompatible} on this issue, and provides semantics similar to \CC.
-Nested types are not hoisted and can be referenced using the field selection operator ``\lstinline@.@'', unlike the \CC scope-resolution operator ``\lstinline@::@''.
-Given that nested types in C are equivalent to not using them, i.e., they are essentially useless, it is unlikely there are any realistic usages that break because of this incompatibility.
-
-
-\item
-Change: In C++, the name of a nested class is local to its enclosing class.
-In C the name of the nested class belongs to the same scope as the name of the outermost enclosing class
-Example:
-\begin{lstlisting}
-struct X {
-struct Y { /* ... */ } y;
-};
-struct Y yy; // valid C, invalid C++
-\end{lstlisting}
-Rationale: C++ classes have member functions which require that classes establish scopes. The C rule
-would leave classes as an incomplete scope mechanism which would prevent C++ programmers from maintaining
-locality within a class. A coherent set of scope rules for C++ based on the C rule would be very
-complicated and C++ programmers would be unable to predict reliably the meanings of nontrivial examples
-involving nested or local functions.
-Effect on original feature: Change of semantics of welldefined
-feature.
-Difficulty of converting: Semantic transformation. To make the struct type name visible in the scope of
-the enclosing struct, the struct tag could be declared in the scope of the enclosing struct, before the enclosing
-struct is defined. Example:
-\begin{lstlisting}
-struct Y; // struct Y and struct X are at the same scope
-struct X {
-struct Y { /* ... */ } y;
-};
-\end{lstlisting}
-All the definitions of C struct types enclosed in other struct definitions and accessed outside the scope of
-the enclosing struct could be exported to the scope of the enclosing struct. Note: this is a consequence of
-the difference in scope rules, which is documented in 3.3.
-How widely used: Seldom.
-\end{enumerate}
 
 
@@ -4061,4 +3958,108 @@
 
 
+\section{Incompatible}
+
+The following incompatibles exist between C and \CFA, and are similar to Annex C for \CC~\cite{ANSI14:C++}.
+
+\begin{enumerate}
+\item
+Change type of character literal \lstinline@int@ to \lstinline@char@.
+This change allows overloading differentiation argument type matching, e.g.:
+\begin{lstlisting}
+int function( int i );
+int function( char c );
+function( 'x' );
+\end{lstlisting}
+It is preferable that this call match the second version of function rather than the first. \\
+Effect on original feature: Change to semantics of well-defined feature. ISO C programs which depend on
+\begin{lstlisting}
+sizeof('x') == sizeof(int)
+\end{lstlisting}
+will not work the same as C++ programs. \\
+Difficulty of converting: Simple. \\
+How widely used: Programs which depend upon sizeof('x') are probably rare.
+
+\item
+Change: String literals made \lstinline@const@ \\
+The type of a string literal is changed from \lstinline@array of char@ to \lstinline@array of const char@.
+The type of a wide string literal is changed from \lstinline@array of wchar_t@ to \lstinline@array of const wchar_t@. \\
+Rationale: This avoids calling an inappropriate overloaded function, which might expect to be able to modify its argument.
+Effect on original feature: Change to semantics of well-defined feature. \\
+Difficulty of converting: Simple syntactic transformation, because string literals can be converted to \lstinline@char*;@ (4.2).
+The most common cases are handled by a new but deprecated standard conversion:
+\begin{lstlisting}
+char* p = "abc"; // valid in C, deprecated in C++
+char* q = expr ? "abc" : "de"; // valid in C, invalid in C++
+\end{lstlisting}
+How widely used: Programs that have a legitimate reason to treat string literals as pointers to potentially modifiable memory are probably rare.
+
+\item
+Change: C++ does not have \emph{tentative definitions} as in C.
+E.g., at file scope,
+\begin{lstlisting}
+int i;
+int i;
+\end{lstlisting}
+is valid in C, invalid in C++.
+This makes it impossible to define mutually referential file-local static
+objects, if initializers are restricted to the syntactic forms of C. For example,
+\begin{lstlisting}
+struct X { int i; struct X *next; };
+static struct X a;
+static struct X b = { 0, &a };
+static struct X a = { 1, &b };
+\end{lstlisting}
+Rationale: This avoids having different initialization rules for builtin types and userdefined types.
+Effect on original feature: Deletion of semantically welldefined feature. \\
+Difficulty of converting: Semantic transformation.
+In C++, the initializer for one of a set of mutuallyreferential filelocal static objects must invoke a function call to achieve the initialization.
+How widely used: Seldom.
+
+\item
+Change: A struct is a scope in C++, not in C \\
+Rationale: Class scope is crucial to C++, and a struct is a class. \\
+Effect on original feature: Change to semantics of well-defined feature. \\
+Difficulty of converting: Semantic transformation. \\
+How widely used: C programs use struct extremely frequently, but the change is only noticeable when struct, enumeration, or enumerator names are referred to outside the struct.
+The latter is probably rare.
+
+\CFA is C \emph{incompatible} on this issue, and provides semantics similar to \CC.
+Nested types are not hoisted and can be referenced using the field selection operator ``\lstinline@.@'', unlike the \CC scope-resolution operator ``\lstinline@::@''.
+Given that nested types in C are equivalent to not using them, i.e., they are essentially useless, it is unlikely there are any realistic usages that break because of this incompatibility.
+
+
+\item
+Change: In C++, the name of a nested class is local to its enclosing class.
+In C the name of the nested class belongs to the same scope as the name of the outermost enclosing class
+Example:
+\begin{lstlisting}
+struct X {
+struct Y { /* ... */ } y;
+};
+struct Y yy; // valid C, invalid C++
+\end{lstlisting}
+Rationale: C++ classes have member functions which require that classes establish scopes. The C rule
+would leave classes as an incomplete scope mechanism which would prevent C++ programmers from maintaining
+locality within a class. A coherent set of scope rules for C++ based on the C rule would be very
+complicated and C++ programmers would be unable to predict reliably the meanings of nontrivial examples
+involving nested or local functions.
+Effect on original feature: Change of semantics of welldefined
+feature.
+Difficulty of converting: Semantic transformation. To make the struct type name visible in the scope of
+the enclosing struct, the struct tag could be declared in the scope of the enclosing struct, before the enclosing
+struct is defined. Example:
+\begin{lstlisting}
+struct Y; // struct Y and struct X are at the same scope
+struct X {
+struct Y { /* ... */ } y;
+};
+\end{lstlisting}
+All the definitions of C struct types enclosed in other struct definitions and accessed outside the scope of
+the enclosing struct could be exported to the scope of the enclosing struct. Note: this is a consequence of
+the difference in scope rules, which is documented in 3.3.
+How widely used: Seldom.
+\end{enumerate}
+
+
 \section{I/O Library}
 \label{s:IOLibrary}
