/[gentoo]/xml/htdocs/proj/en/glep/glep-0016.txt
Gentoo

Diff of /xml/htdocs/proj/en/glep/glep-0016.txt

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.1 Revision 1.7
1GLEP: 16 1GLEP: 16
2Title: Gentoo Menu System 2Title: Gentoo Menu System
3Version: $Revision: 1.1 $ 3Version: $Revision: 1.7 $
4Last-Modified: $Date: 2003/10/04 13:51:00 $ 4Last-Modified: $Date: 2004/11/11 21:33:13 $
5Author: Heinrich Wendel <lanius@gentoo.org>, 5Author: Heinrich Wendel <lanius@gentoo.org>,
6Status: Draft 6Status: deferred
7Type: Standards Track 7Type: Standards Track
8Content-Type: text/x-rst 8Content-Type: text/x-rst
9Created: 09-Sep-2003 9Created: 09-Sep-2003
10Post-History: 04-Oct-2003 10Post-History: 04-Oct-2003, 11-Dec-2003, 13-Dec-2003, 4-May-2004, 11-Nov-2004
11 11
12Definitions 12Definitions
13============ 13============
14 14
15 *APP* 15 *APP*
16 A graphical application that should be listed in the menus. 16 A graphical application that should be listed in the menus.
17 *WM* 17 *WM*
18 A program containing a menu manager (i.e. a program that can display a menu, e.g. a windowmanager). 18 A program containing a menu manager (i.e. a program that can display a menu, e.g. a windowmanager).
19 *rule file*
20 A python script that describes how to build the menu for a WM.
21 19
22 20
23 21
24Abstract 22Abstract
25======== 23========
26 24
27This GLEP handles a proposal for the following two goals: 25This GLEP handles a proposal for the following two goals:
28 26
29* Create a common menu layout, which would be independent of the WM. 27* Create a common menu layout, which would be independent of the WM.
30 This point sound quite important for those people who use more than one WM. 28 This point is quite important for those people who use more than one WM.
31* Provide a common way to add applications to the menus. 29* Provide a common way to add applications to the menus.
30
31
32Status
33======
34
35Timed out (and now subsumed by the gentoo-desktop top-level project)
32 36
33 37
34 38
35Motivation 39Motivation
36========== 40==========
… …
47Rationale 51Rationale
48========= 52=========
49 53
50The idea of a common menu system is not new to the Linux world, every big 54The idea of a common menu system is not new to the Linux world, every big
51distribution (Debian, Mandrake, RedHat, Suse) has such a system. The big DE's, 55distribution (Debian, Mandrake, RedHat, Suse) has such a system. The big DE's,
52KDE and GNOME, with the help of freedesktop.org [8]_ are also trying to 56KDE and GNOME, with the help of freedesktop.org [8]_, are also trying to
53implement one standard. That will most likely happen in GNOME 2.6 and KDE 3.2 57implement one standard. That will most likely happen in GNOME 2.6 and KDE 3.2
54(Currently they are only implementing different versions of the 58(Currently they are only implementing different versions of the
55desktop-entry-spec, but interpreting it in an incompatible way). But there 59desktop-entry-spec, but interpreting it in an incompatible way). But there
56are still many other WM's around that are not going to follow these specs in 60are still many other WM's that currently don't support these specs. So we are
57the near future. So we are trying to base our work on the specifications GNOME 61trying to base our work on the specifications GNOME and KDE are going to use.
58and KDE are going to use. (These are no official standards but evolving 62(These are no official standards but evolving specifications). This has the
59specifications). This has the following advantages: 63following advantages:
60 64
61* follow specified standards 65* follow specified standards
62* i18n support 66* i18n support
63* provide the necessary flexibility and modularity 67* provide the necessary flexibility and modularity
64* integrate with small changes to our ebuildtree. 68* integrate with small changes to our ebuildtree.
65* support for per system and per user menus 69* support for per system and per user menus
66 70
67This system will be completely optional, nobody will be forced to use it!
68
69Here an short overview, how it is supposed work:
70
711. Every APP installs a .desktop file.
722. Every WM installs a rule file.
733. There is a file which specifies the menu layout.
744. A script is run and parses all rule and .desktop files and the menu
75 layout and creates the corresponding menus.
76
77We also intent to include a graphical editor for the menus, but this is not
78the primary priority.
79
80 71
81 72
82Specification 73Specification
83============= 74=============
84 75
851. What packages with an APP should do 76We are trying to follow these specifications:
86--------------------------------------------
87 77
881.1 .desktop file format 78* Desktop Entry Specification [9]_
89''''''''''''''''''''''''' 79* Menu Specification [10]_
90If you want users to be able to find your application you have to create a 80* Icon Theme Specification [11]_
91menu entry in the following format::
92 81
93 [Desktop Entry] 82There are two libraries that offer an API to these specifications:
94 Encoding=UTF-8
95 Type=Application
96 Name=KWord
97 GenericName=Word Processing
98 GenericName[it]=Textverarbeitung
99 Categories=Application;Office;Wordprocessor
100 Icon=kword
101 Exec=/usr/kde/3.1/bin/kword
102 83
103This example does not show all translations of the name and comment, but you 84* PyXDG [12]_ (written in python)
104can see the format of the file and translations from it. The Categories field 85* Desktop File Utils [13]_ (written in C)
105specifies which menu group the application should appear under. In this
106example, the entry is under System Tools.
107 86
108The file should follow the xdg desktop-entry spec 0.9.4 [9]_. The Categories 87Our goal is to patch the WM's with the help of these libraries to support the
109field is used as described in the menu-spec 0.7 [10]_. 88specifications. APP's then only have to install a .desktop entry [9]_ and
89optionally an icon and will be listed in all menus. This installation could
90easily be done by two portage commands (domenu, doicon).
110 91
111 92
1121.2 Validating the file 93Implementation / Status
113''''''''''''''''''''''''
114We will provide a tool (possibly included in repoman) which will validate
115.desktop files.
116
117
1181.3 Icon
119'''''''''
120There are two possibilities to install an icon for the application.
121
1221. You install an icon in /usr/share/pixmaps and specify the absolute path to
123 the file in the .desktop file.
1242. You install the file as part of an icon-theme [11]_ and specify the name of
125 the icon in the .desktop file. Possible icon-themes are:
126
127 * default.kde
128 * gnome
129 * gentoo
130
131The preferred format for icons is png with transparent background.
132
133
1341.4 Modifying the ebuild
135'''''''''''''''''''''''''
136To actually install this file, you have add it to the filesdir of the ebuild.
137The extension has to be .desktop. Then change the ebuild to contain a line
138similar to this: "domenu ${FILESDIR}/file.desktop".
139
140
1412. What packages with a WM should do
142---------------------------------------------
143Each WM should provide a rule file in /usr/share/menus/wms which follows a
144specific format. Documentation for this format has still to be written, You
145can find examples at [12]_.
146
147
1483. The Menu layout file
149-------------------------
150
151The format of the menu layout file will follow the xdg menu-spec 0.7 [10]_.
152
153Gentoo will provide a default menu structure. You can find the current
154proposal at [14]_.
155
156
157
1584. Customizing the menus
159------------------------
160
161Customizing of this system can be done in two ways, system-wide or user-wide.
162The locations of the files follow the xdg basedir-spec 0.6 [14]_.
163
1644.1 Changing the default menu layout
165''''''''''''''''''''''''''''''''''''
166The system menu layout is located in /etc/menu/applications.menu, it can be
167overridden by $XDG_CONFIG_HOME/applications.menu.
168
169
1704.2 Adding own WM files
171'''''''''''''''''''''''''''''''''
172The system WM files are located in $XDG_DATA_DIRS/menu/wms/, they can be
173overridden or extended by $XDG_DATA_HOME/wms/.
174
175
1764.3 Adding own menu entries
177'''''''''''''''''''''''''''
178The system .desktop files are located in $XDG_DATA_DIRS/menu/applications/,
179they can be overridden or extended by $XDG_DATA_HOME/menu/applications/.
180
181
182
183Drawbacks
184=========
185
186A concern might be that it involves a changing a lot of ebuilds (every APP
187needs to be changed). There has been a proposal for another solution that
188generates menus from the current menu structures of GNOME/KDE. This would have
189the advantage of not changing the ebuilds, but the disadvantage of not being
190very flexible. A menu layout file or per system/users menus would not be
191possibly. It seems more like a quick and dirty solution. Consider that we
192don't have to provide massive file-updates, global lists coherent with our
193tree, but each capable and installed package requires a small change that goes
194back and forwards with versions without overhead for version bumps.
195
196
197
198Backwards Compatibility
199======================= 94=======================
200 95
201People who want to use the new system have to recompile all packages that use 96This GLEP exists for a long time now, still it is not accepted. I will outline
202the "gentoo-menu" USE flag. This could be easily done by a tool that will parse 97the current status:
203/var/db/pkg and for all ebuilds find corresponding updates with menu info.
204 98
205Since nobody is forced to use this system, there are no other backward 99* KDE 3.2 (x86) supports this specification
206compatibility issues, you just have to disable the "gentoo-menu" USE-Flag and 100* GNOME 2.6 (~x86) support this specification
207you'll get the vanilla situation. 101* domenu[12_] has to be included in portage to be used by the ebuilds to
102 install a desktop entry
103* Somebody needs to write patches for the other WM's:
208 104
105We should focus on adding support to the following WM's first:
209 106
107* xfce, blackblox / fluxbox / openbox / waimea / kahakai, icewm
108* fvwm, windowmaker, enlightment, afterstep
210 109
211Reference Implementation 110The following are not so important, but support some kind of applications
212======================== 111menu:
213 112
214The reference implementation is nearly finished, it's written in Python, you 113* aewm / aewm++ / evilwm / windowlab / oroborus, amiwm, ctwm, flwm
215can find it here [15]_ [16]_. It contains a sample menu layout 114* golem, larswm, pekwm, plwm, pwm, qvwm, selectwm, treewm, trwm
216(/etc/menu/applications.menu), the domenu script, the update-menus script and 115* vtwm, xpde
217the gentoo icon theme.
218
219Domenu has to be included in Portage, it will install new menu entries in
220/usr/share/menu/applications and run the update-menus script afterwards.
221
222Update-menus parses the menu layout file, the .desktop files and the rule
223files and then creates the menus. If run as user it will create menus only for
224that user, if run as root it will create system wide menus.
225
226 116
227 117
228Credits 118Credits
229======= 119=======
230 120
231Based on suggestions from former discussions on -dev and the Debian 121Based on suggestions from former discussions on the gentoo bugzilla,
232menu-system documentation [17]_. 122mailinglists and forums.
233 123
234 124
235 125
236References 126References
237========== 127==========
… …
245.. [7] http://bugs.gentoo.org/show_bug.cgi?id=25756 135.. [7] http://bugs.gentoo.org/show_bug.cgi?id=25756
246.. [8] http://www.freedesktop.org 136.. [8] http://www.freedesktop.org
247.. [9] Desktop Entry Specification 137.. [9] Desktop Entry Specification
248 [http://www.freedesktop.org/standards/desktop-entry-spec/0.9.4/] 138 [http://www.freedesktop.org/standards/desktop-entry-spec/0.9.4/]
249.. [10] Menu Specification 139.. [10] Menu Specification
250 [http://www.freedesktop.org/standards/menu-spec/0.7/] 140 [http://www.freedesktop.org/standards/menu-spec/0.8/]
251.. [11] Icon Theme Specification 141.. [11] Icon Theme Specification
252 [http://www.freedesktop.org/standards/icon-theme-spec/0.7/] 142 [http://www.freedesktop.org/standards/icon-theme-spec/0.7/]
253.. [12] Example rule files:
254 [http://www.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-menu/examples/?cvsroot=gentoo-src]
255.. [13] Reference menu layout
256 [http://www.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-menu/etc/applications.menu?cvsroot=gentoo-src]
257.. [14] Basedir Specification
258 [http://www.freedesktop.org/standards/basedir-spec/0.6/]
259.. [15] PyXDG 143.. [12] PyXDG
260 [http://cvs.cojobo.net/cgi-bin/viewcvs.cgi/pyxdg/] 144 [http://www.freedesktop.org/software/pyxdg]
261.. [16] Gentoo-Menu 145.. [13] Desktop File Utils
262 [http://www.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-menu/?cvsroot=gentoo-src] 146 [http://www.freedesktop.org/software/desktop-file-utils]
263.. [17] Debian Menu System documentation 147.. [14] domenu
264 [http://www.debian.org/doc/packaging-manuals/menu.html/] 148 [http://bugs.gentoo.org/show_bug.cgi?id=25756]
265
266 149
267 150
268Copyright 151Copyright
269========= 152=========
270 153
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.7
  ViewVC Help
Powered by ViewVC 1.1.20