forked from modelica/ModelicaSpecification
-
Notifications
You must be signed in to change notification settings - Fork 0
/
packages.tex
507 lines (423 loc) · 29.5 KB
/
packages.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
\chapter{Packages}\label{packages}
Packages in Modelica may contain definitions of constants and
classes including all kinds of specialized classes, functions, and
subpackages. By the term subpackage we mean that the package is declared
inside another package, no inheritance relationship is implied.
Parameters and variables cannot be declared in a package. The
definitions in a package should typically be related in some way, which
is the main reason they are placed in a particular package. Packages are
useful for a number of reasons:
\begin{itemize}
\item
Definitions that are related to some particular topic are typically
grouped into a package. This makes those definitions easier to find
and the code more understandable.
\item
Packages provide encapsulation and coarse-grained structuring
that reduces the complexity of large systems. An important example is
the use of packages for construction of (hierarchical) class
libraries.
\item
Name conflicts between definitions in different packages are
eliminated since the package name is implicitly prefixed to names of
definitions declared in a package.
\item
Information hiding and encapsulation can be supported to some
extent by declaring \lstinline!protected! classes, types, and other
definitions that are available only inside the package and therefore
inaccessible to outside code.
\item
Modelica defines a method for locating a package by providing a
standard mapping of package names to storage places, typically file or
directory locations in the file system.
\end{itemize}
\section{Package as Specialized Class}\label{package-as-specialized-class}
The package concept is a specialized class (\cref{specialized-classes}), using the
keyword \lstinline!package!.
\section{Importing Definitions from a Package}\label{importing-definitions-from-a-package}
The \lstinline!import!-clause makes public classes and other public definitions declared in some package available for use by shorter names in a class or a package.
It is the only way of referring to definitions declared in some other package for use inside an encapsulated package or class.
\begin{nonnormative}
The \lstinline!import!-clauses in a package or class fill the following two needs:
\begin{itemize}
\item
Making definitions from other packages available for use (by shorter names) in a package or class.
\item
Explicit declaration of usage dependences on other packages.
\end{itemize}
\end{nonnormative}
%TODO-FORMAT Should be formatted using tabs or tabular?
An \lstinline!import!-clause\indexinline{import} can occur in one of the following syntactic forms:
% Note a syntactic form cannot be written as a single \lstinline due to LaTeXML problem reported here:
% https://github.com/brucemiller/LaTeXML/issues/1274 (marked as fixed as of commit 80d7940)
% Instead, we need to break up the \lstinline in mysterious ways. Be sure to check that the generated HTML
% looks OK when making changes!
\lstinline!import $\mathit{definitionname}$;! (qualified import of top-level definition)
\lstinline!import $\mathit{packagename}$.!% Break up \lstinline as workaround for LaTeXML issue described above.
\lstinline!$\mathit{definitionname}$;! (qualified import)
\lstinline!import $\mathit{packagename}$.{$\mathit{def}_{1}$, $\mathit{def}_{2}$, $\ldots$, $\mathit{def}_{n}$};! (multiple definition import)
\lstinline!import $\mathit{packagename}$.*;! (unqualified import)
\lstinline!import $\mathit{shortname}$ = $\mathit{definitionname}$;! (renaming import of top-level definition)
\lstinline!import $\mathit{shortname}$ = $\mathit{packagename}$.!% Break up \lstinline as workaround for LaTeXML issue described above.
\lstinline!$\mathit{definitionname}$;! (renaming import)
Here $\mathit{packagename}$ is the fully qualified name of the imported package including possible dot notation and $\mathit{definitionname}$ is the name of an element in a package. The multiple definition import is equivalent to multiple single definition imports with corresponding $\mathit{packagename}$ and definition names.
\subsection{Lookup of Imported Names}\label{lookup-of-imported-names}
This section only defines how the imported name is looked up in the \lstinline!import!-clause.
For lookup in general -- including how \lstinline!import!-clauses are used -- see \cref{static-name-lookup}.
Lookup of the name of an imported package or class deviates from the normal lexical lookup.
For example, consider \lstinline!A.B.C! in the \lstinline!import!-clauses \lstinline!import A.B.C;!, \lstinline!import D = A.B.C;!, or \lstinline!import A.B.C.*;!.
Here, lookup starts with the lexical lookup of the first part of the name (\lstinline!A!) at the top level.
Qualified \lstinline!import!-clauses may only refer to packages or elements of packages, i.e., in \lstinline!import A.B.C;! or \lstinline!import D = A.B.C;!, \lstinline!A.B! must be a package.
Unqualified \lstinline!import!-clauses may only import from packages, i.e., in \lstinline!import A.B.*;!, \lstinline!A.B! must be a package.
\begin{nonnormative}
In \lstinline!import A;! the class \lstinline!A! can be any class which is an element of the unnamed top-level package.
\end{nonnormative}
\begin{nonnormative}
For example, if the package \lstinline!ComplexNumbers! would have been declared as a subpackage inside the package \lstinline!Modelica.Math!, its fully qualified name would be
\lstinline!Modelica.Math.ComplexNumbers!. $\mathit{definitionname}$ is the simple name without dot notation of a single definition that is imported. A $\mathit{shortname}$ is
a simple name without dot notation that can be used to refer to the package after import instead of the presumably much longer $\mathit{packagename}$.
The forms of \lstinline!import! are exemplified below assuming that we want to access the addition operation of the hypothetical package \lstinline!Modelica.Math.ComplexNumbers!:
\begin{lstlisting}[language=modelica]
import Modelica.Math.ComplexNumbers; // Accessed by ComplexNumbers.Add
import Modelica.Math.ComplexNumbers.Add; // Accessed by Add
import Modelica.Math.ComplexNumbers.{Add,Sub}; // Accessed by Add and Sub
import Modelica.Math.ComplexNumbers.*; // Accessed by Add
import Co = Modelica.Math.ComplexNumbers; // Accessed by Co.Add
\end{lstlisting}
\end{nonnormative}
\subsection{Rules for Import-Clauses}\label{summary-of-rules-for-import-clauses}\label{rules-for-import-clauses}
The following rules apply to \lstinline!import!-clauses:
\begin{itemize}
\item
The \lstinline!import!-clauses are \emph{not} inherited.
\item
The \lstinline!import!-clauses are not named elements of a class or package.
This means that \lstinline!import!-clauses cannot be changed by modifiers or redeclarations.
\item
The \emph{order} of \lstinline!import!-clauses does not matter.
\item
One can only import \emph{from} packages, not from other kinds of classes.
Both packages and classes can be imported \emph{into} i.e., they may contain \lstinline!import!-clauses.
\item
An imported package or definition should always be referred to by its fully qualified name in the \lstinline!import!-clause.
\item
Multiple qualified \lstinline!import!-clauses shall not have the same import name (see \cref{simple-name-lookup}).
\end{itemize}
\section{The Modelica Library Path -- MODELICAPATH}\label{the-modelica-library-path-modelicapath}
The top-level scope implicitly contains a number of classes stored externally.
If a top-level name is not found at global scope, a Modelica translator shall look up additional classes in an ordered list of library roots, called \lstinline!MODELICAPATH!\indexinline{MODELICAPATH}.
\begin{nonnormative}
The implementation of \lstinline!MODELICAPATH! is tool dependent. In order that a user can work in parallel with different Modelica tools, it is advisable to not
have this list as environment variable, but as a setting in the respective tool. Since \lstinline!MODELICAPATH! is tool dependent, it is not specified in which way
the list of library roots is stored. Typically, on a Windows system \lstinline!MODELICAPATH! is a string with path names separated by `\filename{;}' whereas on a Linux system
it is a string with path names separated by a `\filename{:}'.
\end{nonnormative}
In addition a tool may define an internal list of libraries, since it is
in general not advisable for a program installation to modify global
environment variables. The version information for a library (as defined
in \cref{annotations-for-version-handling}) may also be used during this search to search for a
specific version of the library (e.g.\ if Modelica library version 2.2 is
needed and the first directory in \lstinline!MODELICAPATH! contain Modelica library
version 2.1, whereas the second directory contains Modelica version 2.2,
then Modelica library version 2.2 is loaded from the second directory.).
\begin{nonnormative}
The first part of the path \lstinline!A.B.C! (i.e., \lstinline!A!) is located by searching the ordered list of roots in \lstinline!MODELICAPATH!. If no root contains
\lstinline!A! the lookup fails. If \lstinline!A! has been found in one of the roots, the rest of the path is located in \lstinline!A!; if that fails, the entire lookup
fails without searching for \lstinline!A! in any of the remaining roots in \lstinline!MODELICAPATH!.
\end{nonnormative}
If during lookup a top-level name is not found in the unnamed top-level scope, the search continues in the package hierarchies stored in these directories.
\begin{example}
\Cref{fig:roots} below shows an example \lstinline!MODELICAPATH! = \filename{"C:\textbackslash{}library;C:\textbackslash{}lib1;C:\textbackslash{}lib2"}, with three
directories containing the roots of the package hierarchies \lstinline!Modelica!, \lstinline!MyLib!, and \lstinline!ComplexNumbers!. The first two are represented as
the subdirectories \filename{C:\textbackslash{}library\textbackslash{}Modelica} and \filename{C:\textbackslash{}lib1\textbackslash{}MyLib}, whereas the third is stored
as the file \filename{C:\textbackslash{}lib2\textbackslash{}ComplexNumbers.mo}.
\begin{figure}[H]
\begin{center}
\includegraphics{modelicapath}
\end{center}
\caption{Roots of package hierarchies, e.g., \lstinline!Modelica!, \lstinline!MyLib!, and \lstinline!ComplexNumbers! in
\lstinline!MODELICAPATH! = \filename{"C:\textbackslash{}library;C:\textbackslash{}lib1;C:\textbackslash{}lib2"}.}
\label{fig:roots}
\end{figure}
Assume that we want to access the package \lstinline!MyLib.Pack2! in \cref{fig:roots} above, e.g.\ through an \lstinline!import!-clause \lstinline!import MyLib.Pack2;!.
During lookup we first try to find a package \lstinline!MyLib! corresponding to the first part of the name in the import-statement.
It is not found in the top-level scope since it has not previously been loaded into the environment.
Since the name was not found in the top-level scope the search continues in the directories in the \lstinline!MODELICAPATH! in the specified order. For the search to succeed,
there must be a subdirectory \filename{MyLib} or a file \filename{MyLib.mo} in one of the directories mentioned in the \lstinline!MODELICAPATH!. If there is no such
subdirectory or file, the lookup fails. If \filename{MyLib} is found in one of the directories, the rest of the name, in this case \lstinline!Pack2!, is located in
\filename{MyLib}. If that fails, the entire lookup fails without continuing the search in possibly remaining directories.
In this example the name matches the subdirectory named \filename{MyLib} in the second directory \filename{C:\textbackslash{}lib1} mentioned in the \lstinline!MODELICAPATH!.
This subdirectory must have a file \filename{package.mo} containing a definition of the package \lstinline!MyLib!, according to the Modelica rules on how to map a package
hierarchy to the file system. The subpackage \lstinline!Pack2! is stored in its own subdirectory or file in the subdirectory \filename{MyLib}. In this case the search
succeeds and the package \lstinline!MyLib.Pack2! is loaded into the environment.
\end{example}
\section{File System Mapping of Package/Class}\label{mapping-package-class-structures-to-a-hierarchical-file-system}\label{file-system-mapping-of-package-class}
A package/class hierarchy may be represented in the hierarchical structure of the operating system (the file system).
For classes with version information see also \cref{mapping-of-versions-to-file-system}.
The nature of such an external entity falls into one of the following two groups:
\begin{itemize}
\item
Directory in the file system.
\end{itemize}
\begin{itemize}
\item
File in the file system.
\end{itemize}
Each Modelica file in the file-system is stored in UTF-8 format (defined by The Unicode Consortium; \url{https://unicode.org}). A deprecated feature is that the file may start with the UTF-8 encoded BOM (byte order mark; \lstinline!0xef 0xbb 0xbf!); this is treated as white-space in the grammar. Since the use of BOM is deprecated, tools can ignore any BOM when reading, and it is recommended to never write it.
\begin{nonnormative}
Tools may also store classes in data-base systems, but that is not standardized.
\end{nonnormative}
\subsection{Directory Hierarchy Mapping}\label{mapping-a-package-class-hierarchy-into-a-directory-hierarchy-structured-entity}\label{directory-hierarchy-mapping}
A directory shall contain a node, the file \filename{package.mo}.
The node shall contain a \lstinline[language=grammar]!stored-definition! that defines a class \lstinline!A! with a name matching the name of the structured entity.
\begin{nonnormative}
The node typically contains documentation and graphical information for a package, but may also contain additional elements of the class \lstinline!A!.
\end{nonnormative}
A directory may also contain one or more sub-entities (directories or
files). The sub-entities are mapped as elements of the class defined by
their enclosing structured entity. Two sub-entities shall not define classes with identical names
\begin{example}
If directory \filename{A} contains the three files \filename{package.mo}, \filename{B.mo} and \filename{C.mo}, the classes defined are \lstinline!A!,
\lstinline!A.B!, and \lstinline!A.C.!
\end{example}
\begin{example}
A directory shall not contain both the sub-directory \filename{A} and the file \filename{A.mo}.
\end{example}
In order to preserve the order of sub-entities it is advisable to create
a file \filename{package.order} where each line contains the name of one class or
constant (using its Modelica \lstinline!IDENT! form). If a \filename{package.order} is present when reading a structured entity
the classes and constants are added in this order; if the contents does
not exactly match the classes and constants in the package, the
resulting order is tool specific and a warning may be given. Classes and
constants that are stored in \filename{package.mo} are also present in
\filename{package.order} but their relative order should be identical to the one in
\filename{package.mo} (this ensures that the relative order between classes and
constants stored in different ways is preserved).
\subsection{Single File Mapping}\label{mapping-a-package-class-hierarchy-into-a-single-file-nonstructured-entity}\label{single-file-mapping}
When mapping a package or class-hierarchy to a file (e.g.\ the file \filename{A.mo}), that file shall only define a single class \lstinline!A! with a
name matching the name of the nonstructured entity. In a file hierarchy the files shall have the extension \filename{.mo}.
A \filename{.mo} file defining more than one class cannot be part of the mapping
to file-structure and it is an error if it is loaded from the
\lstinline!MODELICAPATH!.
\subsection{The within Clause}\label{the-within-clause}
A \lstinline!within!-clause has the following syntax:
\begin{lstlisting}[language=grammar]
within [ packageprefixname ] ";"
\end{lstlisting}%
\indexinline{within}
A non-top-level entity shall begin with a \lstinline!within!-clause which for the class defined in the entity specifies the location in the Modelica class hierarchy.
A top-level class may contain a \lstinline!within!-clause with no name.
For a sub-entity of an enclosing structured entity, the \lstinline!within!-clause shall designate the class of the enclosing entity; and this class must exist and must not have been defined using a short class definition.
\begin{example}
The subpackage \lstinline!Rotational! declared within
\lstinline!Modelica.Mechanics! has the fully qualified name
\lstinline!Modelica.Mechanics.Rotational!, which is formed by concatenating
the packageprefixname with the short name of the package. The
declaration of \lstinline!Rotational! could be given as below:
\begin{lstlisting}[language=modelica]
within Modelica.Mechanics;
package Rotational // Modelica.Mechanics.Rotational
$\ldots$
\end{lstlisting}
\end{example}
\section{External Resources}\label{external-resources}
In order to reference external resources from documentation (such as links and images in html-text) and/or to reference images in the \lstinline!Bitmap! annotation (see \cref{bitmap}).
Absolute URIs should be used, for example \filename{file:///} and the URI scheme \filename{modelica://} which can be used to retrieve resources associated with a package.
According to the URI specification scheme names are case-insensitive, but the lower-case form should be used, that is \filename{Modelica://} is allowed but \filename{modelica://} is the recommended form.
The Modelica-scheme\index{Modelica!URI scheme}\index{URI!Modelica} has the ability to reference a hierarchical structure of resources associated with packages.
The same structure is used for all kind of resource references, independent of use (external file, image in documentation, bitmap in icon layer, and link to external file in the documentation), and regardless of the storage mechanism.
Any Modelica-scheme URI containing a slash after the package-name is
interpreted as a reference to a resource. The \emph{authority} portion of the
URI is interpreted as a fully qualified package name and the \emph{path}
portion of the URI is interpreted as the path (relative to the package)
of the resource. Each storage scheme can define its own interpretation
of the path (but care should be taken when converting from one storage
scheme or when restructuring packages that resource references resolve
to the same resource). Any storage scheme should be constrained such
that a resource with a given path should be unique for any package name
that precedes it. The first part of the path shall not be the name of a
class in the package given by the authority.
When Modelica packages are stored hierarchically in a file-system (i.e.\ package \lstinline!A! in a directory \filename{A} containing \filename{package.mo}) the resource
\filename{modelica://A/Resources/C.jpg} should be stored in the file \filename{A/Resources/C.jpg}, it is not recommend to use \filename{modelica://A.B/C.jpg} for referencing
resources; it could be stored in the file \filename{A/B/C.jpg} -- which is counter-intuitive if \lstinline!A.B! is stored together with \lstinline!A!. When Modelica packages
are stored in other formats a similar mapping should be defined, such that a resource with a given path should be unique for any package name that precedes it. The first
part of the path shall not be the name of a class in the package given by the authority. As above for \filename{Modelica 3.2.1/package.mo} i.e.\ resources starting from
\filename{Modelica 3.2.1}, and \filename{modelica://Modelica.Mechanics/C.jpg} is \filename{Modelica 3.2.1/Mechanics/C.jpg} -- regardless of whether \lstinline!Modelica.Mechanics!
is stored in \filename{Modelica 3.2.1/package.mo}, \filename{Modelica 3.2.1/Mechanics.mo}, or \filename{Modelica 3.2.1/Mechanics/package.mo}.
For a Modelica-package stored as a single file, \filename{A.mo}, the resource
\filename{modelica://A/C.jpg} refers to a file \filename{C.jpg} stored in the same
directory as \filename{A.mo}, but using resources in this variant is not
recommended since multiple packages will share resources.
In case the name of the class contains quoted identifiers, the single-quote `\lstinline!`!'
and any reserved characters (`\lstinline!:!', `\lstinline!/!', `\lstinline!?!', `\lstinline!\#!', `\lstinline![!',
`\lstinline!]!', `\lstinline!@!', `\lstinline!!!', `\lstinline[mathescape=false]!\$!', `\lstinline!\&!', `\lstinline!(!', `\lstinline!)!', `\lstinline!*!', `\lstinline!+!',
`\lstinline!,!', `\lstinline!;!', `\lstinline!=!') should be percent-encoded as normal in URIs.
\begin{example}
Consider a top-level package \lstinline!Modelica! and a class
\lstinline!Mechanics! inside it, a reference such as
\filename{modelica://Modelica.Mechanics/C.jpg} is legal, while
\filename{modelica://Modelica/Mechanics/C.jpg} is illegal.
The references \filename{modelica://Modelica.Mechanics/C.jpg} and \filename{modelica://Modelica/C.jpg} must also refer to two distinct resources.
\end{example}
\section{Multilingual Descriptions}\label{multilingual-descriptions}
\begin{nonnormative}
Descriptive texts in a model or library are usually formulated in English.
This section describes how a tool can present the library in another language.
Translated Modelica text is provided by external files, so that no modification of the original Modelica text is required.
\end{nonnormative}
The texts in following Modelica constructs should be translated:
\begin{itemize}
\item description strings of component declarations and classes
\item strings in the following annotations:
\begin{itemize}
\item \lstinline!Text.string!, \lstinline!Text.textString!
\item \lstinline!missingInnerMessage!, \lstinline!obsolete!, \lstinline!unassignedMessage!
\item \lstinline!Dialog.group!, \lstinline!Dialog.tab!
\item
\lstinline!Dialog.loadSelector.caption!, \lstinline!Dialog.loadSelector.filter!,
\ifpdf\\\else\fi% Avoid comma ending up at beginning of wrapped line in PDF output.
\lstinline!Dialog.saveSelector.caption!, \lstinline!Dialog.saveSelector.filter!
\item \lstinline!Documentation.info!, \lstinline!Documentation.revisions!
\item \lstinline!Figure.title!, \lstinline!Figure.caption!, \lstinline!Figure.group!, \lstinline!Plot.title!, \lstinline!Axis.label!, \lstinline!Curve.legend!
\item \lstinline!mustBeConnected!
\end{itemize}
\end{itemize}
\begin{nonnormative}
None of the translatable constructs can have any impact on simulation results.
\end{nonnormative}
Comments (delimited as well as rest-of-line) are not translated.
Only constructs given entirely by one or more concatenated string literals are translated, using nothing but the operator \lstinline!+! for concatenation.
In order to have parameter values as part of the texts the special substitution syntax is preferable (see \cref{text} and \cref{variable-replacements}), and translators need to be aware of these substrings in order to make good translations.
\begin{example}
Consider:
\begin{lstlisting}[language=modelica]
annotation($\ldots$, Text(string = "1st Frequency: %f1"),
Text(string = "2nd Frequency: " + String(w2 / (2 * pi))), $\ldots$);
\end{lstlisting}
In this example only \lstinline!"1st Frequency is %f1."! can be translated; the second \lstinline!Text.string! doesn't consist entirely of concatenated string literals, and is hence completely excluded from translation.
\end{example}
The files to support translation must be provided along with the library.
They must be stored in the resources directory \filename{modelica://$\mathit{LibraryName}$/Resources/Language/}.
Two kind of files in \textcite{GettextManual} format have to be provided:
\begin{enumerate}
\item Template file \filename{$\mathit{LibraryName}$.pot} (Portable Object Template), one file per library which is stored as the resource \filename{modelica://$\mathit{LibraryName}$/Resources/Language/$\mathit{LibraryName}$.pot}.
It describes all translatable strings in the library, but does not contain any translations.
The pattern \filename{$\mathit{LibraryName}$} denotes the toplevel class name of the library.
\item One file for each supported language with the name \filename{$\mathit{LibraryName}$.$\mathit{language}$.po} (Portable Object), as the resource \filename{modelica://$\mathit{LibraryName}$/Resources/Language/$\mathit{LibraryName}$.$\mathit{language}$.po}.
This file is a copy of the associated template file, but extended with the translations in the specified language.
The pattern \filename{$\mathit{language}$} stands for the ISO 639-1 language code, e.g., \filename{de} or \filename{sv}.
\end{enumerate}
The detailed format of these files is described in \textcite{GettextManual}.
Use of translation files in other formats (including the binary MO file format) is not standardized in Modelica.
For Modelica translations, only the keywords \lstinline!msgctxt!, \lstinline!msgid! and \lstinline!msgstr! are used, meaning that a translation entry looks like this:
\begin{lstlisting}
#: $\mathit{filename}$:$\mathit{lineNumber}$
#, no-c-format
msgctxt $\mathit{messageContext}$
msgid $\mathit{messageIdentifier}$
msgstr $\mathit{messageTranslation}$
\end{lstlisting}
The restriction to a few keywords makes it easier for tools to support the format without relying on the implementation from \textcite{GettextManual}.
The use of \lstinline!no-c-format! ensures that translation tools will not parse \lstinline!"%class"! as the format specifier \lstinline!%c! followed by \emph{lass}.
\begin{nonnormative}
In the remainder of this section, several facts about the gettext specification are interleaved non-normatively for easy access to some of the gettext basics.
Always refer to the external gettext specification for full detail or in case of doubt.
All text strings are in double quotes and encoded with UTF-8 characters.
Comments start with an \lstinline!#! and are continued until the end of line.
Spaces outside strings are ignored and used as separators.
The files consist of a header and a body.
The header is marked with an empty \lstinline!msgid! and looks like this:
\begin{lstlisting}
# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2019-03-15 10:52+0100\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
\end{lstlisting}
All general terms in the header should be replaced by specific information.
Following the header, there is one translation entry for each string to be translated.
It can start with an optional comment describing the location (file name and line number) of the text to translate.
Multiple occurences of the same string can be listed here, separated by space.
\end{nonnormative}
The $\mathit{messageContext}$ following the keyword \lstinline!msgctxt! shall be the full name of the Modelica class (e.g., \lstinline!"Modelica.Blocks.Math.Sin"!) where the text appears.
Short class definitions do not appear here.
Texts in such classes belong to the enclosing full class definition.
The text string which shall be translated is used as $\mathit{messageIdentifier}$ (following the \lstinline!msgid! keyword), and shall contain the original string from the Modelica code.
% Describe down-quoting and concatenation of Modelica string literals.
Note that if a \lstinline!msgid! string is given more than once in the same context, all occurrences are translated with the same (last) translation!
\begin{nonnormative}
The $\mathit{messageTranslation}$ (following the keyword \lstinline!msgstr!) is the translation of $\mathit{messageIdentifier}$ and is typically edited using special tools for translators.
In the template file this string is empty by definition.
If this is empty in a language specific file the $\mathit{messageIdentifier}$ may be used instead.
\end{nonnormative}
\begin{nonnormative}
Since in Modelica control sequences also start with a backslash and another backslash is used to use sequences literally or to hide double quotes, no change is required here.
But Modelica allows strings to go over more than one line, gettext does not.
Therefore, line breaks in Modelica must be encoded with \lstinline!"\n"! for gettext.
In order to avoid long lines in the translated strings (following \lstinline!msgid! or \lstinline!msgstr!), strings may be split into smaller parts given on consecutive lines.
E.g., the Modelica description
\begin{lstlisting}
"A
B\"C" + "D\nE"
\end{lstlisting}
evaluates to:\par
\hspace{1em}\begin{minipage}{0.5\textwidth}
A\\
B"CD\\
E
\end{minipage}\par
which in the translation entry looks like:
\begin{lstlisting}
msgid ""
"A\n"
"B\"CD\n"
"E"
\end{lstlisting}
\end{nonnormative}
\begin{example}
Consider a simple sine-source:
\begin{lstlisting}[language=modelica]
within MyPackage.Sources;
model Sine "Sine"
parameter Frequency f=2 "Frequency";
RealOutput y=sin(2*pi*f); // Relying on imported types
/* Could add details. Note that this is not translated */
annotation(Icon(graphics={Text(extent={{0,0},{40,40}},
textString="Frequency: %f")}));
end Sine;
\end{lstlisting}
The entries for translating this model into Swedish could look like this:
\begin{lstlisting}
#: MyPackage/Sources/package.mo:10126
#, no-c-format
msgctxt "MyPackage.Sources.Sine"
msgid "Sine"
msgstr "Sinus"
#: MyPackage/Sources/package.mo:10127
#, no-c-format
msgctxt "MyPackage.Sources.Sine"
msgid "Frequency"
msgstr "Frekvens"
#: MyPackage/Sources/package.mo:10131
#, no-c-format
msgctxt "MyPackage.Sources.Sine"
msgid "Frequency: %f"
msgstr "Frekvens: %f"
\end{lstlisting}
\end{example}
\begin{nonnormative}
To support the translation of these strings a number of free and commercial tools exist in context of GNU gettext.
\end{nonnormative}