[pdftex] \pdfstartlink attributes

[Heiko Oberdiek]

On Wed, Aug 13, 2008 at 11:58:42AM +0200, silvio mercadante wrote:

> I'm trying to understand the attributes of the \pdfstartlink ...  
> \pdfendlink environment.
> The PDFTeX manual says (p.34) that "Additional attributes, which are  
> explained in great detail in the PDF Reference, can be given via
> ???attr spec ???."
> Well, I can't undertand what's written in PDF Reference at all!  (Ehm,  
> needless to say, I'm not an expert of the PDF language...)

\pdfstartlink (and many other primitives) are low level
commands intended for experts. Use some of the
higher user level macros (hyperref/latex, ConTeXt, ...) if
you don't want to become an expert.

> My needs are:
> 1. What's the syntax of the <attr spec>?

The contents of "attr" is put in a PDF dictionary. Therefore
it must contain valid key value pairs. The key is always
a PDF name object.

For testing/debugging it is a good idea to look at the
generated PDF file directly (using a text/hex viewer/editor).

> 2. What are the possible attributes?

PDF Reference.

Both "attr" and "user" writes into the /Annot dictionary,
see PDF specification "8.4.1 Annotation Dictionaries",
especially Table "5.15 Entries common to all annotation dictionaries".
In case of links: Table "8.24 Additional entries specific to a link
annotation".

Common keys for "attr": /F, /Border, /BS, /C, /H,
but also /AP, /AS, /NM and other could be used.

"user" must set /Subtype and /A.

/Rect is set by \pdfstartlink and must not be set manually.

> 3. Some examples.

hyperref, ...

find texlive2008/texmf-dist/tex -exec grep -H pdfstartlink {} \;

> Al this to be able to customize the following TeX macro:
> 
> \def\elink#1#2{%
> \leavevmode%
> \begingroup\pdfstartlink%
> attr{/BS<</Type/Border/S/S/W 1>>}%
> user{/Subtype/Link/A<</Type/Action/S/URI/URI(#1)>>}%
> \ignorespaces#2%
> \pdfendlink\endgroup%
> }

See hyperref's \href for URI actions.
\href{http://www.somewhere.org/}{...}

\elink isn't correct, if #1 contains unmatched parentheses,
thus #1 should be at least passed through \pdfescapestring:

\def\elink#1#2{%
  ...
  user{.../URI(\pdfescapestring{#1})>>}%
  ...
}

Yours sincerely
  Heiko <oberdiek at uni-freiburg.de>
--