<!DOCTYPE ARTICLE PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
]>

<article id="index">
  <artheader>
    <authorgroup>
      <author>
	<firstname>Miguel</firstname> 
	<surname>de Icaza</surname> 
	<affiliation>
	  <address>
	    <email>miguel@gnu.org</email>
	  </address>
	</affiliation>
      </author>
    </authorgroup>
    <copyright>
      <year>1999</year>
      <holder>Miguel de Icaza</holder>
    </copyright>
    <title>The GNOME configuration files</title>
    <abstract>
      <para>
	GNOME applications and the GNOME libraries use a number of
	special files to configure the GNOME desktop.  By dropping
	new files in special locations or customizing these files
	the GNOME desktop can be configured in a number of ways.
      </para>
    </abstract>
  </artheader>

<!--  <sect1 id="dot-desktop">
    <title>Desktop file information</title>
    
    <para>
    </para>
  </sect1> -->

  <sect1 id="mime-info">
    <title>MIME type information</title>

    <sect2>
      <title>MIME type handling in the GNOME desktop</title>

      <para>MIME types are using to distinguish what sort of operations
	and attributes a file has.  The operations are usually things
	like: how to open files of a given mime-type, how to view
	them, what icon is used to display it and so on.</para>
	
      <para>Besides the MIME types, in GNOME, the metadata system is
	used to provide information in a per-file basis (for example, to
	override the defaults of the mime-type).</para>

      <para>GNOME uses a number of techniques depending on the speed
	requirements to figure out what the MIME type of a file is.
	It is possible to get the mime-type by only using the filename
	or if speed is not important, by checking the actual file
	contents (for more information look at the gnome-mime.h header
	file and the accompanying documentation).</para>

      <para>There are ways in GNOME to fetch the values bound to a
	mime-type with the routines provided in the gnome-libs routine
	<filename>gnome-mime-info.c</filename>.</para>
    </sect2>

    <sect2>
      <title>Mapping a filename to a MIME type.</title>

      <para>The GNOME system uses MIME types to identify the contents
	of files.  In addition, the GNOME system can bind
	arbitrary information to these MIME types by the Keys system.
	These are used within the system to associate actions, icons,
	and various operations to MIME types, and by extension to the
	files on the system</para>

      <para>To make the GNOME desktop aware of a new MIME type it is
	necessary to install a file with the extension <filename>.mime</filename> in the
	<filename>$gnome/share/mime-info</filename> directory or from the
	<filename>~/.gnome/mime-info directory.</filename></para>

      <para>The file
	<filename>$gnome/share/mime-info/gnome.mime</filename> is
	special, as it contains the defaults for gnome, and is read
	first.  In addition, the file
	<filename>~/.gnome/mime-info/user.mime</filename> is read
	last.  This will guarantee that there is a way to set system
	defaults, and there is a way for the user to override them.
	There is currently no way to tell anything about the order of
	the other files in those directories, nor is there anyway to
	override system defaults yet.</para>

      <para>The format is the following:

	<example>
	  <title>Definining a MIME type</title>
	  <programlisting>
mime-type-name
	ext[,priority]: ext1 ext2 ext3
	ext[,priority]: ext4
	regex[,priority]: regex1
	regex[,priority]: regex2
	  </programlisting>
	</example>
      </para>
      
      <para>where <filename>"mime-type-name"</filename> is a valid
	MIME type.  For example <emphasis>"text/plain"</emphasis>.</para>

      <para>Multiple ext and regex entries can be provided for this
	mime-type.  Please note that the regex keyword only allows one
	regular expression per line, while the ext keyword lets you
	list a number of extensions in the same line.</para>

      <para>The priority indicates the number of components that your
	extension matches (the bigger the number, the better).  Right
	now, only priorities 1 and 2 are supported.</para>

      <para>This is required to distinguish the mime type correctly
	for situations like <filename>emacs.tar.gz</filename>, where
	the <filename>.gz</filename> extension could match the
	"compressed" rule, while the real match should be for
	<filename>"tar.gz"</filename>, so a
	<filename>"tar.gz"</filename> would have a higher priority</para>

      <para>For example, for a vCalendar application, this file would be
	installed:

	<example>
	  <title><filename>calendar.mime</filename> sample file</title>
	  <programlisting>
application/v-calendar:
	ext: vcf
	  </programlisting>
	</example>
      </para>
    </sect2>
    
    <sect2>
      <title>Adding keys to a MIME type</title>

      <para>To add keys to a mime-type, it is necessary to install a
	file with the extension <filename>.keys</filename> in the
	<filename>$gnome/share/mime-info</filename> directory or from
	the <filename>~/.gnome/mime-info</filename> directory.</para>

      <para>Similar to the <filename>.mime</filename> files, there is
	a provision for a
	<filename>$gnome/share/mime-info/gnome.keys</filename> file
	and a <filename>~/.gnome/mime-info/user.keys</filename> file.
	This, as above, allows for both defaults and user
	preferences.</para>

      <para>The full content of the .keys database is the sum of all
      of the .keys files in the directory. </para>
	
      <para>The file has the following format:

	<example>
	  <title>Sample keys definition file</title>
	  <programlisting>
