summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/stex/doc/packages/stex-inheritance.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2022-05-25 03:01:13 +0000
committerNorbert Preining <norbert@preining.info>2022-05-25 03:01:13 +0000
commitf01a37f8311f33e32441d25bdadcda9dcdbd165d (patch)
treeefb861dfafff09d4bef8024c85a11f8c8deaba76 /macros/latex/contrib/stex/doc/packages/stex-inheritance.tex
parent0c7d079315627312627c83bc9ce6f5e4f1b436f6 (diff)
CTAN sync 202205250301
Diffstat (limited to 'macros/latex/contrib/stex/doc/packages/stex-inheritance.tex')
-rw-r--r--macros/latex/contrib/stex/doc/packages/stex-inheritance.tex132
1 files changed, 131 insertions, 1 deletions
diff --git a/macros/latex/contrib/stex/doc/packages/stex-inheritance.tex b/macros/latex/contrib/stex/doc/packages/stex-inheritance.tex
index 41631f94d2..be7c4e68ec 100644
--- a/macros/latex/contrib/stex/doc/packages/stex-inheritance.tex
+++ b/macros/latex/contrib/stex/doc/packages/stex-inheritance.tex
@@ -1 +1,131 @@
-\textcolor{red}{TODO: inheritance documentation} \ No newline at end of file
+\begin{sfragment}{Simple Inheritance and Namespaces}
+
+ \begin{function}{\importmodule,\usemodule}
+ \stexcode"\importmodule[Some/Archive]{path?ModuleName}" is only allowed within an
+ \stexcode"smodule"-environment and makes the symbols declared in |ModuleName|
+ available therein. Additionally the symbols of |ModuleName| will be exported if the
+ current module is imported somewhere else via \stexcode"\importmodule".
+
+ \stexcode"\usemodule" behaves the same way, but without exporting the content of the
+ used module.
+ \end{function}
+
+ It is worth going into some detail how exactly \stexcode"\importmodule"
+ and \stexcode"\usemodule" resolve their arguments to find
+ the desired module -- which is closely related to the
+ \emph{namespace} generated for a module, that is used to generate
+ its URI.
+
+ \begin{dangerbox}
+ Ideally, \sTeX would use arbitrary URIs for modules, with no
+ forced relationships between the \emph{logical} namespace
+ of a module and the \emph{physical} location of the file
+ declaring the module -- like \mmt does things.
+
+ Unfortunately, \TeX\ only provides very restricted access to
+ the file system, so we are forced to generate namespaces
+ systematically in such a way that they reflect the physical
+ location of the associated files, so that \sTeX can resolve
+ them accordingly. Largely, users need not concern themselves
+ with namespaces at all, but for completenesses sake, we describe
+ how they are constructed:
+
+ \begin{itemize}
+ \item If \stexcode"\begin{smodule}{Foo}"
+ \iffalse\end{smodule}\fi occurs in a file
+ |/path/to/file/Foo[.|\meta{lang}|].tex| which does not belong
+ to an archive, the namespace is |file://path/to/file|.
+ \item If the same statement occurs in a file
+ |/path/to/file/bar[.|\meta{lang}|].tex|, the namespace is
+ |file://path/to/file/bar|.
+ \end{itemize}
+
+ In other words: outside of archives, the namespace corresponds to
+ the file URI with the filename dropped iff it is equal to the
+ module name, and ignoring the (optional) language suffix.
+
+ If the current file is in an archive, the procedure is the same
+ except that the initial segment of the file path up to the archive's
+ |source|-folder is replaced by the archive's namespace URI.
+\end{dangerbox}
+
+\begin{dangerbox}
+ Conversely, here is how namespaces/URIs and file paths are computed
+ in import statements, examplary \stexcode"\importmodule":
+
+ \begin{itemize}
+ \item \stexcode"\importmodule{Foo}" outside of an archive refers
+ to module |Foo| in the current namespace. Consequently, |Foo|
+ must have been declared earlier in the same document or, if not,
+ in a file |Foo[.|\meta{lang}|].tex| in the same directory.
+ \item The same statement \emph{within} an archive refers to either
+ the module |Foo| declared earlier in the same document, or
+ otherwise to the module |Foo| in the archive's top-level namespace.
+ In the latter case, is has to be declared in a file |Foo[.|\meta{lang}|].tex|
+ directly in the archive's |source|-folder.
+ \item Similarly, in \stexcode"\importmodule{some/path?Foo}" the path
+ |some/path| refers to either the sub-directory and relative
+ namespace path of the current directory and namespace outside of an archive,
+ or relative to the current archive's top-level namespace and |source|-folder,
+ respectively.
+
+ The module |Foo| must either be declared in the file
+ \meta{top-directory}|/some/path/Foo[.|\meta{lang}|].tex|, or in
+ \meta{top-directory}|/some/path[.|\meta{lang}|].tex| (which are
+ checked in that order).
+ \item Similarly, \stexcode"\importmodule[Some/Archive]{some/path?Foo}"
+ is resolved like the previous cases, but relative to the archive
+ |Some/Archive| in the mathhub-directory.
+ \item Finally, \stexcode"\importmodule{full://uri?Foo}" naturally refers to the
+ module |Foo| in the namespace |full://uri|. Since the file this module
+ is declared in can not be determined directly from the URI, the module
+ must be in memory already, e.g. by being referenced earlier in the
+ same document.
+
+ Since this is less compatible with a modular development, using full
+ URIs directly is strongly discouraged, unless the module is delared in
+ the current file directly.
+ \end{itemize}
+
+ \end{dangerbox}
+
+ \begin{function}{\STEXexport}
+ \stexcode"\importmodule" and \stexcode"\usemodule" import all symbols, notations,
+ semantic macros and (recursively) \stexcode"\importmodule"s. If you want to
+ additionally export e.g. convenience macros and other (\sTeX) code from a module, you
+ can use the command \stexcode"\STEXexport{<code>}" in your module. Then |<code>| is
+ executed (both immediately and) every time the current module is opened via
+ \stexcode"\importmodule" or \stexcode"\usemodule".
+ \end{function}
+
+ \begin{dangerbox}
+ For persistency reasons, everything in an \stexcode"\STEXexport"
+ is digested by \TeX in the \LaTeX3-category code scheme.
+ This means that the characters \stexcode"_" and \stexcode":"
+ are considered \emph{letters} and valid parts of
+ control sequence names, and space characters are ignored entirely.
+ For spaces, use the character \stexcode"~" instead, and
+ keep in mind, that if you want to use subscripts, you
+ should use \stexcode"\c_math_subscript_token" instead
+ of \stexcode"_"!
+
+
+ Also note, that \stexcode"\newcommand" defines macros \emph{globally}
+ and throws an error if the macro already exists,
+ potentially leading to low-level \LaTeX\xspace errors if
+ we put a \stexcode"\newcommand" in an \stexcode"\STEXexport"
+ and the |<code>| is executed more than once in a document
+ -- which can happen easily.
+
+ A safer alternative is to use macro definition principles,
+ that are safe to use even if the macro being defined already
+ exists, and ideally are local to the current \TeX\xspace group,
+ such as \stexcode"\def" or \stexcode"\let".
+ \end{dangerbox}
+
+\end{sfragment}
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "../stex-manual"
+%%% End: