The includex LaTeX package

extra ways to include files

Matt Swift <[email protected]>

Version: 0.6a Date: 1999/02/23
Documentation revision: 1999/02/23

Abstract
Includex allows you to include just the contents of one source file into an-
other, ignoring the text outside the \begin{document} . . . \end{document}
in the included file.
This package is useful but may have problems and is unsupported.
See also the newclude package.

Contents

I Discussion 2
1 Including Files 2

II Implementation 3
2 Version control 3

3 Requirements 3

4 Disabling things 4

5 New things 4

1
 Part I
Discussion
1 Including Files
\include* \include was always pretty useless to me because it did a \clearpage before and
after the \input. The macro \include* is defined below to be like \include but
without the \clearpage s.
The other thing we do is define a command \includedoc, which includes a
file which is allowed to have its own \documentclass and \begin{document} and
\end{document} and \usepackage commands.
This opens up a whole new world of truly modular LATEX files. There is even
nothing special about extracting the document environment, we can extract any
environment, or perhaps even other things.
There are some problems, however. Maybe the \usepackage is necessary,
maybe it would conflict. Same with other commands like the \newcommand family.
It is simply not (yet) an issue in LATEX design to consider the implications of
parent files. The problems are not insurmountable. We can begin by working
with a convention, and ultimately maybe make some changes in certain macros. I
will be getting to all this. I admit I have not looked carefully to see whether the
design specifications of LATEX3 address these important issues.
The macros here will be useful in many circumstances, when the included files
are themselves simple.
\includedoc There are now two main commands, \includedoc and \includedocskip, each
\includedoc* with a * version analogous to the new include*. Each take a filename as an
\includedocskip argument just like \include.
\includedocskip* \includedoc {filename} reads everything in the file except for \documentclass,
\usepackage, \begin{document}, \end{document} (and whatever follows it).
\includedocskip {filename} does the same except it also skips everything
between \documentclass and \begin{document}.
\disable At present there is a makeshift way to ignore additional commands when using
\includedoc and \includedocskip. If you want to cause \foo which takes no
arguments to be disabled, say \disable{\let\foo\relax}. If \foo takes one
mandatory argument, say \let\foo\Gobble instead. If \foo takes one optional
and one mandatory, say \let\foo\GobbleOM. If \foo takes two mandatory argu-
ments, say \let\foo\GobbleMM. For other permutations of arguments, you can
extrapolate from the macros defined below.

2
 Part II
Implementation
2 Version control
\fileinfo These definitions must be the first ones in the file.
\DoXUsepackagE 1 \def\fileinfo{extra ways to include files}
\HaveECitationS 2 \def\DoXPackageS {}
\fileversion 3 \def\fileversion{v0.6a}
\filedate 4 \def\filedate{1999/02/23}
\docdate 5 \def\docdate{1999/02/23}

\PPOptArg 6 \edef\PPOptArg {%
7 \filedate\space \fileversion\space \fileinfo
8}

