1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
<head>
<title>UK TeX FAQ -- question label conditional</title>
</head><body>
<h3>Conditional compilation and “comments”</h3>
<p>While LaTeX (or any other TeX-derived package) isn’t really like a
compiler, people regularly want to do compiler-like things using it.
Common requirements are conditional ‘compilation’ and ‘block
comments’, and several LaTeX-specific means to this end are available.
<p>The simple <code>\</code><code>newcommand{<code>\</code><code>gobble</code>}[1]</code><code>{</code><code>}</code> and
<code>\</code><code>iffalse</code><code> ... </code><code>\</code><code>fi</code> aren’t really satisfactory (as a general
solution) for comments, since the matter being skipped is nevertheless
scanned by TeX, not always as you would expect. The scanning
imposes restrictions on what you’re allowed to skip; this may not be a
problem in <em>today’s</em> job, but could return to bite you tomorrow.
For an example of surprises that may come to bite you, consider the
following example (derived from real user experience):
<blockquote>
<pre>
\iffalse % ignoring this bit
consider what happens if we
use \verb|\iftrue| -- a surprise
\fi
</pre>
</blockquote><p>
The <code>\</code><code>iftrue</code> is spotted by TeX as it scans, ignoring the
<code>\</code><code>verb</code> command; so the <code>\</code><code>iffalse</code> isn’t terminated by the
following <code>\</code><code>fi</code>. Also, <code>\</code><code>gobble</code> is pretty inefficient at
consuming anything non-trivial, since all the matter to be skipped is
copied to the argument stack before being ignored.
<p>If your requirement is for a document from which whole chapters (or
the like) are missing, consider the LaTeX
<code>\</code><code>include</code>/<code>\</code><code>includeonly</code> system. If you ‘<code>\</code><code>include</code>’ your
files (rather than <code>\</code><code>input</code> them — see
<a href="FAQ-include.html">What’s going on in my <code>\</code><code>include</code> commands?</a>),
LaTeX writes macro traces of what’s going on at the end of each
chapter to the <code>.aux</code> file; by using <code>\</code><code>includeonly</code>, you can give
LaTeX an exhaustive list of the files that are needed. Files that
don’t get <code>\</code><code>include</code>d are skipped entirely, but the document
processing continues as if they <em>were</em> there, and page, footnote,
and other numbers are not disturbed. Note that you can choose which
sections you want included interactively, using the
<i>askinclude</i> package.
<p>The inverse can be done using the <i>excludeonly</i> package: this
allows you to exclude a (list of) <code>\</code><code>include</code>d files from your
document, by means of an <code>\</code><code>excludeonly</code> command.
<p>If you want to select particular pages of your document, use Heiko
Oberdiek’s <i>pagesel</i> or the <i>selectp</i> packages. You
can do something similar with an existing PDF document (which
you may have compiled using <i>pdflatex</i> in the first place),
using the <i>pdfpages</i> package. The job is then done with a
document looking like:
<blockquote>
<pre>
\documentclass{article}
\usepackage[final]{pdfpages}
\begin{document}
\includepdf[pages=30-40]{yoursource.pdf}
\end{document}
</pre>
</blockquote><p>
(To include all of the document, you write
<blockquote>
<pre>
\includepdf[pages=-]{yoursource.pdf}
</pre>
</blockquote><p>
omitting the start and end pages in the optional argument.)
<p>If you want flexible facilities for including or excluding small
portions of a file, consider the <i>comment</i>, <i>version</i> or
<i>optional</i> packages.
<p>The <i>comment</i> package allows you to declare areas of a document to be
included or excluded; you make these declarations in the preamble of
your file. The command <code>\</code><code>includecomment{</code><em>version-name</em><code>}</code>
declares an environment <code>version-name</code> whose content will
be included in your document, while
<code>\</code><code>excludecomment{</code><em>version-name</em><code>}</code> defines an environment whose
content will be excluded from the document. The package uses a method
for exclusion that is pretty robust, and can cope with ill-formed
bunches of text (e.g., with unbalanced braces or <code>\</code><code>if</code> commands).
<p>These FAQs employ the <i>comment</i> package to alter layout
between the printed (two-column) version and the PDF version
for browsing; there are <code>narrowversion</code> and
<code>wideversion</code> for the two versions of the file.
<p><i>version</i> offers similar facilities to <i>comment.sty</i>
(i.e., <code>\</code><code>includeversion</code> and <code>\</code><code>excludeversion</code> commands);
it’s far “lighter weight”, but is less robust (and in particular,
cannot deal with very large areas of text being included/excluded).
<p>A significant development of <i>version</i>, confusingly called
<i>versions</i> (i.e., merely a plural of the old package name).
<i>Versions</i> adds a command
<code>\</code><code>markversion{</code><em>version-name</em><code>}</code> which defines an environment
that prints the included text, with a clear printed mark around it.
<p><i>optional</i> defines a command <code>\</code><code>opt</code>; its first argument is
an ‘inclusion flag’, and its second is text to be included or
excluded. Text to be included or excluded must be well-formed
(nothing mismatched), and should not be too big — if a large body of
text is needed, <code>\</code><code>input</code> should be used in the argument.
The documentation (in the package file itself) tells you
how to declare which sections are to be included: this can be done in
the document preamble, but the documentation also suggests ways in
which it can be done on the command line that invokes LaTeX, or
interactively.
<p>And, not least of this style of conditional compilation,
<i>verbatim</i> (which should be available in any distribution)
defines a <code>comment</code> environment, which enables the
dedicated user of the source text editor to suppress bits of a
LaTeX source file. The <i>memoir</i> class offers the same
environment.
<p>An interesting variation is the <i>xcomment</i> package. This
defines an environment whose body is all excluded, apart from
environments named in its argument. So, for example:
<blockquote>
<pre>
\begin{xcomment}{figure,table}
This text is not included
\begin{figure}
This figure is included
\end{figure}
This is not included, either
\begin{table}
This table also included
\end{table}
...
\end{xcomment}
</pre>
</blockquote><p>
<p>A further valuable twist is offered by the <i>extract</i> package.
This allows you to produce a “partial copy” of an existing document:
the package was developed to permit production of a “book of
examples” from a set of lecture notes. The package documentation
shows the following usage:
<blockquote>
<pre>
\usepackage[
active,
generate=foobar,
extract-env={figure,table},
extract-cmd={chapter,section}
]{extract}
</pre>
</blockquote><p>
which will cause the package to produce a file <i>foobar.tex</i>
containing all the <code>figure</code> and <code>table</code>
environments, and the <code>\</code><code>chapter</code> and <code>\</code><code>section</code> commands, from
the document being processed. The new file <i>foobar.tex</i> is
generated in the course of an otherwise ordinary run on the ‘master’
document. The package provides a good number of other facilities,
including (numeric or labelled) ranges of environments to extract, and
an <code>extract</code> environment which you can use to create complete
ready-to-run LaTeX documents with stuff you’ve extracted.
<dl>
<dt><tt><i>askinclude.sty</i></tt><dd><a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/misc/askinclude.sty">macros/latex/contrib/misc/askinclude.sty</a>
<dt><tt><i>comment.sty</i></tt><dd><a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/comment.zip">macros/latex/contrib/comment</a> (<a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/comment.tar.gz">gzipped tar</a>, <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/comment/">browse</a>)
<dt><tt><i>excludeonly.sty</i></tt><dd><a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/misc/excludeonly.sty">macros/latex/contrib/misc/excludeonly.sty</a>
<dt><tt><i>extract.sty</i></tt><dd><a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/extract.zip">macros/latex/contrib/extract</a> (<a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/extract.tar.gz">gzipped tar</a>, <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/extract/">browse</a>)
<dt><tt><i>memoir.cls</i></tt><dd><a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/memoir.zip">macros/latex/contrib/memoir</a> (<a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/memoir.tar.gz">gzipped tar</a>, <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/memoir/">browse</a>)
<dt><tt><i>optional.sty</i></tt><dd><a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/misc/optional.sty">macros/latex/contrib/misc/optional.sty</a>
<dt><tt><i>pagesel.sty</i></tt><dd>Distributed with Heiko Oberdiek’s packages
<a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/oberdiek.zip">macros/latex/contrib/oberdiek</a> (<a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/oberdiek.tar.gz">gzipped tar</a>, <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/oberdiek/">browse</a>)
<dt><tt><i>pdfpages.sty</i></tt><dd><a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/pdfpages.zip">macros/latex/contrib/pdfpages</a> (<a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/pdfpages.tar.gz">gzipped tar</a>, <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/pdfpages/">browse</a>)
<dt><tt><i>selectp.sty</i></tt><dd><a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/misc/selectp.sty">macros/latex/contrib/misc/selectp.sty</a>
<dt><tt><i>verbatim.sty</i></tt><dd>Distributed as part of <a href="ftp://cam.ctan.org/tex-archive/macros/latex/required/tools.zip">macros/latex/required/tools</a> (<a href="ftp://cam.ctan.org/tex-archive/macros/latex/required/tools.tar.gz">gzipped tar</a>, <a href="http://www.tex.ac.uk/tex-archive/macros/latex/required/tools/">browse</a>)
<dt><tt><i>version.sty</i></tt><dd><a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/misc/version.sty">macros/latex/contrib/misc/version.sty</a>
<dt><tt><i>versions.sty</i></tt><dd><a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/versions/versions.sty">macros/latex/contrib/versions/versions.sty</a>
<dt><tt><i>xcomment.sty</i></tt><dd>Distributed as part of <a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/seminar.zip">macros/latex/contrib/seminar</a> (<a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/seminar.tar.gz">gzipped tar</a>, <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/seminar/">browse</a>)
</dl>
<p><p>This question on the Web: <a href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=conditional">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=conditional</a>
</body>
|
