Ubuntu Packaging Guide

[Kyle Nitzsche]

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
> done.
>   
I have done this as follows:
You Have:
 * You have a help system in a source package.
 * You have a set of language codes for each translations.

You Need:
 * You need a name for the help: use the package name (for example, 
"gthumb").
 * 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 
is installed.
 * You need to update the "library" after the help files and omf files 
are installed.

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 
German: /usr/share/omf/gthumb/gthumb-de.omf

<?xml version="1.0" encoding="utf-8"?>
<omf>
  <resource>find the help files in:
    <creator>(Paolo Bacchilega)</creator>
    <creator>(Alexander Kirillov)</creator>
    <maintainer>(Paolo Bacchilega)</maintainer>
    <title>gThumb-Handbuch V2.11.0</title>
    <date>October 2006</date>
    <version identifier="2.10.10" date="October 2006"/>
    <subject category="GNOME|Applications|Graphics"/>
    <description>gThumb ist ein Bildbetrachter für die 
GNOME-Umgebung</description>
    <type>
      user's guide
    </type>
    <format mime="text/xml" dtd="-//OASIS//DTD DocBook XML V4.1.2//EN"/>
    <identifier url="file:///usr/share/gnome/help/gthumb/de/gthumb.xml"/>
    <language code="de"/>find the help files in:
    <relation seriesid="4d60fcae-643d-11d6-847d-be863f3eea7a"/>
    <rights type="GNU FDL" license.version="1.1" holder="Paolo Bacchilega"/>
  </resource>
</omf>

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:

<identifier url="file:///usr/share/gnome/help/gthumb/de/gthumb.xml"/>
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)

<language code="de"/>
Get that right!

<relation seriesid="4d60fcae-643d-11d6-847d-be863f3eea7a"/>
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:
scrollkeeper-gen-seriesid

That produces output like this:
05692b25-f92c-f8cf-13f3-a91efe586dcc40

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 
your docs
 * 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:
"
html/* /usr/share/gnome/help/<help-name>/
omf/* /usr/share/omf/<help-name>/
"

(If install does not exist in the debian directory, then create it.)

Now, you need to add the scrollkeeper-update command to debian/postinst:
"
#! /bin/sh

scrollkeeper-update
"

(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:
yelp ghelp:<help-name>

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.

Cheers,
Kyle


> 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 :-)
>
> Helen
>
>
> 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.
>>
>> Augustina
>>     
>
>
>
>