mime-type-match:
	[\[LANG\]]key=value
	  </programlisting>
	</example>
      </para>
      
      <para>"mime-type-match" allows you to provide either a full
	mime-type, or a glob expression, for example, you can list
	<filename>"image/gif"</filename> for making the entries apply
	to the image/gif mime type or <filename>"image/*"</filename>
	if you want the keys to apply to all of the images.</para>

      <para>The [LANG] part is optional, and it used to provide internationalized
	versions of any strings appearing in the value.</para>

      <para>key is the key (a number of keys are standardized) and
	value is the value bound to it.</para>

      <para>Given that the actual keys definition can come from
	multiple sources, it is possible for example to ship a file
	that only defines icons for a set of well known files and
	format (this is the case for the file manager) and have
	specific applications install the actual properties when they
	are installed</para>
	
      <para>For example, the GIMP could ship with this file:

	<example>
	  <title>Sample GIMP keys file</title>
	  <programlisting>
image/*:
	open=gimp %f
	
image/x-xcf:
	icon-filename=/opt/gimp/share/xcf.png
	  </programlisting>
	</example>
      </para>

      <para>This will make the GIMP the handler for the open action.
	Files of type xcf would use the filename pointed in the
	icon-filename key.</para>

      <para>%f gets interpolated with the file name or the list of file names that
	matched this mime-type.</para>

      <para>As you can see, a <filename>.keys</filename> file does not
	need to provide all of the values, it can just provide or
	override some of the actions.</para>

      <para>Note that user defined bindings in
	<filename>.keys</filename> file will take precedence over
	system installed files.</para>
    </sect2>

    <sect2>
      <title>Default keys</title>

      <para>The following keys are recognized in the GNOME desktop:</para>

    <table>
	<title>Standard keys used by the GNOME desktop</title>
	<tgroup cols="2">
	  <thead>
	    <row>
	      <entry>Key name</entry>
	      <entry>Action</entry>
	    </row>
	  </thead>
	  <tbody>
	    

	    <row>
	      <entry>icon-filename</entry>

	      <entry>points to a filename with the icon that should be
	      used to represent files of this type</entry>
	    </row>

	    <row>
	      <entry>open</entry>
	      <entry>open the give file with this command.</entry>
	    </row>

	    <row>
	      <entry>fm-open</entry>

	      <entry>file-manager open.  If present, the file manager
		will use this action instead of the value in open to
		perform this action (the file manager for example will
		open archive files as if they were directories by
		using the VFS).</entry>
	    </row>

	    <row>
	      <entry>view</entry>

	      <entry>Command to view the file contents.</entry>
	    </row>

	    <row>
	      <entry>fm-view</entry>

	      <entry>file-manager view.  If present, invoking the view
		operation on the file manager will use the value
		defined here instead of the value in "view".</entry>
	    </row>

	    <row>
	      <entry>ascii-view</entry>

	      <entry>A command that should be used to do an
		ascii-rendering of the file.  Used as a fall-back by
		the filemanager if a "view" action does not
		exist.</entry>
	    </row>

	    <row>
	      <entry>fm-ascii-view</entry>

	      <entry>Fall-back operation for the file manager as
		well.</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>

      <para>Those keys are also queried on the metadata (except in the
	cases where the lookup would be too expensive).</para>
    </sect2>

    <sect2>
      <title>Defining multiple actions</title>

      <para>Sometimes it is important to provide more than one "open"
	action.  To do this, the keys should be specified in the
	following fashion (The same applies to any other key that
	might need more than one option):

	<example>
	  <title>Multiple open actions defined</title>
	  <programlisting>
text/plain:
	open=command %f
	open.tag1.Do this and that=this-and-that %f
	open.tag2.Gzip it=gzip %f
	open.tag3.Mail it=mail %{Recipient} < %f
	  </programlisting>
	</example>
      </para>
      
      <para>This will define a default action (which would invoke
"command %f"), and three extra open commands:</para>

      <table>
	<title>Sample mappings</title>
	<tgroup cols="2">
	  <thead>
	    <row>
	      <entry>Open key name</entry>
	      <entry>Mapping</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry>Do this and that</entry>
	      <entry>this-and-that %f</entry>
	    </row>
	    <row>
	      <entry>Gzip it</entry>
	      <entry>gzip %f</entry>
	    </row>
	    <row>
	      <entry>Mail it</entry>
	      <entry>mail ${Recipient} < %f</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>

      <para>Please notice that you have to add a "tag" to every "open"
	key.</para>

    </sect2>

    <sect2>
      <title>Localizing the texts for a tagged key</title>

      <para>The reason for using the tags, is that they are required
	to distinguish the correct value for internationalization
	purposes, here is how the above example would be translated to
	Spanish:

	<example>
	  <title>Sample keys with localization support</title>
	  <programlisting>
text/plain:
	open=command %f
	open.tag1.Do this and that=this-and-that %f
	[es]open.tag1.Hacer esto y aquello=this and that %f
	open.tag2.Gzip it=gzip %f
	[es]open.tag2.Comprimir con gzip=gzip %f
	open.tag3.Mail it=mail %{Recipient} < %f
	[es]open.tag3.Enviarlo por correo=mail %{Recipient} < %f
	open.tag4.Example=example %f
	  </programlisting>
	</example>
	</para>
      
	<para>To the application programmer, if the code is running
	  with LANG=es, he will get the following keys: "open",
	  "open.tag1.Hacer esto y aquello", "open.tag2.Comprimir con
	  gzip", "open.tag3.Enviarlo por correo" and
	  "open.tag4.Example"</para>

	<para>If a translation entry were missing, he would get the
	  general definition for the default value (in the example
	  above, I did not translate the value for open.tag4.</para>
    </sect2>
  </sect1>

  <sect1 id="help-file">
    <title>Help files in GNOME</title>

    <para>The GNOME libraries provide a special macro to include a
      quick index to the help files installed by a package.  To
      achieve this, the application should install its help files and
      the <filename>topic.dat</filename>in a special directory that
      the GNOME libraries will search at runtime.</para>

    <para>The directory is the
      <filename>$(datadir)/gnome/help/CODEID/LOCALE/</filename>.
      Where CODEID is the CODEID used in the
      <structname>GnomeUIInfo</structname> structure for help files.
      And LOCALE is the locale code name.  The english documentation
      will set the LOCALE to C.</para>

    <para>In this directory, a number of HTML files are expected to be
      installed (The GNOME project uses Docbook for its documentation,
      and it installs their documentation there).</para>

    <para>The special file <filename>topic.dat</filename> is used by
      the <classname>GnomeApp</classname> helper routines to construct
      the index of available help for the application.  The format of
      this file is very simple: it consists of a number of lines, one
      per topic, and the first string up to the first tab character is
      the filename (might include anchors) for the topic being
      defined, then the tab character followed by text that will
      appear on the menu (what the user will see).</para>

    <para>
      For example, here is the topic.dat for the GNOME calendar
      application for the C locale is:

      <example>
	<title>GNOME calendar <filename>topic.dat</filename>
	file</title>
	<programlisting>
gnomecal.html   Manual
cmdline.html    Command line options 
	</programlisting>
      </example></para>

    <para>We suggest that users create in their programs a
      <filename>doc</filename> directory and that they create a
      per-locale directory.  This will allow translators to install
      their own translated versions of the work in there with little
      effort.</para>
      
    <para>Users of Automake can use this fragment for installing the
      help files in the proper location:

      <example>
	<title>Automake fragment for installing GNOME help
	files</title>
	<programlisting>
package_helpdir = $(datadir)/gnome/help/package/C

package_help_DATA =    \
        package.html   \
        topic.dat
	</programlisting>
      </example></para>
  </sect1>
  
<!--  <sect1 id="user-desktop">
    <title>Per-user desktop information</title>

    <para>
    </para>
  </sect1>-->

  <sect1 id="gnorba"><!-- ECL -->
    <title>GNOME Object Activation Directory</title>
    <sect2><title>CORBA Server Handling in the GNOME Desktop</title>

      <para>To allow applications to request access to a specific
      CORBA object, GNOME CORBA servers place information in GOAD, the
      GNOME Object Activation Directory. This directory stores
      information on the CORBA objects that a program can provide to
      other programs. Each directory entry contains a unique
      implementation identifier (the "GOAD ID"), a list of interfaces
      that the object supports, a human-readable description of the
      object implementation, and information on how to create a new
      instance of the object implementation.</para>

      <para>If an application provides the implementation for a CORBA
      object, it is simple to integrate that object into the GOAD
      system. An application would install a '.goad' data file into
      the correct directory as part of its installation process. Then,
      a few simple function calls must be made when the object is
      created and destroyed, and the application must handle an extra
      command line option.</para>

      <para>Included with the GNOME libraries is 'goad-browser'. This
      program lists all the objects registered with GOAD, and allows
      the user to activate these objects, and see which objects are
      currently running.</para>

      <para>Complex activation arrangements are also possible with
      GOAD. An object factory can be used to arbitrate the object
      creation process in a manner that is transparent to the
      client. CORBA implementations in shared libraries also can be
      loaded directly into the address space of the application,
      facilitating higher performance.</para>

    </sect2>
  </sect1>

  <sect1 id="sound">
    <title>GNOME Desktop Sound Configuration</title>
    <sect2><title>Allowing Configurable Per-Application Sound Events</title>
      <para>
      GNOME applications can easily register events for which they
      want user-configurable sounds to be played, and then trigger
      those events. This is done through the gnome triggers system.
      </para>
      <para>The first step in adding sound events is to create a
      .soundlist file that describes the application and each
      event. The format is the following:
<example>
<title>Defining an application's sound event</title>
<programlisting>
[__section_info__]
description=MyApplication

[event1]
file=default1.wav
description=This is a sound event

[event2]
file=default2.wav
description=This is another event
</programlisting>
</example>

The description in the '__section_info__' section should be the name
of the application as the user is to see it. Then, a section for each
event provides a description, and the filename of the default sound to
play.</para>

    <para>The application will also need to call the gnome_triggers_do
    function with the appropriate parameters whenever the event in
    question occurs. By following these two steps, the application
    will allow the user to easily configure what sounds are assigned
    to important application events.</para>

    </sect2>
  </sect1>

<!--  <sect1 id="themes">
    <title>Theme configuration</title>
    <para>
    </para>
  </sect1> -->

  <sect1 id="type-conv">
    <title>File type conversion configuration files</title>

    <para>GNOME includes a number of built-in routines to convert
      files from different formats by using rules.  These routines are
      used by a few programs in the system.  A number of conversion
      rules are provided as part of the default GNOME installation,
      and it is possible for users and system administrators to extend
      these rules with their own rules and their own filters to
      improve the system.</para>

    <para>The system uses MIME types to identify the source file
      format and the target file format.  The GNOME routines will try
      to convert the files from the source to the target with the
      mininum number of operations.</para>

    <para>The file format conversion is achieved by invoking a number
      of filters that convert their standard input from one mime type
      to another mime type.</para>

    <para>The rules for converting from a mime-type to another
      mime-type are loaded from the
      <filename>$gnome-prefix/share/type-convert</filename> directory,
      any files in that directory whose extension is
      <filename>.convert</filename> is loaded as well as the per-user
      <filename>~/.gnome/type.convert</filename> file.</para>
    
    <para>The file format used to define a filter is very
    simple:

      <example>
	<title>Sample MIME type file conversion definition</title>
	<programlisting>
image/gif image/x-portable-pixmap giftopnm
	</programlisting>
      </example>
      
	This sample file conversion file defines a conversion rule
	from the image/gif MIME type to the image/x-portable-pixmap
	MIME type.  The program used for the conversion is
	<filename>giftopnm</filename>.  This program should do the
	specified MIME type conversion by reading its standard input
	and writing the results on the standard output.
    </para>
    
  </sect1>

  <sect1>
    <title>Configuring the desktop</title>

    <para>It is possible to configure the desktop for the users on
      your system.  This is accomplished by populating the
      <filename>$libdir/mc/desktop-scripts</filename>
      directory.</para>

    <para>The directory $(libdir)/mc/desktop-scripts is a place holder for
      information on how to configure the default's user desktop.  There are
      a number of files that can be installed in this
      directory:

        <itemizedlist>
          <listitem><para>Link definition files: These files are used
	    to create links to web and ftp sites on the user's desktop.
	  </para></listitem>

          <listitem><para>Executables: Programs or links to programs that will be
	    executed when the user requests a directory rescan.
          </para></listitem>
        </itemizedlist>

      </para>

      <sect2>
        <title>Link definition file format</title>

	<para>The file should contain an ini-like file whose contents
	  are as follows:

    	<example>
    	  <title>Sample link definition file</title>
    	  <programlisting>
[linkname]
title=Title in english
title[NN]=Title in language NN
type=url
url=some-url
    	  </programlisting>
    	</example>
    
	The linkname is the name of the file that will be created in the
	user's desktop directory.</para>

	<para>title is the caption that will be used by this file.  This can be
	  localized by providing one or more title[NN] entries, where NN is
	  the setting that would be set by the user for the NN locale.</para>

      </sect2>

      <sect2>
        <title>Executables</title>

	<para>Executable programs will be executed like this:

        <informalexample>
          <programlisting>
program --desktop-dir DESKTOPDIR
         </programlisting>
        </informalexample>

	Where DESKTOPDIR is the user's desktop directory.</para>

	<para>The program can then populate the directory with any
	  information it might want.  This is used for example by the
	  g-print program (that provides priting facilities by
	  creating special desktop entries that set up the drop action
	  and various different open actions)</para>

      </sect2>
  </sect1>
</article>