Re: New recruit, help needed in choosing project

[Brent Smith <gnome nextreality net>]

alessandro ferrucci wrote:
> I have one question.
>
> On this box I'm running Ubuntu with Gnome 2.12.1, but I run Gentoo on
> another box.  How do I know that 1 version of Yelp I would look at would
> be the same that you guys would have?
>
>
> What I mean is this...do Ubuntu and Gentoo users look at the same
> documentation all the time?  I doubt that's the case.
>
> Could you tell me how I can acquire the ldatest Yelp sources so I could
> look at the documentation on those?

Ok, it seems like a lot of people have been asking this, so I'm going
to write some technical details for people to refer to for the time
being.  Shaun/Don, please correct me if I am wrong....

Here it goes.

Documentation for most applications are included in the cvs modules
for that application.  For example, if you check out the latest cvs
sources for evince from the GNOME CVS server, the documentation will
be in evince/help/C/evince.xml.

For things like gnome-applets where there are many programs in the
cvs modules, you might have to search around for the help files.

So the easy way to see docs for a particular application, is to
get the latest sources from CVS, and then use yelp to browse the
docbook file in the help directory, by just doing a /usr/bin/yelp
<docbook file>.xml

If you want to have the Table of Contents in yelp work, and point to
the most recent docs for 2.14, then you need to read the rest of this email.

So when you actually get the sources for say, evince, from the GNOME
CVS servers and then compile, make and make install, the documentation
will be installed to $prefix/share/gnome/help/<appname>/C/<docname>.xml

Of course for the documentation to actually show up in yelp,
the scrollkeeper databases need to updated.. When you issue a "make
install", a command gets issued to update scrollkeeper databases that
looks similar to the following:

scrollkeeper-update -p $prefix/var/lib/scrollkeeper -o 
$prefix/share/omf/evince

Since I am using jhbuild (http://www.freedesktop.org/Software/jhbuild
and http://live.gnome.org/JhbuildOnUbuntu) to get the latest version
of GNOME, it installs a second copy of scrollkeeper for me, so that
I have a second documenation database for files that come with GNOME
located at /opt/gnome2/var/lib/scrollkeeper - this will keep the
development docs separate from your main system's docs.

Yelp gets the content list from scrollkeeper by running the command
"scrollkeeper-get-content-list" and then reading the corresponding
xml output file that it puts in /tmp/scrollkeeper-<username>/contents.1
Depending on your $PATH variable in yelp's environment, either the
system wide "scrollkeeper-get-content-list" or the binary installed
with jhbuild at $prefix/bin/ will get run.

Ideally when testing the latest docs you want the binary in $prefix/bin/ 
to get run, since this one will use the database at
$prefix/var/lib/scrollkeeper which has all the documentation installed
from jhbuild.  The easy way to do this, is to issue a "jhbuild shell"
before running yelp.  This will put "$prefix/bin/" in your $PATH
environment variable so the $prefix/bin/scrollkeeper-get-content-list
will get run before /usr/bin/scrollkeeper-get-content-list

If you manage to get all that correct, then the table of contents in
Yelp will point to the most recent docs for 2.14.

Confusing?  That's because it is.  Ask questions and I will try to
help you out if you have problems.


Hope that helps.


--
Brent Smith <gnome nextreality net>
IRC: smitten