trunk/Master/texmf-dist/source/latex/filecontents

git-svn-id: svn://tug.org/texlive/trunk@282 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 424 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/filecontents/filecontents.dtx b/Master/texmf-dist/source/latex/filecontents/filecontents.dtx
new file mode 100644
index 00000000000..730a9615d3c
--- /dev/null
+++ b/Master/texmf-dist/source/latex/filecontents/filecontents.dtx
@@ -0,0 +1,368 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2004 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.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
+%<*driver>
+\ProvidesFile{filecontents.dtx}
+%</driver>
+%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+%<package>\ProvidesPackage{filecontents}
+%<*package>
+    [2004/08/16 v1.1 Create an external file from within a LaTeX document]
+%</package>
+%
+%<*driver>
+\documentclass{ltxdoc}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\begin{document}
+\DocInput{filecontents.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% \CheckSum{173}
+%
+% \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\\scott+fc@pakin.org}
+% \maketitle
+%
+% \changes{v1.0}{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 are specific to filecontents.dtx.
+% \DoNotIndex{\@currenvir,\@gobble,\@gobblefour,\@ifundefined,\@makeother}
+% \DoNotIndex{\@undefined,\day,\do,\E,\end,\I,\if@tempswa,\L,\LaTeX,\loop}
+% \DoNotIndex{\MessageBreak,\month,\newenvironment,\number,\repeat}
+% \DoNotIndex{\reserved@b,\reserved@c,\two@digits,\year}
+% \DoNotIndex{\*,\^}
+%
+% ^^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
+% }
+%
+%
+% \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*| 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.  \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,
+% which is far more convenient than having to place the table manually
+% within a separate file.
+%
+%
+% \StopEventually{^^A
+%   \PrintChanges
+%   \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}
+% 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#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).
+%    \begin{macrocode}
+  \ifeof\@inputcheck%
+    \@latex@warning@no@line%
+        {Writing file `\@currdir#1'}%
+  \else
+    \@latex@warning@no@line%
+        {Overwriting file `\@currdir#1'}%
+  \fi
+%    \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.}
+%    \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}
+%
+%    \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
+%
diff --git a/Master/texmf-dist/source/latex/filecontents/filecontents.ins b/Master/texmf-dist/source/latex/filecontents/filecontents.ins
new file mode 100644
index 00000000000..a88cd8a68d3
--- /dev/null
+++ b/Master/texmf-dist/source/latex/filecontents/filecontents.ins
@@ -0,0 +1,56 @@
+%%
+%% This file will generate fast loadable files and documentation
+%% driver files from the doc files in this package when run through
+%% LaTeX or TeX.
+%%
+%% Copyright (C) 2004 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.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.
+%%
+%% --------------- start of docstrip commands ------------------
+%%
+\input docstrip
+
+\keepsilent
+
+\usedir{tex/latex/filecontents}
+
+\preamble
+
+This is a generated file.
+
+Copyright (C) 2004 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.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.
+
+\endpreamble
+
+\generate{\file{filecontents.sty}{\from{filecontents.dtx}{package}}}
+
+
+\Msg{***********************************************************}
+\Msg{*}
+\Msg{* To finish the installation, you have to move}
+\Msg{* filecontents.sty into a directory searched by TeX.}
+\Msg{*}
+\Msg{* To produce the documentation, run filecontents.dtx}
+\Msg{* through LaTeX.}
+\Msg{*}
+\Msg{* Happy TeXing!}
+\Msg{***********************************************************}
+
+\endbatchfile