summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/stex/doc/packages/stex-inheritance.tex
blob: be7c4e68ec05e5051be468c9c4f7e7f5eb41d99b (plain)
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: