<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<book id="debian-gnome-policy" lang="en">
  <bookinfo>
    <title>Debian GNOME Packaging Policy</title>
    <author>
      <firstname>Ross</firstname><surname>Burton</surname>
      <email>ross@debian.org</email>
    </author>
    <othercredit>
      <firstname>Mikael</firstname><surname>Hallendal</surname>
      <contrib>Advised on correct gtk-doc usage</contrib>
      <email>micke@codefactory.se</email>
    </othercredit>
    <othercredit>
      <firstname>Christian</firstname><surname>Marillat</surname>
      <contrib>Documentation clarifications</contrib>
    </othercredit>
    <othercredit>
      <firstname>Bastien</firstname><surname>Nocera</surname>
    </othercredit>
    <othercredit>
      <firstname>Sebastian</firstname><surname>Rittau</surname>
    </othercredit>
    <othercredit>
      <firstname>Gustavo</firstname> <othername>Noronha</othername> <surname>Silva</surname>
    </othercredit>
    <othercredit>
      <firstname>Colin</firstname><surname>Walters</surname>
      <contrib>GNOME-VFS section</contrib>
    </othercredit>
    <abstract>
      <simpara>
        This document describes the policy requirements for the packaging of GNOME programs in
        Debian GNU/Linux.
      </simpara>
    </abstract>
    <revhistory>
      <revision>
        <revnumber>20050123-1</revnumber> <date>2005-01-23</date>
        <revremark>Remove section on Nautilus Views, add dh_gconf, and clarify
        gtk-doc paths.</revremark>
      </revision>
      <revision>
        <revnumber>20040816-1</revnumber>
        <date>2004-08-16</date>
        <revremark>Quick update to cover changes up to GNOME 2.6.</revremark>
      </revision>
      <revision>
        <revnumber>20030502-1</revnumber>
        <date>2003-05-03</date>
        <revremark>Clarified gtk-doc layout, added a section on the
        'gnome' section, and clarified the section for
        engines.</revremark>
      </revision>
      <revision>
        <revnumber>20030218-1</revnumber>
        <date>2003-02-18</date>
        <revremark>Rewrote section on API Documentation, after talking
        to gtk-doc developers.</revremark>
      </revision>
      <revision>
        <revnumber>20030119-1</revnumber>
        <date>2003-01-19</date>
        <revremark>Added a section on GnomeVFS, and rewrote the API
        documentation section.</revremark>
      </revision>
      <revision>
        <revnumber>20030114-1</revnumber>
        <date>2003-01-14</date>
        <revremark>Reformatted in DocBook.</revremark>
      </revision>
    </revhistory>
    <copyright>
      <year>2003-4</year>
      <holder>Ross Burton</holder>
    </copyright>
    <legalnotice>
      <para>
        <remark>TODO: insert Open Content License or similar here</remark>
      </para>
    </legalnotice>
  </bookinfo>

  <toc>
    <title>Table of Contents</title>
  </toc>

  <chapter>
    <title>Introduction</title>
    <para>
      This document describes the policy requirements for the packaging of
      <application>GNOME</application> programs.
    </para>
    <para>
      This document is currently a draft, as it evolves it should become more organised.
    </para>
    <para>
      This document only mentions packaging guidelines appropriate for GNOME packages. The Debian
      Policy still applies to all packages.
    </para>
  </chapter>

  <chapter>
    <title>General Packaging Guidelines</title>
    <sect1>
      <title>Package Naming</title>
      <para>
        Programs that the end user can actually run (such as <application>File Roller</application>)
        should be packaged as the name of the program. Do not suffix the package with a
        <literal>2</literal> to represent the GNOME 2 package; if upstream is maintaining both GNOME
        1 and GNOME 2 releases, then name the GNOME 1 package <literal>foo-gnome1</literal> instead.
      </para>
    </sect1>
    <sect1>
      <title>Package Section</title>
      <para>
        GNOME applications (not libraries) should be in the <literal>gnome</literal> section unless
        they are used by multiple environments (such as KDE).
      </para>
    </sect1>
    <sect1>
      <title>Documentation</title>
      <para>
        If any binaries accept the standard GTK+ or GNOME command-line options, the manual pages
        should refer to the GTK+ and/or GNOME common command-line option manual pages,
        <filename>gtk-options.7</filename> and <filename>gnome-options.7</filename> (in the packages
        <filename>libgtk2.0-bin</filename> and <filename>libgnome2-common</filename> respectively).
      </para>

      <para>
        If the upstream tarball contains API documentation for a library which is generated using
        <application>gtk-doc</application> or <application>doxygen</application>, it should not be
        regenerated during the Debian package build process. In the case of gtk-doc, this means
        passing the <literal>--disable-gtk-doc</literal> flag to <command>configure</command>. An
        exception to this rule is if the upstream tarball contains incomplete or old API
        documentation, or if it is not installed when <literal>--disable-gtk-doc</literal> is used.
      </para>
      <para>
        API documentation should be included in the <literal>-dev</literal> package if relatively
        small, otherwise in a separate <literal>-doc</literal> package.  API docs should be
        available in <filename>/usr/share/doc/[package]/</filename>, normally in a directory named
        after the type of file (such as <filename>html/</filename>). This is so that multiple
        formats can be packaged (PDF for example).
      </para>
      <para>
        However, if <application>gtk-doc</application> is used to generate the API documentation,
        the documentation should be installed in the default location,
        <filename>/usr/share/gtk-doc/html/[package]</filename>, with a symbolic link in
        <filename>/usr/share/doc/[package]/html/</filename>.
        <footnote>
          <para>
            Alternatively, the documentation can be installed into
            <filename>/usr/share/doc/[package]/</filename> and a symbolic link to it created in
            <filename>/usr/share/gtk-doc/html/</filename>.
          </para>
        </footnote> The <filename>[package].devhelp</filename> file must also be installed.  This
        ensures that gtk-doc and other tools which use the gtk-doc metadata (such as
        <application>DevHelp</application>) can find the documentation.
      </para>
      <para>
        <remark>TODO: There is the issue of rebuilding documentation
          if upstream didn't generate it with cross-references. Ideally all types will be
          cross-referenced, down to <type>gint</type>.</remark>
      </para>
    </sect1>
    <sect1>
      <title>Use of GConf</title>
      <para>
        Many GNOME applications use <application>GConf</application> for preferences, and most
        applications provide schemas for the keys they set. These schemas must be handled specially
        in the package build process.  There are two issues: the location of schema files on disk,
        and registering schemas at install time.
      </para>
      <para>
        GConf schema files are by default installed into <filename>/etc/gconf/schemas</filename>,
        but as they are not configuration files we move them to
        <filename>/usr/share/gconf/schemas/</filename>.  This can be done with the
        <filename>configure</filename> flag
        <literal>--with-gconf-schema-file-dir=/usr/share/gconf/schemas</literal>.  Alternatively
        <filename>dh_gconf</filename> will move any schemas found in
        <filename>/etc/gconf/schemas</filename> if it is called in
        <filename>debian/rules</filename>.
      </para>
      <para>
        If <filename>debian/rules</filename> is using CDBS, simply include
        <filename>/usr/share/cdbs/1/class/gnome.mk</filename>.  This will call
        <filename>dh_gconf</filename> which will set the relevant environment variables and create
        the maintainer scripts.  Note that <filename>dh_gconf</filename> will move the schema files
        from <filename>/etc/gconf/schemas</filename> to
        <filename>/usr/share/gconf/schemas</filename>, as GConf schemas are not configuration files.
      </para>
      <para>
        If the package doesn't use CDBS however, before running <command>make
          install</command>, the variable
        <varname>GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL</varname> must be set to
        1. This will ensure that the schemas are not installed on your machine
        in the package build tree.  Then in the relevant <literal>binary-</literal> target call
        <filename>dh_gconf</filename> to create the maintainer scripts.
      </para>
      <para>
        If you use <filename>dh_gconf</filename> via either CDBS or manually, you must depend on
        <filename>debhelper</filename> >= 4.1.87, although <filename>debhelper</filename> >= 4.2.16
        is recomended for the move of schemas to <filename>/usr/share/gconf/schemas</filename>.
      </para>
    </sect1>
    <sect1>
      <title>Use of Scrollkeeper</title>
      <para>
        If user documentation exists, and an OMF file is provided, the package must depend on
        <varname>scrollkeeper (>=
          0.3.8)</varname>, and update the ScrollKeeper database in the
        maintainer scripts.  Again, CDBS with the <literal>gnome</literal> class does this
        automatically, but otherwise call <filename>dh_scrollkeeper</filename> in the relevant
        <literal>binary-</literal> target.
      </para>
      <para>
        If you use <filename>dh_scrollkeeper</filename>, you must depend on
        <filename>debhelper</filename> 4.2.1 or higher.
      </para>
    </sect1>
  </chapter>

  <chapter>
    <title>Specific Packaging Guidelines</title>
    <sect1>
      <title>Panel Applets</title>
      <para>
        <remark>TODO: Panel applets -- "gnome-applet-foo" or "foo-applet" or
        "gnome-foo-applet"?</remark>
      </para>
      <para>
        Panel applets must be installed into <filename>/usr/lib/gnome-panel</filename> as they are
        never
          directly executabled by the user. This applies to both
        shared library and executable panel applets. <remark>TODO: Or should
          they go into <filename>/usr/share/gnome-applets</filename>?</remark>
      </para>
    </sect1>
    <sect1>
      <title>Themes and Theme Engines</title>
      <para>
        GTK+ 1.x engines must be named <filename>gtk-engines-[name]</filename>, and GTK+ 2.x engines
        must named <filename>gtk2-engines-[name]</filename>.  All engines should be in the
        <literal>gnome</literal> section.
      </para>
      <para>
        Unless there are special requirements, GTK+ themes should not specify a font. This is
        because a font specified in a theme can not be changed by the user trivially.
      </para>
      <para>
        <remark>TODO: How do we package pure gtkrc themes which use engines (such as GitM, which
        uses mist)?  Should engine packages include a set of decent themes for this engine, even if
        they were not written by the same author?</remark>
      </para>
      <para>
        <remark>TODO: Icon themes?  Metacity themes?</remark>
      </para>
    </sect1>
    <sect1>
      <title>GnomeVFS Methods</title>
      <para>
        It is recommended that any GnomeVFS methods included with a program should be packaged
        separately, with just the necessary shared library and the GnomeVFS module configuration
        file.  If a package provides just a single method, it should be named like
        <filename>gnomevfs-method-[prefix]</filename>, where <varname>[prefix]</varname> is the URI
        prefix that the method provides.
      </para>
      <para>
        If a single upstream source package provides multiple methods, it may either be packaged as
        <filename>gnomevfs-methods-[name]</filename>, where <varname>[name]</varname> is the name of
        the upstream source, or it may be split into multiple individual packages as above.
      </para>
    </sect1>
  </chapter>

  <chapter>
    <title>License</title>
    <para><remark>TODO: insert something sane.</remark></para>
  </chapter>
</book>