# Document  $Id: README,v 1.3 2006/05/02 13:19:55 dleidert Exp $
# Summary   Important infos about the chemical-mime-data project.

0. Content
==========

  0. Content
  1. About chemical-mime-data
  2. Copyright and License
  3. Introduction and configuration
  4. Status information
  5. Installation
  6. Associate your chemical application with a chemical MIME type
  7. Sources and Footnotes


1. About chemical-mime-data
===========================

The chemical-mime-data package is a collection of data files which tries give
support for various chemical MIME types (chemical/x-*) on Linux/UNIX desktops,
such as KDE [1] and GNOME [2]. Chemical MIME's [3] have been proposed in 1995,
though it seems they have never been registered with IANA [4]. Most data is
taken from the list of Henry Rzepa [3], but this compilation is written by
Egon Willighagen and Daniel Leidert (see the AUTHORS file for a list of who
has contributed to this project).



2. Copyright and License
========================

Copyright (C) 2004-2006 Egon Willighagen <e.willighagen@science.ru.nl>.
Copyright (C) 2004-2006 Daniel Leidert <daniel.leidert@wgdd.de>.

  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Lesser General Public
  License as published by the Free Software Foundation; either
  version 2.1 of the License, or (at your option) any later version.
  
  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  Lesser General Public License for more details.
  
  You should have received a copy of the GNU Lesser General Public
  License along with this library; if not, write to the Free Software
  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA
					
Please see the file COPYING or visit http://www.gnu.org to obtain a copy of
the GNU Lesser General Public License.

See the files AUTHORS and THANKS for a list of who has contributed to this
project.



3. Introduction and configuration
=================================

Newer desktop systems need to know the MIME type to associate applications
with it. Chemical application writers will use this feature as any other
application developer too.

Newer GNOME (also ROX) desktops use the Shared MIME-info Database [5] to
determine MIMEs. We provide a file chemical-mime-data.xml which has be installed
into the 'packages' sub-directory. It follows the freedesktop.org
specification [6]. After running 'update-mime-database' the chemical MIME
types are registered. To associate an icon for a MIME type, the icon has to
installed into the hicolor-theme [7] and named, e.g.:

	gnome-mime-chemical-x-xyz.png
	gnome-mime-chemical-x-cml.png
	
The syntax is easy:

  gnome-<icon-type>-<mime-media-type>-</mime-sub-type>.png

If the icon naming scheme follows this direction, the MIME type is
automatically associated with the icon. This should work for all systems and
applications mentioned under >Status Information<. You will need the
shared-mime-info package for your distribution [8]

Older GNOME desktops use the mime-info path with .keys and .mime files to
determine MIME stuff. Icons are installed into the pixmaps directory. GNOME 2.6

KDE desktops use the mimelnk path with .desktop files to determine MIME
stuff. The .desktop format is developed by the freedesktop.org
project [5] and specified on [9]. These files can be validated with the
desktop-file-utils tool 'desktop-file-validate'.



4. Status information
=====================

If you want to know more about status, then have a look at [6]. There you will
find the following status notes about the shared MIME info database:

    * ROX has used the system since ROX-Filer 1.3.3 (July 2002).
    * GTK has support since version 2.4 (Mar 2004).
    * GNOME uses the system since version 2.8 (Sep 2004).
    * XFCE uses the system since version 4.2.0 (Jan 2005).
    * KDE is planning to support it for their next major release.
      (Note from authors: This is hopefully KDE 3.4.)



5. Installation
===============

To build and install chemical-mime-data from CVS:

    1) install autoconf, automake, intltool/gettext, xsltproc
    2) get the CVS sources
    3) run autogen.sh (./autogen.sh)
    4) see next part ...

To build and install chemical-mime-data from release tarballs:

    1) Get the required applications:
       - intltool/gettext, pkg-config
       - RSVG2 or imagemagick
       - xsltproc
       - gnome-mime-data, shared-mime-info
    
    2) Configure and compile:
       (see ./configure --help for possible configure options)
         $ ./configure [options-you-like-most-here]
         $ make
       
    3) Install everything:
         $ su
         # make install
       
($: means user-shell, #: means root-shell)

The file INSTALL contains some generic installation instructions.



6. Associate your chemical application with a chemical MIME type
================================================================

To associate the chemical MIME types with a special application, you need to
do the following:

	* KDE: [10], newer freedesktop.org support in $datadir/applications/kde
		
	* GNOME (all versions): [11]

The desktop-file-utils [12] package contains command-line applications to
validate, manipulate and install .desktop files in $datadir/applications(/kde)
and to update the database ($datadir/applications/mimeinfo.cache), which holds
information about applications and associated MIME types.



7. Sources and Footnotes
========================

[1] http://www.kde.org
[2] http://www.gnome.org
[3] http://www.ch.ic.ac.uk/chemime/
[4] http://www.iana.org/assignments/media-types/
[5] http://www.freedesktop.org/
[6] http://www.freedesktop.org/wiki/Standards_2fshared_2dmime_2dinfo_2dspec
[7] http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html
[8] http://freedesktop.org/Software/shared-mime-info
[9] http://standards.freedesktop.org/desktop-entry-spec/latest/
[10] http://www.kde.org/areas/sysadmin/fsh.php
[11] http://www.gnome.org/learn/ (GNOME 2 Desktop System Administrator's Guide,
     chapter 4 in your GNOME version)
[12] http://freedesktop.org/Software/desktop-file-utils

# UTF-8
