Merge pull request #2551 from modelica/cleanup/nonnormative

Move nonnormative content to separate paragraphs
Since there are lots of commits for different files with relevant commit messages I preferred to not squash.

Author: HansOlsson

Makefile

@@ -6,14 +6,21 @@
 
 all: MLS.pdf MLS.html
 
-clean:
+.PHONY: clean-pdf
+clean-pdf:
 	rm *.aux MLS.log MLS.toc MLS.pdf
-	rm MLS.xml *.html
 
-MLS.pdf: *.tex
+.PHONY: clean-html
+clean-html:
+	rm MLS.xml LaTeXML.cache *.html
+
+.PHONY: clean
+clean: clean-pdf clean-html
+
+MLS.pdf: *.tex chapters/*.tex
 	pdflatex MLS.tex
 
 # Seems to be some issue with graphicpath, so set path here as well
-MLS.html: *.tex
-	$(LATEXMLPREFIX)latexml MLS.tex --path=media --dest MLS.xml
-	$(LATEXMLPREFIX)latexmlpost MLS.xml -format html -pmml --splitat=chapter --splitnaming=labelrelative --javascript=css/LaTeXML-maybeMathJax.js --navigationtoc=context --css=css/LaTeXML-navbar-left.css --dest MLS.html
+%.html: %.tex chapters/*.tex
+	$(LATEXMLPREFIX)latexml $*.tex --path=media --dest $*.xml
+	$(LATEXMLPREFIX)latexmlpost $*.xml -format html -pmml --splitat=chapter --splitnaming=labelrelative --javascript=css/LaTeXML-maybeMathJax.js --navigationtoc=context --css=css/LaTeXML-navbar-left.css --dest $@

chapters/annotations.tex

@@ -7,7 +7,6 @@ \chapter{Modelica DAE Representation}\doublelabel{modelica-dae-representation}
 Modelica simulation model into a ``flat'' set of Modelica
 ``statements'', consisting of the equation and algorithm sections of all
 used components by:
-
 \begin{itemize}
 \item
   expanding all class definitions (flattening the inheritance tree) and
@@ -41,19 +40,19 @@ \chapter{Modelica DAE Representation}\doublelabel{modelica-dae-representation}
 
 \begin{longtable}[]{|p{2cm}|p{12cm}|}
 \hline \endhead
-\textbf{p} & Modelica variables declared as \emph{parameter} or
-\emph{constant}, i.e., variables without any
+\textbf{p} & Modelica variables declared as \lstinline!parameter! or
+\lstinline!constant!, i.e., variables without any
 time-dependency.\\ \hline
-\emph{t} & Modelica variable \emph{time}, the independent (real)
+\emph{t} & Modelica variable \lstinline!time!, the independent (real)
 variable.\\ \hline
-\textbf{x}(t) & Modelica variables of type \emph{Real}, appearing
+\textbf{x}(t) & Modelica variables of type \lstinline!Real!, appearing
 differentiated.\\ \hline
 \textbf{m}(t\textsubscript{e}) & Modelica variables of type
-\emph{discrete Real, Boolean, Integer} which are unknown. These
+\lstinline!discrete Real!, \lstinline!Boolean!, \lstinline!Integer! which are unknown. These
 variables change their value only at event instants t\textsubscript{e}.
 \lstinline!pre(m)! are the values of m immediately before the current event
 occurred.\\ \hline
-\textbf{y}(t) & Modelica variables of type \emph{Real} which do not fall
+\textbf{y}(t) & Modelica variables of type \lstinline!Real! which do not fall
 into any other category (= algebraic variables).\\ \hline
 c\textbf{(}t\textsubscript{e}) & The conditions of all if-expressions
 generated including when-clauses after conversion, see \autoref{when-equations}).\\ \hline
@@ -74,7 +73,6 @@ \chapter{Modelica DAE Representation}\doublelabel{modelica-dae-representation}
 have discontinuities, a variable structure and/or which are controlled
 by a discrete-event system. Such types of systems are called
 \emph{hybrid DAEs}. Simulation is performed in the following way:
-
 \begin{enumerate}
 \item
   The DAE (\ref{eq:dae}) is solved by a numerical integration method. In this
@@ -111,7 +109,6 @@ \chapter{Modelica DAE Representation}\doublelabel{modelica-dae-representation}
 
 At an event instant, including the initial event, the model equations
 are reinitialized according to the following iteration procedure:
-
 \begin{lstlisting}[language=modelica]
     known  variables: x, t, p
     unkown variables: dx/dt, y, m, pre(m), c

chapters/arrays.tex

@@ -212,7 +212,6 @@ \subsection{Connection of 3 stream connectors where two mass flow rates are posi
 the required flow direction should be defined in the connector instance
 with the \lstinline!min! attribute (the \lstinline!max! attribute could be also defined,
 however it does not lead to simplifications):
-
 \begin{lstlisting}[language=modelica]
 model m2
   Fluidport c(m_flow(min=0));

chapters/classes.tex

@@ -18,7 +18,6 @@ \section{Inheritance---Extends Clause}\doublelabel{inheritance-extends-clause}
 The extends-clause is used to specify inheritance from a base class into
 an (enclosing) class containing the extends-clause. The syntax of the
 extends-clause is as follows:
-
 \begin{lstlisting}[language=grammar]
 extends-clause :
    extends name [ class-modification ] [annotation]
@@ -79,12 +78,11 @@ \section{Inheritance---Extends Clause}\doublelabel{inheritance-extends-clause}
 yields an instance with \lstinline!bcomp.b = 3!, which overrides \lstinline!b = 2!.
 \end{nonnormative}
 
-The declaration elements of the flattened base class shall either
-
+The declaration elements of the flattened base class shall either:
 \begin{itemize}
 \item
   Not already exist in the partially flattened enclosing class
-  {[}\emph{i.e., have different names}{]} .
+  (i.e., have different names).
 \item
   The new element is a long form of redeclare or uses the \lstinline!class extends A! syntax, see \autoref{redeclaration}.
 \item
@@ -118,9 +116,11 @@ \section{Inheritance---Extends Clause}\doublelabel{inheritance-extends-clause}
 to equations in the flattened enclosing class are discarded. This
 feature is deprecated, and it is recommend to give a warning when
 discarding them and for the future give a warning about all forms of
-equivalent equations due to inheritance. {[}\emph{Note: equations that
-are mathematically equivalent but not syntactically equivalent are not
-discarded, hence yield an overdetermined system of equations.}{]}
+equivalent equations due to inheritance.
+
+\begin{nonnormative}
+Equations that are mathematically equivalent but not syntactically equivalent are not discarded, hence yield an overdetermined system of equations.
+\end{nonnormative}
 
 \subsection{Multiple Inheritance}\doublelabel{multiple-inheritance}
 
@@ -193,21 +193,28 @@ \subsection{Restrictions on the Kind of Base Class}\doublelabel{restrictions-on-
 
 If a derived class is inherited from another type of specialized class,
 then the result is a specialized class of the derived class type.
-{[}\emph{For example, if a} \lstinline!block! \emph{inherits from a} \lstinline!record! \emph{, then the result
-is a} \lstinline!block!\emph{.}{]}
 
-All specialized classes can be derived from \lstinline!class! {[}\emph{provided the
-resulting class fulfills the restriction of the specialized class. It is
-recommended to use the most specific specialized class.}{]} A \lstinline!class! may
+\begin{nonnormative}
+For example, if a \lstinline!block! inherits from a \lstinline!record!, then the result is a \lstinline!block!.
+\end{nonnormative}
+
+All specialized classes can be derived from \lstinline!class!, provided that the
+resulting class fulfills the restriction of the specialized class.  A \lstinline!class! may
 only contain class-definitions, annotations, and extends-clauses (having
 any other contents is deprecated).
 
+\begin{nonnormative}
+It is recommended to use the most specific specialized class.
+\end{nonnormative}
+
 The specialized classes \lstinline!package!, \lstinline!operator!, \lstinline!function!,
 \lstinline!type,! \lstinline!record!,
-\lstinline!operator record,! and expandable connector can only be derived from their
-own kind {[}\emph{(e.g. a package can only be base class for packages.
-All other kinds of classes can use the import statement to use the
-contents of a package)}{]} and from \lstinline!class!\emph{.}
+\lstinline!operator record!, and \lstinline!expandable connector! can only be derived from their
+own kind and from \lstinline!class!.
+
+\begin{nonnormative}
+E.g. a package can only be base class for packages.  All other kinds of classes can use the import statement to use the contents of a package.
+\end{nonnormative}
 
 \begin{example}
 \begin{lstlisting}[language=modelica]
@@ -237,19 +244,25 @@ \subsection{Restrictions on Base Classes and Constraining Types to be Transitive
 
 The class name used after extends for base-classes and for constraining
 classes must use a class reference considered transitively
-non-replaceable, see definition in \autoref{transitively-non-replaceable}. {[}\emph{This
-formulation excludes the long form of redeclare, i.e.} \lstinline!redeclare model extends M...! \emph{where} \lstinline!M! \emph{must be an inherited replaceable
-class.}{]} For a replaceable component declaration without constraining
+non-replaceable, see definition in \autoref{transitively-non-replaceable}.
+For a replaceable component declaration without constraining
 clause the class must use a class reference considered transitively
-non-replaceable. {[}\emph{This implies that constraining classes are
-always transitively non-replaceable -- both if explicitly given or
-implicitly by the declaration.}{]}
+non-replaceable.
+
+\begin{nonnormative}
+The requirement to use a transitively non-replaceable name excludes the long form of redeclare, i.e. \lstinline!redeclare model extends M...! where
+\lstinline!M! must be an inherited replaceable class.
+\end{nonnormative}
+
+\begin{nonnormative}
+The rule for a replaceable component declaration without constraining clause implies that constraining classes are always transitively non-replaceable --- both
+if explicitly given or implicitly by the declaration.
+\end{nonnormative}
 
 \section{Modifications}\doublelabel{modifications}
 
 There are three kinds of constructs in the Modelica language in which
 modifications can occur:
-
 \begin{itemize}
 \item
   Variable declarations.
@@ -272,14 +285,14 @@ \section{Modifications}\doublelabel{modifications}
 \end{lstlisting}
 \end{example}
 
-A modification (i.e. C1 c1(x = 5) is considered a modification equation,
-if the modified variable is a non-parameter (here: c1.x) variable.
-{[}\emph{This equation is created, if the modified component (here: c1)
-is also created (see \autoref{class-declarations}). In most cases a
-modification equation for a non-parameter variable requires that the
-variable was declared with a declaration equation, see \autoref{balanced-models};
-in those cases the declaration equation is replaced by the
-modification equation.}{]}
+A modification (e.g. \lstinline!C1 c1(x = 5)!) is considered a modification equation,
+if the modified variable (here: \lstinline!c1.x!) is a non-parameter variable.
+
+\begin{nonnormative}
+The modification equation is created, if the modified component (here: \lstinline!c1!) is also created (see \autoref{class-declarations}). In most cases
+a modification equation for a non-parameter variable requires that the variable was declared with a declaration equation, see \autoref{balanced-models};
+in those cases the declaration equation is replaced by the modification equation.
+\end{nonnormative}
 
 A more dramatic change is to modify the \emph{type} and/or the
 \emph{prefixes} and possibly the \emph{dimension sizes} of a declared
@@ -328,8 +341,11 @@ \subsection{Modification Environment}\doublelabel{modification-environment}
 The modification environment contains arguments which modify elements of
 the class (e.g., parameter changes). The modification environment is
 built by merging class modifications, where outer modifications override
-inner modifications. {[}\emph{Note: this should not be confused with}
-\lstinline!inner outer! \emph{prefixes described in \autoref{instance-hierarchy-name-lookup-of-inner-declarations}}{]}
+inner modifications.
+
+\begin{nonnormative}
+This should not be confused with \lstinline!inner outer! prefixes described in \autoref{instance-hierarchy-name-lookup-of-inner-declarations}.
+\end{nonnormative}
 
 \subsection{Merging of Modifications}\doublelabel{merging-of-modifications}
 
@@ -424,7 +440,7 @@ \subsection{Merging of Modifications}\doublelabel{merging-of-modifications}
 A flattening of class \lstinline!C4! will give an object with the following variables:
 \begin{longtable}[]{|@{}l|l@{}|}
 \hline \endhead
-\emph{Variable} & \emph{Default value}\\ \hline
+\tablehead{Variable} & \tablehead{Default value}\\ \hline
 \lstinline!x1! & \lstinline!none!\\ \hline
 \lstinline!x2! & \lstinline!22!\\ \hline
 \lstinline!x3.a! & \lstinline!33!\\ \hline
@@ -482,7 +498,6 @@ \subsection{Single Modification}\doublelabel{single-modification}
 \subsection{Modifiers for Array Elements}\doublelabel{modifiers-for-array-elements}
 
 The following rules apply to modifiers:
-
 \begin{itemize}
 \item
   The \lstinline!each! keyword on a modifier requires that it is applied in an array
@@ -547,10 +562,11 @@ \subsection{Final Element Modification Prevention}\doublelabel{final-element-mod
 An element defined as final by the \lstinline!final! prefix in an element
 modification or declaration cannot be modified by a modification or by a
 redeclaration. All elements of a final element are also final.
-{[}\emph{Setting the value of a parameter in an experiment environment
-is conceptually treated as a modification. This implies that a final
-modification equation of a parameter cannot be changed in a simulation
-environment}{]}.
+
+\begin{nonnormative}
+Setting the value of a parameter in an experiment environment is conceptually treated as a modification.  This implies that a final modification equation
+of a parameter cannot be changed in a simulation environment.
+\end{nonnormative}
 
 \begin{example}
 \begin{lstlisting}[language=modelica]
@@ -605,7 +621,6 @@ \section{Redeclaration}\doublelabel{redeclaration}
 preserved.
 
 The groups that are valid for both classes and components:
-
 \begin{itemize}
 \item
   public, protected
@@ -616,7 +631,6 @@ \section{Redeclaration}\doublelabel{redeclaration}
 \end{itemize}
 
 The groups that are only valid for components:
-
 \begin{itemize}
 \item
   flow, stream
@@ -675,23 +689,25 @@ \subsection{The class extends Redeclaration Mechanism}\doublelabel{the-class-ext
 where \lstinline!class! as usual can be replaced by any other specialized class,
 replaces the inherited class \lstinline!B! with another declaration that extends the
 inherited class where the optional class-modification is applied to the
-inherited class. {[}\emph{Since this implies that all declarations are
-inherited with modifications applied there is no need to apply modifiers
-to the new declaration.}{]} Inherited B here means that the class
-containing \lstinline!redeclare class extends! B(\ldots{}) should also inherit
-another declaration of B from one of its extends-clauses. The new
+inherited class.  Inherited \lstinline!B! here means that the class
+containing \lstinline!redeclare class extends B(...)! should also inherit
+another declaration of \lstinline!B! from one of its extends-clauses. The new
 declaration should explicitly include redeclare.
 
+\begin{nonnormative}
+Since the rule about applying the optional class-modification implies that all declarations are inherited with modifications applied, there is no need
+to apply modifiers to the new declaration.
+\end{nonnormative}
+
 For \lstinline!redeclare class extends B(...)! the inherited class is subject
 to the same restrictions as a redeclare of the inherited element, and
-the original class B should be replaceable, and the new element is only
+the original class \lstinline!B! should be replaceable, and the new element is only
 replaceable if the new definition is replaceable. In contrast to normal
-extends it is not subject to the restriction that B should be
-transitively non-replaceable (since B should be replaceable).
+extends it is not subject to the restriction that \lstinline!B! should be
+transitively non-replaceable (since \lstinline!B! should be replaceable).
 
 The syntax rule for \lstinline!class extends! construct is in the definition of the
 \lstinline!class-specifier! nonterminal (see also class declarations in \autoref{class-declarations}):
-
 \begin{lstlisting}[language=grammar]
 class-definition :
    [ encapsulated ] class-prefixes
@@ -842,7 +858,6 @@ \subsection{Constraining Type}\doublelabel{constraining-type}
 
 If the \lstinline!constraining-clause! is not present in the original declaration
 (i.e., the non-redeclared declaration):
-
 \begin{itemize}
 \item
   The type of the declaration is also used as a constraining type.
@@ -984,9 +999,11 @@ \subsubsection{Constraining-clause annotations}\doublelabel{constraining-clause-
 
 Description and annotations on the constraining-clause are applied to
 the entire declaration, and it is an error if they also appear on the
-definition. \emph{{[}The intent is that the description and/or
-annotation are at the end of the declaration, but it is not
-straightforward to specify this in the grammar.{]}}
+definition.
+
+\begin{nonnormative}
+The intent is that the description and/or annotation are at the end of the declaration, but it is not straightforward to specify this in the grammar.
+\end{nonnormative}
 
 \begin{example}
 \begin{lstlisting}[language=modelica]
@@ -1006,27 +1023,27 @@ \subsection{Restrictions on Redeclarations}\doublelabel{restrictions-on-redeclar
 
 The following additional constraints apply to redeclarations (after
 prefixes are inherited, \autoref{redeclaration}):
-
-Only classes and components declared as replaceable can be redeclared
-with a new type {[}\emph{redeclaration with the same type can be used to
-restrict variability and/or change array dimensions}{]}, which must have
-an interface compatible with the constraining interface of the original
-declaration, and to allow further redeclarations one must use
-\lstinline!redeclare replaceable!.
-
 \begin{itemize}
 \item
-  an element declared as constant cannot be redeclared
+  Only classes and components declared as replaceable can be redeclared with a new type, which must have an interface compatible with the constraining
+  interface of the original declaration, and to allow further redeclarations one must use \lstinline!redeclare replaceable!.
+  \begin{nonnormative}
+  Redeclaration with the same type can be used to restrict variability and/or change array dimensions.
+  \end{nonnormative}
+\item
+  An element declared as constant cannot be redeclared
 \item
-  an element declared as final may not be modified, and thus not
+  An element declared as final may not be modified, and thus not
   redeclared
 \item
   Modelica does not allow a protected element to be redeclared as
   public, or a public element to be redeclared as protected.
 \item
   Array dimensions may be redeclared; provided the sub-typing rules in
-  \autoref{interface-compatibility-or-subtyping} are satisfied. {[}\emph{This is one example of redeclare of
-  non-replaceable elements.}{]}
+  \autoref{interface-compatibility-or-subtyping} are satisfied.
+  \begin{nonnormative}
+  This is one example of redeclare of non-replaceable elements.
+  \end{nonnormative}
 \end{itemize}
 
 \subsection{Annotation Choices for Suggested Redeclarations and Modifications}\doublelabel{annotation-choices-for-suggested-redeclarations-and-modifications}