Creating a link

To create a link enter the name of an attribute (of the current element) in the Link to target using attribute field. The value of this attribute will be used as the link target.

The link target can have one of the following forms:

  • An IDREF (e.g. chap2sec37a) — an XML name matching a unique attribute somewhere in the document. This will generate an internal link which, when clicked, will move to a new point in the document. Note that the attribute used to generate the link does not literally have to be of type IDREF, and indeed it is possible to generate the id internally and invoke it via a custom marker.

    Links to other PDF files generated by TopLeaf can be created in the same way. External links within TopLeaf partitions are only enabled when the PDF creation is supplied with a list of partitions to search. When creating external links to PDF files generated by TopLeaf, all target values must be unique in the partitions selected.

  • A link to a local PDF file using a URI (Uniform Resource Identifier) with the file: scheme. For example, file://manual.pdf. More details of these links are given below.

  • A URI with a scheme identifying an external resource. See the note below for more information.

  • A link can be used to execute some javascript code in the PDF viewer. A prefix is used to identify this type of link. See the description of metadata values in the User Guide for more information.

  • A link to a named destination in the PDF document. A prefix is used to identify these links. See the description of metadata values in the User Guide for more information.

No link will be created if the attribute is not present.

[Note] Note

A valid URI can only contain 7-bit (ASCII) characters. Any characters outside this range will be encoded in UTF-8 and percent-escaped. This may not produce the correct result in all cases. It is recommended that attribute values containing URI data should only contain 7-bit values. Consult IETF RFC 3986 for more information about URI syntax.

[Note] Note

Content that has been designated as a link launch point cannot be suppressed, since it is anchored to a specific piece of text in the finished document.

PDF Link resolution

TopLeaf's PDF builder resolves links in the following way:

  1. If the link target starts with the prefix used to identify javascript links, the link will run the code that follows the prefix. See the User Guide section on PDF creation for more information.

  2. If the link target starts with the prefix used to identify named destination links, the part following the prefix will be used as the name of the link destination. See the User Guide section on PDF creation for more information.

  3. If the link target identifies an ID declared within the same document, then the link is assumed to be a local link.

  4. If the link target exists within the PDF builder partition search list (see the GetPDF API call) then the link is assumed to a link located within the externally named partition.

  5. If the link target identifies a PDF file using a URI with the file: scheme then the link target is assumed to be the first page of that file, unless the PDF link target also specifies a PDF target page.

  6. If the link target begins with the URI scheme http:, https:, ftp: or mailto: then the link target will be interpreted as an external resource (for example, http://mycompany.com/docs/spec.html#para5).

  7. Otherwise, the link is not resolved.

Secondary output link resolution

When creating secondary outputs the resolution process is:

  1. If the link target identifies an ID declared within the same document a local link is created.

  2. If the link target begins with the URI scheme http:, https:, ftp: or mailto: then the link target will be interpreted as an external resource.

  3. Otherwise, the link is not resolved.

Linking to other PDF files

To create a link to a local PDF file (not necessarily created by TopLeaf), the link target must begin with “file://” and end with “.pdf” (case is not significant).

The path to the target PDF is found by removing the file:// and interpreting the remainder as either an absolute or relative path. Since URI syntax is being used, note that you must use “/” as a separator.

If the path is relative, note that it is relative to the folder containing the source PDF when it is opened.

Here are some examples:

file://Index.pdf — use this to open a PDF that is located in the same folder as the current PDF.

file://archive/A1998.pdf — this links to a PDF in the archive subfolder.

file://P:/Docn/Current/Manual.pdf — this is a link to an absolute location on the P: drive.

Linking to a specific page within another PDF file

If you need to create a link to a specific page within a local PDF file (not necessarily created by TopLeaf), then specify the PDF link target using the format pathname#PAGE, where PAGE is the target page number.

Example:

file://Index.pdf#23 — use this to open a PDF located in the same folder as the current PDF. The PDF document viewer will open at page 23.