summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/filecontentsdef/filecontentsdef.dtx
blob: b6b722383cd07bc25cc6c8f13240fe642395b8c3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
% -*- coding: utf-8; time-stamp-pattern: "def\\\\dtxtimestamp{%02d-%02m-%:y at %02H:%02M:%02S %Z}" -*-
% N.B.: this dtx file is NOT for use with \DocInput but only docstrip.
% The latex source of the user manual isn't commented out.
%<*none>
\def\dtxtimestamp{21-04-2019 at 15:24:14 CEST}%
%</none>
%<*!readme&!install>
%%
%% Package: filecontentsdef
%% Version: 1.4 (2019/04/20)
%% License: LPPL 1.3c
%% Copyright (C) 2016-2019 Jean-Francois Burnol <jfbu at free dot fr>
%%
%</!readme&!install>
%<*none>
\def\pkgname        {filecontentsdef}
\def\pkgdate        {2019/04/20}
\def\pkgdocdate     {2019/04/21}
\def\pkgversion     {v1.4}
\def\pkgdescription {filecontents + macro + verbatim (JFB)}
\catcode`\^ 12 \iffalse
%</none>
%<*readme|install>
<!-- -->

    Source:  filecontentsdef.dtx (v1.4 2019/04/20)
    Author:  Jean-Francois Burnol
    Info:    filecontents + macro + verbatim
    License: LPPL 1.3c
    Copyright (C) 2016-2019 Jean-Francois Burnol.
    <jfbu at free dot fr>

%</readme|install>
%<*readme>
ABSTRACT
========

This lightweight LaTeX2e package provides an environment `filecontentsdef`
which is like the `filecontents` environment of Scott Pakin's
[filecontents] [1] package but in addition to the file creation stores the
(verbatim) contents into a macro given as an additional argument (either as a
control sequence or as a name).

Displaying verbatim these contents is possible via `\filecontentsprint`,
and executing them (if they represent LaTeX code) via `\filecontentsexec`.

A variant environment `filecontentsdefmacro` stores the contents into a
macro, but skips the save-to-a-file part.

[1]: http://www.ctan.org/pkg/filecontents "filecontents package"

CHANGE LOG
==========

v1.4 \[2019/04/20\]
-------------------

- backport 2018/04/01 LaTeX release change to filecontents environment
  (`^^L` and `^^I` definitions).

- add `filecontentsdefmacro` environment.

- extend `filecontentsdef` and `filecontentsdefmacro` environments as
  well as `\filecontentsprint` and `\filecontentsexec` macros to accept
  indifferently either a control sequence or a name as argument.

- refactor documentation, explain how to define wrapper environments.

v1.2 \[2016/09/19\]
-------------------

Initial version.

LICENSE
=======

This Work may be distributed and/or modified under the
conditions of the LaTeX Project Public License 1.3c.
This version of this license is in

> <http://www.latex-project.org/lppl/lppl-1-3c.txt>

and the latest version of this license is in

> <http://www.latex-project.org/lppl.txt>

and version 1.3 or later is part of all distributions of
LaTeX version 2005/12/01 or later.

The Author of this Work is:

- Jean-Francois Burnol `<jfbu at free dot fr>`

This Work consists of the main source file filecontentsdef.dtx and
its derived files filecontentsdef.sty, filecontentsdef.pdf,
filecontentsdef.dvi, README.md, INSTALL.md, README, INSTALL.
%</readme>
%<*install>
INSTALLATION
============

Use your installation manager.

Else, for manual installation:

- To extract the package and at the same time produce the documentation,
  execute latex twice on `filecontentsdef.dtx` then `dvipdfmx` on the
  `dvi` file.

  To customize the PDF documentation (paper size, etc...): execute `etex`
  once on `filecontentsdef.dtx` then follow instructions given inside the
  extracted file `filecontentsdef.tex`.

- To extract the package but not necessarily build the documentation:
  run `etex` on `filecontentsdef.dtx`.

Files should then be moved to appropriate locations:

    filecontentsdef.sty -> TDS:tex/latex/filecontentsdef/
    filecontentsdef.dtx -> TDS:source/latex/filecontentsdef/
    filecontentsdef.pdf -> TDS:doc/latex/filecontentsdef/
    README.md           -> TDS:doc/latex/filecontentsdef/
    INSTALL.md          -> TDS:doc/latex/filecontentsdef/

You can also place `filecontentsdef.sty` directly within the directory
of the project using it.
%</install>
%<*tex>-------------------------------------------------------------------------
\chardef\Withdvipdfmx 1 % replace 1 by 0 for using pdflatex
\chardef\NoSourceCode 0 % replace 0 by 1 for the doc *without* the source code
\NeedsTeXFormat{LaTeX2e}
\ProvidesFile {filecontentsdef.tex}[Driver for filecontentsdef documentation]%
\PassOptionsToClass   {a4paper,fontsize=11pt,oneside}{scrdoc}
\PassOptionsToPackage {english}{babel}
\input filecontentsdef.dtx
%%% Local Variables:
%%% mode: latex
%%% End:
%</tex>-------------------------------------------------------------------------
%<*none>------------------------------------------------------------------------
\fi\catcode`\^ 7
%
\chardef\noetex 0
\ifx\numexpr\undefined\chardef\noetex 1 \fi
\ifnum\noetex=1 \chardef\extractfiles 0 % extract files, then stop
\else
    \ifx\ProvidesFile\undefined
      \chardef\extractfiles 0 % etex etc.. on dtx, only file extraction.
    \else % latex/pdflatex
      \ifx\Withdvipdfmx\undefined
        % latex/pdflatex on dtx
        \chardef\extractfiles 1 % 1 = extract files and typeset manual, 2 = only typeset
        \chardef\Withdvipdfmx 1 % 0 = pdflatex or latex+dvips, 1 = dvipdfmx
        \chardef\NoSourceCode 0 % 0 =  include source code, 1 = do not
        \NeedsTeXFormat {LaTeX2e}%
        \PassOptionsToClass   {a4paper,fontsize=11pt,oneside}{scrdoc}%
        \PassOptionsToPackage {english}{babel}%
      \else % latex on tex
        \chardef\extractfiles 2 % do not extract files, only typeset
      \fi
      \ProvidesFile{\pkgname.dtx}%
        [\pkgname\space source and documentation (\dtxtimestamp)]%
    \fi
