possible documentation viewer?

[Sean Wheller]

On Friday 03 June 2005 19:31, Jeff Waugh wrote:
> <quote who="Sean Wheller">
>
> > As I see it CSS does a much better job of formatting.
>
> We can use CSS in Yelp.

Why not? It provides a method for every project to customize the standards 
based X/HTML output from the NWalsh Docbook XSLs. So adding to the layout and 
formatting ability.

>
> > It would be much easier if I could just hyperlink to a glossterm in the
> > first sentence "Install a <link>DHCP</link> ... ."
>
> Yes, that would be nice. But it's not a showstopper.

Well yes and no. To you it is not, but to an author it is extra overhead. 
Personally I am tired of explaining what DHCP is over and again. In addition, 
having to break the thread of an explanation with side explanation makes docs 
longer than they need be. Readers get tired of reading and lose the plot when 
this happens too often. There is a reason why we have Glossaries and 
Bibliographies in the authoring and publishing world. The are like a Table of 
Contents or an Index.

Oh yes, that was the other thing we need. Automatic generation of the Index 
from Indexterm elements in the docbook xml. We have not yet started using 
this because we have enough to chew at present.

>
> > One of the very unique things here at Ubuntu is that we do have a need to
> > now produce docs for both distros. At KDE they just worry about KDE and
> > at GNOME they worry about GNOME and each satelite project takes care of
> > itself.
>
> That is incorrect. Common infrastructure is developed between the two (and
> other projects) on freedesktop.org.

I am aware of this, but we are not there yet.

>
> > Our circumstances are different.
>
> Only minimally, in that we happen to include KDE in the supported set. It
> is not our primary concern,

ubuntu/gubuntu/kubuntu are all of equal concern to me.

> however. What we do, we do as standards, and we 
> work with upstream (including freedesktop.org) to improve things where
> there are problems. In the mean time, we work with what we have, instead of
> making everyone's lives harder by adding more muck to the swamp.

I am happy to hear that you will start this ball rolling with upstream. 
However, does this mean that we must stay with the current problems just 
because they are only now awakening to the needs. I don'tthink we should. 
Therefore my approach is to standardize on docbook and the functionality it 
supports. To use all the functionality docbook supports in order to enable us 
to better manage our authoring effort. I do feel that somewhere in the future 
Yelp etc will be able to support the full suite of functions, but doubt if 
that will be before 5.10. Until then, if we stay true to Docbook in our src 
then it should be no problem for people developing help viewers to develop 
apps that support the requirements.

Meanwhile my solution is neutral and does not lock in or out of any route.

-- 
Sean Wheller
Technical Author
sean at inwords.co.za
084-854-9408
http://www.inwords.co.za
Registered Linux User #375355
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20050603/ee7792ff/attachment.pgp>