The attachle package
Scott Pakin
scott+af@pakin.org
March 27, 2011
Abstract
Thispackagedenesan\attachfilecommandthatletsyouattachar-
bitraryles to apdfdocument. Theselesareembeddedrightinthepdf
le,so theygettransmittedalongwithit. Thepackagealso givesyoucon-
trol over thecorresponding icon’s properties and various other associated
metadata.
1 Introduction
pdf, Adobe’sPortable Document Format, is acommonway to distribute docu-
ments that look the same on all platforms and output devices. Beginning with
pdf version 1.3, pdf supports \le attachment annotations". These are arbi-
trary auxiliary lesthat get embeddeddirectly into the pdf document, just like
attachmentsinane-mailmessage.
TheattachlepackagegivespdfLAT
E
Xuserstheabilitytoaddtheseattachments
to their documents automatically. And because LAT
E
X is a markup language,
not a wysiwyg tool, the user has precise control over the location of the le
attachment icons. If an icon representing an attached spreadsheet le isplaced
next toagure,theiconwill move alongwiththegurewheneverthedocument
ismodied. Furthermore, it ispossibleto dene globalpropertiesfor all the le
attachmentsinadocument. Withonecommand,ausercanchangetheproperties
ofalltheiconsintheentiredocument.
Finally,oneniftyfeaturethat attachlesupportsistheabilitytouseyourown
icons,whichcanbe text, graphics,tables,mathematics|younameit! Withthis
feature, a pdf le can, for example, instruct the reader to click on a formula
to extract the Mathematica notebook that derived it. Or to click on a graph
to extract the Microsoft Excel spreadsheet that contains all the data that was
plotted. Thepossiblitiesareendless.
Okay,let’sgetdowntobusiness. Herearesomesampleleattachmentssoyou
cansee if yourpdfviewer isabletohandlethem:
Thislehasversionnumberv1.5b,lastrevised2011/03/27.
1
Add image to pdf java - insert images into PDF in C#.net, ASP.NET, MVC, Ajax, WinForms, WPF
Sample C# code to add image, picture, logo or digital photo into PDF document page using PDF page editor control
pdf insert image; add photo to pdf online
Add image to pdf java - VB.NET PDF insert image library: insert images into PDF in vb.net, ASP.NET, MVC, Ajax, WinForms, WPF
Guide VB.NET Programmers How to Add Images in PDF Document
adding an image to a pdf; how to add an image to a pdf in reader
Icon:
(Shouldresemblethis:
)
L
A
T
E
Xtext:
(Shouldresemblethis:attachfile.bib)
Each of the above points to the BibT
E
Xbibliography (a plain text le) for the
documentyou’rereadingnow. Tryextractingtheattachment. InAdobeAcrobat,
thisisachievedbyright-clickingontheiconandchoosing\SaveEmbeddedFileto
Disk..." (orinolderversionsofAdobeAcrobat,\ExtractFile..."). Youcanalso
double-click toopenthe leimmediately. If you’re unable toaccesstheattached
le,or youobservemiscellaneousstrangebehavior,your pdfviewermightnot be
cabableofhandlingleattachmentsproperly. See Section5for some pdf viewer
problemsIencounteredwhile testing attachle.
2 Usage
Load attachle by putting a \usepackage{attachfile} in your document’s
preamble. attachleimplicitlyloadsavarietyofotherpackages. Section5presents
the complete list.
attachlev1.5bdoesnothaveanyofitsownpackageoptions;anyoptionsthat
get passed to attachle are forwarded to hyperref. Because hyperref worksbest
whenloadedasone of the last packagesinthe document the sameholdstruefor
attachle.
3 Commands
Thefollowingarethecommandsthatattachlemakesavailableforattachingles,
customizingtheiconappearance,andchangingvariousleattachmentmetadata.
\attachfile[hoptionsi]{hlenamei}
The\attachfilemacrohasonlyonerequiredargument: thenameofthele
toattach. \attachfilewillinsertaniconatthecurrentpointinthedocumentto
representthe attachment. hoptionsiisalistofoptionalparametersfordescribing
the iconandotherassortedmetadata. It isdescribedinSection4.
\noattachfile[hoptionsi]
When writing instructions, it is sometimes convenient to describe what a
le attachment icon looks like without actually attaching a le. That’s what
\noattachfileisfor. Allitdoesisinserttheimageofaleattachmenticoninto
the document. hoptionsi is a list of optional parameters for describing the icon
andother assortedmetadata. ItisdescribedinSection4. Inparticular,notethat
iftheprintoptionisset tofalse then\noattachfilewilloutput emptyspace
ofthesamesizeastheiconimage.
2
attachfile.bib
Java Imaging SDK Library: Document Image Scan, Process, PDF
imaging solutions, allowing developers to add document and Using RasterEdge Java Image SDK, developers can easily open Tiff, Jpeg2000, DICOM, JBIG2, PDF, MS Word
add photo to pdf for; add an image to a pdf with acrobat
Zero Footprint AJAX Document Image Viewer| ASP.NET Imaging SDK
Image Annotating Draw and add various text or graphics annotations on Converting Transform, convert and save web document or image file to PDF or TIFF
adding jpg to pdf; add photo to pdf in preview
\textattachfile[hoptionsi]{hlenamei}{htexti}
\textattachfile is just like \attachfile, except that instead of usingone
ofthepredenedpdficons,itletsyouuse anarbitrarypieceof texttorepresent
the attachment. The htexti parameter is not limited to text; it cancontain any
arbitraryhorizontalmaterial. Thefollowingarealllegalusesof\textattachfile:
 You can\textattachfile{myfile.cc}{extractmy source code}if your
