Leo Arnold EUROTEX 2012 & 6CM PROCEEDINGS 101

Multiple documents from one source LaTEX for lecturers and teachers

Abstract le 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 is developed step by step illustrating a typical partment’s corporate design or would like to dene a 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 diering 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) le 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- workow 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 les. 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 le. The exam document class by Philip Hirschhorn [3] Finally we want to produce multiple outputs diering eliminates the need for two source documents. It denes 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 workow 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. diering content in a single run. Though this might seem impossible at rst 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 \ RequirePackage {comment} platform independence. Since pdflatex Sheet.tex will only produce 2 3 \includecomment{problem} Sheet.pdf our task splits into three parts: 4 \ i f c a s e \ c o n d i t i o n 5 %\condition= 0, student 1. Find a way to tell LaT X which parts of the source E 6 \excludecomment{ solution } le to use and which to ignore 7 \excludecomment{howtograde} 2. Change the le name of the output document in 8 \ or %\condition= 1, tutor order to be able to produce multiple outputs 9 \includecomment{ solution } 3. Produce all versions in just one run of pdflatex 10 \excludecomment{howtograde} 11 \ or %\condition= 2, corrector Selectively in- & excluding code 12 \includecomment{ solution } We would like to wrap code into a LaT X environment E 13 \includecomment{howtograde} and have some kind of “switch” in the document pream- 14 \ f i 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 dening 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} denes 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} denes 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 dened 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 document that denes our \condition macro followed 1 \includecomment{ truth } by the actual document code: 2 \excludecomment{nonsense} 3 4 Knuth started 1 \ gdef \condition {0} 5 \ begin { t r u t h } 2 \ input Sheet . t e x 6 developing \ TeX {} 7 \ end { t r u t h } On second thought we can also pass this code on to 8 \ begin { nonsense } LaTEX directly on the command line 9 using WinWord pdflatex "\gdef\condition{0} \input Sheet.tex" 10 \ end { nonsense } 11 in 1 9 7 7 . avoiding the additional le.

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 Knowing the above, we Implementing our use cases. the same output le, 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 modications to a bare minimum we pdflatex --jobname="student" Sheet.tex will assign a number to each use case. We can then dene 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 denition of \condition, LaTEX will We know that LaTEX can write to auxiliary les 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 rst read to the end of the document before writing 1 \ immediate \ write 1 8 { to the shell. If we want the command to be executed 2 p d f l a t e x immediately when LaT X reaches that point in the doc- E 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 \condition {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 \ write 1 8 { developed in the previous sections from within one 7 p d f l a t e x pdflatex run. 8 −−jobname =\ jobname−t u t o r 9 "\ gdef \ s t r i n g \condition {1} Warning. Giving LaT X access to the shell is a gateway E 10 \ s t r i n g \ input \ space \ jobname "} for exploits. Hence \write18 is disabled by default. You 11 \ immediate \ write 1 8 { can temporarily enable it using 12 p d f l a t e x pdflatex --shell-escape Sheet.tex 13 −−jobname =\ jobname−c o r r e c t o r or permanently by adjusting the conguration2 of your 14 "\ gdef \ s t r i n g \condition {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 o 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 specic content. Therefore all of our initial requirements are met and we have devel- Listing 2. General UniFlow template oped a unied workow. 1 % Beginning of Sheet.tex Pitfall. Neither the wrapping pdflatex run nor script 2 \ i f x \condition\undefined 3 will produce an output le 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 \ f i “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 dierent 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 dened solutions from a single source document. yet. After executing a “pseudo shell script” LaTEX will rst 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 le’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 The UniFlow principle can also serve to integrate exter- 19 30 −20 ! 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 dene 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’ returns no output 2 \ begin {sagesilent} Linear Algebra using Sage 3 A = matrix(QQ, [[19,30, − 2 0 ] , Sage is a free and open source computer algebra system. [ 2 6 , 3 9 , − 26], [61,93, − 6 2 ] ] ) It is best used on Linux since the “Windows version” is 4 p = A.charpoly() actually an Ubuntu virtual machine image containing 5 \ end {sagesilent} Sage. 6 We will give a tiny demonstration of the LaTEX inter- 7 \[ A = \sage{A} \] face called SageTEX and its implementation using the 8 The characteristic polynomial of UniFlow principle. Further information on SageTEX can $A$ i s be found in Günter Rau’s demonstration [6] or on the 9 \[\ chi _A(x) = \sage{p} = \sage{ Sage homepage3. factor(p)} \] 10 hence the eigenvalues of $A$ are How to compile. SageT X works similar to BibT X: E E 11 \[ \sage{A.eigenvalues()} \] 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. We will use an easy example from elementary prob- 1 \ i f x \condition\undefined ability. More advanced examples can be found for ex- 2 \ immediate \ write 1 8 { ample in Uwe Ziegenhagen’s demonstration [8] or on 3 p d f l a t e x Friedrich Leisch’s Sweave website5. 4 "\ gdef \ s t r i n g \condition {0} 5 \ s t r i n g \ input \ space \ jobname "} How to compile. As the output of Sweave will be writ- 6 \ immediate \ write 1 8 { ten to Example.tex we change the le name of our 7 sage " \ jobname .sagetex.sage"} document to Example.Rnw (Rnw = R noweb). Now 8 \ immediate \ write 1 8 { we can use LaTEX code as usual and insert R code as 9 p d f l a t e x “chunks” using the noweb syntax. The document is then 10 "\ gdef \ s t r i n g \condition {0} compiled as follows. 11 \ s t r i n g \ input \ space \ jobname "} 1 # HaveR 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 dierent after every compile run. 1 % Beginning of Example.Rnw 2 \ i f x \condition\undefined 3 \ immediate \ write 1 8 { Aftermath 4 R CMD Sweave \ jobname . Rnw } Of course we could have achieved all of this in a one- 5 \ immediate \ write 1 8 { call fashion using some kind of shell script, make6 or its 6 p d f l a t e x LaTEX analogs latexmk7 or rubber8. On the other hand 7 "\ gdef \ s t r i n g \condition {0} the UniFlow principle provides a platform independent, 8 \ s t r i n g \ input \ space \ jobname "} script-like alternative without additional (Make)les or 9 \ expandafter \ stop non-TEX executables. 10 \ f i The future of UniFlow Editing the Example.Rnw as source le 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 oer you the .tex will by now have his or her special use case in mind – and le. 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 T Xnical comments and pieces of advice are number of pips each time. Visualize their relative fre- E always welcome. quency as a histogram and a pie chart. One step further we could think about a unied inter- Solution. Since this exercise depends on probability, face to integrate virtually any program into the LaTEX everyone will have a dierent 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.15

0.10 Acknowledgments

relative frequency relative 4 0.05 6 Many people have directly or indirectly contributed in

0.00 the development of the UniFlow principle. 1 2 3 4 5 6 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 eective time from the following code snippet. post on StackExchange. When I was struggling with selectively showing or 1 # Relevant part of 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 =20) Marcus Bitzl is an avid reader of “Die TEXnische 4 p i p s <− sample ( 1 : 6 , 1 0 0 , replace = Komödie” and drew my attention to the articles on the TRUE ) integration of free math software. He was also the rst 5 h i s t (pips , breaks=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 "gray" , freq=FALSE, main="" , Ziegenhagen (Sweave) were invaluable primers to me xlab="number␣of␣pips" , ylab=" and made the vivid demonstrations of UniFlow in action relative ␣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 ) , col =c ( " white " , " present the UniFlow principle. black") , 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 le output to multiple PDF les?” 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 [email protected]