20

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

SRKX
  • 2,107

4 Answers4

16

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}"
egreg
  • 1,121,712
  • 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 07 '11 at 14:05
  • As far as I can tell it may break cross references. See also edit. – egreg Jul 07 '11 at 14:10
  • "See also edit"? – SRKX Jul 07 '11 at 14:12
  • See also edited answer, sorry. – egreg Jul 07 '11 at 14:14
  • 2
    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 07 '11 at 14:16
  • @egreg: \nofiles shouldn't be necessary here (shouldn't do any harm either). – Lev Bishop Jul 07 '11 at 14:21
  • @Lev: ideally I would like chapter 3 to appear as "Chapter2" in the programmer document. But apparently there is no alternative is it? – SRKX Jul 07 '11 at 14:23
  • 1
    You have to use a different approach, with the comment package. I'll work to it. – egreg Jul 07 '11 at 14:54
  • @JSmaga: egreg's newest update is what I was talking about earlier (just didn't had time to code it myself). – Martin Scharrer Jul 07 '11 at 15:18
4

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.

Community
  • 1
Peter Grill
  • 223,288
  • This requires multiple \ifdefined conditionals in case a chapter needs to be included for more than one version. – egreg Jul 07 '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 07 '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 09 '15 at 19:18
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 :-)

Peter Flynn
  • 2,870
  • 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 07 '15 at 21:09
2

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}"
ypid
  • 1,299