To Yelp or not to Yelp? That's the Question
sean at inwords.co.za
Fri Mar 4 10:34:12 UTC 2005
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
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:
* External cross-referencing (olink)
* Profiling (conditional text)
* CSS styling
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
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
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.
On https://www.ubuntulinux.org/wiki/DocteamPostHoary I have mentioned "Blue
Sky" that I would like to develop using XUL the UbuntuBar and
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.
BTW. I see no problem integrating the transformed docs with KDE help Center.
Since KDE uses static html.
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
Hope this clears some of the concerns people have.
Thoughts, ideas and concerns are welcome.
sean at inwords.co.za
Registered Linux User #375355
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Size: 189 bytes
Desc: not available
More information about the ubuntu-doc