Index: doc/user/user.tex
===================================================================
--- doc/user/user.tex	(revision 59e86eb950542b83c1ba8461a42aa74c1cc65200)
+++ doc/user/user.tex	(revision 275f4b41090b65cafa0ee962bc45569b0ea89354)
@@ -11,6 +11,6 @@
 %% Created On       : Wed Apr  6 14:53:29 2016
 %% Last Modified By : Peter A. Buhr
-%% Last Modified On : Mon Jul 17 13:06:40 2017
-%% Update Count     : 2825
+%% Last Modified On : Sat Jul 22 11:01:19 2017
+%% Update Count     : 2878
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -251,5 +251,5 @@
 The first \CFA implementation of these extensions was by Esteves~\cite{Esteves04}.
 
-The signature feature of \CFA is \Index{overload}able \Index{parametric-polymorphic} functions~\cite{forceone:impl,Cormack90,Duggan96} with functions generalized using a ©forall© clause (giving the language its name):
+The signature feature of \CFA is \emph{\Index{overload}able} \Index{parametric-polymorphic} functions~\cite{forceone:impl,Cormack90,Duggan96} with functions generalized using a ©forall© clause (giving the language its name):
 \begin{lstlisting}
 ®forall( otype T )® T identity( T val ) { return val; }
@@ -257,5 +257,5 @@
 \end{lstlisting}
 % extending the C type system with parametric polymorphism and overloading, as opposed to the \Index*[C++]{\CC{}} approach of object-oriented extensions.