\fi
\ifnum\extractfiles<2 % extract files
\def\MessageDeFin{\newlinechar10 \let\Msg\message
\Msg{********************************************************************^^J}%
\Msg{*^^J}%
\Msg{* To finish the installation you have to move the following^^J}%
\Msg{* file into a directory searched by TeX:^^J}%
\Msg{*^^J}%
\Msg{*\space\space\space\space \pkgname.sty^^J}%
\Msg{*^^J}%
\Msg{* To produce the documentation with source code included run latex^^J}%
\Msg{* twice on file \pkgname.tex and then dvipdfmx on \pkgname.dvi^^J}%
\Msg{*^^J}%
\Msg{* Happy TeXing!^^J}%
\Msg{*^^J}%
\Msg{********************************************************************^^J}%
}%
\begingroup
    \input docstrip.tex
    \askforoverwritefalse
    \def\pkgpreamble{\defaultpreamble^^J\MetaPrefix^^J%
    \string\NeedsTeXFormat{LaTeX2e}^^J%
    \string\ProvidesPackage{\pkgname}^^J%
    \space[\pkgdate\space\pkgversion\space\pkgdescription]}%
    \generate{\nopreamble\nopostamble
    \file{README.md}{\from{\pkgname.dtx}{readme}}%
    \file{INSTALL.md}{\from{\pkgname.dtx}{install}}%
    \usepostamble\defaultpostamble
    \file{\pkgname.tex}{\from{\pkgname.dtx}{tex}}%
    \usepreamble\pkgpreamble
    \file{\pkgname.sty}{\from{\pkgname.dtx}{package}}}%
\endgroup
\fi % end of file extraction (from etex/latex/pdflatex run)
\ifnum\extractfiles=0 % tex/etex/xetex/etc files extracted, stop
      \MessageDeFin\expandafter\end
\fi
% From this point on, run is necessarily with e-TeX.
% Check if \MessageDeFin got defined, if yes put it at end of run.
\ifdefined\MessageDeFin\AtEndDocument{\MessageDeFin}\fi
%-------------------------------------------------------------------------------
% START OF USER MANUAL TEX SOURCE
\documentclass[abstract]{scrdoc}

\ifnum\NoSourceCode=1 \OnlyDescription\fi

\usepackage{ifpdf}
\ifpdf\chardef\Withdvipdfmx 0 \fi

\makeatletter
\ifnum\Withdvipdfmx=1
   \@for\@tempa:=hyperref,bookmark,graphicx,xcolor,pict2e\do
            {\PassOptionsToPackage{dvipdfmx}\@tempa}
   %
   \PassOptionsToPackage{dvipdfm}{geometry}
   \PassOptionsToPackage{bookmarks=true}{hyperref}
   \PassOptionsToPackage{dvipdfmx-outline-open}{hyperref}
   \PassOptionsToPackage{dvipdfmx-outline-open}{bookmark}
   %
   \def\pgfsysdriver{pgfsys-dvipdfm.def}
\else
   \PassOptionsToPackage{bookmarks=true}{hyperref}
\fi
   \let\original@check@percent\check@percent
   \let\check@percent\relax
\makeatother

\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage[hscale=0.66,vscale=0.75]{geometry}
\pagestyle{headings}

\def\MacroFont{\ttfamily\small\hyphenchar\font45 \baselineskip11pt\relax}
\AtBeginDocument{\def\MacroFont{\ttfamily}}

% ATTENTION: (avec doc.sty ou les classes scrdoc ou ltxdoc)
%
% - l'environnement macrocode se fait avec \macro@font qui est le
% \MacroFont du \begin{document}.
%
% - les environnements verbatim utilisent le \MacroFont courant.
%
% - \verb utilise un \ttfamily !! et non pas \verbatim@font que l'on
% peut customiser.
%
% - (9 mars 2015) il ne faut PAS commencer des macrocode directement après
% un \section, il faut un paragraphe (par exemple un \indent\par)

\usepackage{xspace}
\usepackage[dvipsnames]{xcolor}

\definecolor{joli}{RGB}{225,95,0}
\definecolor{JOLI}{RGB}{225,95,0}

