Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2004 by Maarten Sneep
4 % -----------------------------------------------------
5 %
6 % This work is licensed under the CC-GNU GPL, the human readable license
7 % can be found here, with a link to the full text on this page.
8 % http://creativecommons.org/licenses/GPL/2.0/
9 %
10 % To process this file run the accompanying xmpincl.ins file through tex.
11 % To get the documentation, run this file through pdfLaTeX.
12 %
13 % \fi
14 %
15 % \iffalse
16 %
17 %<*driver>
18 \ProvidesFile{xmpincl.dtx}
19 %</driver>
20 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
21 %<package>\ProvidesPackage{xmpincl}
22 %<*package>
23 [2021/09/22 v2.4 Include XMP data in pdflatex]
24 %</package>
25 %
26 %<*driver>
27 \documentclass{ltxdoc}
28 \usepackage{hyperref}
29 \usepackage{url}
30 \usepackage{xmpincl}
31 \hypersetup{colorlinks=true, pdftitle={Including XMP in pdflatex},
32 pdfauthor={Maarten Sneep},
33 pdfsubject={pdflatex and XMP inclusions.}, pdfkeywords={XMP, Creative Commons},
34 pdfview={FitH}, pdfstartview={FitH}, pdfstartpage={1}, plainpages=false}
35 \includexmp{license}
36 \DisableCrossrefs
37 %\CodelineIndex
38 %\RecordChanges
39 %\OnlyDescription
40 \begin{document}
41 \DocInput{xmpincl.dtx}
42 \end{document}
43 %</driver>
44 % \fi
45 %
46 % \CheckSum{121}
47 %
48 % \CharacterTable
49 % {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
50 % 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
51 % Digits \0\1\2\3\4\5\6\7\8\9
52 % Exclamation \! Double quote \" Hash (number) \#
53 % Dollar \$ Percent \% Ampersand \&
54 % Acute accent \' Left paren \( Right paren \)
55 % Asterisk \* Plus \+ Comma \,
56 % Minus \- Point \. Solidus \/
57 % Colon \: Semicolon \; Less than \<
58 % Equals \= Greater than \> Question mark \?
59 % Commercial at \@ Left bracket \[ Backslash \\
60 % Right bracket \] Circumflex \^ Underscore \_
61 % Grave accent \` Left brace \{ Vertical bar \|
62 % Right brace \} Tilde \~}
63 %
64 %
65 % \changes{v1.0}{2004/06/20}{Initial release}
66 % \changes{v1.1}{2004/06/20}{Fixed some miscelaneous typos and removed support
67 % for the package option}
68 % \changes{v1.2}{2004/12/12}{Correctly detect pdftex usage -- rely on the ifpdf
69 % package, not on whether the pdfoutput command is defined}
70 % \changes{v1.3}{2005/02/14}{Clarified which parts are included in the
71 % meta-information, and what isn't.}
72 % \changes{v2.0}{2005/02/15}{Major release. Added code that will append
73 % the xpacket bits, if they are not already there.}
74 % \changes{v2.1}{2005/03/24}{Minor update: ifpdf and Memoir no longer bite each
75 % other. When used with Memoir, version ``2005/03/23 v3.9 Patches for memoir
76 % class v1.61'' of mempatch.sty is required.}
77 % \changes{v2.2}{2008/05/10}{Minor update: made |~| and |&| normal characters
78 % when writing the xmpi file. I still need to find a way to include |%|
79 % characters in the xmpi file.}
80 % \changes{v2.3}{2021/08/31}{Replaced \cs{if}\cs{par} with \cs{ifx}\cs{par}
81 % because the former caused an error with the new definition of \cs{par}.}
82 % \changes{v2.4}{2021/09/22}{Replaced \cs{ifx}\cs{par} with \cs{if}\cs{endline}
83 % because the former caused pdf/a validation errors.}
84 %
85 % \GetFileInfo{xmpincl.dtx}
86 %
87 % \DoNotIndex{\newcommand,\newenvironment}
88 % \DoNotIndex{\#,\$,\%,\&,\@,\\,\{,\},\^,\_,\~,\ }
89 % \DoNotIndex{\@ne}
90 % \DoNotIndex{\advance,\begingroup,\catcode,\closein}
91 % \DoNotIndex{\closeout,\day,\def,\edef,\else,\empty,\endgroup}
92 %
93 % \title{The \textsf{XMP} inclusion package\thanks{This document
94 % corresponds to \textsf{xmpincl.dtx}~\fileversion, dated \filedate.}}
95 % \author{Maarten Sneep}
96 % \date{\filedate}
97 %
98 % \maketitle
99 %
100 % \section{Introduction}
101 %
102 % The |XMP| (eXtensible Metadata Platform) is a framework to add metadata
103 % to digital material to enhance the workflow in publication. References
104 % are given below, but the essence is that the metadata is stored in an
105 % |XML| file, and this XML stream is then embedded in the file to which it
106 % applies. How you create this |XML| file is up to you, but I started
107 % investigating this, because I wanted to embed some licensing information
108 % in the files I create. The license I chose is one of the
109 % \textsf{Creative Commons} licenses, and their web-site offers this
110 % information in a valid |XML| file, suitable for direct inclusion.
111 %
112 % Note that this package is released under the
113 % \href{http://creativecommons.org/licenses/GPL/2.0/}{CC-GNU GPL} license.
114 % You can redistribute, but I kindly request that you update the version
115 % number, add a description of what you added or changed -- if possible
116 % with an explanation as to why -- and re-submit to CTAN, to keep it all
117 % in a single location. You can also submit changes to me, I regularly
118 % read |comp.text.tex| on usenet.
119 %
120 % Many thanks to James Howison for pushing me to put in the
121 % |<?xpacket ?>| writing code, and suggesting to test whether they
122 % are already there.
123 %
124 % Thanks to Martin Szummer for reporting that a |~| in an URL inside the
125 % xmp file will not work.
126 %
127 % \subsection{Usage}
128 %
129 % This package defines a single command, |\includexmp{}|. The |xmp| file
130 % is specified as an argument to this command. Although there is no real
131 % specification as to where the xml-stream should be inserted into the
132 % document, I would advise to put it at the start of the file, so call the
133 % |\includexmp{}| command before |\begin{document}|. Note that the package
134 % will add the extension |.xmp| to the base filename. To include the file
135 % |metadata.xmp|, use the following:
136 %
137 %\begin{verbatim}
138 %. . .
139 %\usepackage{xmpincl}
140 %\includexmp{metadata}
141 %. . .
142 %\begin{document}
143 %. . .
144 %\end{verbatim}
145 %
146 % The file |metadata.xmp| should exist in the same directory as the master
147 % document. At the end of this documentation a sample file is included
148 % that will yield a valid |XMP| enhanced pdf file.
149 %
150 % Previous versions of this package required the inclusion of the
151 % |<?xpacket ?>| tags into the |XMP| file. This is against the standards,
152 % and several users requested that this functionality be added to the
153 % package. This new release (version 2.0) does add the |<?xpacket ?>|
154 % tags, if they are \emph{not} present in the |xmp| file.
155 %
156 % \subsection{New in the release v2.1}
157 %
158 % There used to be a clash between the Memoir document class and the |ifpdf| package.
159 % As of version 2005/03/23 v3.9 of |mempatch.sty|, this clash has been removed, and
160 % glue code that was present here, has been removed in this update. Note that this
161 % may mean that you'll need to update your distribution to include teh latest
162 % |mempatch.sty|.
163 %
164 % \subsection{References}
165 %
166 % \begin{itemize}
167 % \item \url{http://creativecommons.org/}
168 % \item \url{http://creativecommons.org/technology/xmp-help}
169 % \item \url{http://www.adobe.com/products/xmp}
170 % \end{itemize}
171 %
172 % \PrintChanges
173 %
174 % \StopEventually{}
175 %
176 % \section{Implementation}
177 %
178 % First we determine if we run under pdf\LaTeX{}, in pdf-production mode.
179 % This is best done with the |ifpdf| package. The Memoir documentclass also
180 % defines the |\ifpdf| boolean, but didn't actually load the |ifpdf| package.
181 % As of version ``2005/03/23 v3.9 Patches for memoir class v1.61'' of |mempatch.sty|
182 % teh loading of the ifpdf package is properly faked, and we no longer need to
183 % check for the existence of the |\ifpdf| boolean.
184 % \begin{macrocode}
185 %<*package>
186 \RequirePackage{ifpdf}
187 \ifpdf\else
188 % \end{macrocode}
189 % Apparently we do not run under pdflatex, or we are producing DVI.
190 % Someone else may try to do this correcltly for PostScript output. Note
191 % that a metacomment has to be added to the start of the |.ps| document,
192 % and that is something for which I have no clue on how to accomplish that
193 % from within \TeX{}.
194 %
195 % Right now I just skip non-pdflatex support and issue a warning.
196 % \begin{macrocode}
197 \PackageWarningNoLine{xmpincl}%
198 {Only pdflatex is supported by the xmpincl package}
199 % \end{macrocode}
200 % \DescribeMacro{includexmp}
201 % This is the latex (|DVI|) edition: just issue a warning, and stop
202 % reading the rest of this file
203 % \begin{macrocode}
204 \newcommand{\includexmp}[1]{%
205 \PackageError{xmpincl}%
206 {latex is not supported by the \protect\includexmp\space package}%
207 {You tried to include XMP metadata in DVI production.\MessageBreak
208 That doesn't work, and I friendly tried to warn you.\MessageBreak
209 Just continue and pretend nothing is wrong,\MessageBreak
210 but please remove the package or switch to pdflatex.}
211 }
212 % \end{macrocode}
213 % Stop reading this file, as the rest only works when generating |pdf|
214 % directly.
215 % \begin{macrocode}
216 \relax\expandafter\endinput
217 \fi
218 % \end{macrocode}
219 % The |ifthen| package is loaded, for the string comparisons later on.
220 % \begin{macrocode}
221 \RequirePackage{ifthen}
222 % \end{macrocode}
223 % \DescribeMacro{mcs@xmpincl@patchFile}
224 % Based on popular feedback, we now add the |<?xpacket . . .?>| parts
225 % ourselves. This can be a bit tricky, so bear with me. I basically create
226 % a new file |.xmpi| which starts off with the |<?xpacket ?>| tag, copy
227 % the whole |XMP| file to this new file, and add the |<?xpacket ?>| close
228 % tag. Of course, this is new functionality, so we still have to take care
229 % of our backward compatibility issues. So we check that what we've read is
230 % not an |<?xpacket ?>| tag. I'm aware of the odd combination of \TeX{}
231 % and \LaTeX{} coding here, but I didn't manage to get the string
232 % comparison working in palin \TeX{} code, and this \LaTeX{} code is
233 % maintained by others, something I really don't mind.
234 %
235 % The macro starts off by opening a few files, one for reading the user
236 % supplied |XMP|, and another one for writing it back out again, but this
237 % time with the |<?xpacket ?>| bits included.
238 % \begin{macrocode}
239 \newcommand*{\mcs@xmpincl@patchFile}[1]{
240 \begingroup
241 \newwrite\xmpinclWrite
242 \newread\xmpinclRead
243 \immediate\openin\xmpinclRead #1.xmp
244 \immediate\openout\xmpinclWrite #1.xmpi
245 % \end{macrocode}
246 % \DescribeMacro{mcs@xmpinclStart}
247 % \DescribeMacro{mcs@xmpinclStartAlt}
248 % \DescribeMacro{mcs@xmpinclEnd}
249 % The begin and en |<?xpacket ?>| strings are put in some macros to
250 % easier access. Yes, that start string was double checked against the
251 % documentation provided by Adobe. The alternate starting string is there
252 % because the |id| seems to be optional, if I understand the documentation
253 % correctly.
254 % \begin{macrocode}
255 \newcommand{\mcs@xmpinclStart}%
256 {<?xpacket begin='' id='W5M0MpCehiHzreSzNTczkc9d'?> }
257 \newcommand{\mcs@xmpinclStartAlt}%
258 {<?xpacket begin='' id=''?> }
259 \newcommand{\mcs@xmpinclEnd}%
260 {<?xpacket end='r'?> }
261 % \end{macrocode}
262 % Next we change the catcode of |#| to `other'. This is just to prevent
263 % misinterpretation of this character. Of course there are more special
264 % characters, but as far as I can see, these aren't treated in any special
265 % way (|#| is doubled by \TeX{} to |##|).
266 % \begin{macrocode}
267 \catcode`\#=12
268 % \end{macrocode}
269 % We deactivate |~| and |&| as well.
270 % \begin{macrocode}
271 \catcode`\~=12
272 \catcode`\&=12
273 % \end{macrocode}
274 % Read the first line of the input file, and compare it to the start tag,
275 % and the alternate start tag. If they match, write out the standard start
276 % tag (including the |id|). If they don't match, write out the start tag,
277 % followed by the line we've just read.
278 % \begin{macrocode}
279 \immediate\read\xmpinclRead to\xmpinclReadln%
280 \ifthenelse{%
281 \equal{\mcs@xmpinclStart}{\xmpinclReadln}%
282 \or%
283 \equal{\mcs@xmpinclStartAlt}{\xmpinclReadln}%
284 }%
285 {%
286 \immediate\write\xmpinclWrite{\mcs@xmpinclStart}%
287 }%
288 {%
289 \immediate\write\xmpinclWrite{\mcs@xmpinclStart}%
290 \immediate\write\xmpinclWrite{\xmpinclReadln}%
291 }%
292 % \end{macrocode}
293 % Start the |\loop|, and read a line. Check if it is equal to the end tag
294 % or to |\endline|, and if it isn't, write it out to the |.xmpi| file. The
295 % check against |\endline| ensures that empty lines are skipped, and not
296 % replaced by |\par|.
297 %
298 % The |\ifeof| test checks whether we've reached the end of the original
299 % |.xmp| file, and |\repeat|s the |\loop| if we haven't.
300 % \begin{macrocode}
301 \loop%
302 \immediate\read\xmpinclRead to\xmpinclReadln%
303 \ifthenelse{%
304 \equal{\mcs@xmpinclEnd}{\xmpinclReadln}%
305 }{% Note: no if.
306 }{%
307 \if\endline\xmpinclReadln\else%
308 \immediate\write\xmpinclWrite{\xmpinclReadln}%
309 \fi%
310 }%
311 \ifeof\xmpinclRead\else%
312 \repeat
313 % \end{macrocode}
314 % Since we skipped any end |<?xpacket ?>| tags, we write it here. After
315 % that we close both files and end the current group (restoring the
316 % meaning of |#|, |&|, and |~|).
317 % \begin{macrocode}
318 \immediate\write\xmpinclWrite{\mcs@xmpinclEnd}
319 \immediate\closein\xmpinclRead
320 \immediate\closeout\xmpinclWrite
321 \endgroup
322 }
323 % \end{macrocode}
324 % \DescribeMacro{includexmp}
325 % The meat of the business. Actually pretty trivial, once you know
326 % how\ldots
327 % \begin{macrocode}
328 \newcommand{\includexmp}[1]{%
329 % \end{macrocode}
330 % First check that the file can be found, and if we use the new methods,
331 % convert it.
332 % \begin{macrocode}
333 \IfFileExists{#1.xmp}{
334 \mcs@xmpincl@patchFile{#1}
335 % \end{macrocode}
336 % Reset the |\pdfcompresslevel| to 0, do not compress the |XML| data.
337 % This is recommended by Adobe, so that file utilities can grep the |.pdf|
338 % file for metadata, without the full capability to actually parse the
339 % |pdf| file.
340 % Keep the change local.
341 % \begin{macrocode}
342 \begingroup
343 \pdfcompresslevel=0
344 % \end{macrocode}
345 % Write out the |pdf| object, with the specifications given in the
346 % reference manual found at \url{http://www.adobe.com/products/xmp}. The
347 % |file| attribute reads the specified file from disk, although it is not
348 % clear to me if it uses the full \TeX{} search path. To be safe, specify
349 % a local path relative to the master document. Depending on the
350 % compatibility level, we use the original file, or the newly generated
351 % version.
352 % \begin{macrocode}
353 \immediate\pdfobj stream attr {/Type /Metadata /Subtype /XML}
354 file{#1.xmpi}
355 % \end{macrocode}
356 % Also add the newly created object to the catalog.
357 % \begin{macrocode}
358 \pdfcatalog{/Metadata \the\pdflastobj\space 0 R}
359 % \end{macrocode}
360 % end the group, which resets the compression to whatever it was before.
361 % \begin{macrocode}
362 \endgroup
363 }
364 % \end{macrocode}
365 % The file does not exist, and we have to generate an error. Declare a
366 % placeholder for the missing file-name, to prevent double execution of
367 % the macro.
368 % \begin{macrocode}
369 {\newcommand{\mcs@xmpincl@filename}{#1.xmp}
370 \PackageError{xmpincl}%
371 {The file \mcs@xmpincl@filename\space was not found}
372 {The file \mcs@xmpincl@filename\space The metadata file
373 wasn't found.\MessageBreak Oops.}
374 }
375 }
376 %</package>
377 % \end{macrocode}
378 %
379 % \section{A sample \texttt{.xmp} file}
380 % Note that this is the license of this package,
381 % \href{http://creativecommons.org/licenses/GPL/2.0/}{CC-GNU GPL}.
382 %
383 % \begin{macrocode}
384 %<*license>
385 <x:xmpmeta xmlns:x='adobe:ns:meta/'>
386 <rdf:RDF xmlns="http://web.resource.org/cc/"
387 xmlns:dc="http://purl.org/dc/elements/1.1/"
388 xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
389 <Work rdf:about="">
390 <dc:title>xmpincl</dc:title>
391 <dc:date>2005</dc:date>
392 <dc:description>
393 A LaTeX package to include XMP metadata in
394 files generated through pdfLaTeX
395 </dc:description>
396 <dc:creator>
397 <Agent><dc:title>Maarten Sneep</dc:title></Agent>
398 </dc:creator>
399 <dc:rights>
400 <Agent><dc:title>Maarten Sneep</dc:title></Agent>
401 </dc:rights>
402 <dc:source
403 rdf:resource="ftp://ftp.tex.ac.uk/tex&#45;archive/macros/latex/contrib/xmpincl.tar.gz"/>
404 <license rdf:resource="http://creativecommons.org/licenses/GPL/2.0/" />
405 </Work>
406 <License rdf:about="http://creativecommons.org/licenses/GPL/2.0/">
407 <permits rdf:resource="http://web.resource.org/cc/Reproduction" />
408 <permits rdf:resource="http://web.resource.org/cc/Distribution" />
409 <requires rdf:resource="http://web.resource.org/cc/Notice" />
410 <permits rdf:resource="http://web.resource.org/cc/DerivativeWorks" />
411 <requires rdf:resource="http://web.resource.org/cc/ShareAlike" />
412 <requires rdf:resource="http://web.resource.org/cc/SourceCode" />
413 </License>
414 </rdf:RDF>
415 </x:xmpmeta>
416 %</license>
417 % \end{macrocode}
418 % \Finale
419 \endinput