Non normative start

chapters/annotations.tex

@@ -4,9 +4,7 @@ \chapter{Annotations}\label{annotations}
 Annotations are intended for storing extra information about a model,
 such as graphics, documentation or versioning, etc. A Modelica tool is
 free to define and use other annotations, in addition to those defined
-here, according to \cref{vendor-specific-annotations}. The only requirement is that any tool
-shall save files with all annotations from this chapter and all
-vendor-specific annotations intact. To ensure this, annotations must be
+here, according to \cref{vendor-specific-annotations}. Annotations must be
 represented with constructs according to the Modelica grammar (for
 replaceable class declarations with a constraining-clause also refer to
 \cref{constraining-clause-annotations}). The specification in this document defines the
@@ -16,7 +14,9 @@ \section{Vendor-Specific Annotations}\label{vendor-specific-annotations}
 
 A vendor may -- anywhere inside an annotation -- add specific, possibly
 undocumented, annotations which are not intended to be interpreted by
-other tools. Two variants of vendor-specific annotations exist; one
+other tools. The only requirement is that any tool
+shall save files with all vendor-specific annotations (and all annotations from this chapter) intact.
+Two variants of vendor-specific annotations exist; one
 simple and one hierarchical. Double underscore concatenated with a
 vendor name as initial characters of the identifier are used to identify
 vendor-specific annotations.

chapters/arrays.tex

@@ -10,23 +10,20 @@ \chapter{Arrays}\label{arrays}
 regarded as an array with zero dimensions. Vectors have one dimension,
 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. 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

chapters/connectors.tex

@@ -2,8 +2,8 @@ \chapter{Connectors and Connections}\label{connectors-and-connections}
 
 This chapter covers connectors, connect-equations, and connections.
 
-The special functions \lstinline!cardinality!, \lstinline!rooted! (deprecated),
-\lstinline!Connections.isRoot!, and \lstinline!Connections.rooted! may not be used to control them.
+Connectors and connect-equations are designed so that different components can be connected graphically
+with well-defined semantics. However, the graphical part is optional and found in \cref{annotations}.
 
 \section{Connect-Equations and Connectors}\label{connect-equations-and-connectors}
 

chapters/interface.tex

@@ -11,6 +11,7 @@ \chapter{Interface or Type Relationships}\label{interface-or-type-relationships}
 (\cref{interface-compatibility-or-subtyping} and \cref{plug-compatibility-or-restricted-subtyping}) between ''interfaces'' (\cref{the-concepts-of-type-interface-and-subtype}); this can
 also be viewed as sub-typing (\cref{the-concepts-of-type-interface-and-subtype}).
 
+\section{Interface Terminology}\label{interface-terminology}
 In this chapter, two kinds of terminology is used for identical concepts
 to get better understanding (e.g.\ by both engineers and computer
 scientists). A short summary of the terms is given in the following

chapters/operatorsandexpressions.tex

