Upcoming UI changes for UNR: Customizing Yelp's Home Page

[Kyle Nitzsche]

Hi folks,

I just saw this thread and thought I'd mention a couple points that 
derive from work I've done to modify the Ubuntu help system & content 
for other UNR projects. I am writing this email to share some 
experiences and also to raise the issue of whether and how to make it 
easier to customize yelp's default home page, something that may be 
applicable to Ubuntu UNR and that may become increasingly important as 
Ubuntu takes on a variety of flavors.

As Matthew East noted, the Ubuntu Help Center's home page is hard coded 
into yelp.This home page is an xml file that you can find on your system 
here: /usr/share/yelp/toc.xml, which is processed by a page-specific 
xslt file here: /usr/share/yelp/xslt/toc2html.xsl. The two together form 
the home page content.

When yelp is launched *without* a ghelp argument that points to a 
specific help content package (for example, by clicking the yelp icon or 
by typing 'yelp' into a terminal), the content represented by these two 
files (the xml/xslt "home page") displays, making it the default page 
for yelp. This page has some "welcome" content and numerous links to 
other docbook articles. This content is probably not a perfect fit for 
UNR, both in its text and perhaps in its set of links. Thus the question 
is raised: how to handle the custom help for content for UNR (and for 
other Ubuntu-based images).

One obvious possibility is to modify yelp's hard coded home page 
xml/xslt files such that the content is customized. However, there are a 
couple issues with this:
 * The xml home page is a part of the yelp package currently, so yelp 
would have to be forked. This is not ideal, obviously. However, it would 
probably be a relatively small matter to modify yelp to do the 
following: check some other location for the xml home page, and ,if it 
is found, transform and display it, but if it is not found, then use the 
default xml home page. This would theoretically enable using a 
customized home page *without* modifying the Ubuntu Help Center home 
page, by simply installing the new help xml content into this well-known 
other location.
 * However, yelp expects the home page to use the specific xslt file to 
generate html for display. That xslt file actually inserts some content 
(some links). Thus, in order to modify the all of the home page, you 
have to also understand the xslt and modify that. And, yelp would have 
to know to use this other xslt file too.
 *  The format of these home page xml/xslt files are not easy to 
edit/grok. The xml has all its translations mixed into the single file 
(much like desktop files do), which makes it long and unusual. However, 
this current approach does enable a customized layout for the home page, 
translations, and presentation styling based on the current theme.

Another way to approach this subject (which I have used) is to create a 
new help content package for the home page and take a few steps to 
modify yelp to treat it as the default home page. These yelp 
modifications, or some version of them, could conceivably be implemented 
upstream to facilitate. Here's an outline of the approach:

1) Create the custom help package: Write the new UNR home page help (I 
used xhtml) package, translate it (could use xml2po & LP/Rosetta), and 
install it per usual (with omf files).
2) Launch yelp to display UNR help by default: Modify the yelp desktop 
file Exec line that launches yelp to point at the new help system 
(instead of letting yelp use its default, which is the Ubuntu Help 
Center xml/xslt). Something like: Exec=yelp ghelp:unr (<- 'unr' is the 
help system name used in the omf files).  This value could be obtained 
from gconf to enable a different home page without requiring yelp 
modification. With this, yelp launches to display UNR help content using 
the current locale for translated content selection. Since yelp doesn't 
think of this as the true home page, it does not transform it using the 
default home page xslt file, and it can be in any supported format 
(x/html, docbook, mallard?, etc.)
3) Modify yelp toolbar "Help Topics" button to bring the user back to 
UNR help: "Help Topics" (and related widgets in the toolbar), can be 
made to obtain the value for the home page from a gconf key. If the key 
is not present, display Ubuntu Help Center. Otherwise, display the 
identified content (in this case, the UNR home page).

Naturally, almost all (but not all) of Ubuntu Help Center content is 
relevant to UNR. The new UNR home page could include links to whatever 
parts of the Ubuntu help content is appropriate.

Note: The option of writing help in natively x/html means that current 
theme colors are not used, because no dynamic xslt transform inserts 
them, thus, docbook is preferable in cases where dynamic colors are 
desired. (I have been experimenting with another approach whereby a help 
viewer (a 300-line webkit-based/pygtk prototype) listens to gtk theme 
change notification signals, rewrites the main css page with current 
colors, and reloads the help to display it with those current theme 
colors. As a part of this, I've also cooked up an xslt transform (that 
could be run at help package build time, or (ugh) at help display time) 
that transforms the docbook into html, inserting everything needed to 
display the help very similarly to current gnome help: similar layout, 
next and previous buttons for sections via javascript, a clickable 
two-level table of contents on the right (including About this 
Document). The approach appears to be more dynamic respecting themes 
than yelp's current approach, and faster, since there is no xslt 
transform. Such a help viewer would open the door to writing help in 
xhtml to start, which might be nice because it might encourage 
documentation participation. Some work remains of course (like links in 
the content and searching the help library)... But this is another 
topic, and very preliminary!)

Cheers,
Kyle

Matthew East wrote:
> On Sun, Sep 13, 2009 at 10:44 AM, Dougie Richardson
> <dougierichardson at ubuntu.com> wrote:
>   
>> Hi Matthew,
>>
>> 2009/9/13 Matthew East <mdke at ubuntu.com>:
>>     
>>> On Sat, Sep 12, 2009 at 10:15 AM, Loïc Minier <loic.minier at ubuntu.com> wrote:
>>>       
>>>> On Sat, Sep 12, 2009, Dougie Richardson wrote:
>>>>         
>>>>> While we're on UNR, if anyone on the team is interested then let me
>>>>> know, the Network and Internet section is complete but the rest is
>>>>> just a skeleton trunk.
>>>>>           
>>>>  So you mean you started from Ubuntu docs and just revised the Network
>>>>  and Internet sections, right?
>>>>         
>>> FWIW, I think this is definitely the way that this should be done. UNR
>>> is essentially Ubuntu with a facelift, and the majority of the
>>> material in the ubuntu-docs package is applicable. We've discussed in
>>> the past what the best way to ensure that derivative branches (e.g.
>>> xubuntu-docs) can use the material and changes made to the ubuntu-docs
>>> branches, and this is an excellent opportunity to put that into
>>> practice.
>>>
>>> I'd like to see a UNR branch created from the ubuntu-docs branch,
>>> which makes the relevant changes to account for the differences in
>>> menu structure and the additional software included in UNR. That
>>> branch can then keep up to date with changes made to the ubuntu-docs
>>> branch by merging in such changes as are relevant, and ignoring those
>>> that are not.
>>>
>>> Does anyone see an issue with such an approach?
>>>       
>> Yes, the UNR team are keen that help reflects the interface -
>> desktop-switcher flips between the two. At the moment we discussed
>> that it sets an environment variable used to bring up the relevant
>> help.
>>     
>
> I don't think that is an issue with what I suggested, which was about
> how best to go about creating and maintaining the documents. The issue
> you've raised is a challenge related to how to display the end-product
> to users, which I think is a challenge that will arise in any event.
> The problem is going to be that if UNR intends to use yelp as the help
> viewer, yelp is pre-programmed to show the Ubuntu desktop help when it
> is opened. I'm pretty sure there is a way around that (probably by
> creating a separate custom index page for UNR which yelp opens into)
> but I think it's a separate discussion from how to maintain the actual
> documents.
>
>