Index: doc/theses/mike_brooks_MMath/background.tex
===================================================================
--- doc/theses/mike_brooks_MMath/background.tex	(revision d3a4986415d3791181de98120031e71a598fe5ce)
+++ doc/theses/mike_brooks_MMath/background.tex	(revision dd37afa5450c7bb0e81ab86657938750d3465a84)
@@ -65,105 +65,114 @@
 \end{itemize}
 
-The following sections introduce the many layers of the C array story, concluding with an \emph{Unfortunate Syntactic Reference}.
-It shows how to define (spell) the types under discussion, along with interactions with orthogonal (but easily confused) language features.
-Alternate spellings are listed within a row.
-The simplest occurrences of types distinguished in the preceding discussion are marked with $\triangleright$.
-The Type column gives the spelling used in a cast or error message (though note Section TODO points out that some types cannot be casted to).
-The Declaration column gives the spelling used in an object declaration, such as variable or aggregate member; parameter declarations (section TODO) follow entirely different rules.
-
-After all, reading a C array type is easy: just read it from the inside out, and know when to look left and when to look right!
-
-
-\CFA-specific spellings (not yet introduced) are also included here for referenceability; these can be skipped on linear reading.
-The \CFA-C column gives the, more fortunate, ``new'' syntax of section TODO, for spelling \emph{exactly the same type}.
-This fortunate syntax does not have different spellings for types vs declarations;
-a declaration is always the type followed by the declared identifier name;
-for the example of letting @x@ be a \emph{pointer to array}, the declaration is spelled:
-\begin{cfa}
-* [10] T x;
-\end{cfa}
-The \CFA-Full column gives the spelling of a different type, introduced in TODO, which has all of my contributed improvements for safety and ergonomics.
-
-Another example of confusion results from the fact that a routine name and its parameters are embedded within the return type, mimicking the way the return value is used at the routine's call site.
-For example, a routine returning a \Index{pointer} to an array of integers is defined and used in the following way:
-\begin{cfa}
-int @(*@f@())[@5@]@ {...}; $\C{// definition}$
- ... @(*@f@())[@3@]@ += 1; $\C{// usage}$
-\end{cfa}
-Essentially, the return type is wrapped around the routine name in successive layers (like an \Index{onion}).
+
+\section{Reading Declarations}
+
+A significant area of confusion for reading C declarations results from embedding a declared variable in a declaration, mimicking the way the variable is used in executable statements.
+\begin{cquote}
+\begin{tabular}{@{}ll@{}}
+\multicolumn{1}{@{}c}{\textbf{Array}} & \multicolumn{1}{c@{}}{\textbf{Function}} \\
+\begin{cfa}
+int @(*@ar@)[@5@]@; // definition
+  ... @(*@ar@)[@3@]@ += 1; // usage
+\end{cfa}
+&
+\begin{cfa}
+int @(*@f@())[@5@]@ { ... }; // definition
+  ... @(*@f@())[@3@]@ += 1; // usage
+\end{cfa}
+\end{tabular}
+\end{cquote}
+Essentially, the type is wrapped around the name in successive layers (like an \Index{onion}).
 While attempting to make the two contexts consistent is a laudable goal, it has not worked out in practice, even though Dennis Richie believed otherwise:
 \begin{quote}
 In spite of its difficulties, I believe that the C's approach to declarations remains plausible, and am comfortable with it; it is a useful unifying principle.~\cite[p.~12]{Ritchie93}
 \end{quote}
+After all, reading a C array type is easy: just read it from the inside out, and know when to look left and when to look right!
 
 \CFA provides its own type, variable and routine declarations, using a different syntax.
 The new declarations place qualifiers to the left of the base type, while C declarations place qualifiers to the right of the base type.
-In the following example, {\color{red}red} is the base type and {\color{blue}blue} is qualifiers.
-The \CFA declarations move the qualifiers to the left of the base type, \ie move the blue to the left of the red, while the qualifiers have the same meaning but are ordered left to right to specify a variable's type.
+The qualifiers have the same meaning in \CFA as in C.
+Hence, a \CFA declaration is read left to right, where a function return type is enclosed in brackets @[]@.
 \begin{cquote}
-\begin{tabular}{@{}l@{\hspace{3em}}l@{}}
-\multicolumn{1}{c@{\hspace{3em}}}{\textbf{C}}	& \multicolumn{1}{c}{\textbf{\CFA}}	\\
-\begin{cfa}[moredelim={**[is][\color{blue}]{\#}{\#}}]
-@int@ #*# x1 #[5]#;
-@int@ #(*#x2#)[5]#;
-#int (*#f@( int p )@#)[5]#;
+\begin{tabular}{@{}l@{\hspace{3em}}ll@{}}
+\multicolumn{1}{c@{\hspace{3em}}}{\textbf{C}}	& \multicolumn{1}{c}{\textbf{\CFA}} &	\\
+\begin{cfa}
+int @*@ x1 @[5]@;
+int @(*@x2@)[5]@;
+int @(*@f( int p )@)[5]@;
 \end{cfa}
 &
-\begin{cfa}[moredelim={**[is][\color{blue}]{\#}{\#}}]
-#[5] *# @int@ x1;
-#* [5]# @int@ x2;
-#[* [5] int]# f@( int p )@;
-\end{cfa}
+\begin{cfa}
+@[5] *@ int x1;
+@* [5]@ int x2;
+@[ * [5] int ]@ f( int p );
+\end{cfa}
+&
+\begin{cfa}
+// array of 5 pointers to int
+// pointer to array of 5 int
+// function returning pointer to array of 5 ints
+\end{cfa}
+\\
+& &
+\LstCommentStyle{//\ \ \ and taking an int argument}
 \end{tabular}
 \end{cquote}
-
-\VRef[Figure]{bkgd:ar:usr:avp} gives this reference for the discussion so far.
-
-\begin{figure}
+As declaration complexity increases, it becomes corresponding difficult to read and understand the C declaration form.
+Note, writing declarations left to right is common in other programming languages, where the function return-type is often placed after the parameter declarations.
+
+\VRef[Table]{bkgd:ar:usr:avp} introduces the many layers of the C and \CFA array story, where the \CFA story is discussion in \VRef{XXX}.
+The \CFA-thesis column shows the new array declaration form, which is my contributed improvements for safety and ergonomics.
+The table shows there are multiple yet equivalent forms for the array types under discussion, and subsequent discussion shows interactions with orthogonal (but easily confused) language features.
+Each row of the table shows alternate syntactic forms.
+The simplest occurrences of types distinguished in the preceding discussion are marked with $\triangleright$.
+Removing the declared variable @x@, gives the type used for variable, structure field, cast or error message \PAB{(though note Section TODO points out that some types cannot be casted to)}.
+Unfortunately, parameter declarations \PAB{(section TODO)} have more syntactic forms and rules.
+
+\begin{table}
 \centering
-\setlength{\tabcolsep}{3pt}
-\begin{tabular}{ll|l|l|l|l}
-	& Description & Type & Declaration & \CFA  & \CFA-thesis \\ \hline
-	$\triangleright$ & val. & @T@ & @T x;@ & @T@ & \\
-	\hline
-	& immutable val. & @const T@ & @T const x;@ & @const T@ & \\
-	& & @T const@ & @T const x;@ & @T const@ & \\
+\caption{Syntactic Reference for Array vs Pointer. Includes interaction with constness.}
+\label{bkgd:ar:usr:avp}
+\begin{tabular}{ll|l|l|l}
+	& Description & \multicolumn{1}{c|}{C} & \multicolumn{1}{c|}{\CFA}  & \multicolumn{1}{c}{\CFA-thesis} \\
+	\hline
+	$\triangleright$ & value & @T x;@ & @T x;@ & \\
+	\hline
+	& immutable value & @const T x;@ & @const T x;@ & \\
+	& & @T const x;@ & @T const x;@ & \\
 	\hline \hline
-	$\triangleright$ & ptr.\ to val. & @T *@ & @T * x;@ & @* T@ & \\
-	\hline
-	& immutable ptr. to val. & @T * const@ & @T * const x;@ & @const * T@ & \\
-	\hline
-	& ptr. to immutable val. & @const T *@ & @const T * x;@ & @* const T@ & \\
-	& & @T const *@ & @T const * x;@ & @* T const@ & \\
+	$\triangleright$ & pointer to value & @T * x;@ & @* T x;@ & \\
+	\hline
+	& immutable ptr. to val. & @T * const x;@ & @const * T x;@ & \\
+	\hline
+	& ptr. to immutable val. & @const T * x;@ & @* const T x;@ & \\
+	& & @T const * x;@ & @* T const x;@ & \\
 	\hline \hline
-	$\triangleright$ & ar.\ of val. & @T[10]@ & @T x[10];@ & @[10] T@ & @array(T, 10)@ \\
-	\hline
-	& ar.\ of immutable val. & @const T[10]@ & @const T x[10];@ & @[10] const T@ & @const array(T, 10)@ \\
-    & & @T const [10]@ & @T const x[10];@ & @[10] T const@ & @array(T, 10) const@ \\
-	\hline
-	& ar.\ of ptr.\ to val. & @T * [10]@ & @T * x[10];@ & @[10] * T@ & @array(T * | * T, 10)@ \\
-	\hline
-	& ar.\ of imm. ptr.\ to val. & @T * const [10]@ & @T * const x[10];@ & @[10] const * T@ & @array(const * T, 10)@ \\
-	\hline
-	& ar.\ of ptr.\ to imm. val. & @const T * [10]@ & @const T * x[10];@ & @[10] * const T@ & @array(* const T, 10)@ \\
-	& & @T const * [10]@ & @T const * x[10];@ & @[10] * T const@ & @array(* T const, 10)@ \\
+	$\triangleright$ & array of value & @T x[10];@ & @[10] T x@ & @array(T, 10) x@ \\
+	\hline
+	& ar.\ of immutable val. & @const T x[10];@ & @[10] const T x@ & @const array(T, 10) x@ \\
+    & & @T const x[10];@ & @[10] T const x@ & @array(T, 10) const x@ \\
+	\hline
+	& ar.\ of ptr.\ to value & @T * x[10];@ & @[10] * T x@ & @array(T *, 10) x@ \\
+	& & & & @array(* T, 10) x@ \\
+	\hline
+	& ar.\ of imm. ptr.\ to val. & @T * const x[10];@ & @[10] const * T x@ & @array(* const T, 10) x@ \\
+	& & & & @array(const * T, 10) x@ \\
+	\hline
+	& ar.\ of ptr.\ to imm. val. & @const T * x[10];@ & @[10] * const T x@ & @array(const T *, 10) x@ \\
+	& & @T const * x[10];@ & @[10] * T const x@ & @array(* const T, 10) x@ \\
 	\hline \hline
-	$\triangleright$ & ptr.\ to ar.\ of val. & @T(*)[10]@ & @T (*x)[10];@ & @* [10] T@ & @* array(T, 10)@ \\
-	\hline
-	& imm. ptr.\ to ar.\ of val. & @T(* const)[10]@ & @T (* const x)[10];@ & @const * [10] T@ & @const * array(T, 10)@ \\
-	\hline
-	& ptr.\ to ar.\ of imm. val. & @const T(*)[10]@ & @const T (*x)[10];@ & @* [10] const T@ & @* const array(T, 10)@ \\
-	& & @T const (*) [10]}@ & @T const (*x)[10];@ & @* [10] T const@ & @* array(T, 10) const@ \\
-	\hline
-	& ptr.\ to ar.\ of ptr.\ to val. & @T*(*)[10]@ & @T *(*x)[10];@ & @* [10] * T@ & @* array(T * | * T, 10)@ \\
+	$\triangleright$ & ptr.\ to ar.\ of value & @T (*x)[10];@ & @* [10] T x@ & @* array(T, 10) x@ \\
+	\hline
+	& imm. ptr.\ to ar.\ of val. & @T (* const x)[10];@ & @const * [10] T x@ & @const * array(T, 10) x@ \\
+	\hline
+	& ptr.\ to ar.\ of imm. val. & @const T (*x)[10];@ & @* [10] const T x@ & @* const array(T, 10) x@ \\
+	& & @T const (*x)[10];@ & @* [10] T const x@ & @* array(T, 10) const x@ \\
+	\hline
+	& ptr.\ to ar.\ of ptr.\ to val. & @T *(*x)[10];@ & @* [10] * T x@ & @* array(T *, 10) x@ \\
+	& & & & @* array(* T, 10) x@ \\
 	\hline
 \end{tabular}
-\caption{Unfortunate Syntactic Reference for Array vs Pointer.  Includes interaction with constness.}
-\label{bkgd:ar:usr:avp}
-\end{figure}
-
-
-
-
+\end{table}
 
 TODO: Address these parked unfortunate syntaxes