Clean up non-normative content in packages.tex

chapters/packages.tex

@@ -61,27 +61,22 @@ \subsection{Importing Definitions from a Package}\doublelabel{importing-definiti
 \end{nonnormative}
 
 %TODO-FORMAT Should be formatted using tabs or tabular?
-\lstinline!An! import-clause can occur in one of the following five syntactic forms:
+An \lstinline!import!-clause can occur in one of the following five syntactic forms:
 
-\lstinline!import! \emph{packagename}\lstinline!;! (qualified import)
+\lstinline[mathescape=true]!import $\mathit{packagename}$;! (qualified import)
 
-\lstinline!import! {[}\emph{packagename}.{]}\emph{definitionname}\lstinline!;! (single
-definition import)
+\lstinline[mathescape=true]!import ${[}\mathit{packagename}$.${]}\mathit{definitionname}$;! (single definition import)
 
-\lstinline!import!
-{[}\emph{packagename}.{]}\{\emph{def1,def2,\ldots{}defN}\}\lstinline!;! (multiple
-definition import)
+\lstinline[mathescape=true]!import ${[}\mathit{packagename}$.${]}${$\mathit{def}_{1}$, $\mathit{def}_{2}$, $\ldots$, $\mathit{def}_{\mathrm{n}}$};! (multiple definition import)
 
-\lstinline!import! \emph{packagename}.*\lstinline!;! (unqualified import)
+\lstinline[mathescape=true]!import $\mathit{packagename}$.*;! (unqualified import)
 
-\lstinline!import! \emph{shortpackagename} = \emph{packagename}\lstinline!;! (renaming
-import)
+\lstinline[mathescape=true]!import $\mathit{shortpackagename}$ = $\mathit{packagename}$;! (renaming import)
 
-\lstinline!import! \emph{shortpackagename} =
-{[}\emph{packagename.{]}definitionname}\lstinline!;! (renaming single def. import)
+\lstinline[mathescape=true]!import $\mathit{shortpackagename}$ = ${[}\mathit{packagename}$.${]}\mathit{definitionname}$;! (renaming single def. import)
 
-Here \emph{packagename} is the fully qualified name of the imported
-package including possible dot notation and \emph{definitionname} is the
+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
 packagename and definition names.
@@ -101,9 +96,11 @@ \subsubsection{Lookup of Imported Names}\doublelabel{lookup-of-imported-names}
 packages, i.e., in \lstinline!import A.B.C;! or \lstinline!import D=A.B.C;!,
 \lstinline!A.B! must be a
 package. Unqualified import clauses may only import from packages, i.e.,
-in \lstinline!import A.B.*;!, \lstinline!A.B! must be a package. {[}\emph{Note: in} \lstinline!import A;!
-\emph{the class} \lstinline!A! \emph{can be any class which is an element of the
-unnamed top-level package}{]}
+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
@@ -151,7 +148,7 @@ \subsubsection{Summary of Rules for Import Clauses}\doublelabel{summary-of-rules
 \subsection{Mapping Package/Class Structures to a Hierarchical File System}\doublelabel{mapping-package-class-structures-to-a-hierarchical-file-system}
 
 Packages/classes may be represented in the hierarchical structure of the
-operating system {[}\emph{the file system}{]}. For classes with version
+operating system (the file system). For classes with version
 information see also \autoref{mapping-of-versions-to-file-system}. The nature of such an external
 entity falls into one of the following two groups:
 \begin{itemize}
@@ -167,25 +164,33 @@ \subsection{Mapping Package/Class Structures to a Hierarchical File System}\doub
 Each Modelica file in the file-system is stored in UTF-8 format (defined
 by The Unicode Consortium; \lstinline!http://www.unicode.org!) and may start with
 the UTF-8 encoded byte order mark (\lstinline!0xef 0xbb 0xbf!); this is treated as
-white-space in the grammar. \emph{{[}Tools may also store classes in
-data-base systems, but that is not standardized.{]}}
+white-space in the grammar.
+
+\begin{nonnormative}
+Tools may also store classes in data-base systems, but that is not standardized.
+\end{nonnormative}
 
 \subsubsection{Mapping a Package/Class Hierarchy into a Directory Hierarchy (Structured Entity)}\doublelabel{mapping-a-package-class-hierarchy-into-a-directory-hierarchy-structured-entity}
 
 A directory shall contain a node, the file \filename{package.mo}. The node shall contain a stored-definition that defines a class \lstinline!A! with a name
-matching the name of the structured entity. {[}\emph{The node typically
-contains documentation and graphical information for a package, but may
-also contain additional elements of the class} \lstinline!A!.{]}
+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. {[}\emph{For example, if directory} \filename{A}
-\emph{contains the three files} \filename{package.mo}, \filename{B.mo} \emph{and}
-\filename{C.mo}
-\emph{the classes defined are} \lstinline!A!, \lstinline!A.B!, \emph{and} \lstinline!A.C.!{]} Two
-sub-entities shall not define classes with identical names {[}\emph{for
-example, a directory shall not contain both the sub-directory} \filename{A}
-\emph{and the file} \filename{A.mo}{]}.
+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
@@ -200,10 +205,8 @@ \subsubsection{Mapping a Package/Class Hierarchy into a Directory Hierarchy (Str
 
 \subsubsection{Mapping a Package/Class Hierarchy into a Single File (Nonstructured Entity)}\doublelabel{mapping-a-package-class-hierarchy-into-a-single-file-nonstructured-entity}
 
-When mapping a package or class-hierarchy to a file {[}\emph{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
@@ -303,75 +306,62 @@ \subsection{The Modelica Library Path -- MODELICAPATH}\doublelabel{the-modelica-
 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!. {[}\emph{The implementation of}
-\lstinline!MODELICAPATH! \emph{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 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 `;' whereas on a
-Linux system it is a string with path names separated by a `:'.}{]}
+library roots, called \lstinline!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 \autoref{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 MODELICAPATH contain Modelica library
+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.).
 
-{[}\emph{The first part of the path} \lstinline!A.B.C! (\emph{i.e.}, \lstinline!A!) \emph{is
-located by searching the ordered list of roots in} \lstinline!MODELICAPATH!.
-\emph{If no root contains} \lstinline!A! \emph{the lookup fails}. \emph{If} \lstinline!A!
-\emph{has been found in one of the roots, the rest of the path is
-located in} A; \emph{if that fails, the entire lookup fails without
-searching} \emph{for} \lstinline!A! \emph{in any of the remaining roots in}
-\lstinline!MODELICAPATH!.{]}
+\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}
 
 \subsubsection{Example of Searching MODELICAPATH}\doublelabel{example-of-searching-modelicapath}
 
 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. {[}\emph{\autoref{fig:roots} below shows an example} \lstinline!MODELICAPATH! =
-\lstinline!"C:\library;C:\lib1;C:\lib2"!\emph{,
-with three directories containing the roots of the package hierarchies}
-\lstinline!Modelica! \emph{,} \lstinline!MyLib!\emph{, and} \lstinline!ComplexNumbers!\emph{. The first two are represented as the subdirectories}
-\filename{C:\textbackslash{}library\textbackslash{}Modelica} \emph{and}
-\filename{C:\textbackslash{}lib1\textbackslash{}MyLib}\emph{, whereas the third is stored
-as the file} \filename{C:\textbackslash{}lib2\textbackslash{}ComplexNumbers.mo}\emph{.}
+directories.
+
+\begin{example}
+\autoref{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]
-\caption{Roots of package hierarchies, e.g.,
-\texttt{Modelica}, \texttt{MyLib}, and \texttt{ComplexNumbers} in
-\texttt{MODELICAPATH ="C:\textbackslash library;C:\textbackslash lib1;C:\textbackslash lib2"}.}
+\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}
 \includegraphics[width=6in,height=2in]{modelicapath}
 \end{figure}
 
-\emph{Assume that we want to access the package} \lstinline!MyLib.Pack2! \emph{in
-\autoref{fig:roots} above, e.g. through an} \lstinline!import! \emph{clause}
-\lstinline!import MyLib.Pack2;!\emph{. During lookup we first try to find a package} \lstinline!MyLib!
-\emph{corresponding to the first part of the import name. It is not
-found in the top-level scope since it has not previously been loaded
-into the environment. }
-
-\emph{Since the name was not found in the top-level scope the search
-continues in the directories in the} \lstinline!MODELICAPATH! \emph{in the specified
-order. For the search to succeed, there must be a subdirectory} \lstinline!MyLib!
-\emph{or a file} \filename{MyLib.mo} \emph{in one of the directories mentioned in
-the} \lstinline!MODELICAPATH!\emph{. If there is no such subdirectory or file, the
-lookup fails. If} \lstinline!MyLib! \emph{is found in one of the directories, the
-rest of the name, in this case} \lstinline!Pack2!\emph{, is located in} \lstinline!MyLib!\emph{.
-If that fails, the entire lookup fails without continuing the search in
-possibly remaining directories.}
-
-\emph{In this example the name matches the subdirectory named} \lstinline!MyLib!
-\emph{in the second directory} \filename{C:\textbackslash{}lib1}
-\emph{mentioned in the} \lstinline!MODELICAPATH!\emph{. This subdirectory must have
-a file} \filename{package.mo} \emph{containing a definition of the package}
-\lstinline!MyLib!\emph{, according to the Modelica rules on how to map a package
-hierarchy to the file system. The subpackage} \lstinline!Pack2! \emph{is stored in
-its own subdirectory or file in the subdirectory} \filename{MyLib}\emph{. In this
-case the search succeeds and the package} \lstinline!MyLib.Pack2! \emph{is loaded
-into the environment.}{]}
+Assume that we want to access the package \lstinline!MyLib.Pack2! in \autoref{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 import name.  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}