| 1 |
% \iffalse meta-comment |
| 2 |
% |
| 3 |
% Copyright (C) 2016 by Scott Pakin <[email protected]> |
| 4 |
% ------------------------------------------------------- |
| 5 |
% |
| 6 |
% This file may be distributed and/or modified under the conditions of |
| 7 |
% the LaTeX Project Public License, either version 1.3c of this license |
| 8 |
% or (at your option) any later version. The latest version of this |
| 9 |
% license is in: |
| 10 |
% |
| 11 |
% http://www.latex-project.org/lppl.txt |
| 12 |
% |
| 13 |
% and version 1.3c or later is part of all distributions of LaTeX |
| 14 |
% version 2006/05/20 or later. |
| 15 |
% |
| 16 |
% \fi |
| 17 |
% |
| 18 |
% \iffalse |
| 19 |
%<*driver> |
| 20 |
\ProvidesFile{attachfile.dtx} |
| 21 |
%</driver> |
| 22 |
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01] |
| 23 |
%<package>\ProvidesPackage{attachfile} |
| 24 |
%<*package> |
| 25 |
[2016/09/18 v1.9 PDF 1.3+ file attachment] |
| 26 |
%</package> |
| 27 |
% |
| 28 |
%<*driver> |
| 29 |
\documentclass{ltxdoc} |
| 30 |
\usepackage{color} |
| 31 |
\usepackage{xspace} |
| 32 |
\usepackage{needspace} |
| 33 |
\usepackage{tocbibind} |
| 34 |
\usepackage[hyperindex=false,bookmarksopen]{attachfile} |
| 35 |
\usepackage{hyperxmp} |
| 36 |
\EnableCrossrefs |
| 37 |
\CodelineIndex |
| 38 |
\RecordChanges |
| 39 |
\begin{document} |
| 40 |
\DocInput{attachfile.dtx} |
| 41 |
\Needspace{10\baselineskip} |
| 42 |
\phantomsection\addcontentsline{toc}{section}{Change History} |
| 43 |
\PrintChanges |
| 44 |
\PrintIndex |
| 45 |
\end{document} |
| 46 |
%</driver> |
| 47 |
% \fi |
| 48 |
% |
| 49 |
% \changes{v1.5a}{2010/09/14}{Modified the package to generate |
| 50 |
% \texttt{attachfile.bib} automatically from the \texttt{.dtx} |
| 51 |
% and \texttt{.ins} files} |
| 52 |
% \iffalse |
| 53 |
%<*attachment> |
| 54 |
@Book{PDFRef, |
| 55 |
author = {{Adobe Systems Incorporated}}, |
| 56 |
title = {{PDF} Reference Version~1.6}, |
| 57 |
publisher = {Adobe Press}, |
| 58 |
year = 2004, |
| 59 |
key = {PDF}, |
| 60 |
edition = {Fifth}, |
| 61 |
month = dec # {~3,}, |
| 62 |
note = {ISBN~\mbox{0321304748}. Available from \url{http://partners.adobe.com/public/developer/en/pdf/PDFReference16.pdf}} |
| 63 |
} |
| 64 |
|
| 65 |
@Unpublished{MediaTypes, |
| 66 |
author = {{Internet Assigned Numbers Authority}}, |
| 67 |
title = {{MIME} Media Types}, |
| 68 |
note = {Available from \url{http://www.iana.org/assignments/media-types/}}, |
| 69 |
key = {IANA} |
| 70 |
} |
| 71 |
|
| 72 |
@TechReport{Freed1996, |
| 73 |
author = {N. Freed and N. Borenstein}, |
| 74 |
title = {{M}ultipurpose {I}nternet {M}ail {E}xtensions {(MIME)} |
| 75 |
Part Two: Media Types}, |
| 76 |
institution = {Internet Engineering Task Force (IETF), |
| 77 |
Network Working Group}, |
| 78 |
year = 1996, |
| 79 |
type = {Request for Comments (RFC)}, |
| 80 |
number = 2046, |
| 81 |
month = nov, |
| 82 |
note = {Available from |
| 83 |
\url{http://www.rfc-editor.org/rfc/rfc2046.txt}} |
| 84 |
} |
| 85 |
%</attachment> |
| 86 |
% \fi |
| 87 |
% |
| 88 |
% \iffalse |
| 89 |
%<*package> |
| 90 |
% \fi |
| 91 |
% |
| 92 |
% \CheckSum{521} |
| 93 |
% |
| 94 |
% \CharacterTable |
| 95 |
% {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 |
| 96 |
% 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 |
| 97 |
% Digits \0\1\2\3\4\5\6\7\8\9 |
| 98 |
% Exclamation \! Double quote \" Hash (number) \# |
| 99 |
% Dollar \$ Percent \% Ampersand \& |
| 100 |
% Acute accent \' Left paren \( Right paren \) |
| 101 |
% Asterisk \* Plus \+ Comma \, |
| 102 |
% Minus \- Point \. Solidus \/ |
| 103 |
% Colon \: Semicolon \; Less than \< |
| 104 |
% Equals \= Greater than \> Question mark \? |
| 105 |
% Commercial at \@ Left bracket \[ Backslash \\ |
| 106 |
% Right bracket \] Circumflex \^ Underscore \_ |
| 107 |
% Grave accent \` Left brace \{ Vertical bar \| |
| 108 |
% Right brace \} Tilde \~} |
| 109 |
% |
| 110 |
% \changes{v1.0}{2001/01/03}{Initial version} |
| 111 |
% \changes{v1.1}{2005/01/04}{Completely restructured the \texttt{.dtx} file} |
| 112 |
% \changes{v1.1a}{2005/02/18}{Corrected a few stupid bugs} |
| 113 |
% \changes{v1.2}{2005/02/20}{Modified so as to enable filenames to |
| 114 |
% contain special characters, e.g., underscores} |
| 115 |
% \changes{v1.3}{2007/01/15}{Incorporated Ross Moore's patches for |
| 116 |
% making \protect\pkgname{attachfile} robust to running |
| 117 |
% \protect\pkgname{hyperref} with \cs{Hy@unicodetrue} and for |
| 118 |
% supporting the \protect\pdfname{Created}, |
| 119 |
% \protect\pdfname{Modified}, and \protect\pdfname{Size} keys in the |
| 120 |
% \protect\pdfname{EmbeddedFile}'s \protect\pdfname{Params} |
| 121 |
% dictionary} |
| 122 |
% |
| 123 |
% \GetFileInfo{attachfile.dtx} |
| 124 |
% |
| 125 |
% \DoNotIndex{\#,\@,\DeclareRobustCommand,\MessageBreak,\\,\addtocounter} |
| 126 |
% \DoNotIndex{\begingroup,\bgroup,\catcode,\csname,\def,\do,\dospecials} |
| 127 |
% \DoNotIndex{\edef,\egroup,\else,\endcsname,\endgroup,\expandafter,\fi} |
| 128 |
% \DoNotIndex{\gdef,\hbox,\ifnum,\ifpdf,\ifx,\immediate,\let,\makebox} |
| 129 |
% \DoNotIndex{\newcommand,\newcounter,\newif,\newlength,\newsavebox,\parbox} |
| 130 |
% \DoNotIndex{\protect,\raisebox,\relax,\renewcommand,\rule,\savebox} |
| 131 |
% \DoNotIndex{\setbox,\setcounter,\setkeys,\settodepth,\settoheight} |
| 132 |
% \DoNotIndex{\settowidth,\space,\strut,\the,\undefined,\usebox,\wd,\xdef} |
| 133 |
% \DoNotIndex{\{,\}} |
| 134 |
% |
| 135 |
% \hypersetup{^^A |
| 136 |
% pdftitle={The attachfile package}, |
| 137 |
% pdfauthor={Scott Pakin <[email protected]>}, |
| 138 |
% pdfsubject={LaTeX file attachment package}, |
| 139 |
% pdfkeywords={file attachments, annotations, embedded, PDF, LaTeX}, |
| 140 |
% pdfcopyright={Copyright (C) \the\year, Scott Pakin}, |
| 141 |
% pdflicenseurl={http://www.latex-project.org/lppl.txt}, |
| 142 |
% pdfcaptionwriter={Scott Pakin}, |
| 143 |
% pdfcontactregion={New Mexico}, |
| 144 |
% pdfcontactcountry={USA}, |
| 145 |
% pdfcontactemail={[email protected]}, |
| 146 |
% pdfcontacturl={http://www.pakin.org/\xmptilde scott/}, |
| 147 |
% baseurl={http://mirror.ctan.org/macros/latex/contrib/attachfile/attachfile.pdf}, |
| 148 |
% pdflang={en-US} |
| 149 |
% } |
| 150 |
% |
| 151 |
% ^^A Help prevent weird line breaks in URLs |
| 152 |
% \def\UrlBreaks{} |
| 153 |
% \def\UrlBigBreaks{\do/} |
| 154 |
% |
| 155 |
% ^^A Define some logical styles. |
| 156 |
% \newcommand{\menuname}[1]{\textit{#1}} |
| 157 |
% \newcommand{\pkgname}[1]{^^A |
| 158 |
% \textsf{#1}^^A |
| 159 |
% \SortIndex{#1}{\textsf{#1} (package)\encapchar usage}^^A |
| 160 |
% \index{packages>\textsf{#1}\encapchar usage}} |
| 161 |
% \newcommand{\pdfname}[1]{^^A |
| 162 |
% \textsf{#1}\SortIndex{#1}{\textsf{#1}\encapchar usage}} |
| 163 |
% \newcommand{\acronym}[1]{^^A |
| 164 |
% \textsc{\MakeLowercase{#1}}^^A |
| 165 |
% \SortIndex{#1}{\textsc{\MakeLowercase{#1}}\encapchar usage}^^A |
| 166 |
% } |
| 167 |
% |
| 168 |
% ^^A Define some indexable things. |
| 169 |
% \newcommand{\bibtex}{^^A |
| 170 |
% \BibTeX\SortIndex{BibTeX}{\BibTeX\encapchar usage}} |
| 171 |
% \newcommand{\pdflatex}{^^A |
| 172 |
% pdf\LaTeX\SortIndex{pdfLaTeX}{pdf\LaTeX\encapchar usage}} |
| 173 |
% \newcommand{\lualatex}{^^A |
| 174 |
% Lua\LaTeX\SortIndex{LuaLaTeX}{Lua\LaTeX\encapchar usage}} |
| 175 |
% \newcommand{\latex}{^^A |
| 176 |
% \LaTeX\SortIndex{LaTeX}{\LaTeX\encapchar usage}} |
| 177 |
% \newcommand{\tex}{^^A |
| 178 |
% \TeX\SortIndex{TeX}{\TeX\encapchar usage}} |
| 179 |
% |
| 180 |
% ^^A Index one of attachtext's options. |
| 181 |
% \newcommand{\prevopt}{} |
| 182 |
% \newenvironment{describeopt}[1]{^^A |
| 183 |
% \gdef\prevopt{#1}^^A |
| 184 |
% \index{options\levelchar\prevopt |
| 185 |
% \actualchar\texttt{\prevopt}^^A |
| 186 |
% \encapchar(usage}% |
| 187 |
% \index{\prevopt |
| 188 |
% \actualchar\texttt{\prevopt} (option)^^A |
| 189 |
% \encapchar(usage}^^A |
| 190 |
% }{^^A |
| 191 |
% \index{\prevopt% |
| 192 |
% \actualchar\texttt{\prevopt} (option)^^A |
| 193 |
% \encapchar)usage}^^A |
| 194 |
% \index{options\levelchar\prevopt |
| 195 |
% \actualchar\texttt{\prevopt}^^A |
| 196 |
% \encapchar)usage}^^A |
| 197 |
% } |
| 198 |
% |
| 199 |
% ^^A Output the name of an option, and also enter it into the index. |
| 200 |
% \newcommand{\indexedopt}[1]{^^A |
| 201 |
% \gdef\prevopt{#1}^^A |
| 202 |
% \texttt{\prevopt}^^A |
| 203 |
% \index{options\levelchar\prevopt |
| 204 |
% \actualchar\texttt{\prevopt}^^A |
| 205 |
% \encapchar usage}^^A |
| 206 |
% \index{\prevopt |
| 207 |
% \actualchar\texttt{\prevopt} (option)^^A |
| 208 |
% \encapchar usage}^^A |
| 209 |
% } |
| 210 |
% |
| 211 |
% ^^A My nice, long variables names wreak havoc with a three-columned index. |
| 212 |
% \setcounter{IndexColumns}{2} |
| 213 |
% |
| 214 |
% ^^A Index a macro description. This is copy&pasted from \SpecialUsageIndex, |
| 215 |
% ^^A but recast as an environment, so we can get beginning and ending page |
| 216 |
% ^^A numbers. |
| 217 |
% \makeatletter |
| 218 |
% \newcommand{\prevmacro}{} |
| 219 |
% \newenvironment{describemacro}[1]{^^A |
| 220 |
% \gdef\prevmacro{#1}^^A |
| 221 |
% \@bsphack |
| 222 |
% {\let\special@index\index |
| 223 |
% \expandafter\SpecialIndex@\expandafter{\prevmacro}{\encapchar(usage}}^^A |
| 224 |
% \@esphack |
| 225 |
% }{^^A |
| 226 |
% \@bsphack |
| 227 |
% {\let\special@index\index |
| 228 |
% \expandafter\SpecialIndex@\expandafter{\prevmacro}{\encapchar)usage}}^^A |
| 229 |
% \@esphack |
| 230 |
% } |
| 231 |
% \makeatother |
| 232 |
% |
| 233 |
% ^^A Make the index automatically add an entry to the table of contents. |
| 234 |
% ^^A NOTE: Hardwired to a code-line index. If you want to use \PageIndex |
| 235 |
% ^^A instead of \CodelineIndex, be sure to modify the following text |
| 236 |
% ^^A appropriately. |
| 237 |
% \IndexPrologue{^^A |
| 238 |
% \section*{Index}^^A |
| 239 |
% \markboth{Index}{Index}^^A |
| 240 |
% \addcontentsline{toc}{section}{Index}^^A |
| 241 |
% Numbers written in italic refer to the page where the corresponding |
| 242 |
% entry is described; numbers underlined refer to the code line of the |
| 243 |
% definition; numbers in roman refer to the code lines where the entry |
| 244 |
% is used. |
| 245 |
% } |
| 246 |
% |
| 247 |
% ^^A Make legal-minded people happy. |
| 248 |
% ^^A\newcommand{\smallreg}{\textsuperscript{\textregistered}} |
| 249 |
% ^^A\newcommand{\smalltm}{\textsuperscript{TM}} |
| 250 |
% \newcommand{\smallreg}{} |
| 251 |
% \newcommand{\smalltm}{} |
| 252 |
% |
| 253 |
% ^^A Define some trademarked names. |
| 254 |
% \newcommand{\adobe}{Adobe\smallreg\xspace} |
| 255 |
% \newcommand{\adobeacrobat}{^^A |
| 256 |
% \adobe Acrobat\smallreg |
| 257 |
% \index{Adobe Acrobat\encapchar usage}^^A |
| 258 |
% \xspace^^A |
| 259 |
% } |
| 260 |
% \newcommand{\adobeacrobatreader}{^^A |
| 261 |
% \adobeacrobat Reader\smalltm |
| 262 |
% \index{Adobe Acrobat\levelchar Reader\encapchar usage}^^A |
| 263 |
% \xspace |
| 264 |
% } |
| 265 |
% |
| 266 |
% ^^A The following was swiped verbatim from ltxguide.cls: |
| 267 |
% |
| 268 |
% ^^A A declaration of a command, in a box, set out into the margin. |
| 269 |
% ^^A |
| 270 |
% ^^A Unfortunately, there is a bug with this command, which allows page |
| 271 |
% ^^A breaks to happen after a \begin{decl}[DATE]: it is a bug with TeX that |
| 272 |
% ^^A makes it very difficult to get page-breaks correct near marginals, |
| 273 |
% ^^A especially at the end of a paragraph. |
| 274 |
% \DeleteShortVerb{\|} |
| 275 |
% \newenvironment{decl}[1][]^^A |
| 276 |
% {\par\small\addvspace{4.5ex plus 1ex}^^A |
| 277 |
% \vskip -\parskip |
| 278 |
% \ifx\relax#1\relax |
| 279 |
% \def\@decl@date{}^^A |
| 280 |
% \else |
| 281 |
% \def\@decl@date{\NEWfeature{#1}}^^A |
| 282 |
% \fi |
| 283 |
% \noindent\hspace{-\leftmargini}^^A |
| 284 |
% \begin{tabular}{|l|}\hline\ignorespaces}^^A |
| 285 |
% {\\\hline\end{tabular}\nobreak\@decl@date\par\nobreak |
| 286 |
% \vspace{2.3ex}\vskip -\parskip} |
| 287 |
% \MakeShortVerb{\|} |
| 288 |
% |
| 289 |
% ^^A Because we have the fancy decl environment above, we don't need |
| 290 |
% ^^A macro names in the margins. |
| 291 |
% \makeatletter |
| 292 |
% \let\PrintDescribeMacro=\@gobble |
| 293 |
% \makeatother |
| 294 |
% |
| 295 |
% ^^A ---------------------------------------------------------------------- |
| 296 |
% |
| 297 |
% \title{The \textsf{attachfile} package\thanks{This file |
| 298 |
% has version number \fileversion, last revised \filedate.}} |
| 299 |
% \author{Scott Pakin \\ \texttt{[email protected]}} |
| 300 |
% |
| 301 |
% \maketitle |
| 302 |
% |
| 303 |
% \begin{abstract} |
| 304 |
% This package defines an |\attachfile| command that lets you attach |
| 305 |
% arbitrary files to a \acronym{PDF} document. These files are |
| 306 |
% embedded right in the \acronym{PDF} file, so they get transmitted |
| 307 |
% along with it. The package also gives you control over the |
| 308 |
% corresponding icon's properties and various other associated |
| 309 |
% metadata. |
| 310 |
% \end{abstract} |
| 311 |
% |
| 312 |
% |
| 313 |
% \section{Introduction} |
| 314 |
% |
| 315 |
% \acronym{PDF}, \adobe's Portable Document Format, is a common way to |
| 316 |
% distribute documents that look the same on all platforms and output |
| 317 |
% devices. Beginning with \acronym{PDF} version~1.3, \acronym{PDF} |
| 318 |
% supports ``file attachment annotations''. These are arbitrary |
| 319 |
% auxiliary files that get embedded directly into the \acronym{PDF} |
| 320 |
% document, just like attachments in an e-mail message. |
| 321 |
% |
| 322 |
% The \pkgname{attachfile} package gives \pdflatex{} users the ability |
| 323 |
% to add these attachments to their documents automatically. And |
| 324 |
% because \latex{} is a markup language, not a \acronym{WYSIWYG} tool, |
| 325 |
% the user has precise control over the location of the file attachment |
| 326 |
% icons. If an icon representing an attached spreadsheet file is placed |
| 327 |
% next to a figure, the icon will move along with the figure whenever |
| 328 |
% the document is modified. Furthermore, it is possible to define |
| 329 |
% global properties for all the file attachments in a document. With |
| 330 |
% one command, a user can change the properties of all the icons in the |
| 331 |
% entire document. |
| 332 |
% |
| 333 |
% Finally, one nifty feature that \pkgname{attachfile} supports is the |
| 334 |
% ability to use your own icons, which can be text, graphics, tables, |
| 335 |
% mathematics---you name it! With this feature, a \acronym{PDF} file |
| 336 |
% can, for example, instruct the reader to click on a formula to extract |
| 337 |
% the Mathematica\smallreg\ notebook that derived it. Or to click on a |
| 338 |
% graph to extract the Microsoft\smallreg\ Excel spreadsheet that |
| 339 |
% contains all the data that was plotted. The possiblities are endless. |
| 340 |
% |
| 341 |
% \bigskip |
| 342 |
% |
| 343 |
% Okay, let's get down to business. Here are some sample file |
| 344 |
% attachments so you can see if your \acronym{PDF} viewer is able to |
| 345 |
% handle them: |
| 346 |
% |
| 347 |
% \begingroup |
| 348 |
% \attachfilesetup{^^A |
| 349 |
% color=1 0 0, |
| 350 |
% mimetype=text/plain, |
| 351 |
% author={Scott Pakin}, |
| 352 |
% icon=PushPin, |
| 353 |
% description={This document's BibTeX bibliography} |
| 354 |
% } |
| 355 |
% |
| 356 |
% \begin{center} |
| 357 |
% \begin{tabular}{@{}lc@{\qquad(Should resemble this:~}c@{)}} |
| 358 |
% Icon: & |
| 359 |
% \attachfile[size=1015,modified={D:20050104230918-07'00'}]{attachfile.bib} & |
| 360 |
% \noattachfile \\ |
| 361 |
% |
| 362 |
% \latex\ text: & |
| 363 |
% \textattachfile[size=1015,modified={D:20050104230918-07'00'}]{attachfile.bib}{\texttt{attachfile.bib}} & |
| 364 |
% \textcolor[rgb]{1,0,0}{\texttt{attachfile.bib}} |
| 365 |
% \end{tabular} |
| 366 |
% \end{center} |
| 367 |
% \endgroup |
| 368 |
% |
| 369 |
% \noindent |
| 370 |
% Each of the above points to the \bibtex\ bibliography (a plain text |
| 371 |
% file) for the document you're reading now. Try extracting the |
| 372 |
% attachment. In \adobeacrobat, this is achieved by right-clicking on |
| 373 |
% the icon and choosing ``Save Embedded File to Disk\dots'' (or in older |
| 374 |
% versions of \adobeacrobat, ``Extract File\dots''). You can also |
| 375 |
% double-click to open the file immediately. If you're unable to access |
| 376 |
% the attached file, or you observe miscellaneous strange behavior, your |
| 377 |
% \acronym{PDF} viewer might not be cabable of handling file attachments |
| 378 |
% properly. See Section~\ref{sec:caveats} for some \acronym{PDF} viewer |
| 379 |
% problems I encountered while testing \pkgname{attachfile}. |
| 380 |
% |
| 381 |
% |
| 382 |
% \section{Usage} |
| 383 |
% |
| 384 |
% Load \pkgname{attachfile} by putting a |\usepackage{attachfile}| in |
| 385 |
% your document's preamble. \pkgname{attachfile} implicitly loads a |
| 386 |
% variety of other packages. Section~\ref{sec:caveats} presents the |
| 387 |
% complete list. |
| 388 |
% |
| 389 |
% \pkgname{attachfile}~\fileversion{} does not have any of its own |
| 390 |
% package options; any options that get passed to \pkgname{attachfile} |
| 391 |
% are forwarded to \pkgname{hyperref}. Because \pkgname{hyperref} works |
| 392 |
% best when loaded as one of the last packages in the document the same |
| 393 |
% holds true for \pkgname{attachfile}. |
| 394 |
% |
| 395 |
% \section{Commands} |
| 396 |
% \label{sec:commands} |
| 397 |
% |
| 398 |
% The following are the commands that \pkgname{attachfile} makes |
| 399 |
% available for attaching files, customizing the icon appearance, and |
| 400 |
% changing various file attachment metadata. |
| 401 |
% |
| 402 |
% \begin{describemacro}{attachfile} |
| 403 |
% \begin{decl} |
| 404 |
% |\attachfile| \oarg{options} \marg{filename} |
| 405 |
% \end{decl} |
| 406 |
% \DescribeMacro{\attachfile} |
| 407 |
% The |\attachfile| macro has only one required argument: the name of |
| 408 |
% the file to attach. |\attachfile| will insert an icon at the current |
| 409 |
% point in the document to represent the attachment. \meta{options} is |
| 410 |
% a list of optional parameters for describing the icon and other |
| 411 |
% assorted metadata. It is described in Section~\ref{sec:options}. |
| 412 |
% \end{describemacro} |
| 413 |
% |
| 414 |
% \begin{describemacro}{noattachfile} |
| 415 |
% \begin{decl} |
| 416 |
% |\noattachfile| \oarg{options} |
| 417 |
% \end{decl} |
| 418 |
% \DescribeMacro{\noattachfile} |
| 419 |
% When writing instructions, it is sometimes convenient to describe what |
| 420 |
% a file attachment icon looks like without actually attaching a file. |
| 421 |
% That's what |\noattachfile| is for. All it does is insert the image |
| 422 |
% of a file attachment icon into the document. \meta{options} is a list |
| 423 |
% of optional parameters for describing the icon and other assorted |
| 424 |
% metadata. It is described in Section~\ref{sec:options}. In |
| 425 |
% particular, note that if the |print| option is set to |false| then |
| 426 |
% |\noattachfile| will output empty space of the same size as the icon |
| 427 |
% image. |
| 428 |
% \end{describemacro} |
| 429 |
% |
| 430 |
% \begin{describemacro}{textattachfile} |
| 431 |
% \begin{decl} |
| 432 |
% |\textattachfile| \oarg{options} \marg{filename} \marg{text} |
| 433 |
% \end{decl} |
| 434 |
% \DescribeMacro{\textattachfile} |
| 435 |
% |\textattachfile| is just like |\attachfile|, except that instead of |
| 436 |
% using one of the predefined \acronym{PDF} icons, it lets you use an |
| 437 |
% arbitrary piece of text to represent the attachment. The \meta{text} |
| 438 |
% parameter is not limited to text; it can contain any arbitrary |
| 439 |
% horizontal material. The following are all legal uses of |
| 440 |
% |\textattachfile|: |
| 441 |
% |
| 442 |
% \begin{itemize} |
| 443 |
% \item \texttt{You can} |\textattachfile{myfile.cc}{extract| \texttt{my |
| 444 |
% source code}|}| \texttt{if your PDF viewer supports file annotations.} |
| 445 |
% |
| 446 |
% \item \texttt{It is intuitively obvious to even the most casual observer |
| 447 |
% that} |
| 448 |
% \begin{verbatim} |
| 449 |
% \textattachfile{derivation.m}{$\displaystyle |
| 450 |
% \frac{\partial E_p}{\partial w_{ji}^h} = |
| 451 |
% -\sum_k (y_{pk} - o_{pk}) f_k^{o}{}'(\mbox{net}_{pk}^o) |
| 452 |
% w_{kj}^o f_j^h{}'(\mbox{net}_{pj}^h) x_{pi}$} |
| 453 |
% \end{verbatim} |
| 454 |
% |
| 455 |
% \item |\textattachfile{earningsdata.csv}{\includegraphics{earnings}}| |
| 456 |
% |
| 457 |
% \end{itemize} |
| 458 |
% \end{describemacro} |
| 459 |
% |
| 460 |
% \begin{describemacro}{notextattachfile} |
| 461 |
% \begin{decl} |
| 462 |
% |\notextattachfile| \oarg{options} \marg{text} |
| 463 |
% \end{decl} |
| 464 |
% \DescribeMacro{\noattachfile} |
| 465 |
% Just as |\noattachfile| is a dummy version of |\attachfile|, so |
| 466 |
% |\notextattachfile| is a dummy version of |\textattachfile|. All |
| 467 |
% |\notextattachfile| does is insert \meta{text} into the document |
| 468 |
% according to \meta{options} (described in Section~\ref{sec:options}). |
| 469 |
% In particular, note that if the |print| option is set to |false| then |
| 470 |
% |\notextattachfile| will output empty space of the same size as |
| 471 |
% \meta{text}. |
| 472 |
% \end{describemacro} |
| 473 |
% |
| 474 |
% \begin{describemacro}{attachfilesetup} |
| 475 |
% \begin{decl} |
| 476 |
% |\attachfilesetup| \marg{options} |
| 477 |
% \end{decl} |
| 478 |
% \DescribeMacro{\attachfilesetup} |
| 479 |
% If you find yourself passing the same set of options to multiple |
| 480 |
% |\attachfile| calls in your document, you can use |\attachfilesetup| |
| 481 |
% to specify default option values. |\attachfilesetup|'s \meta{options} |
| 482 |
% parameter is the same as that used by |\attachfile| and is described |
| 483 |
% in Section~\ref{sec:options}. Some noteworthy points are: |
| 484 |
% |
| 485 |
% \begin{enumerate} |
| 486 |
% \item |\attachfilesetup| can be called as many times as desired. |
| 487 |
% Any options specified replace the previous value of those options. |
| 488 |
% All unspecified options are left alone. |
| 489 |
% |
| 490 |
% \item Options passed to |\attachfile| take precedence over those |
| 491 |
% specified by |\attachfilesetup|. This lets you define default |
| 492 |
% values for all file attachments and selectively override them on a |
| 493 |
% per-attachment basis. |
| 494 |
% |
| 495 |
% \item Options set by |\attachfilesetup| are local to the current |
| 496 |
% scope. This lets you assign defaults to a group of file attachments |
| 497 |
% without affecting the global defaults. To define options that apply |
| 498 |
% to the entire document, |\attachfilesetup| should be called at the |
| 499 |
% top-level scope (which includes the document's prologue). |
| 500 |
% \end{enumerate} |
| 501 |
% \end{describemacro} |
| 502 |
% |
| 503 |
% \section{Options} |
| 504 |
% \label{sec:options} |
| 505 |
% |
| 506 |
% \pkgname{attachfile} gives the user a great deal of control over the |
| 507 |
% way files are attached to a document. All the commands in |
| 508 |
% Section~\ref{sec:commands} accept the same set of options, which are |
| 509 |
% entered as comma-separated, \meta{key}|=|\meta{value} pairs. Options |
| 510 |
% can be specified in any order. Case is significant. Only the |
| 511 |
% options you want to change need to be specified; the others will |
| 512 |
% retain their previous value (or the default, if no previous value was |
| 513 |
% specified). |
| 514 |
% |
| 515 |
% \subsection{List of available options} |
| 516 |
% \label{sec:option-list} |
| 517 |
% |
| 518 |
% The following are the options \pkgname{attachfile} accepts, in |
| 519 |
% alphabetical order. |
| 520 |
% |
| 521 |
% \begin{describeopt}{appearance} |
| 522 |
% \begin{decl} |
| 523 |
% |appearance=|\meta{boolean} |
| 524 |
% \end{decl} |
| 525 |
% The \pkgname{attachfile} package normally embeds the file attachment's |
| 526 |
% icon explicitly with each file attachment annotation. (In |
| 527 |
% \acronym{PDF}-speak, it includes an appearance dictionary in the |
| 528 |
% \pdfname{FileAttachment} object.) The advantages to doing this are to |
| 529 |
% ensure that: |
| 530 |
% |
| 531 |
% \begin{itemize} |
| 532 |
% \item The file attachment icons look the same in all \acronym{PDF} |
| 533 |
% viewers. |
| 534 |
% |
| 535 |
% \item \tex\ knows exactly how much space to allocate, instead of |
| 536 |
% just guessing based on the size of the \adobeacrobat icons. |
| 537 |
% |
| 538 |
% \item Pre-1.3 \acronym{PDF} viewers don't regress to showing an |
| 539 |
% ``unknown annotation type'' graphic. |
| 540 |
% \end{itemize} |
| 541 |
% |
| 542 |
% \noindent |
| 543 |
% However, the problems with embedding the icon graphic are: |
| 544 |
% |
| 545 |
% \begin{itemize} |
| 546 |
% \item It adds a bit of extra bulk to the \acronym{PDF} file. |
| 547 |
% |
| 548 |
% \item It takes flexibility away from the \acronym{PDF} viewer, which |
| 549 |
% can no longer choose for itself how best to render a file attachment |
| 550 |
% icon. |
| 551 |
% \end{itemize} |
| 552 |
% |
| 553 |
% The |appearance| option gives the author the ability to prevent the |
| 554 |
% icon's appearance from being specified explicitly in the \acronym{PDF} |
| 555 |
% file. By setting \texttt{appearance=false}, it will be left up to the |
| 556 |
% \acronym{PDF} viewer to decide how to display the icon. |
| 557 |
% \end{describeopt} |
| 558 |
% |
| 559 |
% \begin{describeopt}{author} |
| 560 |
% \begin{decl} |
| 561 |
% |author=|\meta{text} |
| 562 |
% \end{decl} |
| 563 |
% The metadata associated with a file attachment annotation includes the |
| 564 |
% name of the person who attached the file. In \adobeacrobat, this |
| 565 |
% information is shown when one right-clicks on the file attachment icon |
| 566 |
% and selects \menuname{Properties\dots}. By default, no author is listed |
| 567 |
% but specifying \indexedopt{author}|=|\meta{name} sets the author field to |
| 568 |
% \meta{name}. |
| 569 |
% \end{describeopt} |
| 570 |
% |
| 571 |
% \begin{describeopt}{color} |
| 572 |
% \begin{decl} |
| 573 |
% |color=|\meta{red} \meta{green} \meta{blue} |
| 574 |
% \end{decl} |
| 575 |
% The icons inserted by |\attachfile| and the text inserted by |
| 576 |
% |\textattachfile| can be any color. The \indexedopt{color} option sets this |
| 577 |
% color. Each of \meta{red}, \meta{green}, and \meta{blue} must be a |
| 578 |
% decimal number between 0~(darkest) and 1~(brightest). The default is |
| 579 |
% |color=1 0.9255 0.7765|, which is a beige. |
| 580 |
% \end{describeopt} |
| 581 |
% |
| 582 |
% \begin{describeopt}{created} |
| 583 |
% \begin{decl} |
| 584 |
% |created=|\meta{PDF date} |
| 585 |
% \end{decl} |
| 586 |
% Virtually all filesystems associate a file-creation timestamp with |
| 587 |
% each file. Although \tex\ provides no portable mechanism for |
| 588 |
% determining the date and time a file was created the |
| 589 |
% \indexedopt{created} option lets you manually specify these |
| 590 |
% parameters for the reader's benefit. See Section~\ref{sec:date-usage} |
| 591 |
% for more information about \pkgname{attachfile} dates. |
| 592 |
% \end{describeopt} |
| 593 |
% |
| 594 |
% \begin{describeopt}{date} |
| 595 |
% \begin{decl} |
| 596 |
% |date=|\meta{PDF date} |
| 597 |
% \end{decl} |
| 598 |
% Each annotation in a \acronym{PDF} file can have a timestamp |
| 599 |
% indicating when the annotation was last modified. |
| 600 |
% \pkgname{attachfile} automatically adds a timestamp to file attachment |
| 601 |
% annotations. It uses the date and time at which \latex\ started |
| 602 |
% processing your job (to minute precision because that's what \tex's |
| 603 |
% \texttt{\string\time} command provides) and includes the timezone, if |
| 604 |
% specified (using the \indexedopt{timezone} option, |
| 605 |
% p.~\pageref{page:timezone}). Although it's unlikely you'll need to |
| 606 |
% use it, the \indexedopt{date} option lets you override the |
| 607 |
% annotation's modification date and time with a date and time of your |
| 608 |
% choice. See Section~\ref{sec:date-usage} for more information |
| 609 |
% about \pkgname{attachfile} dates. |
| 610 |
% \end{describeopt} |
| 611 |
% |
| 612 |
% \begin{describeopt}{description} |
| 613 |
% \begin{decl} |
| 614 |
% |description=|\meta{text} |
| 615 |
% \end{decl} |
| 616 |
% The metadata associated with a file attachment annotation can include |
| 617 |
% a brief description of the file. In \adobeacrobat, this information |
| 618 |
% is shown when one right-clicks on the file attachment icon and selects |
| 619 |
% \menuname{Properties\dots}. Also, in later versions of \adobeacrobat, |
| 620 |
% the description field shows up as a tool~tip when the user mouses over |
| 621 |
% the attachment. By default, no description is included, but |
| 622 |
% specifying \indexedopt{description}|=|\meta{text} sets the description |
| 623 |
% field to \meta{text}. |
| 624 |
% \end{describeopt} |
| 625 |
% |
| 626 |
% \begin{describeopt}{icon} |
| 627 |
% \begin{decl} |
| 628 |
% |icon=|\meta{name} |
| 629 |
% \end{decl} |
| 630 |
% \acronym{PDF}~1.3 defines four icons that can be used for file |
| 631 |
% attachments: \pdfname{Graph}, \pdfname{Paperclip}, \pdfname{PushPin}, |
| 632 |
% and \pdfname{Tag}. These are shown in Table~\ref{tbl:icons}. If no |
| 633 |
% icon name is specified, \pdfname{PushPin} is assumed. While the |
| 634 |
% \acronym{PDF} specifications say that, normally, a \acronym{PDF} |
| 635 |
% viewer chooses how to display each of those, the \pkgname{attachfile} |
| 636 |
% package specifies the appearance explicitly. This is what |
| 637 |
% \adobeacrobat does, presumably because doing so ensures that viewers |
| 638 |
% which don't support file attachment annotations can still display |
| 639 |
% something reasonable. The tradeoff is that it slightly increases the |
| 640 |
% size of the \acronym{PDF} file. |
| 641 |
% |
| 642 |
% \begin{table}[tbp] |
| 643 |
% \newcommand{\tallspace}{\rule[-2pt]{0pt}{24pt}} |
| 644 |
% \centering |
| 645 |
% \begin{tabular}{lc} |
| 646 |
% \tallspace\pdfname{Graph} & \noattachfile[icon=Graph] \\ |
| 647 |
% \tallspace\pdfname{Paperclip} & \noattachfile[icon=Paperclip] \\ |
| 648 |
% \tallspace\pdfname{PushPin} & \noattachfile[icon=PushPin] \\ |
| 649 |
% \tallspace\pdfname{Tag} & \noattachfile[icon=Tag] |
| 650 |
% \end{tabular} |
| 651 |
% \caption{Valid file attachment icons} |
| 652 |
% \label{tbl:icons} |
| 653 |
% \end{table} |
| 654 |
% \end{describeopt} |
| 655 |
% |
| 656 |
% \begin{describeopt}{mimetype} |
| 657 |
% \begin{decl} |
| 658 |
% |mimetype=|\meta{type} |
| 659 |
% \end{decl} |
| 660 |
% It is considered good practice to specify the \acronym{MIME} |
| 661 |
% type~\cite{Freed1996} of each attached file. That way, a |
| 662 |
% \acronym{PDF} viewer can automatically launch an appropriate |
| 663 |
% application to process the file. \meta{type} should be the form |
| 664 |
% ``\meta{type}|/|\meta{subtype}''. For instance, a plain text file |
| 665 |
% would be specified with ``\texttt{mimetype=text/plain}''. An |
| 666 |
% \acronym{MPEG} movie would be specified with |
| 667 |
% ``\texttt{mimetype=video/mpeg}''. The |
| 668 |
% \href{http://www.iana.org/}{Internet Assigned Numbers Authority} |
| 669 |
% maintains a list of registered media types~\cite{MediaTypes}, so look |
| 670 |
% there first to see what type to use for a given file. |
| 671 |
% \end{describeopt} |
| 672 |
% |
| 673 |
% \begin{describeopt}{modified} |
| 674 |
% \begin{decl} |
| 675 |
% |modified=|\meta{PDF date} |
| 676 |
% \end{decl} |
| 677 |
% Virtually all filesystems associate a last-modification timestamp with |
| 678 |
% each file. Although \tex\ provides no portable mechanism for |
| 679 |
% determining the date and time a file was last modified the |
| 680 |
% \indexedopt{modified} option lets you manually specify these |
| 681 |
% parameters for the reader's benefit. See Section~\ref{sec:date-usage} |
| 682 |
% for more information about \pkgname{attachfile} dates. |
| 683 |
% \end{describeopt} |
| 684 |
% |
| 685 |
% \begin{describeopt}{print} |
| 686 |
% \begin{decl} |
| 687 |
% |print=|\meta{boolean} |
| 688 |
% \end{decl} |
| 689 |
% By default, file annotation icons print along with the rest of the |
| 690 |
% document. By setting \texttt{print=false}, the icons will not print. |
| 691 |
% Note that in \adobeacrobat, annotations will \emph{never} print unless |
| 692 |
% the Annotations box is checked in the \Acrobatmenu{Print}{Print |
| 693 |
% dialog}. |
| 694 |
% \end{describeopt} |
| 695 |
% |
| 696 |
% \begin{describeopt}{size} |
| 697 |
% \begin{decl} |
| 698 |
% |size=|\meta{integer} |
| 699 |
% \end{decl} |
| 700 |
% The \indexedopt{size} option tells the \acronym{PDF} viewer that the |
| 701 |
% attached file is \meta{integer} bytes long. \adobeacrobat displays |
| 702 |
% this size under the ``Size'' column in the |
| 703 |
% \Acrobatmenu{ShowHideAttachments}{Attachments pane} but does not |
| 704 |
% otherwise seem to use the \meta{integer} value. |
| 705 |
% \end{describeopt} |
| 706 |
% |
| 707 |
% \begin{describeopt}{subject} |
| 708 |
% \begin{decl} |
| 709 |
% |subject=|\meta{text} |
| 710 |
% \end{decl} |
| 711 |
% The metadata associated with a file attachment annotation can include |
| 712 |
% a brief comment about the subject of the attachment. In |
| 713 |
% \adobeacrobat, this information is shown when one right-clicks on the |
| 714 |
% file attachment icon and selects \menuname{Properties}. By default, |
| 715 |
% no subject is included, but specifying \indexedopt{subject}|=|\meta{text} |
| 716 |
% sets the subject field to \meta{text}. |
| 717 |
% \end{describeopt} |
| 718 |
% |
| 719 |
% \begin{describeopt}{timezone} |
| 720 |
% \label{page:timezone} |
| 721 |
% \begin{decl} |
| 722 |
% |timezone=|\meta{offset} |
| 723 |
% \end{decl} |
| 724 |
% Because \tex\ doesn't make the current timezone available, |
| 725 |
% \pkgname{attachfile} is unable to include timezone information when it |
| 726 |
% timestamps a file attachment. The \indexedopt{timezone} option lets you |
| 727 |
% manually specify the timezone. \meta{offset} is the offset from |
| 728 |
% Universal\index{Universal Time|usage} Time (a.k.a.\ \acronym{GMT}) and |
| 729 |
% should be in the format specified in the \acronym{PDF} reference |
| 730 |
% manual~\cite[\textsection3.8.3, ``Dates'']{PDFRef}, namely: |
| 731 |
% |
| 732 |
% \begin{center} |
| 733 |
% \begin{tabular}{cp{0.66\textwidth}} |
| 734 |
% |+|\meta{HH}|'|\meta{mm}|'| & |
| 735 |
% \meta{HH} hours, \meta{mm} minutes later than Universal Time (i.e., |
| 736 |
% east of Greenwich, England) \\[\baselineskip] |
| 737 |
% |
| 738 |
% |-|\meta{HH}|'|\meta{mm}|'| & |
| 739 |
% \meta{HH} hours, \meta{mm} minutes earlier than Universal Time (i.e., |
| 740 |
% west of Greenwich, England) \\[\baselineskip] |
| 741 |
% |
| 742 |
% |Z| & |
| 743 |
% Universal Time (i.e., at the same longitude as Greenwich, England) |
| 744 |
% \end{tabular} |
| 745 |
% \end{center} |
| 746 |
% |
| 747 |
% \noindent |
| 748 |
% For example, U.S. Central Time would be specified with |
| 749 |
% \indexedopt{timezone}|=-06'00'|. |
| 750 |
% \end{describeopt} |
| 751 |
% |
| 752 |
% \begin{describeopt}{zoom} |
| 753 |
% \begin{decl} |
| 754 |
% |zoom=|\meta{boolean} |
| 755 |
% \end{decl} |
| 756 |
% Normally, when a reader magnifies or reduces the view of the |
| 757 |
% \acronym{PDF} document, the file annotation icons change size |
| 758 |
% proportionally with the text. By setting \texttt{zoom=false}, the |
| 759 |
% icon size does not scale. |
| 760 |
% \end{describeopt} |
| 761 |
% |
| 762 |
% \bigskip |
| 763 |
% The defaults for all of the options described above are summarized in |
| 764 |
% Table~\ref{tbl:opt-defaults}. |
| 765 |
% |
| 766 |
% \begin{table}[htbp] |
| 767 |
% \centering |
| 768 |
% \edef\indexentry{options\levelchar default values\encapchar usage} |
| 769 |
% \expandafter\index\expandafter{\indexentry} |
| 770 |
% \begin{tabular}{@{}l@{\qquad}l@{}} \hline |
| 771 |
% \multicolumn{1}{c}{Option\strut} & |
| 772 |
% \multicolumn{1}{c}{Default setting} \\ \hline |
| 773 |
% \indexedopt{appearance} & |true| \\ |
| 774 |
% \indexedopt{author} & \emph{none} \\ |
| 775 |
% \indexedopt{color} & |1 0.9255 0.7765| \\ |
| 776 |
% \indexedopt{created} & \emph{none} \\ |
| 777 |
% \indexedopt{date} & \emph{automatic} \\ |
| 778 |
% \indexedopt{description} & \emph{none} \\ |
| 779 |
% \indexedopt{icon} & |PushPin| \\ |
| 780 |
% \indexedopt{mimetype} & \emph{none} \\ |
| 781 |
% \indexedopt{modified} & \emph{none} \\ |
| 782 |
% \indexedopt{print} & |true| \\ |
| 783 |
% \indexedopt{size} & \emph{none} \\ |
| 784 |
% \indexedopt{subject} & \emph{none} \\ |
| 785 |
% \indexedopt{timezone} & \emph{none} \\ |
| 786 |
% \indexedopt{zoom} & |true| \\ \hline |
| 787 |
% \end{tabular} |
| 788 |
% \caption{Default values for all options} |
| 789 |
% \label{tbl:opt-defaults} |
| 790 |
% \end{table} |
| 791 |
% |
| 792 |
% \subsection{Date usage} |
| 793 |
% \label{sec:date-usage} |
| 794 |
% |
| 795 |
% Section~\ref{sec:option-list} presents three timestamp-related |
| 796 |
% options: \indexedopt{date}, \indexedopt{created}, and |
| 797 |
% \indexedopt{modified}. The \indexedopt{date} option specifies the |
| 798 |
% annotation date---the date and time the given file was attached to the |
| 799 |
% \acronym{PDF} file---and should usually be left unspecified. (It |
| 800 |
% defaults to the date and time at which \latex\ started processing your |
| 801 |
% job.) The annotation date is displayed in \adobeacrobat by |
| 802 |
% right-clicking on the annotation, choosing \menuname{Properties\dots}\ |
| 803 |
% from the menu, and clicking on the \menuname{General} tab. The |
| 804 |
% \indexedopt{modified} option specifies the file's modification |
| 805 |
% date---the date and time the given file was last modified. |
| 806 |
% \adobeacrobat displays the modification date under the ``Modified'' |
| 807 |
% column in the \Acrobatmenu{ShowHideAttachments}{Attachments pane} but |
| 808 |
% does not otherwise appear to use the modification date. Finally, the |
| 809 |
% \indexedopt{created} option specifies the file's creation date---the |
| 810 |
% date and time the given file was first written to disk. As of this |
| 811 |
% writing, \adobeacrobat does not appear to use or even display the |
| 812 |
% creation date; perhaps future versions or other \acronym{PDF} viewers |
| 813 |
% will. |
| 814 |
% |
| 815 |
% Dates should be specified in the form |
| 816 |
% ``|D:|\textit{YYYYMMDDHHmmSSOHH}|'|\textit{mm}|'|'' as described in |
| 817 |
% the \acronym{PDF} reference manual~\cite[\textsection3.8.3, |
| 818 |
% ``Dates'']{PDFRef}. Note, however, that although the \acronym{PDF} |
| 819 |
% reference manual clearly states that ``viewer applications should be |
| 820 |
% prepared to accept and display a string in any |
| 821 |
% format''~\cite[Table~8.11, ``Entries common to all annotation |
| 822 |
% dictionaries'']{PDFRef}, \adobeacrobat will ignore any timestamp that |
| 823 |
% is not in the recommended format and will instead show ``00/00/00 |
| 824 |
% 00:00:00'' for the annotation date or ``Unknown'' for the modification |
| 825 |
% date. |
| 826 |
% |
| 827 |
% |
| 828 |
% \section{Caveats} |
| 829 |
% \label{sec:caveats} |
| 830 |
% |
| 831 |
% Note that there are a few caveats you should be aware of: |
| 832 |
% |
| 833 |
% \begin{enumerate} |
| 834 |
% \item \pkgname{attachfile} requires either \pdflatex\ version~0.14 |
| 835 |
% or later or \lualatex. (Version~0.14 of \pdflatex\ was released |
| 836 |
% circa~1999 so it's unlikely that you're running an older version |
| 837 |
% than that.) While there are many other ways to produce |
| 838 |
% \acronym{PDF} files from \latex\ source, |
| 839 |
% \pkgname{attachfile}~\fileversion\ supports only \pdflatex\ and |
| 840 |
% \lualatex. |
| 841 |
% |
| 842 |
% \item \lualatex~0.85 introduced incompatible changes in the set of |
| 843 |
% \acronym{PDF} primitives supported. Because \pkgname{attachfile} |
| 844 |
% does not yet provide explicit support for these new primitives, |
| 845 |
% documents will need to include a |\usepackage{luatex85}| line in |
| 846 |
% the preamble in order to build under \lualatex~0.85+. |
| 847 |
% |
| 848 |
% \item \pkgname{attachfile} will not run unless the following |
| 849 |
% \latex\ packages are installed: \pkgname{calc}, \pkgname{keyval}, |
| 850 |
% \pkgname{color}, \pkgname{hyperref}, and \pkgname{ifpdf}. (Most |
| 851 |
% \tex\ distributions include all of these.) |
| 852 |
% |
| 853 |
% \item File attachments are a \acronym{PDF}~1.3 feature. They will |
| 854 |
% not be visible in \acronym{PDF} viewers that don't support |
| 855 |
% \acronym{PDF}~1.3. (Version~4.0 of \adobeacrobat is the first |
| 856 |
% version of that program which does.) |
| 857 |
% |
| 858 |
% \item Even some viewers that purportedly support \acronym{PDF}~1.3 |
| 859 |
% don't support file attachments. As far as I can tell, very old |
| 860 |
% versions of \adobeacrobatreader (the free, view-only version of |
| 861 |
% \adobeacrobat) doesn't seem to support \emph{any} annotations |
| 862 |
% except text annotations. |
| 863 |
% |
| 864 |
% \item Even some viewers that do support \acronym{PDF}~1.3 and file |
| 865 |
% attachments don't support them under all circumstances. For |
| 866 |
% instance, some Windows\smallreg\ versions of \adobeacrobat, when |
| 867 |
% functioning as a Web-browser plug-in, give an error |
| 868 |
% message\footnote{``Launching embedded files from within a browser |
| 869 |
% environment is not allowed''.} when a file attachment icon is |
| 870 |
% activated. |
| 871 |
% |
| 872 |
% \item Even in circumstances where file attachments are supported, |
| 873 |
% the support may be flawed. For example, some |
| 874 |
% Windows\smallreg\ versions of \adobeacrobat change a custom icon |
| 875 |
% to the default icon when it's selected. |
| 876 |
% |
| 877 |
% \item While file-attachment icons with custom appearances printed |
| 878 |
% fine in older versions of \adobeacrobat, \adobe introduced a bug |
| 879 |
% circa \adobeacrobat~6.0 that prevents \pkgname{attachfile}'s |
| 880 |
% icons from printing. Unfortunately, because \adobeacrobat lacks |
| 881 |
% \pkgname{attachfile}'s ability to create custom appearances for |
| 882 |
% file-attachment icons it's unlikely that this bug will ever get |
| 883 |
% fixed. Nevertheless, please consider sending a bug report to |
| 884 |
% \adobe to let them know that you'd like to be able to print |
| 885 |
% file-attachment icons with custom appearances. |
| 886 |
% \end{enumerate} |
| 887 |
% |
| 888 |
% Even given all of those caveats, file attachments can be a useful way |
| 889 |
% to pass additional information along with a \acronym{PDF} file. The |
| 890 |
% \pkgname{attachfile} package makes file annotations automatic and |
| 891 |
% easy. |
| 892 |
% |
| 893 |
% |
| 894 |
% \StopEventually{^^A |
| 895 |
% \section{Future work} |
| 896 |
% |
| 897 |
% The following are some avenues for future work on |
| 898 |
% \pkgname{attachfile}. First, \pkgname{attachfile} supports only |
| 899 |
% \pdflatex\ and \lualatex\ for generating \acronym{PDF} files. It |
| 900 |
% would be nice if it supported all the backends that |
| 901 |
% \pkgname{hyperref} supports: |
| 902 |
% dvipdfm\SortIndex{dvipdfm}{dvipdfm\encapchar usage}, |
| 903 |
% dvips\SortIndex{dvips}{dvips\encapchar usage} with |
| 904 |
% pdfmarks\SortIndex{pdfmarks}{pdfmarks\encapchar usage}, |
| 905 |
% V\TeX\SortIndex{VTeX}{V\TeX\encapchar usage}, and so forth. Along |
| 906 |
% those same lines, a ``draft'' package option would be a welcome |
| 907 |
% addition, for use when \acronym{PDF} is not the final output format. |
| 908 |
% |
| 909 |
% Second, \acronym{PDF} supports platform-specific file attachments. |
| 910 |
% That is, a file attachment icon can represent a different file when |
| 911 |
% activated on Windows, Unix, or MacOS. It might be nice for |
| 912 |
% \pkgname{attachfile} to support that feature. |
| 913 |
% |
| 914 |
% Finally, I'd like to see \pkgname{attachfile} expand sometime to |
| 915 |
% support \emph{all} the various \acronym{PDF} annotations: |
| 916 |
% \pdfname{Sound}, \pdfname{Movie}, \pdfname{Stamp}, \pdfname{Ink}, |
| 917 |
% \pdfname{Popup}, etc. |
| 918 |
% |
| 919 |
% Of course, I make no promises that I'll ever do \emph{any} of the |
| 920 |
% above. \pkgname{attachfile} was just something I wrote in my spare |
| 921 |
% time, and it's unlikely I'll be able to devote another large block of |
| 922 |
% time to enhance it. |
| 923 |
% |
| 924 |
% \begin{thebibliography}{1} |
| 925 |
% \bibitem{PDFRef} |
| 926 |
% {Adobe Systems Incorporated}. |
| 927 |
% \newblock {\em {PDF} Reference Version~1.6}. |
| 928 |
% \newblock Adobe Press, fifth edition, December~3, 2004. |
| 929 |
% \newblock ISBN~\mbox{0321304748}. Available from |
| 930 |
% \url{http://partners.adobe.com/public/developer/en/pdf/PDFReference16.pdf}. |
| 931 |
% |
| 932 |
% \bibitem{Freed1996} |
| 933 |
% N.~Freed and N.~Borenstein. |
| 934 |
% \newblock {M}ultipurpose {I}nternet {M}ail {E}xtensions {(MIME)} part two: |
| 935 |
% Media types. |
| 936 |
% \newblock Request for Comments (RFC) 2046, Internet Engineering Task Force |
| 937 |
% (IETF), Network Working Group, November 1996. |
| 938 |
% \newblock Available from \url{http://www.rfc-editor.org/rfc/rfc2046.txt}. |
| 939 |
% |
| 940 |
% \bibitem{MediaTypes} |
| 941 |
% {Internet Assigned Numbers Authority}. |
| 942 |
% \newblock {MIME} media types. |
| 943 |
% \newblock Available from \url{http://www.iana.org/assignments/media-types/}. |
| 944 |
% \end{thebibliography} |
| 945 |
% } |
| 946 |
% |
| 947 |
% |
| 948 |
% \section{Implementation} |
| 949 |
% |
| 950 |
% This section contains the complete source code for \pkgname{attachfile}. |
| 951 |
% Most users will not get much out of it, but it should be of use to |
| 952 |
% those who need more precise documentation and those who want to extend |
| 953 |
% the \pkgname{attachfile} package. |
| 954 |
% |
| 955 |
% \subsection{Sanity checking} |
| 956 |
% |
| 957 |
% \pkgname{attachfile} \fileversion\ requires either \lualatex\ or |
| 958 |
% \pdflatex\ (and at least version~0.14 of \pdflatex, although |
| 959 |
% \pkgname{attachfile} no longer checks for that). (Future versions of |
| 960 |
% \pkgname{attachfile} may support |
| 961 |
% dvipdfm\SortIndex{dvipdfm}{dvipdfm\encapchar usage}, |
| 962 |
% dvips\SortIndex{dvips}{dvips\encapchar usage} with |
| 963 |
% pdfmarks\SortIndex{pdfmarks}{pdfmarks\encapchar usage}, |
| 964 |
% V\TeX\SortIndex{VTeX}{V\TeX\encapchar usage}, etc.) Also, |
| 965 |
% \pdflatex\slash\lualatex must be in \acronym{PDF}-generating mode, not |
| 966 |
% \acronym{DVI}-generating mode. So, to save the user some aggravation, |
| 967 |
% we check for the correct backend right up front and give a warning if |
| 968 |
% all is not well. Later, in Section~\ref{sec:dummy-commands}, we |
| 969 |
% replace all of the core \pkgname{attachfile} macros with dummy |
| 970 |
% versions so \latex\ can at least run to completion. |
| 971 |
% \changes{v1.3a}{2008/08/15}{Corrected the formatting of the ``not |
| 972 |
% \string\pdflatex'' warning message} |
| 973 |
% \begin{macrocode} |
| 974 |
\RequirePackage{ifpdf} |
| 975 |
\ifpdf |
| 976 |
\else |
| 977 |
\PackageWarningNoLine{attachfile}{% |
| 978 |
attachfile works _only_ with pdfLaTeX and LuaLaTeX\MessageBreak |
| 979 |
and _only_ in PDF-generating mode. For this run,\MessageBreak |
| 980 |
placeholders will be substituted for all\MessageBreak |
| 981 |
attachfile commands% |
| 982 |
} |
| 983 |
\fi |
| 984 |
% \end{macrocode} |
| 985 |
% |
| 986 |
% |
| 987 |
% \subsection{Preliminaries} |
| 988 |
% |
| 989 |
% We need to load \pkgname{hyperref} to get our hands on that great |
| 990 |
% |\pdfstringdef| macro. For now, we blindly pass all our package |
| 991 |
% options directly to \pkgname{hyperref}. In the future, it would |
| 992 |
% be nice to do a |\setkeys{AtFi}| on our options. |
| 993 |
% \begin{macrocode} |
| 994 |
\RequirePackage{keyval} |
| 995 |
\RequirePackage{calc} |
| 996 |
\RequirePackage{color} |
| 997 |
\RequirePackageWithOptions{hyperref} |
| 998 |
% \end{macrocode} |
| 999 |
% |
| 1000 |
% |
| 1001 |
% \subsection{Adobe Acrobat icons} |
| 1002 |
% |
| 1003 |
% The following macros draw a representation of the various icons that |
| 1004 |
% \adobeacrobat{}\footnote{I got these graphics specifically from the |
| 1005 |
% Windows version of \adobeacrobat~4.0.} inserts to represent what the |
| 1006 |
% \acronym{PDF}~1.3 specifications refer to as ``\pdfname{Graph},'' |
| 1007 |
% ``\pdfname{Paperclip},'' ``\pdfname{PushPin},'' and ``\pdfname{Tag}''. |
| 1008 |
% The |\parbox| dimensions are taken directly from the original graphics' |
| 1009 |
% bounding box. However, I just eyeballed the |\raisebox| heights |
| 1010 |
% (intended to put shadows below the baseline). |
| 1011 |
% |
| 1012 |
% \begin{macro}{\atfi@acroGraph@data} |
| 1013 |
% Recreate \adobeacrobat's \pdfname{Graph} icon. |
| 1014 |
% \begin{macrocode} |
| 1015 |
\newcommand{\atfi@acroGraph@data}{% |
| 1016 |
q 0.5 g 1.1133 0 20.7202 18.2754 re f 1 g 0 G 0 i 0.5 w 4 M |
| 1017 |
0.25 1.6453 20.145 17.7715 re B 0 g 2.7319 4.1367 3.9571 |
| 1018 |
13.8867 re f 8.7031 4.1367 3.9571 9.8867 re f 14.7471 4.1367 |
| 1019 |
3.9571 11.8867 re f \atfi@color@rgb\space rg 1.689 3.0938 |
| 1020 |
3.9571 13.8867 re f 7.6602 3.0938 3.9571 9.8867 re f 13.7041 |
| 1021 |
3.0938 3.9571 11.8867 re f Q |
| 1022 |
} |
| 1023 |
% \end{macrocode} |
| 1024 |
% \end{macro} |
| 1025 |
% |
| 1026 |
% \begin{macro}{\atfi@acroGraph} |
| 1027 |
% Draw |\atfi@acroGraph@data| in a box of the appropriate size. |
| 1028 |
% \begin{macrocode} |
| 1029 |
\DeclareRobustCommand{\atfi@acroGraph}{% |
| 1030 |
\raisebox{-1.5bp}{\parbox[b][20bp]{22bp}{% |
| 1031 |
\rule{0pt}{0pt}\pdfliteral{\atfi@acroGraph@data}}% |
| 1032 |
}% |
| 1033 |
} |
| 1034 |
% \end{macrocode} |
| 1035 |
% \end{macro} |
| 1036 |
% |
| 1037 |
% \begin{macro}{\atfi@acroPaperclip@data} |
| 1038 |
% Recreate \adobeacrobat's \pdfname{Paperclip} icon. |
| 1039 |
% \begin{macrocode} |
| 1040 |
\newcommand{\atfi@acroPaperclip@data}{% |
| 1041 |
q 0.75 G 0 i 2.5 w 1 J 4 M 1.9619 11.7559 m 1.9619 3.3037 |
| 1042 |
1.9619 2.5059 v 1.9619 1.707 4.0947 1.25 y 7.4141 1.25 l 9.4292 |
| 1043 |
1.8223 9.4292 3.3066 v 9.4292 4.79 9.4292 16.8945 y 9.7852 |
| 1044 |
18.1514 8.481 18.1514 v 7.1768 18.1514 5.1616 18.1514 y 3.8574 |
| 1045 |
17.9209 3.8574 16.8945 v 3.8574 15.8652 3.8574 6.6172 y 4.3325 |
| 1046 |
5.418 5.1025 5.418 v 5.8726 5.418 6.5845 5.418 y 7.6812 5.6455 |
| 1047 |
7.6812 6.4736 v 7.6812 7.3027 7.6812 11.5264 y S 0 G 1.2495 |
| 1048 |
12.4404 m 1.2495 3.9883 1.2495 3.1895 v 1.2495 2.3906 3.3833 |
| 1049 |
1.9326 y 6.7026 1.9326 l 8.7178 2.5068 8.7178 3.9902 v 8.7178 |
| 1050 |
5.4736 8.7178 17.5781 y 9.0732 18.834 7.769 18.834 v 6.4653 |
| 1051 |
18.834 4.4497 18.834 y 3.146 18.6055 3.146 17.5781 v 3.146 |
| 1052 |
16.5498 3.146 7.3018 y 3.6201 6.1016 4.3911 6.1016 v 5.1611 |
| 1053 |
6.1016 5.873 6.1016 y 6.9692 6.3301 6.9692 7.1572 v 6.9692 |
| 1054 |
7.9863 6.9692 12.21 y S \atfi@color@rgb\space RG 1 w |
| 1055 |
1.2495 12.4404 m 1.2495 3.9883 1.2495 3.1895 v 1.2495 2.3906 |
| 1056 |
3.3833 1.9326 y 6.7026 1.9326 l 8.7178 2.5068 8.7178 3.9902 v |
| 1057 |
8.7178 5.4736 8.7178 17.5781 y 9.0732 18.834 7.769 18.834 v |
| 1058 |
6.4653 18.834 4.4497 18.834 y 3.146 18.6055 3.146 17.5781 v |
| 1059 |
3.146 16.5498 3.146 7.3018 y 3.6201 6.1016 4.3911 6.1016 v |
| 1060 |
5.1611 6.1016 5.873 6.1016 y 6.9692 6.3301 6.9692 7.1572 v |
| 1061 |
6.9692 7.9863 6.9692 12.21 y S Q |
| 1062 |
} |
| 1063 |
% \end{macrocode} |
| 1064 |
% \end{macro} |
| 1065 |
% |
| 1066 |
% \begin{macro}{\atfi@acroPaperclip} |
| 1067 |
% Draw |\atfi@acroPaperclip@data| in a box of the appropriate size. |
| 1068 |
% \begin{macrocode} |
| 1069 |
\DeclareRobustCommand{\atfi@acroPaperclip}{% |
| 1070 |
\raisebox{-1.25bp}{\parbox[b][21bp]{12bp}{% |
| 1071 |
\rule{0pt}{0pt}\pdfliteral{\atfi@acroPaperclip@data}}% |
| 1072 |
}% |
| 1073 |
} |
| 1074 |
% \end{macrocode} |
| 1075 |
% \end{macro} |
| 1076 |
% |
| 1077 |
% \begin{macro}{\atfi@acroPushPin@data} |
| 1078 |
% Recreate \adobeacrobat's \pdfname{PushPin} icon. |
| 1079 |
% \begin{macrocode} |
| 1080 |
\newcommand{\atfi@acroPushPin@data}{% |
| 1081 |
q \atfi@color@rgb\space rg 0 G 1 w 1 6 m 11 6 l 11 13 l 12 |
| 1082 |
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 |
| 1083 |
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 |
| 1084 |
12 12 m 14 10 l 22 10 l 22 11 l S Q |
| 1085 |
} |
| 1086 |
% \end{macrocode} |
| 1087 |
% \end{macro} |
| 1088 |
% |
| 1089 |
% \begin{macro}{\atfi@acroPushPin} |
| 1090 |
% Draw |\atfi@acroPushPin@data| in a box of the appropriate size. |
| 1091 |
% \begin{macrocode} |
| 1092 |
\DeclareRobustCommand{\atfi@acroPushPin}{% |
| 1093 |
\raisebox{-1.25bp}{\parbox[b][14bp]{24bp}{% |
| 1094 |
\rule{0pt}{0pt}\pdfliteral{\atfi@acroPushPin@data}}% |
| 1095 |
}% |
| 1096 |
} |
| 1097 |
% \end{macrocode} |
| 1098 |
% \end{macro} |
| 1099 |
% |
| 1100 |
% \begin{macro}{\atfi@acroTag@data} |
| 1101 |
% Recreate \adobeacrobat's \pdfname{Tag} icon. |
| 1102 |
% \begin{macrocode} |
| 1103 |
\newcommand{\atfi@acroTag@data}{% |
| 1104 |
q 0.5 g 10.0542 14.9873 m 24.27 14.9873 l 25.252 14.0059 l |
| 1105 |
25.252 1.1455 l 24.1064 0 l 9.9609 0 l 6.0327 6.0088 l 6.0327 |
| 1106 |
9.002 l 10.0542 14.9873 l 9.3994 9.376 m 8.5215 9.376 7.8096 |
| 1107 |
8.5596 7.8096 7.5527 c 7.8096 6.5449 8.5215 5.7285 9.3994 |
| 1108 |
5.7285 c 10.2778 5.7285 10.9897 6.5449 10.9897 7.5527 c 10.9897 |
| 1109 |
8.5596 10.2778 9.376 9.3994 9.376 c h f |
| 1110 |
\atfi@color@rgb\space rg 0 G 0 i 0.5 w 4 M 1 j 8.5107 |
| 1111 |
16.5313 m 22.7266 16.5313 l 23.7085 15.5488 l 23.7085 2.6895 l |
| 1112 |
22.563 1.543 l 8.4175 1.543 l 4.4893 7.5527 l 4.4893 10.5449 l |
| 1113 |
8.5107 16.5313 l 7.856 10.9199 m 6.978 10.9199 6.2661 10.1035 |
| 1114 |
6.2661 9.0957 c 6.2661 8.0879 6.978 7.2715 7.856 7.2715 c |
| 1115 |
8.7344 7.2715 9.4463 8.0879 9.4463 9.0957 c 9.4463 10.1035 |
| 1116 |
8.7344 10.9199 7.856 10.9199 c h B 1 w 12.3291 12.2656 m |
| 1117 |
21.1206 12.2656 l S 12.3291 9.1797 m 21.1206 9.1797 l S 12.3291 |
| 1118 |
6.1875 m 21.1206 6.1875 l S 0 G 0.5 w 0 9.0488 m 6.2661 9.0957 |
| 1119 |
l S 1.4028 5.2148 m 1.4028 9.6094 l 1.6831 10.6387 2.4316 |
| 1120 |
10.6387 v 3.6475 10.6387 3.5542 9.0488 y S Q |
| 1121 |
} |
| 1122 |
% \end{macrocode} |
| 1123 |
% \end{macro} |
| 1124 |
% |
| 1125 |
% \begin{macro}{\atfi@acroTag} |
| 1126 |
% Draw |\atfi@acroTag@data| in a box of the appropriate size. |
| 1127 |
% \begin{macrocode} |
| 1128 |
\DeclareRobustCommand{\atfi@acroTag}{% |
| 1129 |
\raisebox{-1.6bp}{\parbox[b][17bp]{25bp}{% |
| 1130 |
\rule{0pt}{0pt}\pdfliteral{\atfi@acroTag@data}}% |
| 1131 |
}% |
| 1132 |
} |
| 1133 |
% \end{macrocode} |
| 1134 |
% \end{macro} |
| 1135 |
% |
| 1136 |
% |
| 1137 |
% \subsection{Helper routines} |
| 1138 |
% \label{sec:helper-routines} |
| 1139 |
% |
| 1140 |
% \begin{macro}{\atfi@temp@string} |
| 1141 |
% \begin{macro}{\atfi@pdfstringdef} |
| 1142 |
% This is the same as |\pdfstringdef|, except that it \emph{locally} |
| 1143 |
% defines its argument. For those of you who like analogies, |
| 1144 |
% |\atfi@pdfstringdef| is to |\def| as |\pdfstringdef| is to |\gdef|. |
| 1145 |
% \begin{macrocode} |
| 1146 |
\def\atfi@temp@string{} |
| 1147 |
\DeclareRobustCommand{\atfi@pdfstringdef}[2]{% |
| 1148 |
\pdfstringdef\atfi@temp@string{#2}% |
| 1149 |
\edef#1{\atfi@temp@string}% |
| 1150 |
} |
| 1151 |
% \end{macrocode} |
| 1152 |
% \end{macro} |
| 1153 |
% \end{macro} |
| 1154 |
% |
| 1155 |
% \begin{macro}{\c@atfi@tmp} |
| 1156 |
% Because \tex\ provides only a limited number of counters, we recycle a |
| 1157 |
% single counter, |atfi@tmp|, throughout the entire package whenever the |
| 1158 |
% need to perform arithmetic arises. |
| 1159 |
% \changes{v1.4}{2010/08/14}{Incorporated Martin M\"unch's reduction of |
| 1160 |
% the number of counters that \protect\pkgname{attachfile} uses from |
| 1161 |
% five to one} |
| 1162 |
% \begin{macro}{\theatfi@tmp} |
| 1163 |
% \changes{v1.7}{2015/09/30}{Made the package robust to redefinitions |
| 1164 |
% of \cs{@arabic}, such as those made by the \protect\pkgname{babel} |
| 1165 |
% package (reported by Jonas Olson and fixed by Heiko Oberdiek)} |
| 1166 |
% \begin{macrocode} |
| 1167 |
\newcounter{atfi@tmp} |
| 1168 |
\renewcommand*{\theatfi@tmp}{\the\value{atfi@tmp}} |
| 1169 |
% \end{macrocode} |
| 1170 |
% \end{macro} |
| 1171 |
% \end{macro} |
| 1172 |
% |
| 1173 |
% \begin{macro}{\atfi@embedfile} |
| 1174 |
% If the given file has not yet been embedded, embed it as a |
| 1175 |
% \acronym{PDF} \pdfname{EmbeddedFile} object, and store its object |
| 1176 |
% number in |\atfi@embedfile@|\meta{filename}. |
| 1177 |
% \changes{v1.3}{2007/01/15}{Included a \protect\pdfname{Params} |
| 1178 |
% dictionary describing the file's date, modification date, and size} |
| 1179 |
% \changes{v1.6}{2015/04/04}{Don't re-embed files that have already been |
| 1180 |
% embedded (feature proposed by Gareth Walker)} |
| 1181 |
% \begin{macrocode} |
| 1182 |
\DeclareRobustCommand{\atfi@embedfile}[1]{% |
| 1183 |
\expandafter\ifx\csname atfi@embed@file@#1\endcsname\relax |
| 1184 |
\immediate\pdfobj stream attr { |
| 1185 |
/Type /EmbeddedFile |
| 1186 |
\atfi@mimetype\space |
| 1187 |
\atfi@dlsize\space |
| 1188 |
/Params << |
| 1189 |
\atfi@credate\space |
| 1190 |
\atfi@moddate\space |
| 1191 |
\atfi@size\space |
| 1192 |
>> |
| 1193 |
} file {#1}% |
| 1194 |
\expandafter\xdef\csname atfi@embed@file@#1\endcsname{\the\pdflastobj}% |
| 1195 |
\fi |
| 1196 |
} |
| 1197 |
% \end{macrocode} |
| 1198 |
% \end{macro} |
| 1199 |
% |
| 1200 |
% \begin{macro}{\atfi@appearancewidth} |
| 1201 |
% \begin{macro}{\atfi@appearanceheight} |
| 1202 |
% \begin{macro}{\atfi@appearancedepth} |
| 1203 |
% \begin{macro}{\atfi@appearancebox} |
| 1204 |
% Each \acronym{PDF} annotation can an associated ``appearance''. In |
| 1205 |
% the \pkgname{attachfile} package, we store the appearance with the |
| 1206 |
% |\atfi@set@appearance| macro (below). As a side effect, |
| 1207 |
% |\atfi@set@appearance| stores the dimensions of its argument in |
| 1208 |
% |\atfi@appearancewidth|, |\atfi@appearanceheight|, and |
| 1209 |
% |\atfi@appearanceddepth| so that, later, we can allocate an |
| 1210 |
% appropriate amount of space for the file attachment icon to fit |
| 1211 |
% within. |\atfi@appearancebox| is a temporary storage location for the |
| 1212 |
% \tex\ box that will get converted to an \pdfname{XObject}. |
| 1213 |
% \begin{macrocode} |
| 1214 |
\newlength{\atfi@appearancewidth} |
| 1215 |
\newlength{\atfi@appearanceheight} |
| 1216 |
\newlength{\atfi@appearancedepth} |
| 1217 |
\newsavebox{\atfi@appearancebox} |
| 1218 |
% \end{macrocode} |
| 1219 |
% \end{macro} |
| 1220 |
% \end{macro} |
| 1221 |
% \end{macro} |
| 1222 |
% \end{macro} |
| 1223 |
% |
| 1224 |
% \begin{macro}{\atfi@set@appearance} |
| 1225 |
% \begin{macro}{\atfi@appearance@obj} |
| 1226 |
% |\atfi@set@appearance| stores its argument as a \acronym{PDF} |
| 1227 |
% \pdfname{XObject} for later referral by the file annotation's |
| 1228 |
% appearance dictionary. This serves two purposes: |
| 1229 |
% |
| 1230 |
% \begin{enumerate} |
| 1231 |
% \item It enables a \tex\ box with arbitrary contents to serve as the |
| 1232 |
% file attachment icon. |
| 1233 |
% \item It enables (generally older) \acronym{PDF} viewers that don't |
| 1234 |
% recognize the icon name to still display something meaningful. |
| 1235 |
% \end{enumerate} |
| 1236 |
% \changes{v1.9}{2016/09/16}{Removed redundant \string\texttt{/Subtype |
| 1237 |
% /Form} dictionary entries} |
| 1238 |
% \begin{macrocode} |
| 1239 |
\DeclareRobustCommand{\atfi@set@appearance}[1]{% |
| 1240 |
\savebox{\atfi@appearancebox}{#1}% |
| 1241 |
\settowidth{\atfi@appearancewidth}{\usebox{\atfi@appearancebox}}% |
| 1242 |
\settoheight{\atfi@appearanceheight}{\usebox{\atfi@appearancebox}}% |
| 1243 |
\settodepth{\atfi@appearancedepth}{\usebox{\atfi@appearancebox}}% |
| 1244 |
\immediate\pdfxform \atfi@appearancebox |
| 1245 |
\edef\atfi@appearanceobj{\the\pdflastxform}% |
| 1246 |
} |
| 1247 |
% \end{macrocode} |
| 1248 |
% \end{macro} |
| 1249 |
% \end{macro} |
| 1250 |
% |
| 1251 |
% \begin{macro}{\atfi@flags@to@int} |
| 1252 |
% \begin{macro}{\atfi@flags} |
| 1253 |
% Convert all our flag options from booleans into a single integer |
| 1254 |
% (|\atfi@flags|). |
| 1255 |
% \begin{macrocode} |
| 1256 |
\DeclareRobustCommand{\atfi@flags@to@int}{% |
| 1257 |
\setcounter{atfi@tmp}{0}% |
| 1258 |
\ifatfi@print |
| 1259 |
\addtocounter{atfi@tmp}{4}% |
| 1260 |
\fi |
| 1261 |
\ifatfi@zoom |
| 1262 |
\else |
| 1263 |
\addtocounter{atfi@tmp}{8}% |
| 1264 |
\fi |
| 1265 |
\edef\atfi@flags{\theatfi@tmp}% |
| 1266 |
} |
| 1267 |
% \end{macrocode} |
| 1268 |
% \end{macro} |
| 1269 |
% \end{macro} |
| 1270 |
% |
| 1271 |
% \begin{macro}{\atfi@insert@file@annot} |
| 1272 |
% \begin{macro}{\atfi@file} |
| 1273 |
% Insert a \acronym{PDF} \pdfname{FileAttachment} annotation that refers to the |
| 1274 |
% object created by |\atfi@embedfile|. \tex\ doesn't normally ``see'' |
| 1275 |
% a |\pdfannot|, so we have to explicitly allocate space for it. |
| 1276 |
% |\atfi@insert@file@annot| takes one argument, the name of the file |
| 1277 |
% to attach. This should be the same value that was passed to |
| 1278 |
% |\atfi@embedfile|. |
| 1279 |
% \changes{v1.3}{2007/01/15}{Made robust to running |
| 1280 |
% \protect\pkgname{hyperref} with \cs{Hy@unicodetrue}} |
| 1281 |
% \changes{v1.8}{2015/11/11}{Strip path names from included files. |
| 1282 |
% Mikkel Futtrup reported that path names often confuse PDF readers |
| 1283 |
% on tablets and smartphones} |
| 1284 |
% \changes{v1.9}{2016/09/16}{Correctly handle filenames that lack an |
| 1285 |
% extension} |
| 1286 |
% \begin{macrocode} |
| 1287 |
\DeclareRobustCommand{\atfi@insert@file@annot}[1]{% |
| 1288 |
\rule{0pt}{0pt}% |
| 1289 |
\bgroup\Hy@unicodefalse |
| 1290 |
\atfi@pdfstringdef\atfi@file{#1}% |
| 1291 |
\edef\next{\egroup |
| 1292 |
\def\noexpand\atfi@file{\atfi@file}% |
| 1293 |
}\next |
| 1294 |
\filename@parse{\atfi@file}% |
| 1295 |
\@ifundefined{filename@ext}{% |
| 1296 |
\edef\atfi@file{\filename@base}% |
| 1297 |
}{% |
| 1298 |
\edef\atfi@file{\filename@base.\filename@ext}% |
| 1299 |
}% |
| 1300 |
\ifatfi@appearance |
| 1301 |
% \end{macrocode} |
| 1302 |
% We currently use the same appearance for \textsf{N}ormal, |
| 1303 |
% \textsf{R}ollover, and \textsf{D}own, although future versions of |
| 1304 |
% \pkgname{attachfile} may provide support for different appearances. |
| 1305 |
% Although the PDF \acronym{PDF} specification claims that \textsf{R} |
| 1306 |
% and \textsf{D} appearances default to the \textsf{N} appearance, |
| 1307 |
% experience dictates otherwise. Hence, we explicitly specify all three |
| 1308 |
% appearances. |
| 1309 |
% ^^A |
| 1310 |
% \changes{v1.1}{2005/01/04}{Added explicit \protect\textsf{R}ollover |
| 1311 |
% and \protect\textsf{D}own appearances to work around browser bugs} |
| 1312 |
% \changes{v1.3}{2007/01/15}{Modified to include the modification date |
| 1313 |
% in the \protect\pdfname{FileAttachment} dictionary} |
| 1314 |
% \begin{macrocode} |
| 1315 |
\def\atfi@appearance@dict{% |
| 1316 |
/AP << |
| 1317 |
/N \atfi@appearanceobj\space 0 R |
| 1318 |
/R \atfi@appearanceobj\space 0 R |
| 1319 |
/D \atfi@appearanceobj\space 0 R |
| 1320 |
>>% |
| 1321 |
}% |
| 1322 |
\fi% |
| 1323 |
\pdfannot width \atfi@appearancewidth |
| 1324 |
height \atfi@appearanceheight |
| 1325 |
depth \atfi@appearancedepth { |
| 1326 |
/Subtype /FileAttachment |
| 1327 |
\atfi@appearance@dict\space |
| 1328 |
\atfi@author\space |
| 1329 |
\atfi@color\space |
| 1330 |
\atfi@date\space |
| 1331 |
\atfi@description\space |
| 1332 |
\atfi@icon\space |
| 1333 |
\atfi@moddate\space |
| 1334 |
\atfi@subject\space |
| 1335 |
/F \atfi@flags\space |
| 1336 |
/FS << |
| 1337 |
/Type /Filespec |
| 1338 |
/F (\atfi@file) |
| 1339 |
/EF << |
| 1340 |
/F \csname atfi@embed@file@#1\endcsname\space 0 R |
| 1341 |
>> |
| 1342 |
>> |
| 1343 |
}% |
| 1344 |
% \end{macrocode} |
| 1345 |
% |
| 1346 |
% Now, so \tex\ can budget space for the annotation, we insert some |
| 1347 |
% zero-width rules into the document. |
| 1348 |
% \begin{macrocode} |
| 1349 |
\rule{0pt}{\atfi@appearanceheight}% |
| 1350 |
\rule[-\atfi@appearancedepth]{0pt}{\atfi@appearancedepth}% |
| 1351 |
\rule{\atfi@appearancewidth}{0pt}% |
| 1352 |
} |
| 1353 |
% \end{macrocode} |
| 1354 |
% \end{macro} |
| 1355 |
% \end{macro} |
| 1356 |
% |
| 1357 |
% \begin{macro}{\atfi@attachfile} |
| 1358 |
% This macro does all the work of the |\attachfile| author command. |
| 1359 |
% |\attachfile| began a group in which most special characters are set |
| 1360 |
% to category code ``other''. |\atfi@attachfile| reads the filename |
| 1361 |
% within this group, embeds the corresponding file into the generated |
| 1362 |
% \acronym{PDF} file, and places an icon at the current location. Then, |
| 1363 |
% it ends the group, thereby restoring the original category codes. |
| 1364 |
% \changes{v1.9}{2016/09/16}{Issue an error if the requested icon isn't found} |
| 1365 |
% \begin{macrocode} |
| 1366 |
\def\atfi@attachfile#1#2{% |
| 1367 |
\setkeys{AtFi}{#1}% |
| 1368 |
\atfi@embedfile{#2}% |
| 1369 |
\@ifundefined{atfi@acro\atfi@icon@icon}{% |
| 1370 |
\PackageError{attachfile}{Icon not found}{% |
| 1371 |
attachfile defines only the following icons:\MessageBreak |
| 1372 |
Graph, Paperclip, PushPin, Tag |
| 1373 |
}% |
| 1374 |
}{}% |
| 1375 |
\atfi@set@appearance{\csname atfi@acro\atfi@icon@icon\endcsname}% |
| 1376 |
\atfi@flags@to@int% |
| 1377 |
\atfi@insert@file@annot{#2}% |
| 1378 |
\endgroup |
| 1379 |
} |
| 1380 |
% \end{macrocode} |
| 1381 |
% \end{macro} |
| 1382 |
% |
| 1383 |
% \begin{macro}{\atfi@textattachfile} |
| 1384 |
% All this macro does is evaluate its second argument (a filename) |
| 1385 |
% within the group begun by |\textattachfile| then pass control to |
| 1386 |
% |\atfi@textattachfile@i|, which does all the work. |
| 1387 |
% |\atfi@textattachfile| is needed to force the filename to be evaluated |
| 1388 |
% while special characters are set to use category code ``other''. |
| 1389 |
% \begin{macrocode} |
| 1390 |
\def\atfi@textattachfile#1#2{% |
| 1391 |
\endgroup |
| 1392 |
\atfi@textattachfile@i{#1}{#2}% |
| 1393 |
} |
| 1394 |
% \end{macrocode} |
| 1395 |
% \end{macro} |
| 1396 |
% |
| 1397 |
% \begin{macro}{\atfi@textattachfile@i} |
| 1398 |
% \begin{macro}{\atfi@textcolor} |
| 1399 |
% This macro does all the work of the |\textattachfile| author command. |
| 1400 |
% Given a filename, some arbitrary text, and an optional set of |
| 1401 |
% attachment options, embed the corresponding file into the generated |
| 1402 |
% \acronym{PDF} file, and use the text as the icon. We recycle the icon |
| 1403 |
% color for the text. Note that the |\strut| is a bug workaround; I |
| 1404 |
% don't know whose fault this is, but the bottom point or so of the text |
| 1405 |
% seems to get cut off. Weird. |
| 1406 |
% \begin{macrocode} |
| 1407 |
\def\atfi@textattachfile@i#1#2#3{% |
| 1408 |
\setkeys{AtFi}{#1}% |
| 1409 |
\atfi@embedfile{#2}% |
| 1410 |
\def\atfi@textcolor(##1 ##2 ##3)##4{% |
| 1411 |
\textcolor[rgb]{##1,##2,##3}{##4}}% |
| 1412 |
\atfi@set@appearance{% |
| 1413 |
\expandafter\atfi@textcolor\expandafter |
| 1414 |
(\atfi@color@rgb){#3\strut}}% |
| 1415 |
\atfi@flags@to@int |
| 1416 |
\atfi@insert@file@annot{#2}% |
| 1417 |
\endgroup |
| 1418 |
} |
| 1419 |
% \end{macrocode} |
| 1420 |
% \end{macro} |
| 1421 |
% \end{macro} |
| 1422 |
% |
| 1423 |
% \begin{macro}{\atfi@pdf@slash} |
| 1424 |
% The \acronym{PDF} specification dictates that \acronym{MIME} types be |
| 1425 |
% specified not as strings (e.g.,~``|(Hello)|'') but rather as |
| 1426 |
% \acronym{PDF} names (e.g.,~``|/Hello|''). The catch is that the |
| 1427 |
% forward slash---required in all \acronym{MIME} types---cannot be part |
| 1428 |
% of a \acronym{PDF} name. The solution is to replace the |
| 1429 |
% \acronym{MIME} ``|/|'' with the hexadecimal sequence ``|#2f|''. |
| 1430 |
% Unfortunately, \pdflatex\ replaces ``|#|'' with ``|##|'' in a |
| 1431 |
% |\pdfobj| but leaves ``|\#|'' as is. The solution is to play some |
| 1432 |
% games with \tex\ to define |\atfi@pdf@slash| as a ``|#2f|'' sequence |
| 1433 |
% that can used within |\pdfobj|. |
| 1434 |
% \begin{macrocode} |
| 1435 |
\bgroup |
| 1436 |
\lccode`\@=`\# |
| 1437 |
\lowercase{\gdef\atfi@pdf@slash{@2f}} |
| 1438 |
\egroup |
| 1439 |
% \end{macrocode} |
| 1440 |
% \end{macro} |
| 1441 |
% |
| 1442 |
% \begin{macro}{\atfi@split@mimetype} |
| 1443 |
% \begin{macro}{\atfi@mime@type} |
| 1444 |
% \begin{macro}{\atfi@mime@subtype} |
| 1445 |
% Split a \acronym{MIME} type (e.g.,~``\texttt{image\slash jpeg}'') into |
| 1446 |
% a type, |\atfi@mime@type| (e.g.,~``|image|''), and a subtype, |
| 1447 |
% |\atfi@mime@subtype| (e.g.,~``|jpeg|''). |
| 1448 |
% \begin{macrocode} |
| 1449 |
\def\atfi@split@mimetype#1/#2/{% |
| 1450 |
\def\atfi@mime@type{#1}% |
| 1451 |
\def\atfi@mime@subtype{#2}% |
| 1452 |
} |
| 1453 |
% \end{macrocode} |
| 1454 |
% \end{macro} |
| 1455 |
% \end{macro} |
| 1456 |
% \end{macro} |
| 1457 |
% |
| 1458 |
% |
| 1459 |
% \subsection{Annotation option processing} |
| 1460 |
% \label{sec:annot-options} |
| 1461 |
% |
| 1462 |
% We start by defining the various options that |\attachfile| accepts |
| 1463 |
% and their default values. |
| 1464 |
% |
| 1465 |
% \begin{macro}{\atfi@mimetype} |
| 1466 |
% Declare the \acronym{MIME} type of the attached file. |
| 1467 |
% For example, ``\texttt{text/plain}'' |
| 1468 |
% would specify that the attachment is an ordinary text file. |
| 1469 |
% \changes{v1.2a}{2006/03/28}{Changed the \string\acronym{MIME} |
| 1470 |
% \string\pdfname{Subtype} from a string to a name} |
| 1471 |
% \begin{macrocode} |
| 1472 |
\def\atfi@mimetype{} |
| 1473 |
\define@key{AtFi}{mimetype}{% |
| 1474 |
\atfi@pdfstringdef\atfi@mimetype{#1}% |
| 1475 |
\atfi@split@mimetype#1/% |
| 1476 |
\edef\atfi@mimetype{% |
| 1477 |
/Subtype /\atfi@mime@type\atfi@pdf@slash\atfi@mime@subtype |
| 1478 |
}% |
| 1479 |
} |
| 1480 |
% \end{macrocode} |
| 1481 |
% \end{macro} |
| 1482 |
% |
| 1483 |
% \begin{macro}{\atfi@icon} |
| 1484 |
% \begin{macro}{\atfi@icon@icon} |
| 1485 |
% Specify an icon to represent the attachment. This should be one of |
| 1486 |
% \pdfname{Graph}, \pdfname{Paperclip}, \pdfname{PushPin} (the default), |
| 1487 |
% or \pdfname{Tag}. |\atfi@icon| is an attribute/value pair that gets |
| 1488 |
% inserted directly into the file attachment object. |\atfi@icon@icon| |
| 1489 |
% is only the icon name itself and is used to insert a static graphic |
| 1490 |
% that represents \adobeacrobat's rendition of a file attachment icon. |
| 1491 |
% \begin{macrocode} |
| 1492 |
\define@key{AtFi}{icon}{% |
| 1493 |
\def\atfi@icon{/Name /#1}% |
| 1494 |
\def\atfi@icon@icon{#1}% |
| 1495 |
} |
| 1496 |
\setkeys{AtFi}{icon=PushPin} |
| 1497 |
% \end{macrocode} |
| 1498 |
% \end{macro} |
| 1499 |
% \end{macro} |
| 1500 |
% |
| 1501 |
% \begin{macro}{\atfi@color} |
| 1502 |
% \begin{macro}{\atfi@color@rgb} |
| 1503 |
% Specify the color of the attachment icon as an \acronym{RGB} triplet. |
| 1504 |
% For example, ``\texttt{0 0.3 0}'' would be a fairly dark green. |
| 1505 |
% |\atfi@color| is an attribute/value pair that gets inserted directly |
| 1506 |
% into the file attachment object. It defaults to the empty string, |
| 1507 |
% which means the \acronym{PDF} viewer gets to choose what color the |
| 1508 |
% icon should be. |\atfi@color@rgb| is only the \acronym{RGB} triplet |
| 1509 |
% itself and is used to insert a static graphic that represents |
| 1510 |
% \adobeacrobat's rendition of a file attachment icon. It defaults to a |
| 1511 |
% beige color. |
| 1512 |
% \begin{macrocode} |
| 1513 |
\define@key{AtFi}{color}{% |
| 1514 |
\def\atfi@color{/C [#1]}% |
| 1515 |
\def\atfi@color@rgb{#1}% |
| 1516 |
} |
| 1517 |
\setkeys{AtFi}{color=1 0.9255 0.7765} |
| 1518 |
% \end{macrocode} |
| 1519 |
% \end{macro} |
| 1520 |
% \end{macro} |
| 1521 |
% |
| 1522 |
% \begin{macro}{\atfi@author} |
| 1523 |
% Specify the author of the annotation. \adobeacrobat shows this when |
| 1524 |
% you right-click on the annotation and choose \menuname{Properties}. |
| 1525 |
% \begin{macrocode} |
| 1526 |
\def\atfi@author{} |
| 1527 |
\define@key{AtFi}{author}[]{% |
| 1528 |
\edef\atfi@author{/T (#1)}% |
| 1529 |
} |
| 1530 |
% \end{macrocode} |
| 1531 |
% \end{macro} |
| 1532 |
% |
| 1533 |
% \begin{macro}{\atfi@pad@ii} |
| 1534 |
% Pad a number to exactly two digits. This is used by |\atfi@date| (below). |
| 1535 |
% \begin{macrocode} |
| 1536 |
\def\atfi@pad@ii#1{% |
| 1537 |
\ifnum#1>9 |
| 1538 |
#1% |
| 1539 |
\else |
| 1540 |
0#1% |
| 1541 |
\fi |
| 1542 |
} |
| 1543 |
% \end{macrocode} |
| 1544 |
% \end{macro} |
| 1545 |
% |
| 1546 |
% \begin{macro}{\atfi@timezone} |
| 1547 |
% Specify the timezone to attach to the file modification date. It |
| 1548 |
% would be awfully nice if \tex\ had some way to produce this |
| 1549 |
% automatically. (Does it?) |
| 1550 |
% \begin{macrocode} |
| 1551 |
\def\atfi@timezone{} |
| 1552 |
\define@key{AtFi}{timezone}{\def\atfi@timezone{#1}} |
| 1553 |
% \end{macrocode} |
| 1554 |
% \end{macro} |
| 1555 |
% |
| 1556 |
% \begin{macro}{\atfi@time} |
| 1557 |
% \begin{macro}{\atfi@hours} |
| 1558 |
% \begin{macro}{\atfi@minutes} |
| 1559 |
% \begin{macro}{\atfi@date} |
| 1560 |
% The date the annotation was last modified. It's unlikely you'd |
| 1561 |
% want to specify this explicitly in your \latex\ document, but |
| 1562 |
% if you want to, you can. Seconds are hardwired to zero, and the |
| 1563 |
% time zone must be manually specified. (I don't believe \tex\ makes either |
| 1564 |
% of those available.) Note that |\time| is stored in |
| 1565 |
% |\atfi@time| in case the minutes roll over during the time calculations. |
| 1566 |
% I was too lazy to do the same for |\day|, |\month|, and |\year|, so |
| 1567 |
% don't process your \latex\ document at midnight if you want to get a |
| 1568 |
% correct datestamp. |
| 1569 |
% \changes{v1.3}{2007/01/15}{Made robust to running |
| 1570 |
% \protect\pkgname{hyperref} with |
| 1571 |
% \protect\texttt{\protect\string\protect\Hy@unicodetrue}} |
| 1572 |
% \begin{macrocode} |
| 1573 |
\edef\atfi@time{\time} |
| 1574 |
\setcounter{atfi@tmp}{\atfi@time/60} |
| 1575 |
\edef\atfi@hours{\theatfi@tmp} |
| 1576 |
\setcounter{atfi@tmp}{\atfi@time-\atfi@hours*60} |
| 1577 |
\edef\atfi@minutes{\theatfi@tmp} |
| 1578 |
\def\atfi@date{% |
| 1579 |
/M (D:\the\year% |
| 1580 |
\expandafter\atfi@pad@ii\the\month |
| 1581 |
\expandafter\atfi@pad@ii\the\day |
| 1582 |
\atfi@pad@ii\atfi@hours |
| 1583 |
\atfi@pad@ii\atfi@minutes |
| 1584 |
00% |
| 1585 |
\atfi@timezone)% |
| 1586 |
} |
| 1587 |
\define@key{AtFi}{date}{% |
| 1588 |
\bgroup \Hy@unicodefalse |
| 1589 |
\atfi@pdfstringdef\atfi@date{#1}% |
| 1590 |
\edef\next{\egroup |
| 1591 |
\def\noexpand\atfi@date{/M (\atfi@date)}% |
| 1592 |
}\next |
| 1593 |
} |
| 1594 |
% \end{macrocode} |
| 1595 |
% \end{macro} |
| 1596 |
% \end{macro} |
| 1597 |
% \end{macro} |
| 1598 |
% \end{macro} |
| 1599 |
% |
| 1600 |
% \begin{macro}{\atfi@description} |
| 1601 |
% Store the annotation's description. \adobeacrobat shows this when you |
| 1602 |
% right-click on the annotation and choose \menuname{Properties}. It |
| 1603 |
% also shows it in the Annotations tab once you ``Rescan Document''. |
| 1604 |
% \begin{macrocode} |
| 1605 |
\def\atfi@description{} |
| 1606 |
\define@key{AtFi}{description}{% |
| 1607 |
\atfi@pdfstringdef\atfi@description{#1}% |
| 1608 |
\edef\atfi@description{/Contents (\atfi@description)}% |
| 1609 |
} |
| 1610 |
% \end{macrocode} |
| 1611 |
% \end{macro} |
| 1612 |
% |
| 1613 |
% \begin{macro}{\atfi@subject} |
| 1614 |
% Store the annotation's subject. \adobeacrobat shows this when you |
| 1615 |
% right-click on the annotation and choose \menuname{Properties}. It |
| 1616 |
% also shows it in the Annotations tab once you ``Rescan Document''. |
| 1617 |
% \changes{v1.1}{2005/01/04}{Added support for specifying the subject of |
| 1618 |
% an annotation} |
| 1619 |
% \begin{macrocode} |
| 1620 |
\def\atfi@subject{} |
| 1621 |
\define@key{AtFi}{subject}{% |
| 1622 |
\atfi@pdfstringdef\atfi@subject{#1}% |
| 1623 |
\edef\atfi@subject{/Subj (\atfi@subject)}% |
| 1624 |
} |
| 1625 |
% \end{macrocode} |
| 1626 |
% \end{macro} |
| 1627 |
% |
| 1628 |
% \begin{macro}{\atfi@credate} |
| 1629 |
% Store the annotation's creation date. \adobeacrobat shows this when |
| 1630 |
% you right-click on the annotation and choose \menuname{Properties}. |
| 1631 |
% It also shows it in the Annotations tab once you ``Rescan Document''. |
| 1632 |
% Note that creation date is a \acronym{PDF}~1.5 feature. |
| 1633 |
% \changes{v1.3}{2007/01/15}{Added support for specifying the creation |
| 1634 |
% date of an annotation} |
| 1635 |
% \begin{macrocode} |
| 1636 |
\def\atfi@credate{} |
| 1637 |
\define@key{AtFi}{created}{% |
| 1638 |
\bgroup \Hy@unicodefalse |
| 1639 |
\atfi@pdfstringdef\atfi@credate{#1}% |
| 1640 |
\edef\next{\egroup |
| 1641 |
\def\noexpand\atfi@credate{/CreationDate (\atfi@credate)}% |
| 1642 |
}\next |
| 1643 |
} |
| 1644 |
% \end{macrocode} |
| 1645 |
% \end{macro} |
| 1646 |
% |
| 1647 |
% \begin{macro}{\atfi@moddate} |
| 1648 |
% Store the annotation's modification date. \adobeacrobat shows this when |
| 1649 |
% you right-click on the annotation and choose \menuname{Properties}. |
| 1650 |
% It also shows it in the Annotations tab once you ``Rescan Document''. |
| 1651 |
% Note that modification date is a \acronym{PDF}~1.5 feature. |
| 1652 |
% \changes{v1.3}{2007/01/15}{Added support for specifying the modification |
| 1653 |
% date of an annotation} |
| 1654 |
% \begin{macrocode} |
| 1655 |
\def\atfi@moddate{} |
| 1656 |
\define@key{AtFi}{modified}{% |
| 1657 |
\bgroup \Hy@unicodefalse |
| 1658 |
\atfi@pdfstringdef\atfi@moddate{#1}% |
| 1659 |
\edef\next{\egroup |
| 1660 |
\def\noexpand\atfi@moddate{/ModDate (\atfi@moddate)}% |
| 1661 |
}\next |
| 1662 |
} |
| 1663 |
% \end{macrocode} |
| 1664 |
% \end{macro} |
| 1665 |
% |
| 1666 |
% \begin{macro}{\atfi@size} |
| 1667 |
% \begin{macro}{\atfi@dlsize} |
| 1668 |
% Store the annotation's file size. \adobeacrobat shows this when |
| 1669 |
% you right-click on the annotation and choose \menuname{Properties}. |
| 1670 |
% It also shows it in the Annotations tab once you ``Rescan Document''. |
| 1671 |
% Note that file size is a \acronym{PDF}~1.5 feature. |
| 1672 |
% \changes{v1.3}{2007/01/15}{Added support for specifying the file size |
| 1673 |
% of an annotation} |
| 1674 |
% \begin{macrocode} |
| 1675 |
\def\atfi@size{} |
| 1676 |
\def\atfi@dlsize{} |
| 1677 |
\define@key{AtFi}{size}{% |
| 1678 |
\bgroup \Hy@unicodefalse |
| 1679 |
\atfi@pdfstringdef\atfi@size{#1}% |
| 1680 |
\edef\next{\egroup |
| 1681 |
\def\noexpand\atfi@size{/Size \atfi@size}% |
| 1682 |
\def\noexpand\atfi@dlsize{/DL \atfi@size}% |
| 1683 |
}\next |
| 1684 |
} |
| 1685 |
% \end{macrocode} |
| 1686 |
% \end{macro} |
| 1687 |
% \end{macro} |
| 1688 |
% |
| 1689 |
% \begin{macro}{\ifatfi@print} |
| 1690 |
% \begin{macro}{\atfi@printtrue} |
| 1691 |
% \begin{macro}{\atfi@printfalse} |
| 1692 |
% By default, file annotation icons print along with the rest of |
| 1693 |
% the document. (In \adobeacrobat, that's the case if and only if the |
| 1694 |
% Annotations box is checked in the \Acrobatmenu{Print}{Print dialog}.) |
| 1695 |
% By setting \texttt{print=false}, the icons will not print. |
| 1696 |
% \begin{macrocode} |
| 1697 |
\newif\ifatfi@print |
| 1698 |
\atfi@printtrue |
| 1699 |
\define@key{AtFi}{print}[true]{\csname atfi@print#1\endcsname} |
| 1700 |
% \end{macrocode} |
| 1701 |
% \end{macro} |
| 1702 |
% \end{macro} |
| 1703 |
% \end{macro} |
| 1704 |
% |
| 1705 |
% \begin{macro}{\ifatfi@zoom} |
| 1706 |
% \begin{macro}{\atfi@zoomtrue} |
| 1707 |
% \begin{macro}{\atfi@zoomfalse} |
| 1708 |
% By default, file annotation icons zoom along with the rest of |
| 1709 |
% the document. By setting \texttt{zoom=false}, the icons will |
| 1710 |
% remain at a constant size, regardless of magnification. |
| 1711 |
% \begin{macrocode} |
| 1712 |
\newif\ifatfi@zoom |
| 1713 |
\atfi@zoomtrue |
| 1714 |
\define@key{AtFi}{zoom}[true]{\csname atfi@zoom#1\endcsname} |
| 1715 |
% \end{macrocode} |
| 1716 |
% \end{macro} |
| 1717 |
% \end{macro} |
| 1718 |
% \end{macro} |
| 1719 |
% |
| 1720 |
% \begin{macro}{\ifatfi@appearance} |
| 1721 |
% \begin{macro}{\atfi@appearancetrue} |
| 1722 |
% \begin{macro}{\atfi@appearancefalse} |
| 1723 |
% \begin{macro}{\atfi@appearance@dict} |
| 1724 |
% The \pkgname{attachfile} package normally embeds an icon graphic in |
| 1725 |
% each file attachment annotation's appearance dictionary. By setting |
| 1726 |
% \texttt{appearance=false}, no appearance dictionary will be added to a |
| 1727 |
% file attachment annotation; the \acronym{PDF} viewer will need to |
| 1728 |
% decide for itself how to display the icon. |
| 1729 |
% \begin{macrocode} |
| 1730 |
\newif\ifatfi@appearance |
| 1731 |
\atfi@appearancetrue |
| 1732 |
\def\atfi@appearance@dict{} |
| 1733 |
\define@key{AtFi}{appearance}[true]{\csname atfi@appearance#1\endcsname} |
| 1734 |
% \end{macrocode} |
| 1735 |
% \end{macro} |
| 1736 |
% \end{macro} |
| 1737 |
% \end{macro} |
| 1738 |
% \end{macro} |
| 1739 |
% |
| 1740 |
% |
| 1741 |
% \subsection{Author commands} |
| 1742 |
% |
| 1743 |
% The commands described in this section are those available to |
| 1744 |
% the user writing a \latex\ document. If the macros seem too simple, |
| 1745 |
% it's because all the work is performed by the helper routines |
| 1746 |
% in Section~\ref{sec:helper-routines} and the option-processing |
| 1747 |
% routines in Section~\ref{sec:annot-options}. |
| 1748 |
% |
| 1749 |
% \begin{macro}{\attachfilesetup} |
| 1750 |
% Set default values for all the various annotation options. |
| 1751 |
% \begin{macrocode} |
| 1752 |
\DeclareRobustCommand{\attachfilesetup}[1]{\setkeys{AtFi}{#1}} |
| 1753 |
% \end{macrocode} |
| 1754 |
% \end{macro} |
| 1755 |
% |
| 1756 |
% \begin{macro}{\attachfile} |
| 1757 |
% Given a filename and an optional set of attachment options, embed the |
| 1758 |
% corresponding file into the generated \acronym{PDF} file, and place an |
| 1759 |
% icon at the current location. The real work is performed by |
| 1760 |
% |\atfi@attachfile|. |\attachfile| merely sets up the category codes |
| 1761 |
% in such a way as to allow filenames to contain special characters such |
| 1762 |
% as underscores. |
| 1763 |
% \changes{v1.5}{2010/08/27}{Reset ``\texttt{\char`\\}'' to category |
| 1764 |
% code~0 to enable the use of \cs{jobname} in the name of the file |
| 1765 |
% attachment (suggested by Felix Mueller-Sarnowski)} |
| 1766 |
% \begin{macrocode} |
| 1767 |
\DeclareRobustCommand{\attachfile}[1][]{% |
| 1768 |
\begingroup |
| 1769 |
\let\do\@makeother |
| 1770 |
\dospecials |
| 1771 |
\catcode`\\=0\relax |
| 1772 |
\catcode`\{=1\relax |
| 1773 |
\catcode`\}=2\relax |
| 1774 |
\atfi@attachfile{#1}% |
| 1775 |
} |
| 1776 |
% \end{macrocode} |
| 1777 |
% \end{macro} |
| 1778 |
% |
| 1779 |
% \begin{macro}{\textattachfile} |
| 1780 |
% Given a filename, some arbitrary text, and an optional set of |
| 1781 |
% attachment options, embed the corresponding file into the generated |
| 1782 |
% \acronym{PDF} file, and use the text as the icon. After setting up |
| 1783 |
% the category codes to use for processing the filename, |
| 1784 |
% |\textattachfile| passes to control to |\atfi@textattachfile|, which |
| 1785 |
% resets the category codes, and then to |\atfi@textattachfile@i|, which |
| 1786 |
% does all the work. We define two groups: one for keeping the |
| 1787 |
% attachment options local and one for temporarily altering category |
| 1788 |
% codes. |
| 1789 |
% \changes{v1.5b}{2011/03/27}{Reset ``\texttt{\char`\\}'' |
| 1790 |
% to category code~0 to enable the use of |
| 1791 |
% \texttt{\string\string\string\jobname} in the name of the file |
| 1792 |
% attachment for compatibility with \texttt{\string\string\string\attachfile} |
| 1793 |
% (reported by Uwe Bieling)} |
| 1794 |
% \begin{macrocode} |
| 1795 |
\DeclareRobustCommand{\textattachfile}[1][]{% |
| 1796 |
\begingroup |
| 1797 |
\begingroup |
| 1798 |
\let\do\@makeother |
| 1799 |
\dospecials |
| 1800 |
\catcode`\\=0\relax |
| 1801 |
\catcode`\{=1\relax |
| 1802 |
\catcode`\}=2\relax |
| 1803 |
\atfi@textattachfile{#1}% |
| 1804 |
} |
| 1805 |
% \end{macrocode} |
| 1806 |
% \end{macro} |
| 1807 |
% |
| 1808 |
% \begin{macro}{\noattachfile} |
| 1809 |
% Insert the same icon into the document that we would for an |
| 1810 |
% |\attachfile| call. This is useful for writing documentation that |
| 1811 |
% instructs a user on how to deal with file attachments. |
| 1812 |
% |\noattachfile| is fairly simple; is just calls |\setkeys| in order to |
| 1813 |
% get the latest values of |\atfi@icon@icon| and |\atfi@color@rgb|, |
| 1814 |
% and then it defers to one of |\atfi@acroGraph|, |\atfi@acroPaperclip|, |
| 1815 |
% |\atfi@acroPushPin|, or |\atfi@acroTag|, which do the actual |
| 1816 |
% rendering work. |
| 1817 |
% ^^A |
| 1818 |
% \changes{v1.1}{2005/01/04}{Modified to leave space on the page when |
| 1819 |
% \protect\texttt{print\protect\actualchar false} is passed as an option} |
| 1820 |
% \begin{macrocode} |
| 1821 |
\DeclareRobustCommand{\noattachfile}[1][]{% |
| 1822 |
\begingroup |
| 1823 |
\setkeys{AtFi}{#1}% |
| 1824 |
\ifatfi@print |
| 1825 |
\csname atfi@acro\atfi@icon@icon\endcsname |
| 1826 |
\else |
| 1827 |
\setbox0=\hbox{\csname atfi@acro\atfi@icon@icon\endcsname}% |
| 1828 |
\makebox[\wd0]{}% |
| 1829 |
\fi |
| 1830 |
\endgroup |
| 1831 |
} |
| 1832 |
% \end{macrocode} |
| 1833 |
% \end{macro} |
| 1834 |
% |
| 1835 |
% \begin{macro}{\notextattachfile} |
| 1836 |
% Insert the same text into the document that we would for a |
| 1837 |
% |\textattachfile| call. This is useful for writing documentation that |
| 1838 |
% instructs a user on how to deal with file attachments. |
| 1839 |
% \changes{v1.1}{2005/01/04}{Created this function} |
| 1840 |
% \begin{macrocode} |
| 1841 |
\DeclareRobustCommand{\notextattachfile}[2][]{% |
| 1842 |
\begingroup |
| 1843 |
\setkeys{AtFi}{#1}% |
| 1844 |
\ifatfi@print |
| 1845 |
\def\atfi@textcolor(##1 ##2 ##3)##4{% |
| 1846 |
\textcolor[rgb]{##1,##2,##3}{##4}}% |
| 1847 |
\expandafter\atfi@textcolor\expandafter |
| 1848 |
(\atfi@color@rgb){#2\strut}% |
| 1849 |
\else |
| 1850 |
\setbox0=\hbox{#2\strut}% |
| 1851 |
\makebox[\wd0]{}% |
| 1852 |
\fi |
| 1853 |
\endgroup |
| 1854 |
} |
| 1855 |
% \end{macrocode} |
| 1856 |
% \end{macro} |
| 1857 |
% |
| 1858 |
% |
| 1859 |
% \subsection{Dummy commands} |
| 1860 |
% \label{sec:dummy-commands} |
| 1861 |
% |
| 1862 |
% If the author is not using \pdflatex\ or \lualatex\ or not using it in |
| 1863 |
% \acronym{PDF}-generating mode, we replace the core |
| 1864 |
% \pkgname{attachfile} commands with dummy versions so \latex\ can at |
| 1865 |
% least run to completion. |
| 1866 |
% ^^A |
| 1867 |
% \changes{v1.1}{2005/01/04}{Wrote dummy versions of all the core macros |
| 1868 |
% to use in the absence of \protect\pdflatex\slash\protect\lualatex\ |
| 1869 |
% running in \protect\acronym{PDF}-generating mode.} |
| 1870 |
% |
| 1871 |
% \begin{macrocode} |
| 1872 |
\ifpdf |
| 1873 |
\else |
| 1874 |
% \end{macrocode} |
| 1875 |
% |
| 1876 |
% \begin{macro}{\atfi@dummy@pushpin} |
| 1877 |
% Define an empty space of approximately the same size as |
| 1878 |
% |\atfi@acroPushPin|. |
| 1879 |
% \begin{macrocode} |
| 1880 |
\def\atfi@dummy@pushpin{% |
| 1881 |
\raisebox{-1.25bp}{\parbox[b][14bp]{24bp}{}}% |
| 1882 |
} |
| 1883 |
% \end{macrocode} |
| 1884 |
% \end{macro} |
| 1885 |
% |
| 1886 |
% \begin{macro}{\textattachfile} |
| 1887 |
% Define a dummy |\textattachfile| in terms of |\notextattachfile|. |
| 1888 |
% \begin{macrocode} |
| 1889 |
\DeclareRobustCommand{\textattachfile}[3][]{% |
| 1890 |
\notextattachfile[#1]{#3}% |
| 1891 |
} |
| 1892 |
% \end{macrocode} |
| 1893 |
% \end{macro} |
| 1894 |
% |
| 1895 |
% \begin{macro}{\noattachfile} |
| 1896 |
% Define a dummy |\noattachfile| in terms of |\notextattachfile|. |
| 1897 |
% \begin{macrocode} |
| 1898 |
\DeclareRobustCommand{\noattachfile}[1][]{% |
| 1899 |
\notextattachfile[#1]{\atfi@dummy@pushpin}% |
| 1900 |
} |
| 1901 |
% \end{macrocode} |
| 1902 |
% \end{macro} |
| 1903 |
% |
| 1904 |
% \begin{macro}{\attachfile} |
| 1905 |
% Define a dummy |\attachfile| in terms of the dummy |\noattachfile|. |
| 1906 |
% \begin{macrocode} |
| 1907 |
\DeclareRobustCommand{\attachfile}[2][]{% |
| 1908 |
\noattachfile[#1]% |
| 1909 |
} |
| 1910 |
% \end{macrocode} |
| 1911 |
% \end{macro} |
| 1912 |
% |
| 1913 |
% \begin{macrocode} |
| 1914 |
\fi |
| 1915 |
% \end{macrocode} |
| 1916 |
% |
| 1917 |
% \iffalse |
| 1918 |
%</package> |
| 1919 |
% \fi |
| 1920 |
% |
| 1921 |
% \Finale |
| 1922 |
\endinput |