summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/stex/packages/stex-mathhub.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2022-05-24 20:23:29 +0000
committerKarl Berry <karl@freefriends.org>2022-05-24 20:23:29 +0000
commitd1a45dc92e84130c08386511a72d4ba1bc95b1b9 (patch)
tree0b41d5e406b7fb349d9c8a6fe3e05e255e2b92a9 /Master/texmf-dist/doc/latex/stex/packages/stex-mathhub.tex
parent36e380761892b6ddfed9ad4e5cd585a8b3ae17cc (diff)
stex (24may22)
git-svn-id: svn://tug.org/texlive/trunk@63390 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/stex/packages/stex-mathhub.tex')
-rw-r--r--Master/texmf-dist/doc/latex/stex/packages/stex-mathhub.tex166
1 files changed, 140 insertions, 26 deletions
diff --git a/Master/texmf-dist/doc/latex/stex/packages/stex-mathhub.tex b/Master/texmf-dist/doc/latex/stex/packages/stex-mathhub.tex
index 4b05134e70d..fb872acfbad 100644
--- a/Master/texmf-dist/doc/latex/stex/packages/stex-mathhub.tex
+++ b/Master/texmf-dist/doc/latex/stex/packages/stex-mathhub.tex
@@ -1,5 +1,6 @@
\begin{sfragment}{The Local MathHub-Directory}
- |\usemodule|, |\importmodule|, |\inputref| etc. allow for
+ \stexcode"\usemodule", \stexcode"\importmodule",
+ \stexcode"\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
@@ -7,30 +8,30 @@
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:
+ \sTeX knows where this folder is via one of four 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.
+ \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.
+ \stexcode"\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.
+ \item Finally, if all else fails, \sTeX will look for a file
+ |~/.stex/mathhub.path|. If this file exists, \sTeX will assume that it contains the
+ path to the local |MathHub|-directory. This method is recommended on systems where
+ it is difficult to set environment variables.
\end{enumerate}
\end{sfragment}
\begin{sfragment}{The Structure of \sTeX Archives}
- An \sTeX archive |group/name| needs to be stored in the
+ An \sTeX archive |group/name| is 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
@@ -43,19 +44,41 @@
|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|.
+ look for files included via \stexcode"\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|
+ has a |/lib|-subdirectory, it too will be searched by \stexcode"\libinput"
from all tex files in any archive in the |group/*|-group.
+
+ \paragraph{} We recommend the following additional directory structure in the
+ |source|-folder of an \sTeX archive:
+ \begin{itemize}
+ \item |/source/mod/| -- individual \sTeX modules, containing
+ symbol declarations, notations, and
+ \stexcode"\begin{sparagraph}[type=symdoc,for=...]"
+ environments for ``encyclopaedic'' symbol documentations
+ \iffalse\end{sparagraph}\fi
+ \item |/source/def/| -- definitions
+ \item |/source/ex/| -- examples
+ \item |/source/thm/| -- theorems, lemmata and proofs; preferably
+ proofs in separate files to allow for multiple proofs for the
+ same statement
+ \item |/source/snip/| -- individual text snippets such as remarks,
+ explanations etc.
+ \item |/source/frag/| -- individual document fragments,
+ ideally only \stexcode"\inputref"ing snippets, definitions,
+ examples etc. in some desirable order
+ \item |/source/tikz/| -- tikz images, as individual |.tex|-files
+ \item |/source/PIC/| -- image files.
+ \end{itemize}
+
\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:
+ The |MANIFEST.MF| in the |META-INF|-directory consists of key-value-pairs, informing
+ \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}
@@ -86,4 +109,95 @@
e.g. for |lmh install|.
\end{itemize}
-\end{sfragment} \ No newline at end of file
+\end{sfragment}
+
+\begin{sfragment}{Using Files in \sTeX Archives Directly}
+ Several macros provided by \sTeX allow for directly including
+ files in repositories. These are:
+ \begin{function}{\mhinput}
+ \stexcode"\mhinput[Some/Archive]{some/file}" directly
+ inputs the file |some/file| in the |source|-folder of
+ |Some/Archive|.
+ \end{function}
+ \begin{function}{\inputref}
+ \stexcode"\inputref[Some/Archive]{some/file}" behaves like \stexcode"\mhinput", but
+ wraps the input in a |\begingroup ... \endgroup|. When converting to |xhtml|, the
+ file is not input at all, and instead an |html|-annotation is inserted that
+ references the file, e.g. for lazy loading.
+
+ In the majority of practical cases \stexcode"\inputref" is likely to be preferred
+ over \stexcode"\mhinput" because it leads to less duplication in the generated
+ |xhtml|.
+ \end{function}
+ \begin{function}{\ifinput}
+ Both \stexcode"\mhinput" and \stexcode"\inputref"
+ set \stexcode"\ifinput" to ``true'' during input. This allows
+ for selectively including e.g. bibliographies only if the
+ current file is not being currently included in a larger document.
+ \end{function}
+ \begin{function}{\addmhbibresource}
+ \stexcode"\addmhbibresource[Some/Archive]{some/file}" searches for a file like
+ \stexcode"\mhinput" does, but calls |\addbibresource| to the result and looks for
+ the file in the archive root directory directly, rather than the |source|
+ directory. Typical invocations are
+ \begin{itemize}
+ \item |\addmhbibresource{lib/refs.bib}|, which specifies a bibliography in the |lib|
+ folder in the local archive or
+ \item |\addmhbibresource[HW/meta-inf]{lib/refs.bib}| in another.
+ \end{itemize}
+ \end{function}
+ \begin{function}{\libinput}
+ \stexcode"\libinput{some/file}"
+ searches for a file |some/file| in
+ \begin{itemize}
+ \item the |lib|-directory of the current archive, and
+ \item the |lib|-directory of a |meta-inf|-archive in
+ (any of) the archive groups containing the current archive
+ \end{itemize}
+ and include all found files in reverse order;
+ e.g. \stexcode"\libinput{preamble}" in a |.tex|-file in
+ |smglom/calculus| will \emph{first} input |.../smglom/meta-inf/lib/preamble.tex|
+ and then |../smglom/calculus/lib/preamble.tex|.
+
+ \stexcode|\libinput| will throw an error if \emph{no} candidate for |some/file|
+ is found.
+ \end{function}
+ \begin{function}{\libusepackage}
+ \stexcode"\libusepackage[package-options]{some/file}" searches for a file
+ |some/file.sty| in the same way that \stexcode"\libinput" does, but will
+ call\\
+ |\usepackage[package-options]{path/to/some/file}| instead of |\input|.
+
+ \stexcode|\libusepackage| throws an error if not \emph{exactly one} candidate for
+ |some/file| is found.
+ \end{function}
+
+ \begin{remark}
+ A good practice is to have individual \sTeX fragments
+ follow basically this document frame:
+ \begin{latexcode}[gobble=12]
+ \documentclass{stex}
+ \libinput{preamble}
+ \begin{document}
+ ...
+ \ifinputref \else \libinput{postamble} \fi
+ \end{document}
+ \end{latexcode}
+ Then the |preamble.tex| files can take care of loading the generally required
+ packages, setting presentation customizations etc. (per archive or archive group
+ or both), and |postamble.tex| can e.g. print the bibliography, index etc.
+
+ \stexcode|\libusepackage| is particularly useful in |preamble.tex| when we want to
+ use custom packages that are not part of {\TeX}Live. In this case we commit the
+ respective packages in one of the |lib| folders and use \stexcode|\libusepackage|
+ to load them.
+ \end{remark}
+\end{sfragment}
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "../stex-manual"
+%%% End:
+
+%%% LocalWords: mathhub symdoc,for lmh subdirs arithmetics,smglom sets,smglom mv,smglom
+%%% LocalWords: linear-algebra,smglom