ltfiles.dtx

Johannes Braams  David Carlisle  Alan Jeffrey
Leslie Lamport  Frank Mittelbach  Chris Rowley

Rainer Schöpf

1995/12/05

1 File Handling

The following user commands are defined in this part:

\document  (ie \begin{document})

Reads in the .AUX files and \catcode’s @ to 12.

\nofiles

Suppresses all file output by setting \@filesw false.

\includeonly {⟨NAME1, ... ,NAMEn⟩} Causes only parts NAME1, ... ,NAMEn to be read by their \include commands. Works by setting partsw true and setting \@partlist to NAME1, ... ,NAMEn.

\include      {⟨NAME⟩}

Does an \input NAME unless \partsw is true and NAME is not in \@partlist. If \@filesw is true, then it directs .AUX output to NAME.AUX, including a checkpoint at the end.

\input      {⟨NAME⟩}

The same as TeX’s \input, except it allows optional braces around the file name. In L^{A}TEX 2ε, it also avoids the primiive ‘missing file’ error, if the file can not be found.

\IfFileExists      {⟨NAME⟩}{⟨then⟩}{⟨else⟩}

If the file exists on the system, execute then otherwise execute else.

\InputIfFileExists      {⟨NAME⟩}{⟨then⟩}{⟨else⟩}

If the file exists on the system, execute then and input NAME otherwise execute else.

1 ⟨∗2ekernel | autoload⟩

 2 \message{files,}

VARIABLES, SWITCHES AND INTERNAL COMMANDS: \@mainaux : Output file number for main .AUX file. \@partaux : Output file number for current part’s .AUX file.

    \@auxout  : Either \@mainout or \@partout, depending on

which .AUX file output goes to.

\@input{foo} : If file foo exists, then \input's it,

otherwise types a warning message.

@filesw : Switch – set false if no .AUX, .TOC, .IDX etc

files are to be written

@partsw : Set true by a \includeonly command. \@partlist : Set to the argument of the \includeonly command.

\cp@FOO : The checkpoint for \include'd file FOO.TEX, written by \@writeckpt at the end of file FOO.AUX

\includeonly{FILELIST} ==

BEGIN

\@partsw := T
\@partlist := FILELIST

END

\include{FILE} ==

BEGIN

\clearpage
if \@filesw = T
  then \immediate\write\@mainaux{\string\@input{FILE.AUX}}

fi

if \@partsw = T
  then \@tempswa := F
       \reserved@b == FILE
       for \reserved@a := \@partlist
           do if eval(\reserved@a) = eval(\reserved@b)
                then \@tempswa := T  fi

od

fi

if \@tempswa = T
   then \@auxout := \@partaux
        if \@filesw = T
          then \immediate\openout\@partaux{FILE.AUX}
                \immediate\write\@partaux{\relax}

fi

        \@input{FILE.TEX}
        \clearpage
        \@writeckpt{FILE}
        if @filesw then \closeout \@partaux fi
        \@auxout := \@mainaux
   else \cp@FILE

fi END

\@writeckpt{FILE} ==

BEGIN

  if \@filesw = T
      \immediate\write on file \@partaux:
                \@setckpt{FILE}{                  %% }
      for \reserved@a := \cl@@ckpt
         do \immediate\write on file \@partaux:
                 \global\string\setcounter
{eval(\reserved@a)}{eval(\c@eval(\reserved@a))}
         od  %% {
      \immediate\write on file \@partaux:  }

fi END

\@setckpt{FILE}{LIST} ==

BEGIN

  G \cp@FILE := LIST

END

INITIALIZATION

  \@tempswa := T

\@inputcheck \@unused Allocate read stream for testing and output stream.

3 \newread\@inputcheck
4 \newwrite\@unused
\@mainaux \@partaux
5 \newwrite\@mainaux
6 \newwrite\@partaux
\if@filesw \if@partsw
7 \newif\if@filesw \@fileswtrue
8 \newif\if@partsw \@partswfalse
\@clubpenalty
9 \newcount\@clubpenalty

FMi & RmS 1991/08/26 set \@noskipsec switch to true in the preamble and to false by \begin{document} to catch lists in the preamble, i.e., to produce a “nodocument” error when things like \maketitle appear before

\begin{document}.

\@noskipsectrue set below where switch is defined 1991/03/26 FMi: \process@table added to support NFSS. This will also work