If we’re loading this file from a \ProcessDTXFile command (see the compsci
package), then \JusTLoaDInformatioN will be defined; othewise we assume it is
not (that’s why the FunkY NamE).
If we’re loading from \ProcessDTXFile, we want to load the packages listed in
\DoXPackageS (needed to typeset the documentation for this file) and then bail
out. Otherwise, we’re using this file in a normal way as a package, so do nothing.
\DoXPackageS, if there are any, are declared in the dtx file, and, if you’re reading
the typeset documentation of this package, would appear just above. (It’s OK to
call \usepackage with an empty argument or \relax, by the way.)
9 \makeatletter% A special comment to help create bst files. Don’t change!
10 \@ifundefined{JusTLoaDInformatioN} {%
11 }{% ELSE (we know the compsci package is already loaded, too)
12 \UndefineCS\JusTLoaDInformatioN
13 \SaveDoXVarS
14 \eExpand\csname DoXPackageS\endcsname\In {%use \csname in case it’s undefined
15 \usepackage{#1}%
16 }%
17 \RestoreDoXVarS
18 \makeatother
19 \endinput
20 }% A special comment to help create bst files. Don’t change!

Now we check for LATEX2e and declare the LaTeX package.

21 \NeedsTeXFormat{LaTeX2e}
22 \ProvidesPackage{includex}[\PPOptArg]

3 Requirements
Now we declare the package, check for LATEX2e, and load the other packages
needed.
23 \NeedsTeXFormat{LaTeX2e}

3
 24 \ProvidesPackage{includex}
25 \RequirePackage{moredefs}

4 Disabling things
\disable This allows the disabling hacks.
26 \ReserveCS\DisableMonster % This line is elsewhere for main package
27 \newcommand\disable[1] {%
28 \g@addto@macro\DisableMonster{#1}%
29 }

5 New things
\sc@saved@include This is a simple redefinition of \include without the \clearpage commands.
\include Nothing tricky going on.
\sc@include 30 \newlet\sc@saved@include\include
\sc@@include 31 \renewcommand\include {%
32 \@ifstar
33 \sc@include
34 \sc@saved@include
35 }
36 \newcommand\sc@include {%
37 \relax
38 \ifnum\@auxout=\@partaux
39 \@latex@error{\string\include\space cannot be nested}\@eha
40 \else
41 \expandafter\sc@@include
42 \fi
43 }
44 \newcommand\sc@@include[1] {%
45 \if@filesw
46 \immediate\write\@mainaux{\string\@input{#1.aux}}%
47 \fi
48 \@tempswatrue
49 \if@partsw
50 \@tempswafalse
51 \edef\@tempb{#1}%
52 \@for \@tempa:=\@partlist
53 \do{\ifx\@tempa
54 \@tempb
55 \@tempswatrue
56 \fi}%
57 \fi
58 \if@tempswa
59 \let\@auxout\@partaux
60 \if@filesw
61 \immediate\openout\@partaux #1.aux%

4
 62 \immediate\write\@partaux{\relax}%
63 \fi
64 \@input@{#1.tex}%
65 \@writeckpt{#1}%
66 \if@filesw
67 % NOTE: Robin took out the \immediate here.
68 % \immediate\closeout\@partaux
69 \closeout\@partaux
70 \fi
71 \else
72 \@nameuse{cp@#1}%
73 \fi
74 \let\@auxout\@mainaux
75 }

Now we start dealing with the much more tricky extraction of the document
environment.
We start with considering how to quit inputting a file. The idea is to make
the \end{document} command of the included file call \endinput. But there is a
hitch that characters on the line after the \end{document} get inserted when you
don’t want them to. To beat that limitation, we have to do some work.

\sc@radical@shutdown We will add a bunch of commands to this macro, with the idea of \catcode ing
everything and its brother to a comment. This would be a brute force method!
76 \ReserveCS\sc@radical@shutdown
First log a message that we’re about to do some crazy things. In case something
ever goes wrong, this might help.
77 \addto@macro\sc@radical@shutdown {%
78 \PackageInfo{includex}{\protect\sc@radical@shutdown\space beginning}%
79 }

Now we start adding \catcode commands. These first two should be redundant;
but just in case someone changed things. . . .
80 \addto@macro\sc@radical@shutdown{\catcode‘\%=14} % 14 = comment
81 \addto@macro\sc@radical@shutdown{\catcode‘\^=7} % 7 = superscript

\sc@disable@char Next, we define a command we weill use in a loop in a moment.

82 \newcommand\sc@disable@char[1] {%
83 \addto@macro\sc@radical@shutdown
84 {\catcode‘#1=14}} % 14 = comment

The following list contains every keyboard char except these three, which are
treated specially: %#. The first is already a comment, and we handle the second
in a moment. Each character in the following list is \catcode d to a comment:
85 \@tfor\sc@t@a:=abcdefghijklmnopqrstuvwxyz%
86 ABCDEFGHIJKLMNOPQRSTUVWXYZ%
87 ~!@$&*()_+-=[]|/?.,<>%
88 1234567890%

5
 89 ‘’";:%
90 \^\\\{\}\ % this is really the chars "^\{}" and space
91 \do {\expandafter\sc@disable@char\sc@t@a}
We add # separately, because it’s tricky or impossible to put it into the list we
just used.
92 \sc@disable@char\#
We end the macro with \endinput. This has to come after all the previous,
otherwise, TEX goes ahead and reads to the end of the line immediately, with
regular catcodes. This is a good theory, I’m not sure it’s necessary.
93 \addto@macro\sc@radical@shutdown{\endinput}

\sc@radical@shutdown@aftergroup We need to use \sc@radical@shutdown this way.

94 \newcommand\sc@radical@shutdown@aftergroup {%
95 \aftergroup\sc@radical@shutdown
96 }

\sc@begindoc@toks These are for \AtBeginIncludedDocument and \AtEndIncludedDocument.

\sc@enddoc@toks 97 \newtoks\sc@begindoc@toks
98 \sc@begindoc@toks{}
99 \newtoks\sc@enddoc@toks
100 \sc@enddoc@toks{}

\AtBeginIncludedDocument The analogue of \AtBeginDocument.

101 \newcommand\AtBeginIncludedDocument[1] {%
102 \sc@begindoc@toks\expandafter{\the\sc@begindoc@toks#1}%
103 }

\AtEndIncludedDocument The analogue of \AtEndDocument

104 \newcommand\AtEndIncludedDocument[1] {%
105 \sc@enddoc@toks\expandafter{\the\sc@enddoc@toks#1}%
106 }

\includedoc Now we start from the other end, defining the user command.
\includedoc* 107 \newcommand\includedoc {%
108 % Robin’s new:
109 \@ifstar {%
110 \def\sc@includebit@cmd{\include*}\sc@includebit
111 }{% ELSE
112 \let\sc@includebit@cmd\include\sc@includebit
113 }%
114 }
115
116 % My old:
117 % {\sc@includebit}
118 % {\clearpage
119 % \sc@includebit[\clearpage]}}

6
 \sc@includebit The commented-out code is for some eventual extensions.
Interface is sc@includebit[postlude]{file} (where [postlude] is com-
mand(s) to be executed after the inclusion is complete); it is assumed that
sc@includebit@cmd is either \include or include*
120 \newcounter{sc@count}
121 \newcounter{bit}
122 \newcommand\sc@includebit [2] [] {%
123 \setcounter{sc@count}{\thebit}%
124 \begingroup
125 \DisableMonster
126 \let\usepackage\GobbleOM
127 % Robin’s new:
128 \def\enddocument {%
129 \makeatletter
130 \the\sc@enddoc@toks
131 \sc@radical@shutdown@aftergroup
132 }
133 % My old:
134 % \let\enddocument\sc@radical@shutdown@aftergroup
135 \let\documentclass\GobbleOM
136 \let\documentstyle\GobbleOM % why worry about branching if 2.09..
137 \def\document {%
138 \the\sc@begindoc@toks
139 }%
140 \def\IncludedJobname {#2}%
141 \sc@includebit@cmd{#2}%
142 \endgroup
143 \par
144 #1
145 }

\includedocskip Now we make a similar command that entirely skips the preamble, whereas
\includedocskip* \includedoc only skipped those commands that we specifically disabled. Ob-
viously this whole business of the preamble needs to be radically reconceived if
convenient modularity of documents is to be had. At the moment, no distinction is
made between things like \newcommand and \usepackage that should be exported
to a parent file, and those things that should not.
146 \newcommand\includedocskip {%
147 \@ifstar {%
148 \sc@includebitskip
149 }{% ELSE
150 \clearpage
151 \sc@includebitskip[\clearpage]%
152 }%
153 }

I tried combining \sc@includebitskip and \sc@includebit but something

changed when I used a conditional to do this. I’m sure the problem could be
figured out and the two combined.

7
\sc@includebitskip We begin skipping with the \documentclass or \documentstyle command, and
stop with the \begin{document} command. With some hacking to the new
verbatim environment, this could be done. I haven’t done this yet, so this is
implemented by stuffing everything into a macro argument. I can’t think of a
\begin occurring between \documentclass the \begin document, but that will
screw things up if it does.
The commented lines here are once again for a future extension.
154 \newcommand\sc@includebitskip [2] [] {%
155 \setcounter{sc@count}{\thebit}%
156 \begingroup
157 \DisableMonster
158 \let\enddocument\sc@radical@shutdown@aftergroup
159 \long\def\documentclass ##1\begin{%
160 \begingroup
161 \def\@currenvir{document}%
162 \GobbleM
163 }% "{document}" is still to be read.
164 \let\documentstyle\documentclass
165 \include*{#2}%
166 \endgroup
167 \par
168 #1\relax
169 }

8
Index
Numbers written in italic refer to the page where the corresponding entry is de-
scribed; numbers underlined refer to the code line of the definition; numbers in
roman refer to the code lines where the entry is used.

Symbols C \GobbleOM . 126, 135, 136

\# . . . . . . . . . . . . . . 92 \catcode . . . . 80, 81, 84
\% . . . . . . . . . . . . . . 80 \clearpage . . . . . . . H
\@auxout . . . . 38, 59, 74 . 118, 119, 150, 151 \HaveECitationS . . . . 1
\@currenvir . . . . . . . 161 \closeout . . . . . . 68, 69
\csname . . . . . . . . . . 14 I
\@eha . . . . . . . . . . . . 39
\if@filesw . . 45, 60, 66
\@for . . . . . . . . . . . . 52
D \if@partsw . . . . . . . 49
\@ifstar . . 32, 109, 147
\def . . 1–5, 110, 128, \if@tempswa . . . . . . . 58
\@ifundefined . . . . . 10
137, 140, 159, 161 \ifnum . . . . . . . . . . . 38
\@input . . . . . . . . . . 46
\disable . . . . . . . . 2, 26 \ifx . . . . . . . . . . . . . 53
\@input@ . . . . . . . . . 64 \immediate . . . . . . .
\@latex@error . . . . . 39 \DisableMonster . . .
. . 26, 28, 125, 157 . 46, 61, 62, 67, 68
\@mainaux . . . . . . 46, 74 \In . . . . . . . . . . . . . 14
\@nameuse . . . . . . . . 72 \do . . . . . . . . . . . 53, 91
\docdate . . . . . . . . . . 1 \include 30, 110, 112, 165
\@partaux . . . . . 38, \include* . . . . . . . . . 2
59, 61, 62, 68, 69 \document . . . . . . . . 137
\documentclass . . . . \IncludedJobname . . 140
\@partlist . . . . . . . 52 \includedoc . . . . . 2, 107
. . . . 135, 159, 164
\@tempa . . . . . . . . 52, 53 \includedoc* . . . . 2, 107
\documentstyle 136, 164
\@tempb . . . . . . . . 51, 54 \includedocskip . 2, 146
\DoXPackageS . . . . . . . 2
\@tempswafalse . . . . 50
\DoXUsepackagE . . . . . 1 \includedocskip* 2, 146
\@tempswatrue . . . 48, 55
\@tfor . . . . . . . . . . . 85 E J
\@writeckpt . . . . . . . 65 \JusTLoaDInformatioN 12
\edef . . . . . . . . . . . 6, 51
\\ . . . . . . . . . . . . . . 90 \eExpand . . . . . . . . . 14
\{ . . . . . . . . . . . . . . 90 L
\else . . . . . . . . . . 40, 71 \let . 59, 74, 112, 126,
\} . . . . . . . . . . . . . . 90 \endcsname . . . . . . . 14
\^ . . . . . . . . . . . . 81, 90 134–136, 158, 164
\enddocument . . . . . . \long . . . . . . . . . . . . 159
. . . . 128, 134, 158
\endgroup . . . . 142, 166 M
\ . . . . . . . . . . . . . . 90 \endinput . . . . . . 19, 93 \makeatletter . . . 9, 129
\expandafter . . . . . . \makeatother . . . . . . 18
A . . 41, 91, 102, 105
\addto@macro . . . . . . N
. 77, 80, 81, 83, 93 F \NeedsTeXFormat . 21, 23
\aftergroup . . . . . . . 95 \fi . . . . . . . . 42, 47, \newcommand 27, 36, 44,
\AtBeginIncludedDocument 56, 57, 63, 70, 73 82, 94, 101, 104,
. . . . . . . . . . . 101 \filedate . . ....... 1 107, 122, 146, 154
\AtEndIncludedDocument \fileinfo . . ....... 1 \newcounter . . . 120, 121
. . . . . . . . . . . 104 \fileversion ....... 1 \newlet . . . . . . . . . . 30
\newtoks . . . . . . . 97, 99
B G
\begin . . . . . . . . . . . 159 \g@addto@macro . . . . 28 O
\begingroup 124, 156, 160 \GobbleM . . . . . . . . . 162 \openout . . . . . . . . . 61

9
 P \sc@begindoc@toks . . 94, 131, 134, 158
\PackageInfo . . . . . . 78 . . . . . 97, 102, 138 \sc@saved@include . 30
\par . . . . . . . . . 143, 167 \sc@disable@char . . \sc@t@a . . . . . . . . 85, 91
\PPOptArg . . . . . . . 1, 22 . . . . . . . 82, 91, 92 \setcounter . . . 123, 155
\protect . . . . . . . . . 78 \sc@enddoc@toks . . . \space . . . . . . . 7, 39, 78
\ProvidesPackage 22, 24 . . . . . 97, 105, 130 \string . . . . . . . . 39, 46
\sc@include . . . . . . . 30
R T
\sc@includebit 110,
\relax . . . . . 37, 62, 168 \the . . 102, 105, 130, 138
112, 117, 119, 120
\renewcommand . . . . . 31 \thebit . . . . . . 123, 155
\sc@includebit@cmd .
\RequirePackage . . . 25
\ReserveCS . . . . . 26, 76 . . . . 110, 112, 141 U
\RestoreDoXVarS . . . 17 \sc@includebitskip . \UndefineCS . . . . . . . 12
. . . . 148, 151, 154 \usepackage . . . . 15, 126
S \sc@radical@shutdown
\SaveDoXVarS . . . . . . 13 . . . . . . . . . 76, 95 W
\sc@@include . . . . . . 30 \sc@radical@shutdown@aftergroup \write . . . . . . . . . 46, 62

10