Debian Codegraph @

texmf-dist/source/latex/filecontentsdef/filecontentsdef.dtx

raw
1 % -*- coding: utf-8; time-stamp-pattern: "def\\\\dtxtimestamp{%02d-%02m-%:y at %02H:%02M:%02S %Z}" -*-
2 % N.B.: this dtx file is NOT for use with \DocInput but only docstrip.
3 % The latex source of the user manual isn't commented out.
4 %<*none>
5 \def\dtxtimestamp{29-09-2019 at 10:46:12 CEST}%
6 %</none>
7 %<*!readme&!install>
8 %%
9 %% Package: filecontentsdef
10 %% Version: 1.5 (2019/09/29)
11 %% License: LPPL 1.3c
12 %% Copyright (C) 2016-2019 Jean-Francois Burnol <jfbu at free dot fr>
13 %%
14 %</!readme&!install>
15 %<*none>
16 \def\pkgname {filecontentsdef}
17 \def\pkgdate {2019/09/29}
18 \def\pkgdocdate {2019/09/29}
19 \def\pkgversion {v1.5}
20 \def\pkgdescription {filecontents + macro + verbatim (JFB)}
21 \catcode`\^ 12 \iffalse
22 %</none>
23 %<*readme|install>
24 <!-- -->
25
26 Source: filecontentsdef.dtx (v1.5 2019/09/29)
27 Author: Jean-Francois Burnol
28 Info: filecontents + macro + verbatim
29 License: LPPL 1.3c
30 Copyright (C) 2016-2019 Jean-Francois Burnol.
31 <jfbu at free dot fr>
32
33 %</readme|install>
34 %<*readme>
35 ABSTRACT
36 ========
37
38 This lightweight LaTeX2e package provides an environment `filecontentsdef`
39 which is like the `filecontents` environment of Scott Pakin's
40 [filecontents] [1] package but in addition to the file creation stores the
41 (verbatim) contents into a macro given as an additional argument (either as a
42 control sequence or as a name).
43
44 Displaying verbatim these contents is possible via `\filecontentsprint`,
45 and executing them (if they represent LaTeX code) via `\filecontentsexec`.
46
47 A variant environment `filecontentsdefmacro` stores the contents into a
48 macro, but skips the save-to-a-file part.
49
50 [1]: http://www.ctan.org/pkg/filecontents "filecontents package"
51
52 CHANGE LOG
53 ==========
54
55 v1.5 \[2019/09/29\]
56 -------------------
57
58 - `\filecontentsexec` does not forcefully reset `\newlinechar`
59 to its LaTeX default after execution.
60
61 - `\FCD@` as prefix for internal non public macros.
62
63 - drop usage of the legacy LaTeX mechanism which issued a warning
64 in case of a form feed or horizontal tabulation character in the
65 parsed contents.
66
67 - make handling of the tabulation and form feed characters
68 customizable.
69
70 - treat especially the case when the `\end{filecontents...}`
71 is not on a line of its own.
72
73 - add `filecontentsdefstarred` (et al.) as alias for
74 `filecontentsdef*` (et al.) for easying up encapsulation in
75 wrapping environments.
76
77 - breaking change: `filecontentsdef` and `filecontentsdefmacro`
78 define a macro obeying the local scope. Use `filecontentsgdef`,
79 resp. `filecontentsgdefmacro` for definitions with global scope.
80
81 - make the name of the environment used by `\filecontentsprint`
82 customizable (it defaults to `verbatim`) and allow to pass options
83 to it; has been tested with `fancyvrb` and `minted`.
84
85 - add `\filecontentsprintviascan` which allows to use verbatim-like
86 environment such as `listings` which are incompatible with
87 `\filecontentsprint`.
88
89 v1.4 \[2019/04/20\]
90 -------------------
91
92 - backport 2018/04/01 LaTeX release change to filecontents environment
93 (`^^L` and `^^I` definitions).
94
95 - add `filecontentsdefmacro` environment.
96
97 - extend `filecontentsdef` and `filecontentsdefmacro` environments as
98 well as `\filecontentsprint` and `\filecontentsexec` macros to accept
99 indifferently either a control sequence or a name as argument.
100
101 - refactor documentation, explain how to define wrapper environments.
102
103 v1.2 \[2016/09/19\]
104 -------------------
105
106 Initial version.
107
108 LICENSE
109 =======
110
111 This Work may be distributed and/or modified under the
112 conditions of the LaTeX Project Public License 1.3c.
113 This version of this license is in
114
115 > <http://www.latex-project.org/lppl/lppl-1-3c.txt>
116
117 and the latest version of this license is in
118
119 > <http://www.latex-project.org/lppl.txt>
120
121 and version 1.3 or later is part of all distributions of
122 LaTeX version 2005/12/01 or later.
123
124 The Author of this Work is:
125
126 - Jean-Francois Burnol `<jfbu at free dot fr>`
127
128 This Work consists of the main source file filecontentsdef.dtx and
129 its derived files filecontentsdef.sty, filecontentsdef.pdf,
130 filecontentsdef.dvi, README.md, INSTALL.md, README, INSTALL.
131 %</readme>
132 %<*install>
133 INSTALLATION
134 ============
135
136 Use your installation manager.
137
138 Else, for manual installation:
139
140 - To extract the package and at the same time produce the documentation,
141 execute latex thrice on `filecontentsdef.dtx` then `dvipdfmx` on the
142 `dvi` file.
143
144 To customize the PDF documentation (paper size, etc...): execute `etex`
145 once on `filecontentsdef.dtx` then follow instructions given inside the
146 extracted file `filecontentsdef.tex`.
147
148 - To extract the package but not necessarily build the documentation:
149 run `etex` on `filecontentsdef.dtx`.
150
151 Files should then be moved to appropriate locations:
152
153 filecontentsdef.sty -> TDS:tex/latex/filecontentsdef/
154 filecontentsdef.dtx -> TDS:source/latex/filecontentsdef/
155 filecontentsdef.pdf -> TDS:doc/latex/filecontentsdef/
156 README.md -> TDS:doc/latex/filecontentsdef/
157 INSTALL.md -> TDS:doc/latex/filecontentsdef/
158
159 You can also place `filecontentsdef.sty` directly within the directory
160 of the project using it.
161 %</install>
162 %<*tex>-------------------------------------------------------------------------
163 \chardef\Withdvipdfmx 1 % replace 1 by 0 for using pdflatex
164 \chardef\NoSourceCode 0 % replace 0 by 1 for the doc *without* the source code
165 \NeedsTeXFormat{LaTeX2e}
166 \ProvidesFile {filecontentsdef.tex}[Driver for filecontentsdef documentation]%
167 \PassOptionsToClass {a4paper,fontsize=11pt,oneside}{scrdoc}
168 \PassOptionsToPackage {english}{babel}
169 \input filecontentsdef.dtx
170 %%% Local Variables:
171 %%% mode: latex
172 %%% End:
173 %</tex>-------------------------------------------------------------------------
174 %<*none>------------------------------------------------------------------------
175 \fi\catcode`\^ 7
176 %
177 \chardef\noetex 0
178 \ifx\numexpr\undefined\chardef\noetex 1 \fi
179 \ifnum\noetex=1 \chardef\extractfiles 0 % extract files, then stop
180 \else
181 \ifx\ProvidesFile\undefined
182 \chardef\extractfiles 0 % etex etc.. on dtx, only file extraction.
183 \else % latex/pdflatex
184 \ifx\Withdvipdfmx\undefined
185 % latex/pdflatex on dtx
186 \chardef\extractfiles 1 % 1 = extract files and typeset manual, 2 = only typeset
187 \chardef\Withdvipdfmx 1 % 0 = pdflatex or latex+dvips, 1 = dvipdfmx
188 \chardef\NoSourceCode 0 % 0 = include source code, 1 = do not
189 \NeedsTeXFormat {LaTeX2e}%
190 \PassOptionsToClass {a4paper,fontsize=11pt,oneside}{scrdoc}%
191 \PassOptionsToPackage {english}{babel}%
192 \else % latex on tex
193 \chardef\extractfiles 2 % do not extract files, only typeset
194 \fi
195 \ProvidesFile{\pkgname.dtx}%
196 [\pkgname\space source and documentation (\dtxtimestamp)]%
197 \fi
198 \fi
199 \ifnum\extractfiles<2 % extract files
200 \def\MessageDeFin{\newlinechar10 \let\Msg\message
201 \Msg{********************************************************************^^J}%
202 \Msg{*^^J}%
203 \Msg{* To finish the installation you have to move the following^^J}%
204 \Msg{* file into a directory searched by TeX:^^J}%
205 \Msg{*^^J}%
206 \Msg{*\space\space\space\space \pkgname.sty^^J}%
207 \Msg{*^^J}%
208 \Msg{* To produce the documentation with source code included run latex^^J}%
209 \Msg{* thrice on file \pkgname.tex and then dvipdfmx on \pkgname.dvi^^J}%
210 \Msg{*^^J}%
211 \Msg{* Happy TeXing!^^J}%
212 \Msg{*^^J}%
213 \Msg{********************************************************************^^J}%
214 }%
215 \begingroup
216 \input docstrip.tex
217 \askforoverwritefalse
218 \def\pkgpreamble{\defaultpreamble^^J\MetaPrefix^^J%
219 \string\NeedsTeXFormat{LaTeX2e}^^J%
220 \string\ProvidesPackage{\pkgname}^^J%
221 \space[\pkgdate\space\pkgversion\space\pkgdescription]}%
222 \generate{\nopreamble\nopostamble
223 \file{README.md}{\from{\pkgname.dtx}{readme}}%
224 \file{INSTALL.md}{\from{\pkgname.dtx}{install}}%
225 \usepostamble\defaultpostamble
226 \file{\pkgname.tex}{\from{\pkgname.dtx}{tex}}%
227 \usepreamble\pkgpreamble
228 \file{\pkgname.sty}{\from{\pkgname.dtx}{package}}}%
229 \endgroup
230 \fi % end of file extraction (from etex/latex/pdflatex run)
231 \ifnum\extractfiles=0 % tex/etex/xetex/etc files extracted, stop
232 \MessageDeFin\expandafter\end
233 \fi
234 % From this point on, run is necessarily with e-TeX.
235 % Check if \MessageDeFin got defined, if yes put it at end of run.
236 \ifdefined\MessageDeFin\AtEndDocument{\MessageDeFin}\fi
237 %-------------------------------------------------------------------------------
238 % START OF USER MANUAL TEX SOURCE
239 \documentclass[abstract]{scrdoc}
240
241 \ifnum\NoSourceCode=1 \OnlyDescription\fi
242
243 \usepackage{ifpdf}
244 \ifpdf\chardef\Withdvipdfmx 0 \fi
245
246 \makeatletter
247 \ifnum\Withdvipdfmx=1
248 \@for\@tempa:=hyperref,bookmark,graphicx,xcolor,pict2e\do
249 {\PassOptionsToPackage{dvipdfmx}\@tempa}
250 %
251 \PassOptionsToPackage{dvipdfm}{geometry}
252 \PassOptionsToPackage{bookmarks=true}{hyperref}
253 \PassOptionsToPackage{dvipdfmx-outline-open}{hyperref}
254 \PassOptionsToPackage{dvipdfmx-outline-open}{bookmark}
255 %
256 \def\pgfsysdriver{pgfsys-dvipdfm.def}
257 \else
258 \PassOptionsToPackage{bookmarks=true}{hyperref}
259 \fi
260 \let\original@check@percent\check@percent
261 \let\check@percent\relax
262 \makeatother
263
264 \usepackage[T1]{fontenc}
265 \usepackage[utf8]{inputenc}
266 \usepackage[hscale=0.66,vscale=0.75]{geometry}
267 \pagestyle{headings}
268
269 \def\MacroFont{\ttfamily\small\hyphenchar\font45 \baselineskip11pt\relax}
270 \AtBeginDocument{\def\MacroFont{\ttfamily}}
271
272 % ATTENTION: (avec doc.sty ou les classes scrdoc ou ltxdoc)
273 %
274 % - l'environnement macrocode se fait avec \macro@font qui est le
275 % \MacroFont du \begin{document}.
276 %
277 % - les environnements verbatim utilisent le \MacroFont courant.
278 %
279 % - \verb utilise un \ttfamily !! et non pas \verbatim@font que l'on
280 % peut customiser.
281 %
282 % - (9 mars 2015) il ne faut PAS commencer des macrocode directement après
283 % un \section, il faut un paragraphe (par exemple un \indent\par)
284
285 \usepackage{xspace}
286 \usepackage[dvipsnames]{xcolor}
287
288 \definecolor{joli}{RGB}{225,95,0}
289 \definecolor{JOLI}{RGB}{225,95,0}
290
291 \newcommand\fcdname{%
292 \texorpdfstring{{\color{joli}\ttfamily\bfseries \pkgname}}{\pkgname}\xspace}
293
294 \DeclareRobustCommand\csa[1]{{\ttfamily\hyphenchar\font45 \char`\\ #1}}
295
296 \newcommand\csh[1]{\texorpdfstring{\csa{#1}}{\textbackslash\detokenize{#1}}}
297
298 \usepackage{babel}
299
300 \usepackage[pdfencoding=pdfdoc]{hyperref}
301 \hypersetup{%
302 linktoc=all,%
303 %% bookmarksdepth=3,%
304 breaklinks=true,%
305 colorlinks,%
306 linkcolor=OliveGreen,%RoyalBlue,%
307 urlcolor=RoyalBlue,%OliveGreen,%
308 pdfauthor={Jean-Fran\c cois Burnol},%
309 pdftitle={The \pkgname\space package},%
310 pdfsubject={\pkgdescription},%
311 pdfkeywords={LaTeX, verbatim, macros},%
312 pdfstartview=FitH,%
313 pdfpagemode=UseOutlines}
314 \usepackage{bookmark}
315
316 \usepackage[zerostyle=a,scaled=0.95,straightquotes]{newtxtt}
317 \renewcommand\familydefault\sfdefault
318 \frenchspacing
319
320 \usepackage{framed}
321
322 %\usepackage{varioref}
323
324 %\usepackage{footnotehyper}
325
326 \usepackage{filecontentsdef}
327
328 \makeatletter
329 % \hbox needed since change to \smash and other macros at LaTeX 2018/12/01
330 \def\NewWith #1{\@bsphack
331 \vadjust{\vskip-\dp\strutbox
332 \hbox{\smash{\hbox to 0pt {\hss\color[named]{Thistle}%
333 \normalfont\small\bfseries
334 \hsize 2.5cm\rightskip.5cm minus.5cm
335 \vtop{\noindent New with #1}\kern.25cm }}}%
336 \vskip\dp\strutbox }\strut\@esphack}
337 \def\ChangedAt #1{\@bsphack
338 \vadjust{\vskip-\dp\strutbox
339 \hbox{\smash{\hbox to 0pt {\hss\color[named]{Thistle}%
340 \normalfont\small\bfseries
341 \hsize 2.5cm\rightskip.5cm minus.5cm
342 \vtop{\noindent Changed at #1}\kern.25cm }}}%
343 \vskip\dp\strutbox }\strut\@esphack}
344 \makeatother
345
346 \begin{document}
347 \rmfamily
348 \thispagestyle{empty}
349
350 \bookmark[named=FirstPage,level=1]{Title page}
351
352 %\ttzfamily
353
354 {%
355 \normalfont\Large\parindent0pt \parfillskip 0pt\relax
356 \leftskip 2cm plus 1fil \rightskip 2cm plus 1fil
357 The \fcdname package\par
358 }
359
360 {\centering
361 \textsc{Jean-François Burnol}\par
362 \footnotesize
363 jfbu (at) free (dot) fr\par
364 Package version: \pkgversion\ (\pkgdate);
365 documentation date: \pkgdocdate.\par
366 {From source file \texttt{\pkgname.dtx (\dtxtimestamp)}}\par
367 }
368
369 \begin{abstract}
370 This lightweight LaTeX2e package provides an environment
371 |filecontentsdef| which is like the |filecontents|
372 environment of \textsc{Scott Pakin}'s
373 \href{https//ctan.org/pkg/filecontents}{filecontents} package but in
374 addition to the file creation stores the (verbatim) contents into a
375 macro given as an additional argument (either as a control sequence or
376 as a name).
377
378 Displaying verbatim these contents is possible via
379 |\filecontentsprint|, and executing them (if they represent LaTeX
380 code) via |\filecontentsexec|.
381
382 A variant environment |filecontentsdefmacro| stores the contents into
383 a macro, but skips the save-to-a-file part.
384
385 I developed this to display \TeX\ code verbatim in documentation
386 and simultaneously produce during the LaTeX run the corresponding
387 files in order to embed them in the PDF as \emph{file attachment
388 annotations} (via the services of \textsc{Scott Pakin}'s
389 further package
390 \href{https://ctan.org/pkg/attachfile}{attachfile}.)
391 \end{abstract}
392
393 \tableofcontents
394
395 \section{Environments and macros}
396
397 \subsection{\textcolor[named]{PineGreen}{\texttt{filecontentsdef}},
398 \textcolor[named]{PineGreen}{\texttt{filecontentsgdef}}}
399
400 The |filecontentsdef| environment is like |filecontents| but
401 requires a second argument. This argument will either be:
402 \begin{itemize}
403 \item a single control sequence token such as |\foo|,
404 \item or anything else which then must after expansion be
405 usable as a macro \emph{name} (it will be handled via
406 |\csname...\endcsname| encapsulation).
407 For example \texttt{\string\myitemnumber\{3\}} can be used as argument and
408 it will then be expanded inside \texttt{\string\csname...\string\endcsname}
409 to construct a control sequence, whose name will possibly contain digits or
410 other characters of non-letter catcodes. A single active character is
411 allowed as long as its expansion is
412 \texttt{\string\csname...\string\endcsname} compatible; the character itself
413 will \emph{not} be assigned a new meaning.
414 \end{itemize}
415
416 Thus the syntax is either:
417 \begin{verbatim}
418 \begin{filecontentsdef}{<filename>}{\foo}
419 ... arbitrary contents ...
420 \end{filecontentsdef}
421 \end{verbatim}
422 or:
423 \begin{verbatim}
424 \begin{filecontentsdef}{<filename>}{(expanding to) macro name}
425 ... arbitrary contents ...
426 \end{filecontentsdef}
427 \end{verbatim}
428
429 The environment creates the file and stores its (verbatim) contents into its
430 second argument |\foo| (or into the macro |\<macro name>| with given name).
431
432 \begin{framed}
433 Hint: if some |\foo| contains the \emph{name} of the macro to be defined, use
434 |\empty\foo| as argument, thus avoiding |\foo| itself to get overwritten by
435 the environment.
436 \end{framed}
437
438 \begin{enumerate}
439 \item The starred variant |filecontentsdef*| acts like
440 |filecontents*| environment regarding the file contents, i.e.
441 it drops addition of a (\TeX) commented out header.
442 \item |filecontentsdefstarred| is an alias for
443 |filecontentsdef*|.\NewWith{v1.5}
444 \item The contents put into the macro are the same for the starred and
445 non-starred environments: neither contains a commented-out header.
446 \item The scope of the macro definition is
447 \textbf{local}.\ChangedAt{v1.5}
448 \item
449 Use |filecontentsgdef| for a definition with global scope.\NewWith{v1.5}
450 \item No check is done on whether the defined macro pre-existed.
451 \item The macro holds a verbatim rendering of the contents, with active spaces
452 and active |^^M| tokens.
453 \item The handling of the\NewWith{v1.5}
454 Form Feed and Tabulation characters can be, contrarily to the |filecontents|
455 treatment, customized. See \autoref{sec:tab}.
456 \item Babel shorthands will be neutralized the same way they are when
457 encountered in a verbatim environment or in a |filecontents|
458 environment. Their action is reactivated if the macro (assuming the
459 contents represent \LaTeX\ code) gets later executed via
460 \csa{filecontentsexec}.
461 \item The environment can be used either in the preamble or the body
462 of the document.
463 \item The contents must not contain themselves a
464 \texttt{\string\end}|{filecontentsdef}| (or \texttt{\string\end}|{filecontentsdef*}| in the
465 starred case).
466 % problème avec Emacs/AUCTeX et |\end{...}| qui fait boguer le fontlock
467 % bizarrement le deuxième ne pose pas de problème. 19 avril 2019.
468 \end{enumerate}
469
470 \begin{footnotesize}
471 Here are some additional relevant details:
472 \begin{enumerate}
473 \item the usual special characters are sanitized like they would be in a
474 verbatim environment,
475 \item the space becomes the active character of ascii code |32|,
476 \item the end of line is converted into the active character |^^M| (i.e. ascii
477 code |13|),
478 \item see \autoref{sec:tab} for the handling of the horizontal tabulation
479 and form feed characters,
480 \item the active bytes of ascii code between |128| and |255| (this is now
481 systematically the case with |inputenc+utf8| being default) are stored
482 into the produced macro ``as is'',
483 \item the non-active bytes of ascii code between |128| and |255| are
484 stored into the produced macro with catcode letter.
485 \end{enumerate}
486 These last two items together mean that 8bit or UTF8-encoded characters will
487 display as expected in a verbatim rendering, see \csa{filecontentsprint} next.
488 \par
489 \end{footnotesize}
490
491 \subsection{\textcolor[named]{PineGreen}{\texttt{filecontentsdefmacro}},
492 \textcolor[named]{PineGreen}{\texttt{filecontentsgdefmacro}}}
493
494 This environment
495 \begin{verbatim}
496 \begin{filecontentsdefmacro}{\foo or macro name}
497 ... arbitrary contents ...
498 \end{filecontentsdefmacro}
499 \end{verbatim}
500 was added at |v1.4|. It is like |filecontentsdef| without the
501 ``save to file'' part... and has thus a sole mandatory argument which may be
502 either a control sequence or a name (or material expanding to name), as
503 previously described. The macro can then be either printed verbatim via
504 \csa{filecontentsprint} or, if it consists of \LaTeX\ code, be executed in
505 re-tokenized form via \csa{filecontentsexec}.
506
507 Its name is thus a bit paradoxical but was chosen to share an existing prefix
508 with the other package macros and environments.
509
510 \subsection{\textcolor[named]{PineGreen}{\csh{filecontentsprint}},
511 \textcolor[named]{PineGreen}{\csh{FCDprintenvname}},
512 \textcolor[named]{PineGreen}{\csh{FCDprintenvoptions}}}
513
514
515 \csa{filecontentsprint} has a
516 unique mandatory argument which will be either:
517 \begin{itemize}
518 \item a single control sequence token (for example |\foo|),
519 \item or anything else which then must after expansion be
520 usable as a macro \emph{name} (for example |macro|). It will be handled via
521 |\csname...\endcsname| encapsulation (see earlier explanations).%
522 \end{itemize}
523 The |\foo| must be of the type constructed by the environments
524 |filecontentsdef| or |filecontentsdefmacro|. It will be then be printed exactly as
525 \begingroup\makeatletter\def\x{\let\@xverbatim\relax
526 \verbatim
527 \string\begin\string{verbatim\string}\par
528 <contents of \string\foo>\par
529 \string\end\string{verbatim\string}\par
530 \endverbatim%
531 \endgroup}\x
532 would have done.
533
534 This uses underneath the |verbatim| environment and has been
535 tested to be compatible with the standard |verbatim|, with the one from
536 package \href{http://www.ctan.org/pkg/doc}{doc} (classes |ltxdoc.cls|,
537 |scrdoc.cls|) and also with the one from package
538 \href{http://www.ctan.org/pkg/verbatim}{verbatim} (whose mechanism is quite
539 different from the one of the default |verbatim| environment.)
540
541 \begin{framed}
542 Due to limitation of the |verbatim| environment, the
543 \texttt{\string\end}|{verbatim}| must not appear inside the contents... else
544 it will be misconstrued as ending the external |verbatim| environment itself
545 which is added by \csa{filecontentsprint}!
546
547 This limitation only
548 affects \csa{filecontentsprint}, not \csa{filecontentsexec}.
549 \end{framed}
550
551 The name of the used environment is held in macro
552 \textcolor[named]{PineGreen}{\csa{FCDprintenvname}}.\NewWith{v1.5}
553 Redefine it to modify the environment name from its default |verbatim|.
554
555 Furthermore\NewWith{v1.5} the macro
556 \textcolor[named]{PineGreen}{\csa{FCDprintenvoptions}} can be used to pass
557 options to that environment.
558
559 Here is a set-up using |fancyvrb| which I tested with success:
560 \begin{verbatim}
561 \documentclass{article}
562 \usepackage{filecontentsdef}
563 \usepackage{xcolor}
564 \usepackage{fancyvrb}
565 \usepackage{fvextra}
566
567 % store tabs as active characters so they can be handled by fancyvrb
568 {\catcode`\^^I=\active\gdef\FCDtabtomacro{\noexpand^^I}}
569
570 % Use fancyvrb Verbatim environment
571 \renewcommand*\FCDprintenvname{Verbatim}
572
573 % with these options. This will be submitted to an \edef, so we
574 % simply wrap in \unexpanded to avoid problems
575 \renewcommand*\FCDprintenvoptions{%
576 \unexpanded{[fontsize=\scriptsize, highlightlines={1, 3-4},
577 numbers=both, showspaces, spacecolor=red,
578 showtabs, %tab=\rightarrowfill% incompatible with linebreaks?
579 breaklines,breakbefore=\\\space]}%
580 }
581 \begin{filecontentsdefmacro}{\testfancyvrb}
582 some contents with long lines and tabs to test the options
583 \end{filecontentsdefmacro}
584 \end{verbatim}
585
586 Here is now a set-up with |minted| which worked also (although the syntax
587 highlighting was not handling correctly control sequences using the @ letter,
588 but I am not knowledgeable enough in the Pygmentize library):
589
590 \begin{verbatim}
591 \documentclass{article}% needs shell-escape
592 \usepackage{filecontentsdef}
593 \usepackage{minted}
594 \newminted{tex}{linenos}
595
596 \renewcommand*\FCDprintenvname{texcode}
597
598 \begin{filecontentsdefmacro}{\testminted}
599 some TeX macros
600 \end{filecontentsdefmacro}
601
602 \begin{document}
603 \filecontentsprint\testminted
604 \end{document}
605 \end{verbatim}
606
607 \subsection{\textcolor[named]{PineGreen}{\csh{filecontentsprintviascan}}}
608
609 It is not possible to use a |listings| environment via \csa{filecontentsprint}
610 and \csa{FCDprintenv}, because |listings| has a special way to identify where
611 it ends and this is incompatible with the \csa{filecontentsprint} approach.
612
613 At |v1.5|
614 \csa{filecontentsprintviascan} is added\NewWith{v1.5} which is more powerful
615 than \csa{filecontentsprint} as it should work not only with verbatim
616 environments known to be compatible with \csa{filecontentsprint} but
617 also with environments of the |listings| type. But this requires \eTeX{}
618 \csa{scantokens} (it uses \csa{filecontentsexec}, see next).%
619 %
620 \footnote{I know that the \LaTeX{} kernel itself requires \eTeX{} for a few
621 years now, but \fcdname could have been installed on an old machine...}
622
623 Here is an example of usage which worked for me (although the syntax
624 highlighting, like the one from |minted|, was not fully satisfying):
625
626 \begin{verbatim}
627 \documentclass{article}
628 \usepackage{filecontentsdef}
629 \usepackage{xcolor}
630 \usepackage{listings}
631 \lstnewenvironment{latexverbatim}
632 {\lstset{
633 basicstyle=\small\ttfamily,
634 breaklines=true,
635 columns=fullflexible,
636 language=[LaTeX]TeX,
637 numbers=left,
638 numbersep=1em,
639 numberstyle=\tiny\color{gray},
640 keywordstyle=\color{red}}}{}
641
642 \renewcommand*\FCDprintenvname{latexverbatim}
643
644 \begin{document}
645
646 \begin{filecontentsdefmacro}{\testlistings}
647 \gdef\filecontentsprintviascan{\FCD@get\FCD@printviascan}%
648 \gdef\FCD@printviascan#1{%
649 \toks@\expandafter{#1}%
650 \edef\FCD@envwithcontents{%
651 \noexpand\begin{\FCDprintenvname}\FCDprintenvoptions\noexpand^^M%
652 \the\toks@\@backslashchar end{\FCDprintenvname}\noexpand^^M}%
653 \FCD@exec\FCD@envwithcontents}%
654 \end{filecontentsdefmacro}
655
656 \filecontentsprintviascan\testlistings
657 \end{document}
658 \end{verbatim}
659
660 \subsection{\textcolor[named]{PineGreen}{\csh{filecontentsexec}}}
661
662 Although \fcdname itself generally does not require \eTeX, it provides as a
663 convenience \csa{filecontentsexec} which
664 does require it as it uses |\scantokens| to re-assign the current catcode
665 regime to the verbatimized tokens stored into its mandatory argument. Again
666 the mandatory argument may have one of the two forms described previously.
667
668 And of course this assumes that the tokens provide legitimate \LaTeX\ code.
669
670 \begin{footnotesize}
671 \textbf{TeX-hacker note:} No group is used in order to not create an extra
672 scoping of the executed macro contents.
673
674 \textbf{TeX-hacker note:} In the case of storage in a macro of some \LaTeX{}
675 contents, and re-parsing via |\filecontentsexec| which uses
676 |\scantokens|, the last line before the
677 \texttt{\string\end}|{filecontentsdef}|
678 or |\end{filecontentsdefmacro}| potentially generates an end of line
679 character, typically a space token (but this depends on the
680 \csa{endlinechar} valid at this location
681 setting). Such a space coming from the last end of line has no impact if
682 the \LaTeX{} contents get executed in vertical mode. In horizontal mode it
683 will be avoided if these contents end with a |%|
684 or also with some control sequence such as a |\relax| or
685 |\empty| (only if \csa{endlinechar} is standard).
686
687 At |v1.5|\NewWith{v1.5} a special convention is added that if the
688 \texttt{\string\end}|{filecontentsdef}| (or variants) stands on
689 the same line as the last line of the contents, rather than being on
690 a line of its own, then the stored contents will get postfixed with
691 an added \csa{empty} token. Thus execution via
692 \csa{filecontentsexec} in horizontal mode will not induce any ending
693 space token (assuming the \csa{endlinechar} is then at its standard
694 setting). This feature is to be used only with contents representing
695 \TeX{} macros, as the \csa{empty} makes sense only in that context.
696 This token will remain invisible in the PDF output from
697 \csa{filecontentsprint}.
698
699 No \csa{empty}
700 gets added to the last line of the exported file (if there is one).
701 The original |filecontents| environment issues a warning when there is
702 contents before the end of the environment on the same line, this warning is
703 now skipped.\ChangedAt{v1.5}
704
705 This extra \csa{empty}
706 added only under such special usage of the environment is not currently
707 customizable, but I can add such a feature if there is a user request.
708
709 \textbf{TeX-hacker note:} one should not think that using
710 \csa{filecontentsexec} with some stored material will behave like copying
711 pasting that material directly at that very location of the source code: for
712 example if the last line ends with a |%|
713 this does not mean that this will comment out what is next in the source
714 code on the same line after the \csa{filecontentsexec}! It is more analogous
715 to making first a macro definition with the contents and then execute that
716 macro. But it is not possible for some macro from inside these contents to
717 itself grab tokens coming next after the \csa{filecontentsexec}\csa{foo}
718 (moreover, \fcdname adds tokens of its own in order restore the
719 \csa{newlinechar}).
720
721
722 \end{footnotesize}
723
724 \subsection{\textcolor[named]{PineGreen}{\texttt{filecontentshere}}}
725
726 This environment
727 \begin{verbatim}
728 \begin{filecontentshere}{<filename>}
729 ... arbitrary contents ...
730 \end{filecontentshere}
731 \end{verbatim}
732 creates on the fly a file with these contents, and simultaneously
733 it typesets them in a verbatim environment. It is a shortcut to doing
734 \begin{verbatim}
735 \begin{filecontentsdef}{<filename>}{\filecontentsheremacro}
736 ... arbitrary contents ...
737 \end{filecontentsdef}
738 \end{verbatim}
739 and then immediately
740 \begin{verbatim}
741 \filecontentsprint\filecontentsheremacro
742 \end{verbatim}
743 The |\filecontentsheremacro| is then available for usage as argument
744 of |\filecontentsexec|. Since |v1.5| its definition has only
745 local scope.
746 \ChangedAt{v1.5}
747
748 The environment has a starred variant
749 |filecontentshere*| (also |filecontentsherestarred|) which does the
750 expected thing.
751
752 For example
753 \begin{verbatim}
754 \begin{filecontentshere*}{\jobname.test}
755 \begin{framed}
756 \noindent
757 We have coded this in \LaTeX: both
758 $E=mc^2$ (input as \verb|$E=mc^2$|)
759 and $E=h\nu$ owe much to \textsc{Albert Einstein}.
760 \end{framed}
761 \end{filecontentshere*}
762 \filecontentsexec\filecontentsheremacro
763 \end{verbatim}
764 will produce an external file with the above contents and have this
765 effect in the document (verbatim framed then real framed):
766 \begin{filecontentshere*}{\jobname.test}
767 \begin{framed}
768 \noindent
769 We have coded this in \LaTeX: both
770 $E=mc^2$ (input as \verb|$E=mc^2$|)
771 and $E=h\nu$ owe much to \textsc{Albert Einstein}.
772 \end{framed}
773 \end{filecontentshere*}
774 \filecontentsexec\filecontentsheremacro
775
776 \section{How to wrap usage of \texttt{filecontentsdef} in another
777 environment}
778
779 Don't use the |\begin/\end| syntax but directly
780 |\begingroup\filecontentsdef{..}{..}| and |\endfilecontentsdef\endgroup|.
781 And these should come last, respectively first, in the definition of the
782 begin, respectively end, part of the new environment.
783
784 The extra |\begingroup...\endgroup| are mandatory with the
785 \fcdname environments making a local scope definition.\ChangedAt{v1.5}
786
787 For those creating global scope macros, |\begingroup...\endgroup|
788 is recommended, as the \LaTeX{} state is not completely clean
789 after |\endfilecontentsgdef| (et al.) execution. Thus it is
790 better to have the extra |\begingroup...\endgroup| pair always
791 (which are a part of the things added by the |\begin/\end| syntax).
792
793 For wrapping the starred variant one needs to use
794 |\csname filecontentsdef*\endcsname|, or make the definition with |*|
795 having catcode letter. A simpler way is to use the alias ending
796 in |...starred|.\NewWith{v1.5} Regarding the ending macro its
797 name can drop the |*|, as the starred environments defined by the
798 \fcdname package use the same ending macros as their non-starred
799 variants.
800
801 As exercise, let's imagine we want an environment which will be associated
802 to some counter, will automatically increment it at each usage, and will
803 use this counter to index the files and macros created on each
804 invocation.
805 Except if you know how to smuggle how a macro from an environment
806 you probably want to use |filecontentsgdef| in order for the
807 macro to have global scope.
808 \begin{filecontentsdefmacro}{\pablo}
809 \newcounter{pablo}
810 \newenvironment{defexercise}
811 {\stepcounter{pablo}%
812 \begingroup
813 \filecontentsgdefstarred
814 {\jobname-ex\the\value{pablo}}{exercise-\the\value{pablo}}}%
815 {\endfilecontentsgdefstarred\endgroup}
816 \newcommand{\printexercise}[1]{\filecontentsexec{exercise-\the\numexpr#1\relax}}
817 \end{filecontentsdefmacro}
818 \filecontentsprint\pablo
819 \filecontentsexec\pablo
820
821 We can then use it this way:
822 \begin{filecontentsdefmacro}{\usepablo}
823 \begin{defexercise}
824 Prove that \[x^n+y^n=z^n\] is not solvable in positive integers if $n$ is at
825 most $-3$.\par
826 \end{defexercise}
827 \begin{defexercise}
828 Refute the existence of black holes in less than 140 characters.\par
829 \end{defexercise}
830 \begin{defexercise}
831 \def\NSA{NSA}%
832 Prove that factorization is easily done via probabilistic algorithms and
833 advance evidence from knowledge of the names of its employees in the
834 seventies that the \NSA\ has known that for 40 years.\par
835 \end{defexercise}
836 \begin{itemize}
837 \item \printexercise{3}
838 \item \printexercise{2}
839 \item \printexercise{1}
840 \end{itemize}
841 \end{filecontentsdefmacro}
842 \filecontentsprint\usepablo
843
844 This produces in the document:
845 \filecontentsexec\usepablo
846 Additionally, three small files were created containing the \LaTeX\ mark-up
847 for each exercise.
848
849
850 \section{How to customize handling of tabulation and form feed characters}
851 \label{sec:tab}
852
853 \LaTeX{} assigns catcode 10 by default to |^^I| meaning that it is handled by
854 default as a space character:
855 \begin{filecontentsdefmacro}{\coucou}
856 \def\test{^^I}
857 \ifx\test\space \textcolor{blue}{OK}\else \ERROR\fi
858 \end{filecontentsdefmacro}
859 \filecontentsprint\coucou
860 \filecontentsexec\coucou
861
862 But \fcdname like the original |filecontents| environment assigns active
863 catcode to the tabulation character before parsing the contents. This allows
864 special treatment.
865
866 \begin{framed}
867 Attention that if input as |^^I| (in opposition to the real ascii character
868 of ascii code 9), it will end up simply as |^^I| in external file or macro,
869 because the caret loses its special meaning in the environment.
870
871 The discussion in this section about customizing \fcdname behaviour applies
872 only to a source with a real tabulation character, not one in \TeX{} notation
873 |^^I|.
874 \end{framed}
875
876 With
877 |v1.5|, \fcdname diverges from original |filecontents| by adding the means to
878 customize the handling of such tabulation character, rather than simply raising
879 a warning and exporting it as a space like original |filecontents|. And also
880 the handling of the form feed character can be customized.
881
882 This is controlled via four control sequences whose default definitions are
883 the following:\NewWith{v1.5}
884 \begin{verbatim}
885 \def\FCDtabtofile{ }%
886
887 {\catcode32\active\gdef\FCDtabtomacro{\noexpand }}%
888
889 \def\FCDformfeedtofile{^^J^^J}%
890
891 {\catcode`\^^M\active\gdef\FCDformfeedtomacro{\noexpand^^M\noexpand^^M}}%
892 \end{verbatim}
893
894 Each of \csa{FCDtabtofile}, \csa{FCDtabtomacro},
895 \csa{FCDformfeedtofile}, \csa{FCDformfeedtomacro} gets used via an
896 expansion inside an \csa{edef}, hence the need for \csa{noexpand} in front
897 of active characters. The |^^J| in \csa{FCDformfeedtofile} matches
898 the default newline character (ascii code 10) of \LaTeX{} for
899 exporting files. The active |^^M| is used for macro storage
900 because this is the most suitable for verbatim printing via
901 \csa{filecontentsprint} as typically in a verbatim environment end
902 of lines get converted into such active |^^M| (which will create
903 a |\par| token).
904
905 If you want for example tabulation characters to get converted into four
906 spaces, use:
907 \begin{verbatim}
908 \def\FCDtabtofile{\space\space\space\space}%
909 {\catcode32\active\gdef\FCDtabtomacro{\noexpand \noexpand \noexpand \noexpand }}%
910 \end{verbatim}
911 I have here used for macro storage active spaces. The \csa{noexpand} are
912 mandatory in such case, but they will disappear from stored contents in a
913 macro. We could also have defined \csa{FCDtabtofile} as an alias to
914 \csa{FCDtabtomacro} here because a non-expanding active space will simply give a
915 space in the external file. Due to \TeX{} tokenization rules
916 |\def\FCDtabtofile{ }| would be the same as with only one single space and
917 thus we used |\space\space\space\space|.
918
919 If you want an actual tabulation character stored to a file, use:
920 \begin{verbatim}
921 {\catcode`\^^I=12 \gdef\FCDtabtofile{^^I}}
922 \def\FCDtabtomacro{TAB}
923 \end{verbatim}
924 The second line is for demonstration only as an example of how to store the
925 tabulation character in a macro, use anything adequate to replace \texttt{TAB}
926 as used here. For example you can store in it the actual tabulation (ascii code
927 9) with catcode 12, via using rather |\let\FCDtabtomacro\FCDtabtofile| in the
928 above. Or use some Unicode symbol and appropriate font configuration.
929
930 Here is an example. This is rendered via |verbatim| which will treat the
931 tabulation characters as spaces, but they are there in the original:
932 \begin{verbatim}
933 {\catcode`\^^I=12 \gdef\FCDtabtofile{^^I}}
934 \let\FCDtabtomacro\FCDtabtofile
935 \begin{filecontentshere}{\jobname-tab.test}
936 Here is a tab and then three in a row .
937 \end{filecontentshere}
938 (we will see them in the PDF output via the glyph at slot 9 of the T1 encoding).
939 \end{verbatim}
940 Here is what the original produces indeed when executed:
941 {\catcode`\^^I=12 \gdef\FCDtabtofile{^^I}}
942 \let\FCDtabtomacro\FCDtabtofile
943 \begin{filecontentshere}{\jobname-tab.test}
944 Here is a tab and then three in a row .
945 \end{filecontentshere}
946 The way it looks in the PDF is due to our definition of \csa{FCDtabtomacro}
947 which gives a catcode12 character of ascii code 9, and we use T1
948 font-encoding. The exported file does contain on the other hand as promised a
949 real tabulation character.
950
951 \begin{footnotesize}
952 \begin{framed}
953 \LaTeX{} since 2018 uses by default |\usepackage[utf8]{inputenc}| and
954 almost all control characters are given active catcode. Exceptions: |^^@|
955 (illegal), |^^I| (treated as space), |^^J| (for some reason it gets catcode
956 12 and thus will if printed to PDF give the glyph at slot 10 of the font
957 encoding), and |^^M| (end of line).
958
959 Notice that such a control character which in the source gets input using
960 \TeX{} notation, for example |^^P|, causes no issue to \fcdname as the
961 caret |^| has lost its special catcode. Thus a |^^P| will be printed to
962 external file.
963
964 If one tries to use directly in the source the CTRL-P, an error will be
965 raised by \LaTeX{} triggered by the active character (\fcdname does not
966 sanitize catcodes in this ascii range, as original |filecontents|
967 environment does not either).
968
969 One can always reassign catcodes, thus you can set the catcode of |^^P| to
970 12 for example. However, when exporting such a control character with
971 catcode 11 or 12 to a file, pdflatex uses |^^| notation in the output.
972 There are three exceptions (with |pdflatex|): the horizontal tabulation (ascii code 9,
973 |^^I|), the line feed (ascii code 10, |^^J|), and vertical tabulation
974 (ascii code 11, |^^K|) are exported to the file as the corresponding ascii
975 characters (at least this is the case with \TeX Live). \emph{These
976 exceptions do not apply with} |xelatex|.
977
978 Thus we again end up with \TeX{} notation |^^P| in the exported file. To
979 get a literal CTRL-P, you need to set the catcode of |^^P| to 11 or 12, and
980 to run |pdflatex| with the |-8bit| option. With Xe\LaTeX, this would be
981 needed even for the horizontal tabulation CTRL-I.
982 \end{framed}
983 \end{footnotesize}
984
985 \begin{footnotesize}
986
987 \section{How to obtain customized verbatim in the output}
988
989 Please refer first to the discussion of \csa{filecontentsprint} and
990 \csa{filecontentsprintviascan} as it provides examples using |fancyvrb|,
991 |minted|, or |listings| environments which may be what you are looking for.
992
993 Here we make quick comments on alternatives to using \csa{filecontentsprint},
994 and handling directly the contents via the configuration of active spaces and
995 active end of lines.
996
997 Here is
998 some (non-\LaTeX) text snippet.
999 \begin{verbatim}
1000 \begin{filecontentsdef}{\jobname.test2}{\testactive}
1001 v1.2 \[2016/09/19\]
1002 -------------------
1003
1004 Initial version.
1005
1006 test: éèàùÉÈÇÀÙÛÎåðñòóôõöœøùúûüýþßŸŽ§
1007 \end{filecontentsdef}
1008 \end{verbatim}
1009
1010 We can expand \csa{testactive} directly inside the \LaTeX\ document, but must
1011 give some definitions to the active space token and the active |^^M| token
1012 like |verbatim| environment does.
1013
1014 For a true verbatim printout \csa{obeyspaces} and \csa{obeylines} are not
1015 enough because spaces at start of lines will disappear, and multiple empty
1016 lines give multiple |\par|'s which collapse into a single one (hence no empty
1017 line can be observed in the output). The usual |verbatim| environment uses a
1018 special definition of |\par| which prevents the disappearance of empty lines,
1019 and for the spaces it has macro \csa{@vobeyspaces} which makes the spaces
1020 issue |\leavevmode| so they are not skipped at the start of lines. Let's
1021 define:
1022 \begin{verbatim}
1023 \makeatletter
1024 % this redefines active spaces, but does not make spaces active
1025 \def\niceactivespaces{\@vobeyspaces\catcode32=10\relax}%
1026 \makeatother
1027 \begingroup
1028 % this redefines active end of lines, but does not make them active
1029 \catcode`\^^M\active %
1030 \gdef\niceactiveCRs{\def^^M{\leavevmode\par}}%
1031 \endgroup %
1032 \end{verbatim}
1033
1034 Then we can issue something like:
1035 \begin{verbatim}
1036 {\setlength{\parindent}{2cm}\niceactivespaces\niceactiveCRs\testactive\par}
1037 \end{verbatim}
1038 This allows hyphenation and ligatures, which are usually inhibited in standard
1039 |verbatim|, and it does not switch to the monospace font. Here is what happens
1040 if we do all of the above, as a test:
1041
1042 \def\testactive{testactive}
1043 \begin{filecontentsdefmacro}{\empty\testactive}
1044 v1.2 \[2016/09/19\]
1045 -------------------
1046
1047 Initial version.
1048
1049 test: éèàùÉÈÇÀÙÛÎåðñòóôõöœøùúûüýþßŸŽ§
1050 \end{filecontentsdefmacro}
1051 \makeatletter
1052 % this redefines active spaces, but does not make spaces active
1053 \def\niceactivespaces{\@vobeyspaces\catcode32=10\relax}%
1054 \makeatother
1055 \begingroup
1056 % this redefines active end of lines, but does not make them active
1057 \catcode`\^^M\active %
1058 \gdef\niceactiveCRs{\def^^M{\leavevmode\par}}%
1059 \endgroup %
1060 {\setlength{\parindent}{2cm}\niceactivespaces\niceactiveCRs\testactive\par}
1061 We see indeed how the |---...--| gave rise to ligatures, and that the
1062 monospace font was not used. This was only to give an idea of how one can use
1063 the macros created by the |filecontentsdef| or |filecontentsdefmacro|
1064 environments for variant verbatim rendering. This technique can be used as
1065 workaround to the problem with \csa{filecontentsprint} that the contents can
1066 not contain \verb|\end{verbatim}|.
1067
1068 \end{footnotesize}
1069
1070 \section{Related packages}
1071
1072 \begin{itemize}
1073 \item Scott~\textsc{Pakin}'s
1074 \href{http://www.ctan.org/pkg/filecontents}{filecontents}. Notice that the
1075 package functionality has been integrated into \LaTeX{} release dated
1076 |2019/10/01|.
1077 \item Pablo~\textsc{González}'s
1078 \href{http://www.ctan.org/pkg/scontents}{scontents}. Make sure your version
1079 is at least |v1.3| as earlier ones had a dependency on \fcdname
1080 and are broken by the changes coming with |filecontentsdef v1.5|.
1081 \end{itemize}
1082
1083
1084 \StopEventually{\end{document}}
1085
1086 \clearpage
1087
1088 \makeatletter
1089 \let\check@percent\original@check@percent
1090 \makeatother
1091
1092 \small
1093
1094 \section{Implementation}
1095
1096 See the \texttt{README.md} file for the \texttt{CHANGE LOG}.
1097
1098 % \indent % !!!!!!!!!!!!!!!!! Lundi 09 mars 2015 à 09:32:22
1099
1100
1101 \makeatletter
1102 \begingroup
1103 \topsep\MacrocodeTopsep
1104 \trivlist\parskip\z@\item[]
1105 \macro@font
1106 \leftskip\@totalleftmargin \advance\leftskip\MacroIndent
1107 \rightskip\z@ \parindent\z@ \parfillskip\@flushglue
1108 \global\@newlistfalse \global\@minipagefalse
1109 \ifcodeline@index
1110 \everypar{\global\advance\c@CodelineNo\@ne
1111 \llap{\theCodelineNo\ \hskip\@totalleftmargin}}%
1112 \fi
1113 \string\NeedsTeXFormat\string{LaTeX2e\string}[1999/12/01]\par
1114 \string\ProvidesPackage\string{\pkgname\string}\par
1115 \noindent\space [\pkgdate\space\pkgversion\space\pkgdescription]\par
1116 \nointerlineskip
1117 \global\@inlabelfalse
1118 \endtrivlist
1119 \endgroup
1120 \makeatother
1121
1122 % The catcode hackery next is to avoid to have <*package> to be listed
1123 % in the commented source code...
1124 % (c) 2012/11/19 jf burnol ;-)
1125
1126 \MakePercentIgnore
1127
1128 %
1129 % \catcode`\<=0 \catcode`\>=11 \catcode`\*=11 \catcode`\/=11
1130 % \let</none>\relax
1131 % \def<*package>{\catcode`\<=12 \catcode`\>=12 \catcode`\*=12 \catcode`\/=12}
1132 %
1133 %</none>
1134 %<*package>
1135 % \begin{macrocode}
1136 \let\FCD@global\global
1137 \begingroup
1138 \catcode`\^^M\active%
1139 % \end{macrocode}
1140 % Attention that all end of lines must now get protected due to
1141 % the end of line character being active.
1142 %
1143 % The \LaTeX{} default for active |^^L| was \csa{outer} up to the |2017-01-01|
1144 % release (got modified in |{v2.3b}{2016/11/06}| version of |ltplain.dtx|).
1145 % But we must still handle that possibility for usage with older formats.
1146 % \begin{macrocode}
1147 \catcode`\^^L\active\let^^L\relax%
1148 \catcode`\^^I\active%
1149 % \end{macrocode}
1150 % \csa{FCD@main} is the core construct.
1151 %
1152 % Bulk of the code is still identical to the one in \textsc{Scott Pakin}'s
1153 % \href{http://www.ctan.org/pkg/filecontents}{filecontents} hence to the
1154 % original one in \LaTeX's sources regarding \csa{filec@ntents}, as
1155 % |filecontentsdef| was conceived as an extension of the original
1156 % |filecontents| environment, with the added feature of storing the
1157 % verbatimized contents in a \TeX{} macro, which can then be printed (verbatim)
1158 % or re-tokenized later via \csa{scantokens} and executed (if it represents
1159 % \LaTeX{} material). Starting with |v1.5| some renaming of internal macros
1160 % appears and the original coding is not only extended but starts being
1161 % modified at some places as well.
1162 %
1163 % |v1.4| adds \csa{filecontentsdefmacro} which does not write to a file.
1164 %
1165 % |v1.5| renames all internal macros to use |\FCD@| namespace prefix. This
1166 % applies here to \csa{FCD@main} whose name was still \csa{filec@ntentsdef} at
1167 % |v1.4|. The change also applies to the \csa{reserved@b} and \csa{reservec@c}.
1168 %
1169 % |v1.5| adds customizability of how tabulation and form feed characters are
1170 % handled either in file output or in macro storage.
1171 %
1172 % |v1.5| modifies |filecontentsdef| to only make a definition with local
1173 % scope. For this we must smuggle out of the environment both the name and the
1174 % meaning of the control sequence to define. We prepare for this a
1175 % \csa{FCD@defmacro} which gets executed via |\endfilecontentsdef| (and
1176 % variants). As \csa{FCD@defmacro} issues \csa{endgroup}, direct usage of
1177 % \csa{filecontentsdef} (not as environment) must be inside an explicit
1178 % \csa{begingroup}/\csa{endgroup} pair, mimicking the one which an environment
1179 % would insert.
1180 %
1181 % The |filecontentsgdef/filecontentsgdefmacro| environments do define
1182 % \csa{FCD@defmacro} but do not execute it.
1183 % \begin{macrocode}
1184 \gdef\FCD@main#1#2{%
1185 \def\FCD@defmacro%
1186 {\toks@\expandafter{#2}%
1187 \edef\x{\endgroup\def\noexpand#2{\the\toks@}%
1188 \begingroup\def\noexpand\@currenvir{\@currenvir}}%
1189 \x}%
1190 \FCD@global\let#2\@empty%
1191 \if@filesw%
1192 \openin\@inputcheck#1 %
1193 \ifeof\@inputcheck%
1194 \@latex@warning@no@line%
1195 {Writing file `\@currdir#1'}%
1196 \else%
1197 \@latex@warning@no@line%
1198 {Overwriting file `\@currdir#1'}%
1199 \fi%
1200 \closein\@inputcheck%
1201 \chardef\FCD@reserved@c15 %
1202 \ch@ck7\FCD@reserved@c\write%
1203 \immediate\openout\FCD@reserved@c#1\relax%
1204 \if@tempswa%
1205 \immediate\write\FCD@reserved@c{%
1206 \@percentchar\@percentchar\space%
1207 \expandafter\@gobble\string\LaTeX2e file `#1'^^J%
1208 \@percentchar\@percentchar\space generated by the %
1209 `\@currenvir' \expandafter\@gobblefour\string\newenvironment^^J%
1210 \@percentchar\@percentchar\space from source `\jobname' on %
1211 \number\year/\two@digits\month/\two@digits\day.^^J%
1212 \@percentchar\@percentchar}%
1213 \fi%
1214 \fi%
1215 \let\do\@makeother\dospecials%
1216 % \end{macrocode}
1217 % SP's |filecontents| sets here in the loop all catcodes to |11|, but we
1218 % need for correct rendering in verbatim that the constructed macro
1219 % stores active characters as active characters.
1220 %
1221 % We don't check for unusual active characters of ascii code |<128|
1222 % as this is not done by original or SP's |filecontents|. But if
1223 % present then they will expand similarly both in the |\write| and
1224 % in the construction of the macro.
1225 % \begin{macrocode}
1226 \count@=128\relax%
1227 \loop%
1228 \ifnum\catcode\count@=\active%
1229 \lccode`~\count@%
1230 \lowercase{\def~{\noexpand~}}%
1231 \else%
1232 \catcode\count@=11 %
1233 \fi%
1234 \advance\count@ by \@ne%
1235 \ifnum\count@<\@cclvi%
1236 \repeat%
1237 % \end{macrocode}
1238 % The default active |^^L| was |\outer| up to |2017/01/01|.
1239 % \begin{macrocode}
1240 \let^^L\relax%
1241 \edef\FCD@E{\@backslashchar end\string{\@currenvir\string}}%
1242 \edef\FCD@reserved@b{\def\noexpand\FCD@reserved@b####1\FCD@E####2\FCD@E####3\relax}%
1243 % \end{macrocode}
1244 % \csa{filecontentsdefmacro} sets \csa{if@filesw} to false.
1245 % \begin{macrocode}
1246 \FCD@reserved@b{%
1247 \ifx\relax##3\relax%
1248 \if@filesw%
1249 \let^^L\FCDformfeedtofile%
1250 \let^^I\FCDtabtofile%
1251 \immediate\write\FCD@reserved@c{##1}%
1252 \fi%
1253 % \end{macrocode}
1254 % This is where the original |filecontents| is extended to store the
1255 % parsed material in a macro (in my very first hack I simply
1256 % patched it to redefine |\write| to also do the macro storage, but
1257 % considerations like the one relative to active characters due to
1258 % |inputenc| made me decide to re-write the whole thing, hence make
1259 % a new package.)
1260 %
1261 % Active characters were defined with a single |\noexpand| in the
1262 % loop, and this is enough because after each new line is processed
1263 % the characters it contains are protected from further expansion in
1264 % the |\xdef|'s. And the single |\noexpand| is enough also for the
1265 % |\write| done above.
1266 % \begin{macrocode}
1267 \toks@\expandafter{#2}%
1268 \let^^L\FCDformfeedtomacro%
1269 \let^^I\FCDtabtomacro%
1270 \FCD@global\edef#2{\the\toks@##1\noexpand^^M}%
1271 \else%
1272 \edef^^M{\noexpand\end{\@currenvir}}%
1273 \ifx\relax##1\relax%
1274 \else%
1275 \if@filesw%
1276 % \end{macrocode}
1277 % |v1.5| suppresses the warning issued by |filecontents| environment
1278 % in such case.
1279 % \begin{macrocode}
1280 \let^^L\FCDformfeedtofile%
1281 \let^^I\FCDtabtofile%
1282 \immediate\write\FCD@reserved@c{##1}%
1283 \fi%
1284 % \end{macrocode}
1285 % In such case with the end of environment not being on a line of its own,
1286 % |v1.5| injects an extra |\empty| token at end of last line. Thus
1287 % usage in this form is restricted to contents representing \TeX{} macros.
1288 % We still need the final |^^M| for \csa{filecontentsprint} matters.
1289 % \begin{macrocode}
1290 \toks@\expandafter{#2}%
1291 \let^^L\FCDformfeedtomacro%
1292 \let^^I\FCDtabtomacro%
1293 \FCD@global\edef#2{\the\toks@##1\noexpand\empty\noexpand^^M}%
1294 \fi%
1295 \ifx\relax##2\relax%
1296 \else%
1297 \@latex@warning{%
1298 Ignoring text `##2' after \string\end{\@currenvir}}%
1299 \fi%
1300 \fi%
1301 ^^M}%
1302 % \end{macrocode}
1303 % |v1.4|: sync |^^L| and |^^I| with |2018/04/01| \LaTeX{} release.
1304 %
1305 % |v1.5|: drop the |^^L| and |^^I| \LaTeX{} definitions in favour of
1306 % \csa{FCDformfeedtomacro} etc...
1307 % \begin{macrocode}
1308 \catcode`\^^L\active%
1309 \catcode`\^^I\active%
1310 \catcode`\^^M\active%
1311 \edef^^M##1^^M{\noexpand\FCD@reserved@b##1\FCD@E\FCD@E\relax}%
1312 % \end{macrocode}
1313 % We need active space characters to be active in the produced macro.
1314 % We only need to protect them once from expansion. The definition
1315 % will work both for writing to a file and for storage into the macro.
1316 % \begin{macrocode}
1317 \catcode32\active\lccode`~32 \lowercase{\def~{\noexpand~}}%
1318 }%
1319 \gdef\FCDformfeedtofile{^^J^^J}%
1320 \gdef\FCDformfeedtomacro{\noexpand^^M\noexpand^^M}%
1321 \gdef\FCDtabtofile{ }%
1322 \catcode32\active\gdef\FCDtabtomacro{\noexpand }%
1323 \endgroup%
1324 % \end{macrocode}
1325 % The |v1.4| macros accept a name as alternative to a macro. Empty or
1326 % ill-formed |#2| will break code. But |#2| can be using |\if|, |\else|,
1327 % |\fi| tokens, the whole thing will end up |\csname|-expanded. An active
1328 % character also will end up |\csname|-expanded. There is no check on
1329 % whether |#2| or |\csname#2\endcsname| is an existing macro.
1330 %
1331 % |v1.5| replaces \csa{@tempa,b} by \csa{FCD@tempa,b}. And its
1332 % \csa{FCD@get@aux} directly grabs |#2| rather than issuing \csa{@firstofone}.
1333 % \begin{macrocode}
1334 \long\def\FCD@get@aux#1\FCD@get@aux#2{#2}%
1335 \def\FCD@get#1#2%
1336 {%
1337 \def\FCD@tempa{#1}\def\FCD@tempb{{#2}}%
1338 \expandafter\FCD@get@aux\@gobbletwo#2\FCD@get@aux
1339 \@thirdofthree
1340 \FCD@get@aux
1341 {\ifcat\relax\noexpand#2\expandafter\@gobble\else\expandafter\@firstofone\fi}%
1342 {\edef\FCD@tempb{{\expandafter\noexpand\csname#2\endcsname}}}%
1343 \expandafter\FCD@tempa\FCD@tempb
1344 }%
1345 % \end{macrocode}
1346 % |v1.4| adds \csa{filecontentsdefmacro}. I abuse the \csa{if@filesw} toggle as
1347 % there is no \csa{if@tempswb} available. No need for a starred version as
1348 % anyhow the commented-out header was not put into the macro by the existing
1349 % \csa{FCD@main} code. No need to reset the toggle as documentation explains
1350 % direct usage of the environment begin and end macros must be inside a
1351 % |\begingroup\endgroup| pair.
1352 %
1353 % |v1.5| adds the ``starred''-named variants as aliases.
1354 % \begin{macrocode}
1355 \begingroup
1356 \catcode`\*=11
1357 \gdef\filecontentsdef #1{\let\FCD@global\@empty
1358 \@tempswatrue\FCD@get{\FCD@main{#1}}}%
1359 \gdef\filecontentsdef*#1{\let\FCD@global\@empty
1360 \@tempswafalse\FCD@get{\FCD@main{#1}}}%
1361 \global\let\filecontentsdefstarred\filecontentsdef*
1362 \gdef\filecontentsgdef #1{\@tempswatrue\FCD@get{\FCD@main{#1}}}%
1363 \gdef\filecontentsgdef*#1{\@tempswafalse\FCD@get{\FCD@main{#1}}}%
1364 \global\let\filecontentsgdefstarred\filecontentsgdef*
1365 % \end{macrocode}
1366 % |v1.5| can not use original \csa{endfilecontents} which makes reference to
1367 % \csa{reserved@c} whereas \fcdname now uses in its place \csa{FCD@reserved@c}.
1368 % Finally I drop altogether the bulk of this macro which issued a warning in
1369 % case of an encountered form feed or tabulation character.
1370 %
1371 % |v1.5| adds support for definitions with local scope so we must smuggle the
1372 % defined macro out of the environment. This is done via \csa{FCD@defmacro}
1373 % which is set-up via \csa{FCD@main}.
1374 % \begin{macrocode}
1375 \gdef\endfilecontentsdef{\immediate\closeout\FCD@reserved@c\FCD@defmacro}%
1376 \global\let\endfilecontentsdef*\endfilecontentsdef
1377 \global\let\endfilecontentsdefstarred\endfilecontentsdef
1378 \gdef\endfilecontentsgdef{\immediate\closeout\FCD@reserved@c}%
1379 \global\let\endfilecontentsgdef*\endfilecontentsgdef
1380 \global\let\endfilecontentsgdefstarred\endfilecontentsgdef
1381 \gdef\filecontentsdefmacro{\let\FCD@global\@empty
1382 \@fileswfalse\FCD@get{\FCD@main{}}}%
1383 \gdef\endfilecontentsdefmacro{\FCD@defmacro}%
1384 \gdef\filecontentsgdefmacro{\@fileswfalse\FCD@get{\FCD@main{}}}%
1385 \global\let\endfilecontentsgdefmacro\relax
1386 \gdef\filecontentshere #1{\let\FCD@global\@empty
1387 \@tempswatrue\FCD@main{#1}\filecontentsheremacro}%
1388 \gdef\filecontentshere*#1{\let\FCD@global\@empty
1389 \@tempswafalse\FCD@main{#1}\filecontentsheremacro}%
1390 \global\let\filecontentsherestarred\filecontentshere*
1391 \gdef\endfilecontentshere{\endfilecontentsdef\aftergroup\FCD@here}%
1392 \global\let\endfilecontentshere*\endfilecontentshere
1393 \global\let\endfilecontentsherestarred\endfilecontentshere
1394 % \end{macrocode}
1395 % Package |verbatim.sty| modifies the standard |verbatim| environment. For
1396 % both the original and the modified version we need to insert an active |^^M|
1397 % upfront, else an empty first line would not be obeyed. The |verbatim.sty|'s
1398 % |verbatim| needs that we feed it with the macro expanded once, as it uses
1399 % active end of lines as delimiters and they thus need to be immediately
1400 % visible. It also needs an active |^^M| after the |\end{verbatim}|. To avoid
1401 % to check at |\AtBeginDocument| if package |verbatim.sty| is loaded, we use a
1402 % slightly tricky common definition. The advantage is that this may help make
1403 % the code compatible with further packages (I have not looked for them)
1404 % modifying the |verbatim| environment. For better code readibility I use
1405 % |^^M%|'s rather than exploiting the active ends of lines here.
1406 %
1407 % |v1.5| adds \csa{FCDprintenvname} which holds the name of the environment to
1408 % be used. Initially configured to hold of course |verbatim|. And it also adds
1409 % \csa{FCDprintenvoptions}.
1410 % \begin{macrocode}
1411 \gdef\filecontentsprint{\FCD@get\FCD@print}%
1412 \catcode`\^^M\active%
1413 \gdef\FCD@print #1{\let\FCD@print@EOL^^M\let^^M\relax%
1414 \begingroup\toks@\expandafter{#1}%
1415 \edef\x{\endgroup%
1416 \noexpand\begin{\FCDprintenvname}\FCDprintenvoptions^^M%
1417 \the\toks@\@backslashchar end\string{\FCDprintenvname\string}}%
1418 \x^^M%
1419 \FCD@print@resetEOL}%
1420 \gdef\FCD@print@resetEOL{\let^^M\FCD@print@EOL}%
1421 \gdef\filecontentsprintviascan{\FCD@get\FCD@printviascan}%
1422 % \end{macrocode}
1423 % |v1.5| adds \csa{filecontentsprintviascan} which uses \csa{scantokens} to wrap
1424 % stored contents in a verbatim-like environment. This is needed for things
1425 % such as |listings| (it uses an active backslash at start of lines).
1426 % Attention to the \csa{scantokens} subtlety with \csa{end} which would become
1427 % |\end<space>| and then again |listings| would not recognize the ending
1428 % pattern.
1429 % \begin{macrocode}
1430 \gdef\FCD@printviascan#1{%
1431 \toks@\expandafter{#1}%
1432 \edef\FCD@envwithcontents{%
1433 \noexpand\begin{\FCDprintenvname}\FCDprintenvoptions\noexpand^^M%
1434 \the\toks@\@backslashchar end{\FCDprintenvname}\noexpand^^M}%
1435 \FCD@exec\FCD@envwithcontents}%
1436 \endgroup
1437 \def\FCDprintenvname{verbatim}%
1438 \let\FCDprintenvoptions\@empty
1439 \def\FCD@here{\FCD@print\filecontentsheremacro}%
1440 \def\filecontentsexec{\FCD@get\FCD@exec}%
1441 % \end{macrocode}
1442 % |v1.5| restores \csa{newlinechar} to its prior value, rather than setting it
1443 % to the \LaTeX{} default (10).
1444 % \begin{macrocode}
1445 \def\FCD@exec #1{\edef\FCD@newlinechar{\the\newlinechar}%
1446 \newlinechar13
1447 \scantokens\expandafter{#1}\newlinechar\FCD@newlinechar\relax}%
1448 \endinput
1449 % \end{macrocode}
1450 % \MakePercentComment
1451 \Finale
1452 %%
1453 %% End of file `filecontentsdef.dtx'.