summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/embedall/embedall.dtx
blob: 99a05c7149de22fc8c5005d6f1df9efe9df7f726 (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
% \iffalse meta-comment
%
% Copyright (C) 2013 by Alberto Sartori
% Copyright (C) 2019 by David Lichti
% -------------------------------------------------------
% 
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
% version 1.3 of this license or (at your option) any later
% version. 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.
%
% \fi
%
% \iffalse
%
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesClass{embedall}[2019/05/18 v2.0 Automatically embed source files in PDF]
%
%<*driver>
\documentclass{ltxdoc}
\usepackage[notall]{embedall}[2019/05/18]
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[osf,sc]{mathpazo}
\usepackage{parskip}
\renewcommand\sfdefault{lmsf}
\renewcommand\ttdefault{lmtt}
\usepackage{microtype}
\linespread{1.1}
\usepackage{enumitem}
\setdescription{font=\itshape,leftmargin=2cm,style=sameline}
\usepackage{hyperref}
\EnableCrossrefs         
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{embedall.dtx}
\end{document}
%</driver>
% 
% \fi
%
% \CheckSum{154}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% \changes{v1.0}{2013/10/10}{Initial version}
% \changes{v2.0}{2019/05/18}{Overhaul using filehook package}
%
% \GetFileInfo{embedall.sty}
%
% \DoNotIndex{\newcommand,\def,\let,\DeclareRobustCommand}
% \DoNotIndex{\newif,\DeclareOption,\ProcessOptions,\relax,\RequirePackage,\fi,\else,\ifcsname,\endcsname,\PackageWarning,\^\^}
% \DoNotIndex{\AtBeginDocument,\IfFileExists,\input,\jobname,\LetLtxMacro,\listxadd,\message,\newlinechar,\xifinlist}
% \DoNotIndex{\embedfile,\currfilename,\AtBeginOfInputs,\AtBeginOfIncludes}
% \DoNotIndex{\Gin@setfile}
% \DoNotIndex{\csvloop,\csv@input@filename}
%
% \title{The \textbf{embedall} package\thanks{This document
%   corresponds to \textsf{embedall}~\fileversion, dated \filedate.}}
% \author{
%    Alberto Sartori -- \texttt{\href{mailto:alberto.sartori.as@gmail.com}{alberto.sartori.as@gmail.com}}\\
%    David Lichti -- \texttt{\href{mailto:dlichtistw@gmx.de}{dlichtistw@gmx.de}}
% }
%
% \maketitle
%
% \embedsource[desc=main source file]
%
% \section{Introduction}
%
% This package is designed to help you storing your projects without losing anything.
% It uses the |filehook| package and some custom patches to hook into several supported import mechanisms.
% These imported files are then attached to the PDF file using the |embedfile| package.
% In particular it can embed images, external TeX files, external code listings, CSV files, and, most importantly, the main TeX file itself.
%
% \section{Usage}
%
% To use the package, simply add |\usepackage{embedsources}| to your document's preamble.
% Without any option, the default behaviour is to attach all supported source file types to the finished document.
% See section~\ref{sec:PackageOptions} for options to change this behaviour.
% No furhter macros are needed, and no change has to be made to the rest of the source.
%
% As of now, this package can hook into |\input| and |\include| using the |filehook| package.
% Furthermore, two hooks for |graphicx| and |csvsimple| are provided.
%
% \subsection{Package Options}\label{sec:PackageOptions}
%
% If the package is loaded without any option, then all hooks are installed.
% In case this is not wanted, each hook can be enabled individually.
% \begin{description}
%    \item[|main|] Attach the main source file.
%        This uses the |\AtBeginDocument| hook.
%    \item[|input|] Attach files loaded with |\input|.
%        This is done using |\AtBeginOfInputs| from the |filehook| package.
%        It also applies to every macro relying on |\input| to load external content.
%    \item[|include|] Attach files loaded with |\include|.
%        This is done using the |\AtBeginOfIncludes| hook.
%    \item[|graphicx|] Attach image files used with |\includegraphics|.
%        This patches some macro in the |graphicx| package, so make sure that it is loaded prior to |embedsources|.
%    \item[|csvsimple|] Attach data files used with the |csvsimple| package.
%        Make sure that it is already loaded.
% \end{description}
% Specifying any of these options will disable all hooks that are not enabled explicitly.
%
% There are some other options for very special cases.
% \begin{description}
%    \item[|all|] Enable all file type hooks.
%        This is the default and the option is mostly redundant.
%        However, it may be used to reenable all hooks, after an explicit type option has disabled them.
%    \item[|notall|] Do not enable all file type hooks.
%        As for the the |all| option, this is mostly useless, since it disables all effects this package was intended for.
%        However, some side effects may remain.
%        Consider not loading the package at all.
%    \item[|compat|] Enable compatibility mode to maintain some functionality from version 1.0.
%        Use this if your document needs the old style |\embedinput| macro.
%\end{description}
%
% \subsection{User Commands}
%
% \DescribeMacro{\embedfile \oarg{options} \marg{filename}}
% Although not defined by this package, it is made available by loading |embedfile|.
% You may use it to manually embed sources or any file, that is not covered by the hooks described above.
% See the |embedfile| documentation for more details.
%
% \DescribeMacro{\embedsource \oarg{options}}
% This macro can be used to embed the current TeX file in case the automatic hook has been disabled.
% Use it inside the file to be loaded.
% The \meta{options} are passed to the |\embedfile| macro.
% 
% \DescribeMacro{\embedinput \oarg{options} \marg{filename}}
% This command is a substitute for |\input{<filename>}| in compatibility mode.
% It adds the feature of attaching the file to the PDF after inserting it in the TeX source.
% The \meta{options} are ultimately passed to the |\embedfile| macro.
% As of version 2.0 with the automatic input file hook enabled, this is not needed anymore.
% Consider using |\embedsource| for manual embedding without the automatic hook.
%
% \section{Compatibility}
%
% This package heavily relies on |filehook|'s\footnote{filehook package: \url{https://ctan.org/pkg/filehook}} file hooks and |embedfile|'s\footnote{embedfile package: \url{https://ctan.org/pkg/embedfile}} file embedding.
% See the compatibility notes in their respective documentations.
%
% Furthermore, hooking into the |graphicx| and |csvsimple| macros is done by patching some of their macros.
% If they have not been loaded when |embedall| is loaded, this will fail.
% If they are loaded or reloaded after |embedall|, these patches may be overwritten.
% To ensure good functionality, load this package after all packages providing import commands.
%
% \StopEventually{}
%
% \section{Implementation}
%
% \subsection{Options}
%
% First, we need some booleans to store package options.
% The switch |embedall@all| acts on all types of hooks.
%    \begin{macrocode}
\newif\ifembedall@all
\embedall@alltrue
%    \end{macrocode}
% The following |embedall@<hook>| can be used to enable specific embedding hooks.
%    \begin{macrocode}
\newif\ifembedall@main
\embedall@mainfalse
\newif\ifembedall@input
\embedall@inputfalse
\newif\ifembedall@include
\embedall@includefalse
\newif\ifembedall@graphicx
\embedall@graphicxfalse
\newif\ifembedall@csvsimple
\embedall@csvsimplefalse
%    \end{macrocode}
% Compatibility mode is disabled by default.
%    \begin{macrocode}
\newif\ifembedall@compat
\embedall@compatfalse
%    \end{macrocode}
%
% Now, declare the actual package options.
%    \begin{macrocode}
\DeclareOption{all}{\embedall@alltrue}
\DeclareOption{notall}{\embedall@allfalse}
%    \end{macrocode}
% The following options correspond to the more specific embedding hooks mentioned above.
% Using any of these options will turn of general embedding off all source file types.
%    \begin{macrocode}
\DeclareOption{main}{\embedall@maintrue\embedall@allfalse}
\DeclareOption{input}{\embedall@inputtrue\embedall@allfalse}
\DeclareOption{include}{\embedall@includetrue\embedall@allfalse}
\DeclareOption{graphicx}{\embedall@graphicxtrue\embedall@allfalse}
\DeclareOption{csvsimple}{\embedall@csvsimpletrue\embedall@allfalse}
%    \end{macrocode}
% Request compatibility mode.
%    \begin{macrocode}
\DeclareOption{compat}{\embedall@compattrue}
%    \end{macrocode}
%
% Now, process these options.
%    \begin{macrocode}
\ProcessOptions\relax
%    \end{macrocode}
%
% Turn on all |embedall@<hook>| if |embedall@all| is |true|.
%    \begin{macrocode}
\ifembedall@all
    \embedall@maintrue
    \embedall@inputtrue
    \embedall@includetrue
    \embedall@graphicxtrue
    \embedall@csvsimpletrue
\fi
%    \end{macrocode}
%
% \subsection{Dependencies}
%
% Load packages for file embedding and file hooks.
%    \begin{macrocode}
\RequirePackage{embedfile}
\RequirePackage{filehook}
\RequirePackage{currfile}
\RequirePackage{etoolbox}
\ifembedall@compat
    \RequirePackage{letltxmacro}
\fi
%    \end{macrocode}
%
% \subsection{Macros}
%
% \begin{macro}{\embedsource}
% We define a shorthand to embed the current source file.
%    \begin{macrocode}
\newcommand\embedsource[1][]{\embedall@embed[#1]{\currfilename}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\embedall@filelist}
% Keep a list of files that have already been attached.
%    \begin{macrocode}
\def\embedall@filelist{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\embedall@embed}
% This is done to avoid embedding the same file multiple times.
%    \begin{macrocode}
\newcommand{\embedall@embed}[2][]{%
    \xifinlist{#2}{\embedall@filelist}{}{%
        \newlinechar=`\^^J%
        \message{^^J^^Jembedall: Attaching file '#2'.^^J^^J}%
        \embedfile[#1]{#2}%
        \listxadd{\embedall@filelist}{#2}%
    }%
}
%    \end{macrocode}
% \end{macro}
%
% \subsection{Compatibility Commands}
%
% The following macros are only defined in compatibility mode to maintain backward compatibility.
%    \begin{macrocode}
\ifembedall@compat
%    \end{macrocode}
%
% \begin{macro}{\embedall@includegraphics}
% This macro is the modified version of |\includegraphics| command from the |graphicx| package with included the |\embedfile| command.
% First the original |\includegraphics| command is stored inside the not-user-accessible |\embedall@latex@includegraphics|.
%    \begin{macrocode}
    \LetLtxMacro\embedall@latex@includegraphics\includegraphics
%    \end{macrocode}
% |\LetLtxMacro| is used (instead of simply |\let|) because some packages modify the |\includegraphics| command.
% For this reason you can not use the * variant of this command but you have to declare the |clip| option instead.
%
% Then the |\embedall@includegraphics| is defined
%    \begin{macrocode}
    \newcommand\embedall@includegraphics[2][]{%
        \embedall@embed[desc=image]{#2}
        \embedall@latex@includegraphics[#1]{#2}%
    }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\embedall@listinputlisting}
% This macro is the modified version of |\listinputlisting| command from the |listings| package with included the |\embedfile| command.
% First the original |\listinputlisting| command is stored inside the not-user-accessible |\embedall@latex@listinputlisting|.
%    \begin{macrocode}
    \LetLtxMacro\embedall@latex@lstinputlisting\lstinputlisting
%    \end{macrocode}
% Then the |\embedall@listinputlisting| is defined
%    \begin{macrocode}
    \newcommand\embedall@lstinputlisting[2][]{%
        \embedfile[desc=listing file]{#2}
        \embedall@latex@lstinputlisting[#1]{#2}%
    }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\embedinput}
% This command can be used as a substitute for |\input| to manually embed the source if the automatic file hook is not enabled.
% Otherwise, it will just call |\input| without further side effects.
% The additional optional parameter sets the input file description in the generated PDF.
%    \begin{macrocode}
    \ifembedall@input
        \DeclareRobustCommand\embedinput[2][]{%
            \input{#2}%
        }
    \else
        \DeclareRobustCommand\embedinput[2][input file]{%
            \input{#2}%
            \embedall@embed[desc={#1}]{#2}%
        }
    \fi
\fi
%    \end{macrocode}
% \end{macro}
%
% \subsection{Installing Hooks}
%
% The actual work happens here.
% First, the main source file is attached.
%    \begin{macrocode}
\ifembedall@main
    \ifembedall@compat
        \IfFileExists{./\jobname.tex}{%
            \embedall@embed[desc=main source file]{\jobname.tex}
        }{}
    \else
        \AtBeginDocument{\embedsource[desc=main source file]}
    \fi
\fi
%    \end{macrocode}
% These macros are provided by the |embedfile| and |currfile| packages.
%
% Then, the hooks for |\input| and |\include| are installed, given the respective switch was enabled.
%    \begin{macrocode}
\ifembedall@input
    \AtBeginOfInputs{\embedsource[desc=input file]}
\fi
\ifembedall@include
    \AtBeginOfIncludes{\embedsource[desc=include file]}
\fi
%    \end{macrocode}
% The macros |\AtBeginOfInputs| and |\AtBeginOfIncludes| are provided by the |filehook| package.
%
% For the |graphicx| hook, we need to patch the |\Gin@setfile| macro to call |\embedfile| after finishing its own work.
% At this point, the full file name including the file name extension will be available as the third argument passed to the macro.
%    \begin{macrocode}
\ifembedall@graphicx
    \ifcsname Gin@setfile\endcsname
        \let\embedall@Gin@setfile\Gin@setfile
        \def\Gin@setfile#1#2#3{%
            \embedall@Gin@setfile{#1}{#2}{#3}%
            \embedall@embed[image file]{#3}%
        }
%    \end{macrocode}
% Issue a warning if |\Gin@setfile| does not exists.
% This could happen in the unlikely case that the internal workings of |graphicx| have changed, or, more likely, because the package was not loaded.
%    \begin{macrocode}
    \else
        \ifembedall@all\else
            \PackageWarning{embedall}{Patching of graphicx requested, but package not loaded. Consider removing the 'graphicx' option.}
        \fi
    \fi
\fi
%    \end{macrocode}
%
% The |csvsimple| hook is very similar to the |graphicx| hook.
% It patches into the |\csvloop| macro which is used by all other user macros to do the actual work.
%    \begin{macrocode}
\ifembedall@csvsimple
    \ifcsname csvloop\endcsname
        \let\embedall@csvloop\csvloop
        \def\csvloop#1{%
            \embedall@csvloop{#1}%
            \embedall@embed[CSV file]{\csv@input@filename}%
        }
    \else
        \ifembedall@all\else
            \PackageWarning{embedall}{Patching of csvsimple requested explicitly, but package not loaded. Consider removing the 'csvsimple' option.}
        \fi
    \fi
\fi
%    \end{macrocode}
% The |\csv@input@filename| macro is used in the |csvsimple| macro to store the input file name.
%
% \Finale
%
\endinput