summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/stex/doc/packages/mathhub.tex
blob: 4b05134e70d2dd6a681f105883b3ac8c2cd84bd8 (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
\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}