Skip to content

Apply modern table presentation to some more annotations #2957

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 20 commits into from
Closed

Apply modern table presentation to some more annotations #2957

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
11a390a
Clean up formatting of annotations in listings
henrikt-ma Jun 17, 2021
6354d85
Align Library annotation syntax with actual use in the MSL
henrikt-ma Jun 17, 2021
ffc8c02
Improve formatting related to missingInnerMessage
henrikt-ma Jun 17, 2021
72e7a19
Remove hyphenated use of 'annotation' according to style guide
henrikt-ma Jun 17, 2021
8d3aeb6
Break too long lines in listings
henrikt-ma Jun 17, 2021
6c62d4b
Deal with bad line breaks by modernizing presentation
henrikt-ma Jun 17, 2021
e9490b0
Modernize presentation of 'choces' and 'choicesAllMatching'
henrikt-ma Jun 17, 2021
1859e7f
Modernize presentation of 'singleInstance'
henrikt-ma Jun 17, 2021
4f4f192
Modernize presentation of version handling
henrikt-ma Jun 18, 2021
2351199
Merge remote-tracking branch 'central/master' into cleanup/style-miss…
henrikt-ma Sep 2, 2021
47ed90c
Merge remote-tracking branch 'central/master' into cleanup/style-miss…
henrikt-ma Nov 8, 2021
af16ab5
Merge remote-tracking branch 'central/master' into cleanup/style-miss…
henrikt-ma Jan 28, 2022
8c4f75b
Change 'class-modification' -> 'modification' in 'choices-argument'
henrikt-ma Feb 10, 2022
a0b1ca0
Clean up white-space inside unassignedMessage string in listing
henrikt-ma Mar 31, 2022
87b8f4a
Define lexical unit PACKAGE-VERSION for contents of package version s…
henrikt-ma Apr 14, 2022
dbebe1b
Spell out meaning of \textvisiblespace
henrikt-ma May 9, 2022
6033119
Merge remote-tracking branch 'central/master' into cleanup/style-miss…
henrikt-ma May 15, 2022
c6f4807
Express PRE-RELEASE-VERSION using MAIN-VERSION
henrikt-ma Sep 6, 2022
493441c
Merge remote-tracking branch 'central/master' into cleanup/style-miss…
henrikt-ma Sep 6, 2022
fd41229
Use non-breaking space instead of \textvisiblespace
henrikt-ma Sep 26, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
448 changes: 281 additions & 167 deletions chapters/annotations.tex
View file
Open in desktop

Large diffs are not rendered by default.

153 changes: 101 additions & 52 deletions chapters/functions.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1739,7 +1739,7 @@ \subsection{Using the Inverse Annotation}\label{using-the-inverse-annotation}

There is no guarantee that a provided inverse will be used, and no rule for at which stage of symbolic processing it could be applied.
Inlining a function means that the possibility to apply provided inverses is lost.
Hence, the recommended inlining annotations -- if any -- for use together with the {\lstinline!inverse!}-annotation is either {\lstinline!Inline = false!} or {\lstinline!LateInline = true!}.
Hence, the recommended inlining annotations -- if any -- for use together with the {\lstinline!inverse!} annotation is either {\lstinline!Inline = false!} or {\lstinline!LateInline = true!}.

\begin{example}
If an inverse is provided, but the injectiveness part of the bijectiveness requirement is not fulfilled, this may introduce additional ambiguity to the solution of equations with multiple solutions.
Expand Down Expand Up @@ -1991,7 +1991,9 @@ \section{External Function Interface}\label{external-function-interface}
is treated the same way as a top-level input or output in the external
call.

If the function has {\lstinline!annotation(Include="includeDirective")!}, \cref{annotations-for-external-libraries-and-include-files} it is assumed that it contains an actual prototype and no prototype shall be automatically generated. In that case the input argument pointers shall be const pointers (indicating that they do not modify the inputs), and non-const pointers are deprecated. The optional {\lstinline[language=grammar]!external-function-call!} is still used for determining the name of the function, and order of arguments, as described below.
If the function has {\lstinline!annotation(Include = "includeDirective")!}, \cref{annotations-for-external-libraries-and-include-files} it is assumed that it contains an actual prototype and no prototype shall be automatically generated.
In that case the input argument pointers shall be const pointers (indicating that they do not modify the inputs), and non-const pointers are deprecated.
The optional {\lstinline[language=grammar]!external-function-call!} is still used for determining the name of the function, and order of arguments, as described below.

\subsection{Argument type Mapping}\label{argument-type-mapping}

Expand Down Expand Up @@ -2356,65 +2358,111 @@ \subsection{Aliasing}\label{aliasing}

\subsection{Annotations for External Functions}\label{annotations-for-external-libraries-and-include-files}

The following annotations are useful in the context of calling external functions from Modelica, and they should occur on the {\lstinline!external!}-clause and no other standard annotations should occur on the {\lstinline!external!}-clause.
They can all specify either a scalar value or an array of values as indicated below for the {\lstinline!Library!} annotation:
The annotations listed below are useful in the context of calling external functions from Modelica.
They should occur on the {\lstinline!external!}-clause, and no other standard annotations should occur on the {\lstinline!external!}-clause.
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Annotation} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
{\lstinline!Library!} & Libraries to link with & \Cref{modelica:Library}\\
{\lstinline!Include!} & Include directives & \Cref{modelica:Include}\\
{\lstinline!LibraryDirectory!} & Directories containing libraries & \Cref{modelica:LibraryDirectory}\\
{\lstinline!IncludeDirectory!} & Directories containing header files & \Cref{modelica:IncludeDirectory}\\
{\lstinline!SourceDirectory!} & Directories containing source code& \Cref{modelica:SourceDirectory}\\
\hline
\end{tabular}
\end{center}

They can all specify either a scalar value or an array of values as indicated by the {\lstinline[language=grammar]!string-or-string-array!} syntax introduced with the {\lstinline!Library!} annotation.

The {\lstinline!ModelicaLibraryName!} used below for {\lstinline!IncludeDirectory!}, {\lstinline!LibraryDirectory!}, and {\lstinline!SourceDirectory!} indicates the top-level class where the annotation is found in the Modelica source code.

\begin{annotationdefinition}[Library]
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer if we just write that it should be a string or an array of strings, and don't use grammar fragments unless needed.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you sure this isn't a good place to use it? It is defined once, used in the definitions of 5 different annotations so far, and also mentioned in the running text. It would take considerably more text and hand waving to do it without giving a name to the idea.

