Adding 02-Fix-potential-access-violation.patch from upstream (Closes: #862570).
[debian/menu-cache.git] / README
1 Libmenu-cache is a library creating and utilizing caches to speed up
2 the manipulation for freedesktop.org defined application menus.
3 It can be used as a replacement of libgnome-menu of gnome-menus.
4
5 Advantages:
6 1. Shorten time for loading menu entries.
7 2. Ease of use. (API is very similar to that of libgnome-menu)
8 3. Lightweight runtime library. (Parsing of the menu definition files 
9    are done by menu-cache-gen when the menus are really changed.)
10 4. Less unnecessary and complicated file monitoring.
11 5. Heavily reduced disk I/O.
12
13 Installing:
14
15 Since version 0.7.0 the Libmenu-cache requires Libfm-extra for the
16 menu-cache-gen menu cache generation binary. Since Libfm depends on
17 Libmenu-cache, there is some hint for bootstrapers how to build those
18 libraries together: you need create Libfm-extra first, you can easily
19 do this by passing '--with-extra-only' option to configure script and
20 installing Libfm-extra. Then you can succesfully build Libmenu-cache
21 and therefore build full version of Libfm.
22
23 Diagnostics:
24
25 Libmenu-cache uses cache generation in "fail-proof" mode when it will
26 ignore improper tags in XML menu file but fail only if that menu file
27 doesn't exist at all, or has invalid XML structure, or has no root menu
28 with name 'Applications'. If you want to explore how it is generated
29 then you can start menu-cache-gen manually in verbose mode, for example:
30
31 G_MESSAGES_DEBUG=all \
32   /usr/lib/menu-cache/menu-cache-gen -v -i applications.menu -o /dev/null
33
34 so you can see all the processing of your XML file and it will fail on
35 any broken tag or at least show you a warning and you can inspect that
36 log.
37
38 Spec:
39
40 Cached menus are localized and stored in ~/.cache/menus/file_name.
41 file_name is a md5 hash of the name of the original menu +
42                                        some environment variable +
43                                        locale name.
44
45 Since most data in a menu are plain text (names, description comments,
46 icon names,...etc.), the cached file is in plain text rather than binary
47 to prevent byte order problems.
48
49 Format of the cached menu file, line by line.
50 (Spaces before the lines are for easier demostration of hierarchy.
51  There are no spaces in the real cached file.
52  Fields marked with [**] added only in the file format 1.2):
53
54 version number (major.minor)
55 menu name>
56 number of files to monitor
57 list of files/dirs which require monitor (prefix D or F indicate whether it
58                                           is a dir or file)
59 list of DE names used in this menu other than the known DEs (LXDE, GNOME,
60                                                              XFCE, KDE, ROX),
61 seperated by ;
62 +id of top menu dir (+ means dir entry, and - means an application entry)
63   title
64   comment
65   icon name
66   menu directory file basename
67   dir in which menu directory file locates (use this number as index to get
68                                             the string from array of preceding
69                                             list of monitored files)
70   [**] bitmask flags: (--)|(--)|(not displayed)
71     -application desktop id (NOTE: desktop id is not necessarily the basename
72                              of desktop file)
73      title
74      comment
75      icon name
76      app desktop file basename, empty means the same as desktop id.
77      dir in which the desktop file localtes (use this number as index to get
78                                              the string from array of
79                                              preceding list of monitored files)
80      generic name
81      exec command line
82      bitmask flags: (use terminal)|(use startup notification)|(not displayed)
83      show_in_flags: bitwise or of masks for various DEs.
84      [**] executable name to test for availability
85      [**] working dir for exec
86      [**] categories: list divided by semicolon
87      [**] keywords: list divided by comma
88     +sub dir id
89      title
90      comment
91      icon name
92      ...