%
% ^^A   N.B.: It will probably be difficult to merge this file with other
% ^^A         .dtx files without a lot of manual effort.  I define so
% ^^A         much stuff in the prologue -- including things like
% ^^A         \AtBeginDocument that can't be moved later -- that I wasn't
% ^^A         able to stick to the simple driver recommended by the doc
% ^^A         documentation.  Once I realized that making attachfile.dtx
% ^^A         mergeable was a lost cause anyway, I moved all the user
% ^^A         documentation into the uncommented driver region, as this
% ^^A         makes editing a lot easier.
% ^^A   
% ^^A         You have been warned.
%
% \iffalse meta-comment
%
% Copyright (C) 2001 Scott Pakin <pakin@uiuc.edu>
% -------------------------------------------------------
%
% This package may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.2
% 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.2 or later is part of all distributions of LaTeX
% version 1999/12/01 or later.
%
% \fi
% \iffalse
%% File: attachfile.dtx Copyright (C) 2001 Scott Pakin <pakin@uiuc.edu>
%
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{attachfile}
%<package>         [2001/01/03 v1.00 PDF 1.3 File Attachment Package (SDP)]
%<package>\RequirePackage{keyval}
%<package>\RequirePackage{calc}
%
%<*driver>
\documentclass{ltxdoc}
\usepackage[pdftex,hyperindex=false]{attachfile}
\usepackage[pdftex]{color}
\usepackage{xspace}
\GetFileInfo{attachfile.sty}
\EnableCrossrefs
\CodelineIndex     % Do not change; see comments before \IndexPrologue below.

% Uncomment the following line if you don't want to include a
% source-code listing.
%\OnlyDescription

% My nice, long variables names wreak havoc with a three-columned index.
\setcounter{IndexColumns}{2}

% For some reason that I haven't yet been able to figure out, hyperref screws
% up \filedate and \fileversion.  As a workaround, I save the good versions
% and reload them when the document begins.
\makeatletter
\edef\correct@filedate{\filedate}
\edef\correct@fileversion{\fileversion}
\AtBeginDocument{%
  \edef\filedate{\correct@filedate}%
  \edef\fileversion{\correct@fileversion}%
}
\makeatother

% Set up hyperlink colors
\definecolor{darkred}{rgb}{0.5,0,0}
\definecolor{darkgreen}{rgb}{0,0.3,0}
\definecolor{darkblue}{rgb}{0,0,0.5}
\definecolor{darkbrown}{rgb}{0.28,0.07,0.07}
\hypersetup{%
  colorlinks=true,
  citecolor=darkblue,
  urlcolor=darkgreen,
  linkcolor=darkred,
  menucolor=darkbrown
}

% Help prevent weird line breaks in URLs
\def\UrlBreaks{}
\def\UrlBigBreaks{\do/}

