diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-conditional.html')
-rw-r--r-- | Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-conditional.html | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-conditional.html b/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-conditional.html new file mode 100644 index 00000000000..cba1c195363 --- /dev/null +++ b/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-conditional.html @@ -0,0 +1,169 @@ +<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>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>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> |