IMPORTANT: VFolder-based KDE menus

[Waldo Bastian]

IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT
---------------------------------------------------------------------
If you release an application from CVS HEAD for KDE 3.1 or older, make 
sure that any .desktop files that are supposed to appear in the KDE 
menu are being installed somewhere under $(kde_appsdir) and not under 
the newly introduced $(xdg_appsdir). That might mean that you have to 
revert the commit where I changed it to use $(xdg_appsdir). 
You can also drop me a mail and I will revert it for you.

You do not need to revert any changes to the .desktop files themselves, 
only the Makefile.am change is important.
---------------------------------------------------------------------
IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT

(End of the important part)

Introduction of VFolder-based KDE menus
=======================================

I'm happy to announce the introduction of the VFolder based KDE menu in CVS 
HEAD. For a long time the KDE menu structure was determined by the directory 
structure under the $KDEDIR/share/applnk directory. The VFolder based KDE 
menu introduces a new concept: .desktop files now describe themselves by 
including a number of categories that are applicable to the application, the 
KDE menu is then build by filling sub-menus with .desktop entries whose 
categories meet certain criteria.

A full description/specification of this process can be found on
http://www.freedesktop.org/standards/menu/draft/menu-spec/menu-spec.html

Advantages
==========

The advantages of this new concept are the following:
* Uses less directories which makes it easier to autodetect changes.
* Makes it easy to replace the KDE menu with a complete custom menu.
* Allows for an easier menu-editing implementation.

Another important aspect is that this spec will be implemented by GNOME and 
hopefully others as well. This will bring the additional benefits of:
* Single method for ISVs/independent developers to install their application
in start menu, regardless of desktop environment.
* (User) changes to menu-structure can be preserved when switching desktop 
environments.
* Allows distributors to define a single menu-structure regardless of
desktop environment.

Backwards compatibility
=======================

Greate care has been given to preserve full backwards compatibility with 
existing installations.

Things you need to know
=======================

As KDE developer you need to know a few things:

- Your .desktop file should contain a "Categories=" entry describing you app. 
This entry should contain at least "Qt" and "KDE". For a list of standard 
categories see the specification on freedesktop.org. For KDE we will most 
likely add a few KDE specific categories. One of those categories is the
X-KDE-More category, which indicates that the application is not of primary 
importance. If you are unable to find appropriate categories for your 
application, please post to this list.

- If your application is going to be released for use with KDE 3.2 or newer 
only, it is adviced that you install your menu .desktop file to $xdg_appsdir 
instead of $kde_appsdir/Some/Submenu. Typically it is enough to add 
xdg_apps_DATA = yourdesktopfile.desktop

You mustn't do this if your application is supposed to be used with KDE 3.1 
or older, because these versions of KDE will not look in $xdg_appsdir. 

Make sure that your Makefile.am doesn't redefine "datadir". $xdg_appsdir is
expressed in terms of $datadir, redefining $datadir will break it.

Things you need to know II
==========================

- KMenuEdit still needs updating. It will most likely not work now.
- Make errors involving xdg_apps_DATA or xdg_appsdir can be resolved by 
updating your admin directory and rerunning make -f Makefile.cvs; ./configure
- Please report any problems that you experience to me. There are without 
doubt many bugs left that still need fixing.

Cheers,
Waldo
-- 
bastian at kde.org -=|[ SuSE, The Linux Desktop Experts ]|=- bastian at suse.com