Debian Codegraph @

upstream/mageia-cauldron/man1/icewm-menu-fdo.1

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