############################################################
# @(#) Links, Dirk Hagedorn, 1996/04/18
############################################################

!subsubnode Links

Sometimes you maybe want to set a link to other parts of the current
document or to other documents. To make it possible for you to insert
links UDO offers you the placeholders called (!I)(!/link!..)(!i),
(!I)(!/xlink!..)(!i) and (!I)(!/plink!..)(!i).

(!HINT) If you want to use a ""("" or a ""]"" inside a link you have to
quote it with an exclamation mark:

!begin_quote
!begin_verbatim
Wrong: (!link [Brackets])] [Link])
Right: (!link [Brackets!]!)] [Link])
                       ----
!end_verbatim
!end_quote

#--------------------------------------------------
!subsubsubnode Internal links

!index (!/link!..)

Using the (!I)(!/link!..)(!i) command you can insert links to parts of
the current document. You can link to chapters, sections, subsections,
labels and aliases. The following list shows you how to use the link command
and how UDO converts it:

!begin_quote
!begin_verbatim
UDO:       (!link [a word] [the link])
HTML:      <a href="file.htm#the link">a word</a>
LaTeX:     a word (see \ref{the link})
ST-Guide:  @{"a word" link "the link"}
WinHelp:   {\uldb a word}{\v the_link}
Turbo:     {a word:the_link}
else:      a word (see "the link")
!end_verbatim
!end_quote

The following example shows how to insert a link to my contact addresses:

!begin_quote
!begin_verbatim
If you want to register UDO,
please send (!link [me] [Contact addresses])
an email.
!end_verbatim
!end_quote

!.. will be displayed this way:

If you want to register UDO,
please send (!link [me] [Contact addresses])
an email.

(!HINTS)

!begin_enumerate

!item	You may use up to (!MAXLINKS) inside a paragraph. If you will use
more links UDO will print an error message.

!item	When converting to hypertext formats UDO checks if the link
destination exists. If it doesn't exits UDO prints an error message.
When converting to the other formats UDO doesn't check if the link
destination exists!

!item	(!LaTeX) only allows it to link to aliases and labels.

!end_enumerate

#-----------------------------------------------------------
!subsubsubnode Internal links with images

!index (!/ilink!..)

Especially for Windows Help and HTML there's existing the
(!I)(!/ilink!..)(!i) (""image link"") commands. It is a mixture of
the (!I)(!/img!..)(!i) and (!I)(!/link!..)(!i) command that allows one to
display ""hyperimages"". If you click an image you will jump to
another part of the current document.

!begin_quote
!begin_verbatim
UDO:      (!ilink [img] [text] [link])
WinHelp:  {\uldb \{bmc img.bmp\}}{\v link}
HTML:     <a href="link"><img src="img.gif" alt="text"></a>
else:     like (!link [text] [link])
!end_verbatim
!end_quote


(!HINTS)

!begin_enumerate

!item	UDO won't check if the images exist.

!index !/html_img_suffix
!item	By default UDO uses ''(!V).gif(!v)'' as the suffix for images when
converting to HTML. You can use the command (!I)!/html_img_suffix(!i) to
change the suffix.

!item	You may use up to (!MAXLINKS) inside a paragraph. If you will use
more links UDO will print an error message.

!end_enumerate

#-----------------------------------------------------------
!subsubsubnode Internal links to pages

!index (!/plink!..)

Especially for (!LaTeX) there's existing the (!I)(!/plink!..)(!i)
(""page link"") command:

!begin_quote
!begin_verbatim
UDO:    (!plink [link commands] [Links])
LaTeX:  link commands (see page \pageref{Links})
else:   link commands
!end_verbatim
!end_quote

The following example shows how to insert a page like to the page that
contains my contact addresses:

!begin_quote
!begin_verbatim
If you want to register UDO,
please send (!plink [me] [Contact addresses])
an email.
!end_verbatim
!end_quote

!.. will be displayed this way:

If you want to register UDO,
please send (!plink [me] [Contact addresses])
an email.

(!HINTS)

!begin_enumerate

!item	You can only insert page links to labels and aliases, not to
chapters when converting to (!LaTeX).

!item	You may use up to (!MAXLINKS) inside a paragraph. If you will use
more links UDO will print an error message.

!end_enumerate

#-----------------------------------------------------------
!subsubsubnode External links

!index (!/xlink!..)

With the (!I)(!/xlink!..)(!i) (""external link"") command you can
insert links to (parts of) other documents, net sites or
hypertexts. The difference to the upper command: UDO doesn't adjust
special chars of the link destination. The tilde isn't a non-breaking space
in the link destination, too.

!begin_quote
!begin_verbatim
UDO:       (!xlink [UDO] [*:\udo.hyp])
ST-Guide:  @{"UDO" link "*:\udo.hyp"}

UDO:       (!xlink [Atari] [http://www.atari.com])
HTML:      <A HREF="http://www.atari.com">Atari</A>

UDO:       (!xlink [UDO] [Titel@d:/winhelp/udo.hlp])
WinHelp:   {\uldb UDO}{\v Titel@d:/winhelp/udo.hlp}

else:     UDO (or Atari)
!end_verbatim
!end_quote


#----------------------------
!ifdest [win]
How to use external links inside a Windows Help file is descriped in the
following example:

!begin_quote
!begin_verbatim
""The guide to (!xlink [WinHelp] [1@winhelp.hlp])!..""
!end_verbatim
!end_quote

!.. will be displayed this way:

!begin_quote
""The guide to (!xlink [WinHelp] [1@winhelp.hlp])!..""
!end_quote

!endif
#----------------------------
!ifdest [stg]

How to use external links inside an ST-Guide file is descriped in the
following example:

!begin_quote
!begin_verbatim
""The (!xlink [Atari Infopages] [*:\aip.hyp])!..""
(!nl)
""The guide to the (!xlink [HCP] [*:\hcp.hyp])!..""
!end_verbatim
!end_quote

!.. will be displayed this way:

!begin_quote
""The (!xlink [Atari Infopages] [*:\aip.hyp])!..""
(!nl)
""The guide to the (!xlink [HCP] [*:\hcp.hyp])!..""
!end_quote

!endif
#----------------------------
!ifdest [html]

How to use external links inside an HTML file is descriped in the
following example:

!begin_quote
!begin_verbatim
""(!xlink [Yahoo] [http://www.yahoo.com])!..""
(!nl)
""(!xlink [Web.De] [http://web.de])!..""
!end_verbatim
!end_quote

!.. will be displayed this way:

!begin_quote
""(!xlink [Yahoo] [http://www.yahoo.com])!..""
(!nl)
""(!xlink [Web.De] [http://web.de])!..""
!end_quote

!endif

#-----------------------------------------------------------
(!HINTS)

!begin_enumerate

!item	You have to use existing topic names for Windows Help. A topic name
must contain only numbers and characters form the alphabet. All other
characters will be converted by UDO.

!item	You should use ''(!V)*:\(!v)'' at the beginning of an external link
for the ST-Guide to tell it to look for the hypertext in all directories you
defined with (!V)PATHS(!v) in your (!V)ST-GUIDE.INF(!v).

!index !/no_xlinks
!item Using the switch called (!I)!/no_xlinks~[!..](!i) you can
suppress the conversion of external links. This is useful if you wrote
a source file especially for HTML and you want to make a version for
Windows Help or ST-Guide, where the external file wouldn't make no
sense.

!end_enumerate