The includex LaTeX package

extra ways to include files

       Matt Swift <swift@alum.mit.edu>

and Robin Fairbairns Version: 0.6 Date: 1999/02/23

Documentation revision: 1999/02/23

Abstract

Includex allows you to include just the contents of one source file into another, 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

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 L^{A}TEX 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 L^{A}TEX 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 L^{A}TEX3 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*
\includedocskip
\includedocskip*

with a * version analogous to the new include*. Each take a filename as an argument just like \include.

\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 arguments, say \let\foo\GobbleMM. For other permutations of arguments, you can extrapolate from the macros defined below.

Part II

Implementation

2 Version control

\fileinfo \DoXUsepackagE \HaveECitationS \fileversion \filedate \docdate \PPOptArg These definitions must be the first ones in the file.
 1 \def\fileinfo{extra ways to include files}
 2 \def\DoXPackageS {}
 3 \def\fileversion{v0.6}
 4 \def\filedate{1999/02/23}
 5 % A trick to include(x!) Robin:
 6 \let\MDSavedauthor\author
 7 \renewcommand\author [1] {%
 8 \MDSavedauthor{#1\\and Robin Fairbairns}%
 9 }
10 \def\docdate{1999/02/23}
11 \edef\PPOptArg {%
12 \filedate\space \fileversion\space \fileinfo

13 }

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.)

