Use pseudocode record for 'Documentation' annotation

Addressing review comment by @HansOlsson.
modelica · Jun 21, 2020 · ee61542 · ee61542
1 parent cfe7615
commit ee61542
Showing 1 changed file with 21 additions and 17 deletions.
diff --git a/chapters/annotations.tex b/chapters/annotations.tex
@@ -40,29 +40,33 @@ \section{Vendor-Specific Annotations}\doublelabel{vendor-specific-annotations}
 
 \section{Annotations for Documentation}\doublelabel{annotations-for-documentation}
 
-\begin{lstlisting}[language=grammar]
-documentation-annotation:
-   annotation "(" Documentation "(" [ "info" "=" STRING ]
-      [ "," "revisions" "=" STRING ]
-      [ "," "figures" "=" figure-annotations ] ")" ")"
-\end{lstlisting}
-The \lstinline!Documentation! annotation can contain the \lstinline!info! annotation
-giving a textual description, the \lstinline!revisions! annotation giving a list
-of revisions, and the \lstinline!figures! annotation giving a list of \lstinline!Figure! annotations as
-described in \autoref{annotations-for-figures}, and other annotations defined by a tool.
-
-How the tool interprets the information in \lstinline!Documentation! is unspecified.  Within the \lstinline!info! and \lstinline!revisions! strings of the \lstinline!Documentation! annotation,
-the tags \lstinline!<HTML>! and \lstinline!</HTML>! or \lstinline!<html>! and \lstinline!</html>! define optionally begin and end of content that is HTML encoded.  For external links,
-see \autoref{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
-\autoref{external-resources}), e.g.,
+The \lstinline!Documentation! annotation has the following contents, where the \lstinline!info! and \lstinline!revisions! annotations are described in \autoref{annotation-info-revisions},
+and the \lstinline!figures! annotation is described in \autoref{annotations-for-figures}:
 \begin{lstlisting}[language=modelica]
-<a href="modelica://MultiBody.Tutorial">MultiBody.Tutorial</a>
+record Documentation
+  String info = "" "Description of the class";
+  String revisions = "" "Revision history";
+  Figure[:] figures = {}; "Simulation result figures";
+end Documentation;
 \end{lstlisting}
 
+How the tool interprets the information in \lstinline!Documentation! is unspecified.
+
+\subsection{Class Description and Revision History}\doublelabel{annotation-info-revisions}
+
+Inside the \lstinline!Documentation! annotation, the \lstinline!info! annotation gives a textual description of the class, and the \lstinline!revisions! annotation gives a revision history.
+
 \begin{nonnormative}
 The \lstinline!revisions! documentation may be omitted in printed documentation.
 \end{nonnormative}
 
+The tags \lstinline!<HTML>! and \lstinline!</HTML>! or \lstinline!<html>! and \lstinline!</html>! define optionally begin and end of content that is HTML encoded.  For external links,
+see \autoref{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
+\autoref{external-resources}), e.g.,
+\begin{lstlisting}[language=modelica]
+<a href="modelica://MultiBody.Tutorial">MultiBody.Tutorial</a>
+\end{lstlisting}
+
 Together with scheme \lstinline!Modelica! the (URI) fragment specifiers
 \lstinline!#diagram!, \lstinline!#info!, \lstinline!#text!, \lstinline!#icon! may be used to reference different
 layers. User-defined fragment specifiers (anchors) may also be used, and they may be renamed
@@ -73,7 +77,7 @@ \section{Annotations for Documentation}\doublelabel{annotations-for-documentatio
 \end{lstlisting}
 
 \subsection{Annotations for Figures}\doublelabel{annotations-for-figures}
-The \lstinline!figure-annotations! is a list of \lstinline!Figure! annotations given by:
+Inside the \lstinline!Documentation! annotation, each element of the \lstinline!figures! annotation array has the following content:
 \begin{lstlisting}[language=modelica]
 record Figure
   String title = "" "Title meant for display";