texinfo: @url

Cross References

@cite

@inforef

Back to Software Index

8.9 '@url', '@uref{URL[, TEXT][, REPLACEMENT]}'
===============================================

'@uref' produces a reference to a uniform resource locator (url).  It
takes one mandatory argument, the url, and two optional arguments which
control the text that is displayed.  In HTML output, '@uref' produces a
link you can follow.

  '@url' is a synonym for '@uref'.  (Originally, '@url' had the meaning
of '@indicateurl' (Note: @indicateurl), but in actual practice it was
almost always misused.  So we've changed the meaning.)

  The second argument, if specified, is the text to display (the default
is the url itself); in Info and DVI output, but not in HTML output, the
url is output in addition to this text.

  The third argument, if specified, is the text to display, but in this
case the url is not output in any format.  This is useful when the text
is already sufficiently referential, as in a man page.  If the third
argument is given, the second argument is ignored.

  TeX allows line breaking within urls at only a few characters (which
are special in urls): '&', '.', '#', '?', and '/' (but not between '/'
characters).  A tiny amount of stretchable space is also inserted around
these characters to help with line breaking.  For HTML output, modern
browsers will also do line breaking within displayed urls.  If you need
to allow breaks at other characters you can insert '@/' as needed (Note:
Line Breaks).

  By default, any such breaks at special characters will occur after the
character.  Some people prefer such breaks to happen after the special
character.  This can be controlled with the '@urefbreakstyle' command
(this command has effect only in TeX):

  Write this command at the beginning of a line with a single word as an
argument, one of the following:

'after'
     (the default) Potentially break after the special characters.
'before'
     Potentially break before the special characters.
'none'
     Do not consider breaking at the special characters; any potential
     breaks must be manually inserted.

  Here is an example of the simple one argument form, where the url is
both the target and the text of the link:

     The official GNU ftp site is @uref{http://ftp.gnu.org/gnu}.

produces:
     The official GNU ftp site is <http://ftp.gnu.org/gnu>.

  An example of the two-argument form:
     The official @uref{http://ftp.gnu.org/gnu, GNU ftp site}
     holds programs and texts.

produces:
     The official GNU ftp site (http://ftp.gnu.org/gnu)
     holds programs and texts.

that is, the Info output is this:
     The official GNU ftp site (http://ftp.gnu.org/gnu)
     holds programs and texts.

and the HTML output is this:
     The official <a href="http://ftp.gnu.org/gnu">GNU ftp site</a>
     holds programs and texts.

  An example of the three-argument form:
     The @uref{/man.cgi/1/ls,,ls} program ...

produces:
     The ls program ...

but with HTML:
     The <a href="/man.cgi/1/ls">ls</a> program ...

  Some people prefer to display urls in the unambiguous format:

     <URL:http://HOST/PATH>

You can use this form in the input file if you wish.  We feel it's not
necessary to include the '<URL:' and '>' in the output, since any
software that tries to detect urls in text already has to detect them
without the '<URL:' to be useful.

  To merely indicate a url without creating a link people can follow,
use '@indicateurl' (Note: @indicateurl).