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
|
\begin{sfragment}{The Local MathHub-Directory}
|\usemodule|, |\importmodule|, |\inputref| etc. allow for
including content modularly without having to specify absolute
paths, which would differ between users and machines. Instead,
\sTeX uses \emph{archives} that determine the global
namespaces for symbols and statements and make it possible
for \sTeX to find content referenced via such URIs.
All \sTeX archives need to exist in the local |MathHub|-directory.
\sTeX knows where this folder is via one of three means:
\begin{enumerate}
\item If the \sTeX package is loaded with the option
|mathhub=/path/to/mathhub|, then \sTeX will consider
|/path/to/mathhub| as the local |MathHub|-directory.
\item If the |mathhub| package option is \emph{not}
set, but the macro |\mathhub| exists when the
\sTeX-package is loaded, then this macro is
assumed to point to the local |MathHub|-directory; i.e.
|\def\mathhub{/path/to/mathhub}\usepackage{stex}|
will set the |MathHub|-directory as |path/to/mathhub|.
\item Otherwise, \sTeX will attempt to retrieve the
system variable |MATHHUB|, assuming it will
point to the local |MathHub|-directory. Since this
variant needs setting up only \emph{once} and is
machine-specific (rather than defined in tex code),
it is compatible with collaborating and sharing tex
content, and hence recommended.
\end{enumerate}
\end{sfragment}
\begin{sfragment}{The Structure of \sTeX Archives}
An \sTeX archive |group/name| needs to be stored in the
directory |/path/to/mathhub/group/name|; e.g. assuming your
local |MathHub|-directory is set as |/user/foo/MathHub|, then
in order for the |smglom/calculus|-archive to be found by the
\sTeX system, it needs to be in |/user/foo/MathHub/smglom/calculus|.
Each such archive needs two subdirectories:
\begin{itemize}
\item |/source| -- this is where all your tex files go.
\item |/META-INF| -- a directory containing a single file
|MANIFEST.MF|, the content of which we will consider shortly
\end{itemize}
An additional |lib|-directory is optional, and is where \sTeX will
look for files included via |\libinput|.
Additionally a \emph{group} of archives |group/name| may have
an additional archive |group/meta-inf|. If this |meta-inf|-archive
has a |/lib|-subdirectory, it too will be searched by |\libinput|
from all tex files in any archive in the |group/*|-group.
\end{sfragment}
\begin{sfragment}{MANIFEST.MF-Files}
The |MANIFEST.MF| in the |META-INF|-directory consists of
key-value-pairs, instructing \sTeX (and associated software)
of various properties of an archive. For example,
the |MANIFEST.MF| of the |smglom/calculus|-archive looks like this:
\begin{framed}
\begin{verbatim}
id: smglom/calculus
source-base: http://mathhub.info/smglom/calculus
narration-base: http://mathhub.info/smglom/calculus
dependencies: smglom/arithmetics,smglom/sets,smglom/topology,
smglom/mv,smglom/linear-algebra,smglom/algebra
responsible: Michael.Kohlhase@FAU.de
title: Elementary Calculus
teaser: Terminology for the mathematical study of change.
description: desc.html
\end{verbatim}
\end{framed}
Many of these are in fact ignored by \sTeX, but some are important:
\begin{itemize}
\item[|id|:] The name of the archive, including its group (e.g. |smglom/calculus|),
\item[|source-base|] or
\item[|ns|:] The namespace from which all symbol and module URIs
in this repository are formed, see (\textcolor{red}{TODO}),
\item[|narration-base:|] The namespace from which all document
URIs in this repository are formed, see (\textcolor{red}{TODO}),
\item[|url-base|:] The URL that is formed as a basis for \emph{external references},
see (\textcolor{red}{TODO}),
\item[|dependencies|:] All archives that this archive depends on. \sTeX ignores
this field, but \mmt can pick up on them to resolve dependencies,
e.g. for |lmh install|.
\end{itemize}
\end{sfragment}
|