While we might be able to change many of the annotations to the pseudo-code style of presentation, the ones we have here belong to the category where specification using grammar actually makes sense as we can't express the type of the annotation using a Modelica type.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Couldn't we just keep the grammar fragment for now, and revisit this once we take the bigger grip on presentation of annotations as decided at the last phone meeting (can't find in what issue that decision was noted)?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any chance we can return to this once we turn to the question of how to present the things that can't be expressed easily in the record style established so far?

\begin{synopsis}[grammar]\begin{lstlisting}
"Library" "=" string-or-string-array

string-or-string-array :
STRING
| "{" [ STRING { "," STRING } ] "}"
\end{lstlisting}\end{synopsis}
\begin{semantics}
{\lstinline!Library = "libraryName"!} is used to tell the linker to include the library file where the compiled external function is available.

{\lstinline!Library = {"libraryName1", "libraryName2"}!} is used to tell the linker to include the library file where the compiled external function is available, as well as additional libraries used to implement it.
For shared libraries it is recommended to include all non-system libraries in this list.

The library on Windows may refer to a lib-file (static library), both a lib- and dll-file (in this case the lib-file is an import-library), or just a dll-file.
It shall not refer to an obj-file.
\end{semantics}
\end{annotationdefinition}

\begin{annotationdefinition}[Include]
\begin{synopsis}[grammar]\begin{lstlisting}
"Include" "=" string-or-string-array
\end{lstlisting}\end{synopsis}
\begin{semantics}
{\lstinline!Include = "includeDirective"!} is used to include source files needed for calling the external function in the code generated by the Modelica compiler.
The included code should be valid C89 code.
\begin{nonnormative}
Examples of files that can be included are header files or source files that contain the functions referenced in the external function declaration.
\end{nonnormative}
\end{semantics}
\end{annotationdefinition}

\begin{annotationdefinition}[LibraryDirectory]
\begin{synopsis}[grammar]\begin{lstlisting}
"LibraryDirectory" "=" string-or-string-array
\end{lstlisting}\end{synopsis}
\begin{semantics}
{\lstinline!LibraryDirectory = "modelica://ModelicaLibraryName/Resources/Library"!} is used to specify a location for library files.
The preceding one is the default and need not be specified; but another location could be specified by using an URI name for the library directory, see \cref{external-resources}.
Different versions of one object library can be provided (e.g.\ for Windows and for Linux) by providing a \emph{platform} directory below the {\lstinline!LibraryDirectory!}.
If no platform directory is present, the object library must be present in the {\lstinline!LibraryDirectory!}.

The following \emph{platform} names are standardized:
\begin{itemize}
\item
The {\lstinline!annotation(Library="libraryName")!}\annotationindex{Library}, used by the linker to include the library file where the compiled external function is available.
{\lstinline!"win32"!} (Microsoft Windows 32 bit)
\item
The {\lstinline!annotation(Library={"libraryName1", "libraryName2"})!}, used by the linker to include the library files where the compiled external function is available and additional libraries used to implement it.
For shared libraries it is recommended to include all non-system libraries in this list.
{\lstinline!"win64"!} (Microsoft Windows 64 bit)
\item
The {\lstinline!annotation(Include="includeDirective")!}\annotationindex{Include}, used to include source files needed for calling the external function in the code generated by the Modelica compiler.
The included code should be valid C89 code.
\begin{nonnormative}
Examples of files that can be included are header files or source files that contain the functions referenced in the external function declaration.
\end{nonnormative}
{\lstinline!"linux32"!} (Linux Intel 32 bit)
\item
The
{\lstinline!annotation(IncludeDirectory="modelica://ModelicaLibraryName/Resources/Include")!}\annotationindex{IncludeDirectory}, used to specify a location for header files.
The preceding one is the default and need not be specified; but another location could be specified by using an URI name for the include directory, see \cref{external-resources}.
\item
The
{\lstinline!annotation(LibraryDirectory="modelica://ModelicaLibraryName/Resources/Library")!}\annotationindex{LibraryDirectory}, used to specify a location for library files.
The preceding one is the default and need not be specified; but another location could be specified by using an URI name for the library directory, see \cref{external-resources}.
Different versions of one object library can be provided (e.g.\ for Windows and for Linux) by providing a \emph{platform} directory below the {\lstinline!LibraryDirectory!}.
If no platform directory is present, the object library must be present in the {\lstinline!LibraryDirectory!}.
The following \emph{platform} names are standardized:
\begin{itemize}
\item
{\lstinline!"win32"!} (Microsoft Windows 32 bit)
\item
{\lstinline!"win64"!} (Microsoft Windows 64 bit)
\item
{\lstinline!"linux32"!} (Linux Intel 32 bit)
\item
{\lstinline!"linux64"!} (Linux Intel 64 bit)
\end{itemize}
\item
The
{\lstinline!annotation(SourceDirectory="modelica://ModelicaLibraryName/Resources/Source")!}\annotationindex{SourceDirectory}, gives the location for source files.
The preceding one is the default and need not be specified; but another location could be specified by using an URI name for the source directory, see \cref{external-resources}.
It is not specified how they are built.
{\lstinline!"linux64"!} (Linux Intel 64 bit)
\end{itemize}
The \filename{win32} or \filename{win64} directories may contain \filename{gcc47}, \filename{vs2010}, \filename{vs2012} for specific versions of these compilers and these are used instead of the general \filename{win32} or \filename{win64} directories, and similarly for other platforms.

The \filename{win32} or \filename{win64} directories may contain \filename{gcc47}, \filename{vs2010}, \filename{vs2012}
for specific versions of these compilers and these are used instead of
the general \filename{win32} or \filename{win64} directories, and similarly for other
platforms.

The library on Windows may refer to a lib-file (static library), both a lib- and dll-file (in this case the lib-file is an import-library),
or just a dll-file. It shall not refer to an obj-file.

If the directory for the specific compiler version is missing the
platform specific directory is used.
If the directory for the specific compiler version is missing the platform specific directory is used.

\begin{nonnormative}
A tool may give a diagnostic if the directory corresponding to the selected compiler version is missing.
The directories may use symbolic links or use a text-file as described below: e.g.\ a text-file \filename{vs2008} containing the text \emph{../win32/vs2005} (or \emph{vs2005}) suggesting that it is compatible with vs2005.
\end{nonnormative}
\end{semantics}
\end{annotationdefinition}

\begin{annotationdefinition}[IncludeDirectory]
\begin{synopsis}[grammar]\begin{lstlisting}
"IncludeDirectory" "=" string-or-string-array
\end{lstlisting}\end{synopsis}
\begin{semantics}
\lstinline!IncludeDirectory = "modelica://ModelicaLibraryName/Resources/Include"! is used to specify a location for header files.
The preceding one is the default and need not be specified; but another location could be specified by using an URI name for the include directory, see \cref{external-resources}.
\end{semantics}
\end{annotationdefinition}

The {\lstinline!ModelicaLibraryName!} used for {\lstinline!IncludeDirectory!}, {\lstinline!LibraryDirectory!}, and {\lstinline!SourceDirectory!} indicates the top-level class where the annotation is found in the Modelica source code.
\begin{annotationdefinition}[SourceDirectory]
\begin{synopsis}[grammar]\begin{lstlisting}
"SourceDirectory" "=" string-or-string-array
\end{lstlisting}\end{synopsis}
\begin{semantics}
\lstinline!SourceDirectory = "modelica://ModelicaLibraryName/Resources/Source"! gives the location for source files.
The preceding one is the default and need not be specified; but another location could be specified by using an URI name for the source directory, see \cref{external-resources}.
It is not specified how they are built.
\end{semantics}
\end{annotationdefinition}

\begin{example}
Use of external functions and of object libraries:
Expand All @@ -2438,10 +2486,11 @@ \subsection{Annotations for External Functions}\label{annotations-for-external-l
output Real y;
external "C"
y = ExternalFunc1_ext(x)
annotation(Library = "ExternalLib1",
Include = "#include \"ExternalFunc1.h\"",
SourceDirectory =
"modelica://ExternalFunctions/Resources/Source");
annotation(
Library = "ExternalLib1",
Include = "#include \"ExternalFunc1.h\"",
SourceDirectory = "modelica://ExternalFunctions/Resources/Source"
);
// The specified SourceDirectory is the default and thus redundant.
end ExternalFunc1;

Expand Down
Loading