Debian Codegraph @

texmf-dist/source/latex/filecontents/filecontents.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2001-2023 Scott Pakin <[email protected]>
4 % --------------------------------------------------------
5 %
6 % This package may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3c
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.3c or later is part of all distributions of LaTeX
14 % version 2008/05/04 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<*driver>
20 \ProvidesFile{filecontents.dtx}
21 %</driver>
22 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
23 %<package>\ProvidesPackage{filecontents}
24 %<*package>
25 [2023/04/02 v1.5a Create an external file from within a LaTeX document]
26 %</package>
27 %
28 %<*driver>
29 \documentclass{ltxdoc}
30 \usepackage{color}
31 \usepackage{microtype}
32 \EnableCrossrefs
33 \CodelineIndex
34 \RecordChanges
35 \begin{document}
36 \DocInput{filecontents.dtx}
37 \end{document}
38 %</driver>
39 % \fi
40 %
41 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
42 %
43 % \CheckSum{191}
44 %
45 % \CharacterTable
46 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
47 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
48 % Digits \0\1\2\3\4\5\6\7\8\9
49 % Exclamation \! Double quote \" Hash (number) \#
50 % Dollar \$ Percent \% Ampersand \&
51 % Acute accent \' Left paren \( Right paren \)
52 % Asterisk \* Plus \+ Comma \,
53 % Minus \- Point \. Solidus \/
54 % Colon \: Semicolon \; Less than \<
55 % Equals \= Greater than \> Question mark \?
56 % Commercial at \@ Left bracket \[ Backslash \\
57 % Right bracket \] Circumflex \^ Underscore \_
58 % Grave accent \` Left brace \{ Vertical bar \|
59 % Right brace \} Tilde \~}
60 %
61 % \GetFileInfo{filecontents.dtx}
62 %
63 % \title{The \textsf{filecontents} package\thanks{This file
64 % has version number \fileversion, last
65 % revised \filedate.}}
66 % \author{Scott Pakin \\ \textit{[email protected]}}
67 % \maketitle
68 %
69 % \changes{v1.0}{2001/07/31}{Initial version}
70 % \changes{v1.1a}{2006/03/11}{%
71 % Clarified/corrected the \texttt{\string\string\string\documentclass}
72 % restriction as per Robin Fairbairns's suggestion}
73 % \changes{v1.5a}{2023/04/02}{Documentation updates; no code changes}
74 %
75 % ^^A The following were copied verbatim from source2e.tex.
76 % \DoNotIndex{\def,\long,\edef,\xdef,\gdef,\let,\global}
77 % \DoNotIndex{\if,\ifnum,\ifdim,\ifcat,\ifmmode,\ifvmode,\ifhmode,%
78 % \iftrue,\iffalse,\ifvoid,\ifx,\ifeof,\ifcase,\else,\or,\fi}
79 % \DoNotIndex{\box,\copy,\setbox,\unvbox,\unhbox,\hbox,%
80 % \vbox,\vtop,\vcenter}
81 % \DoNotIndex{\@empty,\immediate,\write}
82 % \DoNotIndex{\egroup,\bgroup,\expandafter,\begingroup,\endgroup}
83 % \DoNotIndex{\divide,\advance,\multiply,\count,\dimen}
84 % \DoNotIndex{\relax,\space,\string}
85 % \DoNotIndex{\csname,\endcsname,\@spaces,\openin,\openout,%
86 % \closein,\closeout}
87 % \DoNotIndex{\catcode,\endinput}
88 % \DoNotIndex{\jobname,\message,\read,\the,\m@ne,\noexpand}
89 % \DoNotIndex{\hsize,\vsize,\hskip,\vskip,\kern,\hfil,\hfill,\hss}
90 % \DoNotIndex{\m@ne,\z@,\z@skip,\@ne,\tw@,\p@}
91 % \DoNotIndex{\dp,\wd,\ht,\vss,\unskip}
92 %
93 % ^^A The following are specific to filecontents.dtx.
94 % \DoNotIndex{\@currenvir,\@gobble,\@gobblefour,\@ifundefined,\@makeother}
95 % \DoNotIndex{\@undefined,\active,\chardef,\day,\do,\dospecials,\E,\end,\I}
96 % \DoNotIndex{\if@tempswa,\L,\LaTeX,\loop,\MessageBreak,\month}
97 % \DoNotIndex{\newenvironment,\number,\repeat,\reserved@b,\reserved@c}
98 % \DoNotIndex{\two@digits,\year,\*,\^}
99 %
100 % ^^A Define some commands to help delineate my changes.
101 % \newcommand{\startfcchanges}{^^A
102 % \centerline{^^A
103 % \makebox[0pt]{^^A
104 % \raisebox{-2\baselineskip}[0pt][0pt]{^^A
105 % \makebox[0pt][l]{\rule{1pt}{2\baselineskip}}}^^A
106 % \rule{1em}{1pt}^^A
107 % \rule{\linewidth}{1pt}^^A
108 % \rule{1em}{1pt}^^A
109 % \raisebox{-2\baselineskip}[0pt][0pt]{^^A
110 % \makebox[0pt][r]{\rule{1pt}{2\baselineskip}}}^^A
111 % }^^A
112 % }^^A
113 % \noindent
114 % }
115 % \newcommand{\stopfcchanges}{^^A
116 % \centerline{^^A
117 % \makebox[0pt]{^^A
118 % \raisebox{0pt}[0pt][0pt]{^^A
119 % \makebox[0pt][l]{\rule{1pt}{2\baselineskip}}}^^A
120 % \rule{1em}{1pt}^^A
121 % \rule{\linewidth}{1pt}^^A
122 % \rule{1em}{1pt}^^A
123 % \raisebox{0pt}[0pt][0pt]{^^A
124 % \makebox[0pt][r]{\rule{1pt}{2\baselineskip}}}^^A
125 % }^^A
126 % }^^A
127 % }
128 %
129 % \newsavebox{\obsoletenotice}
130 % \begin{lrbox}{\obsoletenotice}
131 % \begin{minipage}[t]{0.75\linewidth}
132 % \color{red}
133 % \centerline{\textsc{Notice}}
134 % \smallskip
135 % The version of \LaTeX\ released in Fall 2019 incorporates all of
136 % this package's functionality (and more) into the \LaTeX\ kernel
137 % itself. As a result, there is no longer a need for the
138 % |filecontents| package. Please use instead the new, built-in
139 % |filecontents| environment. Supply the |overwrite| option to
140 % mimic this package's behavior:
141 %
142 % \bigskip
143 % \quad
144 % \begin{tabular}[t]{@{}l@{}}
145 % |\begin{filecontents}[overwrite]{|\meta{filename}|}| \\
146 % \multicolumn{1}{@{}c@{}}{$\vdots$} \\
147 % |\end{filecontents}|
148 % \end{tabular}
149 % \bigskip
150 %
151 % See
152 % \href{https://www.latex-project.org/news/latex2e-news/ltnews30.pdf}{^^A
153 % \LaTeXe\ News, Issue 30} (1-Oct-2019) for the announcement of the
154 % new kernel functionality.
155 % \end{minipage}
156 % \end{lrbox}
157 %
158 % \begin{center}
159 % \color{red}
160 % \fbox{\usebox{\obsoletenotice}}
161 % \end{center}
162 %
163 %
164 % \section{Introduction}
165 %
166 % \DescribeEnv{filecontents}
167 % There is a little-known environment called |filecontents| that is
168 % built into \LaTeXe. Here is |filecontents|' description, which was
169 % taken from |ltclass.dtx|:
170 %
171 % \begin{quotation}
172 % The environment |filecontents| is intended for passing the contents of
173 % packages, options, or other files along with a document in a single
174 % file. It has one argument, which is the name of the file to
175 % create. If that file already exists (maybe only in the current
176 % directory if the OS supports a notion of a `current directory' or
177 % `default directory') then nothing happens (except for an information
178 % message) and the body of the environment is bypassed. Otherwise, the
179 % body of the environment is written verbatim to the file name given as
180 % the first argument, together with some comments about how it was
181 % produced.
182 %
183 % The environment is allowed only before |\documentclass| to ensure that
184 % all packages or options necessary for this particular run are present
185 % when needed. The begin and end tags should each be on a line by
186 % itself. There is also a star-form; this does not write extra comments
187 % into the file.
188 % \end{quotation}
189 %
190 % \noindent
191 % (The comment about |filecontents| being valid only before
192 % |\documentclass| is, in fact, untrue. |filecontents| is allowed
193 % anywhere in the document's preamble.)
194 %
195 % \bigskip
196 %
197 % The \textsf{filecontents} package provides a hacked-up version of the
198 % |filecontents| and |filecontents*| environments that lifts the two
199 % restrictions stated above, namely that existing files are never
200 % overwritten and that |filecontents| must be used before the
201 % |\documentclass| declaration (really, the |\begin{document}|).
202 % \textsf{filecontents} is therefore a more convenient way to write
203 % external files from within a \LaTeX\ document than is provided by
204 % default by the \LaTeXe\ kernel.
205 %
206 %
207 % \paragraph{Sample usage}
208 % |filecontents| works much like |verbatim|, except that it takes
209 % a mandatory filename argument:
210 %
211 % \begin{verbatim}
212 % \begin{filecontents}{myfile.tex}
213 % This text gets written to \texttt{myfile.tex}.
214 % \end{filecontents}
215 % \end{verbatim}
216 %
217 % \noindent
218 % The preceding code will write a |myfile.tex| file with contents resembling
219 % the following:
220 %
221 % \begin{verbatim}
222 % %% LaTeX2e file `myfile.tex'
223 % %% generated by the `filecontents' environment
224 % %% from source `mydocument' on 2001/07/31.
225 % %%
226 % This text gets written to \texttt{myfile.tex}.
227 % \end{verbatim}
228 %
229 % \noindent
230 % |myfile.tex| can then be incorporated back into the document with
231 % |\include| or |\input|. Had |filecontents*| been used instead of
232 % |filecontents|, the file would have contained only the
233 % ``\texttt{This text gets written to} \verb"\texttt{myfile.tex}."'' line.
234 % |filecontents*| is therefore useful for writing non-\LaTeX\ files such as
235 % Encapsulated PostScript files.
236 %
237 % If you use the \textsf{ltxtable} package you may find
238 % \textsf{filecontents} particularly useful. \textsf{ltxtable} is a
239 % crude conglomeration of \textsf{longtable}, which allows tables to
240 % cross page boundaries, and \textsf{tabularx}, which enables tables to
241 % stretch to a specified width. \textsf{ltxtable}'s interface is a bit
242 % cumbersome, however; it requires that the |longtable| environment be
243 % contained in a separate file. With the \textsf{filecontents} package
244 % you can create this file right before the |\LTXtable| invocation---a
245 % far more convenient alternative than having to manually place the
246 % table within a separate file.
247 %
248 %
249 % \StopEventually{^^A
250 % \PrintChanges
251 % \clearpage
252 % \PrintIndex
253 % }
254 %
255 % \section{Implementation}
256 %
257 % Most users can stop reading at this point. The Implementation section
258 % contains the annotated source code for the \textsf{filecontents}
259 % package itself, which is useful only to people who want a detailed and
260 % precise explanation of how \textsf{filecontents} works.
261 %
262 % To give credit where credit is due, I wrote virtually none of the
263 % \textsf{filecontents} code myself. It comes almost exclusively from
264 % the \LaTeXe\ source code, specifically from the file |ltclass.dtx|,
265 % which is attributed to Frank Mittelbach, Chris Rowley, Alan Jeffrey,
266 % and David Carlisle. I merely made a few small changes (indicated below
267 % by bracketed blocks of code and comments) to make the |filecontents|
268 % environment more convenient to use.
269 %
270 % \begin{macrocode}
271 %<*package>
272 % \end{macrocode}
273 %
274 % \begin{macro}{\filec@ntents@old@kernel}
275 % Except where indicated, the source---including comments---to the
276 % |\filec@ntents| macro---was taken verbatim from |ltclass.dtx|.
277 % \begin{macrocode}
278 \begingroup%
279 \catcode`\*=11 %
280 \catcode`\^^M\active%
281 \catcode`\^^L\active\let^^L\relax%
282 \catcode`\^^I\active%
283 % \end{macrocode}
284 %
285 % \begin{macrocode}
286 \gdef\filec@ntents@old@kernel#1{%
287 \openin\@inputcheck#1 %
288 % \end{macrocode}
289 %
290 % \startfcchanges
291 % In the original code a pre-existing file would not be overwritten.
292 % In the new version the file existence check is used solely to decide
293 % whether to output ``\texttt{Writing file `\textrm{\meta{filename}}'}''
294 % or ``\texttt{Overwriting file `\textrm{\meta{filename}}'}''. Control
295 % flow then always falls through to what used to be the |\ifeof| case
296 % (file does not exist; open it), never the |\else| case (file already
297 % exists; do nothing).
298 % \changes{v1.2}{2009/03/17}{Added percent signs after the
299 % \texttt{\char`\\else} and \texttt{\char`\\fi}
300 % lines as per Heiko Oberdiek's suggestion for getting \textsf{filecontents}
301 % to work with the \textsf{guitar} package}
302 % \changes{v1.3}{2011/10/08}{Added a \texttt{\char`\\closein} to fix bug
303 % \textsf{latex/1487} (reported by Ulrike Fischer and Heiko Oberdiek)}
304 % \begin{macrocode}
305 \ifeof\@inputcheck%
306 \@latex@warning@no@line%
307 {Writing file `\@currdir#1'}%
308 \else %
309 \@latex@warning@no@line%
310 {Overwriting file `\@currdir#1'}%
311 \fi %
312 \closein\@inputcheck %
313 % \end{macrocode}
314 % \begin{macrocode}
315 \chardef\reserved@c15 %
316 \ch@ck7\reserved@c\write%
317 \immediate\openout\reserved@c#1\relax%
318 % \end{macrocode}
319 % \stopfcchanges
320 %
321 % \begin{macrocode}
322 \if@tempswa%
323 \immediate\write\reserved@c{%
324 \@percentchar\@percentchar\space%
325 \expandafter\@gobble\string\LaTeX2e file `#1'^^J%
326 \@percentchar\@percentchar\space generated by the %
327 `\@currenvir' \expandafter\@gobblefour\string\newenvironment^^J%
328 \@percentchar\@percentchar\space from source `\jobname' on %
329 \number\year/\two@digits\month/\two@digits\day.^^J%
330 \@percentchar\@percentchar}%
331 \fi%
332 \let\do\@makeother\dospecials%
333 % \end{macrocode}
334 % \startfcchanges
335 % The \textsf{inputenc} packages might have marked some of the upper~128
336 % character codes ``active'' (category code~13). That confuses
337 % \textsf{filecontents}. Hence, we locally mark each of the upper~128
338 % character codes as ``letter'' (category code~11) so that they can be
339 % written correctly to a file.
340 % \changes{v1.1}{2004/08/16}{Made it possible for \textsf{filecontents}
341 % to write \mbox{Latin-1} characters as per Harry Schmidt's feature
342 % request and Frank Mittelbach's suggestion of how to implement it.}
343 % \changes{v1.2}{2009/03/17}{Added percent signs after each line in
344 % the loop as per Heiko Oberdiek's suggestion for getting
345 % \textsf{filecontents} to work with the \textsf{guitar} package}
346 % \begin{macrocode}
347 \count0=128\relax %
348 \loop %
349 \catcode\count0=11\relax %
350 \advance\count0 by 1\relax %
351 \ifnum\count0<256 %
352 \repeat %
353 % \end{macrocode}
354 % \stopfcchanges
355 %
356 % \begin{macrocode}
357 \edef\E{\@backslashchar end\string{\@currenvir\string}}%
358 \edef\reserved@b{%
359 \def\noexpand\reserved@b%
360 ####1\E####2\E####3\relax}%
361 \reserved@b{%
362 \ifx\relax##3\relax%
363 % \end{macrocode}
364 % There was no |\end{filecontents}|
365 % \begin{macrocode}
366 \immediate\write\reserved@c{##1}%
367 \else%
368 % \end{macrocode}
369 % There was a |\end{filecontents}|, so stop this time.
370 % \begin{macrocode}
371 \edef^^M{\noexpand\end{\@currenvir}}%
372 \ifx\relax##1\relax%
373 \else%
374 % \end{macrocode}
375 % Text before the |\end|, write it with a warning.
376 % \begin{macrocode}
377 \@latex@warning{Writing text `##1' before %
378 \string\end{\@currenvir}\MessageBreak as last line of #1}%
379 \immediate\write\reserved@c{##1}%
380 \fi%
381 \ifx\relax##2\relax%
382 \else%
383 % \end{macrocode}
384 % Text after the |\end|, ignore it with a warning.
385 % \begin{macrocode}
386 \@latex@warning{%
387 Ignoring text `##2' after \string\end{\@currenvir}}%
388 \fi%
389 \fi%
390 ^^M}%
391 % \end{macrocode}
392 %
393 % \changes{v1.4}{2018/05/30}{Update definitions of
394 % \string\texttt{\string\^{}\string\^{}L} and
395 % \string\texttt{\string\^{}\string\^{}I} for compatibility with the
396 % 2018-04-01 \string\LaTeX\ release}
397 % \begin{macrocode}
398 \catcode`\^^L\active%
399 \let\L\@undefined%
400 \def^^L{\expandafter\ifx\csname L\endcsname\relax\fi ^^J^^J}%
401 \catcode`\^^I\active%
402 \let\I\@undefined%
403 \def^^I{\expandafter\ifx\csname I\endcsname\relax\fi\space}%
404 \catcode`\^^M\active%
405 \edef^^M##1^^M{%
406 \noexpand\reserved@b##1\E\E\relax}}%
407 \endgroup
408 % \end{macrocode}
409 % \end{macro}
410 %
411 % \begin{macro}{\fc@no@preamblecmds}
412 % \LaTeXe\ declares |\filecontents|, |\filecontents*|, and all of the
413 % related helper macros as |\@onlypreamble|, meaning they become invalid
414 % after the |\begin{document}|. The following code re-enables their
415 % usage anywhere in the document. It was taken from the
416 % \textsf{pkgindoc} package (which is generated from |ltclass.dtx|), but
417 % modified to re-enable only the commands needed by
418 % \textsf{filecontents}, not all of the class and package
419 % option-processing commands, as well.
420 % \begin{macrocode}
421 \def\fc@no@preamblecmds#1\do\filecontents#2\do\filec@ntents#3\relax{%
422 \gdef\@preamblecmds{#1#3}}
423 % \end{macrocode}
424 % \end{macro}
425 %
426 % Newer \LaTeX\ kernels define a most sophisticated |filecontents|
427 % environment than what this package provides. We currently use the
428 % existence of |\filec@ntents@opt| as indication that the new
429 % |filecontents| environment is available.
430 % \changes{v1.5}{2019/09/20}{Declare the package obsolete when running
431 % under newer \LaTeX\ kernels}
432 % \begin{macrocode}
433 \@ifundefined{filec@ntents@opt}{%
434 % \end{macrocode}
435 % Older kernel: Install this package's version of the |filecontents|
436 % environment.
437 % \begin{macrocode}
438 \let\filec@ntents=\filec@ntents@old@kernel
439 \expandafter\fc@no@preamblecmds\@preamblecmds\relax
440 }{%
441 % \end{macrocode}
442 % Newer kernel: Issue a warning and do not install this package's
443 % version of |filecontents|.
444 % \begin{macrocode}
445 \PackageWarningNoLine{filecontents}{%
446 This package is obsolete. Disabling it and\MessageBreak
447 passing control to the filecontents environment\MessageBreak
448 defined by the LaTeX kernel%
449 }%
450 }
451 % \end{macrocode}
452 %
453 % \begin{macrocode}
454 %</package>
455 % \end{macrocode}
456 %
457 % \Finale
458 %