Re: Rarian and Yelp

[Don Scorgie <Don Scorgie org>]

Hi,

On Fri, 2007-08-03 at 13:39 -0400, Joe Marcus Clarke wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> Don Scorgie wrote:
> >>>> If there's a better list for Rarian, please let me know.  I just
> >>>> finished porting rarian-0.5.6 to FreeBSD (lot of Linuxisms), and I'm
> >>>> trying to confirm that it's working with Yelp 2.19.1.  However, I can no
> >>>> longer see any of my help documents in Yelp.  When I trace yelp, it
> >>>> seems to be looking for directories that do not exist (e.g.
> >>>> /usr/local/share/help/LOCALE/C).  I don't even see those directories on
> >>>> Linux.  Yelp does find all of the OMF files, but it doesn't want to load
> >>>> the related help .xml files.
> > 
> > /usr/local/share/help/LOCALE/C is one of the places searched by Rarian.
> > The general way it's done is:
> > if XDG_DATA_DIRS is set:
> > for (x = each dir) in XDG_DATA_DIRS:
> > 	process `ls x/help/LOCALE/<current lang value>/*`
> > 	process `ls x/help/* (excluding LOCALE)`
> > if XDG_DATA_DIRS is not set:
> > 	use default of /usr/share:/usr/local/share and process as above.
> > 
> > So all you're seeing above is a residue of that.
> > 
> > (FWIW, the reason the LOCALE stuff is checked is for distros wanting to
> > distribute language packs)
> 
> Yes, I see that now.  I sent out another email to g-d-d-l last night,
> but it was moderated.  I'll summarize things for you here.
> 
> > 
> >>>> To be clear, OMF files can be found under /usr/local/share/omf and GNOME
> >>>> help files under /usr/local/share/gnome/help/<app>/<locale>.  This
> >>>> appears to be the same as Linux.
> > 
> > Indeed.
> 
> Yes, this appears to be working fine.  What happens is rarian goes
> through each of the omf subdirectories, and adds an entry with a ghelp
> name of the subdirectory name (dp->d_name).  So, if my omf subdirectory
> contains:
> 
> eog     gnome-terminal
> 
> I get two rarian doc entries with ghelp names of "eog" and "gnome-termial".

So, rarian-example prints out the entries properly?  Or are you watching
the list get built in Rarian itself? [1]

> 
> 
> >>> - yelp doesn't know how to generate the help index anymore, viewing
> >>> normal help files is fine though.
> >>> IMHO these things should be working before rarian is used as default
> >>> documentation system in GNOME. We're still in the early development
> >>> process now, so there's time to fix these things.
> >>> I'll file some bugs with more information in the weekend so people can
> >>> work on it.
> > 
> > The only defence here is "It works on my machine".  I have noticed some
> > other problems at various other points though.  Right now, I'm trying to
> > rebuild my development environment (which is fun in itself).  Once
> > that's done ...
> 
> When I launch yelp by itself, I get a list of documentation categories,
> but whenever I click on one of them, it says, "No documents or
> subcategories found."  This used to work with SK.  What should be
> happening here such that documents will get listed?

Yes, this is the default behaviour for yelp when it doesn't find any
documents.

> 
> >> I can't do anything with yelp+rarian.  Trying to view help files from
> >> standalone Yelp yields "No documents or subcategories found."  Trying to
> >> start Yelp from an app like gnome-terminal or eog throws a "URI is
> >> invalid" error.
> > 
> > Again, that's something I can't reproduce.  Could you please file a bug?
> 
> I've done some more research here, and I found that when I launch yelp
> via another app (e.g. eog) it is passed a ghelp URI in the format (via
> libgnome):
> 
> ghelp:///usr/local/share/gnome/help/eog/C/eog.xml
> 
> Yelp breaks this down to "///usr/local/share/gnome/help/eog/C/eog.xml"
> and passes that to rarian.  Rarian fails to find any documents since all
> of its ghelp names are just the appid.
> 
> Since our libgnome is fairly stock, I'm really not sure how this mapping
> works successfully on Linux.

Okay, that's a failure of the new resolver.  It should check the ghelp
uri to see if it's a full path before invoking rarian.  I'll fix that
soon.

Note: The resolver stuff had to be rewritten due to the move to Rarian.
This removed the libgnome stuff from there.  I thought I'd caught all
the cases, but apparently not :(

> 
> So, I tried launching:
> 
> yelp ghelp:eog
> 
> This "works," but all I see is the section headers from the doc (i.e. no
> contents), and I see the following on the console:
> 
> xmlXPathCompOpEval: function has-same-node not found
> XPath error : Unregistered function
> xmlXPathCompiledEval: 3 objects left on the stack.
> runtime error: file
> /usr/local/share/xml/gnome/xslt/docbook/html/db2html-division.xsl line
> 317 element apply-templates
> Failed to evaluate the 'select' expression.
> xmlXPathCompOpEval: function has-same-node not found
> XPath error : Unregistered function
> xmlXPathCompiledEval: 3 objects left on the stack.
> runtime error: file
> /usr/local/share/xml/gnome/xslt/docbook/html/db2html-division.xsl line
> 317 element apply-templates
> Failed to evaluate the 'select' expression.
> 
> It appears the new g-d-u uses the EXSLT sets extension, but I don't see
> where it actually loads the stylesheet with the function definitions.  I
> looked at the GARNOME distribution, but it doesn't appear to be
> including the EXSLT libraries either.

Yes, I blame shaunm for that one ;)  Changes in g-d-u didn't quite
propagate into yelp successfully.  This one is fixed in SVN Head now.


Thanks
Don

[1] I just had an idea of why yelp isn't finding the documents in categories.  
I think it's the ridiculousness of scrollkeeper and it's |'s that it uses to 
separate categories and subcategories.  Once I have a working system, I'll 
be able to check this.  I suspect the reason I haven't been able to reproduce 
is that I've already converted all the docs to .document files.