<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>

<book id="index">
  <bookinfo>
    <title>Integrating existing software with GNOME</title>
    <subtitle>Guide for Independent Software Vendors</subtitle>
    <abstract role="description"><para>Guide for Independent Software Vendors</para></abstract>

    <authorgroup>
      <author>
	<firstname>Rosanna</firstname>
	<surname>Yuen</surname>
	<affiliation>
	  <address>
	    <email>zana@gnome.org</email>
	  </address>
	</affiliation>
      </author>
      <author role="maintainer">
	<firstname>Federico</firstname>
	<surname>Mena-Quintero</surname>
	<affiliation>
	  <address>
	    <email>federico@gnu.org</email>
	  </address>
	</affiliation>
      </author>
      <author>
	<firstname>Mike</firstname>
	<surname>Hearn</surname>
	<affiliation>
	  <address>
	    <email>mike@navi.cx</email>
	  </address>
	</affiliation>
      </author>
    </authorgroup>

    <copyright>
      <year>2005, 2006</year>
      <holder>Rosanna Yuen, Federico Mena-Quintero, Mike Hearn</holder>
    </copyright>

    <revhistory>
      <revision>
	<revnumber>0.6</revnumber>
	<date>2006/September/19</date>
	<revdescription>
	  <para>
	    Extended the icon guidelines.
	  </para>
	</revdescription>
      </revision>
 <revision>
	<revnumber>0.5</revnumber>
	<date>2006/September/18</date>
	<revdescription>
	  <para>
	    Integrated the content of Rosanna Yuen's first article on
	    freedesktop.org standards.
	  </para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>0.0</revnumber>
	<date>June 2005</date>
	<revdescription>
	  <para>
	    Initial version of this document.
	  </para>
	</revdescription>
      </revision>
    </revhistory>
