Hypertext marks in L^{A}TEX^{∗}

Sebastian Rahtz and Yannis Haralambous

             Email: s.rahtz@elsevier.co.uk

1996/05/09

Contents

1 Introduction

This package derives from and builds on the work of the HyperTEX project; see http://xxx.lanl.gov/hypertex/. It aims to extend the functionality of all the L^{A}TEX cross-referencing commands (including the table of contents) to produce \special commands which are parsed by dvi processors conforming to the HyperTEX guidelines (i.e. xhdvi and dvihps); it provides general hypertext links, including those to external documents.

The package also provides a generalized interface to Acrobat pdfmark commands. The HyperTEX specification (this is borrowed from an article by Arthur Smith) says

that conformant viewers/translators must recognize the following set of \special commands:

href: html:<a href = "href_string">
name: html:<a name = "name_string">
end: html:</a>
image: html:<img src = "href_string">
base name: html:<base href = "href_string">

The href, name and end commands are used to do the basic hypertext operations of establishing links between sections of documents. The image command is intended (as with current html viewers) to place an image of arbitrary graphical format on the page in the current location. The base name command is be used to communicate to the dvi viewer the full (URL) location of the current document so that files specified by relative URL’s may be retrieved correctly.

The href and name commands must be paired with an end command later in the TEX file — the TEX commands between the two ends of a pair form an anchor in the document. In the case of an href command, the anchor is to be highlighted in the dvi viewer, and when clicked on will cause the scene to shift to the destination specified by href string. The anchor associated with a name command represents a possible location to which other hypertext links may refer, either as local references (of the form href="#name string" with the name string identical to the one in the name command) or as part of a URL (of the form URL#name string). Here href string is a valid URL or local identifier, while name string could be any string at all: the only caveat is that ‘"’ characters should be escaped with a backslash (\), and if it looks like a URL name it may cause problems.

∗This file has version number 2.4, last revised 1996/05/09.

2 Usage

Use this package with any more or less normal L^{A}TEX document by specifying \usepackage{hyperref}. Make sure it comes last of your loaded packages, to give it a fighting chance of not being over-written. The resulting dvi file can be processed with xhdvi or dvihps and hopefully you will find that all cross-references work correctly as hypertext.

The low-level user macros which are available are as follows:

\hyperlink  {linkname} {text}
\hypertarget  {anchorname} {text}
\href  {URL} {anchor}

    \hyperimage  {image URL}

\hyperdef  {URL} {category} {name} {text}
\hyperref  {URL} {category} {name} {anchor}
\hyperdef  [label] {URL} {category} {name} {text}
\hyperref  [label] {anchor}
\htmladdimg  = “hyperimage

    \htmladdnormallink  = “href

The \hyperlink command inserts # in front of each link, making it relative to the current document; \href expects a genuine URL.

3 Original, history and acknowledgements

The original authors of hyperbasics.tex and hypertex.sty, from which this package descends, are:

Tanmoy Bhattacharya

     tanmoy@qcd.lanl.gov

Los Alamos National Laboratory

New Mexico, 87544-0285

USA and Thorsten Ohl

     Thorsten.Ohl@Physik.TH-Darmstadt.de

Technische Hochschule Darmstadt

Schloßgartenstr. 9 D-64289 Darmstadt Germany

Eventually I (SPQR) think I have rewritten most of the stuff, because I didn’t understand a lot of the original, and was only interested in getting it to work with L^{A}TEX 2ε; it still has problems, but the majority of L^{A}TEX documents go through, with good PDF functionality.

Tanmoy Bhattacharya found a great many of the bugs, and (even better) often provided fixes, which has made the package more robust. The days spent on RevTEX are entirely due to him! The investigations of Bill Moss (bmoss@math.clemson.edu) into the later versions including ‘nativepdf’ scared up a host of bugs, and his testing is appreciated.

I am grateful to Michael Mehlich, whose hyper package (developed in parallel with hyperref) showed me solutions for some problems. Hopefully the two packages will combine one of these days!

Thanks to Arthur Smith, Mark Doyle, Paul Ginsparg, David Carlisle and Leslie Lamport for comments, thoughts and code.