STeX/Tutorial

sTeX tutorial, given by Michael Kohlhase to the KWARC group.

Motivation
Far more people know TeX than OMDoc. Large collections of TeX documents available. Therefore created sTeX as a TeX notation for OMDoc.

LaTeX (with stex.sty) can create PS/PDF out of sTeX sources, but LaTeXML can create OMDoc from sTeX.

LaTeXML originated independently of sTeX, in the context of the DLMF.

TeX does not understand much about the structure of documents, unless you explicitly annotate it.

Syntax
OMDoc:  ...

sTeX: \begin{assertion}[id=foo,type=theorem] ... \end{assertion}

(uses keywords package)

Packages
modules and presentation are the really interesting ones, the other ones are quite trivial.

statements.sty
mathematical statements (see above)

sproof.sty
proofs with numbered steps

\begin{proof}[for=foo,id=bar] \begin{step} ...  \end{step} \end{proof}

Formatting of steps: P.1 P.1.2.3.4

omdoc.sty
contains environments like omgroup that directly map to the corresponding OMDoc elements

presentation.sty (Introduction)
The really interesting feature of sTeX.

Semantic macros, consider: $$\lambda x_\alpha.x=_\alpha\lambda y_\alpha.y=\mathcal{I}^\alpha$$


 * $$x_\alpha$$ is variable of type $$\alpha$$
 * $$=_\alpha$$ is $$\alpha$$-equality
 * The actual type of $$\mathcal{I}$$ is $$\alpha\to\alpha$$, but is left out here.

Semantic macro for the type $$\alpha$$: \def\typea{\alpha}

Distinguish from abbreviative macros like : \def\wlog{without loss of generation}

You need semantic macros as a Ph.D. student. Eventually your supervisor will say: I don't like your alphas. I rather like small sans-serif a's in that place. – Replacing this manually is tedious. Eventually, you'll end up with one style file (Michael: miko.sty) that contains hundreds of your semantic macros. However, for some other scientific paper, you have to import miko.sty, but you have to change something, your thesis might no longer compile, … By the end of your thesis, your macro file will be as long as a scientific paper.
 * Compare this to word processors: sometimes, $$\alpha$$ is just the "a" of a different font. With an older word processor, you wouldn't even be able to search for all $$\alpha$$

This is the common way of doing it. But LaTeX has late binding, with its pros and cons. If you change the style file, mistakes will be visible in the document using it later. You want a module system instead. Not just \import{miko.sty}, and all semantic macros are visible throughout the whole document. Rather, a symbol is only visible after its definition. Solution: Break your style file into snippets, include them in the place where you need them. But still, they will not become invisible when you don't need them any more in the next section.

Local groups:

\def\foo{foo} {\def\foo{bar}\foo} \foo

\foo in line 2 evaluates to \bar. Really nice solution: associate symbols with their theories/modules. Include modules into target documents as local groups.

modules.sty
Example (symbol visibility):
 * module foo, defines symbol +
 * module bar, defines symbol * but also wants to use +

others

 * mikoslides (using Beamer)
 * assignments
 * problems
 * Content MathML
 * CNXML

Some OMDoc modules do not yet have a counterpart, e.g. theory morphisms, hiding, …

Symbol definitions
Consider a file foo.tex: \begin{module}[id=foo] \symdef{plus}{+} a\plus b \end{module} \begin{module}[id=bar] \importmodule{foo} \symdef{times}{...} a\plus b \end{module}

Other file: \importmodule[foo]{bar}

Means: read the file foo.tex, if needed (doesn't load sth. twice, think of a large dependency graph), and give me the macros from the module bar. Note: This makes TeX process the whole file, including the module foo and maybe unrelated modules placed in that file.

Solution: Put each module into its own file (TeX cannot include just a section of a file. David Carlisle might know how to do), and cache just the symdefs. Consider foo.tex:

\begin{module}[id=foo] \symdef... % lots of other stuff that explains foo, % but does not define macros \end{module}

Instead, a Perl program sms, executed via make, puts the macros into a file foo.sms, which is actually processed by \importmodule[foo]{module-id}.

Maybe it's possible to redefine all letters to non-marking letters. (In TeX, ordinary characters are marking, i.e. they print themselves in the output.)

A realistic solution would be to recode sms in TeX (has been tried but not finished) and to directly integrate it into the sTeX workflow.
 * “If you're using ‘TeX programming’ and ‘easy’ in the same sentence, you're already wrong.”

Problem: All symbol IDs and module IDs are global in TeX. Not like in OMDoc! If there are two symbols of the same name, the first one wins. But there's a qualified import that limits the visibility of symbols to the end of the importing module. (symbol IDs don't even work everywhere in sTeX.) In future, these IDs might be disambiguated by adding internal prefixes in front of them.

