From 2036a05c122c8dd027354cd0cb0679f45db48f4b Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Tue, 18 Dec 2012 23:28:49 +0000
Subject: hyperxmp (18dec12)

git-svn-id: svn://tug.org/texlive/trunk@28568 c570f23f-e606-0410-a88d-b1316a301751
---
 .../texmf-dist/source/latex/hyperxmp/hyperxmp.dtx  | 673 ++++++++++++++++-----
 1 file changed, 528 insertions(+), 145 deletions(-)

(limited to 'Master/texmf-dist/source/latex/hyperxmp/hyperxmp.dtx')

diff --git a/Master/texmf-dist/source/latex/hyperxmp/hyperxmp.dtx b/Master/texmf-dist/source/latex/hyperxmp/hyperxmp.dtx
index 6858ba47772..2189d6ab8a3 100644
--- a/Master/texmf-dist/source/latex/hyperxmp/hyperxmp.dtx
+++ b/Master/texmf-dist/source/latex/hyperxmp/hyperxmp.dtx
@@ -22,7 +22,7 @@
 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
 %<package>\ProvidesPackage{hyperxmp}
 %<*package>
-    [2012/09/16 v2.1 Store hyperref metadata in XMP format]
+    [2012/12/13 v2.2 Store hyperref metadata in XMP format]
 %</package>
 %
 %<*driver>
@@ -35,13 +35,17 @@
 \usepackage{color}
 \usepackage{tocbibind}
 \usepackage{microtype}
+\usepackage{needspace}
+\usepackage{varioref}
+\usepackage{alltt}
 \usepackage{hyperxmp}
-\usepackage[bookmarksopen,bookmarksopenlevel=2,pdflang=en]{hyperref}
+\usepackage[bookmarksopen,bookmarksopenlevel=2,bookmarksnumbered]{hyperref}
 \EnableCrossrefs
 \CodelineIndex
 \RecordChanges
 \begin{document}
   \DocInput{hyperxmp.dtx}
+  \Needspace{10\baselineskip}
   \phantomsection\addcontentsline{toc}{section}{Change History}
   \PrintChanges
   \makeatletter
@@ -56,7 +60,7 @@
 %</driver>
 % \fi
 %
-% \CheckSum{1210}
+% \CheckSum{1370}
 %
 % \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
@@ -81,6 +85,10 @@
 %   (\string\XeTeX\ and \string\LuaTeX)}
 % \changes{v2.0}{2012/08/26}{Added support for the \protect\acro{XMP} Basic
 %   schema and miscellaneous other bits of metadata}
+% \changes{v1.2}{2010/06/04}{Added support for the \protect\XeTeX\ backend
+%   (\texttt{xdvipdfmx})}
+% \changes{v1.2}{2010/06/07}{Added support for the Photoshop schema}
+% \changes{v2.2}{2010/12/06}{Added support for the \protect\acro{IPTC} Photo Metadata schema}
 %
 % \GetFileInfo{hyperxmp.dtx}
 %
@@ -167,7 +175,11 @@
 %   pdfkeywords={LaTeX, embedded metadata, XMP, PDF, copyright, license, comments},
 %   pdfcopyright={Copyright (C) 2012, Scott Pakin},
 %   pdflicenseurl={http://www.latex-project.org/lppl/},
-%   pdfcaptionwriter={Scott Pakin}
+%   pdfcaptionwriter={Scott Pakin},
+%   pdfcontactemail={scott+hyxmp@pakin.org},
+%   pdfcontacturl={http://www.pakin.org/~scott/},
+%   pdflang={en-US},
+%   baseurl={http://www.ctan.org/tex-archive/macros/latex/contrib/hyperxmp/hyperxmp.pdf}
 % }
 %
 % \maketitle
@@ -255,6 +267,14 @@
 %   \item primary author's position/title (\xmpterm{photoshop:AuthorsPosition})
 %   \item summary (\xmpterm{dc:description})
 %   \item title (\xmpterm{dc:title})
+%   \item contact address (\xmpterm{Iptc4xmpCore:CiAdrExtadr},
+%     \xmpterm{Iptc4xmpCore:CiAdrCity},
+%     \xmpterm{Iptc4xmpCore:CiAdrRegion},
+%     \xmpterm{Iptc4xmpCore:CiAdrPcode}, and
+%     \xmpterm{Iptc4xmpCore:CiAdrCtry})
+%   \item contact telephone number(s) (\xmpterm{Iptc4xmpCore:CiTelWork})
+%   \item contact email address(es) (\xmpterm{Iptc4xmpCore:CiEmailWork})
+%   \item contact \acro{URL}(s) (\xmpterm{Iptc4xmpCore:CiUrlWork})
 % \end{itemize}
 %
 % \noindent
@@ -308,29 +328,50 @@
 % \begin{itemize}
 %   \item \optname{pdfauthortitle}
 %   \item \optname{pdfcaptionwriter}
+%   \item \optname{pdfcontactaddress}
+%   \item \optname{pdfcontactcity}
+%   \item \optname{pdfcontactcountry}
+%   \item \optname{pdfcontactemail}
+%   \item \optname{pdfcontactphone}
+%   \item \optname{pdfcontactpostcode}
+%   \item \optname{pdfcontactregion}
+%   \item \optname{pdfcontacturl}
 %   \item \optname{pdfcopyright}
 %   \item \optname{pdflicenseurl}
 %   \item \optname{pdfmetalang}
 % \end{itemize}
 %
-% \noindent
 % \optname{pdfauthortitle} indicates the primary author's position or
 % title.  \optname{pdfcaptionwriter} specifies the name of the person
-% who added the metadata to the document.  \optname{pdfcopyright}
-% defines the copyright text.  \optname{pdflicenseurl} identifies a
-% \acro{URL} that points to the document's license agreement.
-% \optname{pdfmetalang} indicates the natural language in which the
-% metadata is written, typically as an \acro{IETF} language
-% tag~\cite{IANA2011:lang-tags}, for example, ``|en|'' for English,
-% ``|en-US|'' for specifically United States English, ``|de|'' for
-% German, and so forth.  If \optname{pdfmetalang} is not specified,
-% \pkgname{hyperxmp} assumes the metadata language is the same as the
-% document language (\pkgname{hyperref}'s \optname{pdflang} option).  If
-% neither \optname{pdfmetalang} nor \optname{pdflang} is specified,
-% \pkgname{hyperxmp} uses only ``|x-default|'' as the metadata language.
-% Note that ``|x-default|'' metadata is always included in addition to
-% the specified metadata language, as the user reading the document may
-% not have specified a language preference.
+% who added the metadata to the document.  The next eight items describe
+% how to contact the person or institution responsible for the document
+% (the ``contact'').  \optname{pdfcontactaddress} is the contact's
+% street address and can include the institution name if the contact is
+% an institution; \optname{pdfcontactcity} is the contact's city.
+% \optname{pdfcontactcountry} is the contact's country;
+% \optname{pdfcontactemail} is the contact's email address (or multiple,
+% comma-separated email addresses); \optname{pdfcontactphone} is the
+% contact's telephone number (or multiple, comma-separated telephone
+% numbers); \optname{pdfcontactpostcode} is the contact's postal code;
+% \optname{pdfcontactregion} is the contact's state or province; and
+% \optname{pdfcontacturl} is the contact's \acro{URL} (or multiple,
+% comma-separated \acro{URL}s).
+%
+% \optname{pdfcopyright} defines the copyright text.
+% \optname{pdflicenseurl} identifies a \acro{URL} that points to the
+% document's license agreement.  \optname{pdfmetalang} indicates the
+% natural language in which the metadata is written, typically as an
+% \acro{IETF} language tag~\cite{IANA2011:lang-tags}, for example,
+% ``|en|'' for English, ``|en-US|'' for specifically United States
+% English, ``|de|'' for German, and so forth.  If \optname{pdfmetalang}
+% is not specified, \pkgname{hyperxmp} assumes the metadata language is
+% the same as the document language (\pkgname{hyperref}'s
+% \optname{pdflang} option).  If neither \optname{pdfmetalang} nor
+% \optname{pdflang} is specified, \pkgname{hyperxmp} uses only
+% ``|x-default|'' as the metadata language.  Note that ``|x-default|''
+% metadata is always included in addition to the specified metadata
+% language, as the user reading the document may not have specified a
+% language preference.
 %
 % It is usually more convenient to provide values for those options using
 % \pkgname{hyperref}'s |\hypersetup| command than on the |\usepackage|
