Clean up non-normative content in annotations.tex

chapters/arrays.tex

@@ -8,22 +8,25 @@ \chapter{Arrays}\doublelabel{arrays}
 Each array has a certain dimensionality, i.e., number of dimensions. The
 degenerate case of a scalar variable is not really an array, but can be
 regarded as an array with zero dimensions. Vectors have one dimension,
-matrices have two dimensions, etc. {[}\emph{So-called row vectors and
-column vectors do not exist in Modelica and cannot be distinguished
-since vectors have only one dimension. If distinguishing these is
-desired, row matrices and column matrices are available, being the
-corresponding two-dimensional entities. However, in practice this is
-seldom needed since the usual matrix arithmetic and linear algebra
-operations have been defined to give the expected behavior when
-operating on Modelica vectors and matrices.}{]}
+matrices have two dimensions, etc.
+
+\begin{nonnormative}
+So-called row vectors and column vectors do not exist in Modelica and cannot be distinguished since vectors have only one
+dimension.  If distinguishing these is desired, row matrices and column matrices are available, being the corresponding
+two-dimensional entities.  However, in practice this is seldom needed since the usual matrix arithmetic and linear algebra
+operations have been defined to give the expected behavior when operating on Modelica vectors and matrices.
+\end{nonnormative}
 
 Modelica is a strongly typed language, which also applies to array
 types. The number of dimensions of an array is fixed and cannot be
-changed at run-time {[}\emph{in order to permit strong type checking and
-efficient implementation.}{]} However, the sizes of array dimensions can
-be computed at run-time, {[}\emph{allowing fairly generic array
-manipulation code to be written as well as interfacing to standard
-numeric libraries implemented in other programming languages}.{]}
+changed at run-time. However, the sizes of array dimensions can
+be computed at run-time.
+
+\begin{nonnormative}
+The fixed number of array dimensions permits strong type checking and efficient implementation.  The non-fixed sizes of array
+dimensions on the other hand, allow fairly generic array manipulation code to be written as well as interfacing to standard
+numeric libraries implemented in other programming languages.
+\end{nonnormative}
 
 An array is allocated by declaring an array variable or calling an array
 constructor. Elements of an array can be indexed by \lstinline!Integer!, \lstinline!Boolean!, or
@@ -33,18 +36,20 @@ \section{Array Declarations}\doublelabel{array-declarations}
 
 The Modelica type system includes scalar number, vector, matrix (number
 of dimensions, ndim=2), and arrays of more than two dimensions.
-{[}\emph{There is no distinguishing between a row and column vector}.{]}
+
+\begin{nonnormative}
+There is no distinguishing between a row and column vector.
+\end{nonnormative}
 
 The following table shows the two possible forms of declarations and
 defines the terminology. C is a placeholder for any class, including the
-built-in type classes Real, Integer, Boolean, String, and enumeration
+built-in type classes \lstinline!Real!, \lstinline!Integer!, \lstinline!Boolean!, \lstinline!String!, and enumeration
 types. The type of a dimension upper bound expression, e.g. n, m, p,...
-in the table below, need to be a subtype of Integer or EB for a class EB
-that is an enumeration type or subtype of the Boolean type.
+in the table below, need to be a subtype of \lstinline!Integer! or EB for a class EB
+that is an enumeration type or subtype of the \lstinline!Boolean! type.
 
-Colon (:)
-indicates that the dimension upper bound is unknown and is a subtype of
-Integer. The size of such a variable can be determined from its binding equation, or the size
+Colon (:) indicates that the dimension upper bound is unknown and is a subtype of
+\lstinline!Integer!. The size of such a variable can be determined from its binding equation, or the size
 of any of its array attributes - see also \autoref{flexible-array-sizes-and-resizing-of-arrays-in-functions}.
 The size cannot be determined from other equations or algorithm.
 
@@ -80,45 +85,41 @@ \section{Array Declarations}\doublelabel{array-declarations}
 ($k \geq 0$).\\ \hline
 \end{longtable}
 
