Skip to content

Improve presentation of file system mapping #3890

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

Open
henrikt-ma wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Improve presentation of file system mapping #3890

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
31 changes: 17 additions & 14 deletions chapters/packages.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.!
Expand All @@ -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}.


Expand Down