with old lfonts if no other style defines \process@table.

\document Cancel the \begingroup from \begin
10 \def\document{\endgroup

If some options on \documentclass haven’t been used by any package we will now give a warning since this is most certainly a misspelling.

11 \ifx\@unusedoptionlist\@empty\else
12  \@latex@warning@no@line{Unused global option(s):^^J%
13  \@spaces[\@unusedoptionlist]}%
14 \fi
15 \@colht\textheight
16 \@colroom\textheight \vsize\textheight
17 \columnwidth\textwidth
18 \@clubpenalty\clubpenalty
19 \if@twocolumn
20  \advance\columnwidth -\columnsep
21  \divide\columnwidth\tw@ \hsize\columnwidth \@firstcolumntrue
22 \fi
23 \hsize\columnwidth \linewidth\hsize
24 \begingroup\@floatplacement\@dblfloatplacement
25  \makeatletter\let\@writefile\@gobbletwo
26  \global \let \@multiplelabels \relax
27  \@input{\jobname.aux}%
28 \endgroup
29 \if@filesw
30  \immediate\openout\@mainaux\jobname.aux
31  \immediate\write\@mainaux{\relax}%
32 \fi
33 \process@table
34 \let\glb@currsize\@empty  %% Force math initialisation.
35 \normalsize
36 \everypar{}\@noskipsecfalse
37 \let \@refundefined \relax

Just before disabling the preamble commands we execute the begin document hook which contains any code contributed by \AtBeginDocument. Also disable the gathering of the file list, if no \listfiles has been issued. Since a value of exactly 0pt for \topskip causes \twocolumn[] to misbehave, we add this check, hoping that it will not cause any problems elsewhere.

38 \@begindocumenthook

Most of the following assignments will be done globally in case the user adds something like \begin{multicols} to the document hook, ie starts are group in

\begin{document}.
39 \ifdim\topskip< 1sp\global\topskip 1sp\relax\fi
40 \global\@maxdepth\maxdepth
41 \global\let\@begindocumenthook\@undefined
42 \ifx\@listfiles\@undefined
43  \global\let\@filelist\relax
44  \global\let\@addtofilelist\@gobble

45 \fi

At the very end we disable all preamble commands. This has to happen after the begin document hooks was executed so that this hook can still use such commands.

\AtBeginDocument.
46 \gdef\do##1{\global\let ##1\@notprerr}%
47 \@preamblecmds

The next line is a pure safty measure in case a do list is ever expanded at the wrong place. In addition it will save a few tokens to get rid of the above definition.

48 \global\let\do\noexpand

Use of \AtBeginDocument hook might mean that we are already in horizontal mode, so ignore the space after \begin{document}.

49 \ignorespaces}
50 \@onlypreamble\document
\nofiles
51 \def\nofiles{\@fileswfalse
52 \typeout{No auxiliary output files.^^J}%
53 \long\def\protected@write##1##2##3{}%
54 \let\makeindex\relax
55 \let\makeglossary\relax}
56 \@onlypreamble\nofiles

\protected@write This takes three arguments: an output stream, some initialization code, and some text to write. It then writes this, with appropriate handling of \protect and

\thepage.
57 \long\def \protected@write#1#2#3{%
58  \begingroup
59  \let\thepage\relax
60  #2%
61  \let\protect\@unexpandable@protect
62  \edef\reserved@a{\write#1{#3}}%
63  \reserved@a
64  \endgroup
65  \if@nobreak\ifvmode\nobreak\fi\fi

66 }

