Slight reorganisation of Ubuntu material in trunk

[Matthew East]

Hi,

Bhuvaneswaran <bhuvan <at> ubuntu.com> writes:

> > <IMPORTANT>
> > The creation of these articles has meant that loads of cross-reference
> > links are now broken (for example, each time the desktopguide says "See
> > add-applications", this is broken). All these links need to be fixed to
> > point at the right place. This should not take too long, hopefully.
> > </IMPORTANT>

{snip}

> So, to overcome this issue, can we use "ulink" tag. For example, to
> refer "add-applications" section from desktop guide, we can use:
> 
> <ulink     
url="../../add-applications/C/add-applications.xml#add-applications">Add
> Applications</ulink>

This is quite a tricky problem. I don't know whether this solution works to
point at specific section ids, and we would also need to figure out how to make
it work nicely with translations (we can work around that I think) and HTML
generation (I do not think the processing system we have now will retain the
correct links for the HTML).

I have spent some time discussing this issue with Sean McCance from Gnome
upstream and it seems that there isn't a particularly nice way to resolve this
problem.

One option which I am starting to think is going to be the best one is to use
the built in functionality that yelp has to refer to other documents in the help
system: <ulink type="help" url="ghelp:document?sectionid">link text</ulink>.
This ensures that the links work nicely, we can cross reference to individual
sections, and the translations will work.

This doesn't convert nicely to html. So we'd either have to do something funky
(read find/replace) before/after building html, or not build it at all.

Note: this solution is Ubuntu specific: I am not sure what the best approach is
for Kubuntu. Probably there is a similar solution.

Matt