Re: Cross-linking [was Re: Organization of gnome-user-docs, display in yelp]

[Pat Costello <Patrick Costello Sun COM>]

On 14 Feb 2003 Sasha said: 

> Why? We have this general "ghelp" url which allows us to link from any
> document to any other. E.g., I could put in "Intro to gnome" 
> <ulink url="ghelp:gnome-terminal">GNOME Terminal Manual</ulink>
>  and get a link which, when clicked in Yelp, would bring up GNOME
> Terminal manual.  Same can be done when linking from one chapter to
> another.  Or am I missing something?
> 
> What is currently impossible is to use <xref> for linking between
> documents - but this is just a minor inconvenience. 
> Sasha
> 
Eugene was talking about using the <xref> tag. Eugene has to write his source 
files in sgml first, to go through the Sun publishing processes. Then he uses a 
converter to create generic xml files for open-source use. He could not use the 
ghelp url solution during this process. 

However, the original reason why we split up the user guide into chapters - i.e. 
slowness of display in Yelp, has now been resolved by the use of pre-generation. 
Therefore, in the next major release of the GNOME desktop, we should submit the 
user guide as a single book. The chapters would then be organized in a logical 
fashion as the writing team intended. Also, this would facilitate the use of  
<xref> tags within the single book user guide, so both the problems of 
organization and cross-referencing are resolved. 

Instead of the current random listing of subject titles, the top-level of Yelp 
should contain: 

- Big Book Title 1
- Big Book Title 2
- Big Book Title 3
...

As Sander pointed out, there will need to be some rejigging of Help links into 
the user guide, but that can be done. 

Pat