Skip to content

Commit 26f258a

Browse files
henrikt-maHansOlsson
henrikt-ma
and
HansOlsson
authored
Apply modern table presentation to Versions (#3737)
* Apply modern table presentation to Versions * Improve annotation readability * Fix grammar of 'conversion-rule' * Add semicolon after 'version' * Rewrite bad sentence for version-annotation as two sentences * Change PACKAGE-VERSION-STRING -> PACKAGE-VERSION Co-authored-by: Hans Olsson <[email protected]>
1 parent 8beeca5 commit 26f258a

File tree

1 file changed

+159
-80
lines changed

1 file changed

+159
-80
lines changed

‎chapters/annotations.tex‎

Lines changed: 159 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1844,8 +1844,25 @@ \subsection{Connector Sizing}\label{connector-sizing}\annotationindex{connectorS
18441844

18451845
\section{Versions}\label{annotations-for-version-handling}\label{versions}
18461846

1847-
A top-level package or model can specify the version of top-level classes it uses, its own version number, and if possible how to convert from previous versions.
1847+
The annotations listed below allow a top-level package or model to specify the versions of top-level classes it uses, its own version number, and if possible, how to convert from previous versions.
18481848
This can be used by a tool to guarantee that consistent versions are used, and if possible to upgrade usage from an earlier version to a current one.
1849+
\begin{center}
1850+
\begin{tabular}{l|l l}
1851+
\hline
1852+
\tablehead{Annotation} & \tablehead{Description} & \tablehead{Details}\\
1853+
\hline
1854+
\hline
1855+
\lstinline!version! & Version of top-level package & \Cref{modelica:version}\\
1856+
\lstinline!conversion! & Conversions to apply when upgrading & \Cref{modelica:conversion}\\
1857+
\lstinline!uses! & Top-level package dependencies & \Cref{modelica:uses}\\
1858+
\lstinline!versionDate! & Date of first version build & \Cref{modelica:versionDate}\\
1859+
\lstinline!versionBuild! & Maintenance update number & \Cref{modelica:versionBuild}\\
1860+
\lstinline!dateModified! & Date of last change & \Cref{modelica:dateModified}\\
1861+
\lstinline!revisionId! & Version control system version information & \Cref{modelica:revisionId}\\
1862+
\hline
1863+
\end{tabular}
1864+
\end{center}
1865+
18491866

18501867
\subsection{Version Numbering}\label{version-numbering}
18511868

@@ -1876,32 +1893,74 @@ \subsection{Version Numbering}\label{version-numbering}
18761893

18771894
\subsection{Version Handling}\label{version-handling}
18781895

1879-
In a top-level class, the version number and the dependency to earlier versions of this class are defined using one or more of the following annotations:
1880-
% TODO: Syntax below is a mess: neither Modelica, pseudo-code record, nor grammar.
1881-
\begin{itemize}
1882-
\item
1883-
\lstinline!version = CURRENT-VERSION-NUMBER!\annotationindex{version}\\
1884-
Defines the version number of the model or package.
1885-
All classes within this top-level class have this version number.
1886-
\item
1887-
\lstinline!conversion(noneFromVersion = VERSION-NUMBER)!\annotationindex{conversion}\\
1888-
Defines that user models using the \lstinline!VERSION-NUMBER! can be upgraded to the \lstinline!CURRENT-VERSION-NUMBER! of the current class without any changes.
1889-
\item
1890-
\lstinline!conversion(from(version = Versions, [to=VERSION-NUMBER,] Convert))!\\
1891-
where \emph{Versions} is \lstinline!VERSION-NUMBER! \textbar{} \lstinline!{VERSION-NUMBER, VERSION-NUMBER, $\ldots$}! and \lstinline!Convert! is \lstinline!script="$\ldots$"! \textbar{} \lstinline!change={conversionRule(), $\ldots$, conversionRule()}!\\*[.5ex]
1892-
Defines that user models using the \lstinline!VERSION-NUMBER! or any of the given \lstinline!VERSION-NUMBER! can be upgraded to the given \lstinline!VERSION-NUMBER! (if the to-tag is missing this is the \lstinline!CURRENT-VERSION-NUMBER!) of the current class by applying the given conversion rules.
1893-
The script consists of an unordered sequence of \lstinline!conversionRule();! (and optionally Modelica comments).
1894-
The \lstinline!conversionRule! functions are defined in \cref{conversion-rules}.
1895-
1896-
\begin{nonnormative}
1897-
The to-tag is added for clarity and optionally allows a tool to convert in multiple steps.
1898-
\end{nonnormative}
1899-
\item
1900-
\lstinline!uses(IDENT (version = VERSION-NUMBER [, versionBuild=INTEGER] [, dateModified=STRING] ) )!\annotationindex{uses}\\
1901-
Defines that classes within this top-level class use version \lstinline!VERSION-NUMBER! of classes within the top-level class \lstinline!IDENT!.
1902-
\end{itemize}
1896+
In a top-level class, the version number and the dependency to earlier versions of this class are defined using one or more of the annotations described in this section.
1897+
1898+
\begin{annotationdefinition}[version]
1899+
\begin{synopsis}\begin{lstlisting}
1900+
/*literal*/ constant String version;
1901+
\end{lstlisting}\end{synopsis}
1902+
\begin{semantics}
1903+
\lstinline!version = $\mathit{currentVersion}$! defines the version number of the model or package.
1904+
The $\mathit{currentVersion}$ shall be a \lstinline[language=grammar]!PACKAGE-VERSION!.
1905+
All classes within this top-level class have this version number.
1906+
\end{semantics}
1907+
\end{annotationdefinition}
1908+
1909+
\begin{annotationdefinition}[conversion]
1910+
\begin{synopsis}[grammar]\begin{lstlisting}
1911+
"conversion" "=" "(" [ conversion { "," conversion } ] ")"
1912+
1913+
conversion : conversion-none | conversion-with-rules
1914+
1915+
conversion-none : "noneFromVersion" "=" PACKAGE-VERSION
1916+
1917+
conversion-with-rules :
1918+
"from" "("
1919+
"version" = package-versions
1920+
[ "," "to" "=" PACKAGE-VERSION ]
1921+
"," conversion-rules
1922+
")"
19031923

1904-
The annotations \lstinline!uses! and \lstinline!conversion! may contain several different sub-entries.
1924+
conversion-rules :
1925+
"script" "=" STRING
1926+
| "change" "(" [ conversion-rule { "," conversion-rule } ] ")"
1927+
1928+
conversion-rule : IDENT function-call-args
1929+
1930+
package-versions :
1931+
PACKAGE-VERSION
1932+
| "{" PACKAGE-VERSION { "," PACKAGE-VERSION } "}"
1933+
\end{lstlisting}\end{synopsis}
1934+
\begin{semantics}
1935+
\lstinline!conversion(noneFromVersion = $\mathit{fromVersion}$)! defines that models and packages using the $\mathit{fromVersion}$ can be upgraded to the $\mathit{currentVersion}$ of the current class without any changes.
1936+
1937+
\lstinline!conversion(from(version = $\mathit{fromVersions}$, to = $\mathit{toVersion}$, $\mathit{conversionRules}$))! defines that models and packages using any of the $\mathit{fromVersions}$ can be upgraded to the $\mathit{toVersion}$ (if the $\mathit{toVersion}$ is omitted, this is the $\mathit{currentVersion}$) of the current class by applying the $\mathit{conversionRules}$.
1938+
When $\mathit{conversionRules}$ is given as \lstinline!script = $\mathit{conversionScript}$!, the $\mathit{conversionScript}$ is the name of a file consisting of an unordered sequence of \lstinline[language=grammar]!conversion-rule ";"! and Modelica comments, where any comments should be ignored by tools.
1939+
A \lstinline[language=grammar]!conversion-rule! has the form of a function call, where the functions are defined in \cref{conversion-rules}.
1940+
1941+
\begin{nonnormative}
1942+
The \lstinline!to! version is added for clarity and optionally allows a tool to convert in multiple steps.
1943+
\end{nonnormative}
1944+
\end{semantics}
1945+
\end{annotationdefinition}
1946+
1947+
\begin{annotationdefinition}[uses]
1948+
\begin{synopsis}[grammar]\begin{lstlisting}
1949+
"uses" "(" [ used-package { "," used-package } ] ")"
1950+
1951+
used-package :
1952+
IDENT "("
1953+
"version" "=" PACKAGE-VERSION
1954+
[ "," "versionBuild" "=" UNSIGNED-INTEGER ]
1955+
[ "," "dateModified" "=" STRING ]
1956+
")"
1957+
\end{lstlisting}\end{synopsis}
1958+
\begin{semantics}
1959+
\lstinline!uses($\mathit{otherPackage}$(version = $\mathit{otherPackageVersion}$))! defines that classes within this top-level class use the $\mathit{otherPackageVersion}$ of classes within the top-level class $\mathit{otherPackage}$.
1960+
1961+
See \cref{version-date-and-build-information} regarding the use of \lstinline!versionBuild! and \lstinline!dateModified!.
1962+
\end{semantics}
1963+
\end{annotationdefinition}
19051964

19061965
\begin{example}
19071966
\begin{lstlisting}[language=modelica]
@@ -1915,25 +1974,29 @@ \subsection{Version Handling}\label{version-handling}
19151974
from(version = {"2.1", "2.2", "2.2.1"},
19161975
script = "convertTo3.mos"),
19171976
from(version = "1.5",
1918-
script = "convertFromModelica1_5.mos")));
1977+
script = "convertFromModelica1_5.mos")
1978+
));
19191979
end Modelica;
19201980

19211981
model A
19221982
$\ldots$
19231983
annotation(
19241984
version = "1.0",
1925-
uses(Modelica(version = "1.5")));
1985+
uses(Modelica(version = "1.5"))
1986+
);
19261987
end A;
19271988

19281989
model B
19291990
$\ldots$
19301991
annotation(
1931-
uses(Modelica(version = "3.1 Beta 1")));
1992+
uses(Modelica(version = "3.1 Beta 1"))
1993+
);
19321994
end B;
19331995
\end{lstlisting}
19341996
In this example the model \lstinline!A! uses an older version of the Modelica library and can be upgraded using the given script, and model \lstinline!B! uses an older version of the Modelica library but no changes are required when upgrading.
19351997
\end{example}
19361998

1999+
19372000
\subsubsection{Conversion Rules}\label{conversion-rules}
19382001

19392002
% Using mbox to avoid having line starting with ","
@@ -2152,6 +2215,7 @@ \subsubsection{Conversion Rules}\label{conversion-rules}
21522215
If the parameter had no impact on the model it can be removed using \lstinline!convertModifiers!, see \cref{convertmodifiers}.
21532216
\end{nonnormative}
21542217

2218+
21552219
\subsection{Versions in the File System}\label{mapping-of-versions-to-file-system}\label{versions-in-the-File-System}
21562220

21572221
The top-level class $\mathit{packageName}$ with version $\mathit{packageVersion}$ (matching \lstinline[language=grammar]!PACKAGE-VERSION! defined in \cref{version-numbering}) can be stored in one of the following ways in a directory given in the \lstinline!MODELICAPATH! (\cref{the-modelica-library-path-modelicapath}):
@@ -2172,24 +2236,72 @@ \subsection{Versions in the File System}\label{mapping-of-versions-to-file-syste
21722236

21732237
This allows a tool to access multiple versions of the same package.
21742238

2239+
21752240
\subsection{Version Date and Build Information}\label{version-date-and-build-information}
21762241

2177-
Besides version information, a top-level class can have additionally the following top-level annotations to specify associated information to the version number:%
2178-
\begin{lstlisting}[language=modelica]
2242+
This section describes annotations that a top-level class can have to specify information associated to the version number.
2243+
2244+
The \lstinline!versionBuild! and \lstinline!dateModified! annotations can also be specified in the \lstinline!uses! annotation (together with the version number).
2245+
2246+
\begin{nonnormative}
2247+
It is recommended that tools do not automatically store \lstinline!versionBuild! and \lstinline!dateModified! in the \lstinline!uses! annotation.
2248+
\end{nonnormative}
2249+
2250+
\begin{annotationdefinition}[versionDate]
2251+
\begin{synopsis}\begin{lstlisting}
21792252
/*literal*/ constant String versionDate
2180-
"UTC date of first version build (in format: YYYY-MM-DD)";
2253+
\end{lstlisting}\end{synopsis}
2254+
\begin{semantics}
2255+
\lstinline!versionDate! is the date when the library was released.
2256+
This string is updated by the library author to correspond with the version number.
2257+
2258+
The date shall be given as UTC according to ISO 8601: YYYY-MM-DD
2259+
\end{semantics}
2260+
\end{annotationdefinition}
2261+
2262+
\begin{annotationdefinition}[versionBuild]
2263+
\begin{synopsis}\begin{lstlisting}
21812264
/*literal*/ constant Integer versionBuild
2182-
"Larger number is a more recent maintenance update";
2265+
\end{lstlisting}\end{synopsis}
2266+
\begin{semantics}
2267+
\lstinline!versionBuild! is the optional build number of the library.
2268+
When a new version is released \lstinline!versionBuild! should be omitted or \lstinline!versionBuild = 1!.
2269+
There might be bug fixes to the library that do not justify a new library version.
2270+
Such maintenance changes are called a \emph{build} release of the library.
2271+
For every new maintenance change, the \lstinline!versionBuild! number is increased.
2272+
A \lstinline!versionBuild! number $A$ that is higher than \lstinline!versionBuild! number $B$, is a newer release of the library.
2273+
There are no conversions between the same versions with different build numbers.
2274+
2275+
Two releases of a library with the same \lstinline!version! but different \lstinline!versionBuild! are in general assumed to be compatible.
2276+
In special cases, the \lstinline!uses!-clause of a model may specify \lstinline!versionBuild! and/or \lstinline!dateModified!.
2277+
In such a case the tool is expected to give a warning if there is a mismatch between library and model.
2278+
\end{semantics}
2279+
\end{annotationdefinition}
2280+
2281+
\begin{annotationdefinition}[dateModified]
2282+
\begin{synopsis}\begin{lstlisting}
21832283
/*literal*/ constant String dateModified
2184-
"UTC date and time of the latest change to the package
2185-
in the following format (with one space between date
2186-
and time): YYYY-MM-DD hh:mm:ssZ";
2284+
\end{lstlisting}\end{synopsis}
2285+
\begin{semantics}
2286+
\lstinline!dateModified! is the date and time of the last modification of the package.
2287+
2288+
The date and time shall given as UTC according to ISO 8601 (with one space between date and time): YYYY-MM-DD hh:mm:ssZ
2289+
2290+
\begin{nonnormative}
2291+
The intention is that a Modelica tool updates this annotation whenever the package or part of it was modified and is saved on persistent storage (like file or database system).
2292+
\end{nonnormative}
2293+
\end{semantics}
2294+
\end{annotationdefinition}
2295+
2296+
\begin{annotationdefinition}[revisionId]
2297+
\begin{synopsis}\begin{lstlisting}
21872298
/*literal*/ constant String revisionId
2188-
"Revision identifier of the version management system used
2189-
to manage this library. It marks the latest submitted
2190-
change to any file belonging to the package";
2191-
\end{lstlisting}%
2192-
\annotationindex{versionDate}\annotationindex{versionBuild}\annotationindex{dateModified}\annotationindex{revisionId}
2299+
\end{lstlisting}\end{synopsis}
2300+
\begin{semantics}
2301+
\lstinline!revisionId! is a tool specific revision identifier possibly generated by a source code management system (e.g., Subversion or CVS).
2302+
This information exactly identifies the library source code in the source code management system.
2303+
\end{semantics}
2304+
\end{annotationdefinition}
21932305

21942306
\begin{example}
21952307
\begin{lstlisting}[language=modelica,mathescape=false,escapechar=!]
@@ -2200,57 +2312,24 @@ \subsection{Version Date and Build Information}\label{version-date-and-build-inf
22002312
versionDate = "2008-04-10",
22012313
versionBuild = 4,
22022314
dateModified = "2009-02-15 16:33:14Z",
2203-
revisionId = "$Id:: package.mo 2566 2009-05-26 13:25:54Z #$");
2315+
revisionId = "$Id:: package.mo 2566 2009-05-26 13:25:54Z #$"
2316+
);
22042317
end Modelica;
22052318

22062319
model M1
22072320
annotation(
2208-
uses(Modelica(version = "3.0.1"))); // Common case
2321+
uses(Modelica(version = "3.0.1")) // Common case
2322+
);
22092323
end M1
22102324

22112325
model M2
22122326
annotation(
2213-
uses(Modelica(version = "3.0.1", versionBuild = 4)));
2327+
uses(Modelica(version = "3.0.1", versionBuild = 4))
2328+
);
22142329
end M2
22152330
\end{lstlisting}
22162331
\end{example}
22172332

2218-
The meanings of these annotations are:
2219-
\begin{itemize}
2220-
\item
2221-
\lstinline!version! is the version number of the released library, see \cref{version-handling}.
2222-
\item
2223-
\lstinline!versionDate! is the date in UTC format (according to ISO 8601) when the library was released.
2224-
This string is updated by the library author to correspond with the version number.
2225-
\item
2226-
\lstinline!versionBuild! is the optional build number of the library.
2227-
When a new version is released \lstinline!versionBuild! should be omitted or \lstinline!versionBuild = 1!.
2228-
There might be bug fixes to the library that do not justify a new library version.
2229-
Such maintenance changes are called a \emph{build} release of the library.
2230-
For every new maintenance change, the \lstinline!versionBuild! number is increased.
2231-
A \lstinline!versionBuild! number $A$ that is higher than \lstinline!versionBuild! number $B$, is a newer release of the library.
2232-
There are no conversions between the same versions with different build numbers.
2233-
2234-
Two releases of a library with the same \lstinline!version! but different \lstinline!versionBuild! are in general assumed to be compatible.
2235-
In special cases, the \lstinline!uses!-clause of a model may specify \lstinline!versionBuild! and/or \lstinline!dateModified!.
2236-
In such a case the tool is expected to give a warning if there is a mismatch between library and model.
2237-
\item
2238-
\lstinline!dateModified! is the UTC date and time (according to ISO 8601) of the last modification of the package.
2239-
2240-
\begin{nonnormative}
2241-
The intention is that a Modelica tool updates this annotation whenever the package or part of it was modified and is saved on persistent storage (like file or database system).
2242-
\end{nonnormative}
2243-
\item
2244-
\lstinline!revisionId! is a tool specific revision identifier possibly generated by a source code management system (e.g., Subversion or CVS).
2245-
This information exactly identifies the library source code in the source code management system.
2246-
\end{itemize}
2247-
2248-
The \lstinline!versionBuild! and \lstinline!dateModified! annotations can also be specified in the \lstinline!uses! annotation (together with the version number).
2249-
2250-
\begin{nonnormative}
2251-
It is recommended that tools do not automatically store \lstinline!versionBuild! and \lstinline!dateModified! in the \lstinline!uses! annotation.
2252-
\end{nonnormative}
2253-
22542333

22552334
\section{Access Control to Protect Intellectual Property}\label{annotations-for-access-control-to-protect-intellectual-property}\label{access-control-to-protect-intellectual-property}
22562335

0 commit comments

Comments
 (0)