Re: Different types of link

[Joachim Noreiko <jnoreiko yahoo com>]

--- Joachim Noreiko <jnoreiko yahoo com> wrote:

> 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?
> 
> 

Sorry, don't know the mailing list convention for
this. So, in forum terminology... *BUMP*.
Shaun, is the third type of link possible in DocBook?


		
___________________________________________________________ 
How much free photo storage do you get? Store your holiday 
snaps for FREE with Yahoo! Photos http://uk.photos.yahoo.com