[pdftex] Link annotations in included pdf documents

[Lander]

Dear List,

This is my first post here, so I believe greetings to you
all is in order.  I've been learning from this list since
way back, and wish to express my gratitude for all the
helpful answers, tips and tricks I've found so far in your
messages.

Now, let's get cracking.  I pose a problem below and
describe the solution I came up with.  I wonder if you could
take a few minutes to read it over and let me know how you
would face it, what kind of approaches you would follow.
Any comments on my attempts are more than welcome.


Problem

Let's consider a pdf document that contains a scanned book.
The (clipped) page that shows the book contents is as
follows:
    
    ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
    ~                                                     ~
    ~  Contents                                           ~
    ~                                                     ~
    ~  Preface ....................................   vii ~
    ~  Acknowledgements ...........................    xi ~   
    ~  1  Where shall I go? What shall I do? ......     1 ~
    ~  2  Frankly, my dear, I don't give a damn ...    10 ~
    ~                                                     ~
    ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~

Make page numbers be links to the corresponding pages (as
hyperref's linktocpage option does).


First attempt: \pdfannot + /Rect  :-(

For starters, I get the coordinates of a pair of diagonally
opposite corners that describe a rectangle enclosing each
page number.  I do this using gsview, for example, and come
up with several rectangles [llx lly urx ury], one per page
number.

Then, I write a pdflatex document and use the pdfpages
package as follows:

    [Preamble, \begin{document}, some \includepdf]
    
    \pdfannot{/Subtype /Link /C [1 0 0] /Dest (name) 
              /Rect [llx lly urx ury]}
    
    [More \pdfannot lines] 
    
    % This is the contents page
    \includepdf[pages=5]{book.pdf}

    [Following \includepdf, \end{document}]

(Replace name, llx, lly... with suitable values.)

When I run pdflatex on this document, I find that \pdfannot
ignores the Rect entry, and adds one of its own: a
rectangle that encloses the whole included pdf page.  Of
course, the rectangles of the several \pdfannot overlap,
which means that I actually see one rectangle, the one of
the last \pdfannot.  

I think I may know why this happens.  The pdftex
documentation says: "When an annotation is written out,
running dimensions will take the corresponding values from
the box containing the whatsit node representing the
annotation".  I must admit I don't know what a 'whatsit
node' is (and if I'm sincere, it makes me shudder; I recall
reading it in the LaTeX2e sources), but I suppose that the
box containing it is, in this case, the included pdf page.

If I add a <rule spec> to \pdfannot, with the width, height,
and depth of my rectangles, then these rectangles show the
intended dimension in the output pdf, but are located on the
upper left corner of the included pdf page (as in line with
it or something), and again overlap.

Well, whatever; this don't work.  I may know why, but I
don't understand why.  Would it be possible to make
\pdfannot allow a Rect key as part of the <general text>?  I
mean, once it detects the presence of /Rect, it shouldn't
bother calculating any box, should it? 


Second attempt: \pdfannot + /QuadPoints  :-)

The QuadPoints key is documented in the PDF Reference,
version 1.6, as an additional entry specific to a link
annotation.  It lets you specify a 'quadrilateral' that
comprises the region in which the link should be activated.
There's a condition for this to work: the quadrilateral must
lie inside the rectangle given by /Rect.  Fair enough.

Now, the \pdfannot lines go like this:

    \pdfannot{/Subtype /Link /C [1 0 0] /Dest (name)
              /QuadPoints [llx lly lrx lry urx ury ulx uly]}

(Again, replace name, llx, lly... with suitable values.)

Note that there's no need to explicitly add a Rect entry
(which is worthless anyway): \pdfannot adds its own
rectangle (the whole inserted pdf page); I somehow override
it with my quadrilateral (do love this word).  And
everything works like a charm, and I'm very happy about it
because one more time, thanks to the work of selfless
people, I don't need to wear the shackles of non-free
software.  But there's a drawback: I'm using a PDF 1.6
feature, and not all viewers support it.  Not good enough.


This is it: Ground Zero.  Sorry for such a long message; at
least I hope I've made myself clear.

Cheers.
Lander