From be2ecf658ef5a9896370a704f8ca0d01cdeb541e Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Wed, 29 Apr 2026 00:09:32 +0200 Subject: [PATCH] Improve presentation of file system mapping --- chapters/packages.tex | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/chapters/packages.tex b/chapters/packages.tex index 2527a52e1..7d1a4ade6 100644 --- a/chapters/packages.tex +++ b/chapters/packages.tex @@ -177,18 +177,16 @@ \section{The Modelica Library Path -- MODELICAPATH}\label{the-modelica-library-p \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: +Such an entity in the file system is either of: \begin{itemize} \item - Directory in the file system. -\end{itemize} - -\begin{itemize} + A \willintroduce{structured entity}: A directory containing a file named \filename{package.mo} (\cref{directory-hierarchy-mapping}). \item - File in the file system. + A \willintroduce{nonstructured entity}: A file with filename extension \filename{mo} (\cref{single-file-mapping}). \end{itemize} +For classes with version information, see also \cref{mapping-of-versions-to-file-system}. + 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\index{BOM (byte order mark)}\index{byte order mark} (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. @@ -200,19 +198,24 @@ \section{File System Mapping of Package/Class}\label{mapping-package-class-struc \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 \productionref{stored-definition} that defines a class \lstinline!A! with a name matching the name of the structured entity. +When mapping a package or class hierarchy to a directory, the directory is denoted a \firstuse{structured entity}. +The file content of the \filename{package.mo} inside the directory shall match \productionref{stored-definition} in the grammar, defining a single class with name matching the name of the 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!. +The \filename{package.mo} typically contains documentation and graphical information for a package, but may also contain additional elements of the package/class. \end{nonnormative} -A directory may also contain one or more sub-entities (directories or files). +A directory may also contain one or more sub-entities (structured or nonstructured, compare \cref{file-system-mapping-of-package-class}). 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. -Immediate sub-directories that contain a \filename{package.mo} are part of the package. + +\begin{nonnormative} It is recommended that immediate sub-directories not containing a \filename{package.mo} do not contain any file with the extension \filename{mo}. +An immediate sub-directory named identical to an element of the class, but without a \filename{package.mo} inside, is still related to the package hierarchy in the sense that it may contain external resources associated with the element class, see \cref{external-resources}. +Also more deeply nested sub-directories may be related to the package hierarchy in this sense. +\end{nonnormative} + \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.! @@ -229,8 +232,8 @@ \subsection{Directory Hierarchy Mapping}\label{mapping-a-package-class-hierarchy \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}), the file content shall match \productionref{stored-definition} in the grammar. -In this case, the \productionref{stored-definition} shall only define a single class whose name (here, \lstinline!A!) matches the name of the nonstructured entity. +When mapping a package or class hierarchy to a file (e.g., the file \filename{A.mo}), the file is denoted a \firstuse{nonstructured entity}. +The file content shall match \productionref{stored-definition} in the grammar, defining a single class with name (here, \lstinline!A!) matching the name of the entity. The filename shall have the extension \filename{mo}.