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

[Matthew East]

Hi Kyle,

On Tue, Sep 15, 2009 at 5:32 PM, Kyle Nitzsche
<kyle.nitzsche at canonical.com> wrote:
> 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.

Thanks for that, it's very useful.

{snip}

> 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.

This is essentially what I had in mind here:
https://lists.ubuntu.com/archives/ubuntu-doc/2009-September/013614.html

Step 1 is the documentation step. As you rightly point out, UNR is so
similar to Ubuntu that I think the easiest way to achieve step 1 is to
simply fork the ubuntu-docs package, write a custom index page
(installing it at ghelp:unr-index or similar), and amend the documents
currently shipped by ubuntu-docs which require amendment. The obvious
amendments would be to the menu entries, and that is pretty easy to do
by modifying the entities in the libs directory. Those documents would
then be installed at a location like
/usr/share/gnome/help/unr-documentname and links between documents
would be amended to point at ghelp:unr-documentname instead of
ghelp:documentname.

What do people think?

Steps 2 and 3 require modifications to yelp - that's where the docteam
doesn't have much expertise. Do you already have code for that? I
agree that it should be a bit easier, and we might want to talk to
upstream about ways in which yelp could be made easier for derivative
distributions to use in this way.

> 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!)

I don't know if you are aware that upstream work is currently going on
with developing a totally new approach to the help system, including a
new markup. What you've said here seems to overlap with that - you
might be interested in contributing to that effort, which is going
full steam ahead at the moment.

-- 
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF