summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/filecontents
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/filecontents
Initial commit
Diffstat (limited to 'macros/latex/contrib/filecontents')
-rw-r--r--macros/latex/contrib/filecontents/README49
-rw-r--r--macros/latex/contrib/filecontents/filecontents.dtx395
-rw-r--r--macros/latex/contrib/filecontents/filecontents.ins62
-rw-r--r--macros/latex/contrib/filecontents/filecontents.pdfbin0 -> 122585 bytes
4 files changed, 506 insertions, 0 deletions
diff --git a/macros/latex/contrib/filecontents/README b/macros/latex/contrib/filecontents/README
new file mode 100644
index 0000000000..4c62bef626
--- /dev/null
+++ b/macros/latex/contrib/filecontents/README
@@ -0,0 +1,49 @@
+ +--------------------------------------------+
+ | FILECONTENTS |
+ | |
+ | Improved version of LaTeX2e's filecontents |
+ | and filecontents* environments |
+ | |
+ | By Scott Pakin, scott+fc@pakin.org |
+ +--------------------------------------------+
+
+
+Description
+-----------
+
+LaTeX2e's filecontents and filecontents* environments enable a LaTeX
+source file to generate external files as it's run through latex.
+However, there are two limitations of these environments: They refuse
+to overwrite existing files; and, they can be used only before the
+\documentclass declaration. The filecontents package removes these
+limitations, making it possible to overwrite existing files and to use
+filecontents/filecontents* anywhere.
+
+
+Installation
+------------
+
+There's nothing special about building filecontents:
+
+ latex filecontents.ins <== Generate filecontents.sty
+ latex filecontents.dtx <== Produce the documentation (filecontents.dvi)
+
+If you're new to this, see
+http://www.tex.ac.uk/cgi-bin/texfaq2html?label=instpackages for more
+information on installing packages.
+
+
+Copyright and license
+---------------------
+
+Copyright (C) 2018 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.
diff --git a/macros/latex/contrib/filecontents/filecontents.dtx b/macros/latex/contrib/filecontents/filecontents.dtx
new file mode 100644
index 0000000000..0fc96c45a1
--- /dev/null
+++ b/macros/latex/contrib/filecontents/filecontents.dtx
@@ -0,0 +1,395 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2018 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>
+ [2018/05/30 v1.4 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{184}
+%
+% \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}
+%
+% ^^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
+% }
+%
+%
+% \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
+% \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).
+% \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}}
+\expandafter\fc@no@preamblecmds\@preamblecmds\relax
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+%
+% \Finale
+%
diff --git a/macros/latex/contrib/filecontents/filecontents.ins b/macros/latex/contrib/filecontents/filecontents.ins
new file mode 100644
index 0000000000..6471069dcf
--- /dev/null
+++ b/macros/latex/contrib/filecontents/filecontents.ins
@@ -0,0 +1,62 @@
+%%
+%% 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) 2018 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.
+%%
+%% --------------- start of docstrip commands ------------------
+%%
+\input docstrip
+
+\keepsilent
+
+\usedir{tex/latex/filecontents}
+
+\preamble
+
+This is a generated file.
+
+Copyright (C) 2018 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.
+
+\endpreamble
+
+\generate{\file{filecontents.sty}{\from{filecontents.dtx}{package}}}
+
+
+\obeyspaces
+\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{* *}
+\Msg{***********************************************************}
+
+\endbatchfile
diff --git a/macros/latex/contrib/filecontents/filecontents.pdf b/macros/latex/contrib/filecontents/filecontents.pdf
new file mode 100644
index 0000000000..a2340ef345
--- /dev/null
+++ b/macros/latex/contrib/filecontents/filecontents.pdf
Binary files differ