← Back to branch summary

~saiarcot895/ubuntu/wily/xdg-utils/fix-multiple-execs

« back to all changes in this revision

Viewing changes to scripts/desc/xdg-icon-resource.xml

  • Committer: Package Import Robot
  • Author(s): Per Olofsson
  • Date: 2011-12-12 12:04:25 UTC
  • mfrom: (1.2.8)
  • mto: This revision was merged to the branch mainline in revision 34.
  • Revision ID: package-import@ubuntu.com-20111212120425-0rdnrl8tn45vz171
Tags: 1.1.0~rc1+git20111210-1
http://bugs.debian.org/648733
* New upstream git snapshot b961235b197647d6649ef3d48d7cc2cecafe3d47.
* Drop patches applied upstream:
  - xdg-mime-follow-symlinks.diff
  - x-www-browser.diff
  - xdg-mime-generic-use-mimetype.diff
  - bashisms.diff
  - xdg-screensaver-check-gnome.diff
* Modify patches to make changes to scripts/xdg-*.in, instead of the
  generated scripts.
* Also check for ~/.mutt/muttrc when deciding whether to use mutt as
  MUA or not. Thanks to martin f krafft. Closes: #648733.
* Build scripts/xdg-* from *.in files.
* Build-depend on xmlto and awk, as they are needed when building the
  scripts.
* Also build the manual pages.
* Bump Standards-Version to 3.9.2. No changes.

Show diffs side-by-side

added added

removed removed

Lines of Context:
scripts/desc/xdg-icon-resource.xml
 
1
<?xml version="1.0"?>
 
2
<?xml-stylesheet type="text/xsl"
 
3
   href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>
 
4
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
 
5
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
 
6
]>
 
7
<refentry id="xdg-icon-resource">
 
8
  <refentryinfo>
 
9
    <title>xdg-icon-resource Manual</title>
 
10
    <copyright>
 
11
      <year>2006</year>
 
12
    </copyright>
 
13
    <author>
 
14
      <firstname>Kevin</firstname>
 
15
      <surname>Krammer</surname>
 
16
    </author>
 
17
    <address><email>kevin.krammer@gmx.at</email></address>
 
18
    <author>
 
19
      <firstname>Jeremy</firstname>
 
20
      <surname>White</surname>
 
21
    </author>
 
22
    <address><email>jwhite@codeweavers.com</email></address>
 
23
    <releaseinfo>xdg-utils 1.0</releaseinfo>
 
24
  </refentryinfo>
 
25
 
 
26
  <refmeta>
 
27
    <refentrytitle>xdg-icon-resource</refentrytitle>
 
28
    <manvolnum>1</manvolnum>
 
29
  </refmeta>
 
30
 
 
31
  <refnamediv>
 
32
    <refname>xdg-icon-resource</refname>
 
33
    <refpurpose>command line tool for (un)installing icon resources</refpurpose>
 
34
  </refnamediv>
 
35
 
 
36
  <refsynopsisdiv>
 
37
    <cmdsynopsis>
 
38
      <command>xdg-icon-resource</command>
 
39
      <arg choice="plain">install</arg>
 
40
      <arg><option>--noupdate</option></arg>
 
41
      <arg><option>--novendor</option></arg>
 
42
      <arg><option>--theme <replaceable>theme</replaceable></option></arg>
 
43
      <arg><option>--context <replaceable>context</replaceable></option></arg>
 
44
      <arg><option>--mode <replaceable>mode</replaceable></option></arg>
 
45
      <arg choice="plain"><option>--size <replaceable>size</replaceable></option></arg>
 
46
      <arg choice="plain"><replaceable>icon-file</replaceable></arg>
 
47
      <arg><replaceable>icon-name</replaceable></arg>
 
48
    </cmdsynopsis>
 
49
    <cmdsynopsis>
 
50
      <command>xdg-icon-resource</command>
 
51
      <arg choice="plain">uninstall</arg>
 
52
      <arg><option>--noupdate</option></arg>
 
53
      <arg><option>--theme <replaceable>theme</replaceable></option></arg>
 
54
      <arg><option>--context <replaceable>context</replaceable></option></arg>
 
55
      <arg><option>--mode <replaceable>mode</replaceable></option></arg>
 
56
      <arg choice="plain"><option>--size <replaceable>size</replaceable></option></arg>
 
57
      <arg choice="plain"><replaceable>icon-name</replaceable></arg>
 
