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

[Kyle Nitzsche]

Shaun McCance wrote:
> On Wed, 2009-09-16 at 11:44 -0400, Kyle Nitzsche wrote:
>   
>> Just pointing out that coupling the content with the (yelp) viewer 
>> imposes real restrictions. For example, how can karmic UNR fork yelp to 
>> point to UNR Help Center when that same yelp is used in karmic to point 
>> (hard coded) to Ubuntu Help Center (unless changes are made to read the 
>> target from gconf or somewhere).
>>     
>
> So it could be that the differences in what help you want displayed
> can be handled by installing (or not) optional sets of pages that
> plug into the desktop help.  I don't know the scope, so I can't
> really say for sure.
>   
The main home page might be customizable without modifying the yelp 
package. For example, the top level header for UNR should probably read 
"UNR Help Center" instead of Ubuntu Help Center". Currently that home 
page content comes from two file *owned* by the yelp package: toc.xml 
file and toc2html.xslt file. Note that toc2html.xslt actually provides 
some of the content (not just styling/formatting) (for example the links 
under the "Common Questions" header). Thus, currently, to modify the 
home page help content, you have to modify the help viewer, yelp.

> But otherwise, you're asking for Yelp to display a different document
> by default when launched without a URI.  That really is not a big deal.
> If you guys want that to be in a GConf key or something so you can make
> the customization without patching code, we can do that.  I'm here to
> help.  You just have to let me know.
>
>   
Shaun, that would be totally awesome! It would enable many good things, 
such as:
 * the doc team can create a unr docs package that also includes the 
gconf key that tells yelp to use it. Thus, the help system is switched 
to point at unr help without having to modify yelp itself.
 * the current toc page (the home page) in ubuntu docs (the one that 
shows "Ubuntu Help Center" at the top and that consists of toc.xml & 
toc2html.xslt) can be moved from the yelp package into the ubuntu docs 
package, thus making changes to them much easier (the same change would 
naturally be done to unr docs). Of course ubuntu docs would also have to 
set the gconf key saying where to point for the homepage. I guess this 
would also make the diff between ubuntu yelp and gnome yelp smaller too.

A couple follow on points:
 * the Help Topics button and the Go > Help Topics menu item also take 
the user to the home page (through yelp-window.c > window_go_home_cb 
(...) function). these would also need to pick up the gconf home page.
 * should there also be a key to point to the xslt that transforms the 
page (if it is xml)?  As noted above, currently some of the topic is 
provided by the toc2html.xslt that is provided by the yelp package, thus 
if that xslt were used, some of the content (and all of the layout) of 
the toc would not be separated from the yelp package.
 * Could the pointed to home page be any supported format? (docbook, 
mallard, x/html)?

>> Given the increasing numbers of distros/images/flavors that consume help 
>> content, I think it makes sense to consider a model like this:
>>  * single-sourced content that supports inclusion methods (like xinclude 
>> and Mallard)
>>     
>
> So Mallard is designed with the idea that you can plug pages into
> documents.  This is not quite the same thing as pulling pages out
> of documents to plug them in elsewhere.  So this isn't something
> you're going to get for free just yet.
>
>   
Not quite sure of the distinction (because I am new to Mallard...).

I think, somewhat abstractly, of a sea of atomized content chunks that 
are pulled into various wrapper documents as needed. This might enable 
different entry points into a doc system to meet different user needs 
and experiences, in which the doc system re-uses content for all the 
good reasons :-), Imagine, for example, that  a software dialog has a  
"?" mark on it that when clicked launches the help viewer to display 
just the doc that describes the widgets on the page. (The "UI reference 
doc" for it). Now imaging a more standard user manual type docs that 
explain major tasks - it would not need to doc the UI anymore but could 
include links to that single source content. Then image a trouble 
shooting guide that would be able to leverage the same UI reference 
content yet again. This may sound like the talk of a raving dreamer ;) 
But, I raise these points to highlight aspects of the current framework 
that make such implementation difficult to achieve as points for 
consideration by the community.
> That said, the modular document structure of Mallard makes remixing
> far more feasible than with a book-structured format like DocBook.
> We can make this happen.  But what I need is for the writers who
> want this stuff to talk to me.
>
> (I've been wanting to put a site up on projectmallard.org where
> people can host their own extensions, so we can all experiment
> and see what everybody else is experimenting on.  If any web
> developer types want to help, that would be awesome.)
>
>   
>>  * converted into multiple delivery formats (x/html, pdf, etc.) (at 
>> build time... ?)
>>     
>
> To what end?  I'm not trying to say there's no reason to convert
> to other formats, but you should have a user goal in mind when
> you decide how to go about doing it.  Users are, by and large,
> far less interested in documentation than you might think.
>
>   
I tend to think (read: 'opinion' ;) that content viewed on the system 
should be html files whose styling is controlled by css rather than 
docbook that is transformed in real time. This is very flexible and 
well-known and opens the door to a wide ocean of help viewers, while is 
also probably faster (no run-time xslt). As I mentioned previously in 
this chain, I wrote a webkit based viewer and xslt transforms (that run 
at doc build time) that convert docbook articles into html (that part is 
nwalsh) with css classes and javascript inserted (that's what my 
transforms do) as needed. The webkit help viewer listens to gtk theme 
change signals and simply rewrites the css file with new colors and 
reloads the page to pick up the new theme colors. The result provides a 
look and feel that is very similar to gnome user manuals now: forward 
and back buttons, autogenerated  toc content on right as clickable links 
(two levels deep), About this Doc info, etc. It is preliminary but is 
meant to be a proof of concept that html&css based files can provided 
the same user experience from docbook source, without run-time xslt 
transforms and with dynamic responsiveness to the current theme. Again, 
this is not meant to be a proposal, but to share some work I've done 
with the community.  (Consider that  if the  help viewer is truly an 
html browser, one could include links to online content  (like more 
trouble shooting info, how to participate, translate, etc.,  *in the 
same  viewer*.)

I just put this page up to summarize this, provide screenshots, links to 
the viewer code (xslt code to come if interested), and etc.: 
http://people.canonical.com/~knitzsche/help_viewer/help-viewer.html

>>  * displayed by arbitrary viewers
>>
>> I think it makes sense to start considering completely uncoupling 
>> content from the viewer. Otherwise it is too monolithic.
>>     
>
> DocBook and Mallard documentation is in no way tied to Yelp.
> They are both open formats, free to be implemented by anybody.
> You could write your own DocBook or Mallard viewer.  Heck, I'd
> even help you do it.  I've talked to Jim about how I can help
> XFCE make their own help viewer.  We're all friends in freedom.
>
> --
> Shaun
>
>
>   

The work you folks have done collectively is truly awesome. I say that 
whole heartedly and without reservation!

cheers,
Kyle