% Define some logical styles.
\newcommand{\menuname}[1]{\textit{#1}}
\newcommand{\pkgname}[1]{%
  \texttt{#1}\SortIndex{#1}{#1 (package)\encapchar usage}}
\newcommand{\pdfname}[1]{%
  \textsf{#1}\SortIndex{#1}{\textsf{#1}\encapchar usage}}
\newcommand{\acronym}[1]{%
  \textsc{\MakeLowercase{#1}}%
  \SortIndex{#1}{\textsc{\MakeLowercase{#1}}\encapchar usage}%
}

% Define some indexable things.
\newcommand{\bibtex}{%
  \BibTeX\SortIndex{BibTeX}{\BibTeX\encapchar usage}}
\newcommand{\pdflatex}{%
  pdf\LaTeX\SortIndex{pdfLaTeX}{pdf\LaTeX\encapchar usage}}
\newcommand{\latex}{%
  \LaTeX\SortIndex{LaTeX}{\LaTeX\encapchar usage}}
\newcommand{\tex}{%
  \TeX\SortIndex{TeX}{\TeX\encapchar usage}}

% Index one of attachtext's options.
\newcommand{\prevopt}{}
\newenvironment{describeopt}[1]{%
  \gdef\prevopt{#1}%
  \index{options\levelchar\prevopt%
         \actualchar\texttt{\prevopt}%
         \encapchar(usage}%
  \index{\prevopt%
         \actualchar\texttt{\prevopt} (option)%
         \encapchar(usage}%
}{%
  \index{\prevopt%
         \actualchar\texttt{\prevopt} (option)%
         \encapchar)usage}%
  \index{options\levelchar\prevopt%
         \actualchar\texttt{\prevopt}%
         \encapchar)usage}%
}

% Output the name of an option, and also enter it into the index.
\newcommand{\indexedopt}[1]{%
  \texttt{#1}%
  \index{options\levelchar#1%
         \actualchar\texttt{#1}%
         \encapchar usage}%
  \index{#1%
         \actualchar\texttt{#1} (option)%
         \encapchar usage}%
}

% Index a macro description.  This is copy&pasted from \SpecialUsageIndex,
% but recast as an environment, so we can get beginning and ending page
% numbers.
\makeatletter
\newcommand{\prevmacro}{}
\newenvironment{describemacro}[1]{%
  \gdef\prevmacro{#1}%
  \@bsphack%
    {\let\special@index\index%
     \expandafter\SpecialIndex@\expandafter{\prevmacro}{\encapchar(usage}}%
  \@esphack%
}{%
  \@bsphack%
    {\let\special@index\index%
     \expandafter\SpecialIndex@\expandafter{\prevmacro}{\encapchar)usage}}%
  \@esphack%
}
\makeatother

% Make the index automatically add an entry to the table of contents.
% NOTE: Hardwired to a code-line index.  If you want to use \PageIndex
%       instead of \CodelineIndex, be sure to modify the following text
%       appropriately.
\IndexPrologue{%
  \section*{Index}%
  \markboth{Index}{Index}%
  \addcontentsline{toc}{section}{Index}%
  Numbers written in italic refer to the page where the corresponding
  entry is described; numbers underlined refer to the code line of the
  definition; numbers in roman refer to the code lines where the entry
  is used.
}

% Make legal-minded people happy.
%\newcommand{\smallreg}{\textsuperscript{\textregistered}}
%\newcommand{\smalltm}{\textsuperscript{TM}}
\newcommand{\smallreg}{}
\newcommand{\smalltm}{}

% Define some trademarked names.
\newcommand{\adobe}{Adobe\smallreg\xspace}
\newcommand{\adobeacrobat}{%
  \adobe Acrobat\smallreg%
  \index{Adobe Acrobat|usage}%
  \xspace%
}
\newcommand{\adobeacrobatreader}{%
  \adobeacrobat Reader\smalltm%
  \index{Adobe Acrobat\levelchar Reader|usage}%
  \xspace%
}

% The following was swiped verbatim from ltxguide.cls:

% A declaration of a command, in a box, set out into the margin.
%
% Unfortunately, there is a bug with this command, which allows page
% breaks to happen after a \begin{decl}[DATE]: it is a bug with TeX that
% makes it very difficult to get page-breaks correct near marginals,
% especially at the end of a paragraph.

\newenvironment{decl}[1][]%
    {\par\small\addvspace{4.5ex plus 1ex}%
     \vskip -\parskip
     \ifx\relax#1\relax
        \def\@decl@date{}%
     \else
        \def\@decl@date{\NEWfeature{#1}}%
     \fi
     \noindent\hspace{-\leftmargini}%
     \begin{tabular}{|l|}\hline\ignorespaces}%
    {\\\hline\end{tabular}\nobreak\@decl@date\par\nobreak
     \vspace{2.3ex}\vskip -\parskip}

% Because we have the fancy decl environment above, we don't need
% macro names in the margins.
\makeatletter
\let\PrintDescribeMacro=\@gobble
\makeatother

% The document starts here.
\begin{document}
\title{The \textsf{attachfile} package\thanks{This file
        has version number \fileversion, last revised \filedate.}}
\author{Scott Pakin\\pakin@uiuc.edu}
\date{\filedate}
\hypersetup{%
  pdftitle={The attachfile package},
  pdfauthor={Scott Pakin <pakin@uiuc.edu>},
  pdfsubject={LaTeX file attachment package},
  pdfkeywords={attachments,annotations,PDF,LaTeX,package,automatic,files}
}
\maketitle

\begin{abstract}
  This package defines an |\attachfile| command that lets you attach
  arbitrary files to a \acronym{PDF} document.  These files are
  embedded right in the \acronym{PDF} file, so they get transmitted
  along with it.  The package also gives you control over the
  corresponding icon's properties and various other associated
  metadata.
\end{abstract}

\tableofcontents

\section{Introduction}

\acronym{PDF}, \adobe's Portable Document Format, is a common way to
distribute documents that look the same on all platforms and output
devices.  Beginning with \acronym{PDF} version~1.3, \acronym{PDF}
supports ``file attachment annotations''.  These are arbitrary
auxiliary files that get embedded directly into the \acronym{PDF}
document, just like attachments in an e-mail message.

The \pkgname{attachfile} package gives \pdflatex{} users the ability
to add these attachments to their documents automatically.  And
because \latex{} is a markup language, not a \acronym{WYSIWYG} tool,
the user has precise control over the location of the file attachment
icons.  If an icon representing an attached spreadsheet file is placed
next to a figure, the icon will move along with the figure whenever
the document is modified.  Furthermore, it is possible to define
global properties for all the file attachments in a document.  With
one command, a user can change the properties of all the icons in the
entire document.

Finally, one nifty feature that \pkgname{attachfile} supports is the
ability to use your own icons, which can be text, graphics, tables,
mathematics---you name it!  With this feature, a \acronym{PDF} file
can, for example, instruct the reader to click on a formula to extract
the Mathematica\smallreg\ notebook that derived it.  Or to click on a
graph to extract the Microsoft\smallreg\ Excel spreadsheet that
contains all the data that was plotted.  The possiblities are endless.

\bigskip

Okay, let's get down to business.  Here are some sample file
attachments, so you can see if your \acronym{PDF} viewer is able to
handle them:

\begingroup
\attachfilesetup{%
  color=1 0 0,
  mimetype=text/plain,
  author={Scott Pakin},
  icon=PushPin,
  description={This document's BibTeX bibliography}
}

\begin{center}
\begin{tabular}{@{}lc@{\qquad(Should look like this:~}c@{)}}
  Icon: &
  \attachfile{attachfile.bib} &
  \noattachfile \\

  \latex\ text: &
  \textattachfile{attachfile.bib}{\texttt{attachfile.bib}} &
  \textcolor[rgb]{1,0,0}{\texttt{attachfile.bib}}
\end{tabular}
\end{center}
\endgroup

\noindent
Each of the above points to the \bibtex\ bibliography (a plain text
file) for the document you're reading now.  Try extracting the
attachment.  In \adobeacrobat, this is achieved by right-clicking on
the icon and choosing ``Extract File$\ldots$''.  You can also
double-click to open the file immediately.  If you're unable to access
the attached file, or you observe miscellaneous strange behavior, your
\acronym{PDF} viewer might not be cabable of handling file attachments
properly.  See Section~\ref{sec:caveats} for some \acronym{PDF} viewer
problems I encountered while testing \pkgname{attachfile}.


\section{User interface}

|\usepackage{attachfile}| implicitly does a |\usepackage{hyperref}|.
Any options that get passed to \pkgname{attachfile} will be forwarded
to \pkgname{hyperref}.  \pkgname{attachfile}~\fileversion{} does not
process any options itself.  Hence, a typical way to load
\pkgname{attachfile} is by putting a |\usepackage[pdftex]{attachfile}|
in your document's prologue.

\subsection{Commands}
\label{sec:commands}

The following are the commands that \pkgname{attachfile} makes
available for attaching files, customizing the icon appearance, and
changing various file attachment metadata.

\begin{describemacro}{attachfile}
\begin{decl}
  |\attachfile| \oarg{options} \marg{filename}
\end{decl}
\DescribeMacro{\attachfile}
The |\attachfile| macro, has only one required argument: the name of
the file to attach.  |\attachfile| will insert an icon at the current
point in the document to represent the attachment.  \meta{options} is
a list of optional parameters for describing the icon and other
assorted metadata.  It is described in Section~\ref{sec:options}.
\end{describemacro}

\begin{describemacro}{noattachfile}
\begin{decl}
  |\noattachfile| \oarg{options}
\end{decl}
\DescribeMacro{\noattachfile}
When writing instructions, it is sometimes convenient to describe what
a file attachment icon looks like without actually attaching a file.
That's what |\noattachfile| is for.  All it does is insert the image
of a file attachment icon into the document.  \meta{options} is a list
of optional parameters for describing the icon and other assorted
metadata.  It is described in Section~\ref{sec:options}.
\end{describemacro}

\begin{describemacro}{textattachfile}
\begin{decl}
  |\textattachfile| \oarg{options} \marg{filename} \marg{text}
\end{decl}
\DescribeMacro{\textattachfile}
|\textattachfile| is just like |\attachfile|, except that instead of
using one of the predefined \acronym{PDF} icons, it lets you use an
arbitrary piece of text to represent the attachment.  The \meta{text}
parameter is not limited to text; it can contain any arbitrary
horizontal material.  The following are all legal uses of
|\textattachfile|:

\begin{itemize}
  \item \texttt{You can} |\textattachfile{myfile.cc}{extract| \texttt{my
  source code}|}| \texttt{if your PDF viewer supports file annotations.}

  \item \texttt{It is intuitively obvious to even the most casual observer
  that}
\begin{verbatim}
     \textattachfile{derivation.m}{$\displaystyle
       \frac{\partial E_p}{\partial w_{ji}^h} =
         -\sum_k (y_{pk} - o_{pk}) f_k^{o}{}'(\mbox{net}_{pk}^o)
                 w_{kj}^o f_j^h{}'(\mbox{net}_{pj}^h) x_{pi}$}
\end{verbatim}

  \item |\textattachfile{earningsdata.csv}{\includegraphics{earnings}}|

\end{itemize}
\end{describemacro}

\begin{describemacro}{attachfilesetup}
\begin{decl}
  |\attachfilesetup| \marg{options}
\end{decl}
\DescribeMacro{\attachfilesetup}
If you find yourself passing the same set of options to multiple
|\attachfile| calls in your document, you can use |\attachfilesetup|
to specify default option values.  |\attachfilesetup|'s \meta{options}
parameter is the same as that used by |\attachfile| and is described
in Section~\ref{sec:options}.  Some noteworthy points are:

\begin{enumerate}
  \item |\attachfilesetup| can be called as many times as desired.
  Any options specified replace the previous value of those options.
  All unspecified options are left alone.

  \item Options passed to |\attachfile| take precedence over those
  specified by |\attachfilesetup|.  This lets you define default
  values for all file attachments and selectively override them on a
  per-attachment basis.

  \item Options set by |\attachfilesetup| are local to the current
  scope.  This lets you assign defaults to a group of file attachments
  without affecting the global defaults.  To define options that apply
  to the entire document, |\attachfilesetup| should be called at the
  top-level scope (which includes the document's prologue).
\end{enumerate}
\end{describemacro}

\subsection{Options}
\label{sec:options}

\pkgname{attachfile} gives the user a great deal of control over the
way files are attached to a document.  All the commands in
Section~\ref{sec:commands} accept the same set of options, which are
entered as comma-separated, \meta{key}|=|\meta{value} pairs.  Options
can be specified in any order.  Case is significant.  And only the
options you want to change need to be specified; the others will
retain their previous value (or the default, if no previous value was
specified).

The following are the options \pkgname{attachfile} accepts, in
alphabetical order.

\begin{describeopt}{appearance}
\begin{decl}
  |appearance=|\meta{boolean}
\end{decl}
The \pkgname{attachfile} package normally embeds the file attachment's
icon explicitly with each file attachment annotation.  (In
\acronym{PDF}-speak, it includes an appearance dictionary in the
\pdfname{FileAttachment} object.)  The advantages to doing this are to
ensure that:

\begin{itemize}
  \item The file attachment icons look the same in all \acronym{PDF}
  viewers.

  \item \tex\ knows exactly how much space to allocate, instead of
  just guessing based on the size of the \adobeacrobat icons.

  \item Pre-1.3 \acronym{PDF} viewers don't regress to showing an
  ``unknown annotation type'' graphic.
\end{itemize}

\noindent
However, the problems with embedding the icon graphic are:

\begin{itemize}
  \item It adds a bit of extra bulk to the \acronym{PDF} file.

  \item It takes flexibility away from the \acronym{PDF} viewer, which
  can no longer choose for itself how best to render a file attachment
  icon.
\end{itemize}

The |appearance| option gives the author the ability to prevent the
icon's appearance from being specified explicitly in the \acronym{PDF}
file.  By setting \texttt{appearance=false}, it will be left up to the
\acronym{PDF} viewer to decide how to display the icon.
\end{describeopt}

\begin{describeopt}{author}
\begin{decl}
  |author=|\meta{text}
\end{decl}
The metadata associated with a file attachment annotation includes the
name of the person who attached the file.  In \adobeacrobat, this
information is shown when one right-clicks on the file attachment icon
and selects \menuname{Properties}.  By default, no author is listed,
but specifying |author=|\meta{name} sets the author field to
\meta{name}.  As a special case, specifying the |author| option with
no name assignment makes the author the same as the author(s) named
with the |\author| command.
\end{describeopt}{author}

\begin{describeopt}{color}
\begin{decl}
  |color=|\meta{red} \meta{green} \meta{blue}
\end{decl}
The icons inserted by |\attachfile| and the text inserted by
|\textattachfile| can be any color.  The |color| option sets this
color.  Each of \meta{red}, \meta{green}, and \meta{blue} must be a
decimal number between 0~(darkest) and 1~(brightest).  The default is
|color=1 0.9255 0.7765|, which is a beige.
\end{describeopt}

\begin{describeopt}{date}
\begin{decl}
  |date=|\meta{text}
\end{decl}
Every annotation in a \acronym{PDF} can have a timestamp indicating
when the annotation was last modified.  \pkgname{attachfile}
automatically adds a timestamp to file attachment annotations.  It
uses the time and date at which \latex\ started processing your job
and converts it to the form ``|D:|\textit{YYYYMMDDHHmmSS}'', which is
the format recommended by the \acronym{PDF} reference manual~\cite[p.\
89]{PDFRef}, minus the Universal Time information.\footnote{In
addition, seconds are hardwired to zero, because \tex's
\texttt{\bslash time} command has only minute precision.}

The |date| option lets you specify the modification date and time
explicitly.  Note, however, that although the \acronym{PDF} reference
manual clearly states that ``viewer applications should be prepared to
accept and display a string in any format''~\cite[p.\ 400]{PDFRef},
\adobeacrobat will ignore any timestamp that is not in the recommended
format and will instead show the current date and time.
\end{describeopt}

\begin{describeopt}{description}
\begin{decl}
  |description=|\meta{text}
\end{decl}
The metadata associated with a file attachment annotation can include
a brief description of the file.  In \adobeacrobat, this information
is shown when one right-clicks on the file attachment icon and selects
\menuname{Properties}.  By default, no description is included, but
specifying |description=|\meta{text} sets the description field to
\meta{text}.
\end{describeopt}

\begin{describeopt}{icon}
\begin{decl}
  |icon=|\meta{name}
\end{decl}
\acronym{PDF}~1.3 defines four icons that can be used for file
attachments: \pdfname{Graph}, \pdfname{Paperclip}, \pdfname{PushPin},
and \pdfname{Tag}.  These are shown in Table~\ref{tbl:icons}.  If no
icon name is specified, \pdfname{PushPin} is assumed.  While the
\acronym{PDF} specifications say that, normally, a \acronym{PDF}
viewer chooses how to display each of those, the \pkgname{attachfile}
package specifies the appearance explicitly.  This is what
\adobeacrobat does, presumably because doing so ensures that viewers
which don't support file attachment annotations can still display
something reasonable.  The tradeoff is that it slightly increases the
size of the \acronym{PDF} file.

\begin{table}[tbp]
\newcommand{\tallspace}{\rule[-2pt]{0pt}{24pt}}
\centering
\begin{tabular}{lc}
  \tallspace\pdfname{Graph}     & \noattachfile[icon=Graph] \\
  \tallspace\pdfname{Paperclip} & \noattachfile[icon=Paperclip] \\
  \tallspace\pdfname{PushPin}   & \noattachfile[icon=PushPin] \\
  \tallspace\pdfname{Tag}       & \noattachfile[icon=Tag]
\end{tabular}
\caption{Valid file attachment icons}
\label{tbl:icons}
\end{table}
\end{describeopt}

\begin{describeopt}{mimetype}
\begin{decl}
  |mimetype=|\meta{type}
\end{decl}
It is considered good practice to specify the \acronym{MIME}
type~\cite{Freed1996} of each attached file.  That way, a
\acronym{PDF} viewer can automatically launch an appropriate
application to process the file.  \meta{type} should be the form
``\meta{type}|/|\meta{subtype}''.  For instance, a plain text file
would be specified with ``\texttt{mimetype=text/plain}''.  An
\acronym{MPEG} movie would be specified with
``\texttt{mimetype=video/mpeg}''.  The
\href{http://www.iana.org/}{Internet Assigned Numbers Authority}
maintains a list of registered media types~\cite{MediaTypes}, so look
there first to see what type to use for a given file.
\end{describeopt}

\begin{describeopt}{print}
\begin{decl}
  |print=|\meta{boolean}
\end{decl}
By default, file annotation icons print along with the rest of the
document.  By setting \texttt{print=false}, the icons will not print.
Note that in \adobeacrobat, annotations will \emph{never} print unless
the Annotations box is checked in the \Acrobatmenu{Print}{Print
dialog}.
\end{describeopt}

\begin{describeopt}{timezone}
\begin{decl}
  |timezone=|\meta{offset}
\end{decl}
Because \tex\ doesn't make the current timezone available,
\pkgname{attachfile} is unable to include timezone information when it
timestamps a file attachment.  The |timezone| option lets you manually
specify the timezone.  \meta{offset} is the offset from
Universal\index{Universal Time|usage} Time (a.k.a.\ \acronym{GMT}) and
should be in the format specified in the \acronym{PDF} reference
manual~\cite{PDFRef}, namely:

\begin{center}
\begin{tabular}{cp{0.66\textwidth}}
  |+|\meta{HH}|'|\meta{mm}|'| &
  \meta{HH} hours, \meta{mm} minutes later than Universal Time (i.e.,
  east of Greenwich, England) \\[\baselineskip]

  |-|\meta{HH}|'|\meta{mm}|'| &
  \meta{HH} hours, \meta{mm} minutes earlier than Universal Time (i.e.,
  west of Greenwich, England) \\[\baselineskip]

  |Z| &
  Universal Time (i.e., at the same longitude as Greenwich, England)
\end{tabular}
\end{center}

\noindent
For example, U.S. Central Time would be specified with |timezone=-06'00'|.
\end{describeopt}

\begin{describeopt}{zoom}
\begin{decl}
  |zoom=|\meta{boolean}
\end{decl}
Normally, when a reader magnifies or reduces the view of the
\acronym{PDF} document, the file annotation icons change size
proportionally with the text.  By setting \texttt{zoom=false}, the
icon size does not scale.
\end{describeopt}

\bigskip
The defaults for all of the options described above are summarized in
Table~\ref{tbl:opt-defaults}.

\begin{table}[htbp]
\centering
\edef\indexentry{options\levelchar default values\encapchar usage}
\expandafter\index\expandafter{\indexentry}
\begin{tabular}{@{}l@{\qquad}l@{}} \hline
  \multicolumn{1}{c}{Option\strut} &
  \multicolumn{1}{c}{Default setting} \\ \hline
  \indexedopt{appearance}  & |true| \\
  \indexedopt{author}      & \emph{none} \\
  \indexedopt{color}       & |1 0.9255 0.7765| \\
  \indexedopt{date}        & \emph{automatic} \\
  \indexedopt{description} & \emph{none} \\
  \indexedopt{icon}        & |PushPin| \\
  \indexedopt{mimetype}    & \emph{none} \\
  \indexedopt{print}       & |true| \\
  \indexedopt{timezone}    & \emph{none} \\
  \indexedopt{zoom}        & |true| \\ \hline
\end{tabular}
\caption{Default values for all options}
\label{tbl:opt-defaults}
\end{table}


\section{Caveats}
\label{sec:caveats}

Note that there are a few caveats you should be aware of:

\begin{enumerate}
  \item File attachments are a \acronym{PDF}~1.3 feature.  They will
  not be visible in \acronym{PDF} viewers that do support
  \acronym{PDF}~1.3.  (Version~4.0 of \adobeacrobat is the first
  version of that program which does.)

  \item Even some viewers that purportedly support \acronym{PDF}~1.3
  don't support file attachments.  As far as I can tell,
  \adobeacrobatreader (the free, view-only version of \adobeacrobat)
  doesn't seem to support \emph{any} annotations except text
  annotations.

  \item Even some viewers that do support \acronym{PDF}~1.3 and file
  attachments don't support them under all circumstances.  For
  instance, the Windows\smallreg\ version of \adobeacrobat, when
  functioning as a Web-browser plug-in, gives an error
  message\footnote{``Launching embedded files from within a browser
  environment is not allowed''.} when a file attachment icon is
  activated.

  \item Even in circumstances where file attachments are supported,
  the support may be flawed.  For example, the Windows\smallreg\
  version of \adobeacrobat changes a custom icon to the default icon
  when it's selected.
\end{enumerate}

\noindent
In addition, \pkgname{attachfile} requires \pdflatex{} version~14 or
later.  While there are many other ways to produce \acronym{PDF} files
from \latex{} source, \pkgname{attachfile}~\fileversion{} of supports
only \pdflatex, and only versions~14+.

Still, file attachments can be a useful way to pass additional
information along with a \acronym{PDF} file.  The \pkgname{attachfile}
package makes file annotations automatic and easy.


% Now we input ourself to get a fully documented source code listing.
\DocInput{attachfile.dtx}


\section{Future work}

The following are some avenues for future work on
\pkgname{attachfile}.  First, \pkgname{attachfile} supports only
\pdflatex\ for generating \acronym{PDF} files.  It would be nice if it
supported all the backends that \pkgname{hyperref} supports:
dvipdfm\index{dvipdfm}, dvips\index{dvips\encapchar usage} with
pdfmarks\index{pdfmarks\encapchar usage},
V\TeX\SortIndex{VTeX}{V\TeX\encapchar usage}, and so forth.  Along
those same lines, a ``draft'' package option would be a welcome
addition, for use when \acronym{PDF} is not the final output format.

Second, \acronym{PDF} supports platform-specific file attachments.
That is, a file attachment icon can represent a different file when
activated on Windows, Unix, or MacOS.  It might be nice for
\pkgname{attachfile} to support that feature.

Finally, I'd like to see \pkgname{attachfile} expand sometime to
support \emph{all} the various \acronym{PDF} annotations:
\pdfname{Sound}, \pdfname{Movie}, \pdfname{Stamp}, \pdfname{Ink},
\pdfname{Popup}, etc.

Of course, I make no promises that I'll ever do \emph{any} of the
above.  \pkgname{attachfile} was just something I wrote in my spare
time, and it's unlikely I'll be able to devote another large block of
time to enhance it.

\begin{thebibliography}{1}
\addcontentsline{toc}{section}{References}
\bibitem{PDFRef}
{Adobe Systems Incorporated}.
\newblock {\em PDF Reference}.
\newblock Addison-Wesley, 2nd edition, July~3, 2000.
\newblock Available from
  \url{http://partners.adobe.com/asn/developer/acrosdk/DOCS/PDFRef.pdf}.

\bibitem{Freed1996}
N.~Freed and N.~Borenstein.
\newblock {Multipurpose} {Internet} {Mail} {Extensions} {(MIME)} part two:
  Media types.
\newblock Request for Comments (RFC) 2046, Internet Engineering Task Force
  (IETF), Network Working Group, November 1996.
\newblock Available from \url{http://www.rfc-editor.org/rfc/rfc2046.txt}.

\bibitem{MediaTypes}
{Internet Assigned Numbers Authority}.
\newblock Media types.
\newblock Available from
  \url{http://www.isi.edu/in-notes/iana/assignments/media-types/media-types}.
\end{thebibliography}

\PrintIndex

% Attach my public key (not part of the attachfile distribution).
\InputIfFileExists{attachfile.sig}{}{}

\end{document}

%</driver>
% \fi
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% \changes{v1.00}{2001/01/03}{Initial version}
%
% \CheckSum{352}
%% \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         \~}
%%
%
% \StopEventually{}
%
% \DoNotIndex{\begingroup,\csname,\def,\edef,\else,\endcsname}
% \DoNotIndex{\endgroup,\fi,\ifnum,\ifx,\immediate,\protect,\relax}
% \DoNotIndex{\space,\the,\undefined,\xdef}
%
% \section{Implementation}
%
% This section contains the complete source code for \pkgname{attachfile}.
% Most users will not get much out of it, but it should be of use to
% those who need more precise documentation and those who want to extend
% the \pkgname{attachfile} package.
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%
% \subsection{Sanity checking}
%
% \pkgname{attachfile} \fileversion\ requires \pdflatex\ and at least
% version~14.  (Future versions of \pkgname{attachfile} may support
% dvipdfm\index{dvipdfm}, dvips\index{dvips\encapchar usage} with
% pdfmarks\index{pdfmarks\encapchar usage},
% V\TeX\SortIndex{VTeX}{V\TeX\encapchar usage}, etc.)  Also, \pdflatex\ must
% be in \acronym{PDF}-generating mode, not \acronym{DVI}-generating mode.
% So, to save the user some aggravation, we check for the correct backend
% right up front and give a nice error message if we don't have it.
%    \begin{macrocode}
\ifx\pdfoutput\undefined
  \PackageError{attachfile}{%
    You're not using pdfLaTeX.\MessageBreak
    This version of attachfile works _only_ with\MessageBreak
    pdfLaTeX%
  }{%
    The mechanisms attachfile uses to attach a file are
    pdfLaTeX\MessageBreak
    specific and will not work with any other form of
    LaTeX.\space\space\MessageBreak
    Future versions might, but that's assuming somebody\MessageBreak
    volunteers to work on it.\space\space  (Any takers?  :-) )%
  }
\fi

\ifnum\pdfoutput<1
  \PackageError{attachfile}{%
    PDF output is not enabled%
  }{%
    pdfLaTeX can generate either PDF or DVI files.\space\space
    However,\MessageBreak
    attachfile works only when pdfLaTeX is in
    PDF-generating\MessageBreak
    mode.\space\space  To make pdfLaTeX generate PDF, you should
    either\MessageBreak
    specify PDF as the default type in your pdfLaTeX\MessageBreak
    configuration file, or set \protect\pdfoutput=1\space
    in your document\MessageBreak
    (somewhere before the \protect\usepackage{attachfile}).%
  }
\fi

\ifnum\pdftexversion<14
  \PackageError{attachfile}{%
    Outdated version of pdfTeX.\MessageBreak
    Please upgrade to version 14 or later%
  }{%
    attachfile makes use of some pdfTeX features that were\MessageBreak
    introduced in pdfTeX version 14.\space\space
    You will need to install\MessageBreak
    a more recent version of pdfTeX+pdfLaTeX in order for\MessageBreak
    attachfile to work properly.
  }
\fi
%    \end{macrocode}
%
%
% \subsection{Preliminaries}
%
% We need to load \pkgname{hyperref} to get our hands on that great
% |\pdfstringdef| macro.  For now, we blindly pass all our package
% options directly to \pkgname{hyperref}.  In the future, it would
% be nice to do a |\setkeys{AtFi}| on our options.
%
%    \begin{macrocode}
\RequirePackageWithOptions{hyperref}
\RequirePackage[pdftex]{color}
%    \end{macrocode}
%
% \begin{macro}{\atfi@bogus@author}
% \begin{macro}{\atfi@authorstring}
% Store the name of the document's authors as they appear at the
% |\begin{document}|, because---for some unknown reason---|\maketitle|
% clears the |\@author| macro.  We initialize |\atfi@authorstring| to
% |\atfi@bogus@author| so we can give a user-friendly error message
% if the user tries to read the author's name before defining one.
% \label{page:define-authorstring}
%    \begin{macrocode}
\def\atfi@bogus@author{@@@@@}
\edef\atfi@authorstring{\atfi@bogus@author}
\AtBeginDocument{%
  \begingroup
    \def\and{/ }%
    \xdef\atfi@authorstring{\@author}%
  \endgroup%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
% \subsection{Adobe Acrobat icons}
%
% The following macros draw a representation of the various icons that
% \adobeacrobat{}\footnote{I got these graphics specifically from the
% Windows version of \adobeacrobat~4.0.} inserts to represent what the
% \acronym{PDF}~1.3 specifications refer to as ``\pdfname{Graph},''
% ``\pdfname{Paperclip},'' ``\pdfname{PushPin},'' and ``\pdfname{Tag}''.
% The |\parbox| dimensions are taken directly from the original graphics'
% bounding box.  However, I just eyeballed the |\raisebox| heights
% (intended to put shadows below the baseline).
%
% \begin{macro}{\atfi@acroGraph@data}
% Recreate \adobeacrobat's \pdfname{Graph} icon.
%    \begin{macrocode}
\newcommand{\atfi@acroGraph@data}{%
  q 0.5 g 1.1133 0 20.7202 18.2754 re f 1 g 0 G 0 i 0.5 w 4 M
  0.25 1.6453 20.145 17.7715 re B 0 g 2.7319 4.1367 3.9571
  13.8867 re f 8.7031 4.1367 3.9571 9.8867 re f 14.7471 4.1367
  3.9571 11.8867 re f \atfi@color@rgb\space rg 1.689 3.0938
  3.9571 13.8867 re f 7.6602 3.0938 3.9571 9.8867 re f 13.7041
  3.0938 3.9571 11.8867 re f Q
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\atfi@acroGraph}
% Draw |\atfi@acroGraph@data| in a box of the appropriate size.
%    \begin{macrocode}
\DeclareRobustCommand{\atfi@acroGraph}{%
  \raisebox{-1.5bp}{\parbox[b][20bp]{22bp}{%
    \rule{0pt}{0pt}\pdfliteral{\atfi@acroGraph@data}}%
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\atfi@acroPaperclip@data}
% Recreate \adobeacrobat's \pdfname{Paperclip} icon.
%    \begin{macrocode}
\newcommand{\atfi@acroPaperclip@data}{%
  q 0.75 G 0 i 2.5 w 1 J 4 M 1.9619 11.7559 m 1.9619 3.3037
  1.9619 2.5059 v 1.9619 1.707 4.0947 1.25 y 7.4141 1.25 l 9.4292
  1.8223 9.4292 3.3066 v 9.4292 4.79 9.4292 16.8945 y 9.7852
  18.1514 8.481 18.1514 v 7.1768 18.1514 5.1616 18.1514 y 3.8574
  17.9209 3.8574 16.8945 v 3.8574 15.8652 3.8574 6.6172 y 4.3325
  5.418 5.1025 5.418 v 5.8726 5.418 6.5845 5.418 y 7.6812 5.6455
  7.6812 6.4736 v 7.6812 7.3027 7.6812 11.5264 y S 0 G 1.2495
  12.4404 m 1.2495 3.9883 1.2495 3.1895 v 1.2495 2.3906 3.3833
  1.9326 y 6.7026 1.9326 l 8.7178 2.5068 8.7178 3.9902 v 8.7178
  5.4736 8.7178 17.5781 y 9.0732 18.834 7.769 18.834 v 6.4653
  18.834 4.4497 18.834 y 3.146 18.6055 3.146 17.5781 v 3.146
  16.5498 3.146 7.3018 y 3.6201 6.1016 4.3911 6.1016 v 5.1611
  6.1016 5.873 6.1016 y 6.9692 6.3301 6.9692 7.1572 v 6.9692
  7.9863 6.9692 12.21 y S \atfi@color@rgb\space RG 1 w
  1.2495 12.4404 m 1.2495 3.9883 1.2495 3.1895 v 1.2495 2.3906
  3.3833 1.9326 y 6.7026 1.9326 l 8.7178 2.5068 8.7178 3.9902 v
  8.7178 5.4736 8.7178 17.5781 y 9.0732 18.834 7.769 18.834 v
  6.4653 18.834 4.4497 18.834 y 3.146 18.6055 3.146 17.5781 v
  3.146 16.5498 3.146 7.3018 y 3.6201 6.1016 4.3911 6.1016 v
  5.1611 6.1016 5.873 6.1016 y 6.9692 6.3301 6.9692 7.1572 v
  6.9692 7.9863 6.9692 12.21 y S Q
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\atfi@acroPaperclip}
% Draw |\atfi@acroPaperclip@data| in a box of the appropriate size.
%    \begin{macrocode}
\DeclareRobustCommand{\atfi@acroPaperclip}{%
  \raisebox{-1.25bp}{\parbox[b][21bp]{12bp}{%
    \rule{0pt}{0pt}\pdfliteral{\atfi@acroPaperclip@data}}%
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\atfi@acroPushPin@data}
% Recreate \adobeacrobat's \pdfname{PushPin} icon.
%    \begin{macrocode}
\newcommand{\atfi@acroPushPin@data}{%
  q \atfi@color@rgb\space rg 0 G 1 w 1 6 m 11 6 l 11 13 l 12
  13 l 14 11 l 21 11 l 22 12 l 23 12 l 23 2 l 22 2 l 21 3 l 14 3
  l 12 1 l 11 1 l 11 6 l B 0.5 G 0 7 m 10 7 l 10 8 l 1 8 l S 1 G
  12 12 m 14 10 l 22 10 l 22 11 l S Q
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\atfi@acroPushPin}
% Draw |\atfi@acroPushPin@data| in a box of the appropriate size.
%    \begin{macrocode}
\DeclareRobustCommand{\atfi@acroPushPin}{%
  \raisebox{-1.25bp}{\parbox[b][14bp]{24bp}{%
    \rule{0pt}{0pt}\pdfliteral{\atfi@acroPushPin@data}}%
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\atfi@acroTag@data}
% Recreate \adobeacrobat's \pdfname{Tag} icon.
%    \begin{macrocode}
\newcommand{\atfi@acroTag@data}{%
  q 0.5 g 10.0542 14.9873 m 24.27 14.9873 l 25.252 14.0059 l
  25.252 1.1455 l 24.1064 0 l 9.9609 0 l 6.0327 6.0088 l 6.0327
  9.002 l 10.0542 14.9873 l 9.3994 9.376 m 8.5215 9.376 7.8096
  8.5596 7.8096 7.5527 c 7.8096 6.5449 8.5215 5.7285 9.3994
  5.7285 c 10.2778 5.7285 10.9897 6.5449 10.9897 7.5527 c 10.9897
  8.5596 10.2778 9.376 9.3994 9.376 c h f
  \atfi@color@rgb\space rg 0 G 0 i 0.5 w 4 M 1 j 8.5107
  16.5313 m 22.7266 16.5313 l 23.7085 15.5488 l 23.7085 2.6895 l
  22.563 1.543 l 8.4175 1.543 l 4.4893 7.5527 l 4.4893 10.5449 l
  8.5107 16.5313 l 7.856 10.9199 m 6.978 10.9199 6.2661 10.1035
  6.2661 9.0957 c 6.2661 8.0879 6.978 7.2715 7.856 7.2715 c
  8.7344 7.2715 9.4463 8.0879 9.4463 9.0957 c 9.4463 10.1035
  8.7344 10.9199 7.856 10.9199 c h B 1 w 12.3291 12.2656 m
  21.1206 12.2656 l S 12.3291 9.1797 m 21.1206 9.1797 l S 12.3291
  6.1875 m 21.1206 6.1875 l S 0 G 0.5 w 0 9.0488 m 6.2661 9.0957
  l S 1.4028 5.2148 m 1.4028 9.6094 l 1.6831 10.6387 2.4316
  10.6387 v 3.6475 10.6387 3.5542 9.0488 y S Q
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\atfi@acroTag}
% Draw |\atfi@acroTag@data| in a box of the appropriate size.
%    \begin{macrocode}
\DeclareRobustCommand{\atfi@acroTag}{%
  \raisebox{-1.6bp}{\parbox[b][17bp]{25bp}{%
    \rule{0pt}{0pt}\pdfliteral{\atfi@acroTag@data}}%
  }%
}
%    \end{macrocode}
% \end{macro}
%
%
% \subsection{Helper routines}
% \label{sec:helper-routines}
%
% \begin{macro}{\atfi@temp@string}
% \begin{macro}{\atfi@pdfstringdef}
% This is the same as |\pdfstringdef|, except that it \emph{locally}
% defines its argument.  For those of you who like analogies, |\gdef| is
% to |\pdfstringdef| as |\def| is to |\atfi@pdfstringdef|.
%    \begin{macrocode}
\def\atfi@temp@string{}
\DeclareRobustCommand{\atfi@pdfstringdef}[2]{%
  \pdfstringdef\atfi@temp@string{#2}%
  \edef#1{\atfi@temp@string}%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\theatfi@embedfileobj}
% \begin{macro}{\atfi@embedfile}
% Embed a file as a \acronym{PDF} \pdfname{EmbeddedFile} object and store its
% object number in |atfi@embedfileobj|.
%    \begin{macrocode}
\newcounter{atfi@embedfileobj}
\DeclareRobustCommand{\atfi@embedfile}[1]{%
  \immediate\pdfobj stream attr {
    /Type /EmbeddedFile
    \atfi@mimetype
  } file {#1}%
  \setcounter{atfi@embedfileobj}{\pdflastobj}%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\atfi@appearancewidth}
% \begin{macro}{\atfi@appearanceheight}
% \begin{macro}{\atfi@appearancedepth}
% \begin{macro}{\theatfi@appearanceobj}
% \begin{macro}{\atfi@appearancebox}
% Each \acronym{PDF} annotation can an associated ``appearance''.  In the
% \pkgname{attachfile} package, we store the appearance with the
% |\atfi@set@appearance| macro (below).  As a side effect,
% |\atfi@set@appearance| stores the dimensions of its argument in
% |\atfi@appearancewidth|, |\atfi@appearanceheight|, and
% |\atfi@appearanceddepth| so that, later, we can allocate an appropriate
% amount of space for the file attachment icon to fit within.
% |atfi@appearanceobj| is the object number of the appearance
% \pdfname{XObject}, and |\atfi@appearancebox| is a temporary storage
% location for the \tex\ box that will get converted to an \pdfname{XObject}.
%    \begin{macrocode}
\newlength{\atfi@appearancewidth}
\newlength{\atfi@appearanceheight}
\newlength{\atfi@appearancedepth}
\newcounter{atfi@appearanceobj}
\newsavebox{\atfi@appearancebox}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\atfi@set@appearance}
% Store the argument as a \acronym{PDF} \pdfname{XObject}, for later referral by the
% file annotation's appearance dictionary.  This serves two purposes:
% \begin{enumerate}
%   \item It enables a \tex\ box with arbitrary contents to serve as the file
%         attachment icon.
%   \item It enables (generally, older) \acronym{PDF} viewers which don't recognize the
%         icon name to still display something meaningful.
% \end{enumerate}
%    \begin{macrocode}
\DeclareRobustCommand{\atfi@set@appearance}[1]{%
  \savebox{\atfi@appearancebox}{#1}%
  \settowidth{\atfi@appearancewidth}{\usebox{\atfi@appearancebox}}%
  \settoheight{\atfi@appearanceheight}{\usebox{\atfi@appearancebox}}%
  \settodepth{\atfi@appearancedepth}{\usebox{\atfi@appearancebox}}%
  \immediate\pdfxform attr {
    /Subtype /Form
  } \atfi@appearancebox
  \setcounter{atfi@appearanceobj}{\pdflastxform}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\atfi@flags@to@int}
% \begin{macro}{\theatfi@flags}
% Convert all our flag options from booleans into a single integer
% (|atfi@flags|).
%    \begin{macrocode}
\newcounter{atfi@flags}
\DeclareRobustCommand{\atfi@flags@to@int}{%
  \setcounter{atfi@flags}{0}%
  \ifatfi@print
    \addtocounter{atfi@flags}{4}%
  \fi%
  \ifatfi@zoom
  \else
    \addtocounter{atfi@flags}{8}%
  \fi%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%

% \begin{macro}{\atfi@insert@file@annot}
% \begin{macro}{\atfi@file}
% Insert a \acronym{PDF} \pdfname{FileAttachment} annotation that refers to the
% object created by |\atfi@embedfile|.  \tex\ doesn't normally ``see''
% a |\pdfannot|, so we have to explicitly allocate space for it.
% |\atfi@insert@file@annot| takes one argument, the name of the file
% to attach.  This should be the same value that was passed to
% |\atfi@embedfile|.
%    \begin{macrocode}
\DeclareRobustCommand{\atfi@insert@file@annot}[1]{%
  \rule{0pt}{0pt}%
  \atfi@pdfstringdef\atfi@file{#1}%
  \ifatfi@appearance
    \def\atfi@appearance@dict{%
      /AP << /N \theatfi@appearanceobj\space 0 R >>%
    }%
  \fi%
  \pdfannot width \atfi@appearancewidth
            height \atfi@appearanceheight
            depth \atfi@appearancedepth {
    /Subtype /FileAttachment
    \atfi@icon\space
    \atfi@color\space
    \atfi@author\space
    \atfi@date\space
    \atfi@description\space
    \atfi@appearance@dict\space
    /F \theatfi@flags\space
    /FS <<
      /Type /Filespec
      /F (\atfi@file)
      /EF <<
        /F \theatfi@embedfileobj\space 0 R
      >>
    >>
  }%
%    \end{macrocode}
%
% Now, so \tex\ can budget space for the annotation, we insert some
% zero-width rules into the document.
%    \begin{macrocode}
  \rule{0pt}{\atfi@appearanceheight}%
  \rule[-\atfi@appearancedepth]{0pt}{\atfi@appearancedepth}%
  \rule{\atfi@appearancewidth}{0pt}%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
% \subsection{Annotation option processing}
% \label{sec:annot-options}
%
% We start by defining the various options that |\attachfile| accepts
% and their default values.
%
% \begin{macro}{\atfi@mimetype}
% \acronym{MIME} type of attached the file.
% For example, ``\texttt{text/plain}''
% would specify that the attachment is an ordinary text file.
%    \begin{macrocode}
\def\atfi@mimetype{}
\define@key{AtFi}{mimetype}{%
  \atfi@pdfstringdef\atfi@mimetype{#1}%
  \edef\atfi@mimetype{/Subtype (\atfi@mimetype)}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\atfi@icon}
% \begin{macro}{\atfi@icon@icon}
% Icon to represent the attachment.  This should be one of \pdfname{Graph},
% \pdfname{Paperclip}, \pdfname{PushPin} (the default), or \pdfname{Tag}.
% |\atfi@icon| is an attribute/value pair that gets inserted directly into
% the file attachment object.
% |\atfi@icon@icon| is only the icon name itself and
% is used to insert a static graphic that represents \adobeacrobat's
% rendition of a file attachment icon.
%    \begin{macrocode}
\define@key{AtFi}{icon}{%
  \def\atfi@icon{/Name /#1}%
  \def\atfi@icon@icon{#1}%
}
\setkeys{AtFi}{icon=PushPin}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\atfi@color}
% \begin{macro}{\atfi@color@rgb}
% Color of the attachment icon, specified as an \acronym{RGB} triplet.  For
% example, ``\texttt{0 0.3 0}'' would be a fairly dark green.
% |\atfi@color| is an attribute/value pair that gets inserted
% directly into the file attachment object.  It defaults to the empty
% string, which means the \acronym{PDF} viewer gets to choose what color
% the icon should be.  |\atfi@color@rgb| is only the \acronym{RGB} triplet
% itself and is used to insert a static graphic that represents
% \adobeacrobat's rendition of a file attachment icon.  It defaults to
% a beige color.
%    \begin{macrocode}
\define@key{AtFi}{color}{%
  \def\atfi@color{/C [#1]}%
  \def\atfi@color@rgb{#1}%
}
\setkeys{AtFi}{color=1 0.9255 0.7765}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\atfi@author}
% \begin{macro}{\atfi@named@author}
% The ``author'' of the annotation.  \adobeacrobat shows this when
% you right-click on the annotation and choose \menuname{Properties}.
% One complication is that the user might do an |\attachfilesetup|
% before the |\begin{document}|.  If this is the case, then our
% |\AtBeginDocument| command that sets |\atfi@authorstring|
% (page~\pageref{page:define-authorstring}) will not have been executed.
% Hence, we try to detect a pre-|\begin{document}| invocation by
% comparing |\atfi@named@author| to |\atfi@bogus@author|.  If the two
% are the same, then we set |\atfi@named@author| to |\@author| right
% away.  If the user hasn't yet set an author with |\author|, bad
% things will happen, and \pkgname{attachfile} will fail
% ungracefully.\quad |:-(|
%    \begin{macrocode}
\def\atfi@author{}
\define@key{AtFi}{author}[\atfi@authorstring]{%
  \edef\atfi@named@author{#1}%
  \ifx\atfi@named@author\atfi@bogus@author
    \begingroup
      \def\and{/ }%
      \xdef\atfi@temp@string{\@author}%
    \endgroup
    \edef\atfi@named@author{\atfi@temp@string}%
  \fi%
  \atfi@pdfstringdef\atfi@author{\atfi@named@author}%
  \edef\atfi@author{/T (\atfi@author)}%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\atfi@pad@ii}
% Pad a number to exactly two digits.  This is used by |\atfi@date| (below).
%    \begin{macrocode}
\def\atfi@pad@ii#1{%
  \ifnum#1>9
    \the#1%
  \else
    0\the#1%
  \fi%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\atfi@timezone}
% The timezone to attach to the file modification date.  It would
% be awfully nice if \tex\ had some way to produce this automatically.
% (Does it?)
%    \begin{macrocode}
\def\atfi@timezone{}
\define@key{AtFi}{timezone}{\def\atfi@timezone{#1}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\atfi@time}
% \begin{macro}{\c@atfi@hours}
% \begin{macro}{\theatfi@hours}
% \begin{macro}{\c@atfi@minutes}
% \begin{macro}{\atfi@date}
% The date the annotation was last modified.  It's unlikely you'd
% want to specify this explicitly in your \latex\ document, but
% if you want to, you can.  Seconds are hardwired to zero, and the
% time zone must be manually specified.  (I don't believe \tex\ makes either
% of those available.)  Note that |\time| is stored in
% |\atfi@time| in case the minutes roll over during the time calculations.
% I was too lazy to do the same for |\day|, |\month|, and |\year|, so
% don't process your \latex\ document at midnight if you want to get a
% correct datestamp.
%    \begin{macrocode}
\edef\atfi@time{\time}
\newcounter{atfi@hours}
\setcounter{atfi@hours}{\atfi@time/60}
\newcounter{atfi@minutes}
\setcounter{atfi@minutes}{\atfi@time-\theatfi@hours*60}
\def\atfi@date{%
  /M (D:\the\year%
      \atfi@pad@ii\month%
      \atfi@pad@ii\day%
      \atfi@pad@ii\c@atfi@hours%
      \atfi@pad@ii\c@atfi@minutes
      00%
      \atfi@timezone)%
}
\define@key{AtFi}{date}{%
  \atfi@pdfstringdef\atfi@date{#1}%
  \edef\atfi@date{/M (\atfi@date)}%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\atfi@description}
% The annotation's description.  \adobeacrobat shows this when
% you right-click on the annotation and choose \menuname{Properties}.
% It also shows it in the Annotations tab once you ``Rescan
% Document''.
%    \begin{macrocode}
\def\atfi@description{}
\define@key{AtFi}{description}{%
  \atfi@pdfstringdef\atfi@description{#1}%
  \edef\atfi@description{/Contents (\atfi@description)}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ifatfi@print}
% \begin{macro}{\atfi@printtrue}
% \begin{macro}{\atfi@printfalse}
% By default, file annotation icons print along with the rest of
% the document.  (In \adobeacrobat, that's the case if and only if the
% Annotations box is checked in the \Acrobatmenu{Print}{Print dialog}.)
% By setting \texttt{print=false}, the icons will not print.
%    \begin{macrocode}
\newif\ifatfi@print
\atfi@printtrue
\define@key{AtFi}{print}[true]{\csname atfi@print#1\endcsname}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\ifatfi@zoom}
% \begin{macro}{\atfi@zoomtrue}
% \begin{macro}{\atfi@zoomfalse}
% By default, file annotation icons zoom along with the rest of
% the document.  By setting \texttt{zoom=false}, the icons will
% remain at a constant size, regardless of magnification.
%    \begin{macrocode}
\newif\ifatfi@zoom
\atfi@zoomtrue
\define@key{AtFi}{zoom}[true]{\csname atfi@zoom#1\endcsname}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\ifatfi@appearance}
% \begin{macro}{\atfi@appearancetrue}
% \begin{macro}{\atfi@appearancefalse}
% \begin{macro}{\atfi@appearance@dict}
% The \pkgname{attachfile} package normally embeds an icon graphic in
% each file attachment annotation's appearance dictionary.  By setting
% \texttt{appearance=false}, no appearance dictionary will be added to a
% file attachment annotation; the \acronym{PDF} viewer will need to
% decide for itself how to display the icon.
%    \begin{macrocode}
\newif\ifatfi@appearance
\atfi@appearancetrue
\def\atfi@appearance@dict{}
\define@key{AtFi}{appearance}[true]{\csname atfi@appearance#1\endcsname}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
%
% \subsection{Author commands}
%
% The commands described in this section are those available to
% the user writing a \latex\ document.  If the macros seem too simple,
% it's because all the work is performed by the helper routines
% in Section~\ref{sec:helper-routines} and the option-processing
% routines in Section~\ref{sec:annot-options}.
%
% \begin{macro}{\attachfilesetup}
% Set default values for all the various annotation options.
%    \begin{macrocode}
\DeclareRobustCommand{\attachfilesetup}[1]{\setkeys{AtFi}{#1}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\attachfile}
% Given a filename and an optional set of attachment options, embed the
% corresponding file into the generated \acronym{PDF} file, and place an
% icon at the current location.
%    \begin{macrocode}
\DeclareRobustCommand{\attachfile}[2][]{%
  \begingroup
    \setkeys{AtFi}{#1}%
    \atfi@embedfile{#2}%
    \atfi@set@appearance{\csname atfi@acro\atfi@icon@icon\endcsname}%
    \atfi@flags@to@int%
    \atfi@insert@file@annot{#2}%
  \endgroup
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\textattachfile}
% \begin{macro}{\atfi@textcolor}
% Given a filename, some arbitrary text, and an optional set of
% attachment options, embed the corresponding file into the generated
% \acronym{PDF} file, and use the text as the icon.  We recycle the icon color
% for the text.  Note that the |\strut| is a bug workaround; I don't know
% whose fault this is, but the bottom point or so of the text seems to get
% cut off.  Weird.
%    \begin{macrocode}
\DeclareRobustCommand{\textattachfile}[3][]{%
  \begingroup
    \setkeys{AtFi}{#1}%
    \atfi@embedfile{#2}%
    \def\atfi@textcolor(##1 ##2 ##3)##4{%
      \textcolor[rgb]{##1,##2,##3}{##4}}%
    \atfi@set@appearance{%
      \expandafter\atfi@textcolor\expandafter%
      (\atfi@color@rgb){#3\strut}}%
    \atfi@flags@to@int%
    \atfi@insert@file@annot{#2}%
  \endgroup
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\noattachfile}
% Insert the same icon into the document that we would for an
% |\attachfile| call.  This is useful for writing documentation that
% instructs a user on how to deal with file attachments.
% |\noattachfile| is fairly simple; is just calls |\setkeys| in order to
% get the latest values of |\atfi@icon@icon| and |\atfi@color@rgb|,
% and then it defers to one of |\atfi@acroGraph|, |\atfi@acroPaperclip|,
% |\atfi@acroPushPin|, or |\atfi@acroTag|, which do the actual
% rendering work.
%    \begin{macrocode}
\DeclareRobustCommand{\noattachfile}[1][]{%
  \begingroup
    \setkeys{AtFi}{#1}%
    \csname atfi@acro\atfi@icon@icon\endcsname%
  \endgroup%
}
%    \end{macrocode}
% \end{macro}
%
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \Finale
\endinput