<!-- Added with permission of federico -->
<legalnotice id="legalnotice">
  <para>
    Permission is granted to copy, distribute and/or modify this
    document under the terms of the GNU Free Documentation License
    (GFDL), Version 1.1 or any later version published by the Free
    Software Foundation with no Invariant Sections, no Front-Cover
    Texts, and no Back-Cover Texts.  You can find a copy of the GFDL
    at this <ulink url="ghelp:fdl">link</ulink> or in the file
    COPYING-DOCS distributed with this manual.
  </para>
  <para>
    This manual is part of a collection of GNOME manuals distributed
    under the GFDL.  If you want to distribute this manual separately
    from the collection, you can do so by adding a copy of the license
    to the manual, as described in section 6 of the license.
  </para>
  <para>
    Many of the names used by companies to distinguish their products and
    services are claimed as trademarks. Where those names appear in any
    GNOME documentation, and the members of the GNOME Documentation Project
    are made aware of those trademarks, then the names are in capital letters
    or initial capital letters.
  </para>
  <para>
    DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED UNDER
    THE TERMS OF THE GNU FREE DOCUMENTATION LICENSE WITH THE FURTHER
    UNDERSTANDING THAT:
    <orderedlist>
      <listitem>
	<para>
	  DOCUMENT IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTY OF ANY
	  KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION,
	  WARRANTIES THAT THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT
	  IS FREE OF DEFECTS MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR
	  NON-INFRINGING. THE ENTIRE RISK AS TO THE QUALITY, ACCURACY, AND
	  PERFORMANCE OF THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT
	  IS WITH YOU. SHOULD ANY DOCUMENT OR MODIFIED VERSION PROVE
	  DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL WRITER, AUTHOR
	  OR ANY CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY SERVICING,
	  REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES
	  AN ESSENTIAL PART OF THIS LICENSE. NO USE OF ANY DOCUMENT OR
	  MODIFIED VERSION OF THE DOCUMENT IS AUTHORIZED HEREUNDER EXCEPT
	  UNDER THIS DISCLAIMER; AND
	</para>
      </listitem>
      <listitem>
	<para>
	  UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER IN TORT
	  (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL THE AUTHOR,
	  INITIAL WRITER, ANY CONTRIBUTOR, OR ANY DISTRIBUTOR OF THE DOCUMENT
	  OR MODIFIED VERSION OF THE DOCUMENT, OR ANY SUPPLIER OF ANY OF SUCH
	  PARTIES, BE LIABLE TO ANY PERSON FOR ANY DIRECT, INDIRECT, SPECIAL,
	  INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING,
	  WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE,
	  COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER DAMAGES OR
	  LOSSES ARISING OUT OF OR RELATING TO USE OF THE DOCUMENT AND
	  MODIFIED VERSIONS OF THE DOCUMENT, EVEN IF SUCH PARTY SHALL HAVE
	  BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES.
	</para>
      </listitem>
    </orderedlist>
  </para>
</legalnotice>
  </bookinfo>

  <preface id="preface">
    <title>Preface</title>

    <para>
      GNOME is a project to build a complete desktop and development
      platform based entirely on free software.  Many companies,
      governments, schools, institutions, and individuals have
      deployed the GNOME desktop on their systems.  If you are a
      developer of third-party software ("Independent Software Vendor"
      or <acronym>ISV</acronym>, or "Independent Software Developer"
      (<acronym>ISD</acronym>) if you don't do it commercially), you
      may want to ensure that your existing software runs properly
      under GNOME.  This guide explains how to integrate existing
      software with GNOME, without actually rewriting that software to
      explicitly use the GNOME platform libraries and development
      tools.
    </para>

    <para>
      This guide will be useful in the following situations:
    </para>

    <itemizedlist>
      <listitem>
	<para>
	  You are a software developer or distributor who has an
	  application that is not explicitly designed to work with
	  GNOME, but you want to ensure that it runs comfortably
	  within a GNOME desktop.
	</para>
      </listitem>

      <listitem>
	<para>
	  You are a system administrator for an institution that has
	  deployed GNOME desktops to its users.  You also have legacy
	  or in-house applications, and you want your users of GNOME
	  to be able to access those applications comfortably.
	</para>
      </listitem>

      <listitem>
	<para>
	  You are writing a GNOME application proper and you need a
	  checklist of basic things to do to ensure that your
	  application integrates well with the rest of the GNOME
	  desktop.
	</para>
      </listitem>
    </itemizedlist>

    <para>
      In general, this guide is about integrating existing software
      into a GNOME desktop.  On the other hand, if you are considering
      writing new software, we encourage you to develop it completely
      with GNOME as your target platform; please refer to the <ulink
      url="http://developer.gnome.org">GNOME Developer's Site</ulink>
      for more information.
    </para>

    <para>
      One of the main concerns of GNOME is the user experience.  Users
      should have a comfortable computing environment:  this means
      having a complete desktop and a set of applications which
      operate together in a consistent way.  With relatively little
      work, applications which are not written explicitly with GNOME
      in mind can be made to run comfortably within a GNOME desktop.
    </para>

    <section id="structure">
      <title>Structure of this guide</title>

      <para>
	This guide is structured as a list of tasks that you need to
	perform to integrate existing software with GNOME.  The guide
	presents these tasks roughly in order of importance.  For
	example, the task of adding your application to the GNOME
	desktop's menus appears before the task for adding
	drag-and-drop support.  Also, this guide has an <link
	linkend="apx-integration-checklist">appendix with an
	integration checklist</link> to aid you in evaluating your
	integration work.
      </para>
    </section>

    <section id="standards">
      <title>Standards and freedesktop.org</title>

      <para>
	Many of the integration tasks in this guide rely on standards
	which are relevant to more than GNOME.  Other desktop projects
	like the <ulink url="http://www.kde.org">K Desktop
	Environment</ulink> also use these standards:  if you
	integrate your applications with GNOME, you should have to do
	little or no extra work to make them run in those other
	environments as well.
      </para>

      <para>
	Creating a perfect application is a wonderful feeling.
	Whether large or small, you want the desktop to recognize your
	application and for them to interact appropriately.  With
	multiple desktops currently available, it is best for your
	application to be able to integrate itself in as many of them
	as possible.  Even though no official rules have been adopted,
	there is a set of specifications available at
	<emphasis>freedesktop.org</emphasis>.
      </para>

      <para>
	Although not a formal standards body, freedesktop.org
	maintains a set of informal but commonly agreed upon
	guidelines.  When followed, these guidelines allow
	applications to be integrated on to compliant desktops.
      </para>
    </section>
  </preface>

  <chapter id="basic-integration">
    <title>Basic Integration</title>

    <para>
      This chapter teaches you about the very basic steps you should
      take to integrate a program into the GNOME desktop.  These steps
      concern the following:
    </para>

    <itemizedlist>
      <listitem>
	<para>
	  Letting the user launch your application by making it appear
	  in the desktop's panel menus, or any other launching
	  mechanism in the desktop.
	</para>
      </listitem>
      <listitem>
	<para>
	  Letting the desktop know which types of user-created files
	  require your application to be launched.
	</para>
      </listitem>
      <listitem>
	<para>
	  Letting the desktop know how to display the appropriate
	  icons for your program and the files which your program creates.
	</para>
      </listitem>
    </itemizedlist>

    <section id="desktop-files">
      <title>Desktop files: putting your application in the desktop menus</title>

      <para>
	To run applications from GNOME, users click on icons on their
	desktops or they select the applications which they want to run
	from a menu.  Therefore, the first step in integrating an
	existing program with GNOME is to
	<firstterm>register</firstterm> it with the set of applications
	that users can run.
      </para>

      <para>
	Unlike in Windows or MacOS, in GNOME the users menus are
	automatically constructed from the list of registered
	applications. Each published application specifies a set of
	categories to which it belongs, and the systems menu
	configuration sorts and arranges them. This mechanism follows
	the freedesktop.org desktop entry and menu standards.
      </para>

      <note><para>
	Though common in other desktops, creating your own
	application-specific submenu is not recommended. Instead,
	provide one menu item for each application you ship. Extra items
	such as help files, READMEs or links to your web site should be
	embedded into the application itself.
      </para></note>

      <para>
	In GNOME and other freedesktop.org-compliant desktops, an
	application gets registered into the desktop's menus through a
	<firstterm>desktop file</firstterm>.  This desktop file
	contains a listing of the configurations for your application.
	The desktop takes the information in this file and uses it to:
      </para>

      <itemizedlist>
	<listitem>
	  <para>put the application in the <guimenu>Main Menu</guimenu>.</para>
	</listitem>
	<listitem>
	  <para>list the application in the <application>Run
	      Application...</application> dialog</para>
	</listitem>
	<listitem>
	  <para>create appropriate launchers in the menu or on the desktop.</para>
	</listitem>
	<listitem>
	  <para>associate the name and description of the application.</para>
	</listitem>
	<listitem>
	  <para>use the appropriate icon.</para>
	</listitem>
	<listitem>
	  <para>recognize the MIME types it supports for opening files.</para>
	</listitem>
      </itemizedlist>

      <para>
	To add a menu entry for your application, create a desktop
	file. It should have a unique filename, and there are no
	length limits so avoid abbreviations and feel free to include
	brand names. However, don't put spaces or international
	characters in the file name. For instance,
	"foocorp-painter-pro.desktop" would be a good filename to
	choose but "fcpp.desktop" would be a bad name, as would
	"FooCorp Painter Pro.desktop". The file should be UTF-8
	encoded, and should resemble the following template:
      </para>

      <programlisting><![CDATA[
	[Desktop Entry]
	Encoding=UTF-8
	Name=FooCorp Painter Pro
	Exec=foocorp-painter-pro
	Icon=foocorp-painter-pro
	Type=Application
	Categories=Application;
	]]></programlisting>

      <para>
	These .desktop files contain metadata about your application,
	and play a central role in integrating the program with the
	GNOME and other standards compliant desktops. The template
	presented here is the most basic possible. The file can be
	linguistically translated so your applications name can appear
	in the user's native language.
      </para>

      <para>
	Place this file in the
	<literal>/usr/share/applications</literal> directory so that
	it is accessible by everyone, or in
	<literal>~/.local/share/applications</literal> if you only
	wish to make it accessible to a single user.  Which is used
	should depend on whether your application is installed
	systemwide or into a user's home directory.  GNOME monitors
	these directories for changes, so simply copying the file to
	the right location is enough to register it with the
	desktop. <footnote>
	  <para>
	    Note that the
	    <literal>~/.local/share/applications</literal> location is
	    not monitored by versions of GNOME prior to version 2.10
	    or on Fedora Core Linux, prior to version 2.8.  These
	    versions of GNOME follow the now-deprecated vfolder
	    standard, and so .desktop files must be installed to
	    <literal>~/.gnome2/vfolders/applications</literal>. This
	    location is not supported by GNOME 2.8 on Fedora Core nor
	    on upstream GNOME 2.10 so for maximum compatibility with
	    deployed desktops, put the file in both locations.
	  </para>

	  <para>
	    Note that the KDE Desktop requires one to run
	    <command>kbuildsycoca</command> to force a refresh of the
	    menus.
	  </para>

	<!-- MH: Actually I think some distros merge the old vfolders
	directory in so placing items in both locations will cause
	duplicate menu entries. Autopackage seems to have a program
	called "vfolder-magic" which modifies the vfolder
	definition in the users home directory. The comment at the
	top says:

	*  Program that adds or removes a desktop entry in
	*  ~/.gnome2/vfolders/applications.vfolder-info. This seems to be
	*  necessary with gnome 2.8, at least.

        -->
	</footnote>

	<!-- MH: Though this is a GNOME ISV guide, as so much of the
	basic integration work is also compatible with KDE it would
	be wise in my opinion to mention KDE and observe any quirks
	that are necessary to integrate correctly with that
	too. There's no real reason not to, ISVs want the maximum
	userbase possible (indeed, is this not what separates ISVs
	from your average open source project?).
        -->
      </para>

      <para>
	Each working desktop file needs to follow the same format.  A
	minimal example of a desktop file is shown in <xref
	linkend="ex-sample-desktop-file" />.  The file is split into
	sections, each starting with the section descriptor in square
	brackets.  In this example, only one section is shown as that
	is the essential section to integrating your application to
	the desktop.  Within each section, the part of each line
	before the equal sign is the <firstterm>key</firstterm> while
	the second half is the <firstterm>value</firstterm>.  An
	explanation of each line is shown in <xref
	linkend="tb-desktop-file" />.
      </para>

      <note>
	<para>
	  Other than the first line identifying the desktop file, the
	  order of the lines is not important.  In <xref
	  linkend="ex-sample-desktop-file" />, the line
	  <command>Type=Application</command> could be the second row,
	  the fifth row, or the last row and the result would be the
	  same.
	</para>

	<para>
	  However, the keys are case sensitive.
	  <command>Type=Application</command> is not the
	  same as <command>type=Application</command> or
	  <command>TYPE=Application</command>.
	</para>
      </note>

      <example id="ex-sample-desktop-file">
	<title>Sample desktop file</title>
<screen>
[Desktop Entry]
Type=Application
Encoding=UTF-8
Name=Sample Application Name
Comment=A sample application
Exec=application
Icon=application.png
Terminal=false
</screen>
      </example>

      <table id="tb-desktop-file">
	<title>Line by line explanation</title>
	<tgroup cols="2">
	  <colspec colnum="1" colname="line" colwidth="1"/>
	  <colspec colnum="2" colname="desc" colwidth="1"/>

	  <thead>
	    <row>
	      <entry>Line</entry>
	      <entry>Description</entry>
	    </row>
	  </thead>

	  <tbody>
	    <row>
	      <entry><command>[Desktop Entry]</command></entry>
	      <entry>The first line of every desktop file and the section
		header to identify the block of key value pairs associated
		with the desktop.  Necessary for the desktop to recognize
		the file correctly.</entry>
	    </row>
	    <row>
	      <entry><command>Type=Application</command></entry>
	      <entry>Tells the desktop that this desktop file pertains to
		an application.  Other valid values for this key are
		<command>Link</command> and
		<command>Directory</command>.</entry>
	    </row>
	    <row>
	      <entry><command>Encoding=UTF-8</command></entry>
	      <entry>Describes the encoding of the entries in this desktop
		file.</entry>
	    </row>
	    <row>
	      <entry><command>Name=Sample Application Name</command></entry>
	      <entry>Names of your application for the main menu and any launchers.</entry>
	    </row>
	    <row>
	      <entry><command>Comment=A sample application</command></entry>
	      <entry>Describes the application.  Used as a tooltip.</entry>
	    </row>
	    <row>
	      <entry><command>Exec=application</command></entry>
	      <entry>The command that starts this application from a
		shell.  It can have arguments.</entry>
	    </row>
	    <row>
	      <entry><command>Icon=application.png</command></entry>
	      <entry>The icon name associated with this application.</entry>
	    </row>
	    <row>
	      <entry><command>Terminal=false</command></entry>
	      <entry>Describes whether application should run in a terminal.</entry>
	    </row>
	  </tbody>

	</tgroup>
      </table>

      <section id="commandline">
	<title>Starting your application</title>
	<para>
	  If your application can take command line arguments, you can
	  signify that by using the fields as shown in <xref
	    linkend="tb-exec-params"/>.
	</para>

	<table id="tb-exec-params">
	  <title>Exec variables</title>
	  <tgroup cols="2">
	    <colspec colnum="1" colname="line" colwidth="1"/>
	    <colspec colnum="2" colname="desc" colwidth="1"/>

	    <thead>
	      <row>
		<entry>Add...</entry>
		<entry>Accepts...</entry>
	      </row>
	    </thead>

	    <tbody>
	      <row>
		<entry><command>%f</command></entry>
		<entry>a single filename.</entry>
	      </row>
	      <row>
		<entry><command>%F</command></entry>
		<entry>multiple filenames.</entry>
	      </row>
	      <row>
		<entry><command>%u</command></entry>
		<entry>a single URL.</entry>
	      </row>
	      <row>
		<entry><command>%U</command></entry>
		<entry>multiple URLs.</entry>
	      </row>
	      <row>
		<entry><command>%d</command></entry>
		<entry>a single directory.  Used in conjunction with
		  <command>%f</command> to locate a file.</entry>
	      </row>
	      <row>
		<entry><command>%D</command></entry>
		<entry>multiple directories.  Used in conjunction with
		  <command>%F</command> to locate files.</entry>
	      </row>
	      <row>
		<entry><command>%n</command></entry>
		<entry>a single filename without a path.</entry>
	      </row>
	      <row>
		<entry><command>%N</command></entry>
		<entry>multiple filenames without paths.</entry>
	      </row>
	      <row>
		<entry><command>%k</command></entry>
		<entry>a URI or local filename of the location of the
		  desktop file.</entry>
	      </row>
	      <row>
		<entry><command>%v</command></entry>
		<entry>the name of the Device entry.</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>

      </section>

      <section id="internationalization">
	<title>Foreign languages</title>

	<para>
	  To create localized names and comments, additional lines for
	  each locale need to be added.  For example, to add a Swedish
	  version of the comment, add the following line:
	</para>

	<para>
	  <command>
	    Comment[sv]=Exempelprogramnamn
	  </command>
	</para>

	<para>
	  There is no limit to the number of translations in the file.
	</para>

	<tip>
	  <para>
	    Since maintaining a long list of translations in a file is
	    cumbersome, a better way to create these translations is to use
	    the <application>intltool</application> package.  See the man
	    pages for <application>intltool-extract</application> and
	    <application>intltool-merge</application> for more
	    information.
	  </para>
	</tip>

      </section>

      <section id="desktop-references">
	<title>References</title>

	<para>
	  <ulink
	  url="http://standards.freedesktop.org/desktop-entry-spec/latest/index.html">Desktop
	  Entry Specification</ulink> &#x2014; Specifications for
	  creating a desktop file.
	</para>
      </section>
    </section>

    <section id="icons">
      <title>Installing icons</title>

      <para>
	In <xref linkend="ex-sample-desktop-file"/>, we have specified the
	icon for this file as
	<filename><replaceable>application.png</replaceable></filename>.
	In order for this to work, we need to put that icon file in the
	correct directory.
      </para>

      <para>
	The desktop looks for icons in the selected theme directory of
	<filename>/usr/share/icons/</filename>.  Application icons should be
	available at least at a resolution of 48x48 pixels. Place the icon in
	<filename>/usr/share/icons/hicolor/48x48/apps/</filename>.  This is the
	directory the desktop looks in if there is no icon for your application in
	the selected theme.  If you have themed icons, put them in the appropriate
	directories.
      </para>

      <para>
	To better visually integrate with the GNOME desktop, while keeping your
	application look native when run under KDE, Windows XP or Mac OS X,
	follow the <ulink
	url="http://tango.freedesktop.org/Tango_Icon_Theme_Guidelines">Tango
	Style guidelines</ulink> when creating your artwork. The document
	explains various aspects of icon design, including colors, lighting and
	sizes. Some typical workflow and video tutorials are also provided.
      </para>


      <section id="icons-references">
	<title>References</title>

	<para>
	  <ulink
	  url="http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html">Icon
	  Theme Specification</ulink> &#x2014; Describes how to install and look up
	  icons in a themeable way.
	</para>

	<para>
	  <ulink
	  url="http://standards.freedesktop.org/icon-naming-spec/latest/">Icon
	  Naming Specification</ulink> &#x2014; Provides a canonical
	  naming scheme for icon files.
	</para>

	<para>
	  <ulink
	  url="http://tango.freedesktop.org/Tango_Icon_Theme_Guidelines">Tango Style Guidelines</ulink> 
	  &#x2014; Provides description on how to design clean and 'multiplatform' icon artwork.
	</para>
      </section>
    </section>

    <section id="mime">
      <title>Adding MIME types</title>

      <para>
	If your application can open specific MIME types, you need to let
	the desktop know in the desktop file.  For example, if your
	application can accept <filename>png</filename> files, add the
	following line into your desktop file:
      </para>

      <para>
	<screen>MimeType=image/png</screen>
      </para>

      <para>
	Additional Mime types can be added by separating the different
	types with semicolons.
      </para>

      <para>
	The system already knows of a large number of MIME types.
	However, if you are creating one of your own, you need to
	register your MIME type into the MIME database.  In the
	<filename>/usr/share/mime/packages/</filename> directory,
	create an <filename>XML</filename> file with the format as
	shown in <xref linkend ="ex-mime-xml"/>.
      </para>

      <example id="ex-mime-xml">
	<title>Sample file for registering a new MIME type</title>
<screen>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info"&gt;
   &lt;mime-type type="application/x-<replaceable>example</replaceable>"&gt;
     &lt;comment&gt;Example file type &lt;/comment&gt;
     &lt;magic priority="50"&gt;
       &lt;match value="<replaceable>search-string</replaceable>" type="string" offset="10:140"/&gt;
     &lt;/magic&gt;
     &lt;glob pattern="*.<replaceable>newextension</replaceable>"/&gt;
   &lt;/mime-type&gt;
&lt;/mime-info&gt;
</screen>
      </example>

      <para>
	In this example, replace the example MIME type with the name of
	your MIME type.  The <firstterm>magic</firstterm> section searches
	files for the search string for identification.  The
	<firstterm>glob</firstterm> line uses the suffix of file names for
	identification.
      </para>

      <tip>
	<para>
	  Because the <command>magic</command> command forces the computer
	  to open the files to search for the string, the
	  <command>glob</command> command is preferable.
	</para>
      </tip>

      <para>
	Once your new MIME type is adequately described in the file, run
	the following in a shell:
      </para>

      <para>
	<screen>update-mime-database /usr/share/mime</screen>
      </para>

      <tip>
	<para>
	  For more information on choosing a good MIME extension and to
	  register your MIME type, go to the <ulink
	    url="http://www.iana.org/cgi-bin/mediatypes.pl">IANA</ulink>
	  website.
	</para>
      </tip>

      <section id="mime-references">
	<title>References</title>

	<para>
	  <ulink
	  url="http://standards.freedesktop.org/shared-mime-info-spec/latest/">Shared
	  MIME Info Specification</ulink> &#x2014; Describes the MIME registration
	  system in detail.
	</para>
      </section>

    </section>

  </chapter>

  <chapter id="deeper-integration">
    <title>Deeper Integration with the Desktop</title>

    <para>
      This chapter contains a list of things which you can do to make
      your application have better integration with GNOME than the
      absolute minimum.  For example, GNOME is able to display feedback while an
      application is being launched:  you can see how to enable this feedback
      in <xref linkend="startup-notification"/>.  Also, if your
      software creates documents or other "printable" data, you can
      install a thumbnailer utility to let the GNOME file manager
      create thumbnail images specific to your program.
    </para>

    <section id="startup-notification">
      <title>Startup notification</title>

      <para>
	Although the fields shown in <xref linkend="desktop-files"/>
	provide enough information for the desktop to recognize your
	application, there are other fields that may be useful for your
	particular case.  One of these fields is <firstterm>startup
	  notification</firstterm>.
      </para>

      <para>
	When startup notification is set, the panel and cursor notifies
	the user that the application has started.  When the application
	appears onscreen, the panel and cursor return to normal.
      </para>

      <para>
	To let the launcher know your application supports startup
	notification, add the following line to your desktop file:
      </para>

      <para>
	<command>
	  StartupNotify=true
	</command>
      </para>

      <para>
	This command in the desktop file enables the desktop to use
	whatever startup notification is built in to either your
	application or your toolkit.  Most modern toolkits work
	transparently with the startup notification system.  If you are
	not using a modern toolkit, the <ulink
	  url="http://freedesktop.org/wiki/Standards_2fstartup_2dnotification_2dspec">Startup
	  Notification Spec</ulink> has the details that you need to
	implement it yourself.
      </para>

      <tip>
	<para>
	  Regardless of toolkit, there is one type of application where
	  you would have to manually handle feedback.  Applications with
	  remoting capabilities (where you tell an existing process to
	  open a new window instead of starting a new process) cannot use
	  the built-in mechanism.  The value of the DESKTOP_LAUNCH_ID
	  environment has to be passed by your application and have it
	  notify the launching system of your new window.  If you are
	  using <application>GTK+</application>, the documentation for
	  <function>gdk_notify_startup_complete()</function> has a bit
	  more information.
	</para>
      </tip>

      <section id="startup-notification-references">
	<title>References</title>

	<para>
	  <ulink
	  url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">Startup
	  Notification Protocol</ulink> &#x2014; Describes the
	  low-level details of how startup notification is implemented
	  in the X Window System.
	</para>
      </section>
    </section>

    <section id="thumbnailer">
      <title>Installing a Thumbnailer Program</title>

      <para>
	The GNOME file manager, Nautilus, can display little
	thumbnails tailored for each file instead of generic icons in
	its file lists.  For example, a word processor document can be
	made to appear as a little version of the first page in the
	document.  This is useful because users can see a small
	representation of the visible data in their files, which may
	aid in recalling what file they are looking for.  You can make
	your application create these thumbnails with a few simple
	steps.
      </para>

      <!-- FIXME: screenshot of Nautilus showing thumbnails -->

      <para>
	A <firstterm>thumbnailer</firstterm> is a program with no user
	interface that takes a file and a pixel size as inputs, and it
	writes a thumbnail for that file.  GNOME determines which
	thumbnailer program to use based on the MIME type of the file
	for which a thumbnail is to be generated.  The mapping between
	MIME types and thumbnailer programs is stored as a series of
	GConf keys.
      </para>

      <para>
	For each MIME type which you want to handle, you have to
	create a pair of GConf keys:
      </para>

      <variablelist>
	<varlistentry>
	  <term><literal>/desktop/gnome/thumbnailers/<replaceable>application@x-foo</replaceable>/enable</literal></term>
	  <listitem>
	    <para>
	      Type: boolean.  Determines whether this thumbnailer will
	      be run.  You can enable or disable each individual
	      thumbnailer.  When you install a new thumbnailer, you
	      should of course make this key's value be
	      <symbol>true</symbol>.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>/desktop/gnome/thumbnailers/<replaceable>application@x-foo</replaceable>/command</literal></term>
	  <listitem>
	    <para>
	      Type: string.  The command which GNOME will use when it
	      needs to generate a thumbnail for a file of type
	      <replaceable>application@x-foo</replaceable>.  For
	      example, the value could be
	      "<literal>application-x-foo-thumbnailer %i %o
	      %s</literal>".  See below for an explanation of the
	      percent signs.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>
	That is, each MIME type requires two GConf keys
	(<literal>enable</literal> and <literal>command</literal>)
	under the same path.  The path name can be derived from the
	MIME type name by substituting a "<literal>/</literal>" with
	"<literal>@</literal>".  For example, a thumbnailer for
	<literal>image/x-my-format</literal> would need two keys:
	<literal>/desktop/gnome/thumbnailers/image@x-my-format/enable</literal>
	and
	<literal>/desktop/gnome/thumbnailers/image@x-my-format/command</literal>.
      </para>

      <para>
	Within the <literal>command</literal> key, GNOME will
	look for percent sequences and substitute them with actual values:
      </para>

      <informaltable frame="none">
	<tgroup cols="2">
	  <tbody valign="top">
	    <row>
	      <entry><literal>%i</literal></entry>
	      <entry>
		Input file name.  This is the file that your
		thumbnailer needs to read.
	      </entry>
	    </row>
	    <row>
	      <entry><literal>%u</literal></entry>
	      <entry>
		Input URI.  If your thumbnailer can handle URIs
		instead of plain file names, use <literal>%u</literal>
		instead of <literal>%i</literal>.
	      </entry>
	    </row>
	    <row>
	      <entry><literal>%o</literal></entry>
	      <entry>
		Output file name.  This is where your thumbnailer
		should write the thumbnail image in PNG format.
	      </entry>
	    </row>
	    <row>
	      <entry><literal>%s</literal></entry>
	      <entry>
		Size of the thumbnail as a single integer.  For
		example, if this gets substituted with
		<literal>128</literal>, it means that your thumbnailer
		should output an image no bigger than 128×128
		pixels.
	      </entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <para>
	Either of <literal>%i</literal> and <literal>%u</literal> must
	appear in your command, and <literal>%o</literal> is also
	mandatory.  The <literal>%s</literal> substitution is
	optional, but we recommend that your thumbnailer pay attention
	to it.
      </para>

      <section>
	<title>Additional information</title>

	<para>
	  As an additional configuration parameter, you can turn on
	  the boolean key
	  <literal>/desktop/gnome/thumbnailers/disable_all</literal>
	  to disable the generation of all thumbnails.
	</para>
      </section>

      <!-- FIXME: we mentioned the GConf keys, but not how to set them
      globally.  Do we need to describe how to install
      schemas/defaults? -->
    </section>

  </chapter>

  <appendix id="apx-integration-checklist">
    <title>Integration Checklist</title>

    <para>
      This appendix provides a checklist of the various tasks
      presented through this guide.  You can use the checklist to
      ensure that your software is integrated into GNOME in at least
      the most basic ways, and also as a resource to plan for further
      integration work.
    </para>

    <orderedlist>
      <listitem>
	<para>
	  Does your application appear in the menus of the GNOME Panel?
	</para>
      </listitem>
      <listitem>
	<para>
	  Does your application have an icon for the panel menus or
	  the desktop? If so, does it have multiple pre-rendered sizes
	  and a scalable SVG version?
	</para>
      </listitem>
      <listitem>
	<para>
	  If your application can load or save files, does it register
	  the MIME types that it can handle?
	</para>
      </listitem>
      <listitem>
	<para>
	  Does your application provide MIME icons for the file
	  manager?
	</para>
      </listitem>
      <listitem>
	<para>
	  Does your application support startup notification, so that
	  GNOME can display feedback to the user while your
	  application is being launched?
	</para>
      </listitem>
      <listitem>
	<para>
	  If your application creates "printable" documents, does it
	  install a thumbnailer for use by the file manager?
	</para>
      </listitem>
    </orderedlist>
  </appendix>

  <appendix id="apx-acknowledgments">
    <title>Acknowledgments</title>

    <para>
      Many thanks to Jakub Steiner for providing a beautiful CSS
      stylesheet for the HTML version of this guide!
    </para>
  </appendix>

</book>