5  Referring to external documents

The command

\urlhd{URL}{HTML text}{DVI text

lets you link to arbitrary URLs, not just to labels within your document (although it can do that too). In the HTML output, a hyperlink to ‘URL’ is created, with the link text being ‘HTML text’. In the DVI output, the part ‘DVI text’ is output. Example:

For more details, consult 
\urlhd{http://www.ithaka.org/odyssey.html}{the Odyssey}{the 
{\it Odyssey\/} document in the Ithaka repository}. 

In the DVI output, this becomes

For more details, consult the Odyssey document in the Ithaka repository.

In the HTML output, it would be

For more details, consult the Odyssey.

where “the Odyssey” is an HTML link to the site http://www.ithaka.org/odyssey.html.

\urlhd is named to be mnemonic for its argument sequence, viz., the URL, followed by the Html text, followed by the Dvi text.

Note that you can use \urlhd for cross-referencing within the document also. The URL in such cases will be a label as specified by a \label or a \xrtag command, but should add a ‘#’ prefix. E.g.,

See \urlhd{#hairy}{below}{section~\ref{hairy}} 
for further details. 

where the further details are described in a section annotated with \label{hairy}. Assume this section is numbered 21. Then, the reference typesets as “See section 21 ...” in the DVI output and “See below ...” in the HTML output (with below being a link). In contrast, if we had written

See section~\ref{hairy} for further details. 

we would have had “See section 21 ...” in both DVI and HTML. \urlhd is thus more flexible than \ref.

Because of page breaks in the HTML output (p. 4), it is possible that a label’s definition and the references to it do not ultimately sit on the same physical HTML page. Nevertheless, your TeX source can use #tag-style URLs to refer to anchors anywhere within it. TeX2page will automatically convert a #tag-style URL to its correct fully qualified equivalent.

Common hyperlink abbreviations

In some cases, \urlhd’s second and third arguments may be mere repetitions of a preceding argument. For such cases, TeX2page recognizes some convenient abbreviations, viz., \urlh, \urlp, and \url. (A version of \urlh is provided under the name \href by the LaTeX package hyperref.sty, and \url is provided by the LaTeX package url.sty. \url.sty is loadable in plain TeX with miniltx.)

\urlh takes two arguments. The first argument is the URL, and the second is the descriptive text that is used in both the HTML and the DVI outputs. For example:

\TeX\ is available at 
\urlh{http://www.tug.org}{the TUG website}. 

produces

TeX is available at the TUG website.

In the HTML output, “the TUG website” is a hyperlink to http://www.tug.org.

An optional \\ may be used inside \urlh’s second argument. The text before the \\ is used in both the HTML and the DVI outputs. The text after the \\ is used only in the DVI output. This helps you to specify extra information for the DVI output, which may be necessary because the DVI output lacks the information implicit in the hyperlink. For example:

\TeX\ is available at 
\urlh{http://www.tug.org}{TUG\\ (\path!tug.org!)}. 

produces, in the DVI output.

TeX is available at TUG (tug.org).

The HTML output will not mention the parenthesized domain name, since the word “TUG” already hyperlinks to it.

\\ is useful for internal cross-references too. For example (assuming the label callcc refers to section 2.3):

More complicated forms of program control are possible 
using \urlh{#callcc}{{\tt callcc}\\ (section~\ref{callcc})}. 

produces

More complicated forms of program control are possible using callcc (section 2.3).

in the DVI output. In the HTML output, the parenthesized section reference will be dropped as redundant, as the word “callcc” hyperlinks to the relevant section.

An optional \1 may be used after \\ to refer to \urlh’s first argument, i.e., the URL. Example:

\TeX\ is available at 
\urlh{http://www.tug.org}{TUG\\ (\1)}. 

produces

TeX is available at TUG (http://www.tug.org).

in the DVI output. In the HTML output, the parenthesized URL is dropped as redundant, as the word “TUG” hyperlinks to it.

Finally, the combination of \xrtag and \urlh is useful for inserting internal cross-references in the HTML document without affecting the print document. For example, the following text

\xrtag{ex1}{ignore} 
\urlh{#ans1}{\bf Exercise 1.} Statement of a problem ... 
 
... lots of intervening stuff ... 
 
\xrtag{ans1}{ignore} 
\urlh{#ex1}{\bf Answer 1.} Answer to exercise 1 ... 

prints as

Exercise 1. Statement of a problem ...

... lots of intervening stuff ...

Answer 1. Answer to exercise 1 ...

in both the DVI and the HTML. However, in the HTML, the proclamations “Exercise 1.” and “Answer 1.” are also helpful hyperlinks to each other.

\url takes just one argument, the URL. For the descriptive text, both the HTML and the DVI outputs simply use the URL itself. Example:

\TeX\ is available at \url{http://www.tug.org}. 

\urlp takes two arguments. In the HTML output, the first argument is the link text and the second is the URL. In the DVI output, the first argument is typeset followed by a space followed by the URL in parentheses. \urlp{text}{URL} abbreviates \urlh{URL}{text\\ (\path+URL+)}.