summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/stex/sty/stex/stex.dtx
blob: bec4f38373c0ae6fbb4a893564227b878647e9d7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
% \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}[2019/03/20 v1.0 Semantic Markup]
%<logo>\ProvidesPackage{stex-logo}[2019/03/20 v1.0 sTeX Logo]
%
%<*driver>
\documentclass{ltxdoc}
\usepackage[utf8]{inputenc}
\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\\
% FAU Erlangen-N\"urnberg\\
% \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{itemize}
% \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{itemize}
% 
% On the other hand, {\TeX/\LaTeX}/s adaptable syntax and tightly integrated programming
% features within has distinct advantages on the authoring side:
%  
% \begin{itemize}
% \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{itemize}
%
% 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 \protect\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{enumerate}
% \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{enumerate}
%   
% 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{enumerate}
% \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{enumerate}
% 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{enumerate}
% \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{enumerate}
% 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{omdoc}
\RequirePackage{statements}
\RequirePackage{structview}
\RequirePackage{sproof}
\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