path: root/Master/texmf-dist/source/latex/attachfile/attachfile.dtx

% \iffalse meta-comment
%
% Copyright (C) 2008 by Scott Pakin <scott+af@pakin.org>
% -------------------------------------------------------
%
% This file may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, either version 1.3c 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.3c or later is part of all distributions of LaTeX
% version 2006/05/20 or later.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{attachfile.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{attachfile}
%<*package>
    [2008/08/15 v1.3a PDF 1.3+ file attachment]
%</package>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{color}
\usepackage{xspace}
\usepackage[hyperindex=false,bookmarksopen=true]{attachfile}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{attachfile.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{474}
%
% \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         \~}
%
% \changes{v1.0}{2001/01/03}{Initial version}
% \changes{v1.1}{2005/01/04}{Completely restructured the \texttt{.dtx} file}
% \changes{v1.1a}{2005/02/18}{Corrected a few stupid bugs}
% \changes{v1.2}{2005/02/20}{Modified so as to enable filenames to
%   contain special characters, e.g., underscores}
% \changes{v1.3}{2007/01/15}{Incorporated Ross Moore's patches for
%   making \protect\pkgname{attachfile} robust to running
%   \protect\pkgname{hyperref} with
%   \protect\texttt{\protect\string\protect\Hy@unicodetrue} and for
%   supporting the \protect\pdfname{Created},
%   \protect\pdfname{Modified}, and \protect\pdfname{Size} keys in the
%   \protect\pdfname{EmbeddedFile}'s \protect\pdfname{Params}
%   dictionary}
%
% \GetFileInfo{attachfile.dtx}
%
% \DoNotIndex{\addtocounter,\begingroup,\bgroup,\catcode,\csname}
% \DoNotIndex{\DeclareRobustCommand,\def,\do,\dospecials,\edef,\egroup,\else}
% \DoNotIndex{\endcsname,\endgroup,\expandafter,\fi,\gdef,\hbox,\ifnum,\ifx}
% \DoNotIndex{\ifpdf,\immediate,\let,\makebox,\MessageBreak,\newcommand}
% \DoNotIndex{\newcounter,\newif,\newlength,\newsavebox,\parbox,\protect}
% \DoNotIndex{\raisebox,\relax,\rule,\savebox,\setbox,\setcounter}
% \DoNotIndex{\setkeys,\settodepth,\settoheight,\settowidth,\space,\strut}
% \DoNotIndex{\the,\undefined,\usebox,\wd,\xdef,\{,\}}
%
% \hypersetup{^^A
%   pdftitle={The attachfile package},
%   pdfauthor={Scott Pakin <scott+af@pakin.org>},
%   pdfsubject={LaTeX file attachment package},
%   pdfkeywords={attachments; annotations; PDF; LaTeX; package; automatic; files}
% }
%
% ^^A  Help prevent weird line breaks in URLs
% \def\UrlBreaks{}
% \def\UrlBigBreaks{\do/}
%
% ^^A  Define some logical styles.
% \newcommand{\menuname}[1]{\textit{#1}}
% \newcommand{\pkgname}[1]{^^A
%   \textsf{#1}\SortIndex{#1}{#1 (package)\encapchar usage}}
% \newcommand{\pdfname}[1]{^^A
%   \textsf{#1}\SortIndex{#1}{\textsf{#1}\encapchar usage}}
% \newcommand{\acronym}[1]{^^A
%   \textsc{\MakeLowercase{#1}}^^A
%   \SortIndex{#1}{\textsc{\MakeLowercase{#1}}\encapchar usage}^^A
% }
%
% ^^A  Define some indexable things.
% \newcommand{\bibtex}{^^A
%   \BibTeX\SortIndex{BibTeX}{\BibTeX\encapchar usage}}
% \newcommand{\pdflatex}{^^A
%   pdf\LaTeX\SortIndex{pdfLaTeX}{pdf\LaTeX\encapchar usage}}
% \newcommand{\latex}{^^A
%   \LaTeX\SortIndex{LaTeX}{\LaTeX\encapchar usage}}
% \newcommand{\tex}{^^A
%   \TeX\SortIndex{TeX}{\TeX\encapchar usage}}
%
% ^^A  Index one of attachtext's options.
% \newcommand{\prevopt}{}
% \newenvironment{describeopt}[1]{^^A
%   \gdef\prevopt{#1}^^A
%   \index{options\levelchar\prevopt
%          \actualchar\texttt{\prevopt}^^A
%          \encapchar(usage}%
%   \index{\prevopt
%          \actualchar\texttt{\prevopt} (option)^^A
%          \encapchar(usage}^^A
% }{^^A
%   \index{\prevopt%
%          \actualchar\texttt{\prevopt} (option)^^A
%          \encapchar)usage}^^A
%   \index{options\levelchar\prevopt
%          \actualchar\texttt{\prevopt}^^A
%          \encapchar)usage}^^A
% }
%
% ^^A  Output the name of an option, and also enter it into the index.
% \newcommand{\indexedopt}[1]{^^A
%   \gdef\prevopt{#1}^^A
%   \texttt{\prevopt}^^A
%   \index{options\levelchar\prevopt
%          \actualchar\texttt{\prevopt}^^A
%          \encapchar usage}^^A
%   \index{\prevopt
%          \actualchar\texttt{\prevopt} (option)^^A
%          \encapchar usage}^^A
% }
%
% ^^A  My nice, long variables names wreak havoc with a three-columned index.
% \setcounter{IndexColumns}{2}
%
% ^^A  Index a macro description.  This is copy&pasted from \SpecialUsageIndex,
% ^^A  but recast as an environment, so we can get beginning and ending page
% ^^A  numbers.
% \makeatletter
% \newcommand{\prevmacro}{}
% \newenvironment{describemacro}[1]{^^A
%   \gdef\prevmacro{#1}^^A
%   \@bsphack
%     {\let\special@index\index
%      \expandafter\SpecialIndex@\expandafter{\prevmacro}{\encapchar(usage}}^^A
%   \@esphack
% }{^^A
%   \@bsphack
%     {\let\special@index\index
%      \expandafter\SpecialIndex@\expandafter{\prevmacro}{\encapchar)usage}}^^A
%   \@esphack
% }
% \makeatother
%
% ^^A Make the index automatically add an entry to the table of contents.
% ^^A NOTE: Hardwired to a code-line index.  If you want to use \PageIndex
% ^^A       instead of \CodelineIndex, be sure to modify the following text
% ^^A       appropriately.
% \IndexPrologue{^^A
%   \section*{Index}^^A
%   \markboth{Index}{Index}^^A
%   \addcontentsline{toc}{section}{Index}^^A
%   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.
% }
%
% ^^A  Make legal-minded people happy.
% ^^A\newcommand{\smallreg}{\textsuperscript{\textregistered}}
% ^^A\newcommand{\smalltm}{\textsuperscript{TM}}
% \newcommand{\smallreg}{}
% \newcommand{\smalltm}{}
%
% ^^A Define some trademarked names.
% \newcommand{\adobe}{Adobe\smallreg\xspace}
% \newcommand{\adobeacrobat}{^^A
%   \adobe Acrobat\smallreg
%   \index{Adobe Acrobat\encapchar usage}^^A
%   \xspace^^A
% }
% \newcommand{\adobeacrobatreader}{^^A
%   \adobeacrobat Reader\smalltm
%   \index{Adobe Acrobat\levelchar Reader\encapchar usage}^^A
%   \xspace
% }
%
% ^^A  The following was swiped verbatim from ltxguide.cls:
%
% ^^A  A declaration of a command, in a box, set out into the margin.
% ^^A
% ^^A  Unfortunately, there is a bug with this command, which allows page
% ^^A  breaks to happen after a \begin{decl}[DATE]: it is a bug with TeX that
% ^^A  makes it very difficult to get page-breaks correct near marginals,
% ^^A  especially at the end of a paragraph.
% \DeleteShortVerb{\|}
% \newenvironment{decl}[1][]^^A
%     {\par\small\addvspace{4.5ex plus 1ex}^^A
%      \vskip -\parskip
%      \ifx\relax#1\relax
%         \def\@decl@date{}^^A
%      \else
%         \def\@decl@date{\NEWfeature{#1}}^^A
%      \fi
%      \noindent\hspace{-\leftmargini}^^A
%      \begin{tabular}{|l|}\hline\ignorespaces}^^A
%     {\\\hline\end{tabular}\nobreak\@decl@date\par\nobreak
%      \vspace{2.3ex}\vskip -\parskip}
% \MakeShortVerb{\|}
%
% ^^A  Because we have the fancy decl environment above, we don't need
% ^^A  macro names in the margins.
% \makeatletter
% \let\PrintDescribeMacro=\@gobble
% \makeatother
%
% ^^A  ----------------------------------------------------------------------
%
% \title{The \textsf{attachfile} package\thanks{This file
%        has version number \fileversion, last revised \filedate.}}
% \author{Scott Pakin \\ \texttt{scott+af@pakin.org}}
%
% \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}
%
%
% \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{^^A
%   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 resemble this:~}c@{)}}
%   Icon: &
%   \attachfile[size=1015,modified={D:20050104230918-07'00'}]{attachfile.bib} &
%   \noattachfile \\
%
%   \latex\ text: &
%   \textattachfile[size=1015,modified={D:20050104230918-07'00'}]{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 ``Save Embedded File to Disk\dots'' (or in older
% versions of \adobeacrobat, ``Extract File\dots'').  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{Usage}
%
% Load \pkgname{attachfile} by putting a |\usepackage{attachfile}| in
% your document's preamble.  \pkgname{attachfile} implicitly loads a
% variety of other packages.  Section~\ref{sec:caveats} presents the
% complete list.
%
% \pkgname{attachfile}~\fileversion{} does not have any of its own
% package options; any options that get passed to \pkgname{attachfile}
% are forwarded to \pkgname{hyperref}.  Because \pkgname{hyperref} works
% best when loaded as one of the last packages in the document the same
% holds true for \pkgname{attachfile}.
%
% \section{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}.  In
% particular, note that if the |print| option is set to |false| then
% |\noattachfile| will output empty space of the same size as the icon
% image.
% \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}{notextattachfile}
% \begin{decl}
%   |\notextattachfile| \oarg{options} \marg{text}
% \end{decl}
% \DescribeMacro{\noattachfile}
% Just as |\noattachfile| is a dummy version of |\attachfile|, so
% |\notextattachfile| is a dummy version of |\textattachfile|.  All
% |\notextattachfile| does is insert \meta{text} into the document
% according to \meta{options} (described in Section~\ref{sec:options}).
% In particular, note that if the |print| option is set to |false| then
% |\notextattachfile| will output empty space of the same size as
% \meta{text}.
% \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}
%
% \section{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.  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).
%
% \subsection{List of available options}
% \label{sec:option-list}
%
% 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\dots}.  By default, no author is listed
% but specifying \indexedopt{author}|=|\meta{name} sets the author field to
% \meta{name}.
% \end{describeopt}
%
% \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 \indexedopt{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}{created}
% \begin{decl}
%   |created=|\meta{PDF date}
% \end{decl}
% Virtually all filesystems associate a file-creation timestamp with
% each file.  Although \tex\ provides no portable mechanism for
% determining the date and time a file was created the
% \indexedopt{created} option lets you manually specify these
% parameters for the reader's benefit.  See Section~\ref{sec:date-usage}
% for more information about \pkgname{attachfile} dates.
% \end{describeopt}
%
% \begin{describeopt}{date}
% \begin{decl}
%   |date=|\meta{PDF date}
% \end{decl}
% Each annotation in a \acronym{PDF} file can have a timestamp
% indicating when the annotation was last modified.
% \pkgname{attachfile} automatically adds a timestamp to file attachment
% annotations.  It uses the date and time at which \latex\ started
% processing your job (to minute precision because that's what \tex's
% \texttt{\string\time} command provides) and includes the timezone, if
% specified (using the \indexedopt{timezone} option,
% p.~\pageref{page:timezone}).  Although it's unlikely you'll need to
% use it, the \indexedopt{date} option lets you override the
% annotation's modification date and time with a date and time of your
% choice.  See Section~\ref{sec:date-usage} for more information
% about \pkgname{attachfile} dates.
% \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\dots}.  Also, in later versions of \adobeacrobat,
% the description field shows up as a tool~tip when the user mouses over
% the attachment.  By default, no description is included, but
% specifying \indexedopt{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}{modified}
% \begin{decl}
%   |modified=|\meta{PDF date}
% \end{decl}
% Virtually all filesystems associate a last-modification timestamp with
% each file.  Although \tex\ provides no portable mechanism for
% determining the date and time a file was last modified the
% \indexedopt{modified} option lets you manually specify these
% parameters for the reader's benefit.  See Section~\ref{sec:date-usage}
% for more information about \pkgname{attachfile} dates.
% \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}{size}
% \begin{decl}
%   |size=|\meta{integer}
% \end{decl}
% The \indexedopt{size} option tells the \acronym{PDF} viewer that the
% attached file is \meta{integer} bytes long.  \adobeacrobat displays
% this size under the ``Size'' column in the
% \Acrobatmenu{ShowHideAttachments}{Attachments pane} but does not
% otherwise seem to use the \meta{integer} value.
% \end{describeopt}
%
% \begin{describeopt}{subject}
% \begin{decl}
%   |subject=|\meta{text}
% \end{decl}
% The metadata associated with a file attachment annotation can include
% a brief comment about the subject of the attachment.  In
% \adobeacrobat, this information is shown when one right-clicks on the
% file attachment icon and selects \menuname{Properties}.  By default,
% no subject is included, but specifying \indexedopt{subject}|=|\meta{text}
% sets the subject field to \meta{text}.
% \end{describeopt}
%
% \begin{describeopt}{timezone}
% \label{page: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 \indexedopt{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[\textsection3.8.3, ``Dates'']{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
% \indexedopt{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{created}     & \emph{none} \\
%   \indexedopt{date}        & \emph{automatic} \\
%   \indexedopt{description} & \emph{none} \\
%   \indexedopt{icon}        & |PushPin| \\
%   \indexedopt{mimetype}    & \emph{none} \\
%   \indexedopt{modified}    & \emph{none} \\
%   \indexedopt{print}       & |true| \\
%   \indexedopt{size}        & \emph{none} \\
%   \indexedopt{subject}     & \emph{none} \\
%   \indexedopt{timezone}    & \emph{none} \\
%   \indexedopt{zoom}        & |true| \\ \hline
% \end{tabular}
% \caption{Default values for all options}
% \label{tbl:opt-defaults}
% \end{table}
%
% \subsection{Date usage}
% \label{sec:date-usage}
%
% Section~\ref{sec:option-list} presents three timestamp-related
% options: \indexedopt{date}, \indexedopt{created}, and
% \indexedopt{modified}.  The \indexedopt{date} option specifies the
% annotation date---the date and time the given file was attached to the
% \acronym{PDF} file---and should usually be left unspecified.  (It
% defaults to the date and time at which \latex\ started processing your
% job.)  The annotation date is displayed in \adobeacrobat by
% right-clicking on the annotation, choosing \menuname{Properties\dots}\
% from the menu, and clicking on the \menuname{General} tab.  The
% \indexedopt{modified} option specifies the file's modification
% date---the date and time the given file was last modified.
% \adobeacrobat displays the modification date under the ``Modified''
% column in the \Acrobatmenu{ShowHideAttachments}{Attachments pane} but
% does not otherwise appear to use the modification date.  Finally, the
% \indexedopt{created} option specifies the file's creation date---the
% date and time the given file was first written to disk.  As of this
% writing, \adobeacrobat does not appear to use or even display the
% creation date; perhaps future versions or other \acronym{PDF} viewers
% will.
%
% Dates should be specified in the form
% ``|D:|\textit{YYYYMMDDHHmmSSOHH}|'|\textit{mm}|'|'' as described in
% the \acronym{PDF} reference manual~\cite[\textsection3.8.3,
% ``Dates'']{PDFRef}.  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[Table~8.11, ``Entries common to all annotation
% dictionaries'']{PDFRef}, \adobeacrobat will ignore any timestamp that
% is not in the recommended format and will instead show ``00/00/00
% 00:00:00'' for the annotation date or ``Unknown'' for the modification
% date.
%
%
% \section{Caveats}
% \label{sec:caveats}
%
% Note that there are a few caveats you should be aware of:
%
% \begin{enumerate}
%   \item \pkgname{attachfile} requires \pdflatex{} version~0.14 or
%   later.  (Version~0.14 was released circa~1999 so it's unlikely that
%   you're running an older version than that.)  While there are many
%   other ways to produce \acronym{PDF} files from \latex{} source,
%   \pkgname{attachfile}~\fileversion{} supports only \pdflatex, and
%   only versions~0.14+.
%
%   \item \pkgname{attachfile} will not run unless the following \latex\
%   packages are installed: \pkgname{calc}, \pkgname{keyval},
%   \pkgname{color}, \pkgname{hyperref}, and \pkgname{ifpdf}.  (Most
%   \tex\ distributions include all of these.)
%
%   \item File attachments are a \acronym{PDF}~1.3 feature.  They will
%   not be visible in \acronym{PDF} viewers that don't 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, very old
%   versions of \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, some  Windows\smallreg\ versions of \adobeacrobat, when
%   functioning as a Web-browser plug-in, give 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, some Windows\smallreg\
%   versions of \adobeacrobat change a custom icon to the default icon
%   when it's selected.
%
%   Also, while file-attachment icons with custom appearances printed
%   fine in older versions of \adobeacrobat, \adobe introduced a bug
%   circa \adobeacrobat~6.0 that prevents \pkgname{attachfile}'s icons
%   from printing.  Unfortunately, because \adobeacrobat lacks
%   \pkgname{attachfile}'s ability to create custom appearances for
%   file-attachment icons it's unlikely that this bug will ever get
%   fixed.  Nevertheless, please consider sending a bug report to \adobe
%   to let them know that you'd like to be able to print file-attachment
%   icons with custom appearances.
% \end{enumerate}
%
% Even given all of those caveats, 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.
%
%
% \StopEventually{^^A
%   \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\SortIndex{dvipdfm}{dvipdfm\encapchar usage},
%   dvips\SortIndex{dvips}{dvips\encapchar usage} with
%   pdfmarks\SortIndex{pdfmarks}{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 Version~1.6}.
%   \newblock Adobe Press, fifth edition, December~3, 2004.
%   \newblock ISBN~\mbox{0321304748}. Available from
%     \url{http://partners.adobe.com/public/developer/en/pdf/PDFReference16.pdf}.
%
%   \bibitem{Freed1996}
%   N.~Freed and N.~Borenstein.
%   \newblock {M}ultipurpose {I}nternet {M}ail {E}xtensions {(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 {MIME} media types.
%   \newblock Available from \url{http://www.iana.org/assignments/media-types/}.
%   \end{thebibliography}
% }
%
%
% \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~0.14, although \pkgname{attachfile} no longer checks for
% that).  (Future versions of \pkgname{attachfile} may support
% dvipdfm\SortIndex{dvipdfm}{dvipdfm\encapchar usage},
% dvips\SortIndex{dvips}{dvips\encapchar usage} with
% pdfmarks\SortIndex{pdfmarks}{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 warning if all is not well.  Later,
% in Section~\ref{sec:dummy-commands}, we replace all of the core
% \pkgname{attachfile} macros with dummy versions so \latex\ can at
% least run to completion.
% \changes{v1.3a}{2008/08/15}{Corrected the formatting of the ``not
%   \string\pdflatex'' warning message}
%    \begin{macrocode}
\RequirePackage{ifpdf}
\ifpdf
\else
  \PackageWarningNoLine{attachfile}{%
    attachfile works _only_ with pdfLaTeX and _only_ in\MessageBreak
    PDF-generating mode.  For this run, placeholders will\MessageBreak
    be substituted for all attachfile commands.%
  }
\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}
\RequirePackage{keyval}
\RequirePackage{calc}
\RequirePackage{color}
\RequirePackageWithOptions{hyperref}
%    \end{macrocode}
%
%
% \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,
% |\atfi@pdfstringdef| is to |\def| as |\pdfstringdef| is to |\gdef|.
%    \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|.
% \changes{v1.3}{2007/01/15}{Included a \protect\pdfname{Params}
%   dictionary describing the file's date, modification date, and size}
%    \begin{macrocode}
\newcounter{atfi@embedfileobj}
\DeclareRobustCommand{\atfi@embedfile}[1]{%
  \immediate\pdfobj stream attr {
    /Type /EmbeddedFile
    \atfi@mimetype\space
    \atfi@dlsize\space
    /Params <<
      \atfi@credate\space
      \atfi@moddate\space
      \atfi@size\space
    >>
  } 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|.
% \changes{v1.3}{2007/01/15}{Made robust to running
%   \protect\pkgname{hyperref} with
%   \protect\texttt{\protect\string\protect\Hy@unicodetrue}}
%    \begin{macrocode}
\DeclareRobustCommand{\atfi@insert@file@annot}[1]{%
  \rule{0pt}{0pt}%
  \bgroup\Hy@unicodefalse
    \atfi@pdfstringdef\atfi@file{#1}%
    \edef\next{\egroup
      \def\noexpand\atfi@file{\atfi@file}%
    }\next
  \ifatfi@appearance
%    \end{macrocode}
% We currently use the same appearance for \textsf{N}ormal,
% \textsf{R}ollover, and \textsf{D}own, although future versions of
% \pkgname{attachfile} may provide support for different appearances.
% Although the PDF \acronym{PDF} specification claims that \textsf{R}
% and \textsf{D} appearances default to the \textsf{N} appearance,
% experience dictates otherwise.  Hence, we explicitly specify all three
% appearances.
% ^^A
% \changes{v1.1}{2005/01/04}{Added explicit \protect\textsf{R}ollover
%   and \protect\textsf{D}own appearances to work around browser bugs}
% \changes{v1.3}{2007/01/15}{Modified to include the modification date
%   in the \protect\pdfname{FileAttachment} dictionary}
%    \begin{macrocode}
    \def\atfi@appearance@dict{%
      /AP <<
        /N \theatfi@appearanceobj\space 0 R
        /R \theatfi@appearanceobj\space 0 R
        /D \theatfi@appearanceobj\space 0 R
      >>%
    }%
  \fi%
  \pdfannot width \atfi@appearancewidth
            height \atfi@appearanceheight
            depth \atfi@appearancedepth {
    /Subtype /FileAttachment
    \atfi@appearance@dict\space
    \atfi@author\space
    \atfi@color\space
    \atfi@date\space
    \atfi@description\space
    \atfi@icon\space
    \atfi@moddate\space
    \atfi@subject\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}
%
% \begin{macro}{\atfi@attachfile}
% This macro does all the work of the |\attachfile| author command.
% |\attachfile| began a group in which most special characters are set
% to category code ``other''.  |\atfi@attachfile| reads the filename
% within this group, embeds the corresponding file into the generated
% \acronym{PDF} file, and places an icon at the current location.  Then,
% it ends the group, thereby restoring the original category codes.
%    \begin{macrocode}
\def\atfi@attachfile#1#2{%
    \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}{\atfi@textattachfile}
% All this macro does is evaluate its second argument (a filename)
% within the group begun by |\textattachfile| then pass control to
% |\atfi@textattachfile@i|, which does all the work.
% |\atfi@textattachfile| is needed to force the filename to be evaluated
% while special characters are set to use category code ``other''.
%    \begin{macrocode}
\def\atfi@textattachfile#1#2{%
    \endgroup
    \atfi@textattachfile@i{#1}{#2}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\atfi@textattachfile@i}
% \begin{macro}{\atfi@textcolor}
% This macro does all the work of the |\textattachfile| author command.
% 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}
\def\atfi@textattachfile@i#1#2#3{%
    \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}{\atfi@pdf@slash}
% The \acronym{PDF} specification dictates that \acronym{MIME} types be
% specified not as strings (e.g.,~``|(Hello)|'') but rather as
% \acronym{PDF} names (e.g.,~``|/Hello|'').  The catch is that the
% forward slash---required in all \acronym{MIME} types---cannot be part
% of a \acronym{PDF} name.  The solution is to replace the
% \acronym{MIME} ``|/|'' with the hexadecimal sequence ``|#2f|''.
% Unfortunately, \pdflatex\ replaces ``|#|'' with ``|##|'' in a
% |\pdfobj| but leaves ``|\#|'' as is.  The solution is to play some
% games with \tex\ to define |\atfi@pdf@slash| as a ``|#2f|'' sequence
% that can used within |\pdfobj|.
%    \begin{macrocode}
\bgroup
  \lccode`\@=`\#
  \lowercase{\gdef\atfi@pdf@slash{@2f}}
\egroup
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\atfi@split@mimetype}
% \begin{macro}{\atfi@mime@type}
% \begin{macro}{\atfi@mime@subtype}
% Split a \acronym{MIME} type (e.g.,~``\texttt{image\slash jpeg}'') into
% a type, |\atfi@mime@type| (e.g.,~``|image|''), and a subtype,
% |\atfi@mime@subtype| (e.g.,~``|jpeg|'').
%    \begin{macrocode}
\def\atfi@split@mimetype#1/#2/{%
  \def\atfi@mime@type{#1}%
  \def\atfi@mime@subtype{#2}%
}
%    \end{macrocode}
% \end{macro}
% \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}
% Declare the \acronym{MIME} type of the attached file.
% For example, ``\texttt{text/plain}''
% would specify that the attachment is an ordinary text file.
% \changes{v1.2a}{2006/03/28}{Changed the \string\acronym{MIME}
%   \string\pdfname{Subtype} from a string to a name}
%    \begin{macrocode}
\def\atfi@mimetype{}
\define@key{AtFi}{mimetype}{%
  \atfi@pdfstringdef\atfi@mimetype{#1}%
  \atfi@split@mimetype#1/%
  \edef\atfi@mimetype{%
    /Subtype /\atfi@mime@type\atfi@pdf@slash\atfi@mime@subtype
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\atfi@icon}
% \begin{macro}{\atfi@icon@icon}
% Specify an 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}
% Specify the color of the attachment icon 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}
% Specify the author of the annotation.  \adobeacrobat shows this when
% you right-click on the annotation and choose \menuname{Properties}.
%    \begin{macrocode}
\def\atfi@author{}
\define@key{AtFi}{author}[]{%
  \edef\atfi@author{/T (#1)}%
}
%    \end{macrocode}
% \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}
% Specify 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.
% \changes{v1.3}{2007/01/15}{Made robust to running
%   \protect\pkgname{hyperref} with
%   \protect\texttt{\protect\string\protect\Hy@unicodetrue}}
%    \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}{%
  \bgroup \Hy@unicodefalse
    \atfi@pdfstringdef\atfi@date{#1}%
    \edef\next{\egroup
      \def\noexpand\atfi@date{/M (\atfi@date)}%
    }\next
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\atfi@description}
% Store 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}{\atfi@subject}
% Store the annotation's subject.  \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''.
% \changes{v1.1}{2005/01/04}{Added support for specifying the subject of
%   an annotation}
%    \begin{macrocode}
\def\atfi@subject{}
\define@key{AtFi}{subject}{%
  \atfi@pdfstringdef\atfi@subject{#1}%
  \edef\atfi@subject{/Subj (\atfi@subject)}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\atfi@credate}
% Store the annotation's creation date.  \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''.
% Note that creation date is a \acronym{PDF}~1.5 feature.
% \changes{v1.3}{2007/01/15}{Added support for specifying the creation
%   date of an annotation}
%    \begin{macrocode}
\def\atfi@credate{}
\define@key{AtFi}{created}{%
  \bgroup \Hy@unicodefalse
    \atfi@pdfstringdef\atfi@credate{#1}%
    \edef\next{\egroup
      \def\noexpand\atfi@credate{/CreationDate (\atfi@credate)}%
    }\next
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\atfi@moddate}
% Store the annotation's modification date.  \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''.
% Note that modification date is a \acronym{PDF}~1.5 feature.
% \changes{v1.3}{2007/01/15}{Added support for specifying the modification
%   date of an annotation}
%    \begin{macrocode}
\def\atfi@moddate{}
\define@key{AtFi}{modified}{%
  \bgroup \Hy@unicodefalse
    \atfi@pdfstringdef\atfi@moddate{#1}%
    \edef\next{\egroup
      \def\noexpand\atfi@moddate{/ModDate (\atfi@moddate)}%
    }\next
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\atfi@size}
% \begin{macro}{\atfi@dlsize}
% Store the annotation's file size.  \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''.
% Note that file size is a \acronym{PDF}~1.5 feature.
% \changes{v1.3}{2007/01/15}{Added support for specifying the file size
%   of an annotation}
%    \begin{macrocode}
\def\atfi@size{}
\def\atfi@dlsize{}
\define@key{AtFi}{size}{%
  \bgroup \Hy@unicodefalse
    \atfi@pdfstringdef\atfi@size{#1}%
    \edef\next{\egroup
      \def\noexpand\atfi@size{/Size \atfi@size}%
      \def\noexpand\atfi@dlsize{/DL \atfi@size}%
    }\next
}
%    \end{macrocode}
% \end{macro}
% \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.  The real work is performed by
% |\atfi@attachfile|.  |\attachfile| merely sets up the category codes
% in such a way as to allow filenames to contain special characters such
% as underscores.
%    \begin{macrocode}
\DeclareRobustCommand{\attachfile}[1][]{%
  \begingroup
    \let\do\@makeother
    \dospecials
    \catcode`\{=1\relax
    \catcode`\}=2\relax
    \atfi@attachfile{#1}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\textattachfile}
% 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.  After setting up
% the category codes to use for processing the filename,
% |\textattachfile| passes to control to |\atfi@textattachfile|, which
% resets the category codes, and then to |\atfi@textattachfile@i|, which
% does all the work.  We define two groups: one for keeping the
% attachment options local and one for temporarily altering category
% codes.
%    \begin{macrocode}
\DeclareRobustCommand{\textattachfile}[1][]{%
  \begingroup
    \begingroup
      \let\do\@makeother
      \dospecials
      \catcode`\{=1\relax
      \catcode`\}=2\relax
      \atfi@textattachfile{#1}%
}
%    \end{macrocode}
% \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.
% ^^A
% \changes{v1.1}{2005/01/04}{Modified to leave space on the page when
%   \protect\texttt{print\protect\actualchar false} is passed as an option}
%    \begin{macrocode}
\DeclareRobustCommand{\noattachfile}[1][]{%
  \begingroup
    \setkeys{AtFi}{#1}%
    \ifatfi@print
      \csname atfi@acro\atfi@icon@icon\endcsname
    \else
      \setbox0=\hbox{\csname atfi@acro\atfi@icon@icon\endcsname}%
      \makebox[\wd0]{}%
    \fi
  \endgroup
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\notextattachfile}
% Insert the same text into the document that we would for a
% |\textattachfile| call.  This is useful for writing documentation that
% instructs a user on how to deal with file attachments.
% \changes{v1.1}{2005/01/04}{Created this function}
%    \begin{macrocode}
\DeclareRobustCommand{\notextattachfile}[2][]{%
  \begingroup
    \setkeys{AtFi}{#1}%
    \ifatfi@print
      \def\atfi@textcolor(##1 ##2 ##3)##4{%
        \textcolor[rgb]{##1,##2,##3}{##4}}%
      \expandafter\atfi@textcolor\expandafter
        (\atfi@color@rgb){#2\strut}%
    \else
      \setbox0=\hbox{#2\strut}%
      \makebox[\wd0]{}%
    \fi
  \endgroup
}
%    \end{macrocode}
% \end{macro}
%
%
% \subsection{Dummy commands}
% \label{sec:dummy-commands}
%
% If the author is not use \pdflatex\ or not using it in
% \acronym{PDF}-generating mode, we replace the core
% \pkgname{attachfile} commands with dummy versions so \latex\ can at
% least run to completion.
% ^^A
% \changes{v1.1}{2005/01/04}{Wrote dummy versions of all the core macros
%   to use in the absence of \protect\pdflatex\ running in
%   \protect\acronym{PDF}-generating mode.}
%
%    \begin{macrocode}
\ifpdf
\else
%    \end{macrocode}
%
% \begin{macro}{\atfi@dummy@pushpin}
% Define an empty space of approximately the same size as
% |\atfi@acroPushPin|.
%    \begin{macrocode}
  \def\atfi@dummy@pushpin{%
    \raisebox{-1.25bp}{\parbox[b][14bp]{24bp}{}}%
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\textattachfile}
% Define a dummy |\textattachfile| in terms of |\notextattachfile|.
%    \begin{macrocode}
  \DeclareRobustCommand{\textattachfile}[3][]{%
    \notextattachfile[#1]{#3}%
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\noattachfile}
% Define a dummy |\noattachfile| in terms of |\notextattachfile|.
%    \begin{macrocode}
  \DeclareRobustCommand{\noattachfile}[1][]{%
    \notextattachfile[#1]{\atfi@dummy@pushpin}%
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\attachfile}
% Define a dummy |\attachfile| in terms of the dummy |\noattachfile|.
%    \begin{macrocode}
  \DeclareRobustCommand{\attachfile}[2][]{%
    \noattachfile[#1]%
  }
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
\fi
%    \end{macrocode}
%
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \Finale
\endinput