summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/stex/doc/packages/mathhub.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/stex/doc/packages/mathhub.tex')
-rw-r--r--macros/latex/contrib/stex/doc/packages/mathhub.tex89
1 files changed, 89 insertions, 0 deletions
diff --git a/macros/latex/contrib/stex/doc/packages/mathhub.tex b/macros/latex/contrib/stex/doc/packages/mathhub.tex
new file mode 100644
index 0000000000..4b05134e70
--- /dev/null
+++ b/macros/latex/contrib/stex/doc/packages/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