/[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.2
1GLEP: 16 1GLEP: 16
2Title: Gentoo Menu System 2Title: Gentoo Menu System
3Version: $Revision: 1.1 $ 3Version: $Revision: 1.2 $
4Last-Modified: $Date: 2003/10/04 13:51:00 $ 4Last-Modified: $Date: 2003/12/11 21:19:31 $
5Author: Heinrich Wendel <lanius@gentoo.org>, 5Author: Heinrich Wendel <lanius@gentoo.org>,
6Status: Draft 6Status: Draft
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-Oct-2003
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.
32 30
33 31
34 32
35Motivation 33Motivation
47Rationale 45Rationale
48========= 46=========
49 47
50The idea of a common menu system is not new to the Linux world, every big 48The 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, 49distribution (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 50KDE 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 51implement 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 52(Currently they are only implementing different versions of the
55desktop-entry-spec, but interpreting it in an incompatible way). But there 53desktop-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 54are 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 55trying 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 56(These are no official standards but evolving specifications). This has the
59specifications). This has the following advantages: 57following advantages:
60 58
61* follow specified standards 59* follow specified standards
62* i18n support 60* i18n support
63* provide the necessary flexibility and modularity 61* provide the necessary flexibility and modularity
64* integrate with small changes to our ebuildtree. 62* integrate with small changes to our ebuildtree.
65* support for per system and per user menus 63* support for per system and per user menus
66 64
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 65
81 66
82Specification 67Specification
83============= 68=============
84 69
851. What packages with an APP should do 70We are trying to follow these specifications:
86--------------------------------------------
87 71
881.1 .desktop file format 72* Desktop Entry Specification [9]_
89''''''''''''''''''''''''' 73* Menu Specification [10]_
90If you want users to be able to find your application you have to create a 74* Icon Theme Specification [11]_
91menu entry in the following format::
92 75
93 [Desktop Entry] 76There 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 77
103This example does not show all translations of the name and comment, but you 78* PyXDG [12]_ (written in python)
104can see the format of the file and translations from it. The Categories field 79* 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 80
108The file should follow the xdg desktop-entry spec 0.9.4 [9]_. The Categories 81Our 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]_. 82specifications. APP's then only have to install a .desktop entry [9]_ and
110 83optionally an icon and will be listened in all menus. This installation could
111 84easily be done by two portage commands (domenu, doicon). Additionaly we
1121.2 Validating the file 85should provide a reference menu layout and icon theme and add a function to
113'''''''''''''''''''''''' 86repoman to validate .desktop files.
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=======================
200
201People who want to use the new system have to recompile all packages that use
202the "gentoo-menu" USE flag. This could be easily done by a tool that will parse
203/var/db/pkg and for all ebuilds find corresponding updates with menu info.
204
205Since nobody is forced to use this system, there are no other backward
206compatibility issues, you just have to disable the "gentoo-menu" USE-Flag and
207you'll get the vanilla situation.
208
209
210
211Reference Implementation
212========================
213
214The reference implementation is nearly finished, it's written in Python, you
215can find it here [15]_ [16]_. It contains a sample menu layout
216(/etc/menu/applications.menu), the domenu script, the update-menus script and
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 87
226 88
227 89
228Credits 90Credits
229======= 91=======
230 92
231Based on suggestions from former discussions on -dev and the Debian 93Based on suggestions from former discussions on the gentoo bugzilla,
232menu-system documentation [17]_. 94mailinglists and forums.
233 95
234 96
235 97
236References 98References
237========== 99==========
245.. [7] http://bugs.gentoo.org/show_bug.cgi?id=25756 107.. [7] http://bugs.gentoo.org/show_bug.cgi?id=25756
246.. [8] http://www.freedesktop.org 108.. [8] http://www.freedesktop.org
247.. [9] Desktop Entry Specification 109.. [9] Desktop Entry Specification
248 [http://www.freedesktop.org/standards/desktop-entry-spec/0.9.4/] 110 [http://www.freedesktop.org/standards/desktop-entry-spec/0.9.4/]
249.. [10] Menu Specification 111.. [10] Menu Specification
250 [http://www.freedesktop.org/standards/menu-spec/0.7/] 112 [http://www.freedesktop.org/standards/menu-spec/0.8/]
251.. [11] Icon Theme Specification 113.. [11] Icon Theme Specification
252 [http://www.freedesktop.org/standards/icon-theme-spec/0.7/] 114 [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 115.. [12] PyXDG
260 [http://cvs.cojobo.net/cgi-bin/viewcvs.cgi/pyxdg/] 116 [http://www.freedesktop.org/software/pyxg]
261.. [16] Gentoo-Menu 117.. [13] Desktop File Utils
262 [http://www.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-menu/?cvsroot=gentoo-src] 118 [http://www.freedesktop.org/software/desktop-file-utils]
263.. [17] Debian Menu System documentation
264 [http://www.debian.org/doc/packaging-manuals/menu.html/]
265 119
266 120
267 121
268Copyright 122Copyright
269========= 123=========

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.2

  ViewVC Help
Powered by ViewVC 1.1.20