7.2.10. Links to internet sites

The url package enables the use of URL links in the PDF document and takes care of their hyphenation. To use it, you must tell jadetex to load it. You do this by inserting the following in the jadetex.cfg file (see also Section 4.4):

\usepackage{url}

We must also ensure that openjade properly transforms the <ulink> and <filename> elements into jadetex commands. For the <ulink> element, we want openjade to copy the text found between the two tags and within parentheses, i.e. the address given in the id attribute.

In order to do this, we use the customization as described by Pascal Lo Ré in Customizing Document Production: we create a sosofo of type formatting-instruction. We added a new flow-object to those already defined in the DSSSL stylesheets:

;;  Inserted in order to be able to get URLs in PDF documents.
;;  Adapted from manual-print.dsl of <productname>Mandrake</productname>.
;; Include the flow object class "formatting-instruction" : ONLY for Jade
(declare-flow-object-class formatting-instruction
       "UNREGISTERED::James Clark//Flow Object Class::formatting-instruction")

This addition allows us to insert arbitrary, non-formatted text into the output file. Then we can insert suitable TeX instructions into the intermediate output. This new flow-object is called formatting-instruction. The usage syntax of formatting-instruction is as follows:

(make formatting-instruction data:
"text-to-be-output")

The value of the data variable is inserted into the output file. Note that the “\” character must be escaped with an addition '\'. For example, in order to insert the TeX function,\penalty, you would use the following:

(make formatting-instruction data:
"\\penalty")

Now, in order to get hypertext links in PDF, the ulink element is redefined in lyxtox-print.dsl with the help of formatting-instruction (see Using Jade for SGML transformations for the class "formatting-instruction" and Section 4.2 and Section 7.1.5 for the lyxtox-print.dsl file):

;; *** URLs ***
;; Original : dblink.dsl
(element ulink
 (sosofo-append
  ;; If you allow process-children here, you will get the text printed once more!
  ;; (process-children)             ;; Write the text with its format (anchor in HTML)
  (make formatting-instruction      ;; Write : " \href{" + theUrl + "}{" + theText + "}"
    data: (string-append " \\href{" (attribute-string (normalize "url")) "}{" (data-of (current-node)) "}")
  )
 )
)

The text to be edited is accessed by data-of (current-node). Because this text requires special formatting (italics?), we must call the (process-children) function. The address is returned by attribute-string (normalize “url”). To construct the string, we concatenate using the command string-append, and assign the result to data in the sosofo. This nicely produces hypertext links in PDF.

However, the <ulink> element is not only used for URLs, but also for the index generation (see Section 7.1.11). Since we redefined it above, it is going to be used for the index too (remember, the changes you do in the stylesheets, as discussed in Section 7.1.5, will take precedence over the defaults). We thus have to copy the code from dbindex.dsl for <ulink> elements that are children of <primaryie>, <secondaryie> or <tertiaryie>, which is the case for the index:

;; These three elements are from "dbindex.dsl".
;; Must be placed here because of the redifinition of "ulink".
;; Otherwise the Index entries will point to HTML files,
;; instead of page numbers.
(element (primaryie ulink)
  (indexentry-link (current-node)))
(element (secondaryie ulink)
  (indexentry-link (current-node)))
(element (tertiaryie ulink)
  (indexentry-link (current-node)))