-{[}\emph{The number of dimensions and the dimensions sizes are part of
+\begin{example}
+The number of dimensions and the dimensions sizes are part of
 the type, and shall be checked for example at redeclarations.
 Declaration form 1 displays clearly the type of an array, whereas
 declaration form 2 is the traditional way of array declarations in
-languages such as Fortran, C, C++.}
+languages such as Fortran, C, C++.
 
 \begin{lstlisting}[language=modelica]
   Real[:] v1, v2 // vectors v1 and v2 have unknown sizes. The actual sizes may be different.
 \end{lstlisting}
-
-\emph{It is possible to mix the two declaration forms although it might
-be confusing.}
-
+It is possible to mix the two declaration forms although it might be confusing.
 \begin{lstlisting}[language=modelica]
   Real[3,2] x[4,5]; // x has type Real[4,5,3,2];
 \end{lstlisting}
-\emph{The reason for this order is given by examples such as:}
-
+The reason for this order is given by examples such as:
 \begin{lstlisting}[language=modelica]
   type R3=Real[3];
   R3 a;
   R3 b[1]={a};
   Real[3] c[1]=b;
 \end{lstlisting}
-\emph{Using a type for \lstinline!a! and \lstinline!b! in this way is normal, and
-substituting a type by its definition allow \lstinline!c!.}
-
-\emph{A vector \lstinline!y! indexed by enumeration values}
+Using a type for \lstinline!a! and \lstinline!b! in this way is normal, and
+substituting a type by its definition allow \lstinline!c!.
 
+A vector \lstinline!y! indexed by enumeration values
 \begin{lstlisting}[language=modelica]
   type TwoEnums = enumeration(one,two);
   Real[TwoEnums] y;
 \end{lstlisting}
-{]}
+\end{example}
 
-Zero-valued dimensions are allowed, so: \lstinline!C x[0];! declares an empty
-  vector and: \lstinline!C x[0,3]!; an empty matrix.
-{[}\emph{Special cases}:
+Zero-valued dimensions are allowed, so: \lstinline!C x[0];! declares an empty vector and: \lstinline!C x[0,3]!; an empty matrix.
 
+\begin{nonnormative}
+Special cases:
 \begin{longtable}{|l|l|l|l|p{3cm}|}
 \caption{Declaration of arrays as 1-vectors, row-vectors, or
 column-vectors of arrays.}\\
@@ -131,8 +132,7 @@ \section{Array Declarations}\doublelabel{array-declarations}
 C{[}n,1{]} x; & C x{[}n, 1{]}; & 2 & Matrix & n x 1 -- Matrix, representing a column\\ \hline
 C{[}1,n{]} x; & C x{[}1, n{]}; & 2 & Matrix & 1 x n -- Matrix, representing a row\\ \hline
 \end{longtable}
-
-{]}
+\end{nonnormative}
 
 The type of an array of array is the multidimensional array which is
 constructed by taking the first dimensions from the component
@@ -537,7 +537,6 @@ \section{Vector, Matrix and Array Constructors}\doublelabel{vector-matrix-and-ar
 
 The constructor function \lstinline!array(A,B,C,...)! constructs an array from its
 arguments according to the following rules:
-
 \begin{itemize}
 \item
   Size matching: All arguments must have the same sizes, i.e.,
@@ -796,11 +795,8 @@ \section{Array Indexing}\doublelabel{array-indexing}
 The array indexing operator \emph{name}\lstinline![!\emph{...}\lstinline!]! is used to
 access array elements for retrieval of their values or for updating
 these values. An indexing operation is subject to upper and lower array
-dimension index bounds (\autoref{array-dimension-lower-and-upper-index-bounds}). {[}\emph{An indexing operation
-is assumed to take constant time, i.e., largely independent of the size
-of the array.}{]} The indexing operator takes two or more operands,
-where the first operand is the array to be indexed and the rest of the
-operands are index expressions:
+dimension index bounds (\autoref{array-dimension-lower-and-upper-index-bounds}).  The indexing operator takes two or more
+operands, where the first operand is the array to be indexed and the rest of the operands are index expressions:
 
 arrayname{[}\emph{indexexpr1}, \emph{indexexpr2}, ...{]}
 
@@ -818,6 +814,10 @@ \section{Array Indexing}\doublelabel{array-indexing}
 side and the index on the left-hand side are evaluated before any
 element is assigned a new value.
 
+\begin{nonnormative}
+An indexing operation is assumed to take constant time, i.e., largely independent of the size of the array.
+\end{nonnormative}
+
 \begin{example}
 \begin{lstlisting}[language=modelica, escapechar=!]
   a[:, j] !\emph{is a vector of the j-th column of a,}!