@@ -86,6 +86,7 @@ \section{Operator Precedence and Associativity}\label{operator-precedence-and-as
 conditional & \lstinline!if $\mathit{expr}$ then $\mathit{expr}$ else $\mathit{expr}$! & \lstinline!if b then 3 else x!\\ \hline
 named argument & \lstinline!$\mathit{ident}$ = $\mathit{expr}$! & \lstinline!x = 2.26!\\ \hline
 \end{tabular}
+\label{tab:operator-precedence}
 \end{table}
 
 The conditional operator may also include elseif-clauses. Equality \lstinline!=! and

chapters/overloaded.tex

@@ -1,38 +1,35 @@
 \chapter{Overloaded Operators}\label{overloaded-operators}
 
-A Modelica \lstinline!operator record! can define the behavior for
-operations such as constructing, adding, multiplying etc. This is done
-using the specialized class \lstinline!operator! (a restricted class
-similar to \lstinline!package!, see \cref{specialized-classes}) comprised of functions
-implementing different variants of the operation for the record class in
-which the respective \lstinline!operator! definition resides.
+A Modelica \lstinline!operator record! can overload the behavior for
+operations such as constructing, adding, multiplying etc.
 
-\begin{nonnormative}
-The overloading is defined in such a way that ambiguities are not allowed and give an error.  Furthermore, it is sufficient to define overloading for scalars.
+The overloading is defined in such a way that ambiguities are not allowed and give an error.
+Furthermore, it is sufficient to define overloading for scalars.
 Overloaded array operations are automatically deduced from the overloaded scalar operations.
-\end{nonnormative}
 
-The \lstinline!operator! keyword is followed by the name of the operation:
+\section{Overview of overloaded operators}\label{overview-of-overloaded-operators}
+In an \lstinline!operator record! the definition of operations are done using the specialized class \lstinline!operator!
+(a restricted class similar to \lstinline!package!, see \cref{specialized-classes})
+followed by the name of the operation. Each \lstinline!operator! class is
+comprised of functions
+implementing different variants of the operation for the \lstinline!operator record! class in
+which the definition resides.
 % This was something weird that could be seen as a table originally,
 % that is somewhat awkward - but keeping it.
 %
 % Changing to use itemize was attempted, but currently fails in LaTeXML
 % https://github.com/brucemiller/LaTeXML/issues/1057
 % (Note: It's pure coincide that this issue occured for this case.)
-\begin{longtable}[c]{@{}|ll|@{}}
-\hline\endhead
-\multicolumn{2}{|l|}{Overloaded constructors, see \cref{overloaded-constructors}:}\\
-& \lstinline!'constructor'!, \lstinline!'0'!\\
-\multicolumn{2}{|l|}{Overloaded string conversions, see \cref{overloaded-string-conversions}:}\\
-& \lstinline!'String'! \\
-\multicolumn{2}{|l|}{Overloaded binary operations, see \cref{overloaded-binary-operations}:}\\
-& \lstinline!'+'!, \lstinline!'-'! (subtraction), \lstinline!'*'!, \lstinline!'/'!, \lstinline!'^'!,\\
-& \lstinline!'=='!, \lstinline!'<='!', \lstinline!'>'!, \lstinline!'<'!,
-\lstinline!'>='!, \lstinline!'<='!, \lstinline!'and'!, \lstinline!'or'!\\
-\multicolumn{2}{|l|}{Overloaded unary operations, see \cref{overloaded-unary-operations}:}\\
-& \lstinline!'-'! (negation), \lstinline!'not'!\\
-\hline
-\end{longtable}
+\begin{itemize}
+\item Overloaded constructors, see \cref{overloaded-constructors}:\\ \lstinline!'constructor'!, \lstinline!'0'!
+\item Overloaded string conversions, see \cref{overloaded-string-conversions}:\\ \lstinline!'String'!
+\item Overloaded binary operations, see \cref{overloaded-binary-operations}:\\
+\lstinline!'+'!, \lstinline!'-'! (subtraction), \lstinline!'*'!, \lstinline!'/'!, \lstinline!'^'!,\\
+ \lstinline!'=='!, \lstinline!'<='!', \lstinline!'>'!, \lstinline!'<'!,
+\lstinline!'>='!, \lstinline!'<='!, \lstinline!'and'!, \lstinline!'or'!
+\item Overloaded unary operations, see \cref{overloaded-unary-operations}:\\
+\lstinline!'-'! (negation), \lstinline!'not'!
+\end{itemize}
 
 The functions defined in the operator-class must take at least one
 component of the record class as input, except for the
@@ -56,7 +53,7 @@ \chapter{Overloaded Operators}\label{overloaded-operators}
 defined in its base class, for subtyping see \cref{interface-or-type-relationships}.
 
 The precedence and associativity of the overloaded operators is
-identical to the one defined in Table 3.1 in \cref{operator-precedence-and-associativity}.
+identical to the one defined in \cref{tab:operator-precedence} in \cref{operator-precedence-and-associativity}.
 
 \begin{nonnormative}
 Note, the operator overloading as defined in this section is