Ubuntu Packaging Guide
kyle.nitzsche at canonical.com
Wed Sep 30 14:45:02 UTC 2009
Helen McCall wrote:
> Hello again Augustina,
> I will first give some feedback on the problems I had before TJ
> (IntuitiveNipple) offered to teach me how to package properly.
> All the information and guides I found were contradictory and appeared
> incomplete. I was able to hand-build working .debs of a documentation
> package openshot-docs containing the documentation and gnome help files.
> But I was having difficulty making a standardised source tarball which
> could be automatically built into a .deb on the Launchpad ppa.
> The worst problem I have encountered is how to build a package which
> when installed will cause yelp to index the supplied gnome help files
> properly. All the info on the Gnome Documentation Project site were out
> of date and contradictory because they had changed the method of
> registering the gnome help files and not explained how it should now be
I have done this as follows:
* You have a help system in a source package.
* You have a set of language codes for each translations.
* You need a name for the help: use the package name (for example,
* You need a directory in your source package for the help docs.
* You need a directory in your source package for omf files (these
"register" the help).
* You need to install the help files and the omf files when the package
* You need to update the "library" after the help files and omf files
Now, for each of language-specific version of the help document, you
need to create an 'omf' file. Here's the current sample from gthumb for
<?xml version="1.0" encoding="utf-8"?>
<resource>find the help files in:
<version identifier="2.10.10" date="October 2006"/>
<description>gThumb ist ein Bildbetrachter für die
<format mime="text/xml" dtd="-//OASIS//DTD DocBook XML V4.1.2//EN"/>
<language code="de"/>find the help files in:
<rights type="GNU FDL" license.version="1.1" holder="Paolo Bacchilega"/>
OMF File Names:
the OMF file name needs to include the help name ("gthumb" in this case)
and the language code ("de" for German): gthumb-de.omf
OMF Fields: Fill them all in, but pay special attention to the following:
That field points to the actual help file that contains the German help.
You need to write that URI so that points to the (in this case)
*installed* German help file. (installation covered below)
Get that right!
This field is critical: all omf files for this help application must
have the same value. where do you get the value? You generate it with
the following command:
That produces output like this:
Paste that into the relation seriesid field in *every* omf file:
<relation seriesid="PUT VALUE HERE"/>
Let's hit the packaging bits:
* Create a directory in the source package named omf/ that contains
your omf files
* Create a directory in the source package named help/ that contains
* You need to install these files
* You then need to run this command "scrollkeeper-update" after
installation. This causes the proper registration of omf and help files.
Install the files with the debian/install file, as follows:
(If install does not exist in the debian directory, then create it.)
Now, you need to add the scrollkeeper-update command to debian/postinst:
(If postinst does not exist in the debian directory, then create it.)
That's it. After this package is installed, you should be able to launch
the help in yelp as follows:
You can test installation as follows:
sudo dpkg -i <built debian file name, ending in ".deb">
That's a very quick brain dump - hope this helps.
> The result of all of this is that I had to hack with horrible kludges to
> get the help system to work on OpenShot, and still have not been able to
> add the docs package to the ppa. :-(
> I will give you feedback as TJ teaches me :-)
> On Sat, 2009-09-26 at 17:00 -0700, Augustina Blair wrote:
>> Yes please provide feedback! The challenge with the documentation I've
>> had is consistency between what the teams are teaching versus what the
>> guide says. I based my edit on what the guide originally said and
>> tried to make sure whatever tools and processes were outlined there
>> were as accurate and up to date as possible. However, I suspect
>> different methods and processes may be being taught by the teams. Any
>> feedback you and anyone else can offer is totally welcome.
More information about the ubuntu-doc