% \iffalse meta-comment
%
% Copyright (C) 2001-2023 Scott Pakin <scott+fc@pakin.org>
% --------------------------------------------------------
%
% This package may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
%
% http://www.latex-project.org/lppl.txt
%
% and version 1.3c or later is part of all distributions of LaTeX
% version 2008/05/04 or later.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{filecontents.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{filecontents}
%<*package>
[2023/04/02 v1.5a Create an external file from within a LaTeX document]
%</package>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{color}
\usepackage{microtype}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
\DocInput{filecontents.dtx}
\end{document}
%</driver>
% \fi
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% \CheckSum{191}
%
% \CharacterTable
% {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
% 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
% Digits \0\1\2\3\4\5\6\7\8\9
% Exclamation \! Double quote \" Hash (number) \#
% Dollar \$ Percent \% Ampersand \&
% Acute accent \' Left paren \( Right paren \)
% Asterisk \* Plus \+ Comma \,
% Minus \- Point \. Solidus \/
% Colon \: Semicolon \; Less than \<
% Equals \= Greater than \> Question mark \?
% Commercial at \@ Left bracket \[ Backslash \\
% Right bracket \] Circumflex \^ Underscore \_
% Grave accent \` Left brace \{ Vertical bar \|
% Right brace \} Tilde \~}
%
% \GetFileInfo{filecontents.dtx}
%
% \title{The \textsf{filecontents} package\thanks{This file
% has version number \fileversion, last
% revised \filedate.}}
% \author{Scott Pakin \\ \textit{scott+fc@pakin.org}}
% \maketitle
%
% \changes{v1.0}{2001/07/31}{Initial version}
% \changes{v1.1a}{2006/03/11}{%
% Clarified/corrected the \texttt{\string\string\string\documentclass}
% restriction as per Robin Fairbairns's suggestion}
% \changes{v1.5a}{2023/04/02}{Documentation updates; no code changes}
%
% ^^A The following were copied verbatim from source2e.tex.
% \DoNotIndex{\def,\long,\edef,\xdef,\gdef,\let,\global}
% \DoNotIndex{\if,\ifnum,\ifdim,\ifcat,\ifmmode,\ifvmode,\ifhmode,%
% \iftrue,\iffalse,\ifvoid,\ifx,\ifeof,\ifcase,\else,\or,\fi}
% \DoNotIndex{\box,\copy,\setbox,\unvbox,\unhbox,\hbox,%
% \vbox,\vtop,\vcenter}
% \DoNotIndex{\@empty,\immediate,\write}
% \DoNotIndex{\egroup,\bgroup,\expandafter,\begingroup,\endgroup}
% \DoNotIndex{\divide,\advance,\multiply,\count,\dimen}
% \DoNotIndex{\relax,\space,\string}
% \DoNotIndex{\csname,\endcsname,\@spaces,\openin,\openout,%
% \closein,\closeout}
% \DoNotIndex{\catcode,\endinput}
% \DoNotIndex{\jobname,\message,\read,\the,\m@ne,\noexpand}
% \DoNotIndex{\hsize,\vsize,\hskip,\vskip,\kern,\hfil,\hfill,\hss}
% \DoNotIndex{\m@ne,\z@,\z@skip,\@ne,\tw@,\p@}
% \DoNotIndex{\dp,\wd,\ht,\vss,\unskip}
%
% ^^A The following are specific to filecontents.dtx.
% \DoNotIndex{\@currenvir,\@gobble,\@gobblefour,\@ifundefined,\@makeother}
% \DoNotIndex{\@undefined,\active,\chardef,\day,\do,\dospecials,\E,\end,\I}
% \DoNotIndex{\if@tempswa,\L,\LaTeX,\loop,\MessageBreak,\month}
% \DoNotIndex{\newenvironment,\number,\repeat,\reserved@b,\reserved@c}
% \DoNotIndex{\two@digits,\year,\*,\^}
%
% ^^A Define some commands to help delineate my changes.
% \newcommand{\startfcchanges}{^^A
% \centerline{^^A
% \makebox[0pt]{^^A
% \raisebox{-2\baselineskip}[0pt][0pt]{^^A
% \makebox[0pt][l]{\rule{1pt}{2\baselineskip}}}^^A
% \rule{1em}{1pt}^^A
% \rule{\linewidth}{1pt}^^A
% \rule{1em}{1pt}^^A
% \raisebox{-2\baselineskip}[0pt][0pt]{^^A
% \makebox[0pt][r]{\rule{1pt}{2\baselineskip}}}^^A
% }^^A
% }^^A
% \noindent
% }
% \newcommand{\stopfcchanges}{^^A
% \centerline{^^A
% \makebox[0pt]{^^A
% \raisebox{0pt}[0pt][0pt]{^^A
% \makebox[0pt][l]{\rule{1pt}{2\baselineskip}}}^^A
% \rule{1em}{1pt}^^A
% \rule{\linewidth}{1pt}^^A
% \rule{1em}{1pt}^^A
% \raisebox{0pt}[0pt][0pt]{^^A
% \makebox[0pt][r]{\rule{1pt}{2\baselineskip}}}^^A
% }^^A
% }^^A
% }
%
% \newsavebox{\obsoletenotice}
% \begin{lrbox}{\obsoletenotice}
% \begin{minipage}[t]{0.75\linewidth}
% \color{red}
% \centerline{\textsc{Notice}}
% \smallskip
% The version of \LaTeX\ released in Fall 2019 incorporates all of
% this package's functionality (and more) into the \LaTeX\ kernel
% itself. As a result, there is no longer a need for the
% |filecontents| package. Please use instead the new, built-in
% |filecontents| environment. Supply the |overwrite| option to
% mimic this package's behavior:
%
% \bigskip
% \quad
% \begin{tabular}[t]{@{}l@{}}
% |\begin{filecontents}[overwrite]{|\meta{filename}|}| \\
% \multicolumn{1}{@{}c@{}}{$\vdots$} \\
% |\end{filecontents}|
% \end{tabular}
% \bigskip
%
% See
% \href{https://www.latex-project.org/news/latex2e-news/ltnews30.pdf}{^^A
% \LaTeXe\ News, Issue 30} (1-Oct-2019) for the announcement of the
% new kernel functionality.
% \end{minipage}
% \end{lrbox}
%
% \begin{center}
% \color{red}
% \fbox{\usebox{\obsoletenotice}}
% \end{center}
%
%
% \section{Introduction}
%
% \DescribeEnv{filecontents}
% There is a little-known environment called |filecontents| that is
% built into \LaTeXe. Here is |filecontents|' description, which was
% taken from |ltclass.dtx|:
%
% \begin{quotation}
% 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.
% \end{quotation}
%
% \noindent
% (The comment about |filecontents| being valid only before
% |\documentclass| is, in fact, untrue. |filecontents| is allowed
% anywhere in the document's preamble.)
%
% \bigskip
%
% The \textsf{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 (really, the |\begin{document}|).
% \textsf{filecontents} is therefore a more convenient way to write
% external files from within a \LaTeX\ document than is provided by
% default by the \LaTeXe\ kernel.
%
%
% \paragraph{Sample usage}
% |filecontents| works much like |verbatim|, except that it takes
% a mandatory filename argument:
%
% \begin{verbatim}
% \begin{filecontents}{myfile.tex}
% This text gets written to \texttt{myfile.tex}.
% \end{filecontents}
% \end{verbatim}
%
% \noindent
% The preceding code will write a |myfile.tex| file with contents resembling
% the following:
%
% \begin{verbatim}
% %% LaTeX2e file `myfile.tex'
% %% generated by the `filecontents' environment
% %% from source `mydocument' on 2001/07/31.
% %%
% This text gets written to \texttt{myfile.tex}.
% \end{verbatim}
%
% \noindent
% |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
% ``\texttt{This text gets written to} \verb"\texttt{myfile.tex}."'' line.
% |filecontents*| is therefore useful for writing non-\LaTeX\ files such as
% Encapsulated PostScript files.
%
% If you use the \textsf{ltxtable} package you may find
% \textsf{filecontents} particularly useful. \textsf{ltxtable} is a
% crude conglomeration of \textsf{longtable}, which allows tables to
% cross page boundaries, and \textsf{tabularx}, which enables tables to
% stretch to a specified width. \textsf{ltxtable}'s interface is a bit
% cumbersome, however; it requires that the |longtable| environment be
% contained in a separate file. With the \textsf{filecontents} package
% you can create this file right before the |\LTXtable| invocation---a
% far more convenient alternative than having to manually place the
% table within a separate file.
%
%
% \StopEventually{^^A
% \PrintChanges
% \clearpage
% \PrintIndex
% }
%
% \section{Implementation}
%
% Most users can stop reading at this point. The Implementation section
% contains the annotated source code for the \textsf{filecontents}
% package itself, which is useful only to people who want a detailed and
% precise explanation of how \textsf{filecontents} works.
%
% To give credit where credit is due, I wrote virtually none of the
% \textsf{filecontents} code myself. It comes almost exclusively from
% the \LaTeXe\ 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.
%
% \begin{macrocode}
%<*package>
% \end{macrocode}
%
% \begin{macro}{\filec@ntents@old@kernel}
% Except where indicated, the source---including comments---to the
% |\filec@ntents| macro---was taken verbatim from |ltclass.dtx|.
% \begin{macrocode}
\begingroup%
\catcode`\*=11 %
\catcode`\^^M\active%
\catcode`\^^L\active\let^^L\relax%
\catcode`\^^I\active%
% \end{macrocode}
%
% \begin{macrocode}
\gdef\filec@ntents@old@kernel#1{%
\openin\@inputcheck#1 %
% \end{macrocode}
%
% \startfcchanges
% 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 ``\texttt{Writing file `\textrm{\meta{filename}}'}''
% or ``\texttt{Overwriting file `\textrm{\meta{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).
% \changes{v1.2}{2009/03/17}{Added percent signs after the
% \texttt{\char`\\else} and \texttt{\char`\\fi}
% lines as per Heiko Oberdiek's suggestion for getting \textsf{filecontents}
% to work with the \textsf{guitar} package}
% \changes{v1.3}{2011/10/08}{Added a \texttt{\char`\\closein} to fix bug
% \textsf{latex/1487} (reported by Ulrike Fischer and Heiko Oberdiek)}
% \begin{macrocode}
\ifeof\@inputcheck%
\@latex@warning@no@line%
{Writing file `\@currdir#1'}%
\else %
\@latex@warning@no@line%
{Overwriting file `\@currdir#1'}%
\fi %
\closein\@inputcheck %
% \end{macrocode}
% \begin{macrocode}
\chardef\reserved@c15 %
\ch@ck7\reserved@c\write%
\immediate\openout\reserved@c#1\relax%
% \end{macrocode}
% \stopfcchanges
%
% \begin{macrocode}
\if@tempswa%
\immediate\write\reserved@c{%
\@percentchar\@percentchar\space%
\expandafter\@gobble\string\LaTeX2e file `#1'^^J%
\@percentchar\@percentchar\space generated by the %
`\@currenvir' \expandafter\@gobblefour\string\newenvironment^^J%
\@percentchar\@percentchar\space from source `\jobname' on %
\number\year/\two@digits\month/\two@digits\day.^^J%
\@percentchar\@percentchar}%
\fi%
\let\do\@makeother\dospecials%
% \end{macrocode}
% \startfcchanges
% The \textsf{inputenc} packages might have marked some of the upper~128
% character codes ``active'' (category code~13). That confuses
% \textsf{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.
% \changes{v1.1}{2004/08/16}{Made it possible for \textsf{filecontents}
% to write \mbox{Latin-1} characters as per Harry Schmidt's feature
% request and Frank Mittelbach's suggestion of how to implement it.}
% \changes{v1.2}{2009/03/17}{Added percent signs after each line in
% the loop as per Heiko Oberdiek's suggestion for getting
% \textsf{filecontents} to work with the \textsf{guitar} package}
% \begin{macrocode}
\count0=128\relax %
\loop %
\catcode\count0=11\relax %
\advance\count0 by 1\relax %
\ifnum\count0<256 %
\repeat %
% \end{macrocode}
% \stopfcchanges
%
% \begin{macrocode}
\edef\E{\@backslashchar end\string{\@currenvir\string}}%
\edef\reserved@b{%
\def\noexpand\reserved@b%
####1\E####2\E####3\relax}%
\reserved@b{%
\ifx\relax##3\relax%
% \end{macrocode}
% There was no |\end{filecontents}|
% \begin{macrocode}
\immediate\write\reserved@c{##1}%
\else%
% \end{macrocode}
% There was a |\end{filecontents}|, so stop this time.
% \begin{macrocode}
\edef^^M{\noexpand\end{\@currenvir}}%
\ifx\relax##1\relax%
\else%
% \end{macrocode}
% Text before the |\end|, write it with a warning.
% \begin{macrocode}
\@latex@warning{Writing text `##1' before %
\string\end{\@currenvir}\MessageBreak as last line of #1}%
\immediate\write\reserved@c{##1}%
\fi%
\ifx\relax##2\relax%
\else%
% \end{macrocode}
% Text after the |\end|, ignore it with a warning.
% \begin{macrocode}
\@latex@warning{%
Ignoring text `##2' after \string\end{\@currenvir}}%
\fi%
\fi%
^^M}%
% \end{macrocode}
%
% \changes{v1.4}{2018/05/30}{Update definitions of
% \string\texttt{\string\^{}\string\^{}L} and
% \string\texttt{\string\^{}\string\^{}I} for compatibility with the
% 2018-04-01 \string\LaTeX\ release}
% \begin{macrocode}
\catcode`\^^L\active%
\let\L\@undefined%
\def^^L{\expandafter\ifx\csname L\endcsname\relax\fi ^^J^^J}%
\catcode`\^^I\active%
\let\I\@undefined%
\def^^I{\expandafter\ifx\csname I\endcsname\relax\fi\space}%
\catcode`\^^M\active%
\edef^^M##1^^M{%
\noexpand\reserved@b##1\E\E\relax}}%
\endgroup
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\fc@no@preamblecmds}
% \LaTeXe\ 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
% \textsf{pkgindoc} package (which is generated from |ltclass.dtx|), but
% modified to re-enable only the commands needed by
% \textsf{filecontents}, not all of the class and package
% option-processing commands, as well.
% \begin{macrocode}
\def\fc@no@preamblecmds#1\do\filecontents#2\do\filec@ntents#3\relax{%
\gdef\@preamblecmds{#1#3}}
% \end{macrocode}
% \end{macro}
%
% Newer \LaTeX\ kernels define a most sophisticated |filecontents|
% environment than what this package provides. We currently use the
% existence of |\filec@ntents@opt| as indication that the new
% |filecontents| environment is available.
% \changes{v1.5}{2019/09/20}{Declare the package obsolete when running
% under newer \LaTeX\ kernels}
% \begin{macrocode}
\@ifundefined{filec@ntents@opt}{%
% \end{macrocode}
% Older kernel: Install this package's version of the |filecontents|
% environment.
% \begin{macrocode}
\let\filec@ntents=\filec@ntents@old@kernel
\expandafter\fc@no@preamblecmds\@preamblecmds\relax
}{%
% \end{macrocode}
% Newer kernel: Issue a warning and do not install this package's
% version of |filecontents|.
% \begin{macrocode}
\PackageWarningNoLine{filecontents}{%
This package is obsolete. Disabling it and\MessageBreak
passing control to the filecontents environment\MessageBreak
defined by the LaTeX kernel%
}%
}
% \end{macrocode}
%
% \begin{macrocode}
%</package>
% \end{macrocode}
%
% \Finale
%