modelica · HansOlsson · Dec 1, 2021 · Nov 22, 2021 · Nov 22, 2021 · Nov 22, 2021
diff --git a/chapters/annotations.tex b/chapters/annotations.tex
@@ -55,7 +55,10 @@ \subsection{Class Description and Revision History}\label{annotation-info-revisi
 The \lstinline!revisions! documentation may be omitted in printed documentation.
 \end{nonnormative}
 
-If the string starts with the tag \lstinline!<html>! or \lstinline!<HTML>! the entire string is HTML encoded (and is assumed to end with \lstinline!</html>! or \lstinline!</HTML>! and shall be rendered as HTML even if the end-tags are missing), otherwise the entire string is rendered as is.  The HTML encoded content may contain links.  For external links, see \cref{external-resources}.  Links to Modelica classes may be defined with the HTML link command using scheme \lstinline!Modelica! (using its lower case form in the URI, see \cref{external-resources}), e.g.,
+If the string starts with the tag \lstinline!<html>! or \lstinline!<HTML>! the entire string is HTML encoded (and is assumed to end with \lstinline!</html>! or \lstinline!</HTML>! and shall be rendered as HTML even if the end-tags are missing), otherwise the entire string is rendered as is.
+The HTML encoded content may contain links.
+For external links, see \cref{external-resources}.
+Links to Modelica classes may be defined with the HTML link command using scheme \lstinline!Modelica! (using its lower case form in the URI, see \cref{external-resources}), e.g.,
 \begin{lstlisting}[language=modelica]
 <a href="modelica://MultiBody.Tutorial">MultiBody.Tutorial</a>
 \end{lstlisting}

diff --git a/chapters/introduction.tex b/chapters/introduction.tex
@@ -12,6 +12,7 @@ \section{Scope of the Specification}\label{scope-of-the-specification}
 The semantics of the Modelica language is specified by means of a set of
 rules for translating any class described in the Modelica language to a
 flat Modelica structure.
+The semantic specification should be read together with the Modelica grammar.
 
 A class (of specialized class \lstinline!model!, \lstinline!class! or \lstinline!block!) intended to be simulated on its own is called a \firstuse{simulation model}.
 
@@ -75,8 +76,6 @@ \section{Scope of the Specification}\label{scope-of-the-specification}
 
 \section{Some Definitions}\label{some-definitions}
 
-The semantic specification should be read together with the Modelica grammar.
-Non-normative text, i.e., examples and comments, are enclosed in {[}\ldots{]} and set in italics.
 Explanations of many terms can be found using the document index in \cref{document-index}.
 Some important terms are defined below.
 
@@ -99,14 +98,61 @@ \section{Some Definitions}\label{some-definitions}
 % - quality of implementation
 % - simulator
 
-\section{Notation and Grammar}\label{notation-and-grammar}
+\section{Notation}\label{notation}
+
+The remainder of this section shows examples of the presentation used in this document.
 
-The meta symbols (of the extended BNF-grammar) are defined in~\cref{lexical-conventions}.
+Syntax highlighting of Modelica code is illustrated by the code listing below.
+Things to note include keywords that define code structure such as \lstinline!equation!, keywords that do not define code structure such as \lstinline!connect!, and recognized identifiers with meaning defined by the specification such as \lstinline!semiLinear!:
+\begin{lstlisting}[language=modelica]
+model Example "Example used to illustrate syntax highlighting"
+  /* The string above is a class description string, this is a comment. */
+  /* Invalid code is typically presented like this: */
+  String s = 1.0; // Error: No conversion form Real to String.
+  Real x;
+equation
+  2 * x = semiLinear(time - 0.5, 2, 3);
+  /* The annotation below has omitted details represented by an ellipsis: */
+  connect(resistor.n, conductor.p) annotation($\ldots$);
+end Example;
+\end{lstlisting}
 
-Boldface denotes keywords of the Modelica language. Keywords are
-reserved words and shall not be used as identifiers, with the exception of
-\lstinline!initial! which is a keyword in section headings, and \lstinline!der! which is a
-keyword for declaration functions, but it is also possible to call the
-functions \lstinline!initial! and \lstinline!der!.
+Relying on implicit conversion of \lstinline!Integer! literals to \lstinline!Real! is common, as seen in the equation above (note use of Modelica code appearing inline in the text).
+
+It is common to mix Modelica code with mathematical notation.
+For example, \lstinline!average($x$, $y$)! could be defined as $\frac{x + y}{2}$.
+
+\begin{definition}[Something]% Do not add this one to the index!
+Text defining the meaning of \emph{something}.
+\end{definition}
 
-See \cref{modelica-concrete-syntax} for a full lexical specification and grammar.
+In addition to the style of definition above, new terminology can be introduced in the running text.
+% TODO: Switch to \firstuse[---]{dummy} below.  For now, using \willintroduce to avoid risk of accidentally
+% creating index entry in the future.
+For example, a \willintroduce{dummy} is something that\ldots
+
+\begin{nonnormative}
+This is non-normative content that provides some explanation, motivation, and/or additional things to keep in mind.
+It has no defining power and may be skipped by readers strictly interested in just the definition of the Modelica language.
+\end{nonnormative}
+
+\begin{example}
+This is an example, which is a special kind of non-normative content.
+Examples often contain a mix of code listings and explanatory text, and this is no exception:
+\begin{lstlisting}[language=modelica]
+String s = 1.0; // Error: No conversion form Real to String.
+\end{lstlisting}
+To fix the type mismatch above, the number has to be replaced by a \lstinline!String! expression, such as \lstinline!"1.0"!.
+\end{example}
+
+Other code listings in the document include specification of lexical units and grammatical structure, both using metasymbols of the extended BNF-grammar defined in~\cref{lexical-conventions}.
+Lexical units are named with all upper-case letters and introduced with the `\lstinline[language=grammar]!=!' sign:
+\begin{lstlisting}[language=grammar]
+SOME-TOKEN = NON-DIGIT { DIGIT | NON-DIGIT }
+\end{lstlisting}
+Grammatical structure is recognized by production rules being named with lower-case letters and introduced with the `\lstinline[language=grammar]!:!' sign (also note appearance of the Modelica keyword \lstinline!der!):
+\begin{lstlisting}[language=grammar]
+differentiated-expression :
+    der "(" SOME-TOKEN ")"
+    | "(" differentiated-expression "+" differentiated-expression ")"
+\end{lstlisting}
diff --git a/chapters/lexicalstructure.tex b/chapters/lexicalstructure.tex
@@ -108,7 +108,7 @@ \subsection{Names}\label{names}
 
 \subsection{Modelica Keywords}\label{modelica-keywords}
 
-The following Modelica \firstuse[keyword]{keywords} are reserved words and shall not be used as identifiers, except as listed in \cref{lexical-conventions}:
+The following Modelica \firstuse[keyword]{keywords} are reserved words and shall not be used as identifiers:
 \begin{center}
 \begin{tabular}{l l l l l}
 \lstinline!algorithm! & \lstinline!discrete! & \lstinline!false! & \lstinline!loop! & \lstinline!pure!\\ \hline

diff --git a/chapters/revisions.tex b/chapters/revisions.tex
@@ -453,8 +453,8 @@ \subsection{Main changes in Modelica 3.4}\label{main-changes-in-modelica-3-4}
   Clarified structural analysis, \cref{scope-of-the-specification}. Ticket
   \href{https://github.com/modelica/ModelicaSpecification/issues/588}{\#588}.
 \item
-  Clarified meta-symbols, \cref{notation-and-grammar} and 2.3.1. Ticket
-  \href{https://github.com/modelica/ModelicaSpecification/issues/1616}{\#1616}.
+  Clarified meta-symbols, \cref{notation} and 2.3.1.
+  Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/1616}{\#1616}.
 \item
   Typo, \cref{identifiers}. Ticket
   \href{https://github.com/modelica/ModelicaSpecification/issues/1702}{\#1702}.

diff --git a/chapters/syntax.tex b/chapters/syntax.tex
@@ -2,7 +2,7 @@ \chapter{Modelica Concrete Syntax}\label{modelica-concrete-syntax}
 
 \section{Lexical conventions}\label{lexical-conventions}
 
-The following syntactic meta symbols are used (extended BNF):
+The following syntactic metasymbols are used (extended BNF):
 \begin{center}
 \begin{tabular}{c l}
 \hline
@@ -57,18 +57,17 @@ \section{Lexical conventions}\label{lexical-conventions}
   Modelica uses the same comment syntax as C++ and Java (i.e., \lstinline!//! signals the start of a line comment and \lstinline!/* $\ldots$ */! is a multi-line comment); comments may contain any Unicode character.
   Modelica also has structured comments in the form of annotations and string comments.
 \item
-  Each description-string or string in annotations (= \lstinline[language=grammar]!STRING! with production annotation-clause in the grammar) may contain any member of the Unicode character set.
+  Each \lstinline[language=grammar]!description-string! or string in annotations (that is, a \lstinline[language=grammar]!STRING! with production \lstinline[language=grammar]!annotation-clause! in the grammar) may contain any member of the Unicode character set.
   All other strings have to contain only the subset of Unicode characters identical with the 7-bit US-ASCII character set.
   \begin{nonnormative}
   As a consequence, operators like `\lstinline!>!' or `\lstinline!<!', and external functions only operate on ASCII strings and not on Unicode-strings.
-  Within a description-string the tags \lstinline!<HTML>! and \lstinline!</HTML>! or \lstinline!<html>! and \lstinline!</html>! define optionally begin and end of content that is HTML encoded.
+  Within a \lstinline[language=grammar]!description-string! the tags \lstinline!<HTML>! and \lstinline!</HTML>! or \lstinline!<html>! and \lstinline!</html>! define optionally begin and end of content that is HTML encoded.
   \end{nonnormative}
 \item
-  Boldface denotes keywords of the Modelica language. Keywords are
-  reserved words and shall not be used as identifiers.
+  In the grammar, keywords of the Modelica language are highlighted with color, for example, \lstinline[language=grammar]!equation!.
 \item
-  Productions use hyphen as separator both in the grammar and in the
-  text. Previously the grammar used underscore.
+  Productions use hyphen as separator both in the grammar and in the text.
+  (Previously the grammar used underscore.)
 \end{itemize}
 
 \section{Grammar}\label{grammar}