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

[Kyle Nitzsche]

Matthew East wrote:
> 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.
>   
This part may have been figured out already by Loïc.

However, the main points to accomplish this (I think) are:
 * Launch yelp to point to the new ghelp URI (ghelp:unr-index, as you 
suggest) by modifying the yelp.desktop file's Exec line (as previously 
described). This modification can be done through the yelp package's own 
desktop file (or by using a 'divert', or perhaps other ways.)
 * Modify the Help Topics button (and the Go > Help Topics menu item) to 
display UNR Help Center (or live with those widgets taking  the user to 
Ubuntu Help Center, not to UNR Help Center, which seems awkward). I do 
not have a *patch* for this at this moment, however, the code solution 
is probably as simple as the following (in a yelp patch):

In src/yelp-window.c > window_go_home_cb (...) function: change the 
following line:
        yelp_window_load (window, "x-yelp-toc:")
to be:
       yelp_window_load (window, "ghelp:unr-index");

Because both UI widgets return to the home screen through this *one* 
function, modifying it to point to UNR Help Center will probably work.
 
>   
>> 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.
>
>   

I am aware of mallard, which sounds great and raises such interesting 
questions as:
    > Could Ubuntu help be re-factored using mallard (someday) to 
separate UI details (this button does this, that check box does that, 
etc.) from other content in order to enable content reuse in multiple 
'wrapper' docs, for example, to enable making a troubleshooting guide 
that re-uses the single-sourced UI documentation content (currently the 
UI documentation is mixed together with other content).

I am not aware of an upstream effort to move from run-time transform of 
docbook into html (which is a slowish process) towards a help viewer 
that assumes run-time x/html files and uses theme-based dynamic css (via 
the gtk theme change signal I mentioned previously). (Which doesn't mean 
such activities do not exists!) This approach is not inconsistent with 
docbook or mallard (both of which have xslt that converts them to html). 
Docbook and mallard could be the definitive single source. They would be 
transformed to x/html at build time though, not run-time. Which means, 
among other thing, the help viewer could be any browser, such as the 
webkit one I have made, or Firefox...

cheers,
Kyle