diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/stex/stex/stex.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/stex/stex/stex.dtx | 700 |
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 |