67 \let\@auxout=\@mainaux
\includeonly
68 \def\includeonly#1{\@partswtrue
69  \edef\@partlist{\zap@space#1 \@empty}}
70 \@onlypreamble\includeonly
\include In the definition of \include, \def\reserved@b changed to \edef\reserved@b

to be consistent with the \edef in \includeonly. (Suggested by Rainer Schöpf & Frank Mittelbach. Change made 20 Jul 88.)

Changed definition of \include to allow space at end of file name — otherwise, typing \include{foo } would cause L^{A}TEX to overwrite foo.tex. Change made 24 May 89, suggested by Rainer Schöpf and Frank Mittelbach

Made \include check for being used inside an \include’d file, as this will not work and cause surprising results.

71 \def\include#1{\relax
72 \ifnum\@auxout=\@partaux
73  \@latex@error{\string\include\space cannot be nested}\@eha
74 \else \@include#1 \fi}
75 \def\@include#1 {%
76 \clearpage
77 \if@filesw
78  \immediate\write\@mainaux{\string\@input{#1.aux}}%
79 \fi
80 \@tempswatrue
81 \if@partsw
82  \@tempswafalse
83  \edef\reserved@b{#1}%
84  \@for\reserved@a:=\@partlist\do
85  {\ifx\reserved@a\reserved@b\@tempswatrue\fi}%
86 \fi
87 \if@tempswa
88  \let\@auxout\@partaux
89  \if@filesw
90  \immediate\openout\@partaux #1.aux
91  \immediate\write\@partaux{\relax}%
92  \fi
93  \@input@{#1.tex}%
94  \clearpage
95  \@writeckpt{#1}%
96  \if@filesw
97  \immediate\closeout\@partaux
98  \fi
99 \else
100  \@nameuse{cp@#1}%
101 \fi
102 \let\@auxout\@mainaux}
103 \def\@writeckpt#1{\if@filesw
104 \immediate\write\@partaux{\string\@setckpt{#1}\@charlb}%
105 {\let\@elt\@wckptelt \cl@@ckpt}\immediate\write\@partaux{\@charrb}\fi}
106 \def\@wckptelt#1{\immediate\write\@partaux
107 {\string\setcounter{#1}{\the\@nameuse{c@#1}}}}

RmS 93/08/31: introduced \@setckpt

108 \def\@setckpt#1{\global\@namedef{cp@#1}}

The following defines \@charlb and \@charrb to be { and }, respectively with

\catcode 11.
109 {\catcode`[=1 \catcode`]=2

110 \catcode`{=11 \catcode`}=11
111 \gdef\@charlb[{]
112 \gdef\@charrb[}]
113 ]% }brace matching

1.1 Safe Input Macros

\IfFileExists
114 \long\def \IfFileExists#1#2#3{%
115 \openin\@inputcheck#1 %
116 \ifeof\@inputcheck
117  \ifx\input@path\@undefined
118  \def\reserved@a{#3}%
119  \else
120  \def\reserved@a{\@iffileonpath{#1}{#2}{#3}}%
121  \fi
122 \else
123  \closein\@inputcheck
124  \edef\@filef@und{#1 }%
125  \def\reserved@a{#2}%
126 \fi
127 \reserved@a}

\@iffileonpath If the file is not found by \openin, and \input@path is defined, look in all the directories specified in \input@path.

128 \long\def \@iffileonpath#1#2#3{%
129 \def\reserved@a{#3}%
130 \expandafter\@tfor\expandafter\reserved@b\expandafter
131  :\expandafter=\input@path\do{%
132  \openin\@inputcheck\reserved@b#1 %
133  \ifeof\@inputcheck\else
134  \edef\@filef@und{\reserved@b#1 }%
135  \def\reserved@a{#2}%
136  \closein\@inputcheck
137  \@break@tfor
138  \fi}%
139 \reserved@a}

\InputIfFileExists Now define \InputIfFileExists to input #1 if it seems to exist. Immediately prior to the input, #2 is executed. If the file #1 does not exist, execute ‘#3’.

140 \long\def \InputIfFileExists#1#2{%
141 \IfFileExists{#1}%
142  {#2\@addtofilelist{#1}\@@input \@filef@und}}

\input Input a file: if argument is given in braces use save input macros, otherwise use TEX’s primitive \input command (which is called \@@input in L^{A}TEX).

143 \def\input{\@ifnextchar\bgroup\@iinput\@@input}

\@iinput Define \@iinput (i.e., \input) in terms of \InputIfIfileExists.
144 \def\@iinput#1{%
145 \InputIfFileExists{#1}{}%
146 {\filename@parse{#1}%
147 \edef\reserved@a{\noexpand\@missingfileerror
148  {\filename@area\filename@base}%
149  {\ifx\filename@ext\relax tex\else\filename@ext\fi}}%
150 \reserved@a}}

\@input Define \@input in terms of \IfIfileExists. So this is a ‘safe input’ command,

but the files input are not listed by \listfiles.

We don’t want .aux, .toc files etc be listed by \listfiles. However, something like .bbl probably should be listed and thus should be implemented not by

 \@input.
151 \def\@input#1{%
152 \IfFileExists{#1}{\@@input\@filef@und}{\typeout{No file #1.}}}

\@input@ Version of \@input that does add the file to \@filelist.

153 \def\@input@#1{\InputIfFileExists{#1}{}{\typeout{No file #1.}}}

\@missingfileerror This ‘error’ command avoids TEX’s primitive missing file loop.

Missing file error. Prompt for a new filename, offering a default extension.

154 ⟨autoload⟩\def\@missingfileerror{\@autoerr\@missingfileerror}

155 ⟨/2ekernel | autoload⟩ 156 ⟨∗2ekernel | autoerr⟩

157 \gdef\@missingfileerror#1#2{%
158  \typeout{^^J! LaTeX Error: File `#1.#2' not found.^^J^^J%
159  Type X to quit or <RETURN> to proceed,^^J%
160  or enter new name. (Default extension: #2)^^J}%
161  \message{Enter file name: }%
162  {\endlinechar\m@ne
163  \global\read\m@ne to\@gtempa}%
164  \ifx\@gtempa\@empty
165  \else
166  \def\reserved@a{x}\ifx\reserved@a\@gtempa\batchmode\@@end\fi
167  \def\reserved@a{X}\ifx\reserved@a\@gtempa\batchmode\@@end\fi
168  \filename@parse\@gtempa
169  \edef\filename@ext{%
170  \ifx\filename@ext\relax#2\else\filename@ext\fi}%
171  \edef\reserved@a{%
172  \noexpand\InputIfFileExists
173  {\filename@area\filename@base.\filename@ext}%
174  {}%
175  {\noexpand\@missingfileerror
176  {\filename@area\filename@base}{\filename@ext}}}%
177  \reserved@a
178  \fi}

179 ⟨/2ekernel | autoerr⟩ 180 ⟨∗2ekernel | autoload⟩

\@obsoletefile For compatibility with L^{A}TEX 2.09 document styles, we distribute files called

 article.sty, book.sty, report.sty, slides.sty and letter.sty. These use

the command \@obsoletefile, which produces a warning message.

181 \def\@obsoletefile#1#2{%
182 \@latex@warning@no@line{inputting `#1' instead of obsolete `#2'}}
183 \@onlypreamble\@obsoletefile

1.2 Listing files

\@filelist A list of files input so far. The initial value of \@gobble eats the comma before the first file name.

184 \let\@filelist\@gobble

\@addtofilelist Add to the list of files input so far. This ‘real’ definition is only used for ‘cfg’ files during initex. An initial definition of \@gobble has already been set.

185 %\def\@addtofilelist#1{\xdef\@filelist{\@filelist,#1}}

\listfiles A preamble command to cause \end{document} to list files input from the main file.

186 \def\listfiles{%
187 \let\listfiles\relax
188 \def\@listfiles##1##2##3##4##5##6##7##8##9\@@{%
189  \def\reserved@d{\\}%
190  \@tfor\reserved@c:=##1##2##3##4##5##6##7##8\do{%
191  \ifx\reserved@c\reserved@d
192  \edef\filename@area{ \filename@area}%
193  \fi}}%
194 \def\@dofilelist{%
195  \typeout{^^J *File List*}%
196  \@for\@currname:=\@filelist\do{%
197  \filename@parse\@currname
198  \edef\reserved@a{%
199  \filename@base.%
200  \ifx\filename@ext\relax tex\else\filename@ext\fi}%
201  \expandafter\let\expandafter\reserved@b
202  \csname ver@\reserved@a\endcsname
203  \expandafter\expandafter\expandafter\@listfiles\expandafter
204  \filename@area\filename@base\\\\\\\\\\\\\\\\\\\@@
205  \typeout{%
206  \filename@area\reserved@a
207  \ifx\reserved@b\relax\else\@spaces\reserved@b\fi}}%
208  \typeout{ ***********^^J}}}

The \@filelist will be de-activated if \listfiles does not appear in the preamble. \begin{document} contains code equivalent to the following:

  \AtBeginDocument{%
    \ifx\@listfiles\@undefined
      \let\@filelist\relax

      \let\@addtofilelist\@gobble
    \fi}
209 \@onlypreamble\listfiles
\@dofilelist
210 \let\@dofilelist\relax

211 ⟨/2ekernel | autoload⟩