Producing different versions of a document

Question

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...)

Answer 1

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}}
\newcommand\DBadmin{\includeonly{chap1,chap2}}

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}}
\newcommand\DBadmin{%
  \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}"

Answer 2

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
\ifdefined\DBadmin
    \include{chapD}
\fi

You can use more conditionals as per this question., and options on passing parameters to a document can be found in this question.

Answer 3

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 :-)

Answer 4

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}

\tagged{DBadmin}{Include DBadmin section}

\end{document}

Makefile:

LATEX_COMPILER := pdflatex

.PHONY: all
all: Manual_programmers.pdf Manual_programmers.pdf Manual_DBadmin.pdf

Manual_programmers.pdf:
    $(LATEX_COMPILER) --jobname="$(basename $@)" "\AtBeginDocument{\usetag{programmers}}\input{main}"

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

Manual_DBadmin.pdf:
    $(LATEX_COMPILER) --jobname="$(basename $@)" "\AtBeginDocument{\usetag{DBadmin}}\input{main}"