Describe common ways of using ModelicaUtilities.h

chapters/functions.tex

@@ -2645,6 +2645,26 @@ \subsection{Utility Functions}\label{utility-functions}
 
 This section describes the utility functions declared in \filename{ModelicaUtilities.h}, which can be called in external Modelica functions written in C.
 
+The tool must ensure that the header is found by \lstinline[language=C]!#include "ModelicaUtilities.h"! within an \lstinline!Include! annotation (see \cref{annotations-for-external-libraries-and-include-files}); no \lstinline!IncludeDirectory! annotation is needed.
+
+\begin{example}
+The following usage patterns are common:
+\begin{itemize}
+\item
+  The \lstinline!Include! annotation may first \lstinline[language=C]!#include "ModelicaUtilities.h"!, and then contain the external function definition where the utility functions may be used.
+\item
+  Like above, but moving the annotation content above to, say, \filename{myExtFun.c}, and then just do \lstinline[language=C]!#include "myExtFun.c"! in the annotation.
+\item
+  After \lstinline[language=C]!#include "ModelicaUtilities.h"!, the \lstinline!Include! annotation can also define a wrapper around a function in a linked library that does the real job, where the wrapper forwards the arguments as well as passes function pointers for a selection of functions from \filename{ModelicaUtilities.h}.
+\end{itemize}
+\end{example}
+
+\begin{nonnormative}
+When building external libraries, it is not possible to rely on the tool mechanism that provides \filename{ModelicaUtilities.h} for \lstinline!Include! annotations.
+Instead, an external library project may contain its own instance of \filename{ModelicaUtilities.h}, for example obtained by making a copy of the instance included within the Modelica Standard Library.
+\end{nonnormative}
+
+
 \subsubsection{Error Reporting Utility Functions}\label{utility-functions-for-reporting-errors}\label{error-reporting-utility-functions}
 
 The functions listed below produce a message in different ways.