Different types of link

[Joachim Noreiko <jnoreiko yahoo com>]

While working on documentation, I've found there's a
need for different types of links.

The majority of links within the documentation files
are currently cross-references, made with the XREF
docbook element. This is an empty element that
automatically generates the link text. This means it's
usually used like this in the flow of text:

"For more on using the mouse, see [Section 2.2.1,
Mouse Basics]."
(where [ ] marks the hyperlink text)

This is fine, but if you have that sort of text more
than twice on a page, it starts to look a bit heavy.
Links are good, but they shouldn't impair readability.

For example, as I'm currently writing the section on
manipulating windows in the GNOME desktop guide, I
thought it would be a good idea to give links for
'resize pointer' (back to the section that lists all
mouse pointers, with images) and 'drag' (back to the
mouse basics section). 
For these, I've used the LINK element, which allows me
to specify the hyperlinked text.
I think a good rule of thumb is that forward links
(that jump ahead in the document) should use a
cross-reference, and backward links can be done with
plain link text, eg 'The [resize pointer] is shown
when the mouse is on the border.' Then again, looking
at Project Mallard (
http://www.gnome.org/~shaunm/quack/mallard.xml ), we
shouldn't really be thinking of documentation in
linear terms, but rather as a web. ('cross-linked up
the wazoo'! ;)

The downside of using LINK, as Shaun pointed out in
IRC, is that it won't appear at all in the printed
version of the manual.
In HTML & CSS, there's a neat technique to get round
this problem of the location a link points to being
hidden in print. You use CSS in a print-only
stylesheet to generate text after the link element
(see http://www.alistapart.com/stories/goingtoprint/ )
We could use the same idea here, so we'd get:
screen:  'The [resize pointer] is shown when the mouse
is on the border.' 
print:  'The resize pointer (section 2.2.2) is shown
when the mouse is on the border.' 
I mentioned this to Shaun yesterday, and he seemed to
think it was doable.

The third type of link is one to a different document.
I have no idea if this is possible, but I think it is
needed.
An example: we recently had a patch for the manuals of
two panel applets. The patch update the explanation of
how to add the applet to the panel. The extra material
was the same for both documents.
The method of adding an applet to the panel is also
explained in the desktop guide (or it should be).
If the help for each panel applet could link to that
section of the desktop guide,  we'd only have one
piece of text to maintain when it changes in the
future. Users wouldn't notice the difference; if
anything, it would be better for users because there
is less risk of some applets' helpfiles having out of
date instructions.

What do you all think?
Should I file an enhancement request for generating
section numbers on link in print?
What about making links to other documents?



		
___________________________________________________________ 
Yahoo! Exclusive Xmas Game, help Santa with his celebrity party - http://santas-christmas-party.yahoo.net/