\newcommand\fcdname{%
  \texorpdfstring{{\color{joli}\ttfamily\bfseries \pkgname}}{\pkgname}\xspace}

\DeclareRobustCommand\csa [1] {{\ttfamily\hyphenchar\font45 \char`\\ #1}}

\newcommand\csh[1]{\texorpdfstring{\csa{#1}}{\textbackslash\detokenize{#1}}}

\usepackage{babel}

\usepackage[pdfencoding=pdfdoc]{hyperref}
\hypersetup{%
linktoc=all,%
%% bookmarksdepth=3,%
breaklinks=true,%
colorlinks,%   
linkcolor=OliveGreen,%RoyalBlue,%
urlcolor=RoyalBlue,%OliveGreen,%
pdfauthor={Jean-Fran\c cois Burnol},%
pdftitle={The \pkgname\space package},%
pdfsubject={\pkgdescription},%
pdfkeywords={LaTeX, verbatim, macros},%
pdfstartview=FitH,%
pdfpagemode=UseOutlines}
\usepackage{bookmark} 

\usepackage[zerostyle=a,scaled=0.95,straightquotes]{newtxtt}
\renewcommand\familydefault\sfdefault
\frenchspacing

\usepackage{framed}

%\usepackage{varioref}

%\usepackage{footnotehyper}

\usepackage{filecontentsdef}

\makeatletter
% Revert change to \smash and other macros at LaTeX 2018/12/01
% https://github.com/latex3/latex2e/issues/108
\let\leavevmode@ifvmode\empty % for \smash in \NewWith etc...
\newcommand\inmarg [1]{\@bsphack
    \vadjust{\vskip-\dp\strutbox
             \smash{\hbox to 0pt
                       {\color[named]{PineGreen}\normalfont\small\bfseries
                        \hsize 2.5cm\rightskip.5cm minus.5cm
                        \hyphenpenalty\z@\exhyphenpenalty\z@
                        \doublehyphendemerits\z@\baselineskip9pt
                        \hss\vtop{\noindent#1}\kern.25cm }}%
             \vskip\dp\strutbox }\strut\@esphack}
%! 24 février 2014. J'ai besoin de me débarrasser du \to
\def\NewWith #1{\@bsphack
    \vadjust{\vskip-\dp\strutbox
             \smash{\hbox to 0pt {\hss\color[named]{Thistle}%
                        \normalfont\small\bfseries
                        \hsize 2.5cm\rightskip.5cm minus.5cm
                        \vtop{\noindent New with #1}\kern.25cm }}%
             \vskip\dp\strutbox }\strut\@esphack}
\makeatother

\begin{document}
\rmfamily
\thispagestyle{empty}

\bookmark[named=FirstPage,level=1]{Title page}

%\ttzfamily

{%
\normalfont\Large\parindent0pt \parfillskip 0pt\relax
 \leftskip 2cm plus 1fil \rightskip 2cm plus 1fil
 The \fcdname package\par
}

{\centering
  \textsc{Jean-François Burnol}\par
  \footnotesize
  jfbu (at) free (dot) fr\par
  Package version: \pkgversion\ (\pkgdate);
            documentation date: \pkgdocdate.\par
  {From source file \texttt{\pkgname.dtx (\dtxtimestamp)}}\par
}

\begin{abstract}
  This lightweight LaTeX2e package provides an environment
  |filecontentsdef| which is like the |filecontents|
  environment of \textsc{Scott Pakin}'s
  \href{https//ctan.org/pkg/filecontents}{filecontents} package but in
  addition to the file creation stores the (verbatim) contents into a
  macro given as an additional argument (either as a control sequence or
  as a name).

  Displaying verbatim these contents is possible via
  |\filecontentsprint|, and executing them (if they represent LaTeX
  code) via |\filecontentsexec|.

  A variant environment |filecontentsdefmacro| stores the contents into
  a macro, but skips the save-to-a-file part.

  I developed this to display \TeX\ code verbatim in documentation
  and simultaneously produce during the LaTeX run the corresponding
  files in order to embed them in the PDF as \emph{file attachment
    annotations} (via the services of \textsc{Scott Pakin}'s
  further package
  \href{https://ctan.org/pkg/attachfile}{attachfile}.)
\end{abstract}

\section{Description}

This package provides the |filecontentsdef|\inmarg{|file\-contents\-def|}
environment. It is like |filecontents| but requires a second argument. This
argument will either be:
\begin{itemize}
\item a single control sequence token such as |\macro|,
\item \mbox{}\NewWith{v1.4$\to$}or anything else which then must after expansion be
  usable as a macro \emph{name} (it will be handled via
  |\csname...\endcsname| encapsulation).
% Bordel, que d'emmerdements avec le LaTeX \footnote et \verb ! On ne peut même
% pas faire \string\fi (ou \else, ou \if pas vérifié lequel des trois:
% incomplete \ifmmode
%\footnote{
% Bon ben finalement pas de footnote de toute façon. Déjà fait le mark-up je laisse.
  For example \texttt{\string\myitemnumber\{3\}} can be used as argument and
  it will then be expanded inside \texttt{\string\csname...\string\endcsname}
  to construct a control sequence, whose name will possibly contain digits or
  other characters of non-letter catcodes. A single active character is
  allowed as long as its expansion is
  \texttt{\string\csname...\string\endcsname} compatible; the character itself
  will \emph{not} be assigned a new meaning.
%}
%
\end{itemize}

Thus the syntax is either:
\begin{verbatim}
    \begin{filecontentsdef}{<filename>}{\macro}
    ... arbitrary contents ...
    \end{filecontentsdef}
\end{verbatim}
or:
\begin{verbatim}
    \begin{filecontentsdef}{<filename>}{(expanding to) macro name}
    ... arbitrary contents ...
    \end{filecontentsdef}
\end{verbatim}

The environment creates the file and stores its (verbatim) contents into its
second argument |\macro| (or into the  macro |\<macro name>| with given name).

\begin{enumerate}
\item The starred variant acts like |filecontents*| environment regarding the
  file contents.
\item The contents put into the macro are the same for the starred and
  non-starred environments: they do not contain the commented-out header.
\item The scope of the macro definition is global.
\item No check is done on whether the defined macro pre-existed.
% \item |filecontentshere| is a wrapper of the |filecontentsdef|
%   environment using \csa{filecontentsheremacro} as the macro where the
%   contents are stored.\inmarg{\csa{file\-contents\-here\-macro}} This macro
%   can then be reused elsewhere if wanted.
\item The macro holds a verbatim rendering of the contents, which handles the
  Form Feed and Tabulation characters analogously to the |filecontents|
  treatment.
\item Babel shorthands will be neutralized the same way they are when
  encountered in a verbatim environment or in a |filecontents|
  environment. Their action is reactivated if the macro (assuming the
  contents represent \LaTeX\ code) gets later executed via
  \csa{filecontentsexec}.
\item The environment can be used either in the preamble or the body
  of the document.
\item The contents must not contain themselves a
  \texttt{\string\end}|{filecontentsdef}| (or |end{filecontentsdef*}| in the
starred case).
\item If some |\macro| contains the \emph{name} of the macro to be defined,
  use then |\empty\macro| as argument, this trick will avoid the environment
  thinking it is supposed to redefine |\macro| itself.
% problème avec Emacs/AUCTeX et |\end{...}| qui fait boguer le fontlock
% biarrement le deuxième ne pose pas de problème. 19 avril 2019.
\end{enumerate}

\begin{footnotesize}
  Here are some additional relevant details:
\begin{enumerate}
\item the usual special characters are sanitized like they would be in a
  verbatim environment,
\item the space becomes the active character of ascii code |32|,
\item the end of line is converted into the active character |^^M| (i.e. ascii
  code |13|),
\item the tabulation character |CTRL-I| becomes the active space character,
\item the form feed character |CTRL-L| is converted into a pair of active |^^M|,
\item the active bytes of ascii code between |128| and |255| (this is now
  systematically the case with |inputenc+utf8| being default) are stored
  into the produced macro ``as is'',
\item the non-active bytes of ascii code between |128| and |255| are
  stored into the produced macro with catcode letter.
\end{enumerate}
These last two items together mean that 8bit or UTF8-encoded characters will
display as expected in a verbatim rendering, see \csa{filecontentsprint} next.
\par
\end{footnotesize}

\medskip

The \csa{filecontentsprint}\inmarg{\csa{file\-contents\-print}} macro has a
unique mandatory argument which will be either:
\begin{itemize}
\item a single control sequence token (for example |\macro|),
\item \mbox{}\NewWith{v1.4$\to$}or anything else which then must after expansion be
  usable as a macro \emph{name} (for example |macro|). It will be handled via
  |\csname...\endcsname| encapsulation (see earlier explanations).%
\end{itemize}
The |\macro| must be of the type constructed by the environment
|filecontentsdef|. It will be then be printed exactly as
\begingroup\makeatletter\def\x{\let\@xverbatim\relax
       \verbatim
\string\begin\string{verbatim\string}\par
<contents of \string\macro>\par
\string\end\string{verbatim\string}\par
\endverbatim%
\endgroup}\x
would have done.

This uses underneath the |verbatim| environment and has been
  tested to be compatible with the standard |verbatim|, with the one from
  package \href{http://www.ctan.org/pkg/doc}{doc} (classes |ltxdoc.cls|,
  |scrdoc.cls|) and also with the one from package
  \href{http://www.ctan.org/pkg/verbatim}{verbatim} (whose mechanism is quite
  different from the one of the default |verbatim| environment.)

%xxx
% MARRE DE EMACS/AUCTEX QUI SE CROIT PLUS INTELLIGENT QUE L'UTILISATEUR POUR
% L'INDENTATION PAR FILL-PARAGRAPH (M-q)
%xxx

\begin{framed}
  Due to limitation of the |verbatim| environment, the
  \texttt{\string\end}|{verbatim}| must not appear inside the contents... else
  it will be misconstrued as ending the external |verbatim| environment itself
  which is added by \csa{filecontentsprint}!

  This limitation only
  affects \csa{filecontentsprint}, not \csa{filecontentsexec}.
\end{framed}

Although \fcdname itself generally does not require \eTeX, it provides as a
convenience \csa{filecontentsexec}\inmarg{\csa{file\-contents\-exec}} which
does require it as it uses |\scantokens| to re-assign the current catcode
regime to the verbatimized tokens stored into its mandatory argument. Again
the mandatory argument may have one of the two forms described previously.%
\NewWith{v1.4$\to$}

And of course this assumes that the tokens provide legitimate \LaTeX\ code.

\begin{footnotesize}
  \textbf{TeX-hacker note:} As an aftereffect, the |\newlinechar| will be set
  to |10| (its \LaTeX\ default) after execution; we skipped the saving and
  restoring of its value (it is temporarily set to |13| for |\scantokens|
  execution). No group is used in order to not create an extra scoping of the
  executed macro contents.

  \textbf{TeX-hacker note:} A space token will be present at the end of the
  expansion, due to |\scantokens|'s way of working, but may be hidden by the
  nature of the contents themselves, if for example they end with a |\relax|
  or a |%|, or from arising in vertical mode.

\end{footnotesize}

The environment\inmarg{|file\-contents\-here|}
\begin{verbatim}
    \begin{filecontentshere}{<filename>}
    ... arbitrary contents ...
    \end{filecontentshere}
\end{verbatim}
creates on the fly a file with these contents, and simultaneously
it typesets them in a verbatim environment. It is a shortcut to doing
\begin{verbatim}
    \begin{filecontentsdef}{<filename>}{\filecontentsheremacro}
    ... arbitrary contents ...
    \end{filecontentsdef}
\end{verbatim}
and then immediately
\begin{verbatim}
    \filecontentsprint\filecontentsheremacro
\end{verbatim}
The |\filecontentsheremacro| remains available for reuse with |\filecontentsexec|.

For example
\begin{verbatim}
\begin{filecontentshere}{\jobname.test}
  \begin{framed}
    \noindent 
                We have coded this in \LaTeX: both
      $E=mc^2$ (input as \verb|$E=mc^2$|)
    and     $E=h\nu$  owe much    to \textsc{Albert Einstein}.
  \end{framed}
\end{filecontentshere}
\filecontentsexec\filecontentsheremacro
\end{verbatim}
will produce the external file with extension
|.test| and have this effect in the document (verbatim framed then real framed):
\begin{filecontentshere}{\jobname.test}
  \begin{framed}
    \noindent 
                We have coded this in \LaTeX: both
      $E=mc^2$ (input as \verb|$E=mc^2$|)
    and     $E=h\nu$  owe much    to \textsc{Albert Einstein}.
  \end{framed}
\end{filecontentshere}
\filecontentsexec\filecontentsheremacro

The environment\inmarg{|file\-contents\-def\-macro|}
\begin{verbatim}
    \begin{filecontentsdefmacro}{\macro or macro name}
    ... arbitrary contents ...
    \end{filecontentsdefmacro}
\end{verbatim}
was added at |v1.4|.\NewWith{v1.4} It is like |filecontentsdef| without the
``save to file'' part... and has thus a sole mandatory argument which may be
either a control sequence or a name (or material expanding to name), as
previously described. The macro can then be either printed verbatim via
\csa{filecontentsprint} or, if it consists of \LaTeX\ code, be executed in
re-tokenized form via \csa{filecontentsexec}.

Its name is thus a bit paradoxical but was chosen to share an existing prefix
with the other package macros and environments.

\section{How to wrap usage of \texttt{filecontentsdef} in another
  environment}

It is simple: don't use |\begin/\end| syntax
%  \verb|\end{filecontentsdef}|, % uniquement à cause de bug de Emacs/AUCTeX
%                                % fontlocking
but |\begingroup\filecontentsdef{..}{..}| and |\endfilecontentsdef\endgroup|.
And these should come last, respectively first, in the definition of the
begin, respectively end, part of the new environment.

The extra |\begingroup...\endgroup| is needed only to the extent that
definitions and catcode assignments could affect the execution of the
rest of the |end| part of the new environment. As this |end| part will
be tokenized at time of definition, it will in general be indifferent to
the catcode modifications done by \csa{filecontentsdef} and generally
speaking the |\begingroup...\endgroup| can be dropped.

Of course, for wrapping the starred variant one should use
% PUTAIN DE BORDEL DE Text for \verb command ended by end of line, QU'EST-CE
% QUE LATEX EST CHIANT. Plus le fill-paragraph de Emacs et le doctex-mode défectueux.
|\csname filecontentsdef*\endcsname|, or make the definition with |*| having catcode
letter. But the \verb|\endfilecontentsdef| can drop the |*|, as the starred
environments defined by the \fcdname package use the same ending macros as
their non-starred variants.

As exercise, let's imagine we want an environment which will be associated
to some counter, will automatically increment it at each usage, and will
use this counter to index the files and macros created on each invocation.
\begin{filecontentsdefmacro}{\pablo}
\newcounter{pablo}
\newenvironment{defexercise}
   {\stepcounter{pablo}%
    \begingroup
    \csname filecontentsdef*\endcsname
    {\jobname-ex\the\value{pablo}}{exercise-\the\value{pablo}}}%
   {\endfilecontentsdef\endgroup}
\newcommand{\printexercise}[1]{\filecontentsexec{exercise-\the\numexpr#1\relax}}
\end{filecontentsdefmacro}
\filecontentsprint\pablo
\filecontentsexec\pablo

We can then use it this way:
\begin{filecontentsdefmacro}{\usepablo}
\begin{defexercise}
   Prove that \[x^n+y^n=z^n\]  is not solvable in positive integers if $n$ is at
   most $-3$.\par  
\end{defexercise}
\begin{defexercise}
   Refute the existence of black holes in less than 140 characters.\par 
\end{defexercise}
\begin{defexercise}
  \def\NSA{NSA}%
  Prove that factorization is easily done via probabilistic algorithms and
  advance evidence from knowledge of the names of its employees in the
  seventies that the \NSA\ has known that for 40 years.\par
\end{defexercise}
\begin{itemize}
\item \printexercise{3}
\item \printexercise{2} 
\item \printexercise{1}
\end{itemize}
\end{filecontentsdefmacro}
\filecontentsprint\usepablo

This produces in the document:
\filecontentsexec\usepablo
Additionally, three small files were created containing the \LaTeX\ mark-up
for each exercise.

\begin{footnotesize}

\section{Custom verbatim print-outs}

We now comment on alternatives to using \csa{filecontentsprint}. Here is
some (non-\LaTeX) text snippet.
\begin{verbatim}
\begin{filecontentsdef}{\jobname.test2}{\testactive}
v1.2 \[2016/09/19\]
-------------------

Initial version.

test: éèàùÉÈÇÀÙÛÎåðñòóôõöœøùúûüýþߟŽ§
\end{filecontentsdef}
\end{verbatim}

We can expand \csa{testactive} directly inside the \LaTeX\ document, but must
give some definitions to the active space token and the active |^^M| token
like |verbatim| environment does.

For a true verbatim printout \csa{obeyspaces} and \csa{obeylines} are not
enough because spaces at start of lines will disappear, and multiple empty
lines give multiple |\par|'s which collapse into a single one (hence no empty
line can be observed in the output). The usual |verbatim| environment uses a
special definition of |\par| which prevents the disappearance of empty lines,
and for the spaces it has macro \csa{@vobeyspaces} which makes the spaces
issue |\leavevmode| so they are not skipped at the start of lines. Let's
define:
\begin{verbatim}
\makeatletter
% this redefines active spaces, but does not make spaces active
\def\niceactivespaces{\@vobeyspaces\catcode32=10\relax}% 
\makeatother
\begingroup
% this redefines active end of lines, but does not make them active
  \catcode`\^^M\active %
  \gdef\niceactiveCRs{\def^^M{\leavevmode\par}}%
\endgroup %
\end{verbatim}

Then we can issue something like:
\begin{verbatim}
{\setlength{\parindent}{2cm}\niceactivespaces\niceactiveCRs\testactive\par}
\end{verbatim}
This allows hyphenation and ligatures, which are usually inhibited in standard
|verbatim|, and it does not switch to the monospace font. Here is what happens
if we do all of the above, as a test:

\def\testactive{testactive}
\begin{filecontentsdefmacro}{\empty\testactive}
v1.2 \[2016/09/19\]
-------------------

Initial version.

test: éèàùÉÈÇÀÙÛÎåðñòóôõöœøùúûüýþߟŽ§
\end{filecontentsdefmacro}
\makeatletter
% this redefines active spaces, but does not make spaces active
\def\niceactivespaces{\@vobeyspaces\catcode32=10\relax}% 
\makeatother
\begingroup
% this redefines active end of lines, but does not make them active
  \catcode`\^^M\active %
  \gdef\niceactiveCRs{\def^^M{\leavevmode\par}}%
\endgroup %
{\setlength{\parindent}{2cm}\niceactivespaces\niceactiveCRs\testactive\par}
We see indeed how the |---...--| gave rise to ligatures, and that the
monospace font was not used. This was only to give an idea of how one can use
the macros created by the |filecontentsdef| or |filecontentsdefmacro|
environments for variant verbatim rendering. This technique can be used as
workaround to the problem with \csa{filecontentsprint} that the contents can
not contain \verb|\end{verbatim}|.

\end{footnotesize}

\StopEventually{\end{document}}

\clearpage

\makeatletter
    \let\check@percent\original@check@percent
\makeatother

\small

\section{Implementation}

See the \texttt{README.md} file for the \texttt{CHANGE LOG}.

% \indent % !!!!!!!!!!!!!!!!! Lundi 09 mars 2015 à 09:32:22


\makeatletter
\begingroup
\topsep\MacrocodeTopsep
\trivlist\parskip\z@\item[]
\macro@font
\leftskip\@totalleftmargin  \advance\leftskip\MacroIndent
\rightskip\z@  \parindent\z@  \parfillskip\@flushglue
\global\@newlistfalse \global\@minipagefalse
\ifcodeline@index
  \everypar{\global\advance\c@CodelineNo\@ne
  \llap{\theCodelineNo\ \hskip\@totalleftmargin}}%
\fi
\string\NeedsTeXFormat\string{LaTeX2e\string}[1999/12/01]\par
\string\ProvidesPackage\string{\pkgname\string}\par
\noindent\space [\pkgdate\space\pkgversion\space\pkgdescription]\par
\nointerlineskip
\global\@inlabelfalse
\endtrivlist
\endgroup
\makeatother

% The catcode hackery next is to avoid to have <*package> to be listed
% in the commented source code...
% (c) 2012/11/19 jf burnol ;-)

\MakePercentIgnore

%
% \catcode`\<=0 \catcode`\>=11 \catcode`\*=11 \catcode`\/=11
% \let</none>\relax
% \def<*package>{\catcode`\<=12 \catcode`\>=12 \catcode`\*=12 \catcode`\/=12}
%
%</none>
%<*package>
% Most of
% the code is still identical to the one in \textsc{Scott Pakin}'s
% \href{http://www.ctan.org/pkg/filecontents}{filecontents} hence to
% the original one in \LaTeX's sources.
%
% But |v1.4| adds \cs{filecontentsdefmacro} which does not write to a file...
%    \begin{macrocode}
\begingroup
\catcode`\^^M\active%
\catcode`\^^L\active\let^^L\relax%
\catcode`\^^I\active%
\gdef\filec@ntentsdef#1#2{%
  \let#2\@empty%
 \if@filesw%
  \openin\@inputcheck#1 %
  \ifeof\@inputcheck%
    \@latex@warning@no@line%
        {Writing file `\@currdir#1'}%
  \else%
    \@latex@warning@no@line%
        {Overwriting file `\@currdir#1'}%
  \fi%
  \closein\@inputcheck%
  \chardef\reserved@c15 %
  \ch@ck7\reserved@c\write%
  \immediate\openout\reserved@c#1\relax%
  \if@tempswa%
    \immediate\write\reserved@c{%
      \@percentchar\@percentchar\space%
          \expandafter\@gobble\string\LaTeX2e file `#1'^^J%
      \@percentchar\@percentchar\space  generated by the %
        `\@currenvir' \expandafter\@gobblefour\string\newenvironment^^J%
      \@percentchar\@percentchar\space from source `\jobname' on %
         \number\year/\two@digits\month/\two@digits\day.^^J%
      \@percentchar\@percentchar}%
  \fi%
 \fi%
  \let\do\@makeother\dospecials%
%    \end{macrocode}
% SP's |filecontents| sets here in the loop all catcodes to |11|, but we
% need for correct rendering in verbatim that the constructed macro
% stores active characters as active characters.
%
% We don't check for unusual active characters of ascii code |<128|
% as this is not done by original or SP's |filecontents|. But if
% present then they will expand similarly both in the |\write| and
% in the construction of the macro.
%    \begin{macrocode}
  \count@=128\relax%
  \loop%
    \ifnum\catcode\count@=\active%
          \lccode`~\count@%
          \lowercase{\def~{\noexpand~}}%
    \else%
          \catcode\count@=11 %
    \fi%
    \advance\count@ by \@ne%
    \ifnum\count@<\@cclvi%
  \repeat%
%    \end{macrocode}
% The default active |^^L|  is |\outer|. But |\reserved@b| will be |def'd|
% with an active |^^L| in its replacement text.
%    \begin{macrocode}
  \let^^L\relax%
  \edef\E{\@backslashchar end\string{\@currenvir\string}}%
  \edef\reserved@b{\def\noexpand\reserved@b####1\E####2\E####3\relax}%
%    \end{macrocode}
% \cs{filecontentsdefmacro} sets \cs{if@filesw} to false.
%    \begin{macrocode}
  \reserved@b{%
    \ifx\relax##3\relax%
      \if@filesw\immediate\write\reserved@c{##1}\fi%
%    \end{macrocode}
% This is where the original |filecontents| is extended to store the
% parsed material in a macro (in my very first hack I simply
% patched it to redefine |\write| to also do the macro storage, but
% considerations like the one relative to active characters due to
% |inputenc| made me decide to re-write the whole thing, hence make
% a new package.)
%
% Active characters were defined with a single |\noexpand| in the
% loop, and this is enough because after each new line is processed
% the characters it contains are protected from further expansion in
% the |\xdef|'s. And the single |\noexpand| is enough also for the
% |\write| done above.
%
% The |lccode| of the tilde is |32| when this gets executed. Multiple
% form feeds produce the same effect in the macro (insertion of two
% |^^M| per form feed) as in the written out file (via two |^^J|).
%    \begin{macrocode}
      \toks@\expandafter{#2}%
      {\def^^L{\noexpand^^M\noexpand^^M}\lowercase{\let^^I~}%
       \xdef#2{\the\toks@##1\noexpand^^M}}%
    \else%
      \edef^^M{\noexpand\end{\@currenvir}}%
      \ifx\relax##1\relax%
      \else%
       \if@filesw%
          \@latex@warning{Writing text `##1' before %
             \string\end{\@currenvir}\MessageBreak as last line of #1}%
        \immediate\write\reserved@c{##1}%
       \fi%
%    \end{macrocode}
% Same added code as above.
%    \begin{macrocode}
        \toks@\expandafter{#2}%
        {\def^^L{\noexpand^^M\noexpand^^M}\lowercase{\let^^I~}%
         \xdef#2{\the\toks@##1\noexpand^^M}}%
      \fi%
      \ifx\relax##2\relax%
      \else%
         \@latex@warning{%
           Ignoring text `##2' after \string\end{\@currenvir}}%
      \fi%
    \fi%
    ^^M}%
  \catcode`\^^L\active%
%    \end{macrocode}
% |v1.4|: sync |^^L| and |^^I| with 2018/04/01 LaTeX release.
%    \begin{macrocode}
  \let\L\@undefined%
  \def^^L{\expandafter\ifx\csname L\endcsname\relax\fi^^J^^J}%
  \catcode`\^^I\active%
  \let\I\@undefined%
  \def^^I{\expandafter\ifx\csname I\endcsname\relax\fi\space}%
  \catcode`\^^M\active%
  \edef^^M##1^^M{\noexpand\reserved@b##1\E\E\relax}%
%    \end{macrocode}
% We want space characters to be active in the produced macro.
% We only need to protect them once from expansion.
%    \begin{macrocode}
  \catcode32\active\lccode`~32 \lowercase{\def~{\noexpand~}}%
}%
\endgroup
%    \end{macrocode}
% The |v1.4| macros accept a name as alternative to a macro. Empty or
% ill-formed |#2| will break code. But |#2| can be using |\if|, |\else|,
% |\fi| tokens, the whole thing will end up |\csname|-expanded. An active
% character also will end up |\csname|-expanded. There is no check on
% whether |#2| or |\csname#2\endcsname| is an existing macro.
%    \begin{macrocode}
\long\def\filecontentsdef@aux#1\filecontentsdef@aux{\@firstofone}%
\def\filecontentsdef@get#1#2%
{%
  \def\@tempa{#1}\def\@tempb{{#2}}%
  \expandafter\filecontentsdef@aux\@gobbletwo#2\filecontentsdef@aux
  \@thirdofthree
  \filecontentsdef@aux
  {\ifcat\relax\noexpand#2\expandafter\@gobble\else\expandafter\@firstofone\fi}%
  {\edef\@tempb{{\expandafter\noexpand\csname#2\endcsname}}}%
  \expandafter\@tempa\@tempb
}%
%    \end{macrocode}
% |v1.4| adds \cs{filecontentsdefmacro}. I abuse the \cs{if@filesw} toggle as there
% is no \cs{if@tempswb} available. No need for a starred version as anyhow
% the commented-out header was not put into the macro by the existing
% \cs{filec@ntentsdef} code. No need to reset the toggle as only usage as
% an environment is supported. And by lazyness and to spare extra coding,
% \cs{endfilecontentsdefmacro} emits no warning about Form Feed and Tabulation.
%    \begin{macrocode}
\begingroup
\catcode`\*=11
\gdef\filecontentsdef #1{\@tempswatrue\filecontentsdef@get{\filec@ntentsdef{#1}}}%
\gdef\filecontentsdef*#1{\@tempswafalse\filecontentsdef@get{\filec@ntentsdef{#1}}}%
\global\let\endfilecontentsdef \endfilecontents
\global\let\endfilecontentsdef*\endfilecontents
\gdef\filecontentsdefmacro{\@fileswfalse\filecontentsdef@get{\filec@ntentsdef{}}}%
\global\let\endfilecontentsdefmacro\relax
\gdef\filecontentshere #1{\@tempswatrue\filec@ntentsdef{#1}\filecontentsheremacro}%
\gdef\filecontentshere*#1{\@tempswafalse\filec@ntentsdef{#1}\filecontentsheremacro}%
\gdef\endfilecontentshere{\endfilecontentsdef\aftergroup\filecontents@here}%
\global\let\endfilecontentshere*\endfilecontentshere
%    \end{macrocode}
% Package |verbatim.sty| modifies the standard |verbatim| environment. For
% both the original and the modified version we need to insert an active |^^M|
% upfront, else an empty first line would not be obeyed. The |verbatim.sty|'s
% |verbatim| needs that we feed it with the macro expanded once, as it uses
% active end of lines as delimiters and they thus need to be immediately
% visible. It also needs an active |^^M| after the |\end{verbatim}|. To avoid
% to check at |\AtBeginDocument| if package |verbatim.sty| is loaded, we use a
% slightly tricky common definition. The advantage is that this may help make
% the code compatible with further packages (I have not looked for them)
% modifying the |verbatim| environment. For better code readibility I use
% |^^M%|'s rather than exploiting the active ends of lines here.
%    \begin{macrocode}
\gdef\filecontentsprint{\filecontentsdef@get\filecontents@print}%
\catcode`\^^M\active%
\gdef\filecontents@print #1{\let\filecontents@print@EOL^^M\let^^M\relax%
   \begingroup\toks@\expandafter{#1}\edef\x{\endgroup%
            \noexpand\begin{verbatim}^^M%
            \the\toks@\@backslashchar end\string{verbatim\string}}\x^^M%
   \filecontents@print@resetEOL}%
\gdef\filecontents@print@resetEOL{\let^^M\filecontents@print@EOL}%
\endgroup
\def\filecontents@here{\filecontents@print\filecontentsheremacro}%
\def\filecontentsexec{\filecontentsdef@get\filecontents@exec}%
\def\filecontents@exec #1{\newlinechar13 
    \scantokens\expandafter{#1}\newlinechar10\relax}%
\endinput
%    \end{macrocode}
% \MakePercentComment
\Finale
%%
%% End of file `filecontentsdef.dtx'.