Leo Arnold EUROTEX 2012 & 6CM PROCEEDINGS 101

Multiple documents from one source

LaTEX for lecturers and teachers

Abstract file name. In an inattentive moment we might acciden-

In general LaTEX will produce only one output tally upload the version with solutions to our website
document. This paradigm shifts when harnessing the too early, rendering the homework assignments point-
power of the so-called shell escape. We will show how less. Also exam.cls may not provide the customization
to produce multiple output documents with differing you need, for example if you have to implement a de-
content from one single source document. The principle
partment’s corporate design or would like to define a
is developed step by step illustrating a typical
application in academic teaching. third version of the problem sheet containing additional
Focusing on mathematical problems we then explore notes.
two ways of automating calculations by integrating free
software into the LaTEX run. Getting multiple outputs
Multiple outputs would usually be achieved by multiple
Keywords invocations of LaTEX. Before each run we would need
mathematics, problem sheet, shell escape to manipulate the source document in order to have
differing content. All of this can be done using shell
scripts or MakeFiles, but it
The problem with problem sheets
@ requires an additional (script or make) file
Composing appealing problem sheets and preparing in- @ requires non-TEX programs
structive solutions is a time consuming task. Further @ requires knowledge beyond TEX
time is lost when problems need to be altered after type- @ may not be platform independent
setting, requiring updated plots and recalculated solu-
tions. When LaTEX is used, we should optimize our We will introduce a method that handles these short-
workflow and exploit its capabilities to handle as many comings using only pdflatex.
tedious tasks as possible.
Requirements for a unified workflow
Set up for failure: bad practice As we have already seen, it is crucial to have just one
A typical road to ruin is typesetting problems and so- source document to avoid incongruities and have a nat-
lutions in separate files. That way it is hard to keep ural way of typesetting.
changes in order or notation in sync. For better com- Typeset problems will most certainly be reused in
prehension we would also like to have the problem for- future courses. Therefore we would like to be able to
mulation above its solution, but copying them from the copy & paste parts of the exam with ease. Our approach
problem sheet source will just increase the sync prob- should also apply to documents that \input problems
lem. from another source file.
The exam document class by Philip Hirschhorn [3] Finally we want to produce multiple outputs differing
eliminates the need for two source documents. It defines in content by a single invocation of pdflatex. Our
a solution environment that can be included or hidden derivation will assume the following use cases:
via a class option. The solutions are typeset in the source
document right after the problem which makes for a @ student problems only
very natural workflow and easier debugging. Changes @ tutor problems and their solutions
in notation can now be handled globally using the text @ corrector problems, solutions and instructions on
editors “replace all” function. grading the students work
On the other hand, having just one source document
requires us to pay close attention: without additional ad-
justments both versions will compile to the same output
102 EUROTEX 2012 & 6CM PROCEEDINGS Leo Arnold

Designing a unified workflow a macro \condition that expands to the number and
use \ifcase to make the adjustments for corresponding
Our goal is to produce multiple output documents with
case.
differing content in a single run. Though this might
seem impossible at first glance, Ulrike Fischer found
a way [2] to do this using only pdflatex. We will Listing 1. Use case implementation
introduce her approach step by step, keeping an eye on
1 \ R e q u i r e P a c k a g e { comment }
platform independence.
2
Since pdflatex Sheet.tex will only produce
3 \ includecomment { problem }
Sheet.pdf our task splits into three parts:
4 \ ifcase \ condition
5 % \ condition = 0 , student
1. Find a way to tell LaTEX which parts of the source
6 \ excludecomment { s o l u t i o n }
file to use and which to ignore
7 \ excludecomment { h o w t o g r a d e }
2. Change the file name of the output document in
8 \ or % \ c o n d i t i o n = 1 , t u t o r
order to be able to produce multiple outputs
9 \ includecomment { s o l u t i o n }
3. Produce all versions in just one run of pdflatex
10 \ excludecomment { h o w t o g r a d e }
11 \ or % \ c o n d i t i o n = 2 , c o r r e c t o r
Selectively in- & excluding code
12 \ includecomment { s o l u t i o n }
We would like to wrap code into a LaTEX environment
13 \ includecomment { howtograde }
and have some kind of “switch” in the document pream-
14 \ fi
ble to control whether to have LaTEX process it or not.
This is exactly what comment.sty by Victor Eijkhout
[1] does. Now all it takes is defining the value of \condition
to control the content of the output.
Usage. The comment package provides us with two sim-
ple commands Coding discipline. One could of course implement the
above using \ifnum instead. I prefer to use \ifcase
@ \includecomment{foobar} defines the envi- here because the cases are “automatically numbered”
ronment foobar whose content will be included in order of appearance. That way I got less confused
@ \excludecomment{foobar} defines the envi- about which number represents which use case, saving
ronment foobar whose content will be ignored me time on debugging.

Example. A nice feature of environments defined using Rethinking command line calls
comment.sty will not break the line, so we can use We want to control the version of the output without
them in midsentence. The minimal example editing the source document. We could write a wrapper
1 \ includecomment { t r u t h } document that defines our \condition macro followed
2 \ excludecomment { n o n s e n s e } by the actual document code:
3
4 Knuth s t a r t e d 1 \ gdef \ c o n d i t i o n { 0 }
5 \ begin { t r u t h } 2 \ input S h e e t . t e x
6 d e v e l o p i n g \ TeX { }
7 \ end { t r u t h } On second thought we can also pass this code on to
8 \ begin { n o n s e n s e } LaTEX directly on the command line
9 u s i n g WinWord
10 \ end { n o n s e n s e } pdflatex "\gdef\condition{0} \input Sheet.tex"
11 in 1977. avoiding the additional file.
will just output Changing the output file name
Knuth started developing TEX in 1977. By now we can produce any version of the document
by altering a single value but they will still be written to
Implementing our use cases. Knowing the above, we
the same output file, thereby overwriting the previous
can easily write a document that matches our use cases, output.
but we would still have to adjust the in- and exclusions A quick look at pdflatex’s manpage1 provides
before compiling.
To reduce such modifications to a bare minimum we pdflatex --jobname="student" Sheet.tex
will assign a number to each use case. We can then define which will create student.pdf from Sheet.tex.
Multiple documents from one source EUROTEX 2012 & 6CM PROCEEDINGS 103

Escaping to the Shell When we add a definition of \condition, LaTEX will

