diff options
author | Karl Berry <karl@freefriends.org> | 2022-05-24 20:23:29 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2022-05-24 20:23:29 +0000 |
commit | d1a45dc92e84130c08386511a72d4ba1bc95b1b9 (patch) | |
tree | 0b41d5e406b7fb349d9c8a6fe3e05e255e2b92a9 /Master/texmf-dist/doc/latex/stex/packages/stex-mathhub.tex | |
parent | 36e380761892b6ddfed9ad4e5cd585a8b3ae17cc (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.tex | 166 |
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 |