Add PDF hyperlink support

[matsud224]

This PR adds a PDF hyperlink support to SATySFi. I think page navigation features are essential particularly to read a large document like a SATySFi book.

I think the APIs described below are highly controversial.

For example, some features not provided by primitives are not available (e.g. annotation border style, mouse down highlighting mode, ...).
One possible solution is to pass PDF objects(e.g. dictionary, array, stream) as argument of primitive. pdfTeX takes this approach. (c.f. pdfTeX users manual).

Added primitives

• register-destination : string -> point -> unit
  Register given destination key with given coordinates.

• register-link-to-uri : string -> point -> length -> length -> length -> length -> color option -> unit
  Add a link to given URI with given rectangle, border width and border color.

• register-link-to-location : string -> point -> length -> length -> length -> length -> color option -> unit
  Add a link to given destination key with given rectangle, border width and border color.

Package

annot.satyh provides a PDF annotation related commands and functions (now, link annotation only). I used deco-set feature to get a region of link or get a coordinates of link destination.

• \href : [length?; color?; string; inline-text] inline-cmd
  This command makes a link to a designated URI.

This PR modifies stdjabook.satyh to add a link of :

• each table-of-contents element
• \ref
• \ref-page
• \figure

[gfngfn]

I have just checked that it works as you had intended. Thank you for now for sending such a brilliant PR! I will read closely the code that realizes the operation of adding hyperlinks, so I would appreciate it if you could wait for a while (and possibly discuss further in detail).

[gfngfn]

I’m super sorry to make a very late response… I took a close look into your implementation and found it quite well-written basically. Although I’m ready to merge this PR, I have a small question about it:

Is there any rationale for providing register-link-to-uri as a primitive of type

string -> point -> length -> length -> length -> length -> color option -> unit

instead of that of type

string -> point -> length -> length -> length -> (length * color) option -> unit?

IMHO the latter would be more natural as an API, since it seems awkward that one can designate non-zero length for the border width and None for the border color at the same time and that the non-zero length will be ignored in such a case. The same situation holds for register-link-to-location.

I would appreciate it if you could give some comment about this.

(It is off topic, but I have tried to extend your implementation for supporting screen annotations and rendition actions so that users can embed movies into PDFs. It currently fails, however, due to the mismatch of what I wanted to write and what camlpdf provides as its high-level interface.)

[matsud224]

I totally agree with your suggestion.

due to the mismatch of what I wanted to write and what camlpdf provides as its high-level interface.

Camlpdf 's API is sometimes insufficient, so it may be better to extend camlpdf instead of adding modules to SATySFi. (I actually had to extend camlpdf to implement PDF bookmark support.)

[gfngfn]

I came upon another question:

Since the evaluation of function applications of the newly introduced primitives (i.e. register-destination, register-link-to-uri, or register-link-to-location) makes sense only during page breaking, it may be desirable to emit some (run-time) error if such applications are evaluated before page breaking starts. Is this kind of modification acceptable to you?

[matsud224]

Is this kind of modification acceptable to you?

Yes. It looks good.

I fixed stdja and stdjareport to use hyperlink features.

[gfngfn]

Finally I merged the PR. Thank you very much for having discussions! (and sorry for letting you patiently wait my response 😢)