-\CFA{}\hspace{1pt}'s polymorphism was originally formalized by Ditchfiled~\cite{Ditchfield92}, and first implemented by Bilson~\cite{Bilson03}.
+\CFA{}\hspace{1pt}'s polymorphism was originally formalized by Ditchfield~\cite{Ditchfield92}, and first implemented by Bilson~\cite{Bilson03}.
 However, at that time, there was little interesting in extending C, so work did not continue.
 As the saying goes, ``\Index*{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.
@@ -270,5 +270,5 @@
 Language developers often state that adequate \Index{library support} takes more work than designing and implementing the language itself.
 Fortunately, \CFA, like \Index*[C++]{\CC{}}, 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.
-Hence, \CFA begins by leveraging the large repository of C libraries at little cost.
+Hence, \CFA begins by leveraging the large repository of C libraries, and than allows programmers to incrementally augment their C programs with modern \Index{backward-compatible} features.
 
 \begin{comment}
@@ -318,7 +318,5 @@
 \begin{cfa}
 char abs( char );
-®extern "C" {®
-int abs( int );							§\C{// use default C routine for int}§
-®}® // extern "C"
+®extern "C" {® int abs( int ); ®}®		§\C{// use default C routine for int}§
 long int abs( long int );
 long long int abs( long long int );
@@ -335,4 +333,5 @@
 Hence, there is the same need as in \CC, to know if a name is a C or \CFA name, so it can be correctly formed.
 There is no way around this problem, other than C's approach of creating unique names for each pairing of operation and type.
+
 This example strongly illustrates a core idea in \CFA: \emph{the \Index{power of a name}}.
 The name ``©abs©'' evokes the notion of absolute value, and many mathematical types provide the notion of absolute value.
@@ -343,5 +342,5 @@
 \section[Compiling a CFA Program]{Compiling a \CFA Program}
 
-The command ©cfa© is used to compile \CFA program(s), and is based on the GNU \Indexc{gcc} command, \eg:
+The command ©cfa© is used to compile a \CFA program and is based on the \Index{GNU} \Indexc{gcc} command, \eg:
 \begin{cfa}
 cfa§\indexc{cfa}\index{compilation!cfa@©cfa©}§ [ gcc-options ] C/§\CFA{}§-files [ assembler/loader-files ]
@@ -361,5 +360,5 @@
 \Indexc{-CFA}\index{compilation option!-CFA@©-CFA©}
 Only the C preprocessor and the \CFA translator steps are performed and the transformed program is written to standard output, which makes it possible to examine the code generated by the \CFA translator.
-The generated code started with the standard \CFA prelude.
+The generated code starts with the standard \CFA \Index{prelude}.
 
 \item
@@ -373,5 +372,5 @@
 \Indexc{-nodebug}\index{compilation option!-nodebug@©-nodebug©}
 The program is linked with the non-debugging version of the runtime system, so the execution of the program is faster.
-\Emph{However, no runtime checks or ©assert©s are performed so errors usually result in abnormal program termination.}
+\Emph{However, no runtime checks or ©assert©s are performed so errors usually result in abnormal program behaviour or termination.}
 
 \item
@@ -393,8 +392,10 @@
 \textbf{This option is the default.}
 
+\begin{comment}
 \item
 \Indexc{-no-include-stdhdr}\index{compilation option!-no-include-stdhdr@©-no-include-stdhdr©}
 Do not supply ©extern "C"© wrappers for \Celeven standard include files (see~\VRef{s:StandardHeaders}).
 \textbf{This option is \emph{not} the default.}
+\end{comment}
 \end{description}
 
@@ -417,5 +418,5 @@
 \item
 \Indexc{__CFA__}\index{preprocessor variables!__CFA__@©__CFA__©},
-\Indexc{__CFORALL__}\index{preprocessor variables!__CFORALL__@©__CFORALL__©} and
+\Indexc{__CFORALL__}\index{preprocessor variables!__CFORALL__@©__CFORALL__©}, and
 \Indexc{__cforall}\index{preprocessor variables!__cforall@©__cforall©}
 are always available during preprocessing and have no value.
@@ -470,5 +471,5 @@
 \label{s:BackquoteIdentifiers}
 
-\CFA introduces in new keywords (see \VRef{s:CFAKeywords}) that can clash with existing C variable-names in legacy code.
+\CFA introduces several new keywords (see \VRef{s:CFAKeywords}) that can clash with existing C variable-names in legacy code.
 Keyword clashes are accommodated by syntactic transformations using the \CFA backquote escape-mechanism:
 \begin{cfa}
@@ -476,19 +477,21 @@
 double ®`®forall®`® = 3.5;
 \end{cfa}
+
 Existing C programs with keyword clashes can be converted by enclosing keyword identifiers in backquotes, and eventually the identifier name can be changed to a non-keyword name.
-\VRef[Figure]{f:HeaderFileInterposition} shows how clashes in C header files (see~\VRef{s:StandardHeaders}) can be handled using preprocessor \newterm{interposition}: ©#include_next© and ©-I filename©:
+\VRef[Figure]{f:HeaderFileInterposition} shows how clashes in existing C header-files (see~\VRef{s:StandardHeaders}) can be handled using preprocessor \newterm{interposition}: ©#include_next© and ©-I filename©.
+Several common C header-files with keyword clashes are fixed in the standard \CFA header-library, so there is a seamless programming-experience.
 
 \begin{figure}
 \begin{cfa}
-// include file uses the CFA keyword "otype".
-#if ! defined( otype )			§\C{// nesting ?}§
-#define otype ®`®otype®`®		§\C{// make keyword an identifier}§
+// include file uses the CFA keyword "with".
+#if ! defined( with )			§\C{// nesting ?}§
+#define with ®`®with®`®			§\C{// make keyword an identifier}§
 #define __CFA_BFD_H__
 #endif
 
-®#include_next <bfd.h>			§\C{// must have internal check for multiple expansion}§
+®#include_next <bfdlink.h>		§\C{// must have internal check for multiple expansion}§
 ®
-#if defined( otype ) && defined( __CFA_BFD_H__ )	§\C{// reset only if set}§
-#undef otype
+#if defined( with ) && defined( __CFA_BFD_H__ )	§\C{// reset only if set}§
+#undef with
 #undef __CFA_BFD_H__
 #endif
@@ -499,33 +502,13 @@
 
 
-\section{Exponentiation Operator}
-
-C, \CC, and Java (and many other programming languages) have no exponentiation operator\index{exponentiation!operator}\index{operator!exponentiation}, \ie $x^y$, and instead use a routine, like \Indexc{pow}, to perform the exponentiation operation.
-\CFA extends the basic operators with the exponentiation operator ©?\?©\index{?\\?@\lstinline$?\?$} and ©?\=?©\index{?\\=?@\lstinline$?\=?$}, as in, ©x \ y© and ©x \= y©, which means $x^y$ and $x \leftarrow x^y$.
-The priority of the exponentiation operator is between the cast and multiplicative operators, so that ©w * (int)x \ (int)y * z© is parenthesized as ©((w * (((int)x) \ ((int)y))) * z)©.
-
-As for \Index{division}, there are exponentiation operators for integral and floating-point types, including the builtin \Index{complex} types.
-Unsigned integral exponentiation\index{exponentiation!unsigned integral} is performed with repeated multiplication (or shifting if the base is 2).
-Signed integral exponentiation\index{exponentiation!signed integral} is performed with repeated multiplication (or shifting if the base is 2), but yields a floating-point result because $b^{-e}=1/b^e$.
-Hence, it is important to designate exponent integral-constants as unsigned or signed: ©3 \ 3u© return an integral result, while ©3 \ 3© returns a floating-point result.
-Floating-point exponentiation\index{exponentiation!floating point} is performed using \Index{logarithm}s\index{exponentiation!logarithm}, so the base cannot be negative.
-\begin{cfa}
-sout | 2 ®\® 8u | 4 ®\® 3u | -4 ®\® 3u | 4 ®\® -3 | -4 ®\® -3 | 4.0 ®\® 2.1 | (1.0f+2.0fi) ®\® (3.0f+2.0fi) | endl;
-256 64 -64 0.015625 -0.015625 18.3791736799526 0.264715-1.1922i
-\end{cfa}
-Parenthesis are necessary for the complex constants or the expresion is parsed as ©1.0f+(2.0fi \ 3.0f)+2.0fi©.
-The exponentiation operator is available for all the basic types, but for user-defined types, only the integral version is available, if the user type defines multiplication, ©*©, and one, ©1©.
-
-
 \section{\texorpdfstring{Labelled \LstKeywordStyle{continue} / \LstKeywordStyle{break}}{Labelled continue / break}}
 
 While C provides ©continue© and ©break© statements for altering control flow, both are restricted to one level of nesting for a particular control structure.
 Unfortunately, this restriction forces programmers to use \Indexc{goto} to achieve the equivalent control-flow for more than one level of nesting.
-To prevent having to switch to the ©goto©, \CFA extends the \Indexc{continue}\index{continue@\lstinline $continue$!labelled}\index{labelled!continue@©continue©} and \Indexc{break}\index{break@\lstinline $break$!labelled}\index{labelled!break@©break©} with a target label to support static multi-level exit\index{multi-level exit}\index{static multi-level exit}~\cite{Buhr85}.
+To prevent having to switch to the ©goto©, \CFA extends the \Indexc{continue}\index{continue@\lstinline $continue$!labelled}\index{labelled!continue@©continue©} and \Indexc{break}\index{break@\lstinline $break$!labelled}\index{labelled!break@©break©} with a target label to support static multi-level exit\index{multi-level exit}\index{static multi-level exit}~\cite{Buhr85}, as in Java.
 For both ©continue© and ©break©, the target label must be directly associated with a ©for©, ©while© or ©do© statement;
 for ©break©, the target label can also be associated with a ©switch©, ©if© or compound (©{}©) statement.
 \VRef[Figure]{f:MultiLevelResumeTermination} shows the labelled ©continue© and ©break©, specifying which control structure is the target for exit, and the corresponding C program using only ©goto©.
 The innermost loop has 7 exit points, which cause resumption or termination of one or more of the 7 \Index{nested control-structure}s.
-Java supports both labelled ©continue© and ©break© statements.
 
 \begin{figure}
@@ -540,15 +523,15 @@
 			®LF:® for ( ... ) {
 				®LW:® while ( ... ) {
-					... break ®LC®; ...			// terminate compound
-					... break ®LS®; ...			// terminate switch
-					... break ®LIF®; ...			// terminate if
-					... continue ®LF;® ...	 // resume loop
-					... break ®LF®; ...			// terminate loop
-					... continue ®LW®; ...	 // resume loop
-					... break ®LW®; ...		  // terminate loop
+					... break ®LC®; ...		// terminate compound
+					... break ®LS®; ...		// terminate switch
+					... break ®LIF®; ...	// terminate if
+					... continue ®LF;® ...	// resume loop
+					... break ®LF®; ...		// terminate loop
+					... continue ®LW®; ...	// resume loop
+					... break ®LW®; ...		// terminate loop
 				} // while
 			} // for
 		} else {
-			... break ®LIF®; ...					 // terminate if
+			... break ®LIF®; ...			// terminate if
 		} // if
 	} // switch
@@ -592,15 +575,15 @@
 			  LF: for ( ;; ) {
 				  LW: while ( 1 ) {
-						break LC;			// terminate compound
-						break LS;			// terminate switch
-						break LIF;			// terminate if
-						continue LF;	 // resume loop
-						break LF;			// terminate loop
-						continue LW;	 // resume loop
-						break LW;		  // terminate loop
+						break LC;		// terminate compound
+						break LS;		// terminate switch
+						break LIF;		// terminate if
+						continue LF;	// resume loop
+						break LF;		// terminate loop
+						continue LW;	// resume loop
+						break LW;		// terminate loop
 					} // while
 				} // for
 			} else {
-				break LIF;					 // terminate if
+				break LIF;				 // terminate if
 			} // if
 		} // switch
