Debian Codegraph @

upstream/debian-unstable/man1/icewm-menu-fdo.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "ICEWM-MENU-FDO 1"
58 .TH ICEWM-MENU-FDO 1 2026-01-18 "icewm\ 4.0.0" "User Commands"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SS NAME
64 .IX Subsection "NAME"
65 .Vb 1
66 \& icewm\-menu\-fdo \- menu generator for .desktop files
67 .Ve
68 .SS SYNOPSIS
69 .IX Subsection "SYNOPSIS"
70 \&\fBicewm-menu-fdo\fR [\fIOPTIONS\fR] [\fIFILENAME\fR]
71 .SS DESCRIPTION
72 .IX Subsection "DESCRIPTION"
73 \&\fBicewm-menu-fdo\fR generates a menu for the \fBIceWM\fR window manager
74 from XDG menu descriptors (aka FreeDesktop.Org \fI.desktop\fR files).
75 By including this in the \fBicewm\-menu\fR\|(1), the system applications
76 become available in the icewm start menu.
77 .SS ARGUMENTS
78 .IX Subsection "ARGUMENTS"
79 .IP [\fIFILENAME\fR] 4
80 .IX Item "[FILENAME]"
81 The optional \fIFILENAME\fR argument is the location of a \fI.desktop\fR file.
82 When given, \fBicewm-menu-fdo\fR launches the application using the \f(CW\*(C`Exec\*(C'\fR
83 line from the desktop file.
84 .SS OPTIONS
85 .IX Subsection "OPTIONS"
86 .IP "\fB\-g\fR, \fB\-\-generic\fR" 4
87 .IX Item "-g, --generic"
88 Include the generic name in parentheses in the title of \fBprog\fR entries.
89 .IP \fB\-\-seps\fR 4
90 .IX Item "--seps"
91 Print a leading and a trailing separator.
92 .IP \fB\-\-sep\-before\fR 4
93 .IX Item "--sep-before"
94 Print a leading separator.
95 .IP \fB\-\-sep\-after\fR 4
96 .IX Item "--sep-after"
97 Print a trailing separator.
98 .IP \fB\-\-no\-sub\-cats\fR 4
99 .IX Item "--no-sub-cats"
100 Don't nest subcategories in submenus. The correctness of the
101 pigeonholing depends on correct application description which shall
102 always specify a main category. Incorrectly tagged descriptions will be
103 sorted into the \f(CW\*(C`Other\*(C'\fR menu.
104 .IP "\fB\-o\fR, \fB\-\-output=FILE\fR" 4
105 .IX Item "-o, --output=FILE"
106 Write the output to \fIFILE\fR.
107 .IP "\fB\-t\fR, \fB\-\-terminal=NAME\fR" 4
108 .IX Item "-t, --terminal=NAME"
109 Use \fINAME\fR to start a terminal emulator that supports the '\-e' option.
110 .IP "\fB\-s\fR, \fB\-\-no\-lone\-app\fR" 4
111 .IX Item "-s, --no-lone-app"
112 Attempt to detect a single application with no other content in lower
113 submenus and move this one to the parent submenu. This also detects
114 menus with just one submenu inside, attempting to move it's application
115 items to the parent menu where possible.
116 .IP "\fB\-S\fR, \fB\-\-no\-lone\-hint\fR" 4
117 .IX Item "-S, --no-lone-hint"
118 Decorate app entries moved by the \fB\-s\fR option with a hint about the
119 original menu where it would be displayed otherwise. Implies \fB\-s\fR.
120 .IP "\fB\-d TIMEOUT\fR, \fB\-\-deadline\-apps=TIMEOUT\fR" 4
121 .IX Item "-d TIMEOUT, --deadline-apps=TIMEOUT"
122 Specifies a certain timeout value in milliseconds, so that the reading
123 of *.desktop files (for applications) is aborted by that time (or soon
124 after). This can help to avoid extended blocking of the caller.
125 Also see \fB\-D\fR for the subsequent operation.
126 .IP "\fB\-D TIMEOUT\fR, \fB\-\-deadline\-all=TIMEOUT\fR" 4
127 .IX Item "-D TIMEOUT, --deadline-all=TIMEOUT"
128 Specifies a total timeout in milliseconds after which the application
129 has to terminate, regardless of the final menu construction and
130 decoration reading (applied after *.desktop file reading) was finished
131 or not. This would cause a printing of menu contents which were
132 calculated so far, therefore the timeout should be set a certain time
133 before the actual hard deadline by which the program should be
134 terminated. The output may lack translations and icons.
135 .IP "\fB\-l LANGUAGE\fR, \fB\-\-lang=LANGUAGE\fR" 4
136 .IX Item "-l LANGUAGE, --lang=LANGUAGE"
137 Instead of the environment variable \f(CW\*(C`LANG\*(C'\fR use LANGUAGE for the locale.
138 .IP "\fB\-L MAX\fR, \fB\-\-limit\-max\-len=MAX\fR" 4
139 .IX Item "-L MAX, --limit-max-len=MAX"
140 Cut the calculated program titles (after translation and adding
141 hints, see \f(CW\*(C`\-C\*(C'\fR and \f(CW\*(C`\-g\*(C'\fR) at \f(CW\*(C`MAX\*(C'\fR characters, followed by an
142 ellipsis. This can help to restrict the width of the menus in cases
143 where some entry length might get out of hand.
144 .IP \fB\-\-flat\fR 4
145 .IX Item "--flat"
146 Display apps from all categories in one level with the title containing
147 the category information as prefix.
148 .IP "\fB\-F sep\fR, \fB\-\-flat\-sep=sep\fR" 4
149 .IX Item "-F sep, --flat-sep=sep"
150 When used with \f(CW\*(C`\-\-flat\*(C'\fR, the specified character sequence is used as
151 separator between the section titles.
152 .IP "\fB\-m filter\fR, \fB\-\-match=filter\fR" 4
153 .IX Item "-m filter, --match=filter"
154 Specifies a filter to show only apps that contain this as substring
155 within their title.
156 .IP "\fB\-M filter\fR, \fB\-\-imatch=filter\fR" 4
157 .IX Item "-M filter, --imatch=filter"
158 Like \f(CW\*(C`\-\-match\*(C'\fR but applied with any letter case. Might deliver
159 incorrect results with some locale settings.
160 .IP \fB\-\-match\-sec\fR 4
161 .IX Item "--match-sec"
162 Apply the filter from \f(CW\*(C`\-\-match\*(C'\fR or \f(CW\*(C`\-\-imatch\*(C'\fR to both, apps and
163 section titles.
164 .IP \fB\-\-match\-osec\fR 4
165 .IX Item "--match-osec"
166 Apply the filter from \f(CW\*(C`\-\-match\*(C'\fR or \f(CW\*(C`\-\-imatch\*(C'\fR to only to section titles.
167 .IP "\fB\-h\fR, \fB\-\-help\fR" 4
168 .IX Item "-h, --help"
169 Print a brief usage statement to \fIstdout\fR and exit.
170 .IP "\fB\-V\fR, \fB\-\-version\fR" 4
171 .IX Item "-V, --version"
172 Print the program version to \fIstdout\fR and exit.
173 .IP "\fB\-C\fR, \fB\-\-copying\fR" 4
174 .IX Item "-C, --copying"
175 Print copying permissions to \fIstdout\fR for the program and exit.
176 .SS USAGE
177 .IX Subsection "USAGE"
178 This utility is not normally used directly. It is used as the
179 executable in a \fBmenuprog\fR entry in a \fBicewm\-menu\fR\|(5).
180 .SS EXAMPLES
181 .IX Subsection "EXAMPLES"
182 The following line in a \fBicewm\-menu\fR\|(5) file will dynamically generate
183 a comprehensive set of menus for easy access to \fI.desktop\fR files, added
184 in a submenu called \f(CW\*(C`Desktop Apps\*(C'\fR.
185 .PP
186 .Vb 1
187 \& menuprog "Desktop Apps" folder icewm\-menu\-fdo
188 .Ve
189 .PP
190 It can also be embedded directly into the loading menu like in the
191 following example. There could be a separator line added before or after
192 (or both) in case where the program could generate useful content.
193 .PP
194 .Vb 1
195 \& includeprog icewm\-menu\-fdo \-\-seps
196 .Ve
197 .SS ENVIRONMENT
198 .IX Subsection "ENVIRONMENT"
199 \&\fBXDG_DATA_HOME\fR or \fBXDG_DATA_DIRS\fR are considered as suggested by XDG
200 Base Directory Specification.
201 .PP
202 \&\fBTERMINAL\fR may define a terminal emulator that supports the '\-e'
203 option. The option is ignored if the specified command could not be
204 found and a default is used instead.
205 .SS "CONFORMING TO"
206 .IX Subsection "CONFORMING TO"
207 \&\fBicewm-menu-fdo\fR complies roughly to the XDG \fI.desktop\fR file and menu
208 specification, see "Desktop Entry Specification" (Date: 2020\-04\-27,
209 Version: Version 1.5) and "Desktop Menu Specification" (Date: 20 August
210 2016, Version: Version 1.1).
211 .SS CAVEATS
212 .IX Subsection "CAVEATS"
213 The \fBicewm-menu-fdo\fR program is only built when the \fBicewm\fR\|(1) package
214 is configured with the \fB\-\-enable\-menus\-fdo\fR option and only works with
215 \&\fB\-\-enable\-i18n\fR option.
216 .PP
217 Integration of XDG menu files is somewhat of varying quality, heavily
218 depending on the correctness of metadata like translations and sections
219 (menu category) hints.
220 .SS "SEE ALSO"
221 .IX Subsection "SEE ALSO"
222 Base Directory Specification,
223 Desktop Entry Specification,
224 Desktop Menu Specification,
225 \&\fBicewm\fR\|(1),
226 \&\fBicewm\-menu\fR\|(5),
227 \&\fBicewm\-preferences\fR\|(5),
228 \&\fBicewm\-programs\fR\|(5).
229 .SS BUGS
230 .IX Subsection "BUGS"
231 Please report bugs at <https://github.com/ice\-wm/icewm/issues>.
232 .SS AUTHOR
233 .IX Subsection "AUTHOR"
234 Eduard Bloch <mailto:[email protected]>.
235 .PP
236 See \fB\-\-copying\fR for full copyright notice and copying permissions.
237 .SS LICENSE
238 .IX Subsection "LICENSE"
239 \&\fBIceWM\fR is licensed under the GNU Library General Public License.
240 See the \fICOPYING\fR file in the distribution or use the \fB\-\-copying\fR flag
241 to display copying permissions.