possible documentation viewer?

[Sean Wheller]

On Friday 03 June 2005 15:38, Henrik Nilsen Omma wrote:
> Sean Wheller wrote:
> >Yes, but it only supports on-the-fly transformation of xml that conforms
> > to the GNOME requirements. For ubuntu-doc purposes Yelp does not support
> > a mountain of things and is not easily customizable. As a result we will
> > be transforming to X/HTML a format supported by Yelp and KHelpcenter, but
> > we will support viewing under any web browser.
> >  
>
> OK, I'm going to jump in here with some questions: Does the Ubuntu and
> Kubuntu help content live in the same package, 

Not the same package, but often the same XML-instance. Example: FAQ Guide and 
Installation Guide. As time goes on we may even use this method more in order 
to reduce the overhead of developing and maintaining docs for both distros. 
At present the quick guides and the user guides and release notes are 
separate XML-insances for each distro.

> and if so can we split it 
> up? 

Split up is always possible. Just additional overhead. For example: There are 
many things shared between ubuntuguide.org and kubuntuguide which is based on 
ubuntuguide. The same if you look at the PPC version of ubuntuguide.org

Duplication of the information is just a maintenance overhead we can do 
without :-) We are also considering i18n here.

It is possible to preprocess the profiled xml-instances to arrive at new 
xml-instances, one for each document type (gnome, kde, PPC, etc.) and then to 
use that. Read on ...

> It sounds sensible to generate Ubuntu help files from DocBook that 
> work well in Ubuntu's native Yelp and also generate
> KHelpcenter-compatible XML files that can be included as a separate
> package in Kubuntu.

Would be nice if yelp and khelpcenter did the same thing and worked in the 
same way. Alas they do not. Hence we have a compatability issue.

XML for yelp will not work well for Khelpcenter. Khelpcenter does not 
transform XML on the fly. So we need X/HTML. Now the problem is how to deal 
with gnomes xref method. They use ghelp:foo to make refs between docs. If we 
have a text that is common to gnome and kde and it contains an xref, it will 
work in yelp, but not in khelpcenter as html.

> A third process would generate pure HTML files that 
> we can put on the web. That's the advantage of DocBook right?, that once
> you have the content in that format you can quite easily export it in a
> number of ways.

Yes, this is the idea.

>
> I agree with Jeff that the best way to improve and expand Yelp (if that
> is indeed needed) is to suggest changes to the upstream people (or
> submit patches).

Happy to have expansion on yelp. Just did not see it happening, so moved on. 
No point beating your head against the wall too long :-)

>
> >So what we will be packaging with the distro is the X/HTML web-based
> >application.
>
> Which application? Does this exist or is it vapor-ware? Firefox is too
> complex and takes too long to load just to display help files. The spec
> writing for breezy was done at UDU and implementation is well under way,
> so it's really too late to suggest new applications. The balance of
> applications in Ubuntu is carefully constructed based on many factors
> (useability, upstream support, stability, etc.) We cannot simply add
> applications at a whim.
>

No, no. I do not mean an executable application. I mean a web-based 
application. Remember the diagram I uploaded to svn and sent. I attach it 
again. Moderator please release it to the list. The frameset we spoke about. 
It's the same set of files that we would put on help.ubuntu.com.

-- 
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: ubuntu-help-scratch.png
Type: image/png
Size: 28330 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20050603/19e0eae7/attachment.png>
-------------- 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/19e0eae7/attachment.pgp>