58
    </cmdsynopsis>
 
59
    <cmdsynopsis>
 
60
      <command>xdg-icon-resource</command>
 
61
      <arg choice="plain">forceupdate</arg>
 
62
      <arg><option>--theme <replaceable>theme</replaceable></option></arg>
 
63
      <arg><option>--mode <replaceable>mode</replaceable></option></arg>
 
64
    </cmdsynopsis>
 
65
    <cmdsynopsis>
 
66
      <command>xdg-icon-resource</command>
 
67
      <group choice="req">
 
68
        <arg choice="plain"><option>--help</option></arg>
 
69
        <arg choice="plain"><option>--manual</option></arg>
 
70
        <arg choice="plain"><option>--version</option></arg>
 
71
      </group>
 
72
    </cmdsynopsis>
 
73
  </refsynopsisdiv>
 
74
 
 
75
  <refsect1 id="description">
 
76
    <title>Description</title>
 
77
    <para>
 
78
      The xdg-icon-resource program can be used to install icon resources
 
79
      into the desktop icon system in order to illustrate menu entries,
 
80
      to depict desktop icons or to graphically represent file types.
 
81
    </para>
 
82
    <para>
 
83
      The desktop icon system identifies icons by name. Depending on the
 
84
      required size, the choice of icon theme and the context in which the
 
85
      icon is used, the desktop icon system locates an appropriate
 
86
      icon resource to depict an icon. Icon resources can be XPM files or
 
87
      PNG files. 
 
88
    </para>
 
89
    <para>
 
90
      The desktop icon system works according to the
 
91
      XDG Icon Theme Specification at
 
92
      <ulink url="http://www.freedesktop.org/wiki/Specifications/icon-theme-spec"/>
 
93
    </para>
 
94
  </refsect1>
 
95
  <refsect1 id="commands">
 
96
    <title>Commands</title>
 
97
    <variablelist>
 
98
      <varlistentry>
 
99
        <term>install</term>
 
100
        <listitem>
 
101
          <simpara>
 
102
            Installs the icon file indicated by <replaceable>icon-file</replaceable>
 
103
            to the desktop icon system under the name 
 
104
            <replaceable>icon-name</replaceable>. 
 
105
            Icon names do not have an extension.
 
106
            If <replaceable>icon-name</replaceable> is not provided the name is
 
107
            derived from <replaceable>icon-file</replaceable>.
 
108
            The icon file must have
 
109
            <emphasis>.png</emphasis> or <emphasis>.xpm</emphasis>
 
110
            as extension. If a corresponding <emphasis>.icon</emphasis>
 
111
            file exists in the same location as <replaceable>icon-file</replaceable>
 
112
            it will be installed as well.
 
113
          </simpara>
 
114
        </listitem>
 
115
      </varlistentry>
 
116
 
 
117
      <varlistentry>
 
118
        <term>uninstall</term>
 
119
        <listitem>
 
120
          <simpara>
 
121
            Removes the icon indicated by <replaceable>icon-name</replaceable>
 
122
            from the desktop icon system. Note that icon names do not have
 
123
            an extension.
 
124
          </simpara>
 
125
        </listitem>
 
126
      </varlistentry>
 
127
 
 
128
      <varlistentry>
 
129
        <term>forceupdate</term>
 
130
        <listitem>
 
131
          <simpara>
 
132
            Force an update of the desktop icon system. This is only useful if
 
133
            the last call to xdg-icon-resource included the <option>--noupdate</option> option.
 
134
          </simpara>
 
135
        </listitem>
 
136
      </varlistentry>
 
137
    </variablelist>
 
138
  </refsect1>
 
139
  <refsect1 id="options">
 
140
    <title>Options</title>
 
141
    <variablelist>
 
142
      <varlistentry>
 
143
        <term><option>--noupdate</option></term>
 
144
        <listitem>
 
145
          <simpara>
 
146
            Postpone updating the desktop icon system. If multiple icons are
 
147
            added in sequence this flag can be used to indicate that
 
148
            additional changes will follow and that it is not
 
149
            necessary to update the desktop icon system right away.
 
150
          </simpara>
 
151
        </listitem>
 
152
      </varlistentry>
 
153
      <varlistentry>
 
154
        <term><option>--novendor</option></term>
 
155
        <listitem>
 
156
          <simpara>
 
157
            Normally, xdg-icon-resource checks to ensure that an icon file
 
