\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.
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+)}.