diff options
author | Karl Berry <karl@freefriends.org> | 2006-01-11 23:51:00 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2006-01-11 23:51:00 +0000 |
commit | 156d1f0d945ab439cdc5125d08fb60f1241fd361 (patch) | |
tree | 12ead88f1a5e78c55a3bbd4fe78ecba242b5f60e /Master/texmf-dist/source/latex/attachfile/attachfile.dtx | |
parent | b37eb83639b238f6daf87aa70c798eee3e0c9460 (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/texmf-dist/source/latex/attachfile/attachfile.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/attachfile/attachfile.dtx | 1593 |
1 files changed, 1593 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 |