158
            to be installed in the <emphasis>apps</emphasis> context has
 
159
            a proper vendor prefix. This option can be used to disable
 
160
            that check.
 
161
          </simpara>
 
162
          <simpara>
 
163
            A vendor prefix consists of alpha characters ([a-zA-Z]) and is
 
164
            terminated with a dash ("-").
 
165
            Companies and organizations are encouraged to use a word
 
166
            or phrase, preferably the organizations name, for which they hold
 
167
            a trademark as their vendor prefix.
 
168
            The purpose of the vendor prefix is to prevent name conflicts.
 
169
          </simpara>
 
170
        </listitem>
 
171
      </varlistentry>
 
172
 
 
173
      <varlistentry>
 
174
        <term><option>--theme</option> <replaceable>theme</replaceable></term>
 
175
        <listitem>
 
176
          <simpara>
 
177
            Installs or removes the icon file as part of 
 
178
            <replaceable>theme</replaceable>. If no theme is specified the
 
179
            icons will be installed as part of the default <emphasis>hicolor</emphasis> theme.
 
180
            Applications may install icons under multiple themes but should
 
181
            at least install icons for the default <emphasis>hicolor</emphasis> theme.
 
182
          </simpara>
 
183
        </listitem>
 
184
      </varlistentry>
 
185
 
 
186
      <varlistentry>
 
187
        <term><option>--context</option> <replaceable>context</replaceable></term>
 
188
        <listitem>
 
189
          <simpara>
 
190
            Specifies the context for the icon. Icons to be used in the
 
191
            application menu and as desktop icon should use
 
192
            <emphasis>apps</emphasis> as context which is the default
 
193
            context. Icons to be used as file icons should use
 
194
            <emphasis>mimetypes</emphasis> as context.
 
195
            Other common contexts are <emphasis>actions</emphasis>,
 
196
            <emphasis>devices</emphasis>, <emphasis>emblems</emphasis>,
 
197
            <emphasis>filesystems</emphasis> and <emphasis>stock</emphasis>.
 
198
          </simpara>
 
199
        </listitem>
 
200
      </varlistentry>
 
201
 
 
202
      <varlistentry>
 
203
        <term><option>--size</option> <replaceable>size</replaceable></term>
 
204
        <listitem>
 
205
          <simpara>
 
206
            Specifies the size of the icon. All icons must be square.
 
207
            Common sizes for icons in the apps context are:
 
208
            16, 22, 32, 48, 64 and 128.  
 
209
            Common sizes for icons in the mimetypes context are:
 
210
            16, 22, 32, 48, 64 and 128
 
211
          </simpara>
 
212
        </listitem>
 
213
      </varlistentry>
 
214
 
 
215
      <varlistentry>
 
216
        <term><option>--mode</option> <replaceable>mode</replaceable></term>
 
217
        <listitem>
 
218
          <simpara><replaceable>mode</replaceable> can be
 
219
            <emphasis>user</emphasis> or <emphasis>system</emphasis>.
 
220
            In user mode the file is (un)installed for the current user
 
221
            only. In system mode the file is (un)installed for all users
 
222
            on the system. Usually only root is allowed to install in
 
223
            system mode.
 
224
          </simpara>
 
225
          <simpara>
 
226
            The default is to use system mode when called by root
 
227
            and to use user mode when called by a non-root user.
 
228
          </simpara>
 
229
        </listitem>
 
230
      </varlistentry>
 
231
 
 
232
      <varlistentry>
 
233
        <term><option>--help</option></term>
 
234
        <listitem>
 
235
          <simpara>
 
236
            Show command synopsis.
 
237
          </simpara>
 
238
        </listitem>
 
239
      </varlistentry>
 
240
 
 
241
      <varlistentry>
 
242
        <term><option>--manual</option></term>
 
243
        <listitem>
 
244
          <simpara>
 
245
            Show this manual page.
 
246
          </simpara>
 
247
        </listitem>
 
248
      </varlistentry>
 
249
 
 
250
      <varlistentry>
 
251
        <term><option>--version</option></term>
 
252
        <listitem>
 
253
          <simpara>
 
254
            Show the xdg-utils version information.
 
255
          </simpara>
 
256
        </listitem>
 
257
      </varlistentry>
 
258
 
 
259
    </variablelist>
 
260
  </refsect1>
 
261
  <refsect1 id="env_vars">
 
262
    <title>Environment Variables</title>
 
