Merge pull request #2884 from henrikt-ma/cleanup/style-guide

Add specification document style guide

README.md

@@ -43,6 +43,7 @@ A list of MCPs can be found here: [RationaleMCP](https://github.com/modelica/Mod
 CLA: Contributor's license agreement. (Details to follow.)
 
 How to edit and generate final documents
+* Read the [style guide](styleguide.md).
 * For online editing you can use www.overleaf.com (details to follow)
 * The pdf-documents are generated with pdflatex, which is part of most LaTeX installations, we used http://miktex.org/download
 * The HTML-documents are generated with LaTeXML. That is more complicated to install - and can optionally be skipped:

chapters/annotations.tex

@@ -190,7 +190,7 @@ \subsubsection{Plot Curves}\label{plot-curves}
 
 The mandatory \lstinline!x! and \lstinline!y! expressions are restricted to be component references referring to a scalar variable or \lstinline!time!.
 It is an error if \lstinline!x! or \lstinline!y! does not designate a scalar variable.
-When the \lstinline!unit! of an \lstinline!Axis! is non-empty, it is an error if the unit of the corresponding \lstinline!Curve! expression (i.e., a variable's \lstinline!unit!, or second for \lstinline!time!) is incompatible with the axis unit.
+When the \lstinline!unit! of an \lstinline!Axis! is non-empty, it is an error if the unit of the corresponding \lstinline!x! or \lstinline!y! expression (i.e., a variable's \lstinline!unit!, or second for \lstinline!time!) is incompatible with the axis unit.
 
 When \lstinline!legend! isn't provided, the tool produces a default based on \lstinline!x! and/or \lstinline!y!.
 Providing the empty string as \lstinline!legend! means that the curve shall be omitted from the plot legend.
@@ -1090,13 +1090,10 @@ \subsubsection{Bitmap}\label{bitmap}
 
 \subsection{Variable Graphics and Schematic Animation}\label{variable-graphics-and-schematic-animation}
 
-Any value (coordinates, color, text, etc.) in graphical annotations can
-be dependent on class variables using the \lstinline!DynamicSelect! expression.
-\lstinline!DynamicSelect! has the syntax of a function call with two arguments,
-where the first argument specifies the value of the editing state and
-the second argument the value of the non-editing state. The first
-argument must be a literal expression. The second argument may contain
-references to variables to enable a dynamic behavior.
+Any value (coordinates, color, text, etc.) in graphical annotations can be dependent on class variables using \lstinline!DynamicSelect!.
+\lstinline!DynamicSelect! has the syntax of a function call with two arguments, where the first argument specifies the value of the editing state and the second argument the value of the non-editing state.
+The first argument must be a literal expression.
+The second argument may contain references to variables to enable a dynamic behavior.
 
 \begin{example}
 The level of a tank could be animated by a rectangle expanding in vertical direction and its color depending on a variable overflow:

chapters/arrays.tex

@@ -577,11 +577,9 @@ \subsubsection{Reduction Expressions}\label{reduction-expressions}
 function-name "(" expression1 for iterators ")"
 \end{lstlisting}%
 \index{for@\robustinline{for}!reduction expression}
-
-is a reduction-expression. The expressions in the iterators of a
-reduction-expression shall be vector expressions. They are evaluated
-once for each reduction-expression, and are evaluated in the scope
-immediately enclosing the reduction-expression.
+is a \firstuse{reduction expression}\index{reduction expression}.
+The expressions in the iterators of a reduction expression shall be vector expressions.
+They are evaluated once for each reduction expression, and are evaluated in the scope immediately enclosing the reduction expression.
 
 For an iterator:
 \begin{lstlisting}[language=grammar]

chapters/classes.tex

@@ -685,9 +685,7 @@ \subsection{Short Class Definitions}\label{short-class-definitions}
 \end{lstlisting}
 \end{example}
 
-If a short class definition inherits from a partial class the new class
-definition will be partial, regardless of whether it is declared with
-the keyword partial or not.
+If a short class definition inherits from a partial class the new class definition will be partial, regardless of whether it is declared with the prefix \lstinline!partial! or not.
 
 \begin{example}
 \begin{lstlisting}[language=modelica]

chapters/inheritance.tex

@@ -468,14 +468,11 @@ \subsection{Modifiers for Array Elements}\label{modifiers-for-array-elements}
 \item
   The \lstinline!each!\indexinline{each} keyword on a modifier requires that it is applied in an array declaration/modification, and the modifier is applied individually to each element of the enclosing array (with regard to the position of \lstinline!each!).
   In case of nested modifiers this implies it is applied individually to each element of each element of the enclosing array; see example.
-  If the modified element is a vector and the modifier does not contain the \lstinline!each!-prefix, the modification is split such that the first element in the vector is applied to the first element of the vector of elements, the second to the second element, until the last element of the vector-expression is applied to the last element of the array; it is an error if these sizes do not match.
+  If the modified element is a vector and the modifier does not contain the \lstinline!each! prefix, the modification is split such that the first element in the vector is applied to the first element of the vector of elements, the second to the second element, until the last element of the vector-expression is applied to the last element of the array; it is an error if these sizes do not match.
   Matrices and general arrays of elements are treated by viewing those as vectors of vectors etc.
 \item
-  If a nested modifier is split, the split is propagated to all elements
-  of the nested modifier, and if they are modified by the \lstinline!each!-keyword
-  the split is inhibited for those elements. If the nested modifier that
-  is split in this way contains re-declarations that are split it is
-  illegal.
+  If a nested modifier is split, the split is propagated to all elements of the nested modifier, and if they are modified by the \lstinline!each! keyword the split is inhibited for those elements.
+  If the nested modifier that is split in this way contains re-declarations that are split, it is illegal.
 \end{itemize}
 
 \begin{example}

chapters/packages.tex

@@ -216,8 +216,8 @@ \section{Mapping Package/Class Structures to a Hierarchical File System}\label{m
 
 \subsection{Mapping a Package/Class Hierarchy into a Directory Hierarchy (Structured Entity)}\label{mapping-a-package-class-hierarchy-into-a-directory-hierarchy-structured-entity}
 
-A directory shall contain a node, the file \filename{package.mo}. The node shall contain a stored-definition that defines a class \lstinline!A! with a name
-matching the name of the structured entity.
+A directory shall contain a node, the file \filename{package.mo}.
+The node shall contain a \lstinline[language=grammar]!stored-definition! that defines a class \lstinline!A! with a name matching the name of the structured entity.
 
 \begin{nonnormative}
 The node typically contains documentation and graphical information for a package, but may also contain additional elements of the class \lstinline!A!.

chapters/revisions.tex

@@ -394,15 +394,14 @@ \subsection{Main changes in Modelica 3.5}\label{main-changes-in-modelica-3-5}
 \item Clarified illegal modification of outer element, \cref{instance-hierarchy-name-lookup-of-inner-declarations}.
 Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/2283}{\#2283}.
 
-
-
 \if0
 \item xxx, \cref{xxx}.
 Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/}{\#}.
 \item xxx, \cref{xxx}.
 Ticket \href{https://github.com/modelica/ModelicaSpecification/pull/}{\#}.
 \fi
 \end{itemize}
+
 \section{Modelica 3.4}\label{modelica-3-4}
 Modelica 3.4 was released April 10, 2017. The Modelica 3.4 specification
 was edited by Hans Olsson.

chapters/statements.tex

@@ -224,7 +224,10 @@ \subsection{For-statement}\label{for-statement}
 
 \subsubsection{Implicit Iteration Ranges}\label{implicit-iteration-ranges}
 
-An iterator \lstinline!IDENT in range-expr! without the \lstinline!in range-expr! requires that the \lstinline!IDENT! appears as the subscript of one or several subscripted expressions, where the expressions are not part of an array in a component of an expandable connector.  The dimension size of the array expression in the indexed position is used to deduce the \lstinline!range-expr! as \lstinline!1:size(array-expression,indexpos)! if the indices are a subtype of \lstinline!Integer!, or as \lstinline!E.e1:E.en! if the indices are of an enumeration type \lstinline!E = enumeration(e1, $\ldots$, en)!, or as \lstinline!false:true! if the indices are of type \lstinline!Boolean!.  If it is used to subscript several expressions, their ranges must be identical.  The \lstinline!IDENT! may also, inside a reduction-expression, array constructor expression, for-statement, or for-equation, occur freely outside of subscript positions, but only as a reference to the variable \lstinline!IDENT!, and not for deducing ranges.
+An iterator \lstinline!IDENT in range-expr! without the \lstinline!in range-expr! requires that the \lstinline!IDENT! appears as the subscript of one or several subscripted expressions, where the expressions are not part of an array in a component of an expandable connector.
+The dimension size of the array expression in the indexed position is used to deduce the \lstinline!range-expr! as \lstinline!1:size(array-expression,indexpos)! if the indices are a subtype of \lstinline!Integer!, or as \lstinline!E.e1:E.en! if the indices are of an enumeration type \lstinline!E = enumeration(e1, $\ldots$, en)!, or as \lstinline!false:true! if the indices are of type \lstinline!Boolean!.
+If it is used to subscript several expressions, their ranges must be identical.
+The \lstinline!IDENT! may also, inside a reduction expression, array constructor expression, for-statement, or for-equation, occur freely outside of subscript positions, but only as a reference to the variable \lstinline!IDENT!, and not for deducing ranges.
 
 The \lstinline!IDENT! may also be used as a subscript for an array in a component of an expandable connector
 but it is only seen as a reference to the variable \lstinline!IDENT! and cannot be used for deducing ranges.
@@ -276,13 +279,9 @@ \subsubsection{Types as Iteration Ranges}\label{types-as-iteration-ranges}
 
 \subsubsection{Nested For-Loops and Reduction Expressions with Multiple Iterators}\label{nested-for-loops-and-reduction-expressions-with-multiple-iterators}
 
-The notation with several iterators is a shorthand notation for nested
-for-statements or for-equations (or reduction-expressions). For
-for-statements or for-equations it can be expanded into the usual form
-by replacing each `\lstinline!,!' by ``\lstinline!loop for!'' and adding extra ``\lstinline!end for!''. For
-reduction-expressions it can be expanded into the usual form by
-replacing each `\lstinline!,!' by ``\lstinline!) for!'' and prepending the reduction-expression
-with ``\lstinline!functionName(!''.
+The notation with several iterators is a shorthand notation for nested for-statements or for-equations (or reduction expressions).
+For for-statements or for-equations it can be expanded into the usual form by replacing each `\lstinline!,!' by ``\lstinline!loop for!'' and adding extra ``\lstinline!end for!''.
+For reduction expressions it can be expanded into the usual form by replacing each `\lstinline!,!' by ``\lstinline!) for!'' and prepending the reduction expression with ``\lstinline!functionName(!''.
 
 \begin{example}
 \begin{lstlisting}[language=modelica]

preamble.tex

@@ -223,8 +223,6 @@
 % Formatting of table headings.
 \newcommand{\tablehead}[1]{\textit{#1}}
 
-\newcommand{\glossaryitem}[1]{\textbf{#1}}
-
 % Environment for definitions.
 \usepackage{amsthm}
 \newtheoremstyle{mlsdefinition}