From 76e559e4657cc54e211e35d7ae6fdb91f89ee034 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Thu, 2 May 2019 22:39:39 +0000 Subject: filecontentsdef (24apr19) git-svn-id: svn://tug.org/texlive/trunk@50942 c570f23f-e606-0410-a88d-b1316a301751 --- .../latex/filecontentsdef/filecontentsdef.dtx | 800 ++++++++++++--------- .../latex/filecontentsdef/filecontentsdef.ins | 47 -- 2 files changed, 466 insertions(+), 381 deletions(-) delete mode 100644 Master/texmf-dist/source/latex/filecontentsdef/filecontentsdef.ins (limited to 'Master/texmf-dist/source/latex/filecontentsdef') diff --git a/Master/texmf-dist/source/latex/filecontentsdef/filecontentsdef.dtx b/Master/texmf-dist/source/latex/filecontentsdef/filecontentsdef.dtx index 27eb4ebbdbc..b6b722383cd 100644 --- a/Master/texmf-dist/source/latex/filecontentsdef/filecontentsdef.dtx +++ b/Master/texmf-dist/source/latex/filecontentsdef/filecontentsdef.dtx @@ -1,76 +1,75 @@ -% -*- coding: utf-8; time-stamp-format: "%02d-%02m-%:y at %02H:%02M:%02S %Z" -*- -% N.B.: this dtx file is NOT for use with \DocInput. The latex source of the -% user manual isn't prefixed with percent signs. +% -*- 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 {Time-stamp: <19-09-2016 at 11:46:39 CEST>}% +\def\dtxtimestamp{21-04-2019 at 15:24:14 CEST}% % -%<*!readme> +%<*!readme&!install> %% %% Package: filecontentsdef -%% Version: 1.2 (2016/09/19) +%% Version: 1.4 (2019/04/20) %% License: LPPL 1.3c -%% Copyright (C) 2016 Jean-Francois Burnol +%% Copyright (C) 2016-2019 Jean-Francois Burnol %% -% -%<*insfile> +% +%<*none> \def\pkgname {filecontentsdef} -\def\pkgdate {2016/09/19} -\def\pkgdocdate {2016/09/19} -\def\pkgversion {v1.2} +\def\pkgdate {2019/04/20} +\def\pkgdocdate {2019/04/21} +\def\pkgversion {v1.4} \def\pkgdescription {filecontents + macro + verbatim (JFB)} -% -%<*none> -\iffalse +\catcode`\^ 12 \iffalse % -%<*readme> +%<*readme|install> - Source: filecontentsdef.dtx (v1.2 2016/09/19) + Source: filecontentsdef.dtx (v1.4 2019/04/20) Author: Jean-Francois Burnol Info: filecontents + macro + verbatim License: LPPL 1.3c - Copyright (C) 2016 Jean-Francois Burnol. + Copyright (C) 2016-2019 Jean-Francois Burnol. +% +%<*readme> ABSTRACT ======== -This lightweight LaTeX2e package provides two environments called -`filecontentsdef` and `filecontentshere`. They are derived from the -LaTeX `filecontents` environment as extended by Scott Pakin's -[filecontents] [1] package. In addition to the file creation they -either store the (verbatim) contents in a macro (`filecontentsdef`) -or typeset them (verbatim) on the spot (`filecontentshere`). +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). -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 _file attachment annotations_ -(via the services of Scott Pakin's further package [attachfile] [2].) +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" -[2]: http://www.ctan.org/pkg/attachfile "attachfile package" -INSTALLATION -============ +CHANGE LOG +========== -To extract the package (.sty) run etex on the dtx file. To produce -the PDF documentation, either: +v1.4 \[2019/04/20\] +------------------- -1. latex (twice) filecontentsdef.dtx, then dvips, then ps2pdf -2. or pdflatex (twice), -3. or latex (twice) then dvipdfmx +- backport 2018/04/01 LaTeX release change to filecontents environment + (`^^L` and `^^I` definitions). -This will also extract automatically the style file. +- add `filecontentsdefmacro` environment. -Installation: +- extend `filecontentsdef` and `filecontentsdefmacro` environments as + well as `\filecontentsprint` and `\filecontentsexec` macros to accept + indifferently either a control sequence or a name as argument. - filecontentsdef.sty -> TDS:tex/latex/filecontentsdef/filecontentsdef.sty - filecontentsdef.dtx -> TDS:source/latex/filecontentsdef/filecontentsdef.dtx - filecontentsdef.pdf -> TDS:doc/latex/filecontentsdef/filecontentsdef.pdf +- refactor documentation, explain how to define wrapper environments. - README.md -> TDS:doc/latex/filecontentsdef/README.md +v1.2 \[2016/09/19\] +------------------- -The other files may be discarded. +Initial version. LICENSE ======= @@ -93,18 +92,39 @@ The Author of this Work is: - Jean-Francois Burnol `` This Work consists of the main source file filecontentsdef.dtx and -the derived files filecontentsdef.sty, filecontentsdef.ins, -filecontentsdef.pdf, filecontentsdef.dvi, README.md. +its derived files filecontentsdef.sty, filecontentsdef.pdf, +filecontentsdef.dvi, README.md, INSTALL.md, README, INSTALL. +% +%<*install> +INSTALLATION +============ +Use your installation manager. -CHANGE LOG -========== +Else, for manual installation: -v1.2 \[2016/09/19\] -------------------- +- To extract the package and at the same time produce the documentation, + execute latex twice on `filecontentsdef.dtx` then `dvipdfmx` on the + `dvi` file. -Initial version. -% + 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 @@ -117,43 +137,8 @@ Initial version. %%% mode: latex %%% End: %------------------------------------------------------------------------- -%<*insfile>--------------------------------------------------------------------- -\input docstrip.tex -\askforoverwritefalse -\def\pkgpreamble{\defaultpreamble^^J\MetaPrefix^^J% -\string\NeedsTeXFormat{LaTeX2e}^^J% -\string\ProvidesPackage{filecontentsdef}^^J% -\space[\pkgdate\space\pkgversion\space\pkgdescription]}% -\generate{\nopreamble\nopostamble -\file{README.md}{\from{\pkgname.dtx}{readme}}% -\usepostamble\defaultpostamble -\file{\pkgname.tex}{\from{\pkgname.dtx}{tex}}% -\usepreamble\pkgpreamble -\file{\pkgname.sty}{\from{\pkgname.dtx}{package}}}% -\catcode32=13\relax% active space -\let =\space% -\Msg{************************************************************************} -\Msg{*} -\Msg{* To finish the installation you have to move the following} -\Msg{* file into a directory searched by TeX:} -\Msg{*} -\Msg{* \pkgname.sty} -\Msg{*} -\Msg{* To produce the documentation run latex twice on file \pkgname.tex} -\Msg{* and then run dvipdfmx on \pkgname.dvi.} -\Msg{*} -\Msg{* Happy TeXing!} -\Msg{*} -\Msg{************************************************************************} -\ifx\numexpr\undefined -\Msg{* warning: to get correct utf-8 encoded README.md }% -\Msg{* do etex \pkgname.ins and not tex \pkgname.ins }% -\Msg{************************************************************************} -\fi -\endbatchfile -%--------------------------------------------------------------------- %<*none>------------------------------------------------------------------------ -\fi +\fi\catcode`\^ 7 % \chardef\noetex 0 \ifx\numexpr\undefined\chardef\noetex 1 \fi @@ -168,7 +153,7 @@ Initial version. \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}% + \PassOptionsToClass {a4paper,fontsize=11pt,oneside}{scrdoc}% \PassOptionsToPackage {english}{babel}% \else % latex on tex \chardef\extractfiles 2 % do not extract files, only typeset @@ -202,20 +187,13 @@ Initial version. \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.ins}{\from{\pkgname.dtx}{insfile}}% \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\noetex=1 % warning for README.md - \expandafter\def\expandafter\MessageDeFin\expandafter -{\MessageDeFin -\Msg{* warning: to get correct utf-8 encoded README.md ^^J}% -\Msg{* do etex \pkgname.dtx and not tex \pkgname.dtx ^^J}% -\Msg{********************************************************************^^J}}% -\fi \ifnum\extractfiles=0 % tex/etex/xetex/etc files extracted, stop \MessageDeFin\expandafter\end \fi @@ -255,6 +233,7 @@ Initial version. \pagestyle{headings} \def\MacroFont{\ttfamily\small\hyphenchar\font45 \baselineskip11pt\relax} +\AtBeginDocument{\def\MacroFont{\ttfamily}} % ATTENTION: (avec doc.sty ou les classes scrdoc ou ltxdoc) % @@ -282,11 +261,7 @@ Initial version. \newcommand\csh[1]{\texorpdfstring{\csa{#1}}{\textbackslash\detokenize{#1}}} -\usepackage {babel} % ngerman and english options have been passed to babel -\AtBeginDocument {% - \renewcommand\partname{Part}% - \addto\captionsenglish {\renewcommand\partname{Part}}% -} +\usepackage{babel} \usepackage[pdfencoding=pdfdoc]{hyperref} \hypersetup{% @@ -299,7 +274,7 @@ urlcolor=RoyalBlue,%OliveGreen,% pdfauthor={Jean-Fran\c cois Burnol},% pdftitle={The \pkgname\space package},% pdfsubject={\pkgdescription},% -pdfkeywords={LaTeX, files, verbatim},% +pdfkeywords={LaTeX, verbatim, macros},% pdfstartview=FitH,% pdfpagemode=UseOutlines} \usepackage{bookmark} @@ -317,15 +292,26 @@ pdfpagemode=UseOutlines} \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 + {\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} @@ -348,207 +334,329 @@ pdfpagemode=UseOutlines} jfbu (at) free (dot) fr\par Package version: \pkgversion\ (\pkgdate); documentation date: \pkgdocdate.\par - {From source file \texttt{\pkgname.dtx}. \dtxtimestamp.}\par + {From source file \texttt{\pkgname.dtx (\dtxtimestamp)}}\par } \begin{abstract} - This lightweight \LaTeX2e package provides environments - |filecontentsdef| and |filecontentshere|. They are derived from - the \LaTeX\ |filecontents| environment as extended by - \textsc{Scott Pakin}'s - \href{http://www.ctan.org/pkg/filecontents}{filecontents} - package.\footnote{\fcdname works independently from - \href{http://www.ctan.org/pkg/filecontents}{filecontents} and - does not load it.} In addition to the file creation they either - store the (verbatim) contents in a macro (|filecontentsdef|) or - typeset them (verbatim) on the spot (|filecontentshere|). + 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{http://www.ctan.org/pkg/attachfile}{attachfile}.) + \href{https://ctan.org/pkg/attachfile}{attachfile}.) \end{abstract} \section{Description} -The environment\inmarg{|file\-contents\-here|} +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{filecontentshere}{} + \begin{filecontentsdef}{}{\macro} ... arbitrary contents ... - \end{filecontentshere} + \end{filecontentsdef} \end{verbatim} -creates on the fly a file with these contents, and simultaneously -it typesets them in a verbatim environment. There is no syntax - highlighting whatsoever. -\begin{footnotesize} -\begin{enumerate} -\item - The contents are not completely arbitrary, as they may not contain - |\end{filecontentshere}| itself...\par -\item This uses underneath the |verbatim| environment and this 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.) -\end{enumerate} -\end{footnotesize} - -\medskip -The other environment is |filecontentsdef|.\inmarg{|file\-contents\-def|} -It has a second mandatory argument, a macro. - +or: \begin{verbatim} - \begin{filecontentsdef}{}{\macro} + \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). -It creates the file and rather than typesetting it verbatim -simultaneously, it stores its (verbatim) contents in its second argument -|\macro|. +\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 scope of the macro definition is global, -\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 both environments admit the starred form which does \emph{not} add -the usual three comment lines at the top of the written file (those lines -are anyhow not typeset by |filecontentshere| nor are they included in the -macro by |filecontentsdef|). +\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} - Please note that |filecontentsdef| basically stores sanitized - (i.e. verbatim) tokens in its macro argument |\macro|. - - If the material consists of \LaTeX\ code, the expansion of the - macro will only typeset some \emph{verbatim} rendering of the - \LaTeX\ code. + 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} - \def\MacroFont{\ttfamily\footnotesize\hyphenchar\font45 - \baselineskip\the\baselineskip\relax} Using \eTeX's - \csa{scantokens}, one can re-tokenize the macro contents and (here - naturally, we are talking about the situation where the macro - contains \TeX/\LaTeX\ code): we obtain its ``execution'' via - |\scantokens\expandafter{\macro}|. Due to the way |\scantokens| - works, this must be done with |\newlinechar| set to |13| (to match - the |^^M|'s; see later in this documentation). Example: + \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{filecontentsdef}{\jobname.test}{\macro} + \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 |$E=mc^2$|) + $E=mc^2$ (input as \verb|$E=mc^2$|) and $E=h\nu$ owe much to \textsc{Albert Einstein}. \end{framed} -\end{filecontentsdef} -{\newlinechar13 \scantokens\expandafter{\macro}} +\end{filecontentshere} +\filecontentsexec\filecontentsheremacro \end{verbatim} -\begin{filecontentsdef}{\jobname.test}{\macro} +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 |$E=mc^2$|) + $E=mc^2$ (input as \verb|$E=mc^2$|) and $E=h\nu$ owe much to \textsc{Albert Einstein}. \end{framed} -\end{filecontentsdef} -\filecontentsexec\macro Notice\footnote{The absence of indentation - at the start of this paragraph is a funny effect due to it - immediately following |framed| which itself immediately follows a - |verbatim|.} that a space token will generally appear at the end of -the expansion, due to |\scantokens|'s way of working. This is an -end-of-line space, which we could suppress via |\endlinechar-1\relax| -before the |\scantokens|, but that is an option only in the case of -single-line contents. If we had written above \verb|\end{framed}%| or -|\end{framed}\relax| in our use of |filecontentsdef| this would have -prevented |\scantokens| from inserting this final space (naturally in -this example the space is issued while \TeX\ is in vertical mode and -leaves no trace anyhow).\footnote{for basic information on this issue, - see: -\url{http://tex.stackexchange.com/questions/117906/use-of-everyeof-and-endlinechar-with-scantokens}} - -Although \fcdname itself makes no use of \eTeX, it provides as a -convenience -\csa{filecontentsexec}\inmarg{\csa{file\-contents\-exec}\csa{macro}} -which will use |\scantokens| to execute a |\macro| as above (thus -assuming it contains legitimate but possibly verbatimized \LaTeX\ -code.) Rather than using a group (possibly |\macro| makes some -non-global definitions) it issues |\newlinechar10\relax| (as this is -the default -- we could have stored and restored current value, but -well...) after the |\scantokens|.\par -\end{footnotesize} +\end{filecontentshere} +\filecontentsexec\filecontentsheremacro -As an example consider the following (with some |utf8| characters -among those which are available in |T1|-encoded \TeX-fonts as used -by this document with the help of |fontenc| and |inputenc|): +The environment\inmarg{|file\-contents\-def\-macro|} \begin{verbatim} -\begin{filecontentsdef}{filecontentsdef.license}{\fcdlicense} -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-François Burnol `` - -This Work consists of the main source file filecontentsdef.dtx and -the derived files filecontentsdef.sty, filecontentsdef.ins, -filecontentsdef.pdf, filecontentsdef.dvi, README.md. - -CHANGE LOG -========== - -v1.2 \[2016/09/19\] -------------------- - -Initial version. - -test: éèàùÉÈÇÀÙÛÎåðñòóôõöœøùúûüýþߟŽ§ -\end{filecontentsdef} + \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{filecontentsdef}{filecontentsdef.license}{\fcdlicense} -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-François Burnol `` - -This Work consists of the main source file filecontentsdef.dtx and -the derived files filecontentsdef.sty, filecontentsdef.ins, -filecontentsdef.pdf, filecontentsdef.dvi, README.md. +\begin{footnotesize} -CHANGE LOG -========== +\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\] ------------------- @@ -556,38 +664,20 @@ Initial version. test: éèàùÉÈÇÀÙÛÎåðñòóôõöœøùúûüýþߟŽ§ \end{filecontentsdef} +\end{verbatim} -The file |filecontentsdef.license| is created with the usual three commentary -lines at top of it. And macro \csa{fcdlicense} contains the verbatim material. -It can then be expanded anywhere in the document. Here are some relevant -details: - -\begin{enumerate} -\item the usual special characters are sanitized like in a verbatim - environment, -\item spaces become the active character of ascii code |32|, and - end of lines are converted into the active character of ascii - code |13| (i.e. |^^M|), -\item the tabs |CTRL-I| have been converted to active spaces, -\item the form feeds |CTRL-L| have been converted to blank lines (|^^M^^M|), -\item the characters of ascii code between |128| and |255| have been - either given the catcode |letter|, or if they were active (which - will be the case with package |inputenc|), they are just inserted in - the produced macro as active characters. -\end{enumerate} - -Thus what is needed before inserting \csa{fcdlicense} in the document -is to give definitions to the active space and the active |^^M|. -\LaTeX\ and \TeX\ both provide \csa{obeyspaces} and \csa{obeylines}. -For a true verbatim printout, these are usually 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: - +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 @@ -600,46 +690,46 @@ the start of lines. Let's define: \endgroup % \end{verbatim} -Then we can issue something like (the output is not shown): +Then we can issue something like: \begin{verbatim} -{\setlength{\parindent}{1cm}\niceactivespaces\niceactiveCRs\fcdlicense} +{\setlength{\parindent}{2cm}\niceactivespaces\niceactiveCRs\testactive\par} \end{verbatim} -Notice however this will still allow hyphenation and ligatures, which -are usually inhibited in standard |verbatim| (and also we have not -switched to the monospace font.) To emulate exactly what a real -|verbatim| would give, \fcdname provides -\csa{filecontentsprint}\inmarg{\csa{file\-contents\-print}\csa{macro}} -which is a command with one mandatory argument whose invocation will -produce the same as what -\begingroup\makeatletter\def\x{\let\@xverbatim\relax - \verbatim -\string\begin\string{verbatim\string}\par -\par -\string\end\string{verbatim\string}\par -\endverbatim% -\endgroup}\x - -% % bizarre -% % \texttt{\parindent0pt\relax\niceactivespaces\niceactiveCRs\fcdlicense}% -% % crée l'indentation il faut faire le \parindent0pt avant ! -% % hmm, bon pas envie de regarder ce que fait \texttt - -% % pour le fun -% % {\setlength{\parindent}{11cm}\niceactivespaces\niceactiveCRs\ttfamily\fcdlicense} +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: -\noindent would have given.\footnote{This is compatible with - \href{http://www.ctan.org/pkg/verbatim}{verbatim.sty}'s |verbatim| and - hopefully also with other packages modifiying the way the |verbatim| - environment works.} The tokens stored in the macro must be of the type -described above. As an illustration, here is the output from -|\filecontentsprint\fcdlicense|: +\def\testactive{testactive} +\begin{filecontentsdefmacro}{\empty\testactive} +v1.2 \[2016/09/19\] +------------------- +Initial version. -\filecontentsprint\fcdlicense +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 @@ -648,7 +738,9 @@ described above. As an illustration, here is the output from \section{Implementation} -\indent % !!!!!!!!!!!!!!!!! Lundi 09 mars 2015 à 09:32:22 +See the \texttt{README.md} file for the \texttt{CHANGE LOG}. + +% \indent % !!!!!!!!!!!!!!!!! Lundi 09 mars 2015 à 09:32:22 \makeatletter @@ -689,6 +781,8 @@ described above. As an illustration, here is the output from % 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% @@ -696,6 +790,7 @@ described above. As an illustration, here is the output from \catcode`\^^I\active% \gdef\filec@ntentsdef#1#2{% \let#2\@empty% + \if@filesw% \openin\@inputcheck#1 % \ifeof\@inputcheck% \@latex@warning@no@line% @@ -718,6 +813,7 @@ described above. As an illustration, here is the output from \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 @@ -747,9 +843,12 @@ described above. As an illustration, here is the output from \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% - \immediate\write\reserved@c{##1}% + \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 @@ -775,9 +874,11 @@ described above. As an illustration, here is the output from \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} @@ -793,11 +894,14 @@ described above. As an illustration, here is the output from \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{\@ifundefined L^^J^^J^^J}% + \def^^L{\expandafter\ifx\csname L\endcsname\relax\fi^^J^^J}% \catcode`\^^I\active% \let\I\@undefined% - \def^^I{\@ifundefined I\space\space}% + \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} @@ -807,17 +911,43 @@ described above. As an illustration, here is the output from \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 {\@tempswatrue\filec@ntentsdef}% -\gdef\filecontentsdef*{\@tempswafalse\filec@ntentsdef}% +\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\filecontentshere #1{\@tempswatrue - \filec@ntentsdef{#1}\filecontentsheremacro}% -\gdef\filecontentshere*#1{\@tempswafalse - \filec@ntentsdef{#1}\filecontentsheremacro}% -\gdef\endfilecontentshere{\endfilecontentsdef\aftergroup\filecontents@verbatim}% +\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 @@ -832,16 +962,18 @@ described above. As an illustration, here is the output from % 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\filecontentsprint #1{\let\filecontentsprint@EOL^^M\let^^M\relax% +\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% - \filecontentsprint@resetEOL}% -\gdef\filecontentsprint@resetEOL{\let^^M\filecontentsprint@EOL}% + \filecontents@print@resetEOL}% +\gdef\filecontents@print@resetEOL{\let^^M\filecontents@print@EOL}% \endgroup -\def\filecontents@verbatim {\filecontentsprint\filecontentsheremacro}% -\def\filecontentsexec #1{\newlinechar13 +\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} diff --git a/Master/texmf-dist/source/latex/filecontentsdef/filecontentsdef.ins b/Master/texmf-dist/source/latex/filecontentsdef/filecontentsdef.ins deleted file mode 100644 index 4ee739a6bfc..00000000000 --- a/Master/texmf-dist/source/latex/filecontentsdef/filecontentsdef.ins +++ /dev/null @@ -1,47 +0,0 @@ -%% -%% Package: filecontentsdef -%% Version: 1.2 (2016/09/19) -%% License: LPPL 1.3c -%% Copyright (C) 2016 Jean-Francois Burnol -%% -\def\pkgname {filecontentsdef} -\def\pkgdate {2016/09/19} -\def\pkgdocdate {2016/09/19} -\def\pkgversion {v1.2} -\def\pkgdescription {filecontents + macro + verbatim (JFB)} -\input docstrip.tex -\askforoverwritefalse -\def\pkgpreamble{\defaultpreamble^^J\MetaPrefix^^J% -\string\NeedsTeXFormat{LaTeX2e}^^J% -\string\ProvidesPackage{filecontentsdef}^^J% -\space[\pkgdate\space\pkgversion\space\pkgdescription]}% -\generate{\nopreamble\nopostamble -\file{README.md}{\from{\pkgname.dtx}{readme}}% -\usepostamble\defaultpostamble -\file{\pkgname.tex}{\from{\pkgname.dtx}{tex}}% -\usepreamble\pkgpreamble -\file{\pkgname.sty}{\from{\pkgname.dtx}{package}}}% -\catcode32=13\relax% active space -\let =\space% -\Msg{************************************************************************} -\Msg{*} -\Msg{* To finish the installation you have to move the following} -\Msg{* file into a directory searched by TeX:} -\Msg{*} -\Msg{* \pkgname.sty} -\Msg{*} -\Msg{* To produce the documentation run latex twice on file \pkgname.tex} -\Msg{* and then run dvipdfmx on \pkgname.dvi.} -\Msg{*} -\Msg{* Happy TeXing!} -\Msg{*} -\Msg{************************************************************************} -\ifx\numexpr\undefined -\Msg{* warning: to get correct utf-8 encoded README.md }% -\Msg{* do etex \pkgname.ins and not tex \pkgname.ins }% -\Msg{************************************************************************} -\fi -\endbatchfile -\endinput -%% -%% End of file `filecontentsdef.ins'. -- cgit v1.2.3