The filecontents package^{∗}

Scott Pakin scott+fc@pakin.org

August 23, 2004

1 Introduction

filecontents There is a little-known environment called filecontents that is built into L^{A}TEX 2ε. Here is filecontents’ description, which was taken from ltclass.dtx:

The environment filecontents is intended for passing the contents of packages, options, or other files along with a document in a single file. It has one argument, which is the name of the file to create. If that file already exists (maybe only in the current directory if the OS supports a notion of a ‘current directory’ or ‘default directory’) then nothing happens (except for an information message) and the body of the environment is bypassed. Otherwise, the body of the environment is written verbatim to the file name given as the first argument, together with some comments about how it was produced.

The environment is allowed only before \documentclass to ensure that all packages or options necessary for this particular run are present when needed. The begin and end tags should each be on a line by itself. There is also a star-form; this does not write extra comments into the file.

The filecontents package provides a hacked-up version of the filecontents and filecontents* environments that lifts the two restrictions stated above, namely that existing files are never overwritten and that filecontents must be used before the \documentclass declaration. filecontents is therefore a more convenient way to write external files from within a L^{A}TEX document than is provided by default by the L^{A}TEX 2ε kernel.

Sample usage filecontents works much like verbatim, except that it takes a (mandatory) filename argument:

\begin{filecontents}{myfile.tex}
This text gets written to \texttt{myfile.tex}.
\end{filecontents}

∗This file has version number v1.1, last revised 2004/08/16.

The preceding code will write a myfile.tex file with contents resembling the following:

     %% LaTeX2e file `myfile.tex'
     %% generated by the `filecontents' environment
     %% from source `mydocument' on 2001/07/31.
     %%
     This text gets written to \texttt{myfile.tex}.

myfile.tex can then be incorporated back into the document with \include or \input. Had filecontents* been used instead of filecontents, the file would

have contained only the “This text gets written to\texttt{myfile.tex}.”

line. filecontents* is therefore useful for writing non-L^{A}TEX files such as Encapsulated PostScript files.

If you use the ltxtable package, you may find filecontents particularly useful. ltxtable is a crude conglomeration of longtable, which allows tables to cross page boundaries, and tabularx, which enables tables to stretch to a specified width. ltxtable’s interface is a bit cumbersome, however; it requires that the longtable environment be contained in a separate file. With the filecontents package, you can create this file right before the \LTXtable invocation, which is far more convenient than having to place the table manually within a separate file.

2 Implementation

Most users can stop reading at this point. The Implementation section contains the annotated source code for the filecontents package itself, which is useful only to people who want a detailed and precise explanation of how filecontents works.

To give credit where credit is due, I wrote virtually none of the filecontents code myself. It comes almost exclusively from the L^{A}TEX 2ε source code, specifically from the file ltclass.dtx, which is attributed to Frank Mittelbach, Chris Rowley, Alan Jeffrey, and David Carlisle. I merely made a few small changes (indicated below by bracketed blocks of code and comments) to make the filecontents environment more convenient to use.

1 ⟨∗package⟩

\filec@ntents Except where indicated, the source—including comments—to the \filec@ntents macro was taken verbatim from ltclass.dtx.

 2 \begingroup%
 3 \catcode`\*=11 %
 4 \catcode`\^^M\active%
 5 \catcode`\^^L\active\let^^L\relax%
 6 \catcode`\^^I\active%
 7 \gdef\filec@ntents#1{%
 8 \openin\@inputcheck#1 %

In the original code, a pre-existing file would not be overwritten. In the new version, the file existence check is used solely to decide whether to output “Writing file `⟨filename⟩'” or “Overwriting file `⟨filename⟩'”. Control flow then always falls through to what used to be the \ifeof case (file does not exist; open it), never the \else case (file already exists; do nothing).

 9 \ifeof\@inputcheck%
