% \iffalse meta-comment
%
% Copyright (C) 2001 Scott Pakin <pakin@uiuc.edu>
% -------------------------------------------------------
%
% This package may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.2
% 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.2 or later is part of all distributions of LaTeX
% version 1999/12/01 or later.
%
% \fi
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{filecontents}
%<package>   [2001/07/31 v1.00 Create an external file from within a LaTeX document]
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{filecontents}

\EnableCrossrefs
\CodelineIndex

% Uncomment the following line if you don't want to include a
% source-code listing.
%\OnlyDescription

\begin{document}
\DocInput{filecontents.dtx}
\end{document}
%</driver>
% \fi
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% \CheckSum{161}
% \GetFileInfo{filecontents.sty}
%
% \title{The \textsf{filecontents} package\thanks{This file
%         has version number \fileversion, last
%         revised \filedate.}}
% \author{Scott Pakin\\pakin@uiuc.edu}
% \date{\filedate}
% \maketitle
%
% \changes{v1.00}{2001/07/31}{Initial version}
%
% ^^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 is specific to filecontents.dtx.
% \DoNotIndex{\*}
%
%
% \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}
%
% The \textsf{filecontents} package provides a hacked-up version of the
% |filecontents| (and |filecontents*|) environment that eliminates the
% two restrictions stated above, namely that existing files are never
% overwritten and that |filecontents| must be used before the
% |\documentclass| declaration.  \textsf{filecontents} is therefore a
% more convenient way to write external files from within a \LaTeX\
% document.
%
%
% \subsection*{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 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,
% which is far more convenient than having to place the table in a
% separate file manually.
%
%
% \StopEventually{^^A
%   \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.  All I did was delete a few things here and there
% to make the |filecontents| environment more convenient to use.
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%

% \begin{macro}{\filec@ontents}
% The following code---including comments---was taken almost verbatim from
% |ltclass.dtx|.  All I did, as indicated below, was remove the check for
% file existence.  If the file already exists, it is overwritten.
%    \begin{macrocode}
\begingroup%
\catcode`\*=11 %
\catcode`\^^M\active%
\catcode`\^^L\active\let^^L\relax%
\catcode`\^^I\active%
%    \end{macrocode}
%
%    \begin{macrocode}
\gdef\filec@ntents#1{%
  \openin\@inputcheck#1 %
%    \end{macrocode}
%
% \emph{Scott Pakin's modifications}: The following is the only stanza I
% changed from |ltclass.dtx|.  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), never the
% |\else| case (file already exists).
%
%    \begin{macrocode}
  \ifeof\@inputcheck%
    \@latex@warning@no@line%
        {Writing file `\@currdir#1'}%
  \else
    \@latex@warning@no@line%
        {Overwriting file `\@currdir#1'}%
  \fi
  \chardef\reserved@c15 %
  \ch@ck7\reserved@c\write%
  \immediate\openout\reserved@c#1\relax%
  \if@tempswa%
%    \end{macrocode}
%
% \changes{v1.0y}{1997/10/10}
%         {\cs{@currenvir} in banner}
%    \begin{macrocode}
    \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}
%
% \changes{v1.0y}{1997/10/10}
%     {Check for text before or after \cs{end} environment. latex/2636}
%    \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}
%
%    \begin{macrocode}
  \catcode`\^^L\active%
  \let\L\@undefined%
  \def^^L{\@ifundefined L^^J^^J^^J}%
  \catcode`\^^I\active%
  \let\I\@undefined%
  \def^^I{\@ifundefined I\space\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}}
\expandafter\fc@no@preamblecmds\@preamblecmds\relax
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \Finale
%
