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/ _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
