From 379c3bfbcaccb8ba00049bc859e3d1e04f21c2b3 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Tue, 7 Nov 2023 23:07:24 +0100 Subject: [PATCH] Sentence-based line breaks in packages.tex --- chapters/packages.tex | 177 +++++++++++++++++------------------------- 1 file changed, 72 insertions(+), 105 deletions(-) diff --git a/chapters/packages.tex b/chapters/packages.tex index 49b034bac..1cdb7cb62 100644 --- a/chapters/packages.tex +++ b/chapters/packages.tex @@ -1,42 +1,30 @@ \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: +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. + 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. + 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. + 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. + 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. + 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!. +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} @@ -75,7 +63,9 @@ \section{Importing Definitions from a Package}\label{importing-definitions-from- \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. +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} @@ -94,9 +84,9 @@ \subsection{Lookup of Imported Names}\label{lookup-of-imported-names} \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}$. +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] @@ -108,6 +98,7 @@ \subsection{Lookup of Imported Names}\label{lookup-of-imported-names} \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: @@ -128,40 +119,34 @@ \subsection{Rules for Import-Clauses}\label{summary-of-rules-for-import-clauses} 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{:}'. +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.). +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 +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}. +\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} @@ -176,15 +161,16 @@ \section{The Modelica Library Path -- MODELICAPATH}\label{the-modelica-library-p 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. +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. +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} @@ -203,12 +189,15 @@ \section{File System Mapping of Package/Class}\label{mapping-package-class-struc 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. +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}. @@ -218,9 +207,9 @@ \subsection{Directory Hierarchy Mapping}\label{mapping-a-package-class-hierarchy 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 +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!, @@ -231,26 +220,21 @@ \subsection{Directory Hierarchy Mapping}\label{mapping-a-package-class-hierarchy 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). +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}. +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: @@ -263,8 +247,7 @@ \subsection{The within Clause}\label{the-within-clause} 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 \lstinline[language=grammar]!packageprefixname! with the short name of the package. +The subpackage \lstinline!Rotational! declared within \lstinline!Modelica.Mechanics! has the fully qualified name \lstinline!Modelica.Mechanics.Rotational!, which is formed by concatenating the \lstinline[language=grammar]!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; @@ -273,6 +256,7 @@ \subsection{The within Clause}\label{the-within-clause} \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}). @@ -282,16 +266,10 @@ \section{External Resources}\label{external-resources} 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 first \emph{segment} of the -\emph{path} of the URI is interpreted as a fully qualified package name and the rest of the \emph{path} -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. +Any Modelica-scheme URI containing a slash after the package-name is interpreted as a reference to a resource. +The first \emph{segment} of the \emph{path} of the URI is interpreted as a fully qualified package name and the rest of the \emph{path} 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 second segment of the path shall not be the name of a class in the package given by the first segment. As a deprecated feature the URI may start with \filename{modelica://} and use the host-part of the authority as the fully qualified package name. @@ -302,31 +280,21 @@ \section{External Resources}\label{external-resources} \end{nonnormative} 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 second -segment of the path shall not be the name of a class in the package given by the first segment. 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. +\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 second segment of the path shall not be the name of a class in the package given by the first segment. +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. +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}\index{translation!multilingual libraries} \begin{nonnormative} @@ -509,4 +477,3 @@ \section{Multilingual Descriptions}\label{multilingual-descriptions}\index{trans \begin{nonnormative} To support the translation of these strings a number of free and commercial tools exist in context of GNU gettext. \end{nonnormative} -