Introduce notation by example

chapters/introduction.tex

@@ -100,10 +100,60 @@ \section{Some Definitions}\label{some-definitions}
 
 \section{Notation}\label{notation}
 
-Non-normative text, i.e., examples and comments, are enclosed in {[}\ldots{]} and set in italics.
-
-In Modelica code listings, keywords are highlighted with color and may come in both normal weight and boldface, for example, \lstinline!connect! and \lstinline!equation!.
-There are also certain recognized names with special meaning defined by the specification, highlighted with another color, for example, \lstinline!semiLinear!.
-% No need to describe appearance of comments, right?
+The remainder of this section shows examples of the presentation used in this document.
+
+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. */
+//String s = 1.0; /* Commenting out invalid code like this is rare. */
+  /* Instead of commenting-out invalid code, it is typically done this way: */
+  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}
+
+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 inde!
+Text defining the meaning of \emph{something}.
+\end{definition}
 
-The meta symbols of the extended BNF-grammar are defined in~\cref{lexical-conventions}.
+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}

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