Advice needed - moving GNOME help files into langpacks

[Shaun McCance]

On Sun, 2009-08-30 at 10:44 +0200, Martin Pitt wrote:
> Hello Matthew, hello Shaun,
> 
> Matthew East [2009-08-27 23:19 +0100]:
> > I've had a chat this evening with Shaun Mccance, the Gnome yelp
> > maintainer. It seems that yelp gets its paths from rarian, and rarian
> > gets its paths from the content of the omf files. So we can patch the
> > omf files (seems to me to be a big job), patch rarian, or use the
> > symlink idea of Loïc.
> > 
> > I've pasted the conversation here and hope that it helps! I'm afraid I
> > was asking rather uninformed questions, as I don't have a good
> > understanding either of how yelp works, or of how Ubuntu packaging
> > works. But hopefully it takes things forward a little.
> > 
> >  http://pastebin.ubuntu.com/260590/
> 
> Thanks for this conversation! To clarify why we need this dance in the
> first place:
> 
> <mdke_> Martin can't put these files in /usr/share/gnome/help because that will break upgrades
> <shaunm> because it seemed straightforward enough to me to just drop the extra files in the right place
> 
> One assumption from dpkg (and most probably rpm as well) is that a
> particular file can only be shipped in one package (at a time). Thus
> if you have a file /usr/share/gnome/help/foo/foo.xml, which is
> currently shipped by foo, and then you install a language pack which
> also ships that file, the package installation will fail. We can
> enforce that foo is upgraded before the language pack installation, or
> that the langpack will overwrite files from foo, but that would
> require said list of 50ish "Replaces:" declarations.
> 
> This isn't just a transitional problem either: people can install
> third-party .debs, or locally built packages which include the help
> files at the original place, and they would again be uninstallable due
> to file conflicts.

OK.  I'm not a packaging expert, so I'll just have to trust
you on this one.  But I don't see how splitting a package
into subpackages is any different than what gets done now
with -dev packages.

> Now, patching the omf files isn't much work at all, it can happen
> automatically during package build in pkgstriptranslations: while
> removing the gnome help files, it could also apply some seddery to the
> omf files to change /help/ to /help-langpacks/. However, we'd still
> have the same file conflict problem with the omf files themselves.
> 
> <shaunm> now, that won't work for mallard documents
> <shaunm> which basically means empathy
> 
> Shaun, what do you mean here? The current empathy in Karmic (2.27.5)
> seems to use the standard gnome help/omf system.

I'm not running Karmic, so I can't look at what's going on
there.  But I know the source package doesn't provide an OMF
file.  (There's a vestigal omf.in file lingering in git, but
nothing happens with it when building.)

> So it seems to me that the langpacks should ship the help files in
> /usr/share/gnome/help-langpack/ and the omf files in
> /usr/share/omf-langpack/, with the paths mangled accordingly 
> (*/help/* → */help-langpack/*). Then a two-line rarian patch would fall
> back to /usr/share/omf-langpack/ if the requested file does not exist
> in /usr/share/omf/. With that order, locally installed files always
> get preference, which is what we want.

So let me clarify how things will work for all documents
in the future.  Yelp will completely eschew OMF files and
any other metadata file format.  It will look for help
in standard subdirectories of $XDG_DATA_DIRS, following
the freedesktop.org base directory specification.

Obviously, we will look in $XDG_DATA_DIRS/gnome/help,
because that's where we've been putting stuff for ages,
and breaking compatibility there would be absurd.  But
I'd like to talk to some folks from other desktops about
using $XDG_DATA_DIRS/help, and having a common layout.

So, with your proposed solution, in Yelp 3 you would need
to patch Yelp to also look for help files there.  If you
were to use a directory structure like

  /usr/share/langpack/gnome/help/empathy/de/

Then you'd just need to ensure that /usr/share/langpack
is in XDG_DATA_DIRS (or modify Yelp to auto-insert it,
which would be a much smaller patch).

Then again, if we transition from gnome/help to help,
having things in a new location would get rid of the
file conflict problems that cause transition issues
for langpacks.  But I don't really understand the
other issue you mentioned.

--
Shaun