# Producing different versions of a document

I am writing a documentation for a software environment which will be composed of several subfile put together using the \include command.

The thing is, I would like to be able to output different version of the file so that I can print it for different kind of readers without actually modifying the overall documentation.

For example, I would like to be able to generate a version of the file for the programmers, another for the risk analyst, another for the DB admin, each of them having access to different section.

I know I could create several tex files, each including the right subsections, but I think I saw somewhere a way to do it using a parameter at compile-time.

Anyway, I'm looking for suggestions.

EDIT:

If possible, I would like that the document created for each type of reader looks like it is the complete piece (correct chapter numbering etc...)

-
You can use the comment package to define environments which can be enabled and disabled e.g. depending on a macro set in the command line. There are some answer around here showing this. (looking ...) –  Martin Scharrer Jul 7 '11 at 13:36
Found it: Have a look at Whether it's possible to keep translation together with original text? (my answer there shows the use of the comment package). That question is very similar to yours just about text in different languages not different content –  Martin Scharrer Jul 7 '11 at 13:38
charlietanksley.net/philtex/… –  N.N. Jul 7 '11 at 13:42
For passing an option to the document to select which version should be compiled, see Passing parameters to a document. –  Martin Scharrer Jul 7 '11 at 13:45
@Martin Sharrer: thanks. So basically you suggest I use pass a string parameter to the compiler, and the using \if I decide which environment to include. Correct? –  SRKX Jul 7 '11 at 13:54

If the versions differ only for the \included files, you can put in your preamble something like

\newcommand\programmers{\includeonly{chap1,chap3}}
\newcommand\riskanalyst{\includeonly{chap1,chap4}}


Compile the whole document, so every reference is correct. In order to produce the "programmers version", call pdflatex as

pdflatex "\nofiles\AtBeginDocument{\programmers}\input{doc.tex}"


(assuming your main document is doc.tex). Similarly for the other categories. The \nofiles is used to avoid clobbering the already final .aux files.

This method has limitations: the page numbers reflect the presence of the omitted chapters, for example.

## Different implementation with the comment package

\documentclass{article}
\usepackage{comment}
\includecomment{1}\includecomment{2}\includecomment{3}\includecomment{4}
\newcommand\programmers{%
\includecomment{1}\excludecomment{2}\excludecomment{3}\includecomment{4}}
\newcommand\riskanalyst{%
\includecomment{1}\excludecomment{2}\includecomment{3}\excludecomment{4}}
\includecomment{1}\includecomment{2}\excludecomment{3}\excludecomment{4}}

\begin{document}

\begin{1}
\input{chap1}
\end{1}
\begin{2}
\input{chap2}
\end{2}
\begin{3}
\input{chap3}
\end{3}
\begin{4}
\input{chap4}
\end{4}
\end{document}


The first line after loading comment will define the environments. As before you can produce the "programmers" version by saying from the command line

pdflatex "\AtBeginDocument{\programmers}\input{doc.tex}"


and similarly for the other versions. This will renumber chapters and pages. If you don't want to clobber the aux files, you can assign a different job name:

pdflatex --jobname=doc-programmers "\AtBeginDocument{\programmers}\input{doc.tex}"

-
Ok thanks! If I want to remove the page breaks between the includes, to you see any reason why I shouldn't use "newclude" –  SRKX Jul 7 '11 at 14:05
As far as I can tell it may break cross references. See also edit. –  egreg Jul 7 '11 at 14:10
Note, that @egreg's solution will mean that even in the programmers version the chap3 will be labelled as "chapter 3", and there will be a gap in the page numbering where chapter 2 would have gone. Sometimes this is what is wanted, where it's as though the different versions have some pages deleted but otherwise are identical (you can \ref{} to an item that is in an excluded chapter, etc). It's not clear from the question if this is what JSmaga is looking for, though. –  Lev Bishop Jul 7 '11 at 14:16
You have to use a different approach, with the comment package. I'll work to it. –  egreg Jul 7 '11 at 14:54

It may be worth noting that the other way to do this is to maintain your document in XML, where you can define (or use existing) mechanisms to do exactly what you describe. The output dependencies are called effectivities, and XML vocabularies like DocBook have explicit features to handle them. Transformation from XML to LaTeX can be done with XSLT, so you can create unlimited multiple parallel output formats from a single master document.

The downside is that you have to learn how to do it, find a good XML editor, and learn how to write XSLT to generate the LaTeX outputs. Worth it if you have a very large project, or you are already familiar with the basics, or there is money involved :-)

-
That'd be nice, but XML is ... urgh.. verbose. Would it be possible to do something similar, with a simpler markup language? Maybe YAML? –  naught101 Jun 7 at 21:09

I prefer to have the decision of whether a chapter is included at the point where the chapter is actually included. Something like:

\include{chapA}
\ifdefined\programmers
\include{chapB}
\fi
\ifdefined\riskanalyst
\include{chapC}
\fi
\include{chapD}
\fi

-
This requires multiple \ifdefined conditionals in case a chapter needs to be included for more than one version. –  egreg Jul 7 '11 at 19:22
Yep, I realized that after I posed it, and the link to the conditionals should help. This method also allows for a combinations: such as a book for both programmers and DBadmins. –  Peter Grill Jul 7 '11 at 20:23
These are called effectivities, and are a standard part of technical documentation systems. The specification of what selection of parts gets included is usually done at the top of the document, for example as entity declarations in XML, or [as here] predefinitions of macros or token registers that can be tested at the point of insertion. The decision is thus made up front: it's the implementation that gets done at the point of insertion. –  Peter Flynn Jun 9 at 19:18

Tags might come in handy for this use case and luckily there is a LaTeX package (now, v1.0 is from August 2011) called tagging for that. Check out the following mini example.

main.tex:

\documentclass{article}
\usepackage{tagging}

\begin{document}

\tagged{programmers}{Include programmers section}

\tagged{riskanalyst}{Include riskanalyst section}

\end{document}


Makefile:

LATEX_COMPILER := pdflatex

.PHONY: all
$(LATEX_COMPILER) --jobname="$(basename $@)" "\AtBeginDocument{\usetag{programmers}}\input{main}" Manual_riskanalyst.pdf:$(LATEX_COMPILER) --jobname="$(basename$@)" "\AtBeginDocument{\usetag{riskanalyst}}\input{main}"
$(LATEX_COMPILER) --jobname="$(basename \$@)" "\AtBeginDocument{\usetag{DBadmin}}\input{main}"