10  \@latex@warning@no@line%
11  {Writing file `\@currdir#1'}%
12 \else
13  \@latex@warning@no@line%
14  {Overwriting file `\@currdir#1'}%
15 \fi
16 \chardef\reserved@c15 %
17 \ch@ck7\reserved@c\write%
18 \immediate\openout\reserved@c#1\relax%

19 \if@tempswa%
20  \immediate\write\reserved@c{%
21  \@percentchar\@percentchar\space%
22  \expandafter\@gobble\string\LaTeX2e file `#1'^^J%
23  \@percentchar\@percentchar\space  generated by the %
24  `\@currenvir' \expandafter\@gobblefour\string\newenvironment^^J%
25  \@percentchar\@percentchar\space from source `\jobname' on %
26  \number\year/\two@digits\month/\two@digits\day.^^J%
27  \@percentchar\@percentchar}%
28 \fi%
29 \let\do\@makeother\dospecials%

The inputenc packages might have marked some of the upper 128 character codes “active” (category code 13). That confuses filecontents. Hence, we locally mark each of the upper 128 character codes as “letter” (category code 11) so that they can be written correctly to a file.

30 \count0=128\relax
31 \loop
32  \catcode\count0=11\relax
33  \advance\count0 by 1\relax
34  \ifnum\count0<256
35 \repeat

36 \edef\E{\@backslashchar end\string{\@currenvir\string}}%
37 \edef\reserved@b{%
38  \def\noexpand\reserved@b%
39  ####1\E####2\E####3\relax}%
40 \reserved@b{%
41  \ifx\relax##3\relax%
There was no \end{filecontents}
42  \immediate\write\reserved@c{##1}%
43  \else%

There was a \end{filecontents}, so stop this time.

44  \edef^^M{\noexpand\end{\@currenvir}}%
45  \ifx\relax##1\relax%
46  \else%

Text before the \end, write it with a warning.

47  \@latex@warning{Writing text `##1' before %
48  \string\end{\@currenvir}\MessageBreak as last line of #1}%
49  \immediate\write\reserved@c{##1}%
50  \fi%
51  \ifx\relax##2\relax%
52  \else%

Text after the \end, ignore it with a warning.

53  \@latex@warning{%
54  Ignoring text `##2' after \string\end{\@currenvir}}%
55  \fi%
56  \fi%
57  ^^M}%
58 \catcode`\^^L\active%
59 \let\L\@undefined%
60 \def^^L{\@ifundefined L^^J^^J^^J}%
61 \catcode`\^^I\active%
62 \let\I\@undefined%
63 \def^^I{\@ifundefined I\space\space}%
64 \catcode`\^^M\active%
65 \edef^^M##1^^M{%
66  \noexpand\reserved@b##1\E\E\relax}}%
67 \endgroup%
\fc@no@preamblecmds L^{A}TEX 2ε declares \filecontents, \filecontents*, and all of the related

helper macros as \@onlypreamble, meaning they become invalid after the \begin{document}. The following code re-enables their usage anywhere in the document. It was taken from the pkgindoc package (which is generated from ltclass.dtx), but modified to re-enable only the commands needed by filecontents, not all of the class and package option-processing commands, as well.

68 \def\fc@no@preamblecmds#1\do\filecontents#2\do\filec@ntents#3\relax{%
69 \gdef\@preamblecmds{#1#3}}
70 \expandafter\fc@no@preamblecmds\@preamblecmds\relax

71 ⟨/package⟩

Change History

v1.0

General: Initial version . . . . . . . . 1 v1.1

   \filec@ntents: Made it possi-

ble for filecontents to write Latin-1 characters as per Harry Schmidt’s feature request and Frank Mittelbach’s suggestion of how to implement it. . . . . . . 3

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

\@backslashchar . . . 36  4

\@currdir . . . . . . 11, 14

\@inputcheck . . . . . 8, 9
\@latex@warning . 47, 53
\@latex@warning@no@line

. . . . . . . . . 10, 13

\@percentchar . . . . .

…. 21, 23, 25, 27

\@preamblecmds . . 69, 70

\^. . . . . . 4–6, 58, 61, 64

A \active . . 4–6, 58, 61, 64

C \ch@ck . . . . . . . . . . . 17 \chardef . . . . . . . . . 16

D

                          \dospecials . . . . . . . 29

E environments:filecontents

                                                       filecontents . . . . 1

F

                                                   \fc@no@preamblecmds   \underline{68}
                                                   \filec@ntents . . . . \underline{2}, 68
                                                   \filecontents . . . . . 68
                                                   filecontents (environ-

ment) . . . . . . . . 1