@@ -641,8 +624,8 @@
 \item
 They cannot branch into a control structure.
-This restriction prevents missing initialization at the start of a control structure resulting in undefined behaviour.
+This restriction prevents missing declarations and/or initializations at the start of a control structure resulting in undefined behaviour.
 \end{itemize}
 The advantage of the labelled ©continue©/©break© is allowing static multi-level exits without having to use the ©goto© statement, and tying control flow to the target control structure rather than an arbitrary point in a program.
-Furthermore, the location of the label at the \emph{beginning} of the target control structure informs the reader that complex control-flow is occurring in the body of the control structure.
+Furthermore, the location of the label at the \emph{beginning} of the target control structure informs the reader (\Index{eye candy}) that complex control-flow is occurring in the body of the control structure.
 With ©goto©, the label is at the end of the control structure, which fails to convey this important clue early enough to the reader.
 Finally, using an explicit target for the transfer instead of an implicit target allows new constructs to be added or removed without affecting existing constructs.
@@ -736,7 +719,6 @@
 The problem with this usage is branching into control structures, which is known to cause both comprehension and technical difficulties.
 The comprehension problem occurs from the inability to determine how control reaches a particular point due to the number of branches leading to it.
-The technical problem results from the inability to ensure allocation and initialization of variables when blocks are not entered at the beginning.
-Often transferring into a block can bypass variable declaration and/or its initialization, which results in subsequent errors.
-There are virtually no positive arguments for this kind of control flow, and therefore, there is a strong impetus to eliminate it.
+The technical problem results from the inability to ensure declaration and initialization of variables when blocks are not entered at the beginning.
+There are no positive arguments for this kind of control flow, and therefore, there is a strong impetus to eliminate it.
 Nevertheless, C does have an idiom where this capability is used, known as ``\Index*{Duff's device}''~\cite{Duff83}:
 \begin{cfa}
@@ -954,8 +936,7 @@
 but it is cumbersome having to write "©this.©" many times in a member.
 
-\CFA provides a ©with© clause/statement to elided the "©this.©" by opening a scope containing field identifiers and changing the qualified fields into variables, giving an opportunity for optimizing qualified references.\footnote{
-The ©with© statement comes from Pascal~\cite[\S~4.F]{Pascal}.}
-\begin{cfa}
-int mem( S &this ) ®with this® {
+\CFA provides a ©with© clause/statement (see Pascal~\cite[\S~4.F]{Pascal}) to elided the "©this.©" by opening a scope containing field identifiers, changing the qualified fields into variables and giving an opportunity for optimizing qualified references.
+\begin{cfa}
+int mem( S &this ) ®with this® {	// with clause
 	i = 1;			®// this.i
 ®	j = 2;			®// this.j
@@ -976,5 +957,5 @@
 	struct S1 { ... } s1;
 	struct S2 { ... } s2;
-	®with s1® {
+	®with s1® {			// with statement
 		// access fields of s1 without qualification
 		®with s2® {  // nesting
@@ -994,13 +975,13 @@
 struct T { int i; int k; int m } b, c;
 ®with a, b® {
-	j + k;						§\C{// unambiguous, unique names define unique type}§
+	j + k;						§\C{// unambiguous, unique names define unique types}§
 	i;							§\C{// ambiguous, same name and type}§
-	a.i + b.i;					§\C{// unambiguous, qualification defines unique type}§
-	m;							§\C{// ambiguous, no context to define unique type}§
-	m = 5.0;					§\C{// unambiguous, context defines unique type}§
-	m = 1;						§\C{// unambiguous, context defines unique type}§
-}
-®with c® { ... }				§\C{// ambiguous, no context}§
-®with (S)c® { ... }				§\C{// unambiguous, cast defines unique type}§
+	a.i + b.i;					§\C{// unambiguous, qualification defines unique names}§
+	m;							§\C{// ambiguous, same name and no context to define unique type}§
+	m = 5.0;					§\C{// unambiguous, same name and context defines unique type}§
+	m = 1;						§\C{// unambiguous, same name and context defines unique type}§
+}
+®with c® { ... }				§\C{// ambiguous, same name and no context}§
+®with (S)c® { ... }				§\C{// unambiguous, same name and cast defines unique type}§
 \end{cfa}
 
@@ -1028,8 +1009,8 @@
 }
 \end{cfa}
-The kind of raise and handler match: ©throw© with ©catch© and @throwResume@ with @catchResume@.
+The kind of raise and handler match: ©throw© with ©catch© and ©throwResume© with ©catchResume©.
 Then the exception type must match along with any additonal predicate must be true.
 The ©catch© and ©catchResume© handlers may appear in any oder.
-However, the ©finally© clause must
+However, the ©finally© clause must appear at the end of the ©try© statement.
 
 
@@ -1242,4 +1223,25 @@
 
 
+\section{Exponentiation Operator}
+
+C, \CC, and Java (and many other programming languages) have no exponentiation operator\index{exponentiation!operator}\index{operator!exponentiation}, \ie $x^y$, and instead use a routine, like \Indexc{pow}, to perform the exponentiation operation.
+\CFA extends the basic operators with the exponentiation operator ©?\?©\index{?\\?@\lstinline$?\?$} and ©?\=?©\index{?\\=?@\lstinline$?\=?$}, as in, ©x \ y© and ©x \= y©, which means $x^y$ and $x \leftarrow x^y$.
+The priority of the exponentiation operator is between the cast and multiplicative operators, so that ©w * (int)x \ (int)y * z© is parenthesized as ©((w * (((int)x) \ ((int)y))) * z)©.
+
+As for \Index{division}, there are exponentiation operators for integral and floating-point types, including the builtin \Index{complex} types.
+Unsigned integral exponentiation\index{exponentiation!unsigned integral} is performed with repeated multiplication (or shifting if the base is 2).
+Signed integral exponentiation\index{exponentiation!signed integral} is performed with repeated multiplication (or shifting if the base is 2), but yields a floating-point result because $b^{-e}=1/b^e$.
+Hence, it is important to designate exponent integral-constants as unsigned or signed: ©3 \ 3u© return an integral result, while ©3 \ 3© returns a floating-point result.
+Floating-point exponentiation\index{exponentiation!floating point} is performed using \Index{logarithm}s\index{exponentiation!logarithm}, so the base cannot be negative.
+\begin{cfa}
+sout | 2 ®\® 8u | 4 ®\® 3u | -4 ®\® 3u | 4 ®\® -3 | -4 ®\® -3 | 4.0 ®\® 2.1 | (1.0f+2.0fi) ®\® (3.0f+2.0fi) | endl;
+256 64 -64 0.015625 -0.015625 18.3791736799526 0.264715-1.1922i
+\end{cfa}
+Parenthesis are necessary for the complex constants or the expresion is parsed as ©1.0f+(2.0fi \ 3.0f)+2.0fi©.
+The exponentiation operator is available for all the basic types, but for user-defined types, only the integral-computation versions are available.
+For returning an integral value, the user type ©T© must define multiplication, ©*©, and one, ©1©;
+for returning a floating-point value, an additional divide of type ©T© into a ©double© returning a ©double© (©double ?/?( double, T )©) is necessary for negative exponents.
+
+
 \section{Pointer / Reference}
 
@@ -1250,5 +1252,6 @@
 An integer constant expression with the value 0, or such an expression cast to type ©void *©, is called a \newterm{null-pointer constant}.\footnote{
 One way to conceptualize the null pointer is that no variable is placed at this address, so the null-pointer address can be used to denote an uninitialized pointer/reference object;
-\ie the null pointer is guaranteed to compare unequal to a pointer to any object or routine.}
+\ie the null pointer is guaranteed to compare unequal to a pointer to any object or routine.
+In general, a value with special meaning among a set of values is called a \emph{\Index{sentinel value}}, \eg ©-1© as a return code value.}
 An address is \newterm{sound}, if it points to a valid memory location in scope, \ie within the program's execution-environment and has not been freed.
 Dereferencing an \newterm{unsound} address, including the null pointer, is \Index{undefined}, often resulting in a \Index{memory fault}.
@@ -1285,15 +1288,15 @@
 \hline
 \begin{cfa}
-lda		r1,100			// load address of x
-ld		 r2,(r1)		  // load value of x
-lda		r3,104			// load address of y
-st		 r2,(r3)		  // store x into y
+lda		r1,100	// load address of x
+ld		 r2,(r1)	  // load value of x
+lda		r3,104	// load address of y
+st		 r2,(r3)	  // store x into y
 \end{cfa}
 &
 \begin{cfa}
 
-ld		r2,(100)		// load value of x
-
-st		r2,(104)		// store x into y
+ld		r2,(100)	// load value of x
+
+st		r2,(104)	// store x into y
 \end{cfa}
 \end{tabular}
@@ -3265,5 +3268,5 @@
 \Indexc{gcc} provides ©typeof© to declare a secondary variable from a primary variable.
 \CFA also relies heavily on the specification of the left-hand side of assignment for type inferencing, so in many cases it is crucial to specify the type of the left-hand side to select the correct type of the right-hand expression.
-Only for overloaded routines with the same return type is variable type-inferencing possible.
+Only for overloaded routines \emph{with the same return type} is variable type-inferencing possible.
 Finally, ©auto© presents the programming problem of tracking down a type when the type is actually needed.
 For example, given
@@ -5407,6 +5410,6 @@
 ©try©			\\
 ©ttype©			\\
+©with©			\\
 ©zero_t©		\\
-				\\
 \end{tabular}
 \end{tabular}
@@ -5442,5 +5445,5 @@
 g( p1, p2 ) int p1, p2;			§\C{// int g( int p1, int p2 );}§
 \end{cfa}
-\CFA supports K\&R routine definitions:
+\CFA continues to support K\&R routine definitions:
 \begin{cfa}
 f( a, b, c )					§\C{// default int return}§