PDF viewer supports file annotations.
 It is intuitively obvious to even the most casual observer that
\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}$}
 \textattachfile{earningsdata.csv}{\includegraphics{earnings}}
\notextattachfile[hoptionsi]{htexti}
Justas\noattachfileisadummyversionof\attachfile,so\notextattachfile
isadummyversionof \textattachfile. All \notextattachfile doesisinsert
htexti intothedocument according tohoptionsi (describedinSection4). Inpar-
ticular, note that if the print option is set to false then \notextattachfile
willoutputemptyspaceof thesame sizeashtexti.
\attachfilesetup{hoptionsi}
If yound yourself passing the same set of optionsto multiple \attachfile
callsinyour document, youcanuse\attachfilesetuptospecify defaultoption
values. \attachfilesetup’s hoptionsi parameter is the same as that used by
\attachfileandisdescribedinSection4. Somenoteworthypointsare:
1. \attachfilesetup can be called as many times as desired. Any options
speciedreplacethepreviousvalueofthoseoptions. Allunspeciedoptions
areleft alone.
2. Options passed to \attachfile take precedence over those specied by
\attachfilesetup. This lets you dene default values for all le attach-
mentsandselectively overridethemonaper-attachmentbasis.
3. Options set by \attachfilesetup are local to the current scope. This
lets you assign defaults to a group of le attachments without aecting
the global defaults. To dene optionsthat apply to the entire document,
\attachfilesetup should be called at the top-levelscope (which includes
thedocument’sprologue).
3
DocImage SDK for .NET: HTML Viewer, View, Annotate, Convert, Print
in .NET, including Microsoft Word, Excel, PPT, PDF, Tiff, Dicom OCR .NET OCR Add-on provides you with powerful and of years before I found this .NET Image SDK.
add jpg to pdf form; attach image to pdf form
.NET PDF SDK | Read & Processing PDF files
by this .NET Imaging PDF Reader Add-on. and metadata; Advanced document cleanup and image processing options provides royalty-free .NET Imaging PDF Reader SDK
how to add image to pdf; add jpg to pdf online
4 Options
attachlegivestheuseragreatdealofcontrolovertheway lesareattachedtoa
document. AllthecommandsinSection3accept the same set of options, which
areenteredascomma-separated,hkeyi=hvaluei pairs. Optionscanbespeciedin
any order. Case issignicant. Only the options youwant tochange need tobe
specied;theotherswillretaintheir previousvalue(or thedefault,ifnoprevious
valuewasspecied).
4.1 List of available options
Thefollowingaretheoptionsattachle accepts,inalphabeticalorder.
appearance=hbooleani
The attachle package normally embeds the le attachment’s icon explicitly
with each le attachment annotation. (In pdf-speak, it includes an appearance
dictionary in the FileAttachment object.) The advantages to doing this are to
ensurethat:
 Thele attachment iconslook the sameinallpdfviewers.
 T
