[latexrefman-commits] [SCM] latexrefman updated: r620 - trunk
jimhefferon at gnu.org.ua
jimhefferon at gnu.org.ua
Thu May 17 23:43:30 CEST 2018
Author: jimhefferon
Date: 2018-05-18 00:43:30 +0300 (Fri, 18 May 2018)
New Revision: 620
Modified:
trunk/ChangeLog
trunk/latex2e.html
trunk/latex2e.info
trunk/latex2e.pdf
trunk/latex2e.texi
Log:
Change Splitting the input to add more examples and edge cases for input and inputonly
Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog 2018-05-04 17:54:54 UTC (rev 619)
+++ trunk/ChangeLog 2018-05-17 21:43:30 UTC (rev 620)
@@ -1,3 +1,11 @@
+2018-05-17 Jim Hefferon <jhefferon at smcvt.edu>
+
+ * latex2e.texi (\include & \incluldeonly) Combine the two. Include
+ discussion of many edge cases, with examples.
+ (Splitting the input) Add typical case example.
+ (\endinput) Added.
+ (\input) Adjust wording to fit changes.
+
2018-05-04 Vincent Belaïche <vincent.belaiche at biosency.com>
* latex2e-fr.texi (Color): Translate node Color from Jim's r609 —
Modified: trunk/latex2e.html
===================================================================
--- trunk/latex2e.html 2018-05-04 17:54:54 UTC (rev 619)
+++ trunk/latex2e.html 2018-05-17 21:43:30 UTC (rev 620)
@@ -430,8 +430,8 @@
</ul></li>
<li><a name="toc-Splitting-the-input-1" href="#Splitting-the-input">24 Splitting the input</a>
<ul class="no-bullet">
- <li><a name="toc-_005cinclude-1" href="#g_t_005cinclude">24.1 <code>\include</code></a></li>
- <li><a name="toc-_005cincludeonly-1" href="#g_t_005cincludeonly">24.2 <code>\includeonly</code></a></li>
+ <li><a name="toc-_005cendinput-1" href="#g_t_005cendinput">24.1 <code>\endinput</code></a></li>
+ <li><a name="toc-_005cinclude-_0026-_005cincludeonly-1" href="#g_t_005cinclude-_0026-_005cincludeonly">24.2 <code>\include</code> & <code>\includeonly</code></a></li>
<li><a name="toc-_005cinput-1" href="#g_t_005cinput">24.3 <code>\input</code></a></li>
</ul></li>
<li><a name="toc-Front_002fback-matter-1" href="#Front_002fback-matter">25 Front/back matter</a>
@@ -5591,8 +5591,8 @@
<a name="index-package_002c-picture"></a>
<a name="index-picture-package"></a>
-<p>The <code>picture</code> package redefine the <code>picture</code> environment so
-that everywhere a number is used in a <var>picture commands</var> to specify
+<p>The <code>picture</code> package redefines the <code>picture</code> environment so
+that everywhere a number is used in <var>picture commands</var> to specify
a coordinate, one can use alternatively a length. Be aware however that
this will prevent scaling those lengths by changing <code>\unitlength</code>.
</p>
@@ -15498,90 +15498,241 @@
<a name="index-splitting-the-input-file"></a>
<a name="index-input-file"></a>
-<p>A large document requires a lot of input. Rather than putting the whole
-input in a single large file, it’s more efficient to split it into
-several smaller ones. Regardless of how many separate files you use,
-there is one that is the
+<p>LaTeX lets you split a large document into several smaller ones.
+This can simplify editing or allow multiple authors to work on the
+document. It can also speed processing.
+</p>
+<p>Regardless of how many separate files you use, there is always one
<a name="index-root-file"></a>
<a name="index-file_002c-root"></a>
-<em>root file</em>; it is the one whose name you type
-when you run LaTeX.
+<em>root file</em>, on which LaTeX compilation starts.
+This shows such a file with three included files.
</p>
-<p>See <a href="#filecontents">filecontents</a>, for an environment that allows bundling an
-external file to be created with the main document.
+<div class="example">
+<pre class="example">\documentclass{book}
+\includeonly{ % comment out lines here to skip compiling those parts
+ pref,
+ chap1,
+ chap2
+ }
+\begin{document}
+\frontmatter
+\include{pref}
+\mainmatter
+\include{chap1}
+\include{chap2}
+\end{document}
+</pre></div>
+
+<p>This will bring in material from <samp>pref.tex</samp>, <samp>chap1.tex</samp>, and
+<samp>chap2.tex</samp>. If you compile this file, then comment out the lines
+inside <code>\includeonly{...}</code> containing <code>pref</code> and
+<code>chap2</code> and compile again, then LaTeX will only process the
+material in the first chapter but will retain the page numbers and all
+of the cross reference information from the preface and second chapter.
</p>
+
<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#g_t_005cinclude" accesskey="1">\include</a>:</td><td> </td><td align="left" valign="top">Conditionally include a file.
+<tr><td align="left" valign="top">• <a href="#g_t_005cendinput" accesskey="1">\endinput</a>:</td><td> </td><td align="left" valign="top">Stop including material from a file.
</td></tr>
-<tr><td align="left" valign="top">• <a href="#g_t_005cincludeonly" accesskey="2">\includeonly</a>:</td><td> </td><td align="left" valign="top">Determine which files are included.
+<tr><td align="left" valign="top">• <a href="#g_t_005cinclude-_0026-_005cincludeonly" accesskey="2">\include & \includeonly</a>:</td><td> </td><td align="left" valign="top">Conditionally include files.
</td></tr>
<tr><td align="left" valign="top">• <a href="#g_t_005cinput" accesskey="3">\input</a>:</td><td> </td><td align="left" valign="top">Unconditionally include a file.
</td></tr>
</table>
+
<hr>
-<a name="g_t_005cinclude"></a>
+<a name="g_t_005cendinput"></a>
<div class="header">
<p>
-Next: <a href="#g_t_005cincludeonly" accesskey="n" rel="next">\includeonly</a>, Up: <a href="#Splitting-the-input" accesskey="u" rel="up">Splitting the input</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
+Next: <a href="#g_t_005cinclude-_0026-_005cincludeonly" accesskey="n" rel="next">\include & \includeonly</a>, Up: <a href="#Splitting-the-input" accesskey="u" rel="up">Splitting the input</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
-<a name="g_t_005cinclude-1"></a>
-<h3 class="section">24.1 <code>\include</code></h3>
+<a name="g_t_005cendinput-1"></a>
+<h3 class="section">24.1 <code>\endinput</code></h3>
-<a name="index-_005cinclude"></a>
+<a name="index-_005cendinput"></a>
<p>Synopsis:
</p>
<div class="example">
-<pre class="example">\include{<var>file</var>}
+<pre class="example">\endinput
</pre></div>
-<p>If no <code>\includeonly</code> command is present, the <code>\include</code>
-command executes <code>\clearpage</code> to start a new page
-(see <a href="#g_t_005cclearpage">\clearpage</a>), then reads <var>file</var>, then does another
-<code>\clearpage</code>.
+<p>When you <code>\include{file}</code>, inside <samp>filename.tex</samp> the
+material after <code>\endinput</code> will not be included. This command is
+optional; if <samp>filename.tex</samp> has no <code>\endinput</code> then LaTeX
+will read all of the file.
</p>
-<p>Given an <code>\includeonly</code> command, the <code>\include</code> actions are
-only run if <var>file</var> is listed as an argument to
-<code>\includeonly</code>. See <a href="#g_t_005cincludeonly">\includeonly</a>.
+<p>For example, suppose that a document’s root file has
+<code>\input{chap1}</code> and this is <samp>chap1.tex</samp>.
</p>
-<a name="index-nested-_005cinclude_002c-not-allowed"></a>
-<p>The <code>\include</code> command may not appear in the preamble or in a file
-read by another <code>\include</code> command.
+<div class="example">
+<pre class="example">\chapter{One}
+This material will appear in the document.
+\endinput
+This will not appear.
+</pre></div>
+
+<p>This can be useful for putting documentation or comments at the end of a
+file, or for avoiding junk characters that can be added during mailing.
+It is also useful for debugging: one strategy to localize errors is to
+put <code>\endinput</code> halfway through the included file and see if the
+error disappears. Now, knowing which half contains the error, moving
+<code>\endinput</code> to halfway through that area further narrows down the
+location. This process rapidly finds the offending line.
</p>
+<p>After reading <code>\endinput</code>, LaTeX continues to read to the end of
+the line, so something can follow this command and be read nonetheless.
+This allows you, for instance, to close an <code>\if...</code> with a
+<code>\fi</code>.
+</p>
<hr>
-<a name="g_t_005cincludeonly"></a>
+<a name="g_t_005cinclude-_0026-_005cincludeonly"></a>
<div class="header">
<p>
-Next: <a href="#g_t_005cinput" accesskey="n" rel="next">\input</a>, Previous: <a href="#g_t_005cinclude" accesskey="p" rel="prev">\include</a>, Up: <a href="#Splitting-the-input" accesskey="u" rel="up">Splitting the input</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
+Next: <a href="#g_t_005cinput" accesskey="n" rel="next">\input</a>, Previous: <a href="#g_t_005cendinput" accesskey="p" rel="prev">\endinput</a>, Up: <a href="#Splitting-the-input" accesskey="u" rel="up">Splitting the input</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
-<a name="g_t_005cincludeonly-1"></a>
-<h3 class="section">24.2 <code>\includeonly</code></h3>
+<a name="g_t_005cinclude-_0026-_005cincludeonly-1"></a>
+<h3 class="section">24.2 <code>\include</code> & <code>\includeonly</code></h3>
+<a name="index-_005cinclude"></a>
<a name="index-_005cincludeonly"></a>
<p>Synopsis:
</p>
<div class="example">
-<pre class="example">\includeonly{<var>file1</var>,<var>file2</var>,...}
+<pre class="example">\includeonly{ % in document preamble
+ ...
+ <var>filename</var>,
+ ...
+ }
+ ...
+\include{<var>filename</var>} % in document body
</pre></div>
-<p>The <code>\includeonly</code> command controls which files will be read by
-subsequent <code>\include</code> commands. The list of filenames is
-comma-separated. Each element <var>file1</var>, <var>file2</var>, … must
-exactly match a filename specified in a <code>\include</code> command for the
-selection to be effective.
+<p>Bring material from the external file <samp><var>filename</var>.tex</samp> into a
+LaTeX document.
</p>
-<p>This command can only appear in the preamble.
+<p>The <code>\include</code> command does three things: it executes
+<code>\clearpage</code> (see <a href="#g_t_005cclearpage">\clearpage</a>), then it inputs the material from
+<samp>filename.tex</samp> into the document, and then it does another
+<code>\clearpage</code>. This command can only appear in the document body.
+The <code>\includeonly</code> command controls which files will be read by
+LaTeX under subsequent <code>\include</code> commands. Its list of
+filenames is comma-separated, and it can only appear in the preamble.
</p>
+<p>This example root document, <samp>constitution.tex</samp>, brings in
+three files, <samp>preamble.tex</samp>, <samp>articles.tex</samp>, and
+<samp>amendments.tex</samp>.
+</p>
+<div class="example">
+<pre class="example">\documentclass{book}
+\includeonly{
+ preamble,
+ articles,
+ amendments
+ }
+\begin{document}
+\include{preamble}
+\include{articles}
+\include{amendments}
+\end{document}
+</pre></div>
+<p>The file <samp>preamble.tex</samp> contains no special code; you have just
+excerpted the chapter from <samp>consitution.tex</samp> and put it in a
+separate file just for editing convenience.
+</p>
+<div class="example">
+<pre class="example">\chapter{Preamble}
+We the People of the United States, in Order to form a more perfect Union, …
+</pre></div>
+
+<p>Running LaTeX on <samp>constitution.tex</samp> makes the material from the
+three files appear in the document but also generates the auxillary
+files <samp>preamble.aux</samp>, <samp>articles.aux</samp>, and
+<samp>amendments.tex</samp>. These contain information such as page numbers
+and cross-references (see <a href="#Cross-references">Cross references</a>). If you now comment out
+<code>\includeonly</code>’s lines with <code>preamble</code> and <code>amendments</code>
+and run LaTeX again then the resulting document shows only the
+material from <samp>articles.tex</samp>, not the material from
+<samp>preamble.tex</samp> or <samp>amendments.tex</samp>. Nonetheless, all of the
+auxillary information from the omitted files, including the starting
+page number of this chapter, is still there.
+</p>
+<p>If the document preamble does not have <code>\includeonly</code> then
+LaTeX will include all the files you call for with <code>\include</code>
+commands.
+</p>
+<p>The <code>\include</code> command makess a new page. To avoid that, see
+<a href="#g_t_005cinput">\input</a> (which, however, does not retain the auxillary
+information).
+</p>
+<p>File names can involve paths.
+</p>
+<div class="example">
+<pre class="example">\documentclass{book}
+\includeonly{
+ chapters/chap1,
+ }
+\begin{document}
+\include{chapters/chap1}
+\end{document}
+</pre></div>
+
+<p>To make your document portable across distributions and platforms you
+should avoid spaces. The tradition is to instead use underscores in the
+file names. That said, for the filename ‘<samp><samp>amo amas amat</samp></samp>’,
+this works under TeX Live on Linux
+</p>
+<div class="example">
+<pre class="example">\documentclass{book}
+\includeonly{
+ "amo\space amas\space amat"
+ }
+\begin{document}
+\include{"amo\space amas\space amat"}
+\end{document}
+</pre></div>
+
+<p>and this works under MiKTeX on Windows.
+</p>
+<div class="example">
+<pre class="example">\documentclass{book}
+\includeonly{
+ {"amo amas amat"}
+ }
+\begin{document}
+\include{{"amo amas amat"}}
+\end{document}
+</pre></div>
+
+<a name="index-nested-_005cinclude_002c-not-allowed"></a>
+<p>You cannot use <code>\include</code> inside a file that is being included or
+you get ‘<samp>! LaTeX Error: \include cannot be nested.</samp>’ The
+<code>\include</code> command cannot appear in the document preamble; you will
+get ‘<samp>! LaTeX Error: Missing \begin{document}.</samp>’.
+</p>
+<p>If a file that you <code>\include</code> does not exist, for instance if you
+<code>\include{athiesm}</code> but you meant <code>\include{atheism}</code>,
+then LaTeX does not give you an error but will warn you ‘<samp>No file
+athiesm.tex.</samp>’ (It will also create <samp>athiesm.aux</samp>.)
+</p>
+<p>If you <code>\include</code> the root file in itself then you first get
+‘<samp>! LaTeX Error: Can be used only in preamble.</samp>’ Later runs get
+‘<samp>! TeX capacity exceeded, sorry [text input levels=15]</samp>’. To fix
+this, you must remove the inclusion <code>\include{root}</code> but also
+delete the file <samp><var>root</var>.aux</samp> and rerun LaTeX.
+</p>
+
<hr>
<a name="g_t_005cinput"></a>
<div class="header">
<p>
-Previous: <a href="#g_t_005cincludeonly" accesskey="p" rel="prev">\includeonly</a>, Up: <a href="#Splitting-the-input" accesskey="u" rel="up">Splitting the input</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
+Previous: <a href="#g_t_005cinclude-_0026-_005cincludeonly" accesskey="p" rel="prev">\include & \includeonly</a>, Up: <a href="#Splitting-the-input" accesskey="u" rel="up">Splitting the input</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="g_t_005cinput-1"></a>
<h3 class="section">24.3 <code>\input</code></h3>
@@ -15594,14 +15745,17 @@
<pre class="example">\input{<var>file</var>}
</pre></div>
-<p>The <code>\input</code> command causes the specified <var>file</var> to be read
-and processed, as if its contents had been inserted in the current
-file at that point.
+<p>Read <samp><var>file</var>.tex</samp> as if its contents were inserted in the
+current file. For a more sophisticated inclusion mechanism see
+<a href="#g_t_005cinclude-_0026-_005cincludeonly">\include & \includeonly</a>.
</p>
-<p>If <var>file</var> does not end in ‘<samp>.tex</samp>’ (e.g., ‘<samp>foo</samp>’ or
-‘<samp>foo.bar</samp>’), it is first tried with that extension (‘<samp>foo.tex</samp>’
-or ‘<samp>foo.bar.tex</samp>’). If that is not found, the original <var>file</var>
-is tried (‘<samp>foo</samp>’ or ‘<samp>foo.bar</samp>’).
+<p>If <var>file</var> end with ‘<samp>.tex</samp>’ then LaTeX looks for the filename
+as it is. If <var>file</var> does not end in ‘<samp>.tex</samp>’ then LaTeX first
+tries the filename with that extension, so <code>\include{macros}</code>
+will cause LaTeX to first look for <samp>macros.tex</samp>; this is the
+usual case. If there is no such file then the system tries the original
+file name, here ‘<samp><samp>macros</samp></samp>’, without an extension. (This may
+vary by distribution.)
</p>
<hr>
@@ -17144,7 +17298,7 @@
<tr><td></td><td valign="top"><a href="#index-multiplication-symbol_002c-discretionary-line-break">multiplication symbol, discretionary line break</a>:</td><td> </td><td valign="top"><a href="#Math-miscellany">Math miscellany</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-N">N</a></th><td></td><td></td></tr>
-<tr><td></td><td valign="top"><a href="#index-nested-_005cinclude_002c-not-allowed">nested <code>\include</code>, not allowed</a>:</td><td> </td><td valign="top"><a href="#g_t_005cinclude">\include</a></td></tr>
+<tr><td></td><td valign="top"><a href="#index-nested-_005cinclude_002c-not-allowed">nested <code>\include</code>, not allowed</a>:</td><td> </td><td valign="top"><a href="#g_t_005cinclude-_0026-_005cincludeonly">\include & \includeonly</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-new-class-commands">new class commands</a>:</td><td> </td><td valign="top"><a href="#Class-and-package-construction">Class and package construction</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-new-command_002c-check">new command, check</a>:</td><td> </td><td valign="top"><a href="#Class-and-package-commands">Class and package commands</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-new-command_002c-definition">new command, definition</a>:</td><td> </td><td valign="top"><a href="#Class-and-package-commands">Class and package commands</a></td></tr>
@@ -17840,6 +17994,7 @@
<tr><td></td><td valign="top"><a href="#index-_005cemptyset"><code>\emptyset</code></a>:</td><td> </td><td valign="top"><a href="#Math-symbols">Math symbols</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_005cencl"><code>\encl</code></a>:</td><td> </td><td valign="top"><a href="#g_t_005cencl">\encl</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_005cend"><code>\end</code></a>:</td><td> </td><td valign="top"><a href="#Environments">Environments</a></td></tr>
+<tr><td></td><td valign="top"><a href="#index-_005cendinput"><code>\endinput</code></a>:</td><td> </td><td valign="top"><a href="#g_t_005cendinput">\endinput</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_005cenlargethispage"><code>\enlargethispage</code></a>:</td><td> </td><td valign="top"><a href="#g_t_005cenlargethispage">\enlargethispage</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_005cenumi"><code>\enumi</code></a>:</td><td> </td><td valign="top"><a href="#enumerate">enumerate</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_005cenumii"><code>\enumii</code></a>:</td><td> </td><td valign="top"><a href="#enumerate">enumerate</a></td></tr>
@@ -17937,9 +18092,9 @@
<tr><td></td><td valign="top"><a href="#index-_005cIm"><code>\Im</code></a>:</td><td> </td><td valign="top"><a href="#Math-symbols">Math symbols</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_005cimath"><code>\imath</code></a>:</td><td> </td><td valign="top"><a href="#Math-accents">Math accents</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_005cin"><code>\in</code></a>:</td><td> </td><td valign="top"><a href="#Math-symbols">Math symbols</a></td></tr>
-<tr><td></td><td valign="top"><a href="#index-_005cinclude"><code>\include</code></a>:</td><td> </td><td valign="top"><a href="#g_t_005cinclude">\include</a></td></tr>
+<tr><td></td><td valign="top"><a href="#index-_005cinclude"><code>\include</code></a>:</td><td> </td><td valign="top"><a href="#g_t_005cinclude-_0026-_005cincludeonly">\include & \includeonly</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_005cincludegraphics"><code>\includegraphics</code></a>:</td><td> </td><td valign="top"><a href="#g_t_005cincludegraphics">\includegraphics</a></td></tr>
-<tr><td></td><td valign="top"><a href="#index-_005cincludeonly"><code>\includeonly</code></a>:</td><td> </td><td valign="top"><a href="#g_t_005cincludeonly">\includeonly</a></td></tr>
+<tr><td></td><td valign="top"><a href="#index-_005cincludeonly"><code>\includeonly</code></a>:</td><td> </td><td valign="top"><a href="#g_t_005cinclude-_0026-_005cincludeonly">\include & \includeonly</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_005cindent"><code>\indent</code></a>:</td><td> </td><td valign="top"><a href="#g_t_005cindent">\indent</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_005cindex"><code>\index</code></a>:</td><td> </td><td valign="top"><a href="#Indexes">Indexes</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_005cindexentry"><code>\indexentry</code></a>:</td><td> </td><td valign="top"><a href="#Indexes">Indexes</a></td></tr>
Modified: trunk/latex2e.info
===================================================================
--- trunk/latex2e.info 2018-05-04 17:54:54 UTC (rev 619)
+++ trunk/latex2e.info 2018-05-17 21:43:30 UTC (rev 620)
@@ -3616,10 +3616,10 @@
command. When you do this, the reference point will be the lower left
corner of the box.
- The 'picture' package redefine the 'picture' environment so that
-everywhere a number is used in a PICTURE COMMANDS to specify a
-coordinate, one can use alternatively a length. Be aware however that
-this will prevent scaling those lengths by changing '\unitlength'.
+ The 'picture' package redefines the 'picture' environment so that
+everywhere a number is used in PICTURE COMMANDS to specify a coordinate,
+one can use alternatively a length. Be aware however that this will
+prevent scaling those lengths by changing '\unitlength'.
The 'picture' commands are described in the following sections.
@@ -9967,62 +9967,192 @@
24 Splitting the input
**********************
-A large document requires a lot of input. Rather than putting the whole
-input in a single large file, it's more efficient to split it into
-several smaller ones. Regardless of how many separate files you use,
-there is one that is the "root file"; it is the one whose name you type
-when you run LaTeX.
+LaTeX lets you split a large document into several smaller ones. This
+can simplify editing or allow multiple authors to work on the document.
+It can also speed processing.
- *Note filecontents::, for an environment that allows bundling an
-external file to be created with the main document.
+ Regardless of how many separate files you use, there is always one
+"root file", on which LaTeX compilation starts. This shows such a file
+with three included files.
+ \documentclass{book}
+ \includeonly{ % comment out lines here to skip compiling those parts
+ pref,
+ chap1,
+ chap2
+ }
+ \begin{document}
+ \frontmatter
+ \include{pref}
+ \mainmatter
+ \include{chap1}
+ \include{chap2}
+ \end{document}
+
+ This will bring in material from 'pref.tex', 'chap1.tex', and
+'chap2.tex'. If you compile this file, then comment out the lines
+inside '\includeonly{...}' containing 'pref' and 'chap2' and compile
+again, then LaTeX will only process the material in the first chapter
+but will retain the page numbers and all of the cross reference
+information from the preface and second chapter.
+
* Menu:
-* \include:: Conditionally include a file.
-* \includeonly:: Determine which files are included.
-* \input:: Unconditionally include a file.
+* \endinput:: Stop including material from a file.
+* \include & \includeonly:: Conditionally include files.
+* \input:: Unconditionally include a file.
-File: latex2e.info, Node: \include, Next: \includeonly, Up: Splitting the input
+File: latex2e.info, Node: \endinput, Next: \include & \includeonly, Up: Splitting the input
-24.1 '\include'
-===============
+24.1 '\endinput'
+================
Synopsis:
- \include{FILE}
+ \endinput
- If no '\includeonly' command is present, the '\include' command
-executes '\clearpage' to start a new page (*note \clearpage::), then
-reads FILE, then does another '\clearpage'.
+ When you '\include{file}', inside 'filename.tex' the material after
+'\endinput' will not be included. This command is optional; if
+'filename.tex' has no '\endinput' then LaTeX will read all of the file.
- Given an '\includeonly' command, the '\include' actions are only run
-if FILE is listed as an argument to '\includeonly'. See *note
-\includeonly::.
+ For example, suppose that a document's root file has '\input{chap1}'
+and this is 'chap1.tex'.
- The '\include' command may not appear in the preamble or in a file
-read by another '\include' command.
+ \chapter{One}
+ This material will appear in the document.
+ \endinput
+ This will not appear.
+ This can be useful for putting documentation or comments at the end
+of a file, or for avoiding junk characters that can be added during
+mailing. It is also useful for debugging: one strategy to localize
+errors is to put '\endinput' halfway through the included file and see
+if the error disappears. Now, knowing which half contains the error,
+moving '\endinput' to halfway through that area further narrows down the
+location. This process rapidly finds the offending line.
+
+ After reading '\endinput', LaTeX continues to read to the end of the
+line, so something can follow this command and be read nonetheless.
+This allows you, for instance, to close an '\if...' with a '\fi'.
+
-File: latex2e.info, Node: \includeonly, Next: \input, Prev: \include, Up: Splitting the input
+File: latex2e.info, Node: \include & \includeonly, Next: \input, Prev: \endinput, Up: Splitting the input
-24.2 '\includeonly'
-===================
+24.2 '\include' & '\includeonly'
+================================
Synopsis:
- \includeonly{FILE1,FILE2,...}
+ \includeonly{ % in document preamble
+ ...
+ FILENAME,
+ ...
+ }
+ ...
+ \include{FILENAME} % in document body
- The '\includeonly' command controls which files will be read by
-subsequent '\include' commands. The list of filenames is
-comma-separated. Each element FILE1, FILE2, ... must exactly match a
-filename specified in a '\include' command for the selection to be
-effective.
+ Bring material from the external file 'FILENAME.tex' into a LaTeX
+document.
- This command can only appear in the preamble.
+ The '\include' command does three things: it executes '\clearpage'
+(*note \clearpage::), then it inputs the material from 'filename.tex'
+into the document, and then it does another '\clearpage'. This command
+can only appear in the document body. The '\includeonly' command
+controls which files will be read by LaTeX under subsequent '\include'
+commands. Its list of filenames is comma-separated, and it can only
+appear in the preamble.
+ This example root document, 'constitution.tex', brings in three
+files, 'preamble.tex', 'articles.tex', and 'amendments.tex'.
+
+ \documentclass{book}
+ \includeonly{
+ preamble,
+ articles,
+ amendments
+ }
+ \begin{document}
+ \include{preamble}
+ \include{articles}
+ \include{amendments}
+ \end{document}
+
+ The file 'preamble.tex' contains no special code; you have just
+excerpted the chapter from 'consitution.tex' and put it in a separate
+file just for editing convenience.
+
+ \chapter{Preamble}
+ We the People of the United States, in Order to form a more perfect Union, ...
+
+ Running LaTeX on 'constitution.tex' makes the material from the three
+files appear in the document but also generates the auxillary files
+'preamble.aux', 'articles.aux', and 'amendments.tex'. These contain
+information such as page numbers and cross-references (*note Cross
+references::). If you now comment out '\includeonly''s lines with
+'preamble' and 'amendments' and run LaTeX again then the resulting
+document shows only the material from 'articles.tex', not the material
+from 'preamble.tex' or 'amendments.tex'. Nonetheless, all of the
+auxillary information from the omitted files, including the starting
+page number of this chapter, is still there.
+
+ If the document preamble does not have '\includeonly' then LaTeX will
+include all the files you call for with '\include' commands.
+
+ The '\include' command makess a new page. To avoid that, see *note
+\input:: (which, however, does not retain the auxillary information).
+
+ File names can involve paths.
+
+ \documentclass{book}
+ \includeonly{
+ chapters/chap1,
+ }
+ \begin{document}
+ \include{chapters/chap1}
+ \end{document}
+
+ To make your document portable across distributions and platforms you
+should avoid spaces. The tradition is to instead use underscores in the
+file names. That said, for the filename ''amo amas amat'', this works
+under TeX Live on Linux
+
+ \documentclass{book}
+ \includeonly{
+ "amo\space amas\space amat"
+ }
+ \begin{document}
+ \include{"amo\space amas\space amat"}
+ \end{document}
+
+ and this works under MiKTeX on Windows.
+
+ \documentclass{book}
+ \includeonly{
+ {"amo amas amat"}
+ }
+ \begin{document}
+ \include{{"amo amas amat"}}
+ \end{document}
+
+ You cannot use '\include' inside a file that is being included or you
+get '! LaTeX Error: \include cannot be nested.' The '\include' command
+cannot appear in the document preamble; you will get '! LaTeX Error:
+Missing \begin{document}.'.
+
+ If a file that you '\include' does not exist, for instance if you
+'\include{athiesm}' but you meant '\include{atheism}', then LaTeX does
+not give you an error but will warn you 'No file athiesm.tex.' (It will
+also create 'athiesm.aux'.)
+
+ If you '\include' the root file in itself then you first get '! LaTeX
+Error: Can be used only in preamble.' Later runs get '! TeX capacity
+exceeded, sorry [text input levels=15]'. To fix this, you must remove
+the inclusion '\include{root}' but also delete the file 'ROOT.aux' and
+rerun LaTeX.
+
-File: latex2e.info, Node: \input, Prev: \includeonly, Up: Splitting the input
+File: latex2e.info, Node: \input, Prev: \include & \includeonly, Up: Splitting the input
24.3 '\input'
=============
@@ -10031,13 +10161,16 @@
\input{FILE}
- The '\input' command causes the specified FILE to be read and
-processed, as if its contents had been inserted in the current file at
-that point.
+ Read 'FILE.tex' as if its contents were inserted in the current file.
+For a more sophisticated inclusion mechanism see *note \include &
+\includeonly::.
- If FILE does not end in '.tex' (e.g., 'foo' or 'foo.bar'), it is
-first tried with that extension ('foo.tex' or 'foo.bar.tex'). If that
-is not found, the original FILE is tried ('foo' or 'foo.bar').
+ If FILE end with '.tex' then LaTeX looks for the filename as it is.
+If FILE does not end in '.tex' then LaTeX first tries the filename with
+that extension, so '\include{macros}' will cause LaTeX to first look for
+'macros.tex'; this is the usual case. If there is no such file then the
+system tries the original file name, here ''macros'', without an
+extension. (This may vary by distribution.)
File: latex2e.info, Node: Front/back matter, Next: Letters, Prev: Splitting the input, Up: Top
@@ -11032,7 +11165,7 @@
* figure number, cross referencing: \ref. (line 6)
* figures, footnotes in: minipage. (line 21)
* figures, inserting: figure. (line 6)
-* file, root: Splitting the input. (line 9)
+* file, root: Splitting the input. (line 10)
* fixed-width font: Font styles. (line 92)
* flafter package: Floats. (line 82)
* float package: Floats. (line 52)
@@ -11263,7 +11396,8 @@
* multind package: Indexes. (line 39)
* multiplication symbol, discretionary line break: Math miscellany.
(line 7)
-* nested \include, not allowed: \include. (line 18)
+* nested \include, not allowed: \include & \includeonly.
+ (line 99)
* new class commands: Class and package construction.
(line 6)
* new command, check: Class and package commands.
@@ -11445,7 +11579,7 @@
* ring accent, math: Math accents. (line 41)
* robust commands: \protect. (line 6)
* roman font: Font styles. (line 80)
-* root file: Splitting the input. (line 9)
+* root file: Splitting the input. (line 10)
* rotating graphics: \rotatebox. (line 6)
* rotating text: \rotatebox. (line 6)
* rotation: \rotatebox. (line 6)
@@ -11914,6 +12048,7 @@
* \emptyset: Math symbols. (line 197)
* \encl: \encl. (line 6)
* \end: Environments. (line 6)
+* \endinput: \endinput. (line 6)
* \enlargethispage: \enlargethispage. (line 6)
* \enumi: enumerate. (line 47)
* \enumii: enumerate. (line 47)
@@ -12034,9 +12169,11 @@
* \Im: Math symbols. (line 262)
* \imath: Math accents. (line 34)
* \in: Math symbols. (line 265)
-* \include: \include. (line 6)
+* \include: \include & \includeonly.
+ (line 6)
* \includegraphics: \includegraphics. (line 6)
-* \includeonly: \includeonly. (line 6)
+* \includeonly: \include & \includeonly.
+ (line 6)
* \indent: \indent. (line 6)
* \index: Indexes. (line 9)
* \indexentry: Indexes. (line 12)
@@ -12916,196 +13053,196 @@
Node: math138769
Node: minipage139075
Node: picture140267
-Node: \circle145284
-Node: \makebox (picture)145627
-Node: \framebox (picture)146333
-Node: \dashbox146823
-Node: \frame147346
-Node: \line147672
-Node: \linethickness148130
-Node: \thicklines148551
-Node: \thinlines148861
-Node: \multiput149163
-Node: \oval149530
-Node: \put150251
-Node: \shortstack150542
-Node: \vector151016
-Node: quotation and quote151330
-Node: tabbing152537
-Node: table158475
-Node: tabular159902
-Node: \multicolumn167110
-Node: \vline170995
-Node: \cline172340
-Node: \hline173024
-Node: thebibliography173707
-Node: \bibitem175321
-Node: \cite176079
-Node: \nocite176598
-Node: Using BibTeX176886
-Node: theorem178395
-Node: titlepage178781
-Node: verbatim180071
-Node: \verb180710
-Node: verse181260
-Node: Line breaking181754
-Node: \\182851
-Node: \obeycr & \restorecr183889
-Node: \newline184291
-Node: \- (hyphenation)185125
-Node: \discretionary185740
-Node: \fussy186032
-Node: \sloppy186422
-Node: \hyphenation186749
-Node: \linebreak & \nolinebreak187374
-Node: Page breaking188026
-Node: \cleardoublepage188634
-Node: \clearpage189063
-Node: \newpage189360
-Node: \enlargethispage189591
-Node: \pagebreak & \nopagebreak190118
-Node: Footnotes190812
-Node: \footnote192066
-Node: \footnotemark193862
-Node: \footnotetext195106
-Node: Footnotes in a table195596
-Node: Footnotes in section headings197453
-Node: Footnotes of footnotes198309
-Node: Multiple reference to footnotes199076
-Node: Footnote parameters199934
-Node: Definitions200684
-Node: \newcommand & \renewcommand201561
-Node: \providecommand205397
-Node: \newcounter206058
-Node: \newlength207029
-Node: \newsavebox207676
-Node: \newenvironment & \renewenvironment208287
-Node: \newtheorem212647
-Node: \newfont216136
-Node: \protect217701
-Node: \ignorespaces & \ignorespacesafterend220087
-Node: Counters222836
-Node: \alph \Alph \arabic \roman \Roman \fnsymbol224436
-Node: \usecounter226508
-Node: \value227340
-Node: \setcounter228283
-Node: \addtocounter228769
-Node: \refstepcounter229234
-Node: \stepcounter229892
-Node: \day \month \year230234
-Node: Lengths230779
-Node: Units of length232569
-Node: \setlength234063
-Node: \addtolength234467
-Node: \settodepth234785
-Node: \settoheight235076
-Node: \settowidth235373
-Node: Predefined lengths235681
-Node: Making paragraphs236196
-Node: \indent236768
-Node: \noindent237230
-Node: \parskip237739
-Node: Marginal notes237997
-Node: Math formulas239809
-Node: Subscripts & superscripts241593
-Node: Math symbols242931
-Node: Math functions268260
-Node: Math accents269203
-Node: Spacing in math mode270175
-Node: Math miscellany271642
-Node: Modes274192
-Node: \ensuremath276032
-Node: Page styles276948
-Node: \maketitle277442
-Node: \pagenumbering278512
-Node: \pagestyle279008
-Node: \thispagestyle280149
-Node: Spaces280455
-Node: \hspace281325
-Node: \hfill282280
-Node: \spacefactor282672
-Node: \(SPACE) and \@285384
-Ref: \AT285527
-Node: \frenchspacing287004
-Node: \normalsfcodes287620
-Node: \(SPACE) after control sequence287809
-Node: \thinspace288720
-Node: \/289040
-Node: \hrulefill \dotfill290222
-Node: \addvspace291215
-Node: \bigskip \medskip \smallskip292261
-Node: \vfill293153
-Node: \vspace294022
-Node: Boxes295015
-Node: \mbox295727
-Node: \fbox and \framebox296014
-Node: lrbox296818
-Node: \makebox297176
-Node: \parbox297896
-Node: \raisebox299464
-Node: \savebox300061
-Node: \sbox300476
-Node: \usebox300925
-Node: Color301186
-Node: Color package options302030
-Node: Color models303676
-Node: Commands for color305985
-Node: Define colors306400
-Node: Colored text307115
-Node: Colored boxes309490
-Node: Colored pages310929
-Node: Graphics311622
-Node: Graphics package options313741
-Node: Graphics package configuration316497
-Node: \graphicspath317288
-Node: \DeclareGraphicsExtensions320211
-Node: \DeclareGraphicsRule322004
-Node: Commands for graphics325193
-Node: \includegraphics325698
-Node: \rotatebox338724
-Node: \scalebox341519
-Node: \resizebox342571
-Node: Special insertions343763
-Node: Reserved characters344567
-Node: Upper and lower case345768
-Node: Symbols by font position347683
-Node: Text symbols348303
-Node: Accents351751
-Node: Additional Latin letters354293
-Ref: Non-English characters354464
-Node: \rule355481
-Node: \today355910
-Node: Splitting the input356664
-Node: \include357428
-Node: \includeonly358019
-Node: \input358532
-Node: Front/back matter359027
-Node: Tables of contents359232
-Node: \addcontentsline360293
-Node: \addtocontents361311
-Node: Glossaries361844
-Node: Indexes362363
-Node: Letters363996
-Node: \address367674
-Node: \cc368544
-Node: \closing368962
-Node: \encl369273
-Node: \location369688
-Node: \makelabels369957
-Node: \name370958
-Node: \opening371188
-Node: \ps371528
-Node: \signature371817
-Node: \telephone372909
-Node: Terminal input/output373274
-Node: \typein373539
-Node: \typeout374124
-Node: Command line374747
-Node: Document templates375699
-Node: beamer template376106
-Node: book template376757
-Node: tugboat template377125
-Node: Concept Index379489
-Node: Command Index442260
+Node: \circle145283
+Node: \makebox (picture)145626
+Node: \framebox (picture)146332
+Node: \dashbox146822
+Node: \frame147345
+Node: \line147671
+Node: \linethickness148129
+Node: \thicklines148550
+Node: \thinlines148860
+Node: \multiput149162
+Node: \oval149529
+Node: \put150250
+Node: \shortstack150541
+Node: \vector151015
+Node: quotation and quote151329
+Node: tabbing152536
+Node: table158474
+Node: tabular159901
+Node: \multicolumn167109
+Node: \vline170994
+Node: \cline172339
+Node: \hline173023
+Node: thebibliography173706
+Node: \bibitem175320
+Node: \cite176078
+Node: \nocite176597
+Node: Using BibTeX176885
+Node: theorem178394
+Node: titlepage178780
+Node: verbatim180070
+Node: \verb180709
+Node: verse181259
+Node: Line breaking181753
+Node: \\182850
+Node: \obeycr & \restorecr183888
+Node: \newline184290
+Node: \- (hyphenation)185124
+Node: \discretionary185739
+Node: \fussy186031
+Node: \sloppy186421
+Node: \hyphenation186748
+Node: \linebreak & \nolinebreak187373
+Node: Page breaking188025
+Node: \cleardoublepage188633
+Node: \clearpage189062
+Node: \newpage189359
+Node: \enlargethispage189590
+Node: \pagebreak & \nopagebreak190117
+Node: Footnotes190811
+Node: \footnote192065
+Node: \footnotemark193861
+Node: \footnotetext195105
+Node: Footnotes in a table195595
+Node: Footnotes in section headings197452
+Node: Footnotes of footnotes198308
+Node: Multiple reference to footnotes199075
+Node: Footnote parameters199933
+Node: Definitions200683
+Node: \newcommand & \renewcommand201560
+Node: \providecommand205396
+Node: \newcounter206057
+Node: \newlength207028
+Node: \newsavebox207675
+Node: \newenvironment & \renewenvironment208286
+Node: \newtheorem212646
+Node: \newfont216135
+Node: \protect217700
+Node: \ignorespaces & \ignorespacesafterend220086
+Node: Counters222835
+Node: \alph \Alph \arabic \roman \Roman \fnsymbol224435
+Node: \usecounter226507
+Node: \value227339
+Node: \setcounter228282
+Node: \addtocounter228768
+Node: \refstepcounter229233
+Node: \stepcounter229891
+Node: \day \month \year230233
+Node: Lengths230778
+Node: Units of length232568
+Node: \setlength234062
+Node: \addtolength234466
+Node: \settodepth234784
+Node: \settoheight235075
+Node: \settowidth235372
+Node: Predefined lengths235680
+Node: Making paragraphs236195
+Node: \indent236767
+Node: \noindent237229
+Node: \parskip237738
+Node: Marginal notes237996
+Node: Math formulas239808
+Node: Subscripts & superscripts241592
+Node: Math symbols242930
+Node: Math functions268259
+Node: Math accents269202
+Node: Spacing in math mode270174
+Node: Math miscellany271641
+Node: Modes274191
+Node: \ensuremath276031
+Node: Page styles276947
+Node: \maketitle277441
+Node: \pagenumbering278511
+Node: \pagestyle279007
+Node: \thispagestyle280148
+Node: Spaces280454
+Node: \hspace281324
+Node: \hfill282279
+Node: \spacefactor282671
+Node: \(SPACE) and \@285383
+Ref: \AT285526
+Node: \frenchspacing287003
+Node: \normalsfcodes287619
+Node: \(SPACE) after control sequence287808
+Node: \thinspace288719
+Node: \/289039
+Node: \hrulefill \dotfill290221
+Node: \addvspace291214
+Node: \bigskip \medskip \smallskip292260
+Node: \vfill293152
+Node: \vspace294021
+Node: Boxes295014
+Node: \mbox295726
+Node: \fbox and \framebox296013
+Node: lrbox296817
+Node: \makebox297175
+Node: \parbox297895
+Node: \raisebox299463
+Node: \savebox300060
+Node: \sbox300475
+Node: \usebox300924
+Node: Color301185
+Node: Color package options302029
+Node: Color models303675
+Node: Commands for color305984
+Node: Define colors306399
+Node: Colored text307114
+Node: Colored boxes309489
+Node: Colored pages310928
+Node: Graphics311621
+Node: Graphics package options313740
+Node: Graphics package configuration316496
+Node: \graphicspath317287
+Node: \DeclareGraphicsExtensions320210
+Node: \DeclareGraphicsRule322003
+Node: Commands for graphics325192
+Node: \includegraphics325697
+Node: \rotatebox338723
+Node: \scalebox341518
+Node: \resizebox342570
+Node: Special insertions343762
+Node: Reserved characters344566
+Node: Upper and lower case345767
+Node: Symbols by font position347682
+Node: Text symbols348302
+Node: Accents351750
+Node: Additional Latin letters354292
+Ref: Non-English characters354463
+Node: \rule355480
+Node: \today355909
+Node: Splitting the input356663
+Node: \endinput358040
+Node: \include & \includeonly359303
+Node: \input363319
+Node: Front/back matter364029
+Node: Tables of contents364234
+Node: \addcontentsline365295
+Node: \addtocontents366313
+Node: Glossaries366846
+Node: Indexes367365
+Node: Letters368998
+Node: \address372676
+Node: \cc373546
+Node: \closing373964
+Node: \encl374275
+Node: \location374690
+Node: \makelabels374959
+Node: \name375960
+Node: \opening376190
+Node: \ps376530
+Node: \signature376819
+Node: \telephone377911
+Node: Terminal input/output378276
+Node: \typein378541
+Node: \typeout379126
+Node: Command line379749
+Node: Document templates380701
+Node: beamer template381108
+Node: book template381759
+Node: tugboat template382127
+Node: Concept Index384491
+Node: Command Index447328
End Tag Table
Modified: trunk/latex2e.pdf
===================================================================
(Binary files differ)
Modified: trunk/latex2e.texi
===================================================================
--- trunk/latex2e.texi 2018-05-04 17:54:54 UTC (rev 619)
+++ trunk/latex2e.texi 2018-05-17 21:43:30 UTC (rev 620)
@@ -4556,8 +4556,8 @@
lower left corner of the box.
@PkgIndex{picture}
-The @code{picture} package redefine the @code{picture} environment so
-that everywhere a number is used in a @var{picture commands} to specify
+The @code{picture} package redefines the @code{picture} environment so
+that everywhere a number is used in @var{picture commands} to specify
a coordinate, one can use alternatively a length. Be aware however that
this will prevent scaling those lengths by changing @code{\unitlength}.
@@ -12161,70 +12161,223 @@
@cindex splitting the input file
@cindex input file
-A large document requires a lot of input. Rather than putting the whole
-input in a single large file, it's more efficient to split it into
-several smaller ones. Regardless of how many separate files you use,
-there is one that is the
+ at LaTeX{} lets you split a large document into several smaller ones.
+This can simplify editing or allow multiple authors to work on the
+document. It can also speed processing.
+
+Regardless of how many separate files you use, there is always one
@cindex root file
@cindex file, root
- at dfn{root file}; it is the one whose name you type
-when you run @LaTeX{}.
+ at dfn{root file}, on which @LaTeX{} compilation starts.
+This shows such a file with three included files.
- at xref{filecontents}, for an environment that allows bundling an
-external file to be created with the main document.
+ at example
+\documentclass@{book@}
+\includeonly@{ % comment out lines here to skip compiling those parts
+ pref,
+ chap1,
+ chap2
+ @}
+\begin@{document@}
+\frontmatter
+\include@{pref@}
+\mainmatter
+\include@{chap1@}
+\include@{chap2@}
+\end@{document@}
+ at end example
+This will bring in material from @file{pref.tex}, @file{chap1.tex}, and
+ at file{chap2.tex}. If you compile this file, then comment out the lines
+inside @code{\includeonly@{...@}} containing @code{pref} and
+ at code{chap2} and compile again, then @LaTeX{} will only process the
+material in the first chapter but will retain the page numbers and all
+of the cross reference information from the preface and second chapter.
+
+ at c @xref{filecontents}, for an environment that allows bundling an
+ at c external file to be created with the main document.
+
@menu
-* \include:: Conditionally include a file.
-* \includeonly:: Determine which files are included.
-* \input:: Unconditionally include a file.
+* \endinput:: Stop including material from a file.
+* \include & \includeonly:: Conditionally include files.
+* \input:: Unconditionally include a file.
@end menu
- at node \include
- at section @code{\include}
- at findex \include
+ at node \endinput
+ at section @code{\endinput}
+ at findex \endinput
+
Synopsis:
@example
-\include@{@var{file}@}
+\endinput
@end example
-If no @code{\includeonly} command is present, the @code{\include}
-command executes @code{\clearpage} to start a new page
-(@pxref{\clearpage}), then reads @var{file}, then does another
- at code{\clearpage}.
+When you @code{\include@{file@}}, inside @file{filename.tex} the
+material after @code{\endinput} will not be included. This command is
+optional; if @file{filename.tex} has no @code{\endinput} then @LaTeX{}
+will read all of the file.
-Given an @code{\includeonly} command, the @code{\include} actions are
-only run if @var{file} is listed as an argument to
- at code{\includeonly}. See @ref{\includeonly}.
+For example, suppose that a document's root file has
+ at code{\input@{chap1@}} and this is @file{chap1.tex}.
- at cindex nested @code{\include}, not allowed
-The @code{\include} command may not appear in the preamble or in a file
-read by another @code{\include} command.
+ at example
+\chapter@{One@}
+This material will appear in the document.
+\endinput
+This will not appear.
+ at end example
+This can be useful for putting documentation or comments at the end of a
+file, or for avoiding junk characters that can be added during mailing.
+It is also useful for debugging: one strategy to localize errors is to
+put @code{\endinput} halfway through the included file and see if the
+error disappears. Now, knowing which half contains the error, moving
+ at code{\endinput} to halfway through that area further narrows down the
+location. This process rapidly finds the offending line.
- at node \includeonly
- at section @code{\includeonly}
+After reading @code{\endinput}, @LaTeX{} continues to read to the end of
+the line, so something can follow this command and be read nonetheless.
+This allows you, for instance, to close an @code{\if...} with a
+ at code{\fi}.
+
+ at node \include & \includeonly
+ at section @code{\include} & @code{\includeonly}
+
+ at findex \include
@findex \includeonly
Synopsis:
@example
-\includeonly@{@var{file1}, at var{file2},...@}
+\includeonly@{ % in document preamble
+ ...
+ @var{filename},
+ ...
+ @}
+ ...
+\include@{@var{filename}@} % in document body
@end example
+Bring material from the external file @file{@var{filename}.tex} into a
+ at LaTeX{} document.
+
+The @code{\include} command does three things: it executes
+ at code{\clearpage} (@pxref{\clearpage}), then it inputs the material from
+ at file{filename.tex} into the document, and then it does another
+ at code{\clearpage}. This command can only appear in the document body.
The @code{\includeonly} command controls which files will be read by
-subsequent @code{\include} commands. The list of filenames is
-comma-separated. Each element @var{file1}, @var{file2}, @dots{} must
-exactly match a filename specified in a @code{\include} command for the
-selection to be effective.
+ at LaTeX{} under subsequent @code{\include} commands. Its list of
+filenames is comma-separated, and it can only appear in the preamble.
-This command can only appear in the preamble.
+This example root document, @file{constitution.tex}, brings in
+three files, @file{preamble.tex}, @file{articles.tex}, and
+ at file{amendments.tex}.
+ at example
+\documentclass@{book@}
+\includeonly@{
+ preamble,
+ articles,
+ amendments
+ @}
+\begin@{document@}
+\include@{preamble@}
+\include@{articles@}
+\include@{amendments@}
+\end@{document@}
+ at end example
+The file @file{preamble.tex} contains no special code; you have just
+excerpted the chapter from @file{consitution.tex} and put it in a
+separate file just for editing convenience.
+
+ at example
+\chapter@{Preamble@}
+We the People of the United States, in Order to form a more perfect Union, @dots{}
+ at end example
+
+Running @LaTeX{} on @file{constitution.tex} makes the material from the
+three files appear in the document but also generates the auxillary
+files @file{preamble.aux}, @file{articles.aux}, and
+ at file{amendments.tex}. These contain information such as page numbers
+and cross-references (@pxref{Cross references}). If you now comment out
+ at code{\includeonly}'s lines with @code{preamble} and @code{amendments}
+and run @LaTeX{} again then the resulting document shows only the
+material from @file{articles.tex}, not the material from
+ at file{preamble.tex} or @file{amendments.tex}. Nonetheless, all of the
+auxillary information from the omitted files, including the starting
+page number of this chapter, is still there.
+
+If the document preamble does not have @code{\includeonly} then
+ at LaTeX{} will include all the files you call for with @code{\include}
+commands.
+
+The @code{\include} command makess a new page. To avoid that, see
+ at ref{\input} (which, however, does not retain the auxillary
+information).
+
+File names can involve paths.
+
+ at example
+\documentclass@{book@}
+\includeonly@{
+ chapters/chap1,
+ @}
+\begin@{document@}
+\include@{chapters/chap1@}
+\end@{document@}
+ at end example
+
+To make your document portable across distributions and platforms you
+should avoid spaces. The tradition is to instead use underscores in the
+file names. That said, for the filename @samp{@file{amo amas amat}},
+this works under TeX Live on Linux
+
+ at example
+\documentclass@{book@}
+\includeonly@{
+ "amo\space amas\space amat"
+ @}
+\begin@{document@}
+\include@{"amo\space amas\space amat"@}
+\end@{document@}
+ at end example
+
+and this works under MiKTeX on Windows.
+
+ at example
+\documentclass@{book@}
+\includeonly@{
+ @{"amo amas amat"@}
+ @}
+\begin@{document@}
+\include@{@{"amo amas amat"@}@}
+\end@{document@}
+ at end example
+
+ at cindex nested @code{\include}, not allowed
+You cannot use @code{\include} inside a file that is being included or
+you get @samp{! LaTeX Error: \include cannot be nested.} The
+ at code{\include} command cannot appear in the document preamble; you will
+get @samp{! LaTeX Error: Missing \begin@{document@}.}.
+
+If a file that you @code{\include} does not exist, for instance if you
+ at code{\include@{athiesm@}} but you meant @code{\include@{atheism@}},
+then @LaTeX{} does not give you an error but will warn you @samp{No file
+athiesm.tex.} (It will also create @file{athiesm.aux}.)
+
+If you @code{\include} the root file in itself then you first get
+ at samp{! LaTeX Error: Can be used only in preamble.} Later runs get
+ at samp{! TeX capacity exceeded, sorry [text input levels=15]}. To fix
+this, you must remove the inclusion @code{\include@{root@}} but also
+delete the file @file{@var{root}.aux} and rerun @LaTeX{}.
+
+
@node \input
@section @code{\input}
@@ -12236,14 +12389,17 @@
\input@{@var{file}@}
@end example
-The @code{\input} command causes the specified @var{file} to be read
-and processed, as if its contents had been inserted in the current
-file at that point.
+Read @file{@var{file}.tex} as if its contents were inserted in the
+current file. For a more sophisticated inclusion mechanism see
+ at ref{\include & \includeonly}.
-If @var{file} does not end in @samp{.tex} (e.g., @samp{foo} or
- at samp{foo.bar}), it is first tried with that extension (@samp{foo.tex}
-or @samp{foo.bar.tex}). If that is not found, the original @var{file}
-is tried (@samp{foo} or @samp{foo.bar}).
+If @var{file} end with @samp{.tex} then @LaTeX{} looks for the filename
+as it is. If @var{file} does not end in @samp{.tex} then @LaTeX{} first
+tries the filename with that extension, so @code{\include@{macros@}}
+will cause @LaTeX{} to first look for @file{macros.tex}; this is the
+usual case. If there is no such file then the system tries the original
+file name, here @samp{@file{macros}}, without an extension. (This may
+vary by distribution.)
@node Front/back matter
More information about the latexrefman-commits
mailing list