We know that LaTEX can write to auxiliary files using ignore the \ifx block, apply the use case settings and
output stream. There is also the special stream 18 which output the desired version.
will execute the output on the system shell. Considering all use cases and the change of job name
\write18{ping tug.org} we arrive at
This is called escaping to the shell. Used like this LaTEX Listing 3. Pseudo shell script in LaTEX
will first read to the end of the document before writing 1 \ immediate \ w r i t e 1 8 {
to the shell. If we want the command to be executed 2 pdflatex
immediately when LaTEX reaches that point in the doc- 3 −−jobname = \ jobname−s t u d e n t
ument, we use (see [4], p. 226f) 4 " \ gdef \ s t r i n g \ c o n d i t i o n { 0 }
\immediate\write18{ping tug.org} 5 \ s t r i n g \ input \ space \ jobname " }
In particular this means we can invoke the commands 6 \ immediate \ w r i t e 1 8 {
developed in the previous sections from within one 7 pdflatex
pdflatex run. 8 −−jobname = \ jobname−t u t o r
9 " \ gdef \ s t r i n g \ c o n d i t i o n { 1 }
Warning. Giving LaTEX access to the shell is a gateway 10 \ s t r i n g \ input \ space \ jobname " }
for exploits. Hence \write18 is disabled by default. You 11 \ immediate \ w r i t e 1 8 {
can temporarily enable it using 12 pdflatex
pdflatex --shell-escape Sheet.tex 13 −−jobname = \ jobname−c o r r e c t o r
or permanently by adjusting the configuration2 of your 14 " \ gdef \ s t r i n g \ c o n d i t i o n { 2 }
TEX distribution. 15 \ s t r i n g \ input \ space \ jobname " }

The UniFlow principle Combining the UniFlow template (listing 2) with the
After introducing all the building blocks we are now able implementation of the use cases and the corresponding
to understand Ulrike Fischer’s ingenious construction pseudo shell script (listings 1 and 3) we have constructed
[2] to produce multiple output documents in one single the single source document Sheet.tex. Enabling shell
run. escape and processing it with pdflatex will result
We start off with a document skeleton to demonstrate in the three output documents Sheet-student.pdf,
the recursive nature of the approach. Sheet-tutor.pdf and Sheet-corrector.pdf, each
of them with the desired specific content. Therefore all
of our initial requirements are met and we have devel-
Listing 2. General UniFlow template
oped a unified workflow.
1 % Beginning of Sheet.tex Pitfall. Neither the wrapping pdflatex run nor script
2 \ ifx \ condition \ undefined 3 will produce an output file named Sheet.pdf. This
3 % Pseudo shell script (listing 3) can cause error messages when using text editors with
4 \ expandafter \ stop built-in PDF viewers like TEXmaker and its standard
5 \ fi “quick build” feature.
6
7 % Use case implementation (listing 1) Exercise. If you would like to check your understanding
8 of the UniFlow principle, try to write a template for this
9 % Actual document code begins here scenario:
A school teacher always designs two slightly different
versions A and B of an exam. She would like to produce
Processing this code will have pdflatex enter the \ifx the four versions A, B, A with solutions and B with
block as the macro \condition has not been defined solutions from a single source document.
yet. After executing a “pseudo shell script” LaTEX will
first expand the token \fi and then \stop reading. Note
that this run will not produce any output.
In the pseudo shell script, we will invoke pdflatex
again on this very same document. The file’s base name
is obtained from \jobname
pdflatex "\string\input\space\jobname"
and we told the parser to interpret \input as a \string,
preventing it from expansion ([4], p. 40).
104 EUROTEX 2012 & 6CM PROCEEDINGS Leo Arnold

UniFlow in action
19 30 −20
!
The UniFlow principle can also serve to integrate exter-
nal programs into the LaTEX run. Due to the author’s A= 26 39 −26
background the examples are taken from mathematics. 61 93 −62
For applications in other subjects see the PythonTEX Solution. The characteristic polynomial of A is
gallery [5] or Herbert Voß’s article on general source
code [7]. χ_A(x) = x3 + 4x2 + 3x = x · (x + 1) · (x + 3)
For the sake of simplicity we now focus on having hence its eigenvalues are
only one output document. Nevertheless we will still
have to define the \condition macro (setting it to an [0, −1, −3]
arbitrary string value) whenever we want pdflatex to Using sagetex.sty we just needed to type
ignore the \ifx block. The generalization to multiple
output versions is left to the reader as an exercise. 1 % ’ sagesilent ’ r e t u r n s no o u t p u t
2 \ begin { s a g e s i l e n t }

Linear Algebra using Sage 3 A = m a t r i x ( QQ, [[19 ,30 , −20] ,

Sage is a free and open source computer algebra system. [26 ,39 , −26] , [61 ,93 , −62]])
It is best used on Linux since the “Windows version” is 4 p = A . c h a r p o l y ( )
actually an Ubuntu virtual machine image containing 5 \ end { s a g e s i l e n t }
Sage. 6

We will give a tiny demonstration of the LaTEX inter- 7 \ [ A = \ s a g e { A } \ ]

face called SageTEX and its implementation using the 8 The c h a r a c t e r i s t i c p o l y n o m i a l o f
UniFlow principle. Further information on SageTEX can $A$ i s
be found in Günter Rau’s demonstration [6] or on the 9 \ [ \ c h i _A ( x ) = \ s a g e { p } = \ s a g e {
Sage homepage3 . factor (p) } \]
10 h en c e t h e e i g e n v a l u e s o f $A$ a r e
How to compile. SageTEX works similar to BibTEX: 11 \ [ \ s a g e { A . e i g e n v a l u e s ( ) } \ ]
First we run LaTEX to extract the Sage commands. These
are then processed externally with Sage and the results Note how this assures that the matrix A and the so-
are included in the second LaTEX run. lution will always match in the output document. This
is as foolproof as it gets.
1 # Extract Sage commands
2 pdflatex Example . tex Statistics using R and Sweave
3 # Process Sage commands Data plotting techniques play an important role in any
4 sage Example . sagetex . sage statistics course: histograms, q-q plots, boxplots etc. are
5 # Include Sage outputs handy tools to analyze measured data.
6 pdflatex Example . tex R is a free statistics software system available for all
common operating systems4 . It comes with the plug-
in Sweave which “weaves” R (the free successor to S
Implementing UniFlow.
statistics) into LaTEX documents.
1 \ ifx \ condition \ undefined
We will use an easy example from elementary prob-
2 \ immediate \ w r i t e 1 8 { ability. More advanced examples can be found for ex-
3 pdflatex ample in Uwe Ziegenhagen’s demonstration [8] or on
4 " \ gdef \ s t r i n g \ c o n d i t i o n { 0 } Friedrich Leisch’s Sweave website5 .
5 \ s t r i n g \ input \ space \ jobname " } How to compile. As the output of Sweave will be writ-
6 \ immediate \ w r i t e 1 8 { ten to Example.tex we change the file name of our
7 s a g e " \ jobname . s a g e t e x . s a g e " } document to Example.Rnw (Rnw = R noweb). Now
8 \ immediate \ w r i t e 1 8 { we can use LaTEX code as usual and insert R code as
9 pdflatex “chunks” using the noweb syntax. The document is then
10 " \ gdef \ s t r i n g \ c o n d i t i o n { 0 } compiled as follows.
11 \ s t r i n g \ input \ space \ jobname " }
1 # Have R process Example . Rnw and
12 \ expandafter \ stop
2 # create / overwrite Example . tex
13 \ f i
3 R CMD Sweave Example . Rnw
4 pdflatex Example . tex
Exercise. Calculate the eigenvalues of the matrix
Multiple documents from one source EUROTEX 2012 & 6CM PROCEEDINGS 105

Implementing UniFlow. Here, due to the use of sample(), the output will be
different after every compile run.
1 % B e g i n n i n g o f Example . Rnw
2 \ ifx \ condition \ undefined
3 \ immediate \ w r i t e 1 8 { Aftermath
4 R CMD Sweave \ jobname . Rnw } Of course we could have achieved all of this in a one-
5 \ immediate \ w r i t e 1 8 { call fashion using some kind of shell script, make6 or its
6 pdflatex LaTEX analogs latexmk7 or rubber8 . On the other hand
7 " \ gdef \ s t r i n g \ c o n d i t i o n { 0 } the UniFlow principle provides a platform independent,
8 \ s t r i n g \ input \ space \ jobname " } script-like alternative without additional (Make)files or
9 \ expandafter \ stop non-TEX executables.
10 \ fi
The future of UniFlow
Editing the Example.Rnw as source file and using the
To enable anyone to implement the UniFlow principle
above code, the correct command line call is
with ease I will work on developing it into a LaTEX
pdflatex --shell-escape Example.Rnw package.
If you like to use the tab completion feature of your Versatility is UniFlow’s biggest asset and every reader
system shell, it will probably only offer you the .tex will by now have his or her special use case in mind – and
file. Observe that this will generate the same output most certainly be struggling with the inconvenient syn-
because both execute the same pseudo shell script. tax of the corresponding \write18 statement. Hence
designing an intuitive command structure will be key
Exercise. Roll a dice 100 times in a row recording the
and your TEXnical comments and pieces of advice are
number of pips each time. Visualize their relative fre-
always welcome.
quency as a histogram and a pie chart.
One step further we could think about a unified inter-
Solution. Since this exercise depends on probability, face to integrate virtually any program into the LaTEX
everyone will have a different result. Mine looks like run. Herbert Voß [7] already showed how general source
this: code can be extracted from a document and reincluding
2 the output after processing. His approach works with
0.20

3 any kind of batching method, allowing for an integration

1
into UniFlow (once developed).
0.05 0.10 0.15
relative frequency

Acknowledgments
4
6 Many people have directly or indirectly contributed in
0.00

1 2 3 4 5 6
the development of the UniFlow principle.
number of pips
5 First and foremost I want to thank Ulrike Fischer who
These diagrams where of course generated at compile provided the core concepts in her short and effective
time from the following code snippet. post on StackExchange.
When I was struggling with selectively showing or
1 # R e l e v a n t p a r t o f Example . Rnw hiding content, Rolf Niepraschk pointed out the fasci-
2 << echo =FALSE , f i g =TRUE >>= nating simplicity of comment.sty to me.
3 par ( ps = 2 0 ) Marcus Bitzl is an avid reader of “Die TEXnische
4 p i p s <− sample ( 1 : 6 , 1 0 0 , r e p l a c e = Komödie” and drew my attention to the articles on the
TRUE ) integration of free math software. He was also the first
5 hist ( pips , b r e a k s =c ( 0 . 5 , 1 . 5 , to encourage the development of a UniFlow package.
2 . 5 , 3 . 5 , 4 . 5 , 5 . 5 , 6 . 5 ) , col= The articles by Günter Rau (SageTEX) and Uwe
" g r a y " , f r e q =FALSE , main= " " , Ziegenhagen (Sweave) were invaluable primers to me
x l a b = " number ␣ o f ␣ p i p s " , y l a b = " and made the vivid demonstrations of UniFlow in action
r e l a t i v e ␣ frequency " ) possible.
6 @ Finally I would like to express my gratitude to the
7 EuroTEX 2012 organizers for arranging a wonderful and
8 << echo =FALSE , f i g =TRUE >>= inspiring conference and giving me the opportunity to
9 p i e ( t a b l e ( p i p s ) , c o l =c ( " w h i t e " , " present the UniFlow principle.
b l a c k " ) , cex =2)
10 @
106 EUROTEX 2012 & 6CM PROCEEDINGS Leo Arnold

References
[1] V. Eijkhout. comment.sty: Selec-
tively include / excludes portions of text.
CTAN:macros/latex/contrib/comment:
http://www.ctan.org/tex-archive/
macros/latex/contrib/comment.
[2] U. Fischer. Answer to “Can one
TeX file output to multiple PDF files?”
http://tex.stackexchange.com/a/5265.
[3] P. Hirschhorn. exam.cls: Pack-
age for typesetting exam scripts.
CTAN:macros/latex/contrib/exam: http:
//www.ctan.org/tex-archive/macros/
latex/contrib/exam.
[4] D. E. Knuth. The TEXbook. Addison-Wesley,
Eighth printing, August 1986.
[5] G. Poore. PythonTEX: Fast Access to Python from
within LaTEX. github:gpoore/pythontex:
https://github.com/gpoore/pythontex.
[6] G. Rau. SageTEX. Die TEXnische Komödie,
1/2011: http://archiv.dante.de/DTK/PDF/
komoedie_2011_1.pdf:17–21.
[7] H. Voß. Einlesen und Ausführen von Quell-
code. Die TEXnische Komödie, 1/2011: http:
//archiv.dante.de/DTK/PDF/komoedie_
2011_1.pdf:40–54.
[8] U. Ziegenhagen. Datenanalyse mit Sweave, LaTEX
und R. Die TEXnische Komödie, 4/2010: http:
//www.dante.de/DTK/Ausgaben/dtk104.
pdf:35–45.

Weblinks
1. http://linux.die.net/man/1/pdflatex
2. http://wiki.contextgarden.net/Write18
3. http://www.sagemath.org
4. http://www.r-project.org
5. http://www.statistik.lmu.de/~leisch/Sweave
6. http://www.gnu.org/software/make
7. CTAN:support/latexmk: http://ctan.org/
tex-archive/support/latexmk/
8. https://launchpad.net/rubber

Leo Arnold
tex@arney.de