In practice, you can put all other symbols you need, into a big theory "missing", which just contains symdefs without any explanation or definition, what these symbols mean. But eventually, you will break this apart and bring order into it.

modules.sty introduces early binding.

Performance is acceptable on today's machines, sth. like 300 pages in one minute.

Presentation
Interesting semantic macros, or: How you really want to define symbols

\smoothon\Reals would map to $$\mathcal{C}^\infty(\mathbb{R},\mathbb{R})$$

\def\smoothon#1{\mathcal{C}^\infty(#1,#1)}

In sTeX:

\symdef{smoothon}[1]{...} % same as above

No \ in front of symbol name, as in newcommand. (Couldn't get that to work.)

Can also redefine the presentation of a particular symbol.

Mixfix operators
Function types like $$\alpha\times\beta\times\gamma\to\delta$$. One would like to write a content macro like:

\fntype{\alpha,\beta,\gamma}{\delta}

Translation to OpenMath (abbreviated):

     

With an appropriate editor offering bracket highlighting, like Emacs, this is quite convenient to write, and it yields valid output without any misplaced brackets!

For that, the presentation package has macros, e.g.:

\symdef{funtype}[2]{\mixfixai{}{#1}{\rightarrow}{#2}{}{\times}}

Mixfix declaration, where the first argument is associative and the second one is infix.
 * A general mixfix declaration says sth. like: (before 1st)(1st arg)(between 1st and 2nd)(2nd arg)...(nth arg)(after nth)

There are mixfix macros for up to three arguments, but not more, as TeX macros can only take up to 9 arguments.

There is also \prefix etc.

Bracket elision and precedences
\mixfix... takes an optional argument like [p=500,pi=501,pii=499]: Outgoing precedence, precedence of first argument, precedence of second argument.

Example: \plus{\times 35}{\plus 47}

yields $$3\cdot 5+4\cdot 7$$

Swapping \plus and \times yields $$(3+5)\cdot(4+7)$$, i.e. does not elide

Note, for constructors like \smoothon, you usually do not want brackets to be elided!

Transition to sTeX

 * refactor your files into modules
 * define semantic macros for symbols
 * or reuse ones already defined by sb. else
 * How to look them up? Either with a proper IDE (not yet), or look up in the source code

sTeX is really helpful if you need to reuse stuff. Michael started using sTeX for his lecture slides. One slide is the granularity of reusability. Now there are 2,000 slides in the repository.
 * “The pain will start once you actually start writing.” (Unfortunately, not all error messages are helpful.)
 * “I'm not writing my papers in sTeX.” (Also because of co-authors.) “But I use semantic macros.”
 * The next version of the OMDoc book will be written in sTeX, i.e. we'll have an OMDoc book in OMDoc.


 * General CS
 * 2/3 of advanced CS
 * some graduate courses
 * a bit of type theory

As with semantics in general: invest more, gain more. Whether it pays off depends on how much you reuse content.

Troubleshooting

 * sometimes you will get the error "TeX capacity exceeded, sorry [text input levels=15].". This comes from the fact that *.sms files recursively load others, and that thus with a import depth of 15, we have 15 input streams open, which is all that the TeX program allows. There are two ways to proceed here. Either you save on load depth by pre-loading module files using the \requiremodules macro at the beginning of the file. Or you extend the internal registers of TeX. To do this, find the file texmf.cnf on your machine (e.g. by locate, and change the values of the nest_size to e.g. 1000 and max_in_open to e.g. 30 (or whatever you need 30 works for me). Oh, BTW, you will need to do this as root (at least under unix).

OMDoc
If you generate OMDoc from sTeX and render this OMDoc, the output will be quite similar to the PDF generated from sTeX.

Plan

 * create a bit more documentation
 * put it on CTAN
 * make people use it
 * “The thrill about getting you involved is getting all these annoyances fixed I've already got used to.”