summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/filecontentsdef
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/filecontentsdef
Initial commit
Diffstat (limited to 'macros/latex/contrib/filecontentsdef')
-rw-r--r--macros/latex/contrib/filecontentsdef/INSTALL37
-rw-r--r--macros/latex/contrib/filecontentsdef/README.md71
-rw-r--r--macros/latex/contrib/filecontentsdef/filecontentsdef.dtx983
-rw-r--r--macros/latex/contrib/filecontentsdef/filecontentsdef.pdfbin0 -> 90457 bytes
4 files changed, 1091 insertions, 0 deletions
diff --git a/macros/latex/contrib/filecontentsdef/INSTALL b/macros/latex/contrib/filecontentsdef/INSTALL
new file mode 100644
index 0000000000..2657632382
--- /dev/null
+++ b/macros/latex/contrib/filecontentsdef/INSTALL
@@ -0,0 +1,37 @@
+ Source: filecontentsdef.dtx (v1.4 2019/04/20)
+ Author: Jean-Francois Burnol
+ Info: filecontents + macro + verbatim
+ License: LPPL 1.3c
+ Copyright (C) 2016-2019 Jean-Francois Burnol.
+ <jfbu at free dot fr>
+
+
+
+INSTALLATION
+
+
+Use your installation manager.
+
+Else, for manual installation:
+
+- To extract the package and at the same time produce the
+ documentation, execute latex twice on filecontentsdef.dtx then
+ dvipdfmx on the dvi file.
+
+ To customize the PDF documentation (paper size, etc...): execute
+ etex once on filecontentsdef.dtx then follow instructions given
+ inside the extracted file filecontentsdef.tex.
+
+- To extract the package but not necessarily build the documentation:
+ run etex on filecontentsdef.dtx.
+
+Files should then be moved to appropriate locations:
+
+ filecontentsdef.sty -> TDS:tex/latex/filecontentsdef/
+ filecontentsdef.dtx -> TDS:source/latex/filecontentsdef/
+ filecontentsdef.pdf -> TDS:doc/latex/filecontentsdef/
+ README.md -> TDS:doc/latex/filecontentsdef/
+ INSTALL.md -> TDS:doc/latex/filecontentsdef/
+
+You can also place filecontentsdef.sty directly within the directory of
+the project using it.
diff --git a/macros/latex/contrib/filecontentsdef/README.md b/macros/latex/contrib/filecontentsdef/README.md
new file mode 100644
index 0000000000..305ecfc66d
--- /dev/null
+++ b/macros/latex/contrib/filecontentsdef/README.md
@@ -0,0 +1,71 @@
+<!-- -->
+
+ Source: filecontentsdef.dtx (v1.4 2019/04/20)
+ Author: Jean-Francois Burnol
+ Info: filecontents + macro + verbatim
+ License: LPPL 1.3c
+ Copyright (C) 2016-2019 Jean-Francois Burnol.
+ <jfbu at free dot fr>
+
+ABSTRACT
+========
+
+This lightweight LaTeX2e package provides an environment `filecontentsdef`
+which is like the `filecontents` environment of Scott Pakin's
+[filecontents] [1] package but in addition to the file creation stores the
+(verbatim) contents into a macro given as an additional argument (either as a
+control sequence or as a name).
+
+Displaying verbatim these contents is possible via `\filecontentsprint`,
+and executing them (if they represent LaTeX code) via `\filecontentsexec`.
+
+A variant environment `filecontentsdefmacro` stores the contents into a
+macro, but skips the save-to-a-file part.
+
+[1]: http://www.ctan.org/pkg/filecontents "filecontents package"
+
+CHANGE LOG
+==========
+
+v1.4 \[2019/04/20\]
+-------------------
+
+- backport 2018/04/01 LaTeX release change to filecontents environment
+ (`^^L` and `^^I` definitions).
+
+- add `filecontentsdefmacro` environment.
+
+- extend `filecontentsdef` and `filecontentsdefmacro` environments as
+ well as `\filecontentsprint` and `\filecontentsexec` macros to accept
+ indifferently either a control sequence or a name as argument.
+
+- refactor documentation, explain how to define wrapper environments.
+
+v1.2 \[2016/09/19\]
+-------------------
+
+Initial version.
+
+LICENSE
+=======
+
+This Work may be distributed and/or modified under the
+conditions of the LaTeX Project Public License 1.3c.
+This version of this license is in
+
+> <http://www.latex-project.org/lppl/lppl-1-3c.txt>
+
+and the latest version of this license is in
+
+> <http://www.latex-project.org/lppl.txt>
+
+and version 1.3 or later is part of all distributions of
+LaTeX version 2005/12/01 or later.
+
+The Author of this Work is:
+
+- Jean-Francois Burnol `<jfbu at free dot fr>`
+
+This Work consists of the main source file filecontentsdef.dtx and
+its derived files filecontentsdef.sty, filecontentsdef.pdf,
+filecontentsdef.dvi, README.md, INSTALL.md, README, INSTALL.
diff --git a/macros/latex/contrib/filecontentsdef/filecontentsdef.dtx b/macros/latex/contrib/filecontentsdef/filecontentsdef.dtx
new file mode 100644
index 0000000000..b6b722383c
--- /dev/null
+++ b/macros/latex/contrib/filecontentsdef/filecontentsdef.dtx
@@ -0,0 +1,983 @@
+% -*- coding: utf-8; time-stamp-pattern: "def\\\\dtxtimestamp{%02d-%02m-%:y at %02H:%02M:%02S %Z}" -*-
+% N.B.: this dtx file is NOT for use with \DocInput but only docstrip.
+% The latex source of the user manual isn't commented out.
+%<*none>
+\def\dtxtimestamp{21-04-2019 at 15:24:14 CEST}%
+%</none>
+%<*!readme&!install>
+%%
+%% Package: filecontentsdef
+%% Version: 1.4 (2019/04/20)
+%% License: LPPL 1.3c
+%% Copyright (C) 2016-2019 Jean-Francois Burnol <jfbu at free dot fr>
+%%
+%</!readme&!install>
+%<*none>
+\def\pkgname {filecontentsdef}
+\def\pkgdate {2019/04/20}
+\def\pkgdocdate {2019/04/21}
+\def\pkgversion {v1.4}
+\def\pkgdescription {filecontents + macro + verbatim (JFB)}
+\catcode`\^ 12 \iffalse
+%</none>
+%<*readme|install>
+<!-- -->
+
+ Source: filecontentsdef.dtx (v1.4 2019/04/20)
+ Author: Jean-Francois Burnol
+ Info: filecontents + macro + verbatim
+ License: LPPL 1.3c
+ Copyright (C) 2016-2019 Jean-Francois Burnol.
+ <jfbu at free dot fr>
+
+%</readme|install>
+%<*readme>
+ABSTRACT
+========
+
+This lightweight LaTeX2e package provides an environment `filecontentsdef`
+which is like the `filecontents` environment of Scott Pakin's
+[filecontents] [1] package but in addition to the file creation stores the
+(verbatim) contents into a macro given as an additional argument (either as a
+control sequence or as a name).
+
+Displaying verbatim these contents is possible via `\filecontentsprint`,
+and executing them (if they represent LaTeX code) via `\filecontentsexec`.
+
+A variant environment `filecontentsdefmacro` stores the contents into a
+macro, but skips the save-to-a-file part.
+
+[1]: http://www.ctan.org/pkg/filecontents "filecontents package"
+
+CHANGE LOG
+==========
+
+v1.4 \[2019/04/20\]
+-------------------
+
+- backport 2018/04/01 LaTeX release change to filecontents environment
+ (`^^L` and `^^I` definitions).
+
+- add `filecontentsdefmacro` environment.
+
+- extend `filecontentsdef` and `filecontentsdefmacro` environments as
+ well as `\filecontentsprint` and `\filecontentsexec` macros to accept
+ indifferently either a control sequence or a name as argument.
+
+- refactor documentation, explain how to define wrapper environments.
+
+v1.2 \[2016/09/19\]
+-------------------
+
+Initial version.
+
+LICENSE
+=======
+
+This Work may be distributed and/or modified under the
+conditions of the LaTeX Project Public License 1.3c.
+This version of this license is in
+
+> <http://www.latex-project.org/lppl/lppl-1-3c.txt>
+
+and the latest version of this license is in
+
+> <http://www.latex-project.org/lppl.txt>
+
+and version 1.3 or later is part of all distributions of
+LaTeX version 2005/12/01 or later.
+
+The Author of this Work is:
+
+- Jean-Francois Burnol `<jfbu at free dot fr>`
+
+This Work consists of the main source file filecontentsdef.dtx and
+its derived files filecontentsdef.sty, filecontentsdef.pdf,
+filecontentsdef.dvi, README.md, INSTALL.md, README, INSTALL.
+%</readme>
+%<*install>
+INSTALLATION
+============
+
+Use your installation manager.
+
+Else, for manual installation:
+
+- To extract the package and at the same time produce the documentation,
+ execute latex twice on `filecontentsdef.dtx` then `dvipdfmx` on the
+ `dvi` file.
+
+ To customize the PDF documentation (paper size, etc...): execute `etex`
+ once on `filecontentsdef.dtx` then follow instructions given inside the
+ extracted file `filecontentsdef.tex`.
+
+- To extract the package but not necessarily build the documentation:
+ run `etex` on `filecontentsdef.dtx`.
+
+Files should then be moved to appropriate locations:
+
+ filecontentsdef.sty -> TDS:tex/latex/filecontentsdef/
+ filecontentsdef.dtx -> TDS:source/latex/filecontentsdef/
+ filecontentsdef.pdf -> TDS:doc/latex/filecontentsdef/
+ README.md -> TDS:doc/latex/filecontentsdef/
+ INSTALL.md -> TDS:doc/latex/filecontentsdef/
+
+You can also place `filecontentsdef.sty` directly within the directory
+of the project using it.
+%</install>
+%<*tex>-------------------------------------------------------------------------
+\chardef\Withdvipdfmx 1 % replace 1 by 0 for using pdflatex
+\chardef\NoSourceCode 0 % replace 0 by 1 for the doc *without* the source code
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesFile {filecontentsdef.tex}[Driver for filecontentsdef documentation]%
+\PassOptionsToClass {a4paper,fontsize=11pt,oneside}{scrdoc}
+\PassOptionsToPackage {english}{babel}
+\input filecontentsdef.dtx
+%%% Local Variables:
+%%% mode: latex
+%%% End:
+%</tex>-------------------------------------------------------------------------
+%<*none>------------------------------------------------------------------------
+\fi\catcode`\^ 7
+%
+\chardef\noetex 0
+\ifx\numexpr\undefined\chardef\noetex 1 \fi
+\ifnum\noetex=1 \chardef\extractfiles 0 % extract files, then stop
+\else
+ \ifx\ProvidesFile\undefined
+ \chardef\extractfiles 0 % etex etc.. on dtx, only file extraction.
+ \else % latex/pdflatex
+ \ifx\Withdvipdfmx\undefined
+ % latex/pdflatex on dtx
+ \chardef\extractfiles 1 % 1 = extract files and typeset manual, 2 = only typeset
+ \chardef\Withdvipdfmx 1 % 0 = pdflatex or latex+dvips, 1 = dvipdfmx
+ \chardef\NoSourceCode 0 % 0 = include source code, 1 = do not
+ \NeedsTeXFormat {LaTeX2e}%
+ \PassOptionsToClass {a4paper,fontsize=11pt,oneside}{scrdoc}%
+ \PassOptionsToPackage {english}{babel}%
+ \else % latex on tex
+ \chardef\extractfiles 2 % do not extract files, only typeset
+ \fi
+ \ProvidesFile{\pkgname.dtx}%
+ [\pkgname\space source and documentation (\dtxtimestamp)]%
+ \fi
+\fi
+\ifnum\extractfiles<2 % extract files
+\def\MessageDeFin{\newlinechar10 \let\Msg\message
+\Msg{********************************************************************^^J}%
+\Msg{*^^J}%
+\Msg{* To finish the installation you have to move the following^^J}%
+\Msg{* file into a directory searched by TeX:^^J}%
+\Msg{*^^J}%
+\Msg{*\space\space\space\space \pkgname.sty^^J}%
+\Msg{*^^J}%
+\Msg{* To produce the documentation with source code included run latex^^J}%
+\Msg{* twice on file \pkgname.tex and then dvipdfmx on \pkgname.dvi^^J}%
+\Msg{*^^J}%
+\Msg{* Happy TeXing!^^J}%
+\Msg{*^^J}%
+\Msg{********************************************************************^^J}%
+}%
+\begingroup
+ \input docstrip.tex
+ \askforoverwritefalse
+ \def\pkgpreamble{\defaultpreamble^^J\MetaPrefix^^J%
+ \string\NeedsTeXFormat{LaTeX2e}^^J%
+ \string\ProvidesPackage{\pkgname}^^J%
+ \space[\pkgdate\space\pkgversion\space\pkgdescription]}%
+ \generate{\nopreamble\nopostamble
+ \file{README.md}{\from{\pkgname.dtx}{readme}}%
+ \file{INSTALL.md}{\from{\pkgname.dtx}{install}}%
+ \usepostamble\defaultpostamble
+ \file{\pkgname.tex}{\from{\pkgname.dtx}{tex}}%
+ \usepreamble\pkgpreamble
+ \file{\pkgname.sty}{\from{\pkgname.dtx}{package}}}%
+\endgroup
+\fi % end of file extraction (from etex/latex/pdflatex run)
+\ifnum\extractfiles=0 % tex/etex/xetex/etc files extracted, stop
+ \MessageDeFin\expandafter\end
+\fi
+% From this point on, run is necessarily with e-TeX.
+% Check if \MessageDeFin got defined, if yes put it at end of run.
+\ifdefined\MessageDeFin\AtEndDocument{\MessageDeFin}\fi
+%-------------------------------------------------------------------------------
+% START OF USER MANUAL TEX SOURCE
+\documentclass[abstract]{scrdoc}
+
+\ifnum\NoSourceCode=1 \OnlyDescription\fi
+
+\usepackage{ifpdf}
+\ifpdf\chardef\Withdvipdfmx 0 \fi
+
+\makeatletter
+\ifnum\Withdvipdfmx=1
+ \@for\@tempa:=hyperref,bookmark,graphicx,xcolor,pict2e\do
+ {\PassOptionsToPackage{dvipdfmx}\@tempa}
+ %
+ \PassOptionsToPackage{dvipdfm}{geometry}
+ \PassOptionsToPackage{bookmarks=true}{hyperref}
+ \PassOptionsToPackage{dvipdfmx-outline-open}{hyperref}
+ \PassOptionsToPackage{dvipdfmx-outline-open}{bookmark}
+ %
+ \def\pgfsysdriver{pgfsys-dvipdfm.def}
+\else
+ \PassOptionsToPackage{bookmarks=true}{hyperref}
+\fi
+ \let\original@check@percent\check@percent
+ \let\check@percent\relax
+\makeatother
+
+\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
+\usepackage[hscale=0.66,vscale=0.75]{geometry}
+\pagestyle{headings}
+
+\def\MacroFont{\ttfamily\small\hyphenchar\font45 \baselineskip11pt\relax}
+\AtBeginDocument{\def\MacroFont{\ttfamily}}
+
+% ATTENTION: (avec doc.sty ou les classes scrdoc ou ltxdoc)
+%
+% - l'environnement macrocode se fait avec \macro@font qui est le
+% \MacroFont du \begin{document}.
+%
+% - les environnements verbatim utilisent le \MacroFont courant.
+%
+% - \verb utilise un \ttfamily !! et non pas \verbatim@font que l'on
+% peut customiser.
+%
+% - (9 mars 2015) il ne faut PAS commencer des macrocode directement après
+% un \section, il faut un paragraphe (par exemple un \indent\par)
+
+\usepackage{xspace}
+\usepackage[dvipsnames]{xcolor}
+
+\definecolor{joli}{RGB}{225,95,0}
+\definecolor{JOLI}{RGB}{225,95,0}
+
+\newcommand\fcdname{%
+ \texorpdfstring{{\color{joli}\ttfamily\bfseries \pkgname}}{\pkgname}\xspace}
+
+\DeclareRobustCommand\csa [1] {{\ttfamily\hyphenchar\font45 \char`\\ #1}}
+
+\newcommand\csh[1]{\texorpdfstring{\csa{#1}}{\textbackslash\detokenize{#1}}}
+
+\usepackage{babel}
+
+\usepackage[pdfencoding=pdfdoc]{hyperref}
+\hypersetup{%
+linktoc=all,%
+%% bookmarksdepth=3,%
+breaklinks=true,%
+colorlinks,%
+linkcolor=OliveGreen,%RoyalBlue,%
+urlcolor=RoyalBlue,%OliveGreen,%
+pdfauthor={Jean-Fran\c cois Burnol},%
+pdftitle={The \pkgname\space package},%
+pdfsubject={\pkgdescription},%
+pdfkeywords={LaTeX, verbatim, macros},%
+pdfstartview=FitH,%
+pdfpagemode=UseOutlines}
+\usepackage{bookmark}
+
+\usepackage[zerostyle=a,scaled=0.95,straightquotes]{newtxtt}
+\renewcommand\familydefault\sfdefault
+\frenchspacing
+
+\usepackage{framed}
+
+%\usepackage{varioref}
+
+%\usepackage{footnotehyper}
+
+\usepackage{filecontentsdef}
+
+\makeatletter
+% Revert change to \smash and other macros at LaTeX 2018/12/01
+% https://github.com/latex3/latex2e/issues/108
+\let\leavevmode@ifvmode\empty % for \smash in \NewWith etc...
+\newcommand\inmarg [1]{\@bsphack
+ \vadjust{\vskip-\dp\strutbox
+ \smash{\hbox to 0pt
+ {\color[named]{PineGreen}\normalfont\small\bfseries
+ \hsize 2.5cm\rightskip.5cm minus.5cm
+ \hyphenpenalty\z@\exhyphenpenalty\z@
+ \doublehyphendemerits\z@\baselineskip9pt
+ \hss\vtop{\noindent#1}\kern.25cm }}%
+ \vskip\dp\strutbox }\strut\@esphack}
+%! 24 février 2014. J'ai besoin de me débarrasser du \to
+\def\NewWith #1{\@bsphack
+ \vadjust{\vskip-\dp\strutbox
+ \smash{\hbox to 0pt {\hss\color[named]{Thistle}%
+ \normalfont\small\bfseries
+ \hsize 2.5cm\rightskip.5cm minus.5cm
+ \vtop{\noindent New with #1}\kern.25cm }}%
+ \vskip\dp\strutbox }\strut\@esphack}
+\makeatother
+
+\begin{document}
+\rmfamily
+\thispagestyle{empty}
+
+\bookmark[named=FirstPage,level=1]{Title page}
+
+%\ttzfamily
+
+{%
+\normalfont\Large\parindent0pt \parfillskip 0pt\relax
+ \leftskip 2cm plus 1fil \rightskip 2cm plus 1fil
+ The \fcdname package\par
+}
+
+{\centering
+ \textsc{Jean-François Burnol}\par
+ \footnotesize
+ jfbu (at) free (dot) fr\par
+ Package version: \pkgversion\ (\pkgdate);
+ documentation date: \pkgdocdate.\par
+ {From source file \texttt{\pkgname.dtx (\dtxtimestamp)}}\par
+}
+
+\begin{abstract}
+ This lightweight LaTeX2e package provides an environment
+ |filecontentsdef| which is like the |filecontents|
+ environment of \textsc{Scott Pakin}'s
+ \href{https//ctan.org/pkg/filecontents}{filecontents} package but in
+ addition to the file creation stores the (verbatim) contents into a
+ macro given as an additional argument (either as a control sequence or
+ as a name).
+
+ Displaying verbatim these contents is possible via
+ |\filecontentsprint|, and executing them (if they represent LaTeX
+ code) via |\filecontentsexec|.
+
+ A variant environment |filecontentsdefmacro| stores the contents into
+ a macro, but skips the save-to-a-file part.
+
+ I developed this to display \TeX\ code verbatim in documentation
+ and simultaneously produce during the LaTeX run the corresponding
+ files in order to embed them in the PDF as \emph{file attachment
+ annotations} (via the services of \textsc{Scott Pakin}'s
+ further package
+ \href{https://ctan.org/pkg/attachfile}{attachfile}.)
+\end{abstract}
+
+\section{Description}
+
+This package provides the |filecontentsdef|\inmarg{|file\-contents\-def|}
+environment. It is like |filecontents| but requires a second argument. This
+argument will either be:
+\begin{itemize}
+\item a single control sequence token such as |\macro|,
+\item \mbox{}\NewWith{v1.4$\to$}or anything else which then must after expansion be
+ usable as a macro \emph{name} (it will be handled via
+ |\csname...\endcsname| encapsulation).
+% Bordel, que d'emmerdements avec le LaTeX \footnote et \verb ! On ne peut même
+% pas faire \string\fi (ou \else, ou \if pas vérifié lequel des trois:
+% incomplete \ifmmode
+%\footnote{
+% Bon ben finalement pas de footnote de toute façon. Déjà fait le mark-up je laisse.
+ For example \texttt{\string\myitemnumber\{3\}} can be used as argument and
+ it will then be expanded inside \texttt{\string\csname...\string\endcsname}
+ to construct a control sequence, whose name will possibly contain digits or
+ other characters of non-letter catcodes. A single active character is
+ allowed as long as its expansion is
+ \texttt{\string\csname...\string\endcsname} compatible; the character itself
+ will \emph{not} be assigned a new meaning.
+%}
+%
+\end{itemize}
+
+Thus the syntax is either:
+\begin{verbatim}
+ \begin{filecontentsdef}{<filename>}{\macro}
+ ... arbitrary contents ...
+ \end{filecontentsdef}
+\end{verbatim}
+or:
+\begin{verbatim}
+ \begin{filecontentsdef}{<filename>}{(expanding to) macro name}
+ ... arbitrary contents ...
+ \end{filecontentsdef}
+\end{verbatim}
+
+The environment creates the file and stores its (verbatim) contents into its
+second argument |\macro| (or into the macro |\<macro name>| with given name).
+
+\begin{enumerate}
+\item The starred variant acts like |filecontents*| environment regarding the
+ file contents.
+\item The contents put into the macro are the same for the starred and
+ non-starred environments: they do not contain the commented-out header.
+\item The scope of the macro definition is global.
+\item No check is done on whether the defined macro pre-existed.
+% \item |filecontentshere| is a wrapper of the |filecontentsdef|
+% environment using \csa{filecontentsheremacro} as the macro where the
+% contents are stored.\inmarg{\csa{file\-contents\-here\-macro}} This macro
+% can then be reused elsewhere if wanted.
+\item The macro holds a verbatim rendering of the contents, which handles the
+ Form Feed and Tabulation characters analogously to the |filecontents|
+ treatment.
+\item Babel shorthands will be neutralized the same way they are when
+ encountered in a verbatim environment or in a |filecontents|
+ environment. Their action is reactivated if the macro (assuming the
+ contents represent \LaTeX\ code) gets later executed via
+ \csa{filecontentsexec}.
+\item The environment can be used either in the preamble or the body
+ of the document.
+\item The contents must not contain themselves a
+ \texttt{\string\end}|{filecontentsdef}| (or |end{filecontentsdef*}| in the
+starred case).
+\item If some |\macro| contains the \emph{name} of the macro to be defined,
+ use then |\empty\macro| as argument, this trick will avoid the environment
+ thinking it is supposed to redefine |\macro| itself.
+% problème avec Emacs/AUCTeX et |\end{...}| qui fait boguer le fontlock
+% biarrement le deuxième ne pose pas de problème. 19 avril 2019.
+\end{enumerate}
+
+\begin{footnotesize}
+ Here are some additional relevant details:
+\begin{enumerate}
+\item the usual special characters are sanitized like they would be in a
+ verbatim environment,
+\item the space becomes the active character of ascii code |32|,
+\item the end of line is converted into the active character |^^M| (i.e. ascii
+ code |13|),
+\item the tabulation character |CTRL-I| becomes the active space character,
+\item the form feed character |CTRL-L| is converted into a pair of active |^^M|,
+\item the active bytes of ascii code between |128| and |255| (this is now
+ systematically the case with |inputenc+utf8| being default) are stored
+ into the produced macro ``as is'',
+\item the non-active bytes of ascii code between |128| and |255| are
+ stored into the produced macro with catcode letter.
+\end{enumerate}
+These last two items together mean that 8bit or UTF8-encoded characters will
+display as expected in a verbatim rendering, see \csa{filecontentsprint} next.
+\par
+\end{footnotesize}
+
+\medskip
+
+The \csa{filecontentsprint}\inmarg{\csa{file\-contents\-print}} macro has a
+unique mandatory argument which will be either:
+\begin{itemize}
+\item a single control sequence token (for example |\macro|),
+\item \mbox{}\NewWith{v1.4$\to$}or anything else which then must after expansion be
+ usable as a macro \emph{name} (for example |macro|). It will be handled via
+ |\csname...\endcsname| encapsulation (see earlier explanations).%
+\end{itemize}
+The |\macro| must be of the type constructed by the environment
+|filecontentsdef|. It will be then be printed exactly as
+\begingroup\makeatletter\def\x{\let\@xverbatim\relax
+ \verbatim
+\string\begin\string{verbatim\string}\par
+<contents of \string\macro>\par
+\string\end\string{verbatim\string}\par
+\endverbatim%
+\endgroup}\x
+would have done.
+
+This uses underneath the |verbatim| environment and has been
+ tested to be compatible with the standard |verbatim|, with the one from
+ package \href{http://www.ctan.org/pkg/doc}{doc} (classes |ltxdoc.cls|,
+ |scrdoc.cls|) and also with the one from package
+ \href{http://www.ctan.org/pkg/verbatim}{verbatim} (whose mechanism is quite
+ different from the one of the default |verbatim| environment.)
+
+%xxx
+% MARRE DE EMACS/AUCTEX QUI SE CROIT PLUS INTELLIGENT QUE L'UTILISATEUR POUR
+% L'INDENTATION PAR FILL-PARAGRAPH (M-q)
+%xxx
+
+\begin{framed}
+ Due to limitation of the |verbatim| environment, the
+ \texttt{\string\end}|{verbatim}| must not appear inside the contents... else
+ it will be misconstrued as ending the external |verbatim| environment itself
+ which is added by \csa{filecontentsprint}!
+
+ This limitation only
+ affects \csa{filecontentsprint}, not \csa{filecontentsexec}.
+\end{framed}
+
+Although \fcdname itself generally does not require \eTeX, it provides as a
+convenience \csa{filecontentsexec}\inmarg{\csa{file\-contents\-exec}} which
+does require it as it uses |\scantokens| to re-assign the current catcode
+regime to the verbatimized tokens stored into its mandatory argument. Again
+the mandatory argument may have one of the two forms described previously.%
+\NewWith{v1.4$\to$}
+
+And of course this assumes that the tokens provide legitimate \LaTeX\ code.
+
+\begin{footnotesize}
+ \textbf{TeX-hacker note:} As an aftereffect, the |\newlinechar| will be set
+ to |10| (its \LaTeX\ default) after execution; we skipped the saving and
+ restoring of its value (it is temporarily set to |13| for |\scantokens|
+ execution). No group is used in order to not create an extra scoping of the
+ executed macro contents.
+
+ \textbf{TeX-hacker note:} A space token will be present at the end of the
+ expansion, due to |\scantokens|'s way of working, but may be hidden by the
+ nature of the contents themselves, if for example they end with a |\relax|
+ or a |%|, or from arising in vertical mode.
+
+\end{footnotesize}
+
+The environment\inmarg{|file\-contents\-here|}
+\begin{verbatim}
+ \begin{filecontentshere}{<filename>}
+ ... arbitrary contents ...
+ \end{filecontentshere}
+\end{verbatim}
+creates on the fly a file with these contents, and simultaneously
+it typesets them in a verbatim environment. It is a shortcut to doing
+\begin{verbatim}
+ \begin{filecontentsdef}{<filename>}{\filecontentsheremacro}
+ ... arbitrary contents ...
+ \end{filecontentsdef}
+\end{verbatim}
+and then immediately
+\begin{verbatim}
+ \filecontentsprint\filecontentsheremacro
+\end{verbatim}
+The |\filecontentsheremacro| remains available for reuse with |\filecontentsexec|.
+
+For example
+\begin{verbatim}
+\begin{filecontentshere}{\jobname.test}
+ \begin{framed}
+ \noindent
+ We have coded this in \LaTeX: both
+ $E=mc^2$ (input as \verb|$E=mc^2$|)
+ and $E=h\nu$ owe much to \textsc{Albert Einstein}.
+ \end{framed}
+\end{filecontentshere}
+\filecontentsexec\filecontentsheremacro
+\end{verbatim}
+will produce the external file with extension
+|.test| and have this effect in the document (verbatim framed then real framed):
+\begin{filecontentshere}{\jobname.test}
+ \begin{framed}
+ \noindent
+ We have coded this in \LaTeX: both
+ $E=mc^2$ (input as \verb|$E=mc^2$|)
+ and $E=h\nu$ owe much to \textsc{Albert Einstein}.
+ \end{framed}
+\end{filecontentshere}
+\filecontentsexec\filecontentsheremacro
+
+The environment\inmarg{|file\-contents\-def\-macro|}
+\begin{verbatim}
+ \begin{filecontentsdefmacro}{\macro or macro name}
+ ... arbitrary contents ...
+ \end{filecontentsdefmacro}
+\end{verbatim}
+was added at |v1.4|.\NewWith{v1.4} It is like |filecontentsdef| without the
+``save to file'' part... and has thus a sole mandatory argument which may be
+either a control sequence or a name (or material expanding to name), as
+previously described. The macro can then be either printed verbatim via
+\csa{filecontentsprint} or, if it consists of \LaTeX\ code, be executed in
+re-tokenized form via \csa{filecontentsexec}.
+
+Its name is thus a bit paradoxical but was chosen to share an existing prefix
+with the other package macros and environments.
+
+\section{How to wrap usage of \texttt{filecontentsdef} in another
+ environment}
+
+It is simple: don't use |\begin/\end| syntax
+% \verb|\end{filecontentsdef}|, % uniquement à cause de bug de Emacs/AUCTeX
+% % fontlocking
+but |\begingroup\filecontentsdef{..}{..}| and |\endfilecontentsdef\endgroup|.
+And these should come last, respectively first, in the definition of the
+begin, respectively end, part of the new environment.
+
+The extra |\begingroup...\endgroup| is needed only to the extent that
+definitions and catcode assignments could affect the execution of the
+rest of the |end| part of the new environment. As this |end| part will
+be tokenized at time of definition, it will in general be indifferent to
+the catcode modifications done by \csa{filecontentsdef} and generally
+speaking the |\begingroup...\endgroup| can be dropped.
+
+Of course, for wrapping the starred variant one should use
+% PUTAIN DE BORDEL DE Text for \verb command ended by end of line, QU'EST-CE
+% QUE LATEX EST CHIANT. Plus le fill-paragraph de Emacs et le doctex-mode défectueux.
+|\csname filecontentsdef*\endcsname|, or make the definition with |*| having catcode
+letter. But the \verb|\endfilecontentsdef| can drop the |*|, as the starred
+environments defined by the \fcdname package use the same ending macros as
+their non-starred variants.
+
+As exercise, let's imagine we want an environment which will be associated
+to some counter, will automatically increment it at each usage, and will
+use this counter to index the files and macros created on each invocation.
+\begin{filecontentsdefmacro}{\pablo}
+\newcounter{pablo}
+\newenvironment{defexercise}
+ {\stepcounter{pablo}%
+ \begingroup
+ \csname filecontentsdef*\endcsname
+ {\jobname-ex\the\value{pablo}}{exercise-\the\value{pablo}}}%
+ {\endfilecontentsdef\endgroup}
+\newcommand{\printexercise}[1]{\filecontentsexec{exercise-\the\numexpr#1\relax}}
+\end{filecontentsdefmacro}
+\filecontentsprint\pablo
+\filecontentsexec\pablo
+
+We can then use it this way:
+\begin{filecontentsdefmacro}{\usepablo}
+\begin{defexercise}
+ Prove that \[x^n+y^n=z^n\] is not solvable in positive integers if $n$ is at
+ most $-3$.\par
+\end{defexercise}
+\begin{defexercise}
+ Refute the existence of black holes in less than 140 characters.\par
+\end{defexercise}
+\begin{defexercise}
+ \def\NSA{NSA}%
+ Prove that factorization is easily done via probabilistic algorithms and
+ advance evidence from knowledge of the names of its employees in the
+ seventies that the \NSA\ has known that for 40 years.\par
+\end{defexercise}
+\begin{itemize}
+\item \printexercise{3}
+\item \printexercise{2}
+\item \printexercise{1}
+\end{itemize}
+\end{filecontentsdefmacro}
+\filecontentsprint\usepablo
+
+This produces in the document:
+\filecontentsexec\usepablo
+Additionally, three small files were created containing the \LaTeX\ mark-up
+for each exercise.
+
+\begin{footnotesize}
+
+\section{Custom verbatim print-outs}
+
+We now comment on alternatives to using \csa{filecontentsprint}. Here is
+some (non-\LaTeX) text snippet.
+\begin{verbatim}
+\begin{filecontentsdef}{\jobname.test2}{\testactive}
+v1.2 \[2016/09/19\]
+-------------------
+
+Initial version.
+
+test: éèàùÉÈÇÀÙÛÎåðñòóôõöœøùúûüýþߟŽ§
+\end{filecontentsdef}
+\end{verbatim}
+
+We can expand \csa{testactive} directly inside the \LaTeX\ document, but must
+give some definitions to the active space token and the active |^^M| token
+like |verbatim| environment does.
+
+For a true verbatim printout \csa{obeyspaces} and \csa{obeylines} are not
+enough because spaces at start of lines will disappear, and multiple empty
+lines give multiple |\par|'s which collapse into a single one (hence no empty
+line can be observed in the output). The usual |verbatim| environment uses a
+special definition of |\par| which prevents the disappearance of empty lines,
+and for the spaces it has macro \csa{@vobeyspaces} which makes the spaces
+issue |\leavevmode| so they are not skipped at the start of lines. Let's
+define:
+\begin{verbatim}
+\makeatletter
+% this redefines active spaces, but does not make spaces active
+\def\niceactivespaces{\@vobeyspaces\catcode32=10\relax}%
+\makeatother
+\begingroup
+% this redefines active end of lines, but does not make them active
+ \catcode`\^^M\active %
+ \gdef\niceactiveCRs{\def^^M{\leavevmode\par}}%
+\endgroup %
+\end{verbatim}
+
+Then we can issue something like:
+\begin{verbatim}
+{\setlength{\parindent}{2cm}\niceactivespaces\niceactiveCRs\testactive\par}
+\end{verbatim}
+This allows hyphenation and ligatures, which are usually inhibited in standard
+|verbatim|, and it does not switch to the monospace font. Here is what happens
+if we do all of the above, as a test:
+
+\def\testactive{testactive}
+\begin{filecontentsdefmacro}{\empty\testactive}
+v1.2 \[2016/09/19\]
+-------------------
+
+Initial version.
+
+test: éèàùÉÈÇÀÙÛÎåðñòóôõöœøùúûüýþߟŽ§
+\end{filecontentsdefmacro}
+\makeatletter
+% this redefines active spaces, but does not make spaces active
+\def\niceactivespaces{\@vobeyspaces\catcode32=10\relax}%
+\makeatother
+\begingroup
+% this redefines active end of lines, but does not make them active
+ \catcode`\^^M\active %
+ \gdef\niceactiveCRs{\def^^M{\leavevmode\par}}%
+\endgroup %
+{\setlength{\parindent}{2cm}\niceactivespaces\niceactiveCRs\testactive\par}
+We see indeed how the |---...--| gave rise to ligatures, and that the
+monospace font was not used. This was only to give an idea of how one can use
+the macros created by the |filecontentsdef| or |filecontentsdefmacro|
+environments for variant verbatim rendering. This technique can be used as
+workaround to the problem with \csa{filecontentsprint} that the contents can
+not contain \verb|\end{verbatim}|.
+
+\end{footnotesize}
+
+\StopEventually{\end{document}}
+
+\clearpage
+
+\makeatletter
+ \let\check@percent\original@check@percent
+\makeatother
+
+\small
+
+\section{Implementation}
+
+See the \texttt{README.md} file for the \texttt{CHANGE LOG}.
+
+% \indent % !!!!!!!!!!!!!!!!! Lundi 09 mars 2015 à 09:32:22
+
+
+\makeatletter
+\begingroup
+\topsep\MacrocodeTopsep
+\trivlist\parskip\z@\item[]
+\macro@font
+\leftskip\@totalleftmargin \advance\leftskip\MacroIndent
+\rightskip\z@ \parindent\z@ \parfillskip\@flushglue
+\global\@newlistfalse \global\@minipagefalse
+\ifcodeline@index
+ \everypar{\global\advance\c@CodelineNo\@ne
+ \llap{\theCodelineNo\ \hskip\@totalleftmargin}}%
+\fi
+\string\NeedsTeXFormat\string{LaTeX2e\string}[1999/12/01]\par
+\string\ProvidesPackage\string{\pkgname\string}\par
+\noindent\space [\pkgdate\space\pkgversion\space\pkgdescription]\par
+\nointerlineskip
+\global\@inlabelfalse
+\endtrivlist
+\endgroup
+\makeatother
+
+% The catcode hackery next is to avoid to have <*package> to be listed
+% in the commented source code...
+% (c) 2012/11/19 jf burnol ;-)
+
+\MakePercentIgnore
+
+%
+% \catcode`\<=0 \catcode`\>=11 \catcode`\*=11 \catcode`\/=11
+% \let</none>\relax
+% \def<*package>{\catcode`\<=12 \catcode`\>=12 \catcode`\*=12 \catcode`\/=12}
+%
+%</none>
+%<*package>
+% Most of
+% the code is still identical to the one in \textsc{Scott Pakin}'s
+% \href{http://www.ctan.org/pkg/filecontents}{filecontents} hence to
+% the original one in \LaTeX's sources.
+%
+% But |v1.4| adds \cs{filecontentsdefmacro} which does not write to a file...
+% \begin{macrocode}
+\begingroup
+\catcode`\^^M\active%
+\catcode`\^^L\active\let^^L\relax%
+\catcode`\^^I\active%
+\gdef\filec@ntentsdef#1#2{%
+ \let#2\@empty%
+ \if@filesw%
+ \openin\@inputcheck#1 %
+ \ifeof\@inputcheck%
+ \@latex@warning@no@line%
+ {Writing file `\@currdir#1'}%
+ \else%
+ \@latex@warning@no@line%
+ {Overwriting file `\@currdir#1'}%
+ \fi%
+ \closein\@inputcheck%
+ \chardef\reserved@c15 %
+ \ch@ck7\reserved@c\write%
+ \immediate\openout\reserved@c#1\relax%
+ \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%
+ \fi%
+ \let\do\@makeother\dospecials%
+% \end{macrocode}
+% SP's |filecontents| sets here in the loop all catcodes to |11|, but we
+% need for correct rendering in verbatim that the constructed macro
+% stores active characters as active characters.
+%
+% We don't check for unusual active characters of ascii code |<128|
+% as this is not done by original or SP's |filecontents|. But if
+% present then they will expand similarly both in the |\write| and
+% in the construction of the macro.
+% \begin{macrocode}
+ \count@=128\relax%
+ \loop%
+ \ifnum\catcode\count@=\active%
+ \lccode`~\count@%
+ \lowercase{\def~{\noexpand~}}%
+ \else%
+ \catcode\count@=11 %
+ \fi%
+ \advance\count@ by \@ne%
+ \ifnum\count@<\@cclvi%
+ \repeat%
+% \end{macrocode}
+% The default active |^^L| is |\outer|. But |\reserved@b| will be |def'd|
+% with an active |^^L| in its replacement text.
+% \begin{macrocode}
+ \let^^L\relax%
+ \edef\E{\@backslashchar end\string{\@currenvir\string}}%
+ \edef\reserved@b{\def\noexpand\reserved@b####1\E####2\E####3\relax}%
+% \end{macrocode}
+% \cs{filecontentsdefmacro} sets \cs{if@filesw} to false.
+% \begin{macrocode}
+ \reserved@b{%
+ \ifx\relax##3\relax%
+ \if@filesw\immediate\write\reserved@c{##1}\fi%
+% \end{macrocode}
+% This is where the original |filecontents| is extended to store the
+% parsed material in a macro (in my very first hack I simply
+% patched it to redefine |\write| to also do the macro storage, but
+% considerations like the one relative to active characters due to
+% |inputenc| made me decide to re-write the whole thing, hence make
+% a new package.)
+%
+% Active characters were defined with a single |\noexpand| in the
+% loop, and this is enough because after each new line is processed
+% the characters it contains are protected from further expansion in
+% the |\xdef|'s. And the single |\noexpand| is enough also for the
+% |\write| done above.
+%
+% The |lccode| of the tilde is |32| when this gets executed. Multiple
+% form feeds produce the same effect in the macro (insertion of two
+% |^^M| per form feed) as in the written out file (via two |^^J|).
+% \begin{macrocode}
+ \toks@\expandafter{#2}%
+ {\def^^L{\noexpand^^M\noexpand^^M}\lowercase{\let^^I~}%
+ \xdef#2{\the\toks@##1\noexpand^^M}}%
+ \else%
+ \edef^^M{\noexpand\end{\@currenvir}}%
+ \ifx\relax##1\relax%
+ \else%
+ \if@filesw%
+ \@latex@warning{Writing text `##1' before %
+ \string\end{\@currenvir}\MessageBreak as last line of #1}%
+ \immediate\write\reserved@c{##1}%
+ \fi%
+% \end{macrocode}
+% Same added code as above.
+% \begin{macrocode}
+ \toks@\expandafter{#2}%
+ {\def^^L{\noexpand^^M\noexpand^^M}\lowercase{\let^^I~}%
+ \xdef#2{\the\toks@##1\noexpand^^M}}%
+ \fi%
+ \ifx\relax##2\relax%
+ \else%
+ \@latex@warning{%
+ Ignoring text `##2' after \string\end{\@currenvir}}%
+ \fi%
+ \fi%
+ ^^M}%
+ \catcode`\^^L\active%
+% \end{macrocode}
+% |v1.4|: sync |^^L| and |^^I| with 2018/04/01 LaTeX release.
+% \begin{macrocode}
+ \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}%
+% \end{macrocode}
+% We want space characters to be active in the produced macro.
+% We only need to protect them once from expansion.
+% \begin{macrocode}
+ \catcode32\active\lccode`~32 \lowercase{\def~{\noexpand~}}%
+}%
+\endgroup
+% \end{macrocode}
+% The |v1.4| macros accept a name as alternative to a macro. Empty or
+% ill-formed |#2| will break code. But |#2| can be using |\if|, |\else|,
+% |\fi| tokens, the whole thing will end up |\csname|-expanded. An active
+% character also will end up |\csname|-expanded. There is no check on
+% whether |#2| or |\csname#2\endcsname| is an existing macro.
+% \begin{macrocode}
+\long\def\filecontentsdef@aux#1\filecontentsdef@aux{\@firstofone}%
+\def\filecontentsdef@get#1#2%
+{%
+ \def\@tempa{#1}\def\@tempb{{#2}}%
+ \expandafter\filecontentsdef@aux\@gobbletwo#2\filecontentsdef@aux
+ \@thirdofthree
+ \filecontentsdef@aux
+ {\ifcat\relax\noexpand#2\expandafter\@gobble\else\expandafter\@firstofone\fi}%
+ {\edef\@tempb{{\expandafter\noexpand\csname#2\endcsname}}}%
+ \expandafter\@tempa\@tempb
+}%
+% \end{macrocode}
+% |v1.4| adds \cs{filecontentsdefmacro}. I abuse the \cs{if@filesw} toggle as there
+% is no \cs{if@tempswb} available. No need for a starred version as anyhow
+% the commented-out header was not put into the macro by the existing
+% \cs{filec@ntentsdef} code. No need to reset the toggle as only usage as
+% an environment is supported. And by lazyness and to spare extra coding,
+% \cs{endfilecontentsdefmacro} emits no warning about Form Feed and Tabulation.
+% \begin{macrocode}
+\begingroup
+\catcode`\*=11
+\gdef\filecontentsdef #1{\@tempswatrue\filecontentsdef@get{\filec@ntentsdef{#1}}}%
+\gdef\filecontentsdef*#1{\@tempswafalse\filecontentsdef@get{\filec@ntentsdef{#1}}}%
+\global\let\endfilecontentsdef \endfilecontents
+\global\let\endfilecontentsdef*\endfilecontents
+\gdef\filecontentsdefmacro{\@fileswfalse\filecontentsdef@get{\filec@ntentsdef{}}}%
+\global\let\endfilecontentsdefmacro\relax
+\gdef\filecontentshere #1{\@tempswatrue\filec@ntentsdef{#1}\filecontentsheremacro}%
+\gdef\filecontentshere*#1{\@tempswafalse\filec@ntentsdef{#1}\filecontentsheremacro}%
+\gdef\endfilecontentshere{\endfilecontentsdef\aftergroup\filecontents@here}%
+\global\let\endfilecontentshere*\endfilecontentshere
+% \end{macrocode}
+% Package |verbatim.sty| modifies the standard |verbatim| environment. For
+% both the original and the modified version we need to insert an active |^^M|
+% upfront, else an empty first line would not be obeyed. The |verbatim.sty|'s
+% |verbatim| needs that we feed it with the macro expanded once, as it uses
+% active end of lines as delimiters and they thus need to be immediately
+% visible. It also needs an active |^^M| after the |\end{verbatim}|. To avoid
+% to check at |\AtBeginDocument| if package |verbatim.sty| is loaded, we use a
+% slightly tricky common definition. The advantage is that this may help make
+% the code compatible with further packages (I have not looked for them)
+% modifying the |verbatim| environment. For better code readibility I use
+% |^^M%|'s rather than exploiting the active ends of lines here.
+% \begin{macrocode}
+\gdef\filecontentsprint{\filecontentsdef@get\filecontents@print}%
+\catcode`\^^M\active%
+\gdef\filecontents@print #1{\let\filecontents@print@EOL^^M\let^^M\relax%
+ \begingroup\toks@\expandafter{#1}\edef\x{\endgroup%
+ \noexpand\begin{verbatim}^^M%
+ \the\toks@\@backslashchar end\string{verbatim\string}}\x^^M%
+ \filecontents@print@resetEOL}%
+\gdef\filecontents@print@resetEOL{\let^^M\filecontents@print@EOL}%
+\endgroup
+\def\filecontents@here{\filecontents@print\filecontentsheremacro}%
+\def\filecontentsexec{\filecontentsdef@get\filecontents@exec}%
+\def\filecontents@exec #1{\newlinechar13
+ \scantokens\expandafter{#1}\newlinechar10\relax}%
+\endinput
+% \end{macrocode}
+% \MakePercentComment
+\Finale
+%%
+%% End of file `filecontentsdef.dtx'.
diff --git a/macros/latex/contrib/filecontentsdef/filecontentsdef.pdf b/macros/latex/contrib/filecontentsdef/filecontentsdef.pdf
new file mode 100644
index 0000000000..ddf56cc7ac
--- /dev/null
+++ b/macros/latex/contrib/filecontentsdef/filecontentsdef.pdf
Binary files differ