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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (show annotations) (download)
Sat Oct 4 13:51:00 2003 UTC (10 years, 10 months ago) by liquidx
Branch: MAIN
File MIME type: text/plain
new glep for menu systems

1 GLEP: 16
2 Title: Gentoo Menu System
3 Version: $Revision: 1.0 $
4 Last-Modified: $Date: 2003/09/27 22:00:00 $
5 Author: Heinrich Wendel <lanius@gentoo.org>,
6 Status: Draft
7 Type: Standards Track
8 Content-Type: text/x-rst
9 Created: 09-Sep-2003
10 Post-History: 04-Oct-2003
11
12 Definitions
13 ============
14
15 *APP*
16 A graphical application that should be listed in the menus.
17 *WM*
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
22
23
24 Abstract
25 ========
26
27 This GLEP handles a proposal for the following two goals:
28
29 * 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.
31 * Provide a common way to add applications to the menus.
32
33
34
35 Motivation
36 ==========
37
38 GNOME, KDE, Fluxbox, to name only a few, have all their own ways of handling
39 menus. There have been several requests [1]_ [2]_ [3]_ [4]_ [5]_ [6]_ from
40 users to streamline these menus. Furthermore there are several bug reports
41 about applications not having a menu entry [7]_, but since there is not
42 standard way to create such an entry, they are just sitting around in
43 bugzilla.
44
45
46
47 Rationale
48 =========
49
50 The idea of a common menu system is not new to the Linux world, every big
51 distribution (Debian, Mandrake, RedHat, Suse) has such a system. The big DE's,
52 KDE and GNOME, with the help of freedesktop.org [8]_ are also trying to
53 implement 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
55 desktop-entry-spec, but interpreting it in an incompatible way). But there
56 are still many other WM's around that are not going to follow these specs in
57 the near future. So we are trying to base our work on the specifications GNOME
58 and KDE are going to use. (These are no official standards but evolving
59 specifications). This has the following advantages:
60
61 * follow specified standards
62 * i18n support
63 * provide the necessary flexibility and modularity
64 * integrate with small changes to our ebuildtree.
65 * support for per system and per user menus
66
67 This system will be completely optional, nobody will be forced to use it!
68
69 Here an short overview, how it is supposed work:
70
71 1. Every APP installs a .desktop file.
72 2. Every WM installs a rule file.
73 3. There is a file which specifies the menu layout.
74 4. A script is run and parses all rule and .desktop files and the menu
75 layout and creates the corresponding menus.
76
77 We also intent to include a graphical editor for the menus, but this is not
78 the primary priority.
79
80
81
82 Specification
83 =============
84
85 1. What packages with an APP should do
86 --------------------------------------------
87
88 1.1 .desktop file format
89 '''''''''''''''''''''''''
90 If you want users to be able to find your application you have to create a
91 menu entry in the following format::
92
93 [Desktop Entry]
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
103 This example does not show all translations of the name and comment, but you
104 can see the format of the file and translations from it. The Categories field
105 specifies which menu group the application should appear under. In this
106 example, the entry is under System Tools.
107
108 The file should follow the xdg desktop-entry spec 0.9.4 [9]_. The Categories
109 field is used as described in the menu-spec 0.7 [10]_.
110
111
112 1.2 Validating the file
113 ''''''''''''''''''''''''
114 We will provide a tool (possibly included in repoman) which will validate
115 .desktop files.
116
117
118 1.3 Icon
119 '''''''''
120 There are two possibilities to install an icon for the application.
121
122 1. You install an icon in /usr/share/pixmaps and specify the absolute path to
123 the file in the .desktop file.
124 2. 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
131 The preferred format for icons is png with transparent background.
132
133
134 1.4 Modifying the ebuild
135 '''''''''''''''''''''''''
136 To actually install this file, you have add it to the filesdir of the ebuild.
137 The extension has to be .desktop. Then change the ebuild to contain a line
138 similar to this: "domenu ${FILESDIR}/file.desktop".
139
140
141 2. What packages with a WM should do
142 ---------------------------------------------
143 Each WM should provide a rule file in /usr/share/menus/wms which follows a
144 specific format. Documentation for this format has still to be written, You
145 can find examples at [12]_.
146
147
148 3. The Menu layout file
149 -------------------------
150
151 The format of the menu layout file will follow the xdg menu-spec 0.7 [10]_.
152
153 Gentoo will provide a default menu structure. You can find the current
154 proposal at [14]_.
155
156
157
158 4. Customizing the menus
159 ------------------------
160
161 Customizing of this system can be done in two ways, system-wide or user-wide.
162 The locations of the files follow the xdg basedir-spec 0.6 [14]_.
163
164 4.1 Changing the default menu layout
165 ''''''''''''''''''''''''''''''''''''
166 The system menu layout is located in /etc/menu/applications.menu, it can be
167 overridden by $XDG_CONFIG_HOME/applications.menu.
168
169
170 4.2 Adding own WM files
171 '''''''''''''''''''''''''''''''''
172 The system WM files are located in $XDG_DATA_DIRS/menu/wms/, they can be
173 overridden or extended by $XDG_DATA_HOME/wms/.
174
175
176 4.3 Adding own menu entries
177 '''''''''''''''''''''''''''
178 The system .desktop files are located in $XDG_DATA_DIRS/menu/applications/,
179 they can be overridden or extended by $XDG_DATA_HOME/menu/applications/.
180
181
182
183 Drawbacks
184 =========
185
186 A concern might be that it involves a changing a lot of ebuilds (every APP
187 needs to be changed). There has been a proposal for another solution that
188 generates menus from the current menu structures of GNOME/KDE. This would have
189 the advantage of not changing the ebuilds, but the disadvantage of not being
190 very flexible. A menu layout file or per system/users menus would not be
191 possibly. It seems more like a quick and dirty solution. Consider that we
192 don't have to provide massive file-updates, global lists coherent with our
193 tree, but each capable and installed package requires a small change that goes
194 back and forwards with versions without overhead for version bumps.
195
196
197
198 Backwards Compatibility
199 =======================
200
201 People who want to use the new system have to recompile all packages that use
202 the "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
205 Since nobody is forced to use this system, there are no other backward
206 compatibility issues, you just have to disable the "gentoo-menu" USE-Flag and
207 you'll get the vanilla situation.
208
209
210
211 Reference Implementation
212 ========================
213
214 The reference implementation is nearly finished, it's written in Python, you
215 can find it here [15]_ [16]_. It contains a sample menu layout
216 (/etc/menu/applications.menu), the domenu script, the update-menus script and
217 the gentoo icon theme.
218
219 Domenu 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
222 Update-menus parses the menu layout file, the .desktop files and the rule
223 files and then creates the menus. If run as user it will create menus only for
224 that user, if run as root it will create system wide menus.
225
226
227
228 Credits
229 =======
230
231 Based on suggestions from former discussions on -dev and the Debian
232 menu-system documentation [17]_.
233
234
235
236 References
237 ==========
238
239 .. [1] http://bugs.gentoo.org/show_bug.cgi?id=5510
240 .. [2] http://bugs.gentoo.org/show_bug.cgi?id=10429
241 .. [3] http://bugs.gentoo.org/show_bug.cgi?id=4884
242 .. [4] http://bugs.gentoo.org/show_bug.cgi?id=25797
243 .. [5] http://forums.gentoo.org/viewtopic.php?t=66754
244 .. [6] http://forums.gentoo.org/viewtopic.php?p=263106#263106
245 .. [7] http://bugs.gentoo.org/show_bug.cgi?id=25756
246 .. [8] http://www.freedesktop.org
247 .. [9] Desktop Entry Specification
248 [http://www.freedesktop.org/standards/desktop-entry-spec/0.9.4/]
249 .. [10] Menu Specification
250 [http://www.freedesktop.org/standards/menu-spec/0.7/]
251 .. [11] Icon Theme Specification
252 [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
260 [http://cvs.cojobo.net/cgi-bin/viewcvs.cgi/pyxdg/]
261 .. [16] Gentoo-Menu
262 [http://www.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-menu/?cvsroot=gentoo-src]
263 .. [17] Debian Menu System documentation
264 [http://www.debian.org/doc/packaging-manuals/menu.html/]
265
266
267
268 Copyright
269 =========
270
271 This document has been placed in the public domain.

  ViewVC Help
Powered by ViewVC 1.1.20