summaryrefslogtreecommitdiff
path: root/Master
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-11 23:51:00 +0000
committerKarl Berry <karl@freefriends.org>2006-01-11 23:51:00 +0000
commit156d1f0d945ab439cdc5125d08fb60f1241fd361 (patch)
tree12ead88f1a5e78c55a3bbd4fe78ecba242b5f60e /Master
parentb37eb83639b238f6daf87aa70c798eee3e0c9460 (diff)
trunk/Master/texmf-dist/source/latex/attachfile
git-svn-id: svn://tug.org/texlive/trunk@147 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master')
-rw-r--r--Master/texmf-dist/source/latex/attachfile/attachfile.dtx1593
-rw-r--r--Master/texmf-dist/source/latex/attachfile/attachfile.ins55
2 files changed, 1648 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/attachfile/attachfile.dtx b/Master/texmf-dist/source/latex/attachfile/attachfile.dtx
new file mode 100644
index 00000000000..1f1dbb3ebbc
--- /dev/null
+++ b/Master/texmf-dist/source/latex/attachfile/attachfile.dtx
@@ -0,0 +1,1593 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2005 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.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
+%<*driver>
+\ProvidesFile{attachfile.dtx}
+%</driver>
+%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+%<package>\ProvidesPackage{attachfile}
+%<*package>
+ [2005/02/20 v1.2 PDF 1.3+ file attachment]
+%</package>
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage[hyperindex=false]{attachfile}
+\usepackage{color}
+\usepackage{xspace}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\begin{document}
+ \DocInput{attachfile.dtx}
+ \PrintChanges
+ \PrintIndex
+\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{378}
+%
+% \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}
+%
+% \GetFileInfo{attachfile.dtx}
+%
+% \DoNotIndex{\addtocounter,\begingroup,\catcode,\csname}
+% \DoNotIndex{\DeclareRobustCommand,\def,\do,\dospecials,\edef,\else}
+% \DoNotIndex{\endcsname,\endgroup,\expandafter,\fi,\hbox,\ifnum,\ifx}
+% \DoNotIndex{\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
+% \texttt{#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}%
+% \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}
+%
+% \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{^^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 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}
+%
+% 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}.
+%
+% \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}. 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}
+%
+% \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}.
+% \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 |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}. 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
+% |description=|\meta{text} sets the description field to \meta{text}.
+% \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 |subject=|\meta{text} sets the
+% subject 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{subject} & \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 \pkgname{attachfile} will not run unless the following \latex\
+% packages are installed: \pkgname{calc}, \pkgname{keyval},
+% \pkgname{color}, \pkgname{hyperref}, and \pkgname{ifpdf}.
+%
+% \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~0.14 or
+% later. 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+.
+%
+% \bigskip
+%
+% 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.
+% \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|.
+% \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
+% \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}
+% \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@icon\space
+ \atfi@color\space
+ \atfi@author\space
+ \atfi@date\space
+ \atfi@description\space
+ \atfi@subject\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}
+%
+% \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}
+%
+%
+% \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.
+% \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}
+% 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.
+% \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}
+% 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''.
+% ^^A
+% \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}{\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
diff --git a/Master/texmf-dist/source/latex/attachfile/attachfile.ins b/Master/texmf-dist/source/latex/attachfile/attachfile.ins
new file mode 100644
index 00000000000..a40fc6e39cf
--- /dev/null
+++ b/Master/texmf-dist/source/latex/attachfile/attachfile.ins
@@ -0,0 +1,55 @@
+%%
+%% This file will generate fast loadable files and documentation
+%% driver files from the doc files in this package when run through
+%% LaTeX or TeX.
+%%
+%% Copyright (C) 2005 Scott Pakin <scott+af@pakin.org>
+%% -------------------------------------------------------
+%%
+%% 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.
+%%
+%% --------------- start of docstrip commands ------------------
+%%
+\input docstrip
+
+\keepsilent
+
+\usedir{tex/latex/attachfile}
+
+\preamble
+
+This is a generated file.
+
+Copyright (C) 2005 Scott Pakin <scott+af@pakin.org>
+-------------------------------------------------------
+
+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.
+
+\endpreamble
+
+\generate{\file{attachfile.sty}{\from{attachfile.dtx}{package}}}
+
+\Msg{***********************************************************}
+\Msg{*}
+\Msg{* To finish the installation, you have to move}
+\Msg{* attachfile.sty into a directory searched by TeX.}
+\Msg{*}
+\Msg{* To produce the documentation, run attachfile.dtx}
+\Msg{* through pdfLaTeX.}
+\Msg{*}
+\Msg{* Happy TeXing!}
+\Msg{***********************************************************}
+
+\endbatchfile