1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
\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:
|