% makeindex < aebpro_man.idx > aebpro_man.ind
\documentclass{article}
\usepackage[fleqn]{amsmath}
\usepackage[
    web={centertitlepage,designv,
        forcolorpaper,usesf,tight,latextoc,pro},
    eforms,aebxmp
]{aeb_pro}
\usepackage{aeb_mlink}
\usepackage{graphicx,array}
%\usepackage{myriadpro}
%\usepackage[usecmtt]{myriadpro}
\usepackage[altbullet]{lucidbry}

\usepackage{makeidx}
\makeindex
\usepackage{acroman}

%\usepackage{myriadpro}
\usepackage[altbullet]{lucidbry}


%\margins{.25in}{.25in}{24pt}{.25in} % left,right,top, bottom
%\screensize{6.5in}{5in} % height, width

\university{\AcroTeX.Net}
\title{The aebXMP Package\texorpdfstring{\\[1em]}{: }Updating XMP using E4X and {\LaTeX}}
\author{D. P. Story}
\Authors{{D. P. Story}{J\u00FCrgen Gilg}}
\subject{Documentation of the AeBXMP Package}
\Keywords{XMP,E4X,Adobe Acrobat,JavaScript}
\email{dpstory@acrotex.net}
\copyrightStatus{True}
\copyrightNotice{Copyright (C) 2006-\the\year, D. P. Story}
\copyrightInfoURL{http://www.acrotex.net}
\authortitle{Programming and Development, AcroTeX.Net}
\descriptionwriter{Testing and Promotions Department, AcroTeX.Net}
\customProperties
{%
    {name=Developer,value={D. P. Story, Esq.}}
    {name=Motivator,value=J\u00FCrgen Gilg}
}

\DeclareInitView{windowoptions=showtitle}

\def\dps{$\hbox{$\mathfrak D$\kern-.3em\hbox{$\mathfrak P$}%
   \kern-.6em \hbox{$\mathcal S$}}$}

\def\AcroTeX{Acro\negthinspace\TeX}

\makeatletter
\@mparswitchfalse\reversemarginpar
\makeatother


%\pagestyle{empty}
\parindent0pt
\parskip\medskipamount


\definePath\bgPath{"C:/Users/Public/Documents/ManualBGs/Manual_BG_Print_AeB.pdf"}
\begin{docassembly}
\addWatermarkFromFile({
    bOnTop:false,
    cDIPath:\bgPath
});
\executeSave();
\end{docassembly}


\begin{document}

\maketitle

\changelinkcolorto{black}

\tableofcontents

\changelinkcolorto{webgreen}


\section{Introduction}

The motivation for the development of this package came from
Herr~J\"{u}rgen Gilg, who had a need to fill in the metadata fields
beyond those normally populated by using \textsf{hyperref}:
\textsf{Title}, \textsf{Author}, \textsf{Subject} and
\textsf{Keywords}. Of particular interest to him were the metadata
fields \textsf{Copyright Status}, \textsf{Copyright Notice} and
\textsf{Copyright Info URL}.

After doing some research on the CTAN archives, I came across the
\textsf{hyperxmp} package by Scott Pakin.\begin{NoHyper}\footnote{The reader is
invited to read the documentation of the \textsf{hyperxmp}, as
contained therein is a good discussion of XMP (eXtensible Metadata
Platform).}\end{NoHyper} The package works well with \textsf{pdftex} and
\textsf{dvipdfm}, but has a bit of a problem when using the
distiller. For this reason, I sought my own solution to the problem.

As a beta tester of Acrobat~8 Professional, I had the opportunity to
use some of the new capabilities of the JavaScript interpreter as an
alternate approach to the one used by Mr.~Patkin. The JavaScript
version~1.6 interpreter, the one used in version 8, comes with E4X,
an XML parser, built in.  I could see that E4X could be exploited to
manipulate the XMP data, and this was my approach.

\section{Requirements}

The techniques used by the \textsf{aebxmp} package to update the XMP
data require the \textcolor{blue}{{\AcroTeX} eDucation Bundle}
(AeB), freely available from \url{www.acrotex.net}.  Because E4X is
used, we also require \textsf{Acrobat~8 Professional}, and, since
you have \textsf{Acrobat~8}, my \LaTeX ing friend, use Acrobat
\textsf{Distiller} to create your PDF.

\section{The Test File}

The package \textsf{aebxmp} has a simple test file,
\textsf{aebxmp\_test.tex}, which is found in the \texttt{examples} folder.

To use this package, you must have, in addition to Acrobat~8 Pro (or later),
installed on your computer a standard {\TeX} system, including the
latest version of AeB.\footnote{AeB can be downloaded from any CTAN
server, from \url{www.math.uakron.edu/~dpstory/webeq.html}, or from
\url{www.acrotex.net}.}

\section{Metadata}

The \textsf{hyperref} package provides basic metadata support, providing
a mechanism for providing the title, author, subject, and keywords. Beyond
these, we can include additional metadata.

\subsection{Author, Author}

The \textsf{hyperref} package allows you to specify an author or authors;
the \textsf{Web} package uses this through the \cs{title} command, which
passes its argument on to \textsf{hyperref} of inclusion in the PDF Info
dictionary. The authors names are not individually assessable through
JavaScript. In Acrobat~9, I believe, the JavaScript API includes the
\texttt{Doc.info.Authors} property, its value is an array of authors,
We can access each author using array notation: First author is
\texttt{this.info.Authors[0]}, second author is
\texttt{this.info.Authors[1]}, and so on. The number of authors is
obtained using the length property of arrays, \texttt{this.info.Authors.length}.

The AeBXMP interface to this is through the \cs{Authors} command. It takes
a list of authors, each enclosed in braces, no commas (,) between the
authors. Like so:
\begin{Verbatim}[xleftmargin=20pt,fontsize=\fontsize{9}{11}\selectfont]
\Authors{{D. P. Story}{J\u00FCrgen Gilg}}
\end{Verbatim}
Using \cs{Authors} will overwrite the author(s) named in the \cs{title}
command (of \textsf{Web}), or more generally, passed to
\verb!\hypersetup{pdfauthor={<author>}}! of
\textsf{hyperref}.\begin{NoHyper}\footnote{This may be to your advantage when using
\textsf{Web}; the value of \cs{title} is used to display the author(s) of
the document, you may want to present the names one way on the title page,
for example, and another way in the \textsf{Description} tab of the
\textsf{Document Properties} dialog box.}\end{NoHyper}

If you do use \cs{Authors} and overwrite the author(s) as passed through
\textsf{hyperref}, the first author listed will be the one returned by the
JavaScript command \texttt{this.info.Author}; in the Document Properties
Dialog Box (\texttt{Ctrl+D}), all authors are listed in a semi-colon
delimited list.


\subsection{The \texorpdfstring{\cs{Keywords}}{\textbackslash{Keywords}} Command}

The \cs{Authors} command utilizes \texttt{Doc.info.Authors}, which takes
an array of authors names. There is no such property available for
\texttt{Doc.info.Keywords}, the value of this property takes only a string
of keywords.  The keywords are stored by Acrobat in three ways,
(1) \texttt{pdf:Keywords}; (2) in the \textbf{Info} dictionary; and (3) in
\texttt{dc:subject}. In the latter case, \texttt{dc:subject} takes a \texttt{Bag}
of subjects (keywords). A \texttt{Bag}, in XMP parlance, is an unordered array.

The command \cs{Keywords} takes a comma delimited list of keywords. Notice
the word is capitalized to distinguish it from \cs{keywords}, which is
defined in the \textsf{Web} package as the interface to inserting the
keywords, via \textsf{hyperref}, into the \textbf{Info} dictionary.
\begin{Verbatim}[xleftmargin=20pt,fontsize=\fontsize{9}{11}\selectfont]
\Keywords{AcroTeX.Net,XMP,E4X,Adobe Acrobat,JavaScript}
\end{Verbatim}
The command takes each comma-delimited list of keywords and
inserts each into the \texttt{dc:subject} part of the metadata.
For this document, the keywords appear in the XML metadata as
\begin{Verbatim}[xleftmargin=20pt,fontsize=\fontsize{9}{11}\selectfont]
<dc:subject>
   <rdf:Bag>
      <rdf:li>AcroTeX.Net</rdf:li>
      <rdf:li>XMP</rdf:li>
      <rdf:li>E4X</rdf:li>
      <rdf:li>Adobe Acrobat</rdf:li>
      <rdf:li>JavaScript</rdf:li>
   </rdf:Bag>
</dc:subject>
\end{Verbatim}
When the document is first opened, the following command is executed
\begin{Verbatim}[xleftmargin=20pt,fontsize=\fontsize{9}{11}\selectfont]
this.info.Keywords="AcroTeX.Net; XMP; E4X; Adobe Acrobat; JavaScript"
\end{Verbatim}
Here, I have broken the string across lines for readability. This inserts
the same list of keywords into the \textbf{Info} dictionary.

When you executed \texttt{this.info.Keywords} in the console, you'll get
%
\begin{Verbatim}[xleftmargin=20pt,fontsize=\fontsize{9}{11}\selectfont]
AcroTeX.Net; XMP; E4X; Adobe Acrobat; JavaScript
\end{Verbatim}
as expected.

To access the individual keywords, I've inserted a document-level
function, \texttt{aKeywords}. It takes as its argument the index of the
keyword you want to get; For example, executing \texttt{aKeyword(0)} in
the console returns a value of \texttt{"AcroTeX.Net"}, while
\texttt{aKeyword(4)} returns a value of \texttt{"JavaScript"}. If you
execute \texttt{aKeyword(5)}, a value of \texttt{undefined} is returned.

Listing the keywords may be of interest to someone, it is an exercise to
me.\begin{NoHyper}\footnote{Actually, this is the way \textbf{Acrobat} handles a
comma-delimited list of keywords when the words are entered through
the user interface; it puts them in a \texttt{Bag}.}\end{NoHyper}

\subsection{Additional Metadata}

As mentioned previously, the \textsf{aebxmp} package addresses three
areas of interest: Setting the \textsf{Copyright Status},
\textsf{Copyright Notice}, and the \textsf{Copyright Info URL}.
Obviously, other elements of the XMP can be addressed. To that end,
the \textsf{aebxmp} package defines five new {\LaTeX} commands to
populate the values of the five metadata fields \textsf{Copyright
Status}, \textsf{Copyright Notice}, \textsf{Copyright Info URL},
\textsf{Author Title}, and \textsf{Writer Description}.

Values for the arguments of these commands are documented below.
\begin{description}
\item[] \verb!\copyrightStatus{True|False}!: If \texttt{True}, \textsf{Copyright Status} is set to
\texttt{Copyrighted}; if \texttt{False}, \textsf{Copyright Status} is set to \textsf{Public Domain}.
If left empty, the status is set to \textsf{Unknown}.

\item[]\verb!\copyrightNotice{<text>}!: The \texttt{<text>} of the \textsf{Copyright Notice} is defined

\item[] \verb!\copyrightInfoURL{<URL>}!: The \texttt{<URL>} to the copyright information
\item[] \verb!\authortitle{<text>}!: The \texttt{<text>} appears in the
\textsf{Author Title} line on the \textsf{Additional Metadata} dialog box.
This is a \textbf{Photoshop} property. (See the Advanced category in the left
panel.)
\item[] \verb!\descriptionwriter{<text>}!: The \texttt{<text>} appears in the
\textsf{Description Writer} line on the \textsf{Additional Metadata} dialog box.
This is a \textbf{Photoshop} property. (See the \textsf{Advanced} category in the left
panel.)
\end{description}

For example, for this document, we have in the preamble,
\begin{Verbatim}[xleftmargin=20pt,fontsize=\fontsize{9}{11}\selectfont]
\copyrightStatus{True}
\copyrightNotice{Copyright (C) 2006-\the\year, D. P. Story}
\copyrightInfoURL{http://www.acrotex.net}
\authortitle{Programming and Development, AcroTeX.Net}
\descriptionwriter{Testing and Promotions Department, AcroTeX.Net}
\end{Verbatim}

\newtopic Enter unicode (\cs{uXXXX}) directly into the \cs{copyrightNotice} and \cs{copyrightInfoURL} fields; for example,
\begin{Verbatim}[xleftmargin=20pt,fontsize=\fontsize{9}{11}\selectfont]
\copyrightNotice{Copyright (C) 2006-\the\year, J\u00FCrgen Gilg}
\end{Verbatim}
Unicode can be used in \cs{authortitle} and \cs{descriptionwriter} as
well.

\subsection{Custom Document Properties}
You can define custom properties using the \cs{customProperties} command.
\begin{Verbatim}[xleftmargin=20pt,fontsize=\fontsize{9}{11}\selectfont]
\customProperties
{%
    {name=<name1>,value=<value1>}
    {name=<name2>,value=<value2>}
}
\end{Verbatim}
The value of the \texttt{name} key requires a unique name, which must not
be one of the standard property names \texttt{Title}, \texttt{Author}, \texttt{Subject}, \texttt{Keywords},
\texttt{Creator}, \texttt{Producer}, \texttt{CreationDate}, \texttt{ModDate}, and
\texttt{Trapped}. The value of \texttt{name} shall consist of the
characters \texttt{A--Z}, \texttt{a--z}, and \texttt{0--9}, and beginning with a
letter. The value may contain unicode, for example, in the preamble of
this document we have,
\begin{Verbatim}[xleftmargin=20pt,fontsize=\fontsize{9}{11}\selectfont]
\customProperties
{%
    {name=Developer,value={D. P. Story, Esq.}}
    {name=Motivator,value=J\u00FCrgen Gilg}
}
\end{Verbatim}
The properties may be accessed through the \texttt{info} property of the
\texttt{Doc} object. The button (on the left) \marginpar{\hfill\pushButton[\TU{Press to see the document
properties}\CA{Info}
\A{\JS{%
    console.show();\r
    console.clear();\r
    for (var o in this.info)\r\t
        console.println("info."+o+"="+this.info[o]);\r
    if (typeof aKeywords=="function") {\r\t
        console.println("List Keywords:");\r\t
        var i=0;\r\t
        while(aKeywords(i)!=undefined) {\r\t\t
            console.println("    "+aKeywords(i));\r\t\t
            i++;\r\t
        }\r
    }
}}]{info}{}{11bp}}
opens the console debugger window and displays all the document
properties.

The custom properties may be viewed using the user interface; press
\texttt{Ctrl+D} and choose the \textsf{Custom} tab.

For more information on this topic, see
\href{http://www.adobe.com/devnet/xmp.html}{
Part 3, Storage in Files}, section 3.2 on \textbf{Native metadata in PDF files}, in particular,
see section~3.2.1 concerning user-defined document properties.


\section{Checking for validity}

While looking at this file in Acrobat (or Adobe Reader), press
\texttt{Ctrl+D} to get the \textsf{Document Properties} dialog box.
Select the \textsf{Description} tab and click \textsf{Additional
Metadata}. Since this document was built using the \textsf{aebxmp}
package, with the declarations

\begin{Verbatim}[xleftmargin=20pt,fontsize=\fontsize{9}{12}\selectfont]
\copyrightStatus{True}
\copyrightNotice{Copyright (C) 2006-\the\year, D. P. Story}
\copyrightInfoURL{http://www.acrotex.net}
\authortitle{Programming and Development, AcroTeX.Net}
\descriptionwriter{Testing and Promotions Department, AcroTeX.Net}
\end{Verbatim}

\newtopic In the Advanced Metadata dialog box, you should see,
\begin{itemize}
    \item[] \textsf{Copyright Status}: \texttt{Copyrighted}
    \item[] \textsf{Copyright Notice}: \texttt{Copyright (C) 2006-\the\year, D. P. Story}
    \item[] \textsf{Copyright Info URL}: \texttt{http://www.acrotex.net}
    \item[] \textsf{Author Title}: \texttt{Programming and Development,
    AcroTeX.Net}
    \item[] \textsf{Description Writer}: \texttt{Testing and Promotions Department,
    AcroTeX.Net}
\end{itemize}
in addition to the usual Document Title, Author, Description, and
Keywords. I promise you that I did not enter these values through the user interface. \texttt{:-)}
\section{Resources}

\newtopic The resources for the development of this package are
\begin{itemize}
    \item \textsl{Standard ECMA-357: ECMAScript for XML (E4X) Specification},\\
        {\small\url{http://www.ecma-international.org/publications/standards/Ecma-357.htm}}
    \item \textsl{XMP Specification}, \url{http://www.adobe.com/devnet/xmp.html}
    \item \textsl{Acrobat JavaScript Scripting Reference}, Version 8.0\\
    \url{http://www.adobe.com/go/acrobat_developer}
    \item \textsf{hyperxmp} package by Scott Pakin.\\
    \url{ftp://cam.ctan.org/tex-archive/macros/latex/contrib/hyperxmp/}
    \item The {\AcroTeX} System Tools, available for free download at \url{www.acrotex.net}. This is
        a {\LaTeX}-based system.
\end{itemize}

Now, I simply must get back to my retirement. \dps

\end{document}