E
X knows exactly how much space to allocate, instead of just guessing
basedonthesize of theAdobe Acrobat icons.
 Pre-1.3pdfviewersdon’tregresstoshowingan\unknownannotationtype"
graphic.
However,theproblemswithembeddingtheicongraphicare:
 It addsabitofextrabulk tothe pdf le.
 Ittakes exibilityawayfromthepdfviewer,whichcannolongerchoosefor
itselfhowbesttorender aleattachmenticon.
The appearance optiongivesthe author the ability toprevent theicon’sap-
pearancefrombeingspeciedexplicitlyinthepdfle. Bysettingappearance=false,
itwillbeleft uptothe pdfviewertodecidehowtodisplaytheicon.
author=htexti
Themetadataassociatedwithaleattachmentannotationincludesthename
ofthe personwhoattachedthele. InAdobe Acrobat,thisinformationisshown
when one right-clicks on the le attachment icon and selects Properties.... By
default,noauthorislistedbut specifyingauthor=hnamei setstheauthor eldto
hnamei.
4
.NET PDF Generator | Generate & Manipulate PDF files
RasterEdge .NET Image SDK - PDF Generator. swap and delete any pages in PDFs; Add metadata of a RasterEdge provides royalty-free .NET Imaging PDF Generator of
add jpeg signature to pdf; add image pdf acrobat
Image Converter | Convert Image, Document Formats
Can be used as an add-on for .NET Imaging SDK; support, like ASCII, PDF, HTML, MS- Word, PDF/A Most Find image converters to suit your needs in this following
add image to pdf online; add jpg signature to pdf
color=hredihgreenihbluei
Theiconsinsertedby\attachfileandthetextinsertedby\textattachfile
can be any color. The color optionsetsthiscolor. Each of hredi, hgreeni, and
hbluei must be a decimal number between 0 (darkest) and 1 (brightest). The
default iscolor=1 0.9255 0.7765,whichisabeige.
created=hPDF datei
Virtually alllesystemsassociateale-creationtimestampwitheachle. Al-
thoughT
E
Xprovidesnoportablemechanismfordeterminingthedateandtimea
lewascreatedthecreatedoptionletsyoumanuallyspecifytheseparametersfor
the reader’sbenet. See Section4.2for moreinformationabout attachle dates.
date=hPDF datei
Eachannotationinapdflecanhaveatimestampindicatingwhentheanno-
tationwaslast modied. attachleautomaticallyaddsatimestamptoleattach-
ment annotations. It uses the date andtime at whichLAT
E
Xstarted processing
your job (to minute precision because that’s what T
E
X’s \time command pro-
vides) and includesthe timezone, if specied (using the timezone option, p. 7).
Althoughit’sunlikely you’llneedtouse it,thedate optionletsyouoverride the
annotation’smodicationdateandtimewithadateandtimeofyourchoice. See
Section4.2for moreinformationaboutattachledates.
description=htexti
Themetadataassociatedwithaleattachmentannotationcanincludeabrief
description of the le. In Adobe Acrobat, this information is shown when one
right-clickson the le attachment icon and selects Properties.... Also, in later
versionsof AdobeAcrobat, the descriptioneldshowsupasa tool tipwhenthe
user mouses over the attachment. By default, no description is included, but
specifying description=htexti setsthedescriptioneldtohtexti.
icon=hnamei
pdf1.3denesfour iconsthatcanbeusedfor leattachments: Graph,Paper-
clip,PushPin, andTag. Theseare showninTable1. If noiconname isspecied,
PushPinisassumed. Whilethepdfspecicationssaythat,normally,apdfviewer
chooseshow todisplay eachof those, the attachlepackagespeciestheappear-
ance explicitly. Thisis what Adobe Acrobat does, presumably because doingso
ensuresthatviewerswhichdon’tsupportleattachmentannotationscanstilldis-
playsomethingreasonable. Thetradeoisthatitslightlyincreasesthesizeofthe
pdfle.
5
.NET Annotation SDK| Annotate, Redact Images
object or group of annotation objects add-on; Save annotation into image files, separate annotation files NET Document Imaging SDK and Java Document Imaging
add an image to a pdf form; how to add a jpeg to a pdf file
.NET Barcode Generate SDK| Generate Barcodes
Support QR Code, Data Matrix, PDF-417; Seamless integrate into any Automatically add check digit for barcodes; High-usability image options provided to
add jpg to pdf; how to add image to pdf form
Graph
Paperclip
PushPin
Tag
Table1: Validle attachment icons
mimetype=htypei
It is considered good practice to specify the mime type [2] of each attached
le. Thatway,apdf viewer canautomaticallylaunchanappropriateapplication
toprocessthe le. htypei shouldbe the form \htypei/hsubtypei". For instance, a
plaintext lewouldbe speciedwith\mimetype=text/plain". Anmpegmovie
wouldbespeciedwith\mimetype=video/mpeg". TheInternetAssignedNumbers
Authority maintainsalist of registeredmediatypes[3],so look there rsttosee
whattypetousefora givenle.
modified=hPDFdatei
Virtuallyalllesystemsassociatealast-modicationtimestampwitheachle.
AlthoughT
E
Xprovidesnoportablemechanismfordeterminingthedateandtime
alewaslast modied the modified option letsyoumanually specify these pa-
rameters for the reader’s benet. See Section 4.2 for more information about
attachle dates.
print=hbooleani
By default, le annotation icons print along with the rest of the document.
By setting print=false, the iconswill not print. Note that in Adobe Acrobat,
annotationswill never print unless the Annotationsbox is checked inthe Print
dialog.
size=hintegeri
The size optiontellsthe pdf viewer that theattachedle ishintegeri bytes
long. Adobe Acrobat displays this size under the \Size" column inthe Attach-
mentspanebut doesnototherwiseseem tousethehintegeri value.
6
.NET Excel Document Add-on | Manipulate Excel File in .NET
to convert Excel to PNG, JPEG, BMP, and GIF image formats, and to TIFF, PDF and SVG functions of this DLL, .NET programmers also need to add .NET Basic DLL
how to add image to pdf in preview; add a picture to a pdf file
.NET Word Document Add-on DLL of RasterEdge DocImage SDK for .NET
any page of Word document to raster image file (PNG and convert Word to other documents, like PDF, TIFF and be ordered for using .NET Word Document Add-on for
add an image to a pdf in preview; how to add jpg to pdf file
subject=htexti
Themetadataassociatedwithaleattachmentannotationcanincludeabrief
commentaboutthesubjectoftheattachment. InAdobeAcrobat,thisinformation
isshownwhenone right-clicksonthe leattachmenticonandselectsProperties.
By default,nosubject isincluded,but specifying subject=htextisetsthesubject
eldtohtexti.
timezone=hoseti
Because T
E
X doesn’t make the current timezone available, attachle is un-
ableto include timezone informationwhenit timestampsale attachment. The
timezone option lets you manually specify the timezone. hoseti is the oset
from Universal Time (a.k.a. gmt) and shouldbe in the format specied in the
pdfreferencemanual[1,x3.8.3, \Dates"],namely:
+hHHi’hmmi’ hHHihours,hmmiminuteslaterthanUniversalTime
(i.e.,east of Greenwich, England)
-hHHi’hmmi’ hHHi hours, hmmi minutes earlier than Universal
Time(i.e.,west ofGreenwich,England)
Z
UniversalTime (i.e.,at the samelongitudeasGreen-
wich,England)
For example,U.S. CentralTime wouldbe speciedwith timezone=-06’00’.
zoom=hbooleani
Normally,whenareader magniesor reducesthe view of thepdf document,
the le annotation icons change size proportionally with the text. By setting
zoom=false,the iconsize doesnotscale.
ThedefaultsforalloftheoptionsdescribedabovearesummarizedinTable2.
4.2 Date usage
Section 4.1 presents three timestamp-related options: date, created, and
modified. The date option species the annotation date|the date and time
thegivenlewasattachedtothepdfle|andshouldusuallybeleftunspecied.
(It defaults to the date and time at which LAT
E
X started processing your job.)
The annotation date isdisplayed inAdobe Acrobat by right-clicking on the an-
notation,choosingProperties... fromthemenu,andclickingontheGeneral tab.
Themodifiedoptionspeciesthele’smodicationdate|thedateandtimethe
givenlewaslastmodied. AdobeAcrobatdisplaysthemodicationdateunder
the\Modied"columnintheAttachmentspanebutdoesnototherwiseappearto
7
Option
Defaultsetting
appearance
true
author
none
color
1 0.9255 0.7765
created
none
date
automatic
description
none
icon
PushPin
mimetype
none
modified
none
print
true
size
none
subject
none
timezone
none
zoom
true
Table2: Defaultvaluesforalloptions
usethemodicationdate. Finally,the created optionspeciesthele’screation
date|thedateandtimethegivenlewasrstwrittentodisk. Asofthiswriting,
AdobeAcrobat doesnotappear touseorevendisplaythecreationdate;perhaps
futureversionsor other pdf viewerswill.
Datesshouldbespeciedintheform\D:YYYYMMDDHHmmSSOHH’mm’"
asdescribedinthepdfreferencemanual[1,x3.8.3,\Dates"]. Note,however,that
althoughthepdfreferencemanualclearlystatesthat\viewerapplicationsshould
bepreparedtoaccept anddisplayastringinanyformat"[1,Table8.11,\Entries
commontoallannotationdictionaries"],AdobeAcrobatwillignoreanytimestamp
thatisnotintherecommendedformatandwillinsteadshow\00/00/0000:00:00"
fortheannotationdate or \Unknown"for the modicationdate.
5 Caveats
Notethat there areafewcaveatsyoushouldbeawareof:
1. attachlerequirespdfLAT
E
Xversion0.14orlater. (Version0.14wasreleased
circa 1999 so it’sunlikely that you’re runningan older versionthan that.)
While there are many other ways to produce pdf les from LAT
E
X source,
attachlev1.5bsupportsonlypdfLAT
E
X,andonly versions0.14+.
2. attachlewillnotrununlessthefollowingLAT
E
Xpackagesareinstalled: calc,
keyval, color, hyperref, and ifpdf. (Most T
E
X distributions include all of
these.)
3. File attachments are a pdf 1.3 feature. They will not be visible in pdf
viewersthat don’t support pdf 1.3. (Version 4.0 of Adobe Acrobat is the
rst versionof thatprogram whichdoes.)
8
4. Evensomeviewersthatpurportedly support pdf 1.3don’t support le at-
tachments. AsfarasIcantell,very oldversionsof Adobe AcrobatReader
(thefree,view-onlyversionofAdobeAcrobat)doesn’tseemtosupport any
annotationsexcepttext annotations.
5. Evensomeviewersthatdosupport pdf1.3andleattachmentsdon’t sup-
portthem underallcircumstances. For instance,someWindowsversionsof
Adobe Acrobat, whenfunctioningasa Web-browser plug-in, give an error
message
1
whenaleattachmenticonisactivated.
6. Even in circumstances where le attachments are supported, the support
may be  awed. For example, some Windows versions of Adobe Acrobat
changeacustom icontothedefault iconwhenit’sselected.
Also, while le-attachment iconswith custom appearances printed ne in
olderversionsofAdobeAcrobat,AdobeintroducedabugcircaAdobeAcro-
bat6.0thatpreventsattachle’siconsfromprinting. Unfortunately,because
AdobeAcrobatlacksattachle’sabilitytocreatecustomappearancesforle-
attachmenticonsit’sunlikelythatthisbugwillevergetxed. Nevertheless,
pleaseconsider sendingabugreport toAdobetoletthemknowthatyou’d
liketobe able toprint le-attachmenticonswithcustomappearances.
Even givenall of those caveats, le attachmentscanbe auseful way to pass
additional information along with a pdf le. The attachle package makes le
annotationsautomaticandeasy.
6 Implementation
This section contains the complete source code for attachle. Most users will
not get much out of it, but it should be of use to those who need more precise
documentationandthosewhowant toextendtheattachle package.
6.1 Sanity checking
attachlev1.5brequirespdfLAT
E
X(andatleastversion0.14,althoughattachleno
longerchecksforthat). (Futureversionsof attachlemaysupport dvipdfm,dvips
with pdfmarks, VT
E
X, etc.) Also, pdfLAT
E
X must be in pdf-generating mode,
not dvi-generating mode. So, to save the user some aggravation, we check for
the correct backendrightupfrontand give awarningif allisnot well. Later,in
Section6.7, we replace all of the core attachle macros with dummy versionsso
LAT
E
Xcanat least runtocompletion.
1
\RequirePackage{ifpdf}
2
\ifpdf
3
\else
4
\PackageWarningNoLine{attachfile}{%
1
\Launchingembeddedlesfromwithinabrowserenvironmentisnotallowed".
9
5
attachfile works _only_ with pdfLaTeX and _only_ in\MessageBreak
6
PDF-generating mode. For this run, placeholders will\MessageBreak
7
be substituted for all attachfile commands.%
8
}
9
\fi
6.2 Preliminaries
We need toload hyperref toget our handsonthat great \pdfstringdef macro.
Fornow,weblindlypassallourpackageoptionsdirectlytohyperref. Inthefuture,
itwouldbenicetodoa\setkeys{AtFi}onouroptions.
10
\RequirePackage{keyval}
11
\RequirePackage{calc}
12
\RequirePackage{color}
13
\RequirePackageWithOptions{hyperref}
6.3 Adobe Acrobat icons
The followingmacrosdraw arepresentationof the variousiconsthat Adobe Ac-
robat
2
inserts to represent what the pdf 1.3 specications refer to as \Graph,"
\Paperclip," \PushPin," and \Tag". The \parbox dimensionsare takendirectly
fromtheoriginalgraphics’boundingbox. However,Ijusteyeballedthe\raisebox
heights(intendedtoputshadowsbelowthe baseline).
\atfi@acroGraph@data
Recreate Adobe Acrobat’sGraphicon.
14
\newcommand{\atfi@acroGraph@data}{%
15
q 0.5 g 1.1133 0 20.7202 18.2754 re f 1 g 0 G 0 i 0.5 w 4 M
16
0.25 1.6453 20.145 17.7715 re B 0 g 2.7319 4.1367 3.9571
17
13.8867 re f 8.7031 4.1367 3.9571 9.8867 re f 14.7471 4.1367
18
3.9571 11.8867 re f \atfi@color@rgb\space rg 1.689 3.0938
19
3.9571 13.8867 re f 7.6602 3.0938 3.9571 9.8867 re f 13.7041
20
3.0938 3.9571 11.8867 re f Q
21
}
\atfi@acroGraph
Draw\atfi@acroGraph@datainaboxof theappropriatesize.
22
\DeclareRobustCommand{\atfi@acroGraph}{%
23
\raisebox{-1.5bp}{\parbox[b][20bp]{22bp}{%
24
\rule{0pt}{0pt}\pdfliteral{\atfi@acroGraph@data}}%
25
}%
26
}
\atfi@acroPaperclip@data
Recreate Adobe Acrobat’sPaperclip icon.
27
\newcommand{\atfi@acroPaperclip@data}{%
28
q 0.75 G 0 i 2.5 w 1 J 4 M 1.9619 11.7559 m 1.9619 3.3037
29
1.9619 2.5059 v 1.9619 1.707 4.0947 1.25 y 7.4141 1.25 l 9.4292
30
1.8223 9.4292 3.3066 v 9.4292 4.79 9.4292 16.8945 y 9.7852
2
Igot thesegraphicsspecicallyfromtheWindowsversionofAdobeAcrobat 4.0.
10
Documents you may be interested
Documents you may be interested