Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2013 by Alberto Sartori
4 % Copyright (C) 2019 by David Lichti
5 % -------------------------------------------------------
6 %
7 % This file may be distributed and/or modified under the
8 % conditions of the LaTeX Project Public License, either
9 % version 1.3 of this license or (at your option) any later
10 % version. The latest version of this license is in:
11 %
12 % http://www.latex-project.org/lppl.txt
13 %
14 % and version 1.3 or later is part of all distributions of
15 % LaTeX version 2005/12/01 or later.
16 %
17 % \fi
18 %
19 % \iffalse
20 %
21 %<package>\NeedsTeXFormat{LaTeX2e}
22 %<package>\ProvidesClass{embedall}[2019/05/18 v2.0 Automatically embed source files in PDF]
23 %
24 %<*driver>
25 \documentclass{ltxdoc}
26 \usepackage[notall]{embedall}[2019/05/18]
27 \usepackage[utf8]{inputenc}
28 \usepackage[T1]{fontenc}
29 \usepackage[osf,sc]{mathpazo}
30 \usepackage{parskip}
31 \renewcommand\sfdefault{lmsf}
32 \renewcommand\ttdefault{lmtt}
33 \usepackage{microtype}
34 \linespread{1.1}
35 \usepackage{enumitem}
36 \setdescription{font=\itshape,leftmargin=2cm,style=sameline}
37 \usepackage{hyperref}
38 \EnableCrossrefs
39 \CodelineIndex
40 \RecordChanges
41 \begin{document}
42 \DocInput{embedall.dtx}
43 \end{document}
44 %</driver>
45 %
46 % \fi
47 %
48 % \CheckSum{154}
49 %
50 % \CharacterTable
51 % {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
52 % 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
53 % Digits \0\1\2\3\4\5\6\7\8\9
54 % Exclamation \! Double quote \" Hash (number) \#
55 % Dollar \$ Percent \% Ampersand \&
56 % Acute accent \' Left paren \( Right paren \)
57 % Asterisk \* Plus \+ Comma \,
58 % Minus \- Point \. Solidus \/
59 % Colon \: Semicolon \; Less than \<
60 % Equals \= Greater than \> Question mark \?
61 % Commercial at \@ Left bracket \[ Backslash \\
62 % Right bracket \] Circumflex \^ Underscore \_
63 % Grave accent \` Left brace \{ Vertical bar \|
64 % Right brace \} Tilde \~}
65 %
66 % \changes{v1.0}{2013/10/10}{Initial version}
67 % \changes{v2.0}{2019/05/18}{Overhaul using filehook package}
68 %
69 % \GetFileInfo{embedall.sty}
70 %
71 % \DoNotIndex{\newcommand,\def,\let,\DeclareRobustCommand}
72 % \DoNotIndex{\newif,\DeclareOption,\ProcessOptions,\relax,\RequirePackage,\fi,\else,\ifcsname,\endcsname,\PackageWarning,\^\^}
73 % \DoNotIndex{\AtBeginDocument,\IfFileExists,\input,\jobname,\LetLtxMacro,\listxadd,\message,\newlinechar,\xifinlist}
74 % \DoNotIndex{\embedfile,\currfilename,\AtBeginOfInputs,\AtBeginOfIncludes}
75 % \DoNotIndex{\Gin@setfile}
76 % \DoNotIndex{\csvloop,\csv@input@filename}
77 %
78 % \title{The \textbf{embedall} package\thanks{This document
79 % corresponds to \textsf{embedall}~\fileversion, dated \filedate.}}
80 % \author{
81 % Alberto Sartori -- \texttt{\href{mailto:[email protected]}{[email protected]}}\\
82 % David Lichti -- \texttt{\href{mailto:[email protected]}{[email protected]}}
83 % }
84 %
85 % \maketitle
86 %
87 % \embedsource[desc=main source file]
88 %
89 % \section{Introduction}
90 %
91 % This package is designed to help you storing your projects without losing anything.
92 % It uses the |filehook| package and some custom patches to hook into several supported import mechanisms.
93 % These imported files are then attached to the PDF file using the |embedfile| package.
94 % In particular it can embed images, external TeX files, external code listings, CSV files, and, most importantly, the main TeX file itself.
95 %
96 % \section{Usage}
97 %
98 % To use the package, simply add |\usepackage{embedsources}| to your document's preamble.
99 % Without any option, the default behaviour is to attach all supported source file types to the finished document.
100 % See section~\ref{sec:PackageOptions} for options to change this behaviour.
101 % No furhter macros are needed, and no change has to be made to the rest of the source.
102 %
103 % As of now, this package can hook into |\input| and |\include| using the |filehook| package.
104 % Furthermore, two hooks for |graphicx| and |csvsimple| are provided.
105 %
106 % \subsection{Package Options}\label{sec:PackageOptions}
107 %
108 % If the package is loaded without any option, then all hooks are installed.
109 % In case this is not wanted, each hook can be enabled individually.
110 % \begin{description}
111 % \item[|main|] Attach the main source file.
112 % This uses the |\AtBeginDocument| hook.
113 % \item[|input|] Attach files loaded with |\input|.
114 % This is done using |\AtBeginOfInputs| from the |filehook| package.
115 % It also applies to every macro relying on |\input| to load external content.
116 % \item[|include|] Attach files loaded with |\include|.
117 % This is done using the |\AtBeginOfIncludes| hook.
118 % \item[|graphicx|] Attach image files used with |\includegraphics|.
119 % This patches some macro in the |graphicx| package, so make sure that it is loaded prior to |embedsources|.
120 % \item[|csvsimple|] Attach data files used with the |csvsimple| package.
121 % Make sure that it is already loaded.
122 % \end{description}
123 % Specifying any of these options will disable all hooks that are not enabled explicitly.
124 %
125 % There are some other options for very special cases.
126 % \begin{description}
127 % \item[|all|] Enable all file type hooks.
128 % This is the default and the option is mostly redundant.
129 % However, it may be used to reenable all hooks, after an explicit type option has disabled them.
130 % \item[|notall|] Do not enable all file type hooks.
131 % As for the the |all| option, this is mostly useless, since it disables all effects this package was intended for.
132 % However, some side effects may remain.
133 % Consider not loading the package at all.
134 % \item[|compat|] Enable compatibility mode to maintain some functionality from version 1.0.
135 % Use this if your document needs the old style |\embedinput| macro.
136 %\end{description}
137 %
138 % \subsection{User Commands}
139 %
140 % \DescribeMacro{\embedfile \oarg{options} \marg{filename}}
141 % Although not defined by this package, it is made available by loading |embedfile|.
142 % You may use it to manually embed sources or any file, that is not covered by the hooks described above.
143 % See the |embedfile| documentation for more details.
144 %
145 % \DescribeMacro{\embedsource \oarg{options}}
146 % This macro can be used to embed the current TeX file in case the automatic hook has been disabled.
147 % Use it inside the file to be loaded.
148 % The \meta{options} are passed to the |\embedfile| macro.
149 %
150 % \DescribeMacro{\embedinput \oarg{options} \marg{filename}}
151 % This command is a substitute for |\input{<filename>}| in compatibility mode.
152 % It adds the feature of attaching the file to the PDF after inserting it in the TeX source.
153 % The \meta{options} are ultimately passed to the |\embedfile| macro.
154 % As of version 2.0 with the automatic input file hook enabled, this is not needed anymore.
155 % Consider using |\embedsource| for manual embedding without the automatic hook.
156 %
157 % \section{Compatibility}
158 %
159 % 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.
160 % See the compatibility notes in their respective documentations.
161 %
162 % Furthermore, hooking into the |graphicx| and |csvsimple| macros is done by patching some of their macros.
163 % If they have not been loaded when |embedall| is loaded, this will fail.
164 % If they are loaded or reloaded after |embedall|, these patches may be overwritten.
165 % To ensure good functionality, load this package after all packages providing import commands.
166 %
167 % \StopEventually{}
168 %
169 % \section{Implementation}
170 %
171 % \subsection{Options}
172 %
173 % First, we need some booleans to store package options.
174 % The switch |embedall@all| acts on all types of hooks.
175 % \begin{macrocode}
176 \newif\ifembedall@all
177 \embedall@alltrue
178 % \end{macrocode}
179 % The following |embedall@<hook>| can be used to enable specific embedding hooks.
180 % \begin{macrocode}
181 \newif\ifembedall@main
182 \embedall@mainfalse
183 \newif\ifembedall@input
184 \embedall@inputfalse
185 \newif\ifembedall@include
186 \embedall@includefalse
187 \newif\ifembedall@graphicx
188 \embedall@graphicxfalse
189 \newif\ifembedall@csvsimple
190 \embedall@csvsimplefalse
191 % \end{macrocode}
192 % Compatibility mode is disabled by default.
193 % \begin{macrocode}
194 \newif\ifembedall@compat
195 \embedall@compatfalse
196 % \end{macrocode}
197 %
198 % Now, declare the actual package options.
199 % \begin{macrocode}
200 \DeclareOption{all}{\embedall@alltrue}
201 \DeclareOption{notall}{\embedall@allfalse}
202 % \end{macrocode}
203 % The following options correspond to the more specific embedding hooks mentioned above.
204 % Using any of these options will turn of general embedding off all source file types.
205 % \begin{macrocode}
206 \DeclareOption{main}{\embedall@maintrue\embedall@allfalse}
207 \DeclareOption{input}{\embedall@inputtrue\embedall@allfalse}
208 \DeclareOption{include}{\embedall@includetrue\embedall@allfalse}
209 \DeclareOption{graphicx}{\embedall@graphicxtrue\embedall@allfalse}
210 \DeclareOption{csvsimple}{\embedall@csvsimpletrue\embedall@allfalse}
211 % \end{macrocode}
212 % Request compatibility mode.
213 % \begin{macrocode}
214 \DeclareOption{compat}{\embedall@compattrue}
215 % \end{macrocode}
216 %
217 % Now, process these options.
218 % \begin{macrocode}
219 \ProcessOptions\relax
220 % \end{macrocode}
221 %
222 % Turn on all |embedall@<hook>| if |embedall@all| is |true|.
223 % \begin{macrocode}
224 \ifembedall@all
225 \embedall@maintrue
226 \embedall@inputtrue
227 \embedall@includetrue
228 \embedall@graphicxtrue
229 \embedall@csvsimpletrue
230 \fi
231 % \end{macrocode}
232 %
233 % \subsection{Dependencies}
234 %
235 % Load packages for file embedding and file hooks.
236 % \begin{macrocode}
237 \RequirePackage{embedfile}
238 \RequirePackage{filehook}
239 \RequirePackage{currfile}
240 \RequirePackage{etoolbox}
241 \ifembedall@compat
242 \RequirePackage{letltxmacro}
243 \fi
244 % \end{macrocode}
245 %
246 % \subsection{Macros}
247 %
248 % \begin{macro}{\embedsource}
249 % We define a shorthand to embed the current source file.
250 % \begin{macrocode}
251 \newcommand\embedsource[1][]{\embedall@embed[#1]{\currfilename}}
252 % \end{macrocode}
253 % \end{macro}
254 %
255 % \begin{macro}{\embedall@filelist}
256 % Keep a list of files that have already been attached.
257 % \begin{macrocode}
258 \def\embedall@filelist{}
259 % \end{macrocode}
260 % \end{macro}
261 %
262 % \begin{macro}{\embedall@embed}
263 % This is done to avoid embedding the same file multiple times.
264 % \begin{macrocode}
265 \newcommand{\embedall@embed}[2][]{%
266 \xifinlist{#2}{\embedall@filelist}{}{%
267 \newlinechar=`\^^J%
268 \message{^^J^^Jembedall: Attaching file '#2'.^^J^^J}%
269 \embedfile[#1]{#2}%
270 \listxadd{\embedall@filelist}{#2}%
271 }%
272 }
273 % \end{macrocode}
274 % \end{macro}
275 %
276 % \subsection{Compatibility Commands}
277 %
278 % The following macros are only defined in compatibility mode to maintain backward compatibility.
279 % \begin{macrocode}
280 \ifembedall@compat
281 % \end{macrocode}
282 %
283 % \begin{macro}{\embedall@includegraphics}
284 % This macro is the modified version of |\includegraphics| command from the |graphicx| package with included the |\embedfile| command.
285 % First the original |\includegraphics| command is stored inside the not-user-accessible |\embedall@latex@includegraphics|.
286 % \begin{macrocode}
287 \LetLtxMacro\embedall@latex@includegraphics\includegraphics
288 % \end{macrocode}
289 % |\LetLtxMacro| is used (instead of simply |\let|) because some packages modify the |\includegraphics| command.
290 % For this reason you can not use the * variant of this command but you have to declare the |clip| option instead.
291 %
292 % Then the |\embedall@includegraphics| is defined
293 % \begin{macrocode}
294 \newcommand\embedall@includegraphics[2][]{%
295 \embedall@embed[desc=image]{#2}
296 \embedall@latex@includegraphics[#1]{#2}%
297 }
298 % \end{macrocode}
299 % \end{macro}
300 %
301 % \begin{macro}{\embedall@listinputlisting}
302 % This macro is the modified version of |\listinputlisting| command from the |listings| package with included the |\embedfile| command.
303 % First the original |\listinputlisting| command is stored inside the not-user-accessible |\embedall@latex@listinputlisting|.
304 % \begin{macrocode}
305 \LetLtxMacro\embedall@latex@lstinputlisting\lstinputlisting
306 % \end{macrocode}
307 % Then the |\embedall@listinputlisting| is defined
308 % \begin{macrocode}
309 \newcommand\embedall@lstinputlisting[2][]{%
310 \embedfile[desc=listing file]{#2}
311 \embedall@latex@lstinputlisting[#1]{#2}%
312 }
313 % \end{macrocode}
314 % \end{macro}
315 %
316 % \begin{macro}{\embedinput}
317 % This command can be used as a substitute for |\input| to manually embed the source if the automatic file hook is not enabled.
318 % Otherwise, it will just call |\input| without further side effects.
319 % The additional optional parameter sets the input file description in the generated PDF.
320 % \begin{macrocode}
321 \ifembedall@input
322 \DeclareRobustCommand\embedinput[2][]{%
323 \input{#2}%
324 }
325 \else
326 \DeclareRobustCommand\embedinput[2][input file]{%
327 \input{#2}%
328 \embedall@embed[desc={#1}]{#2}%
329 }
330 \fi
331 \fi
332 % \end{macrocode}
333 % \end{macro}
334 %
335 % \subsection{Installing Hooks}
336 %
337 % The actual work happens here.
338 % First, the main source file is attached.
339 % \begin{macrocode}
340 \ifembedall@main
341 \ifembedall@compat
342 \IfFileExists{./\jobname.tex}{%
343 \embedall@embed[desc=main source file]{\jobname.tex}
344 }{}
345 \else
346 \AtBeginDocument{\embedsource[desc=main source file]}
347 \fi
348 \fi
349 % \end{macrocode}
350 % These macros are provided by the |embedfile| and |currfile| packages.
351 %
352 % Then, the hooks for |\input| and |\include| are installed, given the respective switch was enabled.
353 % \begin{macrocode}
354 \ifembedall@input
355 \AtBeginOfInputs{\embedsource[desc=input file]}
356 \fi
357 \ifembedall@include
358 \AtBeginOfIncludes{\embedsource[desc=include file]}
359 \fi
360 % \end{macrocode}
361 % The macros |\AtBeginOfInputs| and |\AtBeginOfIncludes| are provided by the |filehook| package.
362 %
363 % For the |graphicx| hook, we need to patch the |\Gin@setfile| macro to call |\embedfile| after finishing its own work.
364 % At this point, the full file name including the file name extension will be available as the third argument passed to the macro.
365 % \begin{macrocode}
366 \ifembedall@graphicx
367 \ifcsname Gin@setfile\endcsname
368 \let\embedall@Gin@setfile\Gin@setfile
369 \def\Gin@setfile#1#2#3{%
370 \embedall@Gin@setfile{#1}{#2}{#3}%
371 \embedall@embed[image file]{#3}%
372 }
373 % \end{macrocode}
374 % Issue a warning if |\Gin@setfile| does not exists.
375 % This could happen in the unlikely case that the internal workings of |graphicx| have changed, or, more likely, because the package was not loaded.
376 % \begin{macrocode}
377 \else
378 \ifembedall@all\else
379 \PackageWarning{embedall}{Patching of graphicx requested, but package not loaded. Consider removing the 'graphicx' option.}
380 \fi
381 \fi
382 \fi
383 % \end{macrocode}
384 %
385 % The |csvsimple| hook is very similar to the |graphicx| hook.
386 % It patches into the |\csvloop| macro which is used by all other user macros to do the actual work.
387 % \begin{macrocode}
388 \ifembedall@csvsimple
389 \ifcsname csvloop\endcsname
390 \let\embedall@csvloop\csvloop
391 \def\csvloop#1{%
392 \embedall@csvloop{#1}%
393 \embedall@embed[CSV file]{\csv@input@filename}%
394 }
395 \else
396 \ifembedall@all\else
397 \PackageWarning{embedall}{Patching of csvsimple requested explicitly, but package not loaded. Consider removing the 'csvsimple' option.}
398 \fi
399 \fi
400 \fi
401 % \end{macrocode}
402 % The |\csv@input@filename| macro is used in the |csvsimple| macro to store the input file name.
403 %
404 % \Finale
405 %
406 \endinput