263
    <para>
 
264
      xdg-icon-resource honours the following environment variables:
 
265
    </para>
 
266
    <variablelist>
 
267
      <varlistentry>
 
268
        <term>XDG_UTILS_DEBUG_LEVEL</term>
 
269
        <listitem>
 
270
          <simpara>
 
271
            Setting this environment variable to a non-zero numerical value
 
272
            makes xdg-icon-resource do more verbose reporting on stderr.
 
273
            Setting a higher value increases the verbosity.
 
274
          </simpara>
 
275
        </listitem>
 
276
      </varlistentry>
 
277
      <varlistentry>
 
278
        <term>XDG_UTILS_INSTALL_MODE</term>
 
279
        <listitem>
 
280
          <simpara>
 
281
            This environment variable can be used by the user or
 
282
            administrator to override the installation mode.
 
283
            Valid values are <emphasis>user</emphasis> and
 
284
            <emphasis>system</emphasis>.  
 
285
          </simpara>
 
286
        </listitem>
 
287
      </varlistentry>
 
288
    </variablelist>
 
289
  </refsect1>
 
290
 
 
291
  <refsect1 id="exitcodes">
 
292
    <title>Exit Codes</title>
 
293
    <para>
 
294
      An exit code of 0 indicates success while a non-zero exit code
 
295
      indicates failure. The following failure codes can be returned:
 
296
    </para>
 
297
    <variablelist>
 
298
      <varlistentry>
 
299
        <term><option>1</option></term>
 
300
        <listitem>
 
301
          <simpara>
 
302
            Error in command line syntax.
 
303
          </simpara>
 
304
        </listitem>
 
305
      </varlistentry>
 
306
      <varlistentry>
 
307
        <term><option>2</option></term>
 
308
        <listitem>
 
309
          <simpara>
 
310
            One of the files passed on the command line did not exist.
 
311
          </simpara>
 
312
        </listitem>
 
313
      </varlistentry>
 
314
      <varlistentry>
 
315
        <term><option>3</option></term>
 
316
        <listitem>
 
317
          <simpara>
 
318
            A required tool could not be found. 
 
319
          </simpara>
 
320
        </listitem>
 
321
      </varlistentry>
 
322
      <varlistentry>
 
323
        <term><option>4</option></term>
 
324
        <listitem>
 
325
          <simpara>
 
326
            The action failed. 
 
327
          </simpara>
 
328
        </listitem>
 
329
      </varlistentry>
 
330
      <varlistentry>
 
331
        <term><option>5</option></term>
 
332
        <listitem>
 
333
          <simpara>
 
334
            No permission to read one of the files passed on the command
 
335
            line.
 
336
          </simpara>
 
337
        </listitem>
 
338
      </varlistentry>
 
339
    </variablelist>
 
340
  </refsect1>
 
341
  <refsect1 id="seealso">
 
342
    <title>See Also</title>
 
343
    <para><citerefentry><refentrytitle>xdg-desktop-icon</refentrytitle>
 
344
        <manvolnum>1</manvolnum>
 
345
      </citerefentry>,
 
346
      <citerefentry><refentrytitle>xdg-desktop-menu</refentrytitle>
 
347
        <manvolnum>1</manvolnum>
 
348
      </citerefentry>,
 
349
      <citerefentry><refentrytitle>xdg-mime</refentrytitle>
 
350
        <manvolnum>1</manvolnum>
 
351
      </citerefentry>
 
352
    </para>
 
353
  </refsect1>
 
354
  <refsect1 id="examples">
 
355
    <title>Examples</title>
 
356
    <para>
 
357
To install an icon resource to depict a launcher for the application
 
358
myfoobar, the company ShinyThings Inc. can use:
 
359
<programlisting>
 
360
xdg-icon-resource install --size 64 shinythings-myfoobar.png
 
361
</programlisting>
 
362
    </para>
 
363
    <para>
 
364
To install an icon for a new application/x-foobar file type one can use:
 
365
<programlisting>
 
366
xdg-icon-resource install --context mimetypes --size 48 ./mime-foobar-48.png application-x-foobar
 
367
xdg-icon-resource install --context mimetypes --size 64 ./mime-foobar-64.png application-x-foobar
 
368
</programlisting>This will install two icons with the name application-x-foobar
 
369
but with different sizes.
 
370
    </para>
 
371
  </refsect1>
 
372
</refentry>