Best Practices for sTeX Collections

The sTeX development was driven large case study, where we semantically pre-load the course materials for a two-semester course in Computer Science (GenCS) at  Jacobs University Bremen and transform them to OMDoc. We have semantically pre-loaded the LaTeX sources for the course materials (>400 slides and course notes, >10k lines of sTeX code with >400kb + ~1000 homework/quiz problems). Furthermore, some members of the KWARC group at Jacobs have written all their research presentations and tutorials in sTeX in the last years.

We have used these best practices in the example in the sTeX distribution.

Best Practice 1: The 'Little Modules' Approach

sTeX supports the notion of a "module", i.e. a conceptually self-contained unit of knowledge that can be re-used or inherited in multiple documents. Clearly, the smaller the modules, the more effective the re-use, so we advise a 'little-modules' approach to sTeX markup. This way the semantic macros introduced by a module can selectively be inherited by a \importmodule command.

Best Practice 2: The 'One Module One File' Approach

As the TeX formatting workflow does not support the inclusion of file fragments (easily), it has turned out as a good practice to use one file per module (except for nested modules of course). This way a module can be included into a document via a \input or \sinput command. Note that module files are not self-contained entities, e.g. because they lack a \documentclass declaration a LaTeX preamble and the \begin/end{document} environment. This distinguisehes them from sTeX documents that do.

Best Practice 3: Organize sTeX documents by category and topic in a repository

The GenCS and research presentation case study has resulted in an subversion repository of more than 2000 sTeX files (governed by the two practices above). The sheer size of this makes is difficult to manage. It has turned out as a good practice to organize the modules by topic (e.g. first-order automated theorem proving or XML basics) as top-level directories, since these can be re-used as subversion externals somewhere else (e.g. for individual courses). For each topic we have a structure of subdirectories by category:

• en, de, ... for modules with slides/notes in english/german/...
• fragments for files that larger groupings of modules with a narrative structure that introduces a part of a topic
• problems} for modules with homework or quiz problems
• probsets for fragments that correspond to larger problem sets
• talks for sTeX documents that aggregate talks or lectures from fragments, problem sets, problems, and modules.

It has turned out that is is also good to maintain an sTeX document (usually called all.tex per directory that includes all modules or fragments in that directory. This can be useful as an overview as well as a formatting or conversion target to test the sTeX markup of all modules in the directory. Another advantage of this setup is that all modules are at the same level, which facilitates searching for macros via grep

Best Practice 4: Use Makefile-Based Automation

The sTeX distribution comes with a set of Gnu Makefiles that help automate the transformation process. In particular, adding Makefiles at all levels of the file system tree helps run large batch conversion jobs and keep the OMDoc version up to date with the PDF version.