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
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This document is an unofficial reference manual for LaTeX, a
document preparation system, version of October 2018.
This manual was originally translated from LATEX.HLP v1.0a in the
VMS Help Library. The pre-translation version was written by
George D. Greenwade of Sam Houston State University. The
LaTeX 2.09 version was written by Stephen Gilmore. The
LaTeX2e version was adapted from this by Torsten Martinsen. Karl
Berry made further updates and additions, and gratefully acknowledges
using Hypertext Help with LaTeX, by Sheldon Green, and
LaTeX Command Summary (for LaTeX 2.09) by
L. Botway and C. Biemesderfer (published by the TeX Users
Group as TeXniques number 10), as reference material. We also
gratefully acknowledge additional material appearing in
latex2e-reference by Martin Herbert Dietze. (From these references no
text was directly copied.)
Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013,
2014, 2015, 2016, 2017, 2018 Karl Berry.
Copyright 1988, 1994, 2007 Stephen Gilmore.
Copyright 1994, 1995, 1996 Torsten Martinsen.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions. -->
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Splitting the input (LaTeX2e unofficial reference manual (October 2018))</title>
<meta name="description" content="Splitting the input (LaTeX2e unofficial reference manual (October 2018))">
<meta name="keywords" content="Splitting the input (LaTeX2e unofficial reference manual (October 2018))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="latex2e_0.html#Top" rel="start" title="Top">
<link href="latex2e_30.html#Index" rel="index" title="Index">
<link href="latex2e_0.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="latex2e_0.html#Top" rel="up" title="Top">
<link href="latex2e_25.html#Front_002fback-matter" rel="next" title="Front/back matter">
<link href="latex2e_23.html#g_t_005ctoday" rel="prev" title="\today">
<style type="text/css">
<!--
body {margin: 1em; margin-top: 0px; padding-top: 1px}
a.anchor {float: right}
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body id="top" lang="en">
<a name="Splitting-the-input" class="anchor"></a>
<a name="Splitting-the-input-1" class="anchor"></a>
<h2 class="chapter">Splitting the input</h2>
<a name="index-splitting-the-input-file" class="anchor"></a>
<a name="index-input-file" class="anchor"></a>
<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" class="anchor"></a>
<a name="index-file_002c-root" class="anchor"></a>
<em>root file</em>, on which LaTeX compilation starts. This shows such
a file with five included files.
</p>
<div class="example">
<pre class="example">\documentclass{book}
\includeonly{ % comment out lines below to omit compiling
pref,
chap1,
chap2,
append,
bib
}
\begin{document}
\frontmatter
\include{pref}
\mainmatter
\include{chap1}
\include{chap2}
\appendix
\include{append}
\backmatter
\include{bib}
\end{document}
</pre></div>
<p>This will bring in material from <samp>pref.tex</samp>, <samp>chap1.tex</samp>,
<samp>chap2.tex</samp>, <samp>append.tex</samp>, and <samp>bib.tex</samp>. If you compile
this file, and then comment out all of the lines inside
<code>\includeonly{...}</code> except for <code>chap1,</code> and compile again,
then LaTeX will only process the material in the first chapter.
Thus, your output will appear more quickly and be shorter to print.
However, the advantage of the <code>\includeonly</code> command is that
LaTeX will retain the page numbers and all of the cross reference
information from the other parts of the document so these will appear in
your output correctly.
</p>
<p>See <a href="latex2e_29.html#Larger-book-template">Larger book template</a> for another example of <code>\includeonly</code>.
</p>
<hr>
<a name="g_t_005cendinput" class="anchor"></a>
<a name="g_t_005cendinput-1" class="anchor"></a>
<h3 class="section"><code>\endinput</code></h3>
<a name="index-_005cendinput" class="anchor"></a>
<p>Synopsis:
</p>
<div class="example">
<pre class="example">\endinput
</pre></div>
<p>When you <code>\include{filename}</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>For example, suppose that a document’s root file has
<code>\input{chap1}</code> and this is <samp>chap1.tex</samp>.
</p>
<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_005cinclude-_0026-_005cincludeonly" class="anchor"></a>
<a name="g_t_005cinclude-_0026-_005cincludeonly-1" class="anchor"></a>
<h3 class="section"><code>\include</code> & <code>\includeonly</code></h3>
<a name="index-_005cinclude" class="anchor"></a>
<a name="index-_005cincludeonly" class="anchor"></a>
<p>Synopsis:
</p>
<div class="example">
<pre class="example">\includeonly{ % in document preamble
...
<var>filename</var>,
...
}
...
\include{<var>filename</var>} % in document body
</pre></div>
<p>Bring material from the external file <samp><var>filename</var>.tex</samp> into a
LaTeX document.
</p>
<p>The <code>\include</code> command does three things: it executes
<code>\clearpage</code> (see <a href="latex2e_10.html#g_t_005cclearpage-_0026-_005ccleardoublepage">\clearpage & \cleardoublepage</a>), then it
inputs the material from <samp><var>filename</var>.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 auxiliary
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="latex2e_7.html#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
auxiliary information from the omitted files is still there, including
the starting page number of the chapter.
</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 makes a new page. To avoid that, see
<a href="#g_t_005cinput">\input</a> (which, however, does not retain the auxiliary
information).
</p>
<p>See <a href="latex2e_29.html#Larger-book-template">Larger book template</a> for another example using <code>\include</code>
and <code>\includeonly</code>. That example also uses <code>\input</code> for some
material that will not necessarily start on a new page.
</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 in the file names. The tradition is to instead use
dashes or underscores. Nevertheless, for the name ‘<samp>amo amas amat</samp>’,
this works under TeX Live on GNU/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" class="anchor"></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" class="anchor"></a>
<a name="g_t_005cinput-1" class="anchor"></a>
<h3 class="section"><code>\input</code></h3>
<a name="index-_005cinput" class="anchor"></a>
<p>Synopsis:
</p>
<div class="example">
<pre class="example">\input{<var>filename</var>}
</pre></div>
<p>LaTeX processes the file 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>filename</var> does not end in ‘<samp>.tex</samp>’ then LaTeX first tries
the filename with that extension; this is the usual case. If
<var>filename</var> ends with ‘<samp>.tex</samp>’ then LaTeX looks for the
filename as it is.
</p>
<p>For example, this
</p>
<div class="example">
<pre class="example">\input{macros}
</pre></div>
<p>will cause LaTeX to first look for <samp>macros.tex</samp>. If it finds
that file then it processes its contents as thought they had been
copy-pasted in. If there is no file of the name <samp>macros.tex</samp> then
LaTeX tries the name <samp>macros</samp>, without an extension. (This may
vary by distribution.)
</p>
<p>To make your document portable across distributions and platforms you
should avoid spaces in the file names. The tradition is to instead use
dashes or underscores. Nevertheless, for the name ‘<samp>amo amas amat</samp>’,
this works under TeX Live on GNU/Linux:
</p>
<div class="example">
<pre class="example">\input{"amo\space amas\space amat"}
</pre></div>
<p>and this works under MiKTeX on Windows:
</p>
<div class="example">
<pre class="example">\input{{"amo amas amat"}}
</pre></div>
</body>
</html>
|