14 \makeatletter% A special comment to help create bst files.  Don't change!
15 \@ifundefined{JusTLoaDInformatioN} {%
16 }{% ELSE (we know the compsci package is already loaded, too)
17 \UndefineCS\JusTLoaDInformatioN
18 \SaveDoXVarS
19 \eExpand\csname DoXPackageS\endcsname\In {%use \csname in case it's undefined
20  \usepackage{#1}%
21 }%
22 \RestoreDoXVarS
23 \makeatother
24 \endinput
25 }% A special comment to help create bst files.  Don't change!

Now we check for L^{A}TEX2e and declare the LaTeX package.

26 \NeedsTeXFormat{LaTeX2e}
27 \ProvidesPackage{includex}[\PPOptArg]

3 Requirements

Now we declare the package, check for L^{A}TEX2e, and load the other packages needed.

28 \NeedsTeXFormat{LaTeX2e}
29 \ProvidesPackage{includex}
30 \RequirePackage{moredefs}

4 Disabling things

\disable This allows the disabling hacks.

31 \ReserveCS\DisableMonster  % This line is elsewhere for main package
32 \newcommand\disable[1] {%
33 \g@addto@macro\DisableMonster{#1}%

34 }

5 New things

\sc@saved@include \include \sc@include \sc@@include This is a simple redefinition of \include without the \clearpage commands.

Nothing tricky going on.

35 \newlet\sc@saved@include\include
36 \renewcommand\include {%
37 \@ifstar
38  \sc@include
39  \sc@saved@include

40 }

41 \newcommand\sc@include {%
42 \relax
43 \ifnum\@auxout=\@partaux
44  \@latex@error{\string\include\space cannot be nested}\@eha
45 \else
46  \expandafter\sc@@include
47 \fi

48 }

49 \newcommand\sc@@include[1] {%
50 \if@filesw
51  \immediate\write\@mainaux{\string\@input{#1.aux}}%
52 \fi
53 \@tempswatrue
54 \if@partsw
55  \@tempswafalse
56  \edef\@tempb{#1}%
57  \@for \@tempa:=\@partlist
58  \do{\ifx\@tempa
59  \@tempb
60  \@tempswatrue
61  \fi}%
62 \fi
63 \if@tempswa
64  \let\@auxout\@partaux
65  \if@filesw
66  \immediate\openout\@partaux #1.aux%
67  \immediate\write\@partaux{\relax}%
68  \fi
69  \@input@{#1.tex}%

70  \@writeckpt{#1}%
71  \if@filesw
72 % NOTE: Robin took out the \immediate here.
73 %      \immediate\closeout\@partaux
74  \closeout\@partaux
75  \fi
76 \else
77  \@nameuse{cp@#1}%
78 \fi
79 \let\@auxout\@mainaux

80 }

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!

81 \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.

82 \addto@macro\sc@radical@shutdown {%
83 \PackageInfo{includex}{\protect\sc@radical@shutdown\space beginning}%

84 }

Now we start adding \catcode commands. These first two should be redundant; but just in case someone changed things. …

85 \addto@macro\sc@radical@shutdown{\catcode`\%=14}    % 14 = comment
86 \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.

87 \newcommand\sc@disable@char[1] {%
88 \addto@macro\sc@radical@shutdown
89  {\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:

90 \@tfor\sc@t@a:=abcdefghijklmnopqrstuvwxyz%
91  ABCDEFGHIJKLMNOPQRSTUVWXYZ%
92  ~!@$&*()_+-=[]|/?.,<>%
93  1234567890%
94  `'";:%
95  \^\\\{\}\ % this is really the chars "^\{}" and space
96  \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.

97 \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.

 98 \addto@macro\sc@radical@shutdown{\endinput}
\sc@radical@shutdown@aftergroup We need to use \sc@radical@shutdown this way.
 99 \newcommand\sc@radical@shutdown@aftergroup {%
100 \aftergroup\sc@radical@shutdown

101 }

\sc@begindoc@toks \sc@enddoc@toks These are for \AtBeginIncludedDocument and \AtEndIncludedDocument.
102 \newtoks\sc@begindoc@toks
103 \sc@begindoc@toks{}
104 \newtoks\sc@enddoc@toks
105 \sc@enddoc@toks{}
\AtBeginIncludedDocument The analogue of \AtBeginDocument.
106 \newcommand\AtBeginIncludedDocument[1] {%
107  \sc@begindoc@toks\expandafter{\the\sc@begindoc@toks#1}%

108 }

\AtEndIncludedDocument The analogue of \AtEndDocument
109 \newcommand\AtEndIncludedDocument[1] {%
110  \sc@enddoc@toks\expandafter{\the\sc@enddoc@toks#1}%

111 }

\includedoc \includedoc* Now we start from the other end, defining the user command.

112 \newcommand\includedoc {%
113 % Robin's new:
114 \@ifstar {%
115  \def\sc@includebit@cmd{\include*}\sc@includebit
116  }{% ELSE
117  \let\sc@includebit@cmd\include\sc@includebit

118 }% 119 }

120

121 % My old:
122 %      {\sc@includebit}
123 %    {\clearpage
124 %    \sc@includebit[\clearpage]}}

\sc@includebit The commented-out code is for some eventual extensions.

Interface is sc@includebit[⟨postlude⟩]{⟨file⟩} (where [⟨postlude⟩] is command(s) to be executed after the inclusion is complete); it is assumed that

 sc@includebit@cmd is either \include or include*
125 \newcounter{sc@count}
126 \newcounter{bit}
127 \newcommand\sc@includebit [2] [] {%
128 \setcounter{sc@count}{\thebit}%
129 \begingroup
130  \DisableMonster
131  \let\usepackage\GobbleOM
132 % Robin's new:

133  \def\enddocument {%
134  \makeatletter
135  \the\sc@enddoc@toks
136  \sc@radical@shutdown@aftergroup

137 }

138 % My old:
139 % \let\enddocument\sc@radical@shutdown@aftergroup
140  \let\documentclass\GobbleOM
141  \let\documentstyle\GobbleOM  % why worry about branching if 2.09..
142  \def\document {%
143  \the\sc@begindoc@toks

144 }%

145  \def\IncludedJobname {#2}%
146  \sc@includebit@cmd{#2}%
147 \endgroup
148 \par

149 #1 150 }

\includedocskip \includedocskip* Now we make a similar command that entirely skips the preamble, whereas \includedoc only skipped those commands that we specifically disabled. Obviously 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.

151 \newcommand\includedocskip {%
152 \@ifstar {%
153  \sc@includebitskip
154  }{% ELSE
155  \clearpage
156  \sc@includebitskip[\clearpage]%

157 }% 158 }

   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.

\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.

159 \newcommand\sc@includebitskip [2] [] {%
160 \setcounter{sc@count}{\thebit}%
161 \begingroup
162  \DisableMonster
163  \let\enddocument\sc@radical@shutdown@aftergroup
164  \long\def\documentclass ##1\begin{%
165  \begingroup
166  \def\@currenvir{document}%

167  \GobbleM
168  }% "{document}" is still to be read.
169  \let\documentstyle\documentclass
170  \include*{#2}%
171 \endgroup
172 \par
173 #1\relax

174 }

Index

Numbers written in italic refer to the page where the corresponding entry is described; numbers underlined refer to the code line of the definition; numbers in roman refer to the code lines where the entry is used.

Symbols

\# . . . . . . . . . . . . . . 97 \% . . . . . . . . . . . . . . 85 \@auxout …. 43, 64, 79

\@currenvir . . . . . . . 166

\@eha . . . . . . . . . . . . 44 \@for . . . . . . . . . . . . 57 \@ifstar . . 37, 114, 152

\@ifundefined . . . . . 15

\@input . . . . . . . . . . 51 \@input@ . . . . . . . . . 69

\@latex@error . . . . . 44

\@mainaux . . . . . . 51, 79 \@nameuse . . . . . . . . 77

\@partaux . . . . . 43,

64, 66, 67, 73, 74

\@partlist . . . . . . . 57

\@tempa . . . . . . . . 57, 58 \@tempb . . . . . . . . 56, 59

\@tempswafalse . . . . 55
\@tempswatrue . . . 53, 60

\@tfor . . . . . . . . . . . 90

\@writeckpt . . . . . . . 70

\\ . . . . . . . . . . . . . 8, 95 \{ . . . . . . . . . . . . . . 95 \} . . . . . . . . . . . . . . 95 \^. . . . . . . . . . . . 86, 95

\␣ . . . . . . . . . . . . . . 95

A

\addto@macro . . . . . .

. 82, 85, 86, 88, 98

\aftergroup . . . . . . . 100
\AtBeginIncludedDocument

. . . . . . . . . . . \underline{106}

\AtEndIncludedDocument

. . . . . . . . . . . \underline{109}

\author . . . . . . . . . 6, 7

B

\begin . . . . . . . . . . . 164

\begingroup 129, 161, 165

C

\catcode …. 85, 86, 89

                          \clearpage . . . . . . .

. 123, 124, 155, 156 \closeout . . . . . . 73, 74 \csname . . . . . . . . . . 19

D \def 1–4, 10, 115, 133,

142, 145, 164, 166 \disable . . . . . . . . 2, \underline{31}

                          \DisableMonster . . .

. . 31, 33, 130, 162 \do . . . . . . . . . . . 58, 96 \docdate . . . . . . . . . . \underline{1} \document . . . . . . . . 142

                          \documentclass . . . .

…. 140, 164, 169

                          \documentstyle 141, 169
                          \DoXPackageS . . . . . . . 2
                          \DoXUsepackagE . . . . . \underline{1}

E \edef . . . . . . . . . . 11, 56 \eExpand . . . . . . . . . 19 \else . . . . . . . . . . 45, 76

                          \endcsname . . . . . . . 19
                          \enddocument . . . . . .

…. 133, 139, 163 \endgroup …. 147, 171 \endinput . . . . . . 24, 98

                          \expandafter . . . . . .

. . 46, 96, 107, 110

F \fi . . . . . . . . 47, 52,

61, 62, 68, 75, 78 \filedate . . . . . . . . . \underline{1} \fileinfo . . . . . . . . . \underline{1}

                          \fileversion . . . . . . . \underline{1}

G

                          \g@addto@macro . . . . 33

\GobbleM . . . . . . . . . 167 \GobbleOM . 131, 140, 141

H

                          \HaveECitationS . . . . \underline{1}

I

                          \if@filesw . . 50, 65, 71

                                                   \if@partsw . . . . . . . 54
                                                   \if@tempswa . . . . . . . 63

\ifnum . . . . . . . . . . . 43 \ifx . . . . . . . . . . . . . 58

                                                   \immediate . . . . . . .

. 51, 66, 67, 72, 73 \In . . . . . . . . . . . . . 19 \include \underline{35}, 115, 117, 170 \include* . . . . . . . . . 2

                                                   \IncludedJobname . . 145
                                                   \includedoc . . . . . 2, \underline{112}
                                                   \includedoc* . . . . 2, \underline{112}
                                                   \includedocskip . 2, \underline{151}
                                                   \includedocskip* 2, \underline{151}

J

                                                   \JusTLoaDInformatioN 17

L \let . . . . . . . . . . . 6,

64, 79, 117, 131, 139–141, 163, 169

\long . . . . . . . . . . . . 164

M

                                                   \makeatletter . . 14, 134
                                                   \makeatother . . . . . . 23
                                                   \MDSavedauthor . . . 6, 8

N

                                                   \NeedsTeXFormat . 26, 28
                                                   \newcommand 32, 41, 49,

87, 99, 106, 109, 112, 127, 151, 159

                                                   \newcounter . . . 125, 126

\newlet . . . . . . . . . . 35 \newtoks . . . . . 102, 104

O \openout . . . . . . . . . 66

P

                                                   \PackageInfo . . . . . . 83

\par . . . . . . . . . 148, 172 \PPOptArg . . . . . . . \underline{1}, 27 \protect . . . . . . . . . 83

                                                   \ProvidesPackage 27, 29

R \relax . . . . . 42, 67, 173

\renewcommand . . . . 7, 36
\RequirePackage . . . 30
\ReserveCS . . . . . 31, 81
\RestoreDoXVarS . . . 22

S

\SaveDoXVarS . . . . . . 18
\sc@@include . . . . . . \underline{35}
\sc@begindoc@toks .

…. \underline{102}, 107, 143

\sc@disable@char . .

. . . . . . . \underline{87}, 96, 97

\sc@enddoc@toks . . .

…. \underline{102}, 110, 135

                          \sc@include . . . . . . . \underline{35}
                          \sc@includebit 115,

117, 122, 124, \underline{125}

                          \sc@includebit@cmd .

…. 115, 117, 146

                          \sc@includebitskip .

…. 153, 156, \underline{159}

                          \sc@radical@shutdown

. . . . . . . . \underline{81}, 100

                          \sc@radical@shutdown@aftergroup

. \underline{99}, 136, 139, 163

                          \sc@saved@include . \underline{35}

\sc@t@a . . . . . . . . 90, 96

                                                   \setcounter . . . 128, 160

\space . . . . . . 12, 44, 83 \string . . . . . . . . 44, 51

T \the . . 107, 110, 135, 143 \thebit . . . . . . 128, 160

U

                                                   \UndefineCS . . . . . . . 17
                                                   \usepackage . . . . 20, 131

W \write . . . . . . . . . 51, 67