From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex/contrib/filecontentsdef/INSTALL | 37 + macros/latex/contrib/filecontentsdef/README.md | 71 ++ .../contrib/filecontentsdef/filecontentsdef.dtx | 983 +++++++++++++++++++++ .../contrib/filecontentsdef/filecontentsdef.pdf | Bin 0 -> 90457 bytes 4 files changed, 1091 insertions(+) create mode 100644 macros/latex/contrib/filecontentsdef/INSTALL create mode 100644 macros/latex/contrib/filecontentsdef/README.md create mode 100644 macros/latex/contrib/filecontentsdef/filecontentsdef.dtx create mode 100644 macros/latex/contrib/filecontentsdef/filecontentsdef.pdf (limited to 'macros/latex/contrib/filecontentsdef') 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. + + + + +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. + + +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 + +> + +and the latest version of this license is in + +> + +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 `` + +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}% +% +%<*!readme&!install> +%% +%% Package: filecontentsdef +%% Version: 1.4 (2019/04/20) +%% License: LPPL 1.3c +%% Copyright (C) 2016-2019 Jean-Francois Burnol +%% +% +%<*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 +% +%<*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. + + +% +%<*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 + +> + +and the latest version of this license is in + +> + +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 `` + +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. +% +%<*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. +% +%<*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: +%------------------------------------------------------------------------- +%<*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}{}{\macro} + ... arbitrary contents ... + \end{filecontentsdef} +\end{verbatim} +or: +\begin{verbatim} + \begin{filecontentsdef}{}{(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 |\| 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 +\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}{} + ... 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}{}{\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\relax +% \def<*package>{\catcode`\<=12 \catcode`\>=12 \catcode`\*=12 \catcode`\/=12} +% +% +%<*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 Binary files /dev/null and b/macros/latex/contrib/filecontentsdef/filecontentsdef.pdf differ -- cgit v1.2.3