summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/filecontents
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-11 23:53:18 +0000
committerKarl Berry <karl@freefriends.org>2006-01-11 23:53:18 +0000
commita3a531f158fb3386da51e20b772ac50332d8513f (patch)
tree9cc67b572b5460c835020eae12bc3a51f6552632 /Master/texmf-dist/source/latex/filecontents
parent1cd38ebf8864da966b4f3e68cbc1137dc9c8962d (diff)
trunk/Master/texmf-dist/source/latex/filecontents
git-svn-id: svn://tug.org/texlive/trunk@282 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/filecontents')
-rw-r--r--Master/texmf-dist/source/latex/filecontents/filecontents.dtx368
-rw-r--r--Master/texmf-dist/source/latex/filecontents/filecontents.ins56
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