diff options
Diffstat (limited to 'macros/latex/contrib/stex/doc/packages/stex-mathhub.tex')
-rw-r--r-- | macros/latex/contrib/stex/doc/packages/stex-mathhub.tex | 89 |
1 files changed, 89 insertions, 0 deletions
diff --git a/macros/latex/contrib/stex/doc/packages/stex-mathhub.tex b/macros/latex/contrib/stex/doc/packages/stex-mathhub.tex new file mode 100644 index 0000000000..4b05134e70 --- /dev/null +++ b/macros/latex/contrib/stex/doc/packages/stex-mathhub.tex @@ -0,0 +1,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}
\ No newline at end of file |