Re: Rarian and Yelp

[Don Scorgie <Don Scorgie org>]

Hi,

(CCing gnome-doc-devel.  Please take any further responses there)

On Thu, 2007-08-02 at 17:59 -0400, Joe Marcus Clarke wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> Jan de Groot wrote:
> > On Thu, 2007-08-02 at 16:45 -0400, Joe Marcus Clarke wrote:
> >> -----BEGIN PGP SIGNED MESSAGE-----
> >> Hash: SHA1
> >>
> >> 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)

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

> >>
> >> My question is, is rarian supposed to be working now?  Should Yelp be
> >> finding the help documents?  Right now, Yelp can only successfully find
> >> GNU info and man pages.  Thanks.

Yes, Rarian is supposed to be working right now.

> >
> > I submitted two crasher patches for librarian yesterday, rarian seems to
> > work quite fine on linux now. Three side notes though:
> > - beagle search in yelp no longer builds as of 2.19.1

Yes, this is known.  It seems my system doesn't like me enough to work
with Beagle, so I can't really test :(

> > - simple search crashes with an invalid pointer somewhere in librarian

Does it?  That's new.  Does it crash with every search?  Could you
possibly file a bug about this and provide a stack trace?  This seems
especially suspicious as the search stuff is generated using exactly the
same codepaths as the TOC.  Therefore, its likely to be something yelp
is overwriting in memory.

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

As for the other point (about Rarian being default): If you check
through the archives, I specifically stated that I wanted to get it in
before feature freeze (because the new yelp depends on it).  I received
no replies (except for a couple of "Yay!"'s).  I was then asked on IRC
to put Rarian in instead of scrollkeeper due to scrollkeeper being a)
dead and b) broken at present.  (a) doesn't look like it'll be fixed any
time soon, which means neither will (b).

> 
> 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'm still not sure how this works on Linux as I don't see the
> /usr/local/share/help/LOCALE directories on a Linux box I have.  Does
> this directory exist for you?  If it does, what is its contents?  Who
> creates it?  Is there any way to further debug what rarian is doing?

As mentioned, this is a residual and not so important.  Alas, the debug
infrastructure in Rarian is pretty thin on the ground (something I had
planned on fixing relatively soon).  You could try running the
rarian-example program and dumping it's output to a file (it goes
through all info, man and docs and dumps various stuff to stdout).  If
the docs are appearing in there, then it's a yelp problem.  If they're
not, Rarian.  Other than that, an strace would be quite nice.  Also, try
setting XDG_DATA_DIRS to something (else).  Any stderr output from
running yelp / rarian-example would also be immensely useful.

> 
> Note: I've built rarian using the defaults so both ENABLE_OMF_READ and
> ENABLE_INSTALL Are defined.

Which is the way it should currently be built.

Don