Archive-name: hypertex-faq This article contains information in question-answer format about HyperTeX. This FAQ list is maintained by Arthur Smith (asmith@mammoth.chem.washington.edu) so if you have questions or answers not on this list (or corrections), please send e-mail to that address. This is version 0.03, last changed June 29, 1995 Thanks due to: Sebastian Rahtz, Tanmoy Bhattacharya, Mark Doyle, Hiroshi Kubo, Alan Jeffrey and David Carlisle for helping to answer these questions. This FAQ is subdivided as follows: 0. Information sources. 0.1 How can I get a copy of the latest FAQ list? 0.2 What other information is available on HyperTeX? 0.3 How can I get the latest information automatically? 0.4 How can I help in developing HyperTeX? 0.5 Where do I find/send bug reports? 1. HyperTeX details. 1.1 What is HyperTeX useful for? 1.2 How is HyperTeX implemented? 1.3 What file formats does the standard specify? 1.4 What is a URL? 2. HyperTeX macro packages for TeX and LaTeX. 2.1 What macro packages are available? 2.2 How do I use hyperbasics.tex? 3. Available viewers. 3.1 What viewers/processors support the HyperTeX specials? 3.2 Is there a PC/Mac viewer out yet? 3.3 Xhdvi: 3.3.1 Compilation errors...? 3.3.2 Why does xhdvi take so long to start up? 3.3.3 How do I get xhdvi to bring up referenced files in format x? 3.4 HyperTeXView.app: 3.4.1 Why doesn't HyperTeXView.app work on my NeXT machine? 3.5 Acrobat: 3.5.1 Why does my .pdf file look ugly and take so long to display? 3.5.2 Why do some characters not display in my pdf file? 4. Miscellaneous questions. 4.1 What is the standard way to label x? 0. Information sources. 0.1. How can I get a copy of the latest FAQ list? This will be posted monthly to the hypertex-announce mailing list and to comp.text.tex, and intermittently to other lists or newsgroups as appropriate. The latest version should also be archived at snorri.chem.washington.edu in the file /pub/hypertex/hypertex-faq. 0.2 What other information is available on HyperTeX? Archives of the hypertex announcements are available by anonymous ftp at snorri.chem.washington.edu in /pub/hypertex/archives, and also available by e-mail request from majordomo@snorri.chem.washington.edu The ftp directory /pub/hypertex contains some of the HyperTeX software and macros, which is also mirrored at CTAN (ftp.shsu.edu). Other information is available from the Web page at Los Alamos: http://xxx.lanl.gov/hypertex/ 0.3 How can I get the latest information automatically? Subscribe to the hypertex-announce mailing list, which receives this FAQ monthly and also gets immediate announces of new software releases. Send e-mail to majordomo@snorri.chem.washington.edu with subscribe hypertex-announce in the body of the message. 0.4 How can I help in developing HyperTeX? There are many ways to help: adding support to existing viewers or writing new viewers, writing macro packages, or just getting involved in testing what we come up with. We especially need to get one of the PC or Mac TeX packages to support hyper-linking. If you want to help with this, you should also subscribe to the hypertex-dev mailing list. Send e-mail to majordomo@snorri.chem.washington.edu with subscribe hypertex-dev in the body of the message, and then e-mail to hypertex-dev@snorri.chem.washington.edu to let everybody else know what you're up to. 0.5 Where do I find/send bug reports? Generally, sending a bug report to hypertex-dev@snorri.chem.washington.edu should bring a response. You might instead want to send the report directly to one of the developers responsible (particularly if you've come up with a fix for it) - if you can't find the appropriate e-mail address, send me a note (asmith@mammoth.chem.washington.edu). We haven't yet set up a system for making bug reports generally available - check the "TODO" files of the software for a general idea of what might still be wrong. 1. HyperTeX details. 1.1 What is HyperTeX useful for? As any TeX user knows, TeX is the best word-processing software out there, particularly for scientific and technical literature, and best of all it's free. TeX is a language for creation of beautiful documents, but thus far it has been almost exclusively confined to the production of a paper end-product. HyperTeX was inspired by the success of the World Wide Web, and is an extension of TeX structure to embed within a document links to other parts of the document and to other documents. When viewed on-line, these links become active and allow the reader to move with greater ease within and between documents. External links can be to any document on the internet, in a manner compatible with the naming scheme used in the WWW. For LaTeX documents, there is often a very well defined internal structure (more sophisticated than the structured markup of HTML which is the basic language of the WWW), and the HyperTeX definitions allow a single-line modification of the source LaTeX file (inclusion of a specific macro package) to turn those internal structures into links and the document into an active hypertext. There are also several varieties of plain TeX for which similar modified macro packages are available. Thus far external links must be added by hand, but even this can be easier using TeX macros than the corresponding requisite effort in HTML. Obviously, hypermedia links are only really useful on-screen, and have no effect on the printed version of a document. On-screen viewing requires a viewing program, and the supported file formats (.dvi, a hyper .ps, and .pdf) are described in 1.3 below, while associated viewers are described in section 3. 1.2 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:} \special{html:} \special{html:} \special{html:} \special{html:} 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). Rather than just applying these "\special" commands directly, use of one of the macro packages (see section 2.) at least as a first step to "hyper-izing" a document is recommended. 1.3 What file formats does the standard specify? TeX and LaTeX automatically put the "\special" information specified above into the output ".dvi" file. There are currently ".dvi" viewers that can interpret these hyper-dvi files directly for X-windows and NextStep - see section 3. below. The hyper-linking information can also be preserved through the transformation processes normally applied to ".dvi" files prior to printing or display - currently this has been done through modifications to "dvips" producing PostScript output with Adobe's pdfmarks attached to allow internal document links. Adobe's distiller can then transform this into a well-linked ".pdf" file, although be warned that ".pdf" works a lot better with scalable postscript fonts than with the standard TeX bitmapped fonts. 1.4 What is a URL? URL stands for "Uniform Resource Locator", and is the name for the addressing system used by the world wide web (WWW). A typical URL looks like: http://xxx.lanl.gov/hypertex/ and if you haven't seen these things before, you've had your head in the sand... For details on the standards for URLs, consult the authoritative Web pages (at http://www.w3.org/). 2. HyperTeX macro packages for TeX and LaTeX. 2.1 What macro packages are available? hyperbasics.tex - by Tanmoy Bhattacharya: a basic set of macros for implementation of the HyperTeX specials. lanlmac.tex - by Paul Ginsparg: a minimal plain TeX macro package. hyperlatex.tex - also by T.B.: include before the \documentstyle of LaTeX (2.09) to replace ".sty" by ".hty" files. A variety of ".hty" files for different LaTeX styles are available. Note that this does NOT work with LaTeX2e because it uses undocumented latex internals. The above are available by ftp from: xxx.lanl.gov, directory pub/hypertex/ hyperref.dtx - by Sebastian Rahtz and Yannis Haralambous: a completely new, but compatible, implementation for LaTeX2e. available from CTAN, at macros/latex/contrib/supported/hyperref hyper.dtx - by Michael Mehlich: similar to hyperlatex, but for LaTeX2e. available from CTAN, at macros/latex/contrib/supported/hyper 2.2 How do I use hyperbasics.tex? The basic command to create a link is: \href{URL}{text} which, when viewed, will cause "text" to be highlighted, and clicking on text will bring up the referenced URL. For more sophisticated use you should probably refer to the "README" files with the various packages. 3. Available viewers. 3.1 What viewers/processors support the HyperTeX specials? A. Viewers for dvi files: xhdvi - due to Arthur Smith: X-windows previewer (based on xdvi version 18) available from ftp://snorri.chem.washington.edu/pub/hypertex/ Latest version (as of 6/18/95): 0.8a HyperTeXview.app - due to Dmitri Linde and Mark Doyle: NextStep previewer, based on TeXview.app available from ftp://gita.lanl.gov/people/doyle/HyperTeXview/HyperTeXview.tar.gz Latest version (as of 6/18/95): 0.1 beta 1 "Japanized xdvi" - due to Hiroshi Kubo: HyperTeX modifications to Japanese version of xdvi version 17 available from ftp://ueda9.kuee.kyoto-u.ac.jp/pub/xdvi/xdvi-17miyu+etc.hypertex.patch B. Processors for dvi files: dvihps - due to M.D. and T.B.: Hyper-Postscript converter (based on dvips due to Tom Rockicki). info available from http://nqcd.lanl.gov/people/doyle/README_HPS.txt C. Viewers for hyper-ps files: ghostview-hacked - due to Tanmoy Bhattacharya: (based on ghostview) see http://nqcd.lanl.gov/people/tanmoy/hypertex/README-ghostview-mods.html The latest release is gv1.5gs3.33hack, which works only with gs3.33. This is available from ftp://nqcd.lanl.gov/people/tanmoy/gv1.5gs3.33hack/ and is known to work on SunOS4.1.4, HP-UX9000/712, IRIX 5.3, Linux, all under X11R5. Still needs more testing... D. Processors for hyper-ps files: Adobe's distiller (commercial software) - converts to .pdf format E. Viewers for pdf files: Adobe's acrobat. The latest version of ghostscript (3.33) has some pdf capabilities. It doesn't work with ghostview though (yet). 3.2 Is there a PC/Mac viewer out yet? No. Let us know if you want to work on one! 3.3 Xhdvi: 3.3.1 Compilation errors...? The latest version of xhdvi (0.8a) requires the X11R5 Athena widget library. If you are running R4 on your system, a fix should come out soon. Meanwhile, precompiled versions of xhdvi (including the WWW library) are available from ftp://snorri.chem.washington.edu/hypertex/xhdvi_binaries for the following machines: Dec alpha-OSF/1 IBM RS6000/AIX Intel x86/NextStep SGI R3000/IRIX 4 Sun 3 and Sun 4/SunOS-4 If you have any problems compiling on these or other systems please send e-mail to asmith@mammoth.chem.washington.edu 3.3.2 Why does xhdvi take so long to start up? By default, xhdvi is compiled with an option to search all subdirectories of the XDVIFONTS etc directories to locate fonts suitable for display. If XDVIFONTS points to a large set of directories, this could take a long time, especially if the fonts are NFS mounted over a network. One solution is to be more explicit about which font directories you really mean to use. A better solution would be to use the "kpathsea" font searching methods - any volunteers for modifying xhdvi to support these libraries? 3.3.3 How do I get xhdvi to bring up referenced files in format x? If "format x" is not one of the standard types (dvi, postscript, jpeg, gif, audio, mpeg are common ones) or you don't have one of the requisite viewers available, you need your own "mailcap" file - the same "~/.mailcap" file used for Mosaic or Netscape should work for xhdvi. If the file extension used is unconventional, you may also need a "~/.mime-types" file specifying the connection between file format and extension. A sample is provided with the xhdvi source. Note that currently xhdvi can inline postscript figures using the "epsf" or "psfig" macro packages or style files. These need be specified only as local files (or with a relative URL name) for them to work properly when viewed remotely, as long as the remote dvi viewer knows the full URL of the main dvi file (which can be specified explicitly by the "base" \special). 3.4 HyperTeXView.app: 3.4.1 Why doesn't HyperTeXView.app work on my NeXT machine? It shares some start-up information (for the Display PostScript screen) with TeXView.app, and you need the version of that from NeXTStep release 3.2 or later. The updated versions of these files should be available on the network somewhere [any pointers?] 3.5 Acrobat: 3.5.1 Why does my .pdf file look ugly and take so long to display? By default, TeX uses "bitmapped" fonts. PDF relies on scalable postscript-based fonts for fast rendering, and bitmapped TeX fonts look ugly and take a long time to display. Unfortunately there aren't many scalable postscript fonts freely available. The Type1 CM fonts developed by Basil Maylshev, called BaKoMa, are free for non-commercial use. These are available from CTAN in the directory fonts/cm/ps-type1/bakoma Using commercially available type-1 fonts in documents you intend to distribute to the public may violate your license for the fonts - check the fine print... 3.5.2 Why do some characters not display in my pdf file? At least some (old?) versions of distiller do not work well with the type-1 cm fonts because distiller assumes that character code 32 if used will always be whitespace, whereas TeX encodes other characters into this slot. The solution is to use a newer version of Acroexchange (the distiller). 4. Miscellaneous questions 4.1 What is the standard way to label x? The various subsections of a document can be referenced as part of a URL description through the "#" extension to the URL name. We have been using the following standard names for ease of linking into HyperTeX documents based on the macro packages currently available: Page 5 is at doc.dvi#page.5 Section 2 is at doc.dvi#section.2 Equation 3 is at doc.dvi#equation.3 Reference 11 is at doc.dvi#reference.11 similar definitions thus far exist for subsection, figure and table entities. New macro packages or style files should try to conform to this naming scheme (see the currently available packages for details on how this is done).