To Yelp or not to Yelp? That's the Question

Fri Mar 4 10:34:12 UTC 2005

Hi,

I have been pushing not to use yelp for ubuntu docs. This has created some 
confusion and people are not sure why I am doing so. Hopefully this will 
clear it up.

First, let me be clear. I am not saying get rid of yelp. While I belive the 
days of help viewing tools are numbered, there is obviously a current need 
for yelp under a gnome desktop. All the GDP documents are available from it. 
However, yelp assumes that the person will be running gnome and using gnome 
apps. Since ubuntu does intend having a KDE desktop (kubuntu), and there may 
be more, I would recommend that the primary method for viewing ubuntu docs 
should be any Web browser. This will ensure compatability across desktops. 
Since a KDE user may not have yelp installed it makes sense to provide a 
method to view ubuntu docs on any desktop.

While yelp is a great tool for viewing Online Help, especially if the Docbook 
source is developed in strict compliance with the GDP rules, features 
implimented by the GDP are not portable across viewing methods. For example, 
the use of ghelp: values for inter-document cross references only works in 
yelp.

In addition Yelp has patchy support of some publishing features that we could 
really use to assist users and generally improve the docs. Some of the 
features not currently supported are:
* Glossary
* Index
* Bibliographies
* External cross-referencing (olink)
* Profiling (conditional text)
* CSS styling
* Scripting

The reason why yelp does not support these feature is because the GDP is 
focused on GNOME. They only support what they need as apposed to supporting 
everything. This makes absolute sense, since docbook is large and the xsl's 
are hectic. They don't need to support everything.

The GDP is focused on documenting a desktop and apps. At ubuntu we are focused 
on an OS. Although I think many people get confused because much focus is on 
the desktop. In fact some people think ubuntu is a GNOME only distro. As far 
as I know it was not intended to be indefinitely so, the decision to go with 
GNOME for now was more due to resources at the time than it was about being a 
desktop specific distro. 

Personally I would like to see wide desktop support but the problem is that 
there is a level of incompatibility between desktops. While freedesktop.org 
is making progress to close the gap, the reality is that the gap is not 
closed and we therefore have to remain with the problem of how to support 
them.

For these reasons I am asking that we target the ubuntu docs to be accessible 
from all desktops using any browser. This will mean that we use the docbook 
standard DTD and XSL's shipped by the project and transform to any of the 
following formats: HTML/XHTML, PDF, HTML-help. All can be displayed in any 
browser.

Using this method enables us to use the full publishing feature set and build 
an Ubuntu customization layer. It also better enables us to benefit from the 
advances in development comming from the Docbook community. Some may know 
that Docbook 5.0 is around the corner and the long awaited availability of 
RelaxNG (RNG) will come with it. Moving to RNG will solve many problems of 
DTD and will enable many new possabilities for us. I cannot see Yelp 
providing immediate support for RNG and the entire set of publishing 
capabilities available with native docbook.

<sidebar>
On https://www.ubuntulinux.org/wiki/DocteamPostHoary I have mentioned "Blue 
Sky" that I would like to develop using XUL the UbuntuBar and 
UbuntuNavigator. 

These tools would only work in Mozilla and Firefox. However, since most 
desktops install firefox they will be accessible. The idea is that the 
UbuntuBar will add a toobar to firefox that provides menu options linking to 
various resources both in the installed ubuntu docs and ubuntu.com. The 
UbuntuNavigator provide the left side panel tree view users get in yelp and 
kde help center.

The UbuntuNavigator can be served from localhost or from a web server. I will 
provide search features across ubuntu docs and interlinking in a standard way 
using uri. I am also contemplating xlink.

The other tool I mention is UbuntuDocNote. This tool enables users to add 
notes inline to the current document. Notes can be distributed to other users 
or back to the docteam. Notes are stored in the users ~./ubuntu-doc as ASCII 
text or XML.

<note>
BTW. I see no problem integrating the transformed docs with KDE help Center. 
Since KDE uses static html.
</note>

The ideas mentioned in this sidebar are ideas at application layer. People may 
be inlcined to think that developing them will lock ubuntu into FireFox. 
Please note that this is not so. All documents can be opened in any browser. 
If we so wish we can even create an any browser compatible index page and 
navigation tree.

</sidebar> 

Hope this clears some of the concerns people have.

Thoughts, ideas and concerns are welcome.
-- 
Sean Wheller
Technical Author
sean at inwords.co.za
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/20050304/119cb40b/attachment.pgp>