A hyperTEX patch for xdvik

Timothy Murphy

               (tim@maths.tcd.ie)

23 July 1995

Contents

1 Introduction 2 1.1 Comment invited . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 The patch 3 2.1 Where from? . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.2 Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.3 Plagiarism or Research? . . . . . . . . . . . . . . . . . . . . . 3 2.4 Omissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3 Compilation 4 3.1 The WWW Library . . . . . . . . . . . . . . . . . . . . . . . . 4 3.2 Patching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.3 Compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

4 Implementation 5 4.1 Fail-safe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 5 The hyperTEX standard 5

5.1 Links and Anchors . . . . . . . . . . . . . . . . . . . . . . . . 6 5.2 Remote references . . . . . . . . . . . . . . . . . . . . . . . . . 7 5.3 The 3 varieties of link . . . . . . . . . . . . . . . . . . . . . . . 7

6 The hyperref package 8

6.1 Links and anchors in hyperref . . . . . . . . . . . . . . . . . 8 6.1.1 Internal links . . . . . . . . . . . . . . . . . . . . . . . 8 6.1.2 External links . . . . . . . . . . . . . . . . . . . . . . . 9 6.1.3 A third option . . . . . . . . . . . . . . . . . . . . . . . 9 6.1.4 An addendum to hyperref . . . . . . . . . . . . . . . 10

7 Miming 11 7.1 Which viewer? . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 7.2 Browsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

8 Including remote EPS files 13

9 The last 2 specials 14 9.1 The image special . . . . . . . . . . . . . . . . . . . . . . . . . 14 9.2 The URLbase special . . . . . . . . . . . . . . . . . . . . . . . 15

Abstract

These notes describe a patch to Karl Berry’s (and Paul Vojta’s) xdvik which makes this program ‘hypertext-aware’, in accordance with Arthur Smith’s hyperTEX standard.

1 Introduction

HyperTEX adds hypertext facilities to TEX/L^{A}TEX, through 5 \special’s as specified in sections 5 and 9 below. We may say that a DVI interpreter which understands these 5 specials is “hyperTEX-aware”.

By “hypertext” we mean the ability to jump to another place in the same or a different document by clicking on a word or region.

This file contains a patch to xdvik-18f which adds hyperTEX-awareness to the program xdvi.

1.1 Comment invited

Please send any remarks on this document or on the patch to me at tim@maths.tcd.ie. All comments and suggestions will be gratefully received.

2 The patch

2.1 Where from?

This patch can be retrieved from

    ftp://ftp.maths.tcd.ie/pub/TeX/xdvik-18f.hyper-patch.tgz

2.2 Format

The patch comes in 2 parts:

1. A patch file xdvik-18f.hyper-patch which alters a few of the files in

     the directory .../xdvik-18f/xdvik.

2. 3 new files to add to this directory: hypertex.c, mime.c and

     WWWfetch.c.

2.3 Plagiarism or Research?

If you steal from one author, that’s plagiarism; if you steal from many, that’s research. (Wilson Mezner)

This patch is stolen in its entirety from Arthur Smith’s xhdvi program. In effect, it is no more than a marriage between this program and Karl Berry’s (and Paul Vojta’s) xdvik.

2.4 Omissions

I omitted the scrolling mechanism from xhdvi — allowing scrolling across pages — (1) because I didn’t understand it, and (2) because I prefered that xdvi should behave exactly as before when processing normal (nonhyperTEX) files.

3 Compilation

3.1 The WWW Library

This program — like xhdvi, its model — requires the standard CERN WWW Library, libwww.a (or equivalent). If you are running mosaic or a similar browser you probably have this library on your system. If not, it can be retrieved from

    ftp://ftp.w3.org/pub/www/src/WWWLibrary.tar.Z

3.2 Patching

To apply the patch, assuming that you have the xdvik program (available

from the CTANs in /tex-archive/dviware/xdvik.tar.gz) in the directory

.../xdvik-18f, follow these instructions:

Move to the top xdvik-18f subdirectory, and un-tar the .tgz file. This

will add 3 files hypertex.c, mime.c and WWWfetch.c to the xdvik subdirec-

tory. It will also leave a file xdvik.patch in the top xdvik-18f directory. Go to this subdirectory, and apply this patch as shown.

    % cd .../xdvik-18f
    % mv .../xdvik-18f.hyper-patch.tar.gz .
    % tar xzvf xdvik-18f.hyper-patch.tgz
    % cd xdvik
    % patch -p1 < ../xdvik.patch

Everything is now ready for compilation.

3.3 Compiling

Now move back to the top xdvik-18f directory, and run ‘configure’:

    % cd ..
    % configure -v

This will create a modified Makefile in the xdvik directory. The modification is trivial, and can easily be done by hand if prefered. It consists simply of adding the object files hypertex.o, mime.o and WWWfetch.o and the library -lwww to the requirements for xdvi.

Finally, ‘make’ as follows, substituting for <WWWINCDIR> and <WWWLIBDIR> appropriately. (Or if preferred, put these switches in the Makefile.)

    % make CFLAGS="-O -I<WWWINCDIR>" LDFLAGS="-s -L<WWWLIBDIR>"

On my Linux system I have

    <WWWINCDIR> = /src/info-systems/WWW/Library/Implementation
    <WWWLIBDIR> = /src/info-systems/WWW/Library/linux

Of course these -I and -L switches can be put in the Makefile if desired.

4 Implementation

4.1 Fail-safe

This patch is — or is intended to be — doubly fail-safe.

1. If compiled without the -DHTEX switch it should revert to the original xdvik, unaltered. In effect, all changes to the xdvik files have been sandwiched between #ifdef HTEX … #endif’s.

2. Even when compiled with the -DHTEX switch the program xdvi should act on standard DVI files (ie those not using the hyperTEX extensions) exactly as before.

5 The hyperTEX standard

Arthur Smith (asmith@mammoth.chem.washington.edu) has proposed a

simple but powerful way of adding hypertext-awareness to TEX/L^{A}TEX, through 5 \special commands.

Although we might call this a hypertext “extension” of TEX it is important to realise that it does not involve any modification to the tex program. The only changes required are to DVI interpreters, making them responsive to these 5 specials.

For the moment, we need only consider the first 3 of these specials, which are all that are likely to occur in the vast majority of hyperTEX documents.

5.1 Links and Anchors

The first 3 hyperTEX \special’s are used to define links and anchors.

In this document I shall use the word ‘link’ to describe a pointer, or in the language of L^{A}TEX a \ref; and I shall use the word ‘anchor’ to describe the target of a pointer, or in the language of L^{A}TEX a \label. I mention this because there seems some confusion in the literature, with each word sometimes being used in both senses.

With this understanding, a link is established by a sequence such as the following:

    Click
    \special{html:<a href=paradise>
    here
    \special{html:</a>}
    to go to heaven.

(The division into lines is of course arbitrary, and is simply added for readability.)

The corresponding anchor might be established by the sequence

    \special{html:<a name=paradise>}
    Heaven
    \special{html:</a>}
    is in the heart.

Thus each link begins with \special{html:<a href=...>} and ends with \special{html:</a>}, the material between constituting the active text, clicking on which transports one (in this case) to paradise.

The corresponding anchor takes exactly the same form, except for the substitution of name for href. (The active text in the anchor appears to me to have no real function, though it may be highlighted in some way.)

The match between link and anchor is established by the use of the same label, in this case ‘paradise’. (Of course more than one link may point to the same anchor.)

We emphasize that while these \special’s can be written directly in TEX or L^{A}TEX source files, they will normally be ‘mediated’ by appropriate macros, as for example those provided in L^{A}TEX by the hyperref package (Section 6).

5.2 Remote references

The hyperTEX standard allows a link to reference an anchor in another document, even one at another site. This is implemented by allowing an href of the form <URL>#<label>, for example

    \special{html:<a href=http//www.maths.tcd.ie/~tim/ch1.dvi#equation.1.1}

This matches the anchor

    \special{html:<a name=equation.1.1}
in the DVI file http:/www.maths.tcd.ie/~tim/ch1.dvi. (Note that care

is needed to avoid interpretation of ~ and # in such a special. Any macro outputting the special should deal with this.)

5.3 The 3 varieties of link

A link may refer to

1. An anchor in the same document. I shall call this an internal reference. An example would be

         \special{html:<a href=paradise>}

2. An anchor in another document at the same site. I shall call this a local reference. Local references are implemented by the ‘pseudo-URL’ file:, as for example in

         \special{html:<a href=file:ch1.dvi#equation.1.1>}

(Note that some special action will usually be required to let the # pass unchanged to the DVI file. We shall discuss this point in the L^{A}TEX context below, Section 6.)

3. An anchor in a document on another computer. I shall call this a remote reference. In this case the full WWW ‘URL’ must be given, as for example in

         \special{html:<href=http://www.maths.tcd.ie/~tim/ch1.dvi#section2.3>}

In all cases, the link must of course be closed — after the active text —

with \special{html:</a>}.

6 The hyperref package

There are several L^{A}TEX packages (or style files) which implement hyperTEX. I have only used one, the hyperref package of Sebastian Rahtz and Yannis

Haralambous (available in /tex-archive/macros/latex/contrib/supported

from the CTANs).

This package has the very nice feature (which may indeed be shared by other hyperTEX packages) that the mere inclusion of the magic words \usepackage{hyperref} adds hyperTEX features to an ordinary ‘classic’ L^{A}TEX file.

More precisely, link/anchor correspondences are automatically established in the following cases:

1. Between the entries in the Table of Contents and the corresponding sections, etc.

2. Between citations and the bibliography

3. Between footnote marks and footnotes.

4. Between \ref’s and the corresponding \label’s.

6.1 Links and anchors in hyperref

6.1.1 Internal links

For internal links hyperref provides the macros \hyperlink and \hyperanchor. Each takes 2 arguments, the anchor-label and the ‘active’ text, eg

    The way to
    \hyperlink{dis}{Hell}
    is paved with good intentions.
    ...
    \hyperanchor{dis}{Hell} is other people. (Sartre)

The common label — ‘dis’ in this case — establishes the correspondence between link and anchor.

6.1.2 External links For external links — whether local or remote — hyperref offers the macro \href. This again takes 2 arguments like hyperlink; but now a full <URL>#<label> reference may be given, as eg

    \href{http://www/maths.tcd.ie/\~tim/analysis.dvi\#equation.4.2}%
      {Taylor's Theorem}

(Note that ~, # and % must be ‘escaped’ to avoid interpretation by L^{A}TEX.)

A local reference, as explained earlier, uses the ‘pseudo-URL’ file:, as eg

    \href{file:analysis.dvi\#equation.4.2}{Taylor's Theorem}

Note that since all anchors are internal, \hyperanchor will match an

\href as well as a \hyperlink.

6.1.3 A third option The hyperref package offers a third pair of macros for defining links and anchors, namely \hyperref and \hyperdef. Each of these takes 4 arguments:

1. URL

2. label type, eg ‘equation’, ‘chapter’, etc

3. label

4. text

In effect

    \hyperref{URL}{type}{label}{text} =
\href{URL#type.label}{text}

The following example illustrates how the pair might be used.

    \hyperref{http://www.maths.tcd.ie/plan.dvi}{section}{1.2}%
      {Funding}
    ...
    \hyperdef{}{section}{1.2}{Money matters}

(It seems to me that the first argument of \hyperdef should always be empty, since an anchor, as we just noted, is necessarily internal.)

It is worth noting that the automatic ‘hyperTEX-ing’ of L^{A}TEX files invoked

by \usepackage{hyperref} uses this \hyperdef format. Thus equation

(3.3) is automatically provided with the anchor

    \hyperdef{}{equation}{3.3}{...}

where the text consists of the whole equation.

Consequently references to this equation, whether internal or external, can conveniently use the \hyperref format, eg

    \hyperref{file:analysis.dvi}{equation}{3.3}{The Jacobi identity}

In fact I would recommend usage of this \hyperref/\hyperdef pair at all times, with the following 2 exceptions:

1. In targetting anchors defined by the classic \label. Here the actual label must be used unadorned, while \hyperref always adds a ‘.’, even if the label-type is empty:

         \hyperref{}{}{label}{text} = \hyperlink{.label}{text}

2. Similarly, no prefix is added to citations, and so for these also the \hyperref macro is inappropriate.

But note that in these 2 cases no link need be provided for internal references, since these are already added to \ref and \cite by hyperref. Thus these more complicated \href’s are only required when referring to a \label or a \bibitem in an external document.

6.1.4 An addendum to hyperref

If you wish to use \hyperref’s to target remote files, you will probably need to make a trivial modification to hyperref.sty, to allow the use of \~, \# and \@ within URLs. To be precise, the definition

\def\hyperref#1#2#3#4{% URL, category, name, text
  \hyper@link{#1\hyper@hash#2.#3}{#4}%
}

should probably be replaced by

\def\hyperref#1#2#3#4{% URL, category, name, text
\bgroup
\let\%\@percentchar
\let\#\hyper@hash
\let\~\hyper@tilde
\hyper@link{#1\hyper@hash#2.#3}{#4}%
\egroup

If making this change, it might be as well to make the corresponding change to the definition of \htmladdimg, with

\def\htmladdimg#1{\special{html: <img src=\hyper@quote#1\hyper@quote>}}

replaced by

\def\htmladdimg#1{%
\bgroup
\let\%\@percentchar
\let\#\hyper@hash
\let\~\hyper@tilde
\special{html: <img src=\hyper@quote#1\hyper@quote>}%
\egroup
}

7 Miming

So far we have assumed that a link points to a target in a DVI file. In fact we allow links to non-DVI files. In that case we employ the ‘mime’ mechanism, as used in metamail and other places. That is, the type of the file is determined from its extension (if possible), and an appropriate viewer invoked.

For example, a sound file might be included by

  Click
  \href{http://www.maths.tcd.ie/\~tim/tim.au}{here}
  to hear my voice.

7.1 Which viewer?

The extension-viewer correspondence is established in 2 stages.

1. The filename extension is first matched to a ‘mime-type’ according to a data-base, if found, or else to the default list in the file mime.c. This data-base is sought first in the file $HOME/.mime-types, and then in

MIMELIBDIR/mime-types (where MIMELIBDIR = /usr/local/lib/texmf/xdvi

in my patch).

In fact the default list of mime-types in mime.c is quite extensive, and certainly matches all the extensions I can think of. Consequently I have found no need to create an alternative .mimes-type file.

2. Having determined the mime-type in this way, the program then looks in a second data-base to determine what action to take. This data-base is sought first in the file $HOME/.mailcap, and then in

MAILCAPDIR/mailcap (where MAILCAPDIR = /usr/local/lib/texmf/xdvi

in my patch).

By contrast with mime-types the default mailcap entries in mime.c are unlikely to suffice for anyone using this facility. My .mailcap reads in part

application/postscript; ghostview %s
application/x-dvi; xdvi %s
image/jpeg; xv %s
image/gif; xv %s
image/tiff; xv %s
audio/basic; cat %s > /dev/audio
video/mpeg; mpeg_play %s

The format should be clear from this; each line contains <mime-type>; followed by a command to be executed, with the name of the invoked file represented by %s.

(If a second %s appears in the line, then the first is replaced by the current URLbase — see Section 9.2 — and the second by the filename. However, I have never used this feature.)

7.2 Browsing

If the extension cannot be matched, then mime.c currently invokes the ‘browser’, as specified by the environment variable WWWBROWSER or by the X-windows ‘resource’ xdvi*browser.

I have never tested this feature, so will say no more of it here.

8 Including remote EPS files

The graphics and graphicx packages allow Encapsulated PostScript (EPS) files to be incorporated by the \includegraphics command, as eg

    \includegraphics{tcdarms.ps}

L^{A}TEX normally determines the size of the EPS box (which it needs to know in order to leave an appropriate space) by scanning the EPS file until the %%Bounding Box pseudo-comment is encountered, from which the size of the (unscaled) graphic is read.

However, this box can be given explicitly by an optional argument to \includegraphics. If the graphicx package — a useful extension of the graphics package — is used, this box can be specified with the bb key:

    \includegraphics[bb = 89 162 523 630]{tcdarms.ps}

The EPS graphic can be scaled to any specified size in various ways, eg with the graphicx package by

    \includegraphics[width=1in]{picture.ps}

This results in the graphic being scaled so that it is 1in wide.

(Note that the effects of the bb and width options are quite different. The former does not cause any scaling of the graphic, and should match the Bounding Box comment in the EPS file.)

The present implementation of xdvi — following xhdvi — allows \includegraphics to import remote EPS files, provided the enclosing box is completely specified, eg using the bb option with the graphicx package, as above.

In truth, this proviso is required by TEX/L^{A}TEX rather than xdvi. For if the box is not specified, the \includegraphics macro calls on latex to open the EPS file, and read it until it meets the bounding box specification.

However, L^{A}TEX is not hyperTEX-aware, and so is unable to open a remote file.

As an illustration, one might include a remote picture by

    \includegraphics[bb=89 162 523 630,width=1in]%
      {ftp://ftp.maths.tcd.ie/pub/TeX/PS/tcdarms.ps}

Note that if the URL contains ~ or @ a little care is needed, eg

    \bgroup
    \makeatletter
    \let\~=\hyper@tilde
    \includegraphics[bb=89 162 523 630,width=1in]%
      {http://www.maths.tcd.ie/\~tim/PS/tcdarms.ps}
    \egroup

9 The last 2 specials

9.1 The image special

The 4th special takes the form

    \special{html:<img src="...">}

where the quotes enclose a filename.

This special is implemented in the hyperref package by the macro \htmladdimg, which takes just 1 argument, the filename, eg

    \htmladdimg{tim.au}

The effect is the same as if one had said

    \hyperlink{tim.au}{Click here}

except that the mime mechanism (as described above) is invoked immediately, without clicking on any text.

A remote file can be invoked in this way, at least if one makes the changes to hyperref.sty suggested in section 6.1.4 above to allow ‘escaping’, eg

    \htmladdimg{http://www.maths.tcd.ie/\~tim/tim.au}

Note that if a DVI file is given here, it will not receive special treatment; a new xdvi will be spawned to view it, if that is what is specified in the

.mailcap file.

9.2 The URLbase special

The 5th and last special takes the form

    \special{html:<base href=...>}

where an URL directory is specified, eg

    \special{html:<base href=http://www.maths.tcd.ie/~tim>}

The effect of this is that all local links are changed to remote links by prepending the URLbase.

In practice this facility is rarely if ever used (and no macro is offered by hyperref to implement it). The URLbase does nevertheless play an important rôle, but one that is automatically invoked.

In the first place, we can apply xdvi to a remote file — this should perhaps have been mentioned earlier — eg

    % xdvi http://www.maths.tcd.ie/~tim/hyperTeX

(Note that if the filename does not end in .dvi that is appended. This is the only place where that is done. For local or remote links the full filename must be given.)

In such a case the URLbase,

    http://www.maths.tcd.ie/~tim/

in this case, is abstracted, and becomes the current URLbase. This is subsequently prepended to any local link, converting it to a remote link.

The same mechanism is invoked if one has a link to a remote file, and that file has a link to a local file; the latter is converted to the appropriate remote link. (Honesty forces me to admit that I have never tested this feature!)