@@ -340,6 +381,8 @@
 % sample \LaTeX\ document that provides values for most of the metadata
 % options that \pkgname{hyperxmp} recognizes:
 %
+% \Needspace{4\baselineskip}
+% \label{page:begin-sample-doc}
 % \begin{verbatim}
 %     \documentclass{article}
 %     \usepackage{hyperxmp}
@@ -359,6 +402,16 @@
 %       pdfkeywords={energy quanta, Hertz effect, quantum physics},
 %       pdflicenseurl={http://creativecommons.org/licenses/by-nc-nd/3.0/},
 %       pdfcaptionwriter={Scott Pakin},
+%       pdfcontactaddress={Kramgasse 49},
+%       pdfcontactcity={Bern},
+%       pdfcontactpostcode={3011},
+%       pdfcontactcountry={Switzerland},
+%       pdfcontactphone={031 312 00 91},
+%       pdfcontactemail={aeinstein@ipi.ch},
+%       pdfcontacturl={%
+%         http://einstein.biz/,
+%         https://www.facebook.com/AlbertEinstein
+%       },
 %       pdflang={en},
 %       baseurl={http://www.ctan.org/tex-archive/macros/latex/contrib/hyperxmp/}
 %     }
@@ -370,6 +423,7 @@
 %     processes in so-called empty space\dots
 %     \end{document}
 % \end{verbatim}
+% \label{page:end-sample-doc}
 %
 % Compile the document to \acro{PDF} using any of the following
 % approaches:
@@ -396,113 +450,25 @@
 %
 % \bigskip
 %
-% Once the document is compiled, the resulting \acro{PDF} file
-% will contain an \acro{XMP} packet that looks something like this:
-%
-% \begin{verbatim}
-%     <?xpacket begin="\357\273\277" id="W5M0MpCehiHzreSzNTczkc9d"?>
-%     <x:xmpmeta xmlns:x="adobe:ns:meta/" x:xmptk="3.1-702">
-%        <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
-%           <rdf:Description rdf:about=""
-%                xmlns:pdf="http://ns.adobe.com/pdf/1.3/">
-%                <pdf:Keywords>
-%                  energy quanta, Hertz effect, quantum physics
-%                </pdf:Keywords>
-%                <pdf:Producer>pdfTeX-1.40.10</pdf:Producer>
-%           </rdf:Description>
-%           <rdf:Description rdf:about=""
-%                xmlns:xmpRights="http://ns.adobe.com/xap/1.0/rights/">
-%              <xmpRights:Marked>True</xmpRights:Marked>
-%              <xmpRights:WebStatement>
-%                http://creativecommons.org/licenses/by-nc-nd/3.0/
-%              </xmpRights:WebStatement>
-%           </rdf:Description>
-%           <rdf:Description rdf:about=""
-%                 xmlns:dc="http://purl.org/dc/elements/1.1/">
-%              <dc:format>application/pdf</dc:format>
-%              <dc:title>
-%                 <rdf:Alt>
-%                    <rdf:li xml:lang="en">
-%                      On a heuristic viewpoint concerning the production and
-%                      transformation of light
-%                    </rdf:li>
-%                    <rdf:li xml:lang="x-default">
-%                      On a heuristic viewpoint concerning the production and
-%                      transformation of light
-%                    </rdf:li>
-%                 </rdf:Alt>
-%              </dc:title>
-%              <dc:description>
-%                 <rdf:Alt>
-%                    <rdf:li xml:lang="en">photoelectric effect</rdf:li>
-%                    <rdf:li xml:lang="x-default">photoelectric effect</rdf:li>
-%                 </rdf:Alt>
-%              </dc:description>
-%              <dc:rights>
-%                 <rdf:Alt>
-%                    <rdf:li xml:lang="en">
-%                      Copyright (C) 1905, Albert Einstein
-%                    </rdf:li>
-%                    <rdf:li xml:lang="x-default">
-%                      Copyright (C) 1905, Albert Einstein
-%                    </rdf:li>
-%                 </rdf:Alt>
-%              </dc:rights>
-%              <dc:creator>
-%                 <rdf:Seq>
-%                    <rdf:li>Albert Einstein</rdf:li>
-%                 </rdf:Seq>
-%              </dc:creator>
-%              <dc:subject>
-%                 <rdf:Bag>
-%                    <rdf:li>energy quanta</rdf:li>
-%                    <rdf:li>Hertz effect</rdf:li>
-%                    <rdf:li>quantum physics</rdf:li>
-%                 </rdf:Bag>
-%              </dc:subject>
-%              <dc:date>
-%                 <rdf:Seq>
-%                    <rdf:li>2012-08-26</rdf:li>
-%                 </rdf:Seq>
-%              </dc:date>
-%              <dc:language>en</dc:language>
-%              <dc:source>einstein.tex</dc:source>
-%           </rdf:Description>
-%           <rdf:Description rdf:about=""
-%                 xmlns:photoshop="http://ns.adobe.com/photoshop/1.0/">
-%              <photoshop:AuthorsPosition>
-%                Technical Assistant, Level III
-%              </photoshop:AuthorsPosition>
-%              <photoshop:CaptionWriter>Scott Pakin</photoshop:CaptionWriter>
-%           </rdf:Description>
-%           <rdf:Description rdf:about=""
-%                 xmlns:xmp="http://ns.adobe.com/xap/1.0/">
-%              <xmp:CreateDate>2012-08-26</xmp:CreateDate>
-%              <xmp:ModifyDate>2012-08-26</xmp:ModifyDate>
-%              <xmp:MetadataDate>2012-08-26</xmp:MetadataDate>
-%              <xmp:CreatorTool>LaTeX with hyperref package</xmp:CreatorTool>
-%              <xmp:BaseURL>
-%                http://www.ctan.org/tex-archive/macros/latex/contrib/hyperxmp/
-%              </xmp:BaseURL>
-%           </rdf:Description>
-%           <rdf:Description rdf:about=""
-%                 xmlns:xmpMM="http://ns.adobe.com/xap/1.0/mm/">
-%              <xmpMM:DocumentID>uuid:0595fdce-41dc-e4c4-6c418dc4ce46</xmpMM:DocumentID>
-%              <xmpMM:InstanceID>uuid:efd754c4-1d7f-200a-ef754ce413ea</xmpMM:InstanceID>
-%           </rdf:Description>
-%        </rdf:RDF>
-%     </x:xmpmeta>
-%     <?xpacket end="w"?>
-% \end{verbatim}
-%
-% \noindent
-% Figure~\ref{fig:xmp-metadata} is a screenshot of the preceding packet
-% as it appears in Adobe Acrobat's ``Advanced'' metadata dialog box.
+% Once the document is compiled, the resulting \acro{PDF} file will
+% contain an \acro{XMP} packet that looks something like that shown in
+% Appendix~\ref{sec:sample-packet}.  Figure~\ref{fig:xmp-metadata-1} is
+% a screenshot of the \acro{XMP} metadata as it appears in Adobe
+% Acrobat's ``Advanced'' metadata dialog box.  Further clicking on the
+% ``Advanced'' item within that dialog box displays all of the
+% document's metadata sorted by schema as shown in
+% Figure~\ref{fig:xmp-metadata-2}.
 %
 % \begin{figure}[htbp]
-%   \includegraphics[width=\linewidth]{einstein}
+%   \includegraphics[width=\linewidth]{einstein1}
 %   \caption{\acro{XMP} metadata as it appears in Adobe Acrobat}
-%   \label{fig:xmp-metadata}
+%   \label{fig:xmp-metadata-1}
+% \end{figure}
+%
+% \begin{figure}[htbp]
+%   \includegraphics[width=\linewidth]{einstein2}
+%   \caption{Additional \acro{XMP} metadata as it appears in Adobe Acrobat}
+%   \label{fig:xmp-metadata-2}
 % \end{figure}
 %
 % \paragraph{Note~1: Acrobat \pdfterm{Author} bug}
@@ -537,7 +503,27 @@
 % \acro{PDF} readers likely displaying only the first author.
 %
 %
-% \paragraph{Note~2: \XeLaTeX\ object compression}
+% \paragraph{Note~2: Acrobat multiline-field bug}
+% The \acro{IPTC} Photo Metadata schema states that ``the [contact]
+% address is a multiline field''~\cite{IPTC2010:photo-meta}.
+% \pkgname{hyperxmp} converts commas in \optname{pdfcontactaddress}'s
+% argument to line breaks in the generated \acro{XML}\@.  Unfortunately,
+% A bug in Adobe Acrobat---at least in versions~10.0.1 and
+% earlier---causes that \acro{PDF} reader to discard line breaks in the
+% contact address.  Interestingly, Adobe Illustrator CS5 correctly
+% displays the contact address.
+% \DescribeMacro{\xmplinesep}
+% If your find Adobe Acrobat's behavior bothersome, you can redefine the
+% |\xmplinesep| macro as a string to use as an address-line separator.
+% For example, the following replaces all commas appearing in
+% \optname{pdfcontactaddress}'s argument with semicolons:
+%
+% \begin{verbatim}
+%     \renewcommand*{\xmlinesep}{;}
+% \end{verbatim}
+%
+%
+% \paragraph{Note~3: \XeLaTeX\ object compression}
 % \XeLaTeX\ (or, more precisely, the \cmdname{xdvipdfmx} back end),
 % compresses \emph{all} \acro{PDF} objects, including the ones
 % containing \acro{XMP} metadata.  While Adobe Acrobat can still detect
@@ -551,7 +537,7 @@
 % Adobe Acrobat and re-saving it with the Save As\dots\ menu option.
 %
 %
-% \paragraph{Note~3: Literal commas}
+% \paragraph{Note~4: Literal commas}
 % \pkgname{hyperxmp} splits the \optname{pdfauthor} and
 % \optname{pdfkeywords} lists at commas.  Therefore, when specifying
 % \optname{pdfauthor} and \optname{pdfkeywords}, you should separate
@@ -570,16 +556,41 @@
 %
 % \noindent
 % \DescribeMacro{\xmpcomma}
-% If you need to include a comma within an author or keyword list, use
-% the |\xmpcomma| macro to represent it, and wrap the entire entry
-% containing the comma within |\xmpquote{|\dots|}| as shown below:
+% \DescribeMacro{\xmpquote}
+% If you need to include a literal comma within an author or keyword
+% list (where commas normally separate list items) or a street address
+% (where commas normally separate lines), use the |\xmpcomma| macro to
+% represent it, and wrap the entire entry containing the comma within
+% |\xmpquote{|\dots|}| as shown below:
 %
 % \begin{verbatim}
 %     pdfauthor={\xmpquote{Jack Napier\xmpcomma\ Jr.},
 %                \xmpquote{Edward Nigma\xmpcomma\ PhD},
 %                \xmpquote{Harvey Dent\xmpcomma\ Esq.}}
+%
+%     pdfcontactaddress={Office of the President,
+%                        \xmpquote{Wayne Enterprises\xmpcomma\ Inc.},
+%                        One Wayne Blvd}
+% \end{verbatim}
+%
+% As of version~2.2 of \pkgname{hyperxmp}, it is acceptable to use
+% |\xmpcomma| and |\xmpquote| within any \pkgname{hyperxmp} option, not
+% just in those in which a comma normally serves as a separator
+% (i.e.,~lists and multiline fields).  Outside of those cases,
+% |\xmpcomma| is treated as an ordinary comma, and |\xmpquote| returns
+% its argument unmodified.  Hence, it is legitimate to use |\xmpcomma|
+% and |\xmpquote| in cases like the following
+%
+% \begin{verbatim}
+%     pdfauthortitle={\xmpquote{Psychiatrist\xmpcomma\ Arkham Asylum}}
 % \end{verbatim}
 %
+% \noindent
+% (Like most \pkgname{hyperxmp} options, \optname{pdfauthortitle}
+% inserts its argument unmodified in an \acro{XMP} tag.)  When in
+% doubt, use |\xmpcomma| and |\xmpquote|; it should always be safe
+% to do so.
+%
 %
 % \StopEventually{^^A
 % \section{Future Work}
@@ -594,6 +605,21 @@
 % \tex\ engines (\pdfTeX, \LuaTeX, \XeTeX, etc.), please send me a code
 % patch.
 %
+% \appendix
+%
+% \section{Sample XMP packet}
+% \label{sec:sample-packet}
+%
+% The following is an example of a complete \acro{XMP} packet as may be
+% produced by \pkgname{hyperxmp}.  This packet corresponds to the
+% metadata included in the sample \LaTeX\ document presented
+% \vpagerefrange{page:begin-sample-doc}{page:end-sample-doc}.  For
+% clarity, metadata values, either specified explicitly by the document
+% or introduced automatically by \pkgname{hyperxmp}, are colored blue.
+%
+% \input{einstein-xmp}
+%
+%
 % \begin{thebibliography}{1}
 % \bibitem{Adobe2010:pdfmark}
 % Adobe Systems, Inc., San Jose, California.
@@ -628,11 +654,24 @@
 % \newblock Archived by Google at
 %   \url{http://groups.google.com/group/comp.text.tex/msg/7da7643b9e8f3b48}.
 %
+% \bibitem{IPTC2010:photo-meta}
+% International Press Telecommunications Council.
+% \newblock {\em {IPTC} Photo Metadata: Core 1.1/Extension 1.1}, July 2010.
+% \newblock Revision~1. Available from
+%   \url{http://www.iptc.org/std/photometadata/specification/IPTC-PhotoMetadata-201007_1.pdf}.
+%
 % \bibitem{IANA2011:lang-tags}
 % {Internet Assigned Numbers Authority}.
 % \newblock Language subtag registry, January~11, 2011.
 % \newblock Available from
 %   \url{http://www.iana.org/assignments/language-subtag-registry}.
+%
+% \bibitem{PDFA2008:ext-schemas}
+% PDF/A Competence Center, Berlin, Germany.
+% \newblock {\em TechNote~0009: {XMP} Extension Schemas in {PDF/A-1}}, March~20,
+%   2008.
+% \newblock Available from
+%   \url{http://www.pdfa.org/wp-content/uploads/2011/08/tn0009_xmp_extension_schemas_in_pdfa-1_2008-03-20.pdf}.
 % \end{thebibliography}
 % }
 %
@@ -664,8 +703,8 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \changes{v1.5}{2012/03/10}{Made the XMP inclusion more robust.  Thanks to
-%   Heiko Oberdiek for the bug report and suggested modifications.}
+% \changes{v1.5}{2012/03/10}{Made the \acro{XMP} inclusion more robust.
+%   Thanks to Heiko Oberdiek for the bug report and suggested modifications.}
 %
 % \begin{macro}{\hyxmp@at@end}
 % \begin{macro}{\hyxmp@driver}
@@ -761,6 +800,102 @@
 %    \end{macrocode}
 % \end{macro}
 %
+% The following eight macros---|\@pdfcontactaddress|,
+% |\@pdfcontactcity|, |\@pdfcontactregion|, |\@pdfcontactpostcode|,
+% |\@pdfcontactcountry|, |\@pdfcontactphone|, |\@pdfcontactemail|, and
+% |\@pdfcontacturl|---together specify how to contact the person or
+% institution responsible for the document.
+%
+% \begin{macro}{\@pdfcontactaddress}
+% Prepare to store a street address for the document's contact
+% person\slash institution.  The \acro{IPTC} standard defines this as
+% follows:
+%
+% \begin{quote}
+%   The contact information address part. Comprises an optional company
+%   name and all required information to locate the building or postbox
+%   to which mail should be sent. To that end, the address is a
+%   multiline field.
+% \end{quote}
+%
+% For consistency with the rest of \pkgname{hyperxmp}, we use commas to
+% separate terms, in this case, lines of the address.  The author can
+% use |\xmpquote| and |\xmpcomma| to include literal commas.
+%    \begin{macrocode}
+\def\@pdfcontactaddress{}
+\define@key{Hyp}{pdfcontactaddress}{%
+  \let\xmpcomma=\hyxmp@comma
+  \def\xmpquote##1{##1}%
+  \pdfstringdef\@pdfcontactaddress{#1}%
+  \def\xmpcomma{,}%
+  \let\xmpquote=\relax
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@pdfcontactcity}
+% Prepare to store the city of the document's contact person\slash
+% institution.
+%    \begin{macrocode}
+\def\@pdfcontactcity{}
+\define@key{Hyp}{pdfcontactcity}{\pdfstringdef\@pdfcontactcity{#1}}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@pdfcontactregion}
+% Prepare to store the state or province of the document's contact
+% person\slash institution.
+%    \begin{macrocode}
+\def\@pdfcontactregion{}
+\define@key{Hyp}{pdfcontactregion}{\pdfstringdef\@pdfcontactregion{#1}}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@pdfcontactpostcode}
+% Prepare to store the postal code of the document's contact
+% person\slash institution.
+%    \begin{macrocode}
+\def\@pdfcontactpostcode{}
+\define@key{Hyp}{pdfcontactpostcode}{\pdfstringdef\@pdfcontactpostcode{#1}}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@pdfcontactcountry}
+% Prepare to store the country of the document's contact person\slash
+% institution.
+%    \begin{macrocode}
+\def\@pdfcontactcountry{}
+\define@key{Hyp}{pdfcontactcountry}{\pdfstringdef\@pdfcontactcountry{#1}}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@pdfcontactphone}
+% Prepare to store the telephone number of the document's contact
+% person\slash institution.
+%    \begin{macrocode}
+\def\@pdfcontactphone{}
+\define@key{Hyp}{pdfcontactphone}{\pdfstringdef\@pdfcontactphone{#1}}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@pdfcontactemail}
+% Prepare to store the email address of the document's contact
+% person\slash institution.
+%    \begin{macrocode}
+\def\@pdfcontactemail{}
+\define@key{Hyp}{pdfcontactemail}{\pdfstringdef\@pdfcontactemail{#1}}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@pdfcontacturl}
+% Prepare to store the \acro{URL} of the document's contact person\slash
+% institution.
+%    \begin{macrocode}
+\def\@pdfcontacturl{}
+\define@key{Hyp}{pdfcontacturl}{\pdfstringdef\@pdfcontacturl{#1}}
+%    \end{macrocode}
+% \end{macro}
+%
 % \changes{v2.1}{2012/09/16}{Enabled \pkgname{hyperxmp} and
 %   \pkgname{hyperref} to be loaded in either order.  This addresses a
 %   bug report by Yury Donskoy}
@@ -784,6 +919,17 @@
 % same thing.  This is required in case \pkgname{hyperref} is loaded
 % before \pkgname{hyperxmp}.
 %
+
+% \begin{macro}{\hyxmp@pdfauthor}
+% \begin{macro}{\hyxmp@pdfkeywords}
+% Prepare to store the name of the author and a list of keywords.
+%    \begin{macrocode}
+\def\hyxmp@pdfauthor{}
+\def\hyxmp@pdfkeywords{}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
 % \begin{macro}{\hyxmp@redefine@Hyp}
 % If not already redefined, redefine \pkgname{hyperref}'s
 % \optname{pdfauthor} and \optname{pdfkeywords} options to properly
@@ -829,7 +975,7 @@
     \def\xmpcomma{,}%
     \def\xmpquote####1{"####1"}%
     \hyxmp@Hyp@pdfauthor{##1}%
-    \let\xmpcomma=\relax
+    \def\xmpcomma{,}%
     \let\xmpquote=\relax
   }%
 %    \end{macrocode}
@@ -868,7 +1014,7 @@
     \def\xmpcomma{,}%
     \def\xmpquote####1{"####1"}%
     \hyxmp@Hyp@pdfkeywords{##1}%
-    \let\xmpcomma=\relax
+    \def\xmpcomma{,}%
     \let\xmpquote=\relax
   }%
 }
@@ -932,6 +1078,14 @@
     \@pdfauthor
     \@pdfauthortitle
     \@pdfcaptionwriter
+    \@pdfcontactaddress
+    \@pdfcontactcity
+    \@pdfcontactcountry
+    \@pdfcontactemail
+    \@pdfcontactphone
+    \@pdfcontactpostcode
+    \@pdfcontactregion
+    \@pdfcontacturl
     \@pdfcopyright
     \@pdfkeywords
     \@pdflang
@@ -1056,11 +1210,14 @@ disabled}%
 % Because \pkgname{hyperxmp} splits lists at commas, a comma cannot
 % normally be used within a list.  We there provide an |\xmpcomma| macro
 % that can expand to either a true comma or a placeholder character
-% depending on the situation.  Here, we bind it to |\relax| to prevent
-% it from expanding to either prematurely.
+% depending on the situation.  Here, we bind it to a comma so it can be
+% used in \emph{any} \pkgname{hyperxmp} option, not just those that treat
+% commas specially.
 % \changes{v2.0}{2012/08/25}{Added this macro}
+% \changes{v2.2}{2012/12/07}{Changed the default from
+%   \texttt{\string\string\string\relax} to an ordinary comma}
 %    \begin{macrocode}
-\let\xmpcomma=\relax
+\def\xmpcomma{,}%
 %    \end{macrocode}
 % \end{macro}
 %
@@ -1788,8 +1945,11 @@ disabled}%
 % blocks of \acro{XML} for various \acro{XMP} schemata: Adobe \acro{PDF}
 % (Section~\ref{sec:adobe-pdf}), Dublin Core
 % (Section~\ref{sec:dublin-core}), \acro{XMP} Rights Management
-% (Section~\ref{sec:xmp-rights}), and \acro{XMP} Media Management
-% (Section~\ref{sec:xmp-media}).  The |\hyxmp@construct@packet| macro
+% (Section~\ref{sec:xmp-rights}), \acro{XMP} Media Management
+% (Section~\ref{sec:xmp-media}), \acro{XMP} Basic
+% (Section~\ref{sec:xmp-basic}), Photoshop
+% (Section~\ref{sec:photoshop}), and \acro{IPTC} Photo Metadata
+% (Section~\ref{sec:photo-meta}).  The |\hyxmp@construct@packet| macro
 % constructs the \acro{XMP} packet into |\hyxmp@xml|.  It first writes
 % the appropriate \acro{XML} header, then calls the various
 % schema-writing macros, then injects |\hyxmp@padding| as padding, and
@@ -2062,7 +2222,7 @@ ______</rdf:Description>^^J%
 % \label{sec:xmp-rights}
 %
 % \begin{macro}{\hyxmp@xmpRights@schema}
-% Add properties defined by the XMP Rights Management schema to the
+% Add properties defined by the \acro{XMP} Rights Management schema to the
 % |\hyxmp@xml| macro.  Currently, these are only the
 % \xmpterm{xmpRights:Marked} property and the
 % \xmpterm{xmpRights:WebStatement} property.  If the author specified a
@@ -2135,7 +2295,7 @@ ______</rdf:Description>^^J%
 % \label{sec:xmp-media}
 %
 % \begin{macro}{\hyxmp@mm@schema}
-% Add properties defined by the XMP Media Management schema to the
+% Add properties defined by the \acro{XMP} Media Management schema to the
 % |\hyxmp@xml| macro.  According to the \acro{XMP} specification, the
 % \xmpterm{xmpMM:DocumentID} property is supposed to uniquely identify a
 % document, and the \xmpterm{xmpMM:InstanceID} property is supposed to
@@ -2192,14 +2352,13 @@ ______</rdf:Description>^^J%
 % \label{sec:photoshop}
 %
 % \begin{macro}{\hyxmp@photoshop@schema}
+% \changes{v2.0}{2012/08/26}{Simplified using
+%   \texttt{\string\string\string\hyxmp@add@simple}}
 % \begin{macro}{\hyxmp@photoshop@data}
 % Add properties defined by the Photoshop schema to the |\hyxmp@xml|
 % macro.  We currently support only the
 % \xmpterm{photoshop:AuthorsPosition} and
 % \xmpterm{photoshop:CaptionWriter} properties.
-% \changes{v1.2}{2010/06/07}{Added support for the Photoshop schema}
-% \changes{v2.0}{2012/08/26}{Simplified using
-%   \texttt{\string\string\string\hyxmp@add@simple}}
 %    \begin{macrocode}
 \gdef\hyxmp@photoshop@schema{%
   \edef\hyxmp@photoshop@data{\@pdfauthortitle\@pdfcaptionwriter}%
@@ -2224,6 +2383,231 @@ ______</rdf:Description>^^J%
 % \end{macro}
 %
 %
+% \subsubsection{The IPTC Photo Metadata schema}
+% \label{sec:photo-meta}
+%
+% \begin{macro}{\xmplinesep}
+% Lines in multiline fields are separated by |\xmplinesep| in the
+% generated \acro{XML}.  This defaults to an \acro{LF} (|^^J|) character
+% but written as an \acro{XML} character entity for consistency across
+% operating systems.
+% \changes{v2.2}{2012/12/07}{Added this macro}
+%    \begin{macrocode}
+\begingroup
+  \catcode`\&=12
+  \catcode`\#=12
+  \gdef\xmplinesep{&#xA;}
+\endgroup
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\hyxmp@list@to@lines}
+% Given a property~(|#1|) and a macro containing a comma-separated
+% list~(|#2|), replace commas with |\xmplinesep|.  Do nothing it the
+% list is empty.
+% \changes{v2.2}{2012/12/07}{Added this macro}
+%    \begin{macrocode}
+\newcommand*{\hyxmp@list@to@lines}[2]{%
+  \ifx#2\@empty
+  \else
+    \bgroup
+      \hyxmp@add@to@xml{%
+_________<#1>%
+      }%
+%    \end{macrocode}
+% \begin{macro}{\@elt@first}
+% The first element of the list is output as is.
+%    \begin{macrocode}
+      \def\@elt@first##1{%
+        \hyxmp@add@to@xml{##1}%
+        \let\@elt=\@elt@rest
+      }%
+%    \end{macrocode}
+% \begin{macro}{\@elt@rest}
+% The remaining elements of the list are output with a preceding line
+% separator (|\xmplinesep|).
+%    \begin{macrocode}
+      \def\@elt@rest##1{%
+        \hyxmp@add@to@xml{\xmplinesep##1}%
+      }%
+%    \end{macrocode}
+% \begin{macro}{\@elt}
+% Re-encode the text from \term{Unicode} if necessary.  Then redefine
+% |\@elt| to insert a line separator between terms.
+%    \begin{macrocode}
+      \let\@elt=\@elt@first
+      \hyxmp@xmlify{#2}%
+      \hyxmp@commas@to@list\hyxmp@list{\hyxmp@xmlified}%
+      \hyxmp@list
+      \hyxmp@add@to@xml{</#1>^^J}%
+    \egroup
+  \fi
+}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\hyxmp@photometa@schema}
+% \changes{v2.2}{2012/12/07}{Added this macro}
+% \begin{macro}{\hyxmp@photometa@data}
+% Add properties defined by the \acro{IPTC} Photo Metadata
+% schema~\cite{IPTC2010:photo-meta} to the |\hyxmp@xml| macro.  We
+% currently support only the contact-information details structure,
+% viz.\ the \xmpterm{Iptc4xmpCore:CiAdrExtadr},
+% \xmpterm{Iptc4xmpCore:CiAdrCity}, \xmpterm{Iptc4xmpCore:CiAdrRegion},
+% \xmpterm{Iptc4xmpCore:CiAdrPcode}, \xmpterm{Iptc4xmpCore:CiAdrCtry},
+% \xmpterm{Iptc4xmpCore:CiTelWork}, \xmpterm{Iptc4xmpCore:CiEmailWork},
+% and \xmpterm{Iptc4xmpCore:CiUrlWork} properties.
+%    \begin{macrocode}
+\gdef\hyxmp@photometa@schema{%
+  \edef\hyxmp@photometa@data{%
+    \@pdfcontactaddress
+    \@pdfcontactcity
+    \@pdfcontactregion
+    \@pdfcontactpostcode
+    \@pdfcontactcountry
+    \@pdfcontactphone
+    \@pdfcontactemail
+    \@pdfcontacturl
+  }%
+  \ifx\hyxmp@photometa@data\@empty
+  \else
+    \hyxmp@iptc@extensions
+    \hyxmp@add@to@xml{%
+______<rdf:Description rdf:about=""^^J%
+___________xmlns:Iptc4xmpCore="http://iptc.org/std/Iptc4xmpCore/1.0/xmlns/">^^J%
+_______<Iptc4xmpCore:CreatorContactInfo rdf:parseType="Resource">^^J%
+    }%
+  \fi
+  \hyxmp@list@to@lines{Iptc4xmpCore:CiAdrExtadr}{\@pdfcontactaddress}%
+  \hyxmp@add@simple{Iptc4xmpCore:CiAdrCity}{\@pdfcontactcity}%
+  \hyxmp@add@simple{Iptc4xmpCore:CiAdrRegion}{\@pdfcontactregion}%
+  \hyxmp@add@simple{Iptc4xmpCore:CiAdrPcode}{\@pdfcontactpostcode}%
+  \hyxmp@add@simple{Iptc4xmpCore:CiAdrCtry}{\@pdfcontactcountry}%
+%    \end{macrocode}
+% \begin{macro}{\xmplinesep}
+% The \acro{IPTC} standard states that sets of telephone numbers, email
+% address, and \acro{URL}s for the contact person or institution,
+% ``[m]ay have to be separated by a comma in the user
+% interface''~\cite{IPTC2010:photo-meta}.  This is rather ambiguous:
+% Does the comma appear \emph{only} in the user interface or also in the
+% generated \acro{XML}\@?  Here we assume the latter interpretation and
+% temporarily redefine |\xmplinesep| as a comma and use
+% |\hyxmp@list@to@lines| to insert the data.  Unlike
+% |\hyxmp@add@simple|, this approach trims all spaces surrounding commas.
+%    \begin{macrocode}
+  \bgroup
+    \def\xmplinesep{,}%
+    \hyxmp@list@to@lines{Iptc4xmpCore:CiTelWork}{\@pdfcontactphone}%
+    \hyxmp@list@to@lines{Iptc4xmpCore:CiEmailWork}{\@pdfcontactemail}%
+    \hyxmp@list@to@lines{Iptc4xmpCore:CiUrlWork}{\@pdfcontacturl}%
+  \egroup
+  \ifx\hyxmp@photometa@data\@empty
+  \else
+    \hyxmp@add@to@xml{%
+_______</Iptc4xmpCore:CreatorContactInfo>^^J%
+______</rdf:Description>^^J%
+    }%
+  \fi
+}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\hyxmp@iptc@extensions}
+% \changes{v2.2}{2012/12/13}{Added this macro to support
+%   \acro{PDF/A} generation}
+% Because \acro{IPTC} metadata are not recognized by the \acro{PDF/A}
+% standard, \acro{PDF/A} conversion would normally fail for documents
+% that utilize |\pdfcontactaddress|, |\pdfcontactcity|, etc.  However,
+% there exists a technique, described in a PDF Association technical
+% note~\cite{PDFA2008:ext-schemas}, for describing nonstandard
+% \acro{XMP} metadata within the \acro{XMP} packet itself.  We use that
+% technique here to describe all of the metadata that
+% |\hyxmp@photometa@schema| can produce.  Doing so enables the document
+% to be converted to \acro{PDF/A} format.
+%    \begin{macrocode}
+\newcommand*{\hyxmp@iptc@extensions}{%
+  \hyxmp@add@to@xml{%
+______<rdf:Description rdf:about=""^^J%
+__________xmlns:pdfaExtension="http://www.aiim.org/pdfa/ns/extension/"^^J%
+__________xmlns:pdfaSchema="http://www.aiim.org/pdfa/ns/schema\hyxmp@hash"^^J%
+__________xmlns:pdfaProperty="http://www.aiim.org/pdfa/ns/property\hyxmp@hash"^^J%
+__________xmlns:pdfaType="http://www.aiim.org/pdfa/ns/type\hyxmp@hash"^^J%
+__________xmlns:pdfaField="http://www.aiim.org/pdfa/ns/field\hyxmp@hash">^^J%
+________<pdfaExtension:schemas>^^J%
+__________<rdf:Bag>^^J%
+____________<rdf:li rdf:parseType="Resource">^^J%
+______________<pdfaSchema:schema>IPTC Core Schema</pdfaSchema:schema>^^J%
+______________<pdfaSchema:namespaceURI>http://iptc.org/std/Iptc4xmpCore/1.0/xmlns/</pdfaSchema:namespaceURI>^^J%
+______________<pdfaSchema:prefix>Iptc4xmpCore</pdfaSchema:prefix>^^J%
+______________<pdfaSchema:property>^^J%
+________________<rdf:Seq>^^J%
+__________________<rdf:li rdf:parseType="Resource">^^J%
+____________________<pdfaProperty:name>CreatorContactInfo</pdfaProperty:name>^^J%
+____________________<pdfaProperty:valueType>contactinfo</pdfaProperty:valueType>^^J%
+____________________<pdfaProperty:category>external</pdfaProperty:category>^^J%
+____________________<pdfaProperty:description>contact information for the document's creator</pdfaProperty:description>^^J%
+__________________</rdf:li>^^J%
+________________</rdf:Seq>^^J%
+______________</pdfaSchema:property>^^J%
+______________<pdfaSchema:valueType>^^J%
+________________<rdf:Seq>^^J%
+__________________<rdf:li rdf:parseType="Resource">^^J%
+____________________<pdfaType:type>contactinfo</pdfaType:type>^^J%
+____________________<pdfaType:namespaceURI>http://iptc.org/std/Iptc4xmpCore/1.0/xmlns/contactinfo/</pdfaType:namespaceURI>^^J%
+____________________<pdfaType:prefix>Iptc4xmpCore</pdfaType:prefix>^^J%
+____________________<pdfaType:description>contact information</pdfaType:description>^^J%
+____________________<pdfaType:field>^^J%
+______________________<rdf:Seq>^^J%
+  }%
+%    \end{macrocode}
+%    \begin{macrocode}
+  \hyxmp@text@resource{CiAdrExtadr}{contact address}%
+  \hyxmp@text@resource{CiAdrCity}{contact city}%
+  \hyxmp@text@resource{CiAdrRegion}{contact region}%
+  \hyxmp@text@resource{CiAdrPcode}{contact postal code}%
+  \hyxmp@text@resource{CiAdrCtry}{contact country}%
+  \hyxmp@text@resource{CiTelWork}{contact telephone number}%
+  \hyxmp@text@resource{CiEmailWork}{contact email address}%
+  \hyxmp@text@resource{CiUrlWork}{contact url}%
+%    \end{macrocode}
+%    \begin{macrocode}
+  \hyxmp@add@to@xml{%
+______________________</rdf:Seq>^^J%
+____________________</pdfaType:field>^^J%
+__________________</rdf:li>^^J%
+________________</rdf:Seq>^^J%
+______________</pdfaSchema:valueType>^^J%
+____________</rdf:li>^^J%
+__________</rdf:Bag>^^J%
+________</pdfaExtension:schemas>^^J%
+______</rdf:Description>^^J%
+  }%
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\hyxmp@text@resource}
+% \changes{v2.2}{2012/12/13}{Added this macro}
+% Output a single \xmpterm{Text} resource given its name and description.
+%    \begin{macrocode}
+\newcommand*{\hyxmp@text@resource}[2]{%
+  \hyxmp@add@to@xml{%
+________________________<rdf:li rdf:parseType="Resource">^^J%
+__________________________<pdfaField:name>#1</pdfaField:name>^^J%
+__________________________<pdfaField:valueType>Text</pdfaField:valueType>^^J%
+__________________________<pdfaField:description>#2</pdfaField:description>^^J%
+________________________</rdf:li>^^J%
+  }
+}
+%    \end{macrocode}
+% \end{macro}
+%
+%
 % \subsubsection{Constructing the XMP packet}
 %
 % \begin{macro}{\hyxmp@bom}
@@ -2270,6 +2654,7 @@ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns\hyxmp@hash">^^J%
   \hyxmp@xmpRights@schema
   \hyxmp@dc@schema
   \hyxmp@photoshop@schema
+  \hyxmp@photometa@schema
   \hyxmp@xmp@basic@schema
   \hyxmp@mm@schema
   \hyxmp@add@to@xml{%
@@ -2471,8 +2856,6 @@ ___</rdf:RDF>^^J%
 % always to leave the \pdfterm{Metadata} stream uncompressed, so the
 % \acro{XMP} metadata is likely to be missed by non-\acro{PDF}-aware
 % \acro{XMP} viewers.
-% \changes{v1.2}{2010/06/04}{Added support for the \XeTeX\ backend
-%   (\texttt{xdvipdfmx})}
 %    \begin{macrocode}
 \newcommand*{\hyxmp@embed@packet@xetex}{%
   \special{pdf:stream @hyxmp@Metadata (\hyxmp@xml)
-- 
cgit v1.2.3

