Linking to websites

Linking to websites
	Chapter 15. Cross references

Creating a link from your DocBook document to a website is easy. You use the ulink element, putting the target URL in the ulink's url attribute. For example:

For more information on DocBook, go to the
<ulink  url="https://sourceforge.net/projects/docbook/">DocBook 
SourceForge website</ulink>
or to <ulink  url="http://docbook.org"/>.

The first ulink example is not empty, so its text content becomes the hot text in HTML output. The second ulink is empty, so the stylesheet will automatically copy its URL to use as the hot text.

In HTML output, you can have the target document appear in a separate window if you set the ulink.target parameter to a different window name. That adds a target attribute to the HTML anchor tag. By default, the parameter's value is _top, which loads the content into the topmost frame, which is likely the same window.

For FO output, you can choose whether the url attribute value for the ulink is printed. If you just set the parameter ulink.show to nonzero, then the URL appears in square brackets after the ulink text. If you also set the parameter ulink.footnotes to nonzero, then the URL becomes a footnote to the ulink text. Regardless of the parameter settings, if the URL exactly matches the ulink text string (or the ulink element is empty, which produces the same result), then the stylesheet does not repeat the same URL in brackets or a footnote.

Breaking long URLs

In print output, long URLs that start near the end of a line may need to be broken to format nicely. The problem is that URLs have no spaces, and so will not be line broken on a space. If you try to insert zero-width spaces in the ulink url attribute to allow breaks in the printed form, you will find that the URL no longer works as a link. If you copy the url to the ulink element content and add the zero-width spaces there, you will find that the stylesheet no longer treats them as the same and repeats the URL after the text.

You can solve this problem by using a feature of the print stylesheet to enable hyphenation of ulink URLs, with a hyphenation character that you specify. The way it works is you set the stylesheet parameter ulink.hyphenate to contain some character. When that parameter is not empty, then that character is inserted by the stylesheet into the printed version of the URL after every character that is included in the stylesheet parameter ulink.hyphenate.chars (which is set to / by default). Generally you should set ulink.hyphenate to either Unicode soft hyphen () or Unicode zero-width space (). The former will generate a hyphen if the URL breaks, and the latter will not. However, not all processors support both characters, so you should test. If you want more opportunities for breaking in a URL than just after / characters, then you can expand the set of characters in ulink.hyphenate.chars.

The following example allows breaks after slash, ampersand, and question mark in a URL, and does not display a hyphen at the break:

<xsl:param name="ulink.hyphenate.chars">/&amp;?</xsl:param>
<xsl:param name="ulink.hyphenate">&#x200B;</xsl:param>


Cross references between documents		DocBook 5 cross references