Use new presentation style in "Annotations for Simulations" and inclu…

…de HideResult

chapters/annotations.tex

@@ -341,7 +341,6 @@ \section{Annotations for Code Generation}\label{annotations-for-code-generation}
 \hline
 \hline
 \lstinline!Evaluate! & Use parameter value for symbolic processing & \Cref{modelica:Evaluate}\\
-\lstinline!HideResult! & Don't show component's simulator result & \Cref{modelica:HideResult}\\
 \hline
 \end{tabular}
 \end{center}
@@ -366,6 +365,41 @@ \section{Annotations for Code Generation}\label{annotations-for-code-generation}
 \end{semantics}
 \end{annotationdefinition}
 
+
+\section{Annotations for Simulations}\label{annotations-for-simulations}
+
+The annotations listed below define how models can be checked, translated, and simulated.
+\begin{center}
+\begin{tabular}{l|l l}
+\hline
+\tablehead{Annotation} & \tablehead{Description} & \tablehead{Details}\\
+\hline
+\hline
+\lstinline!experiment! & Simulation experiment settings & \Cref{modelica:experiment}\\
+\lstinline!HideResult! & Don't show component's simulator result & \Cref{modelica:HideResult}\\
+\lstinline!TestCase! & Information for model used as test case & \Cref{modelica:TestCase}\\
+\hline
+\end{tabular}
+\end{center}
+
+\begin{annotationdefinition}[experiment]
+% henrikt-ma 2021-04: Seems strange to allow 'experiment' completely without list of options -- what would it mean?
+\begin{synopsis}[grammar]\begin{lstlisting}
+"experiment"
+   [ "(" [ experimentOption { "," experimentOption } ] ")" ]
+
+experimentOption:
+   "StartTime" "=" [ "+" | "-" ] UNSIGNED-NUMBER
+   | "StopTime" "=" [ "+" | "-" ] UNSIGNED-NUMBER
+   | "Interval" "=" UNSIGNED-NUMBER
+   | "Tolerance" "=" UNSIGNED-NUMBER
+\end{lstlisting}\end{synopsis}
+\begin{semantics}
+The \lstinline{experiment} annotation defines the default start time (\lstinline!StartTime!) in {[}s{]}, the default stop time (\lstinline!StopTime!) in {[}s{]}, the suitable time resolution for the result grid (\lstinline!Interval!) in {[}s{]}, and the default relative integration tolerance (\lstinline!Tolerance!) for simulation experiments to be carried out with the model or block at hand.
+If \lstinline!StartTime! is not specified it is assumed to be \lstinline!0.0!.
+\end{semantics}
+\end{annotationdefinition}
+
 \begin{annotationdefinition}[HideResult]
 \begin{synopsis}[grammar]\begin{lstlisting}
 "HideResult" "=" ( false | true )
@@ -383,43 +417,22 @@ \section{Annotations for Code Generation}\label{annotations-for-code-generation}
 \end{semantics}
 \end{annotationdefinition}
 
-
-\section{Annotations for Simulations}\label{annotations-for-simulations}
-
-These annotations define how models can be checked, translated, and simulated.
-
-\subsection{Annotations for Simulation Experiments}\label{annotations-for-simulation-experiments}
-
-\begin{lstlisting}[language=grammar]
-experiment-annotation:
-   annotation "(" "experiment" [ "(" [experimentOption
-      {"," experimentOption}] ")" ] ")"
-
-experimentOption:
-  "StartTime" "=" [ "+" | "-" ] UNSIGNED-NUMBER |
-  "StopTime"  "=" [ "+"  | "-"] UNSIGNED-NUMBER |
-  "Interval" "=" UNSIGNED-NUMBER |
-  "Tolerance" "=" UNSIGNED-NUMBER
-\end{lstlisting}
-
-The \fmtannotationindex{experiment} annotation defines the default start time (\lstinline!StartTime!) in {[}s{]}, the default stop time (\lstinline!StopTime!) in {[}s{]}, the suitable time resolution for the result grid (\lstinline!Interval!) in {[}s{]}, and the default relative integration tolerance (\lstinline!Tolerance!) for simulation experiments to be carried out with the model or block at hand.
-If \lstinline!StartTime! is not specified it is assumed to be \lstinline!0.0!.
-
-\subsection{Annotation for Test Cases}\label{annotation-for-test-cases}
-
-\begin{lstlisting}[language=grammar]
-testcase-annotation:
-   annotation "(" "TestCase" "(" "shouldPass" "=" ( false | true ) ")" ")"
-\end{lstlisting}%
-\annotationindex{TestCase}
+\begin{annotationdefinition}[TestCase]
+\begin{synopsis}[grammar]\begin{lstlisting}
+"TestCase" "(" "shouldPass" "=" ( false | true ) ")"
+\end{lstlisting}\end{synopsis}
+\begin{semantics}
 If \lstinline!shouldPass! is \lstinline!false! it indicates that the translation or the simulation of the model should fail.
 If a tools checks a package where classes have \lstinline!shouldPass = false! they should not generate errors, and checking may even be skipped.
 On the other hand, models with \lstinline!shouldPass = false! may be useful for creation of negative tests in tool-specific ways.
 Similarly as a class with obsolete-annotation, a class with \lstinline!TestCase! annotation (regardless of the value of \lstinline!shouldPass!) shall not be used in other models, unless those models also have a \lstinline!TestCase! annotation.
+
 \begin{nonnormative}
 The intent of the test-case can be included in the documentation of the class.
 This annotation can both be used for models intended as test-cases for implementations, and for models explaining detectable errors.
 \end{nonnormative}
+\end{semantics}
+\end{annotationdefinition}
 
 
 \section{Annotation for Single Use of Class}\label{annotation-for-single-use-of-class}

chapters/revisions.tex

@@ -175,7 +175,7 @@ \subsection{Main changes in Modelica 3.5}\label{main-changes-in-modelica-3-5}
 Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/2145}{\#2145}.
 \item Clarified Evaluate annotation for hierarchical components, \cref{annotations-for-code-generation}.
 Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/2288}{\#2288}.
-\item Added test-case annotation for incorrect models, \cref{annotations-for-simulation-experiments}.
+\item Added test-case annotation for incorrect models, \cref{modelica:TestCase}.
 Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/2340}{\#2340}.
 \item Clarified choicesAllMatching, \cref{annotation-choices-for-suggested-redeclarations-and-modifications}.
 Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/2693}{\#2693}.
@@ -221,7 +221,7 @@ \subsection{Main changes in Modelica 3.5}\label{main-changes-in-modelica-3-5}
 Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/2170}{\#2170}.
 \item Add iconVisible to be able to show/hide connectors in icon layer for public connectors, \cref{component-instance}.
 Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/2200}{\#2200}.
-\item Correct grammar for experiment and give default for startTime, \cref{annotations-for-simulation-experiments}.
+\item Correct grammar for experiment and give default for \lstinline!StartTime!, \cref{modelica:experiment}.
 Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/2224}{\#2224}.
 \item Clarified that versionBuild and dateModified can be used for uses annotation, \cref{version-handling}.
 Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/2239}{\#2239}.
@@ -1111,8 +1111,7 @@ \subsection{Main changes in Modelica 3.3}\label{main-changes-in-modelica-3-3}
   \item
     Functions to generate events, \cref{annotations-for-code-generation}.
   \item
-    Experiments to specify a time-resolution of simulation result,
-    \cref{annotations-for-simulation-experiments}.
+    Experiments to specify a time-resolution of simulation result, \cref{modelica:experiment}.
   \item
     Single instance of class, \cref{annotation-for-single-use-of-class}.
   \item
@@ -1265,10 +1264,7 @@ \subsection{Main changes in Modelica 3.2 Revision 2}\label{main-changes-in-model
 \item
   New built-in operator \lstinline!Connections.rooted(A.R)! to inquire whether an overdetermined type or record instance \lstinline!A.R! in a call to \lstinline!Connections.branch(A.R, B.R)! is closer to the root of the spanning tree than \lstinline!B.R!, \cref{overconstrained-equation-operators-for-connection-graphs} (used in MSL 3.2 to avoid algebraic loops in several components such as in \lstinline!Modelica.Mechanics.MultiBody.Joints.Revolute!).
 \item
-  Several new annotations where vendor-specific variants were used in
-  MSL 3.2; \cref{annotation-choices-for-suggested-redeclarations-and-modifications},
-  \cref{annotations-for-documentation}, \cref{annotations-for-code-generation},
-  \cref{annotations-for-simulation-experiments}, \cref{connections}, and \cref{annotations-for-the-graphical-user-interface}.
+  Several new annotations where vendor-specific variants were used in MSL 3.2; \cref{annotation-choices-for-suggested-redeclarations-and-modifications}, \cref{annotations-for-documentation}, \cref{annotations-for-code-generation}, \cref{modelica:experiment}, \cref{connections}, and \cref{annotations-for-the-graphical-user-interface}.
 \item
   Specified that Evaluate can also occur in types, since this is used in
   MSL and important for performance; \cref{annotations-for-code-generation}. Ticket
@@ -2204,9 +2200,8 @@ \subsection{Main Changes in Modelica 3.0}\label{main-changes-in-modelica-3-0}
   New annotations \crefnameref{annotations-for-code-generation}:\\
   \lstinline!Evaluate!, \lstinline!HideResult!, \lstinline!Inline!, \lstinline!LateInline!, \lstinline!smoothOrder!
 \item
-  New annotation \crefnameref{annotations-for-simulation-experiments}:\\
-  \lstinline!StartTime!, \lstinline!StopTime!, \lstinline!Tolerance! to define important parameters of an
-  experiment setup.
+  New annotation \cref{modelica:experiment}:\\
+  \lstinline!StartTime!, \lstinline!StopTime!, \lstinline!Tolerance! to define important parameters of an experiment setup.
 \item
   New annotations for graphical annotations in \cref{annotations-for-graphical-objects}:\\
   New attribute \lstinline!Smooth = enumeration(None, Bezier)! for graphical objects

chapters/scoping.tex

@@ -515,7 +515,7 @@ \subsubsection{Steps of Instantiation}\label{steps-of-instantiation}
 
 \begin{nonnormative}
 The annotations can be relevant for simulations, e.g.\ annotations for code generation (\cref{annotations-for-code-generation}.), simulation experiments
-(\cref{annotations-for-simulation-experiments}) or functions (\cref{declaring-derivatives-of-functions}, \cref{declaring-inverses-of-functions} and \cref{external-function-interface}).
+(\cref{modelica:experiment}) or functions (\cref{declaring-derivatives-of-functions}, \cref{declaring-inverses-of-functions} and \cref{external-function-interface}).
 \end{nonnormative}
 
 Extends clauses are not looked up, but empty extends clause nodes are created and inserted into the current instance (to be able to preserve the declaration order of components).