summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/stex/stex/stex.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/stex/stex/stex.dtx')
-rw-r--r--Master/texmf-dist/source/latex/stex/stex/stex.dtx700
1 files changed, 700 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/stex/stex/stex.dtx b/Master/texmf-dist/source/latex/stex/stex/stex.dtx
new file mode 100644
index 00000000000..5fa948d9203
--- /dev/null
+++ b/Master/texmf-dist/source/latex/stex/stex/stex.dtx
@@ -0,0 +1,700 @@
+% \iffalse meta-comment
+% The sTeX packages all at once
+% Copyright (c) 2016 Michael Kohlhase, all rights reserved
+% this file is released under the
+% LaTeX Project Public License (LPPL)
+%
+% The original of this file is in the public repository at
+% http://github.com/KWARC/sTeX/
+% \fi
+%
+% \iffalse
+%<package|logo>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+%<package>\ProvidesPackage{stex}[2016/04/07 v1.0 Semantic Markup]
+%<logo>\ProvidesPackage{stex-logo}[2016/04/07 v1.0 sTeX Logo]
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{url,float,xspace,tikz}
+\usepackage[show]{ed}
+\usepackage[hyperref=auto,style=alphabetic,backend=bibtex]{biblatex}
+\addbibresource{kwarcpubs.bib}
+\addbibresource{extpubs.bib}
+\addbibresource{kwarccrossrefs.bib}
+\addbibresource{extcrossrefs.bib}
+\usepackage{stex-logo}
+\usepackage{ctangit}
+\usepackage{hyperref}
+\makeindex
+\def\latexml{\hbox{{\LaTeX}ML}\xspace}
+\floatstyle{boxed}
+\newfloat{exfig}{thp}{lop}
+\floatname{exfig}{Example}
+\def\xml{XML\xspace}
+\def\xslt{XSLT\xspace}
+\def\mathml{MathML\xspace}
+\def\omdoc{OMDoc\xspace}
+\def\smglom{SMGloM\xspace}
+\begin{document}\DocInput{stex.dtx}\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{36}
+%
+% \changes{v1.0}{2015/11/19}{self-documenting package}
+% \changes{v1.0}{2015/12/17}{Package dependency figure}
+% \changes{v1.0}{2016/04/06}{documenting all \protect\sTeX packages}
+%
+% \MakeShortVerb{\|}
+%
+% \title{Semantic Markup in {\TeX/\LaTeX}}
+% \author{Michael Kohlhase\\
+% Jacobs University, Bremen\\
+% \url{http://kwarc.info/kohlhase}}
+% \maketitle
+%
+% \begin{abstract}
+% We present a collection of {\TeX} macro packages that allow to markup {\TeX/\LaTeX}
+% documents semantically without leaving the document format, essentially turning
+% {\TeX/\LaTeX} into a document format for mathematical knowledge management (MKM).
+% \end{abstract}
+% \setcounter{tocdepth}{2}\tableofcontents\newpage
+%
+% \section{Introduction}
+%
+% The last few years have seen the emergence of various content-oriented {\xml}-based,
+% content-oriented markup languages for mathematics on the web, e.g.
+% OpenMath~\cite{BusCapCar:2oms04}, content MathML~\cite{CarIon:MathML03}, or our own
+% {\omdoc}~\cite{Kohlhase:OMDoc1.2}. These representation languages for mathematics, that
+% make the structure of the mathematical knowledge in a document explicit enough that
+% machines can operate on it. Other examples of content-oriented formats for mathematics
+% include the various logic-based languages found in automated reasoning tools
+% (see~\cite{RobVor:hoar01} for an overview), program specification languages (see
+% e.g.~\cite{Bergstra:as89}).
+%
+% The promise if these content-oriented approaches is that various tasks involved in ``doing
+% mathematics'' (e.g. search, navigation, cross-referencing, quality control, user-adaptive
+% presentation, proving, simulation) can be machine-supported, and thus the working
+% mathematician is relieved to do what humans can still do infinitely better than machines:
+% The creative part of mathematics --- inventing interesting mathematical objects,
+% conjecturing about their properties and coming up with creative ideas for proving these
+% conjectures. However, before these promises can be delivered upon (there is even a
+% conference series~\cite{MKM-IG-Meetings:online} studying ``Mathematical Knowledge
+% Management (MKM)''), large bodies of mathematical knowledge have to be converted into
+% content form.
+%
+% Even though {\mathml} is viewed by most as the coming standard for representing
+% mathematics on the web and in scientific publications, it has not not fully taken off in
+% practice. One of the reasons for that may be that the technical communities that need
+% high-quality methods for publishing mathematics already have an established method which
+% yields excellent results: the {\TeX/\LaTeX} system: and a large part of mathematical
+% knowledge is prepared in the form of {\TeX}/{\LaTeX} documents.
+%
+% {\TeX}~\cite{Knuth:ttb84} is a document presentation format that combines complex
+% page-description primitives with a powerful macro-expansion facility, which is utilized
+% in {\LaTeX} (essentially a set of {\TeX} macro packages, see~\cite{Lamport:ladps94}) to
+% achieve more content-oriented markup that can be adapted to particular tastes via
+% specialized document styles. It is safe to say that {\LaTeX} largely restricts content
+% markup to the document structure\footnote{supplying macros e.g. for sections,
+% paragraphs, theorems, definitions, etc.}, and graphics, leaving the user with the
+% presentational {\TeX} primitives for mathematical formulae. Therefore, even though
+% {\LaTeX} goes a great step into the direction of an MKM format, it is not, as it lacks
+% infrastructure for marking up the functional structure of formulae and mathematical
+% statements, and their dependence on and contribution to the mathematical context.
+%
+% \subsection{The {\xml} vs. {\TeX/\LaTeX} Formats and Workflows}
+%
+% {\mathml} is an {\xml}-based markup format for mathematical formulae, it is standardized
+% by the World Wide Web Consortium in {\cite{CarIon:MathML03}}, and is supported by the
+% major browsers. The {\mathml} format comes in two integrated components: presentation
+% {\mathml} presentation MathML and content {\mathml} content MathML. The former provides
+% a comprehensive set of layout primitives for presenting the visual appearance of
+% mathematical formulae, and the second one the functional/logical structure of the
+% conveyed mathematical objects. For all practical concerns, presentation {\mathml} is
+% equivalent to the math mode of {\TeX}. The text mode facilitates of {\TeX} (and the
+% multitude of {\LaTeX} classes) are relegated to other {\xml} formats, which embed
+% {\mathml}.
+%
+% The programming language constructs of {\TeX} (i.e. the macro definition
+% facilities\footnote{We count the parser manipulation facilities of {\TeX}, e.g. category
+% code changes into the programming facilities as well, these are of course impossible for
+% {\mathml}, since it is bound to {\xml} syntax.}) are relegated to the {\xml}
+% programming languages that can be used to develop language extensions.
+% transformation language {\xslt}~\cite{Deach:exls99,Kay:xpr00} or proper {\xml}-enabled
+% The {\xml}-based syntax and the separation of the presentational-, functional- and
+% programming/extensibility concerns in {\mathml} has some distinct advantages over the
+% integrated approach in {\TeX/\LaTeX} on the services side: {\mathml} gives us better
+% \begin{compactitem}
+% \item integration with web-based publishing,
+% \item accessibility to disabled persons, e.g. (well-written) {\mathml} contains enough
+% structural information to supports screen readers.
+% \item reusability, searchabiliby and integration with mathematical software systems
+% (e.g. copy-and-paste to computer algebra systems), and
+% \item validation and plausibility checking.
+% \end{compactitem}
+%
+% On the other hand, {\TeX/\LaTeX}/s adaptable syntax and tightly integrated programming
+% features within has distinct advantages on the authoring side:
+%
+% \begin{compactitem}
+% \item The {\TeX/\LaTeX} syntax is much more compact than {\mathml}, and if needed, the
+% community develops {\LaTeX} packages that supply new functionality in with a succinct
+% and intuitive syntax.
+% \item The user can define ad-hoc abbreviations and bind them to new control sequences to
+% structure the source code.
+% \item The {\TeX/\LaTeX} community has a vast collection of language extensions and best
+% practice examples for every conceivable publication purpose and an established and very
+% active developer community that supports these.
+% \item There is a host of software systems centered around the {\TeX/\LaTeX} language that
+% make authoring content easier: many editors have special modes for {\LaTeX}, there are
+% spelling/style/grammar checkers, transformers to other markup formats, etc.
+% \end{compactitem}
+%
+% In other words, the technical community is is heavily invested in the whole
+% {\index*{workflow}}, and technical know-how about the format permeates the
+% community. Since all of this would need to be re-established for a {\mathml}-based
+% workflow, the technical community is slow to take up {\mathml} over {\TeX/\LaTeX}, even
+% in light of the advantages detailed above.
+%
+% \subsection{A {\LaTeX}-based Workflow for {\xml}-based Mathematical Documents}
+%
+% An elegant way of sidestepping most of the problems inherent in transitioning from a
+% {\LaTeX}-based to an {\xml}-based workflow is to combine both and take advantage of the
+% respective advantages.
+%
+% The key ingredient in this approach is a system that can transform {\TeX\LaTeX} documents
+% to their corresponding {\xml}-based counterparts. That way, {\xml}-documents can be
+% authored and prototyped in the {\LaTeX} workflow, and transformed to {\xml} for
+% publication and added-value services, combining the two workflows.
+%
+% There are various attempts to solve the {\TeX/\LaTeX} to {\xml} transformation problem
+% (see ~\cite{StaGinDav:maacl09} for an overview); the most mature is probably Bruce
+% Miller's \latexml system~\cite{Miller:latexml:online}. It consists of two parts: a
+% re-implementation of the {\TeX} {\index*{analyzer}} with all of it's intricacies, and a
+% extensible {\xml} emitter (the component that assembles the output of the parser). Since
+% the {\LaTeX} style files are (ultimately) programmed in {\TeX}, the {\TeX} analyzer can
+% handle all {\TeX} extensions, including all of {\LaTeX}. Thus the \latexml parser can
+% handle all of {\TeX/\LaTeX}, if the emitter is extensible, which is guaranteed by the
+% \latexml binding language: To transform a {\TeX/\LaTeX} document to a given {\xml}
+% format, all {\TeX} extensions\footnote{i.e. all macros, environments, and syntax
+% extensions used int the source document} must have ``\latexml
+% bindings''\index{LaTeXML}{binding}, i.e. a directive to the \latexml emitter that
+% specifies the target representation in {\xml}.
+%
+% \subsection{Generating \protect\omdoc from \sTeX}
+%
+% The \sTeX packages (see Section~\ref{sec:packages}) provide functionalities for marking
+% up the functional structure of mathematical documents, so that the {\LaTeX} sources
+% contain enough information that can be exported to the \omdoc format (\underline{O}pen
+% \underline{M}athematical \underline{Doc}uments; see~\cite{Kohlhase:OMDoc1.2}). For the
+% actual transformation, we use a \latexml plugin~\cite{LaTeXMLsTeX:github:on} that
+% provides the \latexml bindings for the \sTeX packages.
+%
+% \subsection{Conclusion}\label{sec:concl}
+%
+% The {\stex} collection provides a set of semantic macros that extends the familiar and
+% time-tried {\LaTeX} workflow in academics until the last step of Internet publication of
+% the material. For instance, an {\smglom} module can be authored and maintained in
+% {\LaTeX} using a simple text editor, a process most academics in technical subjects are
+% well familiar with. Only in a last publishing step (which is fully automatic) does it get
+% transformed into the {\xml} world, which is unfamiliar to most academics.
+%
+% Thus, {\stex} can serve as a conceptual interface between the document author and MKM
+% systems: Technically, the semantically preloaded {\LaTeX} documents are transformed into
+% the (usually {\xml}-based) MKM representation formats, but conceptually, the ability to
+% semantically annotate the source document is sufficient.
+%
+% The {\stex} macro packages have been validated together with a case
+% study~\cite{Kohlhase04:stex}, where we semantically preload the course materials for a
+% two-semester course in Computer Science at Jacobs University Bremen and transform them to
+% the {\omdoc} MKM format.
+%
+% \subsection{Licensing, Download and Setup}\label{sec:setup}
+%
+% The {\stex} packages are licensed under the {\LaTeX} Project Public License~\cite{LPPL},
+% which basically means that they can be downloaded, used, copied, and even modified by
+% anyone under a set of simple conditions (e.g. if you modify you have to distribute under a
+% different name).
+%
+% \subsubsection{The \protect\sTeX Distribution}
+%
+% The {\stex} packages and classes are available from the Comprehensive {\TeX} Archive
+% Network (CTAN~\cite{CTAN:on}) and are part of the primary {\TeX/\LaTeX} distributions
+% (e.g. TeXlive~\cite{TeXLive:on} and MikTeX~\cite{MiKTeX:on}). The development version is
+% on GitHub~\cite{sTeX:github:on}, it can cloned or forked from the repository URL
+% \begin{center}
+% \url{https://github.com/KWARC/sTeX.git}
+% \end{center}
+% It is usually a good idea to enlarge the internal memory allocation of the \TeX/\LaTeX executables. This can be done by
+% adding the following configurations in \texttt{texmf.cnf} (or changing them, if they
+% already exist). Note that you will probably need \texttt{sudo} to do this.
+% \begin{footnotesize}\sf
+% \begin{verbatim}
+% max_in_open = 50 % simultaneous input files and error insertions,
+% param_size = 20000 % simultaneous macro parameters, also applies to MP
+% nest_size = 1000 % simultaneous semantic levels (e.g., groups)
+% stack_size = 10000 % simultaneous input sources
+% main_memory = 12000000
+% \end{verbatim}
+% \end{footnotesize}
+% After that, you have to run the
+% \begin{verbatim}
+% sudo fmtutil-sys --all
+% \end{verbatim}
+%
+% With this installation using \sTeX is as painless as using \LaTeX, just make sure the
+% \sTeX distribution is where \texttt{latex} can find it and run \texttt{pdflatex} over
+% the main file.
+%
+% \subsubsection{The \protect\sTeX Plugin for \protect\latexml}
+%
+% For the \omdoc transformation of \sTeX documents we use a \latexml plugin that provides
+% the \latexml bindings for the \sTeX packages. For installation and setup follow the
+% instructions at~\cite{LaTeXMLsTeX:github:on}\ednote{We are working on a CPAN submission
+% that should make installations painless.}
+%
+%\newpage
+% \section{The Packages of the \protect\stex Collection}\label{sec:packages}
+%
+% In the following, we will shortly preview the packages and classes in the {\stex}
+% collection. They all provide part of the solution of representing semantic structure in
+% the {\TeX/\LaTeX} workflow. We will group them by the conceptual level they
+% address. Figure~\ref{fig:packages} gives an overview.
+%
+% \subsection{The \protect\sTeX Distribution}\label{pkg:stex}
+%
+% The |stex| package provides |stex.sty| that just loads all packages below and passes
+% around the package options accordingly and |stex-logo.sty| that provides the macros
+% \DescribeMacro{\sTeX}|\sTeX| and \DescribeMacro{\stex}|\stex| that typeset the \sTeX
+% logo.
+%
+% \begin{figure}[ht]\centering
+% \begin{tikzpicture}[xscale=1.1]\tt
+% \node (metakeys) at (0,0) {metakeys};
+% \node (cpath) at (-2,0) {cpath};
+% \node (presentation) at (2.5,0) {presentation};
+%
+% \node (sref) at (0,1) {sref};
+% \node (cmath) at (2.5,1) {cmath};
+%
+% \node (rdfmeta) at (-2,2) {rdfmeta};
+% \node (modules) at (0,2) {modules};
+% \node (omdoc) at (1.5,2) {omdoc};
+% \node (sproof) at (3,2) {sproof};
+%
+% \node (wa) at (-2,3) {workaddress};
+% \node (omtext) at (0,3) {omtext};
+% \node (structview) at (3,3) {structview};
+%
+% \node (dcm) at (-2,4) {dcm};
+% \node (statements) at (0,4) {statements};
+% \node (stex-logo) at (3.5,4) {stex-logo};
+%
+% \node (problem) at (4.5,5) {problem};
+% \node (tikzinput) at (2.5,5) {tikzinput};
+% \node (stex) at (0,5) {stex};
+% \node (smultiling) at (-2,5) {smultiling};
+%
+% \node (smglomsty) at (-2,6) {smglom.sty};
+% \node (mikoslidessty) at (.5,6) {mikoslides.sty};
+% \node (hwexamsty) at (4.5,6) {hwexam.sty};
+%
+% \node (smglomcls) at (-2,7) {smglom.cls};
+% \node (mikoslidescls) at (.5,7) {mikoslides.cls};
+% \node (hwexamcls) at (4.5,7) {hwexam.cls};
+% \node (omdoccls) at (2.5,6.5) {omdoc.cls};
+%
+% \draw[->] (sref) -- (metakeys);
+% \draw[->] (cmath) -- (presentation);
+% \draw[->] (rdfmeta) -- (sref);
+% \draw[->] (wa) -- (modules);
+% \draw[->] (modules) -- (sref);
+% \draw[->] (modules) -- (cpath);
+% \draw[->] (omdoc) -- (sref);
+% \draw[->] (sproof) -- (sref);
+% \draw[->] (dcm) to[bend right=70] (rdfmeta);
+% \draw[->] (dcm) -- (wa);
+% \draw[->] (omtext) -- (modules);
+% \draw[->] (statements) -- (omtext);
+% \draw[->] (stex) -- (statements);
+% \draw[->] (stex) -- (dcm);
+% \draw[->] (stex) to[bend left=5] (sproof);
+% \draw[->] (stex) to[bend left=5] (structview);
+% \draw[->] (structview) -- (modules);
+% \draw[->] (stex) to[bend left=15] (cmath);
+% \draw[->] (stex) to[bend left=20] (omdoc);
+% \draw[->] (stex) -- (stex-logo);
+% \draw[->] (problem) -- (omtext);
+% \draw[->] (smglomsty) -- (smultiling);
+% \draw[->] (smglomsty) -- (statements);
+% \draw[->] (smglomcls) -- (smglomsty);
+% \draw[->] (smglomcls) -- (stex);
+% \draw[->] (mikoslidescls) -- (mikoslidessty);
+% \draw[->] (mikoslidescls) -- (smglomsty);
+% \draw[->] (mikoslidessty) -- (tikzinput);
+% \draw[->] (mikoslidessty) -- (stex);
+% \draw[->] (mikoslidessty) -- (smglomsty);
+% \draw[->] (hwexamcls) -- (hwexamsty);
+% \draw[->] (hwexamsty) -- (problem);
+% \draw[->] (omdoccls) to[bend right=20] (omdoc);
+%
+% \draw[->] (hwexamcls) -- (tikzinput);
+% \draw[->] (hwexamcls) to[bend right=10] (omdoccls);
+% \draw[->] (mikoslidescls) to[bend left=10] (omdoccls);
+% \draw[->] (smglomcls) to[bend right=10] (omdoccls);
+% \end{tikzpicture}
+% \caption{The \protect\sTeX packages and their dependencies.}\label{fig:packages}
+% \end{figure}
+%
+% \subsection{Content Markup of Mathematical Formulae in {\TeX/\LaTeX}}
+%
+% \subsubsection{\texttt{cmath}: Building Content Math Representations}\label{pkg:cmath}
+%
+% The |cmath| package (see~\ctancite{Kohlhase:cmath}) supplies an interface for building
+% content math representations. It gives special macros for marking up variables,
+% applications and bindings. It supports the transformation into both
+% OpenMath~\cite{BusCapCar:2oms04} and content MathML~\cite{CarIon:MathML03}.
+%
+% \subsubsection{{\texttt{presentation}}: Flexible Presentation for Semantic
+% Macros}\label{pkg:presentation}
+%
+% The {\texttt{presentation}} package (see~\ctancite{Kohlhase:ipsmsl}) supplies an
+% infrastructure that allows to specify the presentation of semantic macros, including
+% preference-based bracket elision. This allows to markup the functional structure of
+% mathematical formulae without having to lose high-quality human-oriented presentation in
+% {\LaTeX}. Moreover, the notation definitions can be used by MKM systems for added-value
+% services, either directly from the {\sTeX} sources, or after translation.
+%
+% \subsection{Mathematical Statements}
+%
+% \subsubsection{{\texttt{statements}}: Extending Content Macros for Mathematical
+% Notation}\label{pkg:statements}
+%
+% The \texttt{statements} package (see\ctancite{Kohlhase:smms}) provides semantic markup
+% facilities for mathematical statements like Theorems, Lemmata, Axioms, Definitions,
+% etc. in {\stex} files. This structure can be used by MKM systems for added-value services,
+% either directly from the {\sTeX} sources, or after translation.
+%
+% \subsubsection{{\texttt{sproof}}: Extending Content Macros for Mathematical
+% Notation}\label{pkg:sproof}
+%
+% The \texttt{sproof} package (see~\ctancite{Kohlhase:smp}) supplies macros and environment
+% that allow to annotate the structure of mathematical proofs in {\stex} files. This
+% structure can be used by MKM systems for added-value services, either directly from the
+% {\sTeX} sources, or after translation.
+%
+% \subsubsection{\texttt{omtext}: Mathematical Text}\label{pkg:omtext}
+% \ednote{say something}
+%
+% \subsection{Context Markup for Mathematics}
+%
+% \subsubsection{{\texttt{modules}}: Extending Content Macros for Mathematical\
+% Notation}\label{pkg:modules}
+%
+% The \texttt{modules} package (see~\ctancite{KohAmb:smmssl}) supplies a definition
+% mechanism for semantic macros and a non-standard scoping construct for them, which is
+% oriented at the semantic dependency relation rather than the document structure. This
+% structure can be used by MKM systems for added-value services, either directly from the
+% {\sTeX} sources, or after translation. A side effect of this is that we have an
+% ``object-oriented'' inheritance mechanism for semantic macros: the semantic macros for
+% the mathematical objects described in a module come with the module itself. As a
+% consequence, the \textbf{modules signatures} (only the macro definitions, not the
+% descriptions) need to be loaded before they can be used somewhere else.
+%
+% \subsubsection{\texttt{smultiling}: Multilingual Mathematical
+% Modules}\label{pkg:smultiling}
+%
+% In multilingual settings, i.e. where we have multiple \sTeX documents that are
+% translations of each other, it is better to separate the module signature from the
+% descriptive document. \ednote{continue}
+%
+% \subsubsection{\texttt{structview}: Structures and Views}\label{pkg:structview}
+% \ednote{Say something}
+%
+% \subsection{Mathematical Document Classes}
+%
+% \subsubsection{OMDoc Documents}\label{pkg:omdoc}
+%
+% The \texttt{omdoc} package provides an infrastructure that allows to markup {\omdoc}
+% documents in {\LaTeX}. It provides \texttt{omdoc.cls}, a class with the and
+% {\texttt{omdocdoc.sty}}\ednote{continue}
+%
+% \subsubsection{\texttt{hwexam}: Homeworks and Exams}\label{pkg:hwexam}
+%
+% The \texttt{hwexam} package~\ctancite{Kohlhase:hwexam} provides |hwexam.cls| and
+% |hwexam.sty| for marking up homework assignments, and exams. The content markup strategy
+% employed in \sTeX allows to specify -- and profit from -- administrative metadata such
+% as time and point counts. This package relies on the |problem|
+% package~\ctancite{Kohlhase:problem} which provides markup for problems, hints, and
+% solutions.
+%
+% \subsubsection{\texttt{mikoslides}: Slides and Course Notes}\label{pkg:mikoslides}
+%
+% The |mikoslides| package provides a document class from which we can generate both
+% course slides -- via the |beamer| classs -- and course notes -- via the |omdoc| class --
+% in a transparent way.
+%
+% \subsection{Metadata}
+%
+% \subsubsection{\texttt{rdfmeta}: RDFa Metadata for \protect\sTeX}\label{pkg:rdfmeta}
+% \ednote{Say something}
+%
+% \subsubsection{\texttt{dcm}: Dublin Core Metadata}\label{pkg:dcm}
+% \ednote{Say something}
+%
+% \subsubsection{\texttt{workaddress}: Markup for FOAF Metadata}\label{pkg:workaddress}
+% \ednote{Say something}
+%
+% \subsection{Support for MathHub}
+%
+% The |mathhub| package provides the supplementary packages |mikoslides-mh|,
+% |modules-mh.sty|, |omtext-mh.sty|, |problem-mh.sty|, |smultiling-mh.sty|,
+% |structview-mh.sty|, and |tikzinput-mh.sty| with variants of the user-visible macros
+% that are adapted to the MathHub system -- see Section~\ref{sec:mathhub} for details.
+%
+% \subsection{Auxiliary Packages}
+%
+% \subsubsection{\texttt{metakeys}: An extended key/value Interface}\label{pkg:metakeys}
+% \ednote{Say something}
+%
+% \subsubsection{\texttt{pathsuris}: Managing Relative/Absolute File Paths}\label{pkg:pathsuris}
+% \ednote{Say something}
+%
+% \subsubsection{\texttt{tikzinput}: External TIKZ Pictures as Standalone Images}\label{pkg:tikzinput}
+% \ednote{Say something}
+%
+% \newpage
+% \section{Workflows and Best Practices}\label{sec:workflows}
+%
+% \subsection{The ``Little Modules'' Approach}
+%
+% One of the key advantages of semantic markup with \sTeX is that the \sTeX sources are
+% highly reusable by the ``object-oriented'' inheritance model induced by \sTeX
+% modules. It turned out to be useful to divide \sTeX documents into three kinds of files:
+% \begin{compactenum}
+% \item \textbf{module files}: files that essentially contain a collection of \sTeX
+% modules~\ctancite{KohAmb:smmssl} -- usually a single one whose module name coincides
+% the file name base.
+% \item \textbf{fragment files}: files that contain a group of input references to module-
+% or fragment files -- usually one group deep for flexibility, transition text, and
+% additional remarks.
+% \item \textbf{driver files} that set up the document class, contain the preambles, and
+% input reference fragment files.
+% \end{compactenum}
+%
+% These correspond to the \sTeX documents, but can reuse and share \sTeX fragments and
+% modules. Figure~\ref{fig:reuse} shows a situation, where we have two courses given over
+% multiple years, which results in five course notes documents given by driver files, wich
+% share quite a few components. As drivers and fragment files are mostly content-free --
+% they only contribute document structure, this lets all documents contribute from the
+% development of the modules.
+%
+% \begin{figure}[ht]\centering
+% \begin{tikzpicture}\footnotesize
+% \tikzstyle{course} = [draw,rounded corners,inner sep=0pt]
+% \tikzstyle{topic} = [draw,inner sep=2pt]
+%
+% \node at (-1,0) {modules};
+% \node at (-1,1) {fragments};
+% \node at (-1,2) {drivers};
+%
+% \node[topic] (strings) at (1,0) {strings};
+% \node[topic] (pref) at (2.5,0) {\begin{tabular}{c}prefix\\codes\end{tabular}};
+% \node[topic] (codes) at (1.5,1) {codes};
+%
+% \node[topic] (xml) at (5.3,0) {DAG};
+% \node[topic] (uc) at (4,0) {Trees};
+% \node[topic] (html) at (4.5,1) {GraphTheo};
+%
+% \node[topic] (docbook) at (8,0) {NatDed};
+% \node[topic] (dita) at (6.8,0) {FOL};
+% \node[topic] (man) at (7.5,1) {Logic};
+%
+% \node[course] (gencs) at (3,2) {\begin{tabular}{c}GenCS\\2011\end{tabular}};
+% \node[course] (gencs10) at (1.5,2) {\begin{tabular}{c}GenCS\\2010\end{tabular}};
+% \node[course] (gencs12) at (4.5,2) {\begin{tabular}{c}GenCS\\2012\end{tabular}};
+% \node (gdots) at (3,1) {\ldots};
+% \node[course] (tdm) at (6.5,2) {\begin{tabular}{c}AdvCS\\2011\end{tabular}};
+% \node[course] (tdm12) at (8,2) {\begin{tabular}{c}AdvCS\\2012\end{tabular}};
+% \node (tdots) at (6,1) {\ldots};
+%
+% \draw (gencs) -- (strings) -- (codes);
+% \draw (gencs) -- (html) -- (uc);
+% \draw (tdm) -- (man) -- (docbook);
+% \draw (tdm) -- (html) -- (xml);
+% \draw (codes) -- (pref);
+% \draw (man) -- (dita);
+% \draw (gencs) -- (gdots);
+% \draw (tdm) -- (tdots);
+% \draw (gencs12) -- (codes);
+% \draw (gencs10) -- (codes);
+% \draw (gencs12) -- (gdots);
+% \draw (gencs10) -- (gdots);
+% \draw (gencs12) -- (html);
+% \draw (gencs10) -- (html);
+% \draw (tdm12) -- (html);
+% \draw (tdm12) -- (tdots);
+% \draw (tdm12) -- (man);
+% \end{tikzpicture}
+% \caption{Reuse of Fragments and Modules in a Course Notes Setting}\label{fig:reuse}
+% \end{figure}
+%
+% The downside of this ``object-oriented'' inheritance mechanism is that we need to keep
+% the module signatures (see Section~\ref{pkg:modules}) up to date adding to the
+% complexity of document management.
+%
+% Another advantage of the ``little modules approach'' is that modules can be developed
+% separately. Indeed all modules of a given subject share common pre- and post-ambles which
+% can be developed in special files -- usually named |pre.tex|, |post.tex|, and
+% |preamble.tex| (the latter is included in |pre.tex|). Given such a setup, the call to
+% |pdflatex| can be suitably adapted to handle the pre/postfixes.
+%
+% \subsection{Basic Utilities \& Makefiles}\label{sec:utilities}
+%
+% The \sTeX distribution contains three basic command line utilities to manage \sTeX
+% documents in the |bin| directory of the distribution.
+% \begin{description}
+% \item[\texttt{sms}] computes the \stex module signatures for a given \stex file
+% (see~\ctancite{KohAmb:smmssl} details).
+% \item[\texttt{filedate} and \texttt{checksum}] that help keeping the metadata of the
+% self-documenting {\LaTeX} packages in the \stex distribution up to date.
+% \item[\texttt{installFonts.sh}] that installs the fonts necessary for chinese \sTeX
+% documents.
+% \end{description}
+% These are supplemented by a set of UNIX |Makefiles| in the |lib/make| directory. The way
+% to use them is to include them into a |Makefile| in the directory and then run one of
+% the targets |pdf| and |mpdf| to make the PDF versions of the drivers and
+% modules\ednote{MK: what about the fragments?} and |omdoc| and |mods| to generate
+% \omdoc. Note that we need to |make sms| in order to make the respective \sTeX module
+% signatures for the modules.
+%
+% \subsection{MathHub: a Portal for Active Mathematical Documents}\label{sec:mathhub}
+%
+% MathHub (\url{http://mathhub.info} see~\cite{IanJucKoh:sdm14}) is a portal for Active
+% Mathematical Documents -- documents that are made context-aware and interactive by
+% semantic annotations. \sTeX is one of the main input formats for informal active
+% documents. MathHub supports \sTeX documents in three ways:
+% \begin{compactenum}
+% \item MathHub offers free/open hosting in document repositories for (mathematical) \sTeX
+% document collections.
+% \item the backend system supports the large-scale change- and error-management for \sTeX
+% documents in the ``little modules'' paradigm.
+% \item the front-end displays interactive (HTML5) documents generated from the \sTeX
+% sources (via \omdoc).
+% \end{compactenum}
+% The MathHub system is probably the best way of developing and hosting larger \sTeX
+% document collections. It offers two authoring workflows an online authoring workflow via
+% a direct web interface~\cite{MathHub:oa:on} or casual users and an offline authoring
+% workflow that we describe next.
+%
+% \subsection{\texttt{lmh}: MathHub's Build System Locally}\label{sec:lmh}
+%
+% As direct web editing workflows are not efficient for larger document collections, the
+% MathHub system offers an offline authoring system. This uses GIT repositories for
+% distribution -- the author develops the document collection on a local working copy and
+% then commits for inclusion to MathHub. The MathHub build system can be used locally for
+% efficient development via the |localmh| system~\cite{lmh:github:on}. In a nutshell --
+% see~\cite{MathHub:law:on} for details --
+% \begin{compactenum}
+% \item |localmh| is installed in a docker container that supplies the build system and
+% provides the |lmh| command suite.
+% \item |lmh pdf| formats \sTeX modules to PDF -- building all dependencies, e.g. module
+% signatures, first.
+% \item |lmh omdoc| generates \omdoc for \sTeX documents -- again with dependencies.
+% \item |lmh xhtml| generates active documents (in XHTML5) from the \sTeX sources or their
+% \omdoc versions.
+% \item |lmh| \meta{gitsc} distributes the git subcommand \meta{gitsc} over multiple
+% repositories.
+% \end{compactenum}
+% Various other |lmh| subcommands help with large-scale editing problems like renaming or
+% moving modules, translations in multilingual settings, etc.
+%
+% \StopEventually{\newpage\PrintIndex\newpage\PrintChanges\newpage\printbibliography}\newpage
+%
+% \newpage
+% \section{The Implementation}\label{sec:implementation}
+%
+% \subsection{Package Options}\label{sec:impl:options}
+%
+% The first step is to declare (a few) package options that handle whether certain
+% information is printed or not. They all come with their own conditionals that are set by
+% the options.
+%
+% \begin{macrocode}
+%<*package>
+\DeclareOption*{\PassOptionsToPackage{\CurrentOption}{statements}
+ \PassOptionsToPackage{\CurrentOption}{structview}
+ \PassOptionsToPackage{\CurrentOption}{sproofs}
+ \PassOptionsToPackage{\CurrentOption}{omdoc}
+ \PassOptionsToPackage{\CurrentOption}{cmath}
+ \PassOptionsToPackage{\CurrentOption}{dcm}}
+\ProcessOptions
+% \end{macrocode}
+%
+% Then we make sure that the necessary packages are loaded (in the right versions).
+% \begin{macrocode}
+\RequirePackage{stex-logo}
+\RequirePackage{statements}
+\RequirePackage{structview}
+\RequirePackage{sproof}
+\RequirePackage{omdoc}
+\RequirePackage{cmath}
+\RequirePackage{dcm}
+%</package>
+% \end{macrocode}
+%
+% \subsection{The \protect\sTeX Logo}\label{sec:impl:ids}
+%
+% To provide default identifiers, we tag all elements that allow |xml:id| attributes by
+% executing the |numberIt| procedure from |omdoc.sty.ltxml|.
+%
+% \begin{macrocode}
+%<*logo>
+\RequirePackage{xspace}
+\def\stex{%
+ \@ifundefined{texorpdfstring}%
+ {\let\texorpdfstring\@firstoftwo}%
+ {}%
+ \texorpdfstring{\raisebox{-.5ex}S\kern-.5ex\TeX}{sTeX}\xspace%
+}
+\def\sTeX{\stex}
+%</logo>
+% \end{macrocode}
+% \Finale
+\endinput
+% \iffalse
+%%% Local Variables:
+%%% mode: doctex
+%%% TeX-master: t
+%%% End:
+% \fi
+% LocalWords: GPL structuresharing STR dtx pts keyval xcomment CPERL DefKeyVal iffalse
+% LocalWords: RequirePackage Semiverbatim DefEnvironment OptionalKeyVals soln texttt baz
+% LocalWords: exnote DefConstructor inclprob NeedsTeXFormat omd.sty textbackslash exfig
+% LocalWords: stopsolution fileversion filedate maketitle setcounter tocdepth newpage uc
+% LocalWords: tableofcontents showmeta showmeta solutionstrue usepackage minipage hrule
+% LocalWords: linewidth elefants.prob Elefants smallskip noindent textbf startsolutions
+% LocalWords: startsolutions stopsolutions stopsolutions includeproblem includeproblem
+% LocalWords: textsf HorIacJuc cscpnrr11 includemhproblem includemhproblem importmodule
+% LocalWords: importmhmodule foobar ldots latexml mhcurrentrepos mh-variants mh-variant
+% LocalWords: compactenum langle rangle langle rangle ltxml metakeys newif ifexnotes rm
+% LocalWords: exnotesfalse exnotestrue ifhints hintsfalse hintstrue ifsolutions ifpts
+% LocalWords: solutionsfalse ptsfalse ptstrue ifmin minfalse mintrue ifboxed boxedfalse
+% LocalWords: boxedtrue sref mdframed marginpar prob srefaddidkey addmetakey refnum kv
+% LocalWords: newcounter ifx thesection theproblem hfill newenvironment metasetkeys ltx
+% LocalWords: stepcounter currentsectionlevel xspace ignorespaces surroundwithmdframed
+% LocalWords: omdoc autoopen autoclose solvedinminutes kvi qw vals newcommand exhint pgk
+% LocalWords: specialcomment excludecomment mhrepos xref marginpar addtocounter doctex
+% LocalWords: mh@currentrepos endinput stex Bergstra mathml ttb84 utilized ladps94 xslt
+% LocalWords: specialized standardized Deach exls99 xpr00 compactitem searchabiliby tdm
+% LocalWords: StaGinDav maacl09 analyzer athematical uments concl smglom subsubsection
+% LocalWords: TeXlive TeXLive texmf.cnf pdflatex ednote cmath cmath ctancite ipsmsl lmh
+% LocalWords: centering tikzpicture xscale cpath cpath rdfmeta rdfmeta sproof sproof
+% LocalWords: workaddress omtext omtext tikzinput tikzinput smglomsty mikoslidessty
+% LocalWords: mikoslides.sty hwexamsty hwexam.sty smglomcls smglom.cls mikoslidescls
+% LocalWords: mikoslides.cls hwexamcls hwexam.cls omdoccls omdoc.cls smms KohAmb smmssl
+% LocalWords: omdocdoc.sty hwexam hwexam mikoslides mikoslides mathhub modules-mh.sty
+% LocalWords: omtext-mh.sty problem-mh.sty smultiling-mh.sty structview-mh.sty docbook
+% LocalWords: tikzinput-mh.sty pathsuris pathsuris tikzstyle NatDed gencs gdots tdots
+% LocalWords: printbibliography sproofs texorpdfstring raisebox IanJucKoh sdm14 localmh
+% LocalWords: gitsc gitsc