Overview

• For the impatient LaTeX users who just want to do it, go to the Quick Hyperref Guide.
• Try an example pdf document. If acroread doesn't work you may try FAQ .
• The TeX purist can read the section on for an introduction to their special problems.

Why this now

Two things changes have occured that makes this program more attractive. The first is that the "hyperref" [ distribution , manual.pdf ] package is distributed as part of teTeX so presumably it will be reasonably stable. The second is that viewers are now generally available for most common computers and operating systems which make the results of the effort available to essentially everyone who uses the web.

The basic idea

Those who want to make TeX and LaTeX documents available on the web and who also want future portability should maintain their TeX files as original source. Make as few changes as possible in these documents, and the changes that you do make should be consistent with the " hyperref " macros. Minimally, a single command

	\RequirePackage{hyperref}

Once you have fixed up your LaTeX file to include the hyperlinks, you run latex as usual. This creates a .dvi file which contains link information. Using xhdvi instead of xdvi, you can view this document and follow the links.

Since many people cannot run xhdvi and xdvi from their computers, it is for the time being necessary to generate a format which is more universal than .dvi before making the document available on the web. The .pdf format seems to fill that role and there is a free reader, acroread available from Adobe which runs on virtually all computers and operating systems.

At fy.chalmers.se on the Unix workstations you can create the pdf file by running dvips -z (or dvips -z -P type1 ) to create a Post-Script document, which is then converted to Adobe's .pdf format by using distill. The pdf file is placed in the web directory and made publicly available.

In the long run, I am convinced that a dvi viewer will become functional (see idvi ); as long as you keep the original document as standard LaTeX format, you should have no problem taking advantage of that in the future. Many of the problems listed below will disappear when it makes sense to make the dvi files publicly available rather than the pdf files.

A good idea is to let hyperref automatically fix links internal to the document to the fullest extent possible so that you can minimize changes to your own document when updates to hypperref occurs. Link external documents sparingly and if necessary, with stable links and stable files. It is much more of a nuisance than in HTML to fix up an indidual link which has gone out of date since you may have to rerun a bunch of slow commands just to accomplish this change in the viewed document.

Problems

• no good TeX support here (see this section.)
  
  
• reliance on pdf files

  Although we use the .pdf format for viewable files, it does have the drawback that the format is controlled by Adobe. Right now, the pdf-reader acroread is free, but it is not public domain. Everyone in the physics department ought to be able to read .pdf file, if necessary by getting their own copy of acroread .

  To generate the .pdf files from LaTeX you must use a version of dvips that has the -z flag to pass LaTeX "\special" properly to PostScript. To generate pdf from PostScript we suggest you use "distill." The program "dvips" is public domain, and "distill" is available in the Acrobat package from Adobe. We have installed both of these for Suns on fy.chalmers.se. Users of these machines should have no trouble generating the pdf files. Other users may have difficulties with either or both of these programs. The easiest solution may be to make the latex-pdf conversion on a Sun workstation.

  Since I believe that a solution like idvi (below) may eventually obviate the need for pdf format, we will wait to install Acrobat and distill more widely.
  
  

• acroread is tedious and the screen fonts that permits me to view a whole page give me eyestrain.
  
  
• cycle time ... edit-latex-dvips-distill is tedious, largely because distill is slow.
  
  

Other solutions

A number of programs are available that claim to do some or all of the functions discussed above that we do make an effort to support.

• latex2html will generate an "html" file from latex, but the equations look very poor and it seems to break down when there are lots of macros. I have not found latex2html satisfactory for a typical latex document, but you can try it with the command "latex2html." Here is an online manual.
• idvi should enable everyone to directly read the .dvi files by building in the viewer as part of the downloaded file and may be the best solution in the long run. In my opinion, it is the only realistic solution that does not involve putting pdf files on the web. It is public domain, so we could provide the dvi file directly to anyone with a java-enabled browser. But it is under development and we are not prepared to support it now.
• Platform-specific dvi viewers are available that support links: nDVI and xhdvi
• Platform-specific pdf viewers other than acroread exist: xpdf , ghostscript3.33 and ghostscript-5.10 . At this point, I see no advantage of these over acroread.
• ghostview-5.10 can also convert from Post-Script to pdf. However, at this point there seems to be no reason to prefer ghostview for this purpose if you have access to ``distill''.
• acroexch (part of the Adobe Acrobat package) is a pdf-editor. If you use that feature, however, you will no longer have the LaTeX document as the source and when you want to change your latex document, you will lose the changes you made in the old document using the pdf-editor. However, the little "post-its" you can glue in your pdf-document for instance, might be pretty useful for making temporary comments in class notes, for instance.

How is HyperTeX implemented?

TeX and LaTeX output is in the form of a ".dvi" file, the letters being short for "device-independent". ".dvi" files are not completely self-contained because they depend on external font files, but aside from that they describe the formatting of a document in a fashion independent of the display or printing device. The ".dvi" format is also arbitrarily extendible, due to the "\special" command of TeX, which allows new display commands to be embedded in the ".dvi" file. The "\special" command has previously been used to extend TeX by allowing inclusion of line drawings, PostScript figures, and colored text. HyperTeX adds five new "\special" commands to the menagerie. These are:

       \special{html:<a href = "hrefstring">}
       \special{html:<a name = "namestring">}
       \special{html:</a>}
       \special{html:<img src = "hrefstring">}
       \special{html:<base href = "hrefstring">}

These are identified as HyperTeX specials by the first 4 characters, "html". The first three commands establish links between sections of documents in a manner exactly analogous to the HTML of the WWW. The "img" command is intended to place an image of arbitrary graphical format on the page, although currently it is implemented as bringing up automatically an external viewer of the appropriate type. The "hrefstring" values are arbitrary relative URL's, except for the "base" command. The latter gives the full URL of the current document, which is necessary because WWW browsers do not communicate this information to external viewers (such as a hyper-dvi browser).