summaryrefslogtreecommitdiffstats
path: root/spec/icon-theme-spec.xml
blob: af619cb8e31cc9821350d0471be896b38d6196be (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<article id="index">
  <articleinfo>
    <title>Icon Theme Specification</title>
    <releaseinfo>Version 0.10</releaseinfo>
    <date>February 7 2006</date>
    <authorgroup>
      <author>
	<firstname>Alexander</firstname>
	<surname>Larsson</surname>
	<affiliation>
	  <address>
	    <email>alexl@redhat.com</email>
	  </address>
	</affiliation>
      </author>
      <author>
	<firstname>Frans</firstname>
	<surname>Englich</surname>
	<affiliation>
	  <address>
	    <email>frans.englich@telia.com</email>
	  </address>
	</affiliation>
      </author>
    </authorgroup>
  </articleinfo>

  <sect1 id="overview">
    <title>Overview</title>
    <para>
    An icon theme is a set of icons that share a common look and
    feel. The user can then select the icon theme that they want to
    use, and all apps use icons from the theme. The initial user of
    icon themes is the icon field of the desktop file specification,
    but in the future it can have other uses (such as mimetype
    icons).
    </para>
    <para>
    From a programmer perspective an icon theme is just a
    mapping. Given a set of directories to look for icons in and a theme
    name it maps from icon name and nominal icon size to an icon filename.
    </para>
  </sect1>

  <sect1 id="definitions">
    <title>Definitions</title>
    <variablelist>
      <varlistentry>
	<term>Icon Theme</term>
	<listitem>
	  <para>
          An icon theme is a named set of icons. It is used to map
          from an iconname and size to a file. Themes may inherit
          from other themes as a way to extend them.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Icon file</term>
	<listitem>
	  <para>
          An icon file is an image that can be loaded and used as an
          icon. The supported image file formats are PNG, XPM and SVG.
          PNG is the recommended bitmap format, and SVG is for
          vectorized icons. XPM is supported due to backwards
          compability reasons, and it is not recommended that new
          themes use XPM files. Support for SVGs is optional. 
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>Base Directory</term>
	<listitem>
	  <para>
          Icons and themes are searched for in a set of directories,
          called base directories. The themes are stored in
          subdirectories of the base directories.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </sect1>

  <sect1 id="directory_layout">
    <title>Directory Layout</title>
    <para>
    Icons and themes are looked for in a set of directories. By
    default, apps should look in $HOME/.icons (for backwards compatibility),
    in $XDG_DATA_DIRS/icons and in /usr/share/pixmaps (in that order).
    Applications may further add
    their own icon directories to this list, and users may extend or
    change the list (in application/desktop specific ways).In each of
    these directories themes are stored as subdirectories. A theme can
    be spread across several base directories by having subdirectories of
    the same name. This way users can extend and override system 
    themes. 
    </para>
    <para>
    In order to have a place for third party applications to install
    their icons there should always exist a theme called "hicolor"
    <footnote><para>This name is chosen for backwards compatibility with the old
    KDE default theme</para></footnote>.
    The data for the hicolor theme is available for download at:
    http://www.freedesktop.org/software/icon-theme/.
    Implementations are required to look in the "hicolor" theme if
    an icon was not found in the current theme.
    </para>
    <para>
    Each theme is stored as subdirectories of the base
    directories. The internal name of the theme is the name of the
    subdirectory, although the user-visible name as specified by the
    theme may be different. Hence, theme names are case sensitive, and
    are limited to ASCII characters. Theme names may also not contain
    comma or space.
    </para>
    <para>
    In at least one of the theme directories there must be a file
    called index.theme that describes the theme. The first index.theme
    found while searching the base directories in order is used. This
    file describes the general attributes of the theme.
    </para>
    <para>
    In the theme directory are also a set of subdirectories containing
    image files. Each directory contains icons designed for a certain
    nominal icon size, as described by the index.theme file. The
    subdirectories are allowed to be several levels deep, e.g. the
    subdirectory "48x48/apps" in the theme "hicolor" would end up at
    $basedir/hicolor/48x48/apps.
    </para>
    <para>
    The image files must be one of the types: PNG, XPM, or SVG, and
    the extension must be ".png", ".xpm", or ".svg" (lower case). The
    support for SVG files is optional. Implementations that do not
    support SVGs should just ignore any ".svg" files. In
    addition to this there may be an additional file with extra
    icon-data for each file. It should have the same basename as the
    image file, with the extension ".icon". e.g. if the icon file is
    called "mime_source_c.png" the corresponding file would be named
    "mime_source_c.icon".
    </para>
  </sect1>

  <sect1 id="file_formats">
    <title>File Formats</title>
    <para>
    Both the icon theme description file and the icon data files are
    ini-style text files, as described in the desktop file
    specification. They don't have any encoding field. Instead, they 
    must always be stored in UTF-8 encoding.
    </para>
    <para>
    The index.theme file must start with a section called <citetitle>Icon
    Theme</citetitle>, with contents according to table 1 below. All lists are
    comma-separated.
    <table>
      <title>Standard Keys</title>
      <tgroup cols="4">
	<thead>
	  <row>
	    <entry>Key</entry>
	    <entry>Description</entry>
	    <entry>Value Type</entry>
	    <entry>Required</entry>
	  </row>
	</thead>
	<tbody>
	  <row>
	    <entry>Name</entry>
	    <entry>
              short name of the icon theme, used in e.g. lists when
              selecting themes.
	    </entry>
	    <entry>localestring</entry>
	    <entry>YES</entry>
	  </row>
	  <row>
	    <entry>Comment</entry>
	    <entry>
              longer string describing the theme
	    </entry>
	    <entry>localestring</entry>
	    <entry>YES</entry>
	  </row>
	  <row>
	    <entry>Inherits</entry>
	    <entry>
              <para>
              The name of the theme that this theme inherits from. If an icon
              name is not found in the current theme, it is searched for in the
              inherited theme (and recursively in all the inherited themes).
              </para>
              <para>
              If no theme is specified implementations are required to add
              the "hicolor" theme to the inheritance tree. An implementation
              may optionally add other default themes in between the last
              specified theme and the hicolor theme.
              </para>
	    </entry>
	    <entry>strings</entry>
	    <entry>NO</entry>
	  </row>
	  <row>
	    <entry>Directories</entry>
	    <entry>
             list of subdirectories for this theme. For every
             subdirectory there must be a section in the index.theme
             file describing that directory.
	    </entry>
	    <entry>strings</entry>
	    <entry>YES</entry>
	  </row>
	  <row>
	    <entry>Hidden</entry>
	    <entry>
            Whether to hide the theme in a theme selection user interface.
            This is used for things such as fallback-themes that are not supposed
            to be visible to the user.
	    </entry>
	    <entry>boolean</entry>
	    <entry>NO</entry>
	  </row>
	  <row>
	    <entry>Example</entry>
	    <entry>
              The name of an icon that should be used as an example of
              how this theme looks.
	    </entry>
	    <entry>string</entry>
	    <entry>NO</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
    </para>
    <para>
    Each directory specified in the Directory key has a corresponding section
    with the same name as the directory. The contents of this section is
    listed in table 2 below.
    <table>
      <title>Per-Directory Keys</title>
      <tgroup cols="4">
	<thead>
	  <row>
	    <entry>Key</entry>
	    <entry>Description</entry>
	    <entry>Value Type</entry>
	    <entry>Required</entry>
	    <entry>Type</entry>
	  </row>
	</thead>
	<tbody>
	  <row>
	    <entry>Size</entry>
	    <entry>
              Nominal size of the icons in this directory.
	    </entry>
	    <entry>integer</entry>
	    <entry>YES</entry>
	  </row>
	  <row>
	    <entry>Context</entry>
	    <entry>
              The context the icon is normally used in. This 
              is in detail discussed in <xref linkend="context"/>.
	    </entry>
	    <entry>string</entry>
	    <entry>NO</entry>
	  </row>
	  <row>
	    <entry>Type</entry>
	    <entry>
              The type of icon sizes for the icons in this
              directory. Valid types are Fixed, Scalable and
              Threshold. The type decides what other keys in the
              section are used. If not specified, the default is
              Threshold.
	    </entry>
	    <entry>string</entry>
	    <entry>NO</entry>
	  </row>
	  <row>
	    <entry>MaxSize</entry>
	    <entry>
              Specifies the maximum size that the icons in this
              directory can be scaled to. Defaults to the value
              of Size if not present.
	    </entry>
	    <entry>integer</entry>
	    <entry>NO</entry>
	    <entry>Scalable</entry>
	  </row>
	  <row>
	    <entry>MinSize</entry>
	    <entry>
              Specifies the minimum size that the icons in this
              directory can be scaled to. Defaults to the value
              of Size if not present.
	    </entry>
	    <entry>integer</entry>
	    <entry>NO</entry>
	    <entry>Scalable</entry>
	  </row>
	  <row>
	    <entry>Threshold</entry>
	    <entry>
              The icons in this directory can be used if the size differ
              at most this much from the desired size. Defaults to 2 if not
              present.
	    </entry>
	    <entry>integer</entry>
	    <entry>NO</entry>
	    <entry>Threshold</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
    </para>
    <para>
    In addition to these groups you may add extra groups to the
    index.theme file in order to extend it. These extensions must
    begin with "X-", and can be used to add desktop specific
    information to the theme file. Example group names would be "X-KDE
    Icon Theme" or "X-Gnome Icon Theme".
    </para>
    <para>
    The optional filename.icon file contains a group called "Icon
    Data", with the content listed in table 3.
    <table>
      <title>Icon Data Keys</title>
      <tgroup cols="4">
	<thead>
	  <row>
	    <entry>Key</entry>
	    <entry>Description</entry>
	    <entry>Value Type</entry>
	    <entry>Required</entry>
	  </row>
	</thead>
	<tbody>
	  <row>
	    <entry>DisplayName</entry>
	    <entry>
              A translated UTF8 string that can be used instead of the
              icon name when the icon is listen in e.g. a user interface.
	    </entry>
	    <entry>localestring</entry>
	    <entry>NO</entry>
	  </row>
	  <row>
	    <entry>EmbeddedTextRectangle</entry>
	    <entry>
              If this exists, it specifies the four corners of a
              rectangle where the program displaying the icon can
              embed text. This is normally used by e.g. file managers
              that want to display a preview of text file contents in
              the icon. The corners are specified by a list of four
              values: x0,y0,x1,y1. The values are pixel coordinates
              from the top left corner of the icon, except for SVG
              files, where they are specified in a 1000x1000
              coordinate space that is scaled to the final rendered
              size of the icon.
	    </entry>
	    <entry>integers</entry>
	    <entry>NO</entry>
	  </row>
	  <row>
	    <entry>AttachPoints</entry>
	    <entry>
              A list of points, separated by "|" that may be used as
              anchor points for emblems/overlays. The points are pixel
              coordinates from the top left corner of the icon, except
              for SVG files, where they are specified in a 1000x1000
              coordinate space that is scaled to the final rendered
              size of the icon.
	    </entry>
	    <entry>points</entry>
	    <entry>NO</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
    </para>
    <para>
    Extensions to the filename.icon file are allowed, but the
    keys must be begin with "X-" to avoid collisions with future
    standardized extensions to this format.
    </para>

    <sect2 id="context">
	<title>Context</title>

	<para>The <systemitem>Context</systemitem> allows 
    	  the designer to group icons on a conceptual level. 
	  It doesn't act as a namespace in the file system, such 
	  that icons can have identical names, but allows 
	  implementations to categorize and sort by it, for example.
 	</para>

	<para>These are the available contexts:</para>
	<itemizedlist>

	  <listitem>
	    <formalpara>
	    <title>Actions</title>
	    <para>Icons representing actions which the user initiates, such as <action>Save As</action>.</para>
	    </formalpara>
	  </listitem>

	  <listitem>
	    <formalpara>
	    <title>Devices</title>
	    <para>Icons representing real world devices, 
		    such as printers and mice. It's not for 
		    file system nodes such as character or block devices.</para>
	    </formalpara>
	  </listitem>

	  <listitem>
	    <formalpara>
	      <title>FileSystems</title>
	      <para>Icons for objects which are represented as 
		 part of the file system. This is for example, 
		 the local network, <quote>Home</quote>, 
		 and <quote>Desktop</quote> folders.</para>
	    </formalpara>
	  </listitem>

	  <listitem>
	  <formalpara>
	  <title>MimeTypes</title>
	  <para>Icons representing MIME types.</para>
	  </formalpara>
	  </listitem>

	</itemizedlist>
		
    </sect2>
  </sect1>

  <sect1 id="icon_lookup">
    <title>Icon Lookup</title>
    <para>
    The icon lookup mechanism has two global settings, the list of
    base directories and the internal name of the current theme. Given
    these we need to specify how to look up an icon file from the icon
    name and the nominal size.
    </para>
    <para>
    The lookup is done first in the current theme, and then
    recursively in each of the current theme's parents, and
    finally in the default theme called "hicolor" (implementations may
    add more default themes before "hicolor", but "hicolor" must be
    last). As soon as there is an icon of any size that matches in a
    theme, the search is stopped. Even if there may be an icon with a
    size closer to the correct one in an inherited theme, we don't want
    to use it. Doing so may generate an inconsistant change in an icon
    when you change icon sizes (e.g. zoom in).
    </para>
    <para>
    The lookup inside a theme is done in three phases. First all the
    directories are scanned for an exact match, e.g. one where the
    allowed size of the icon files match what was looked up. Then all
    the directories are scanned for any icon that matches the name. If
    that fails we finally fall back on unthemed icons. If we fail to
    find any icon at all it is up to the application to pick a good
    fallback, as the correct choice depends on the context.
    </para>
    <para>
    The exact algorithm (in pseudocode) for looking up an icon in a theme
    (if the implementation supports SVG) is:
    <programlisting>
FindIcon(icon, size) {
  theme = user selected theme
  do {
    filename = LookupIcon (icon, size, theme)
    if filename != none
      return filename
    theme = theme.parentTheme()
  } while (theme)
  return LookupFallbackIcon (iconname)
}
     </programlisting>
     With the following helper functions:
     <programlisting>
LookupIcon (iconname, size, theme) {
  for each subdir in $(theme subdir list) {
    for each directory in $(basename list) {
      for extension in ("png", "svg", "xpm") {
        if DirectoryMatchesSize(subdir, size) {
          filename = directory/$(themename)/subdir/iconname.extension
          if exist filename
	    return filename
        }
      }
    }
  }
  minimal_size = MAXINT
  for each subdir in $(theme subdir list) {
    for each directory in $(basename list) {
      for extension in ("png", "svg", "xpm") {
        filename = directory/$(themename)/subdir/iconname.extension
        if exist filename and DirectorySizeDistance(subdir, size) &lt; minimal_size {
	   closest_filename = filename
	   minimal_size = DirectorySizeDistance(subdir, size)
        }
      }
    }
  }
  if closest_filename set
     return closest_filename
  return none
}

LookupFallbackIcon (iconname) {
  for each directory in $(basename list) {
    for extension in ("png", "svg", "xpm") {
      if exists directory/iconname.extension
        return directory/iconname.extension
    }
  }
  return none
}

DirectoryMatchesSize(subdir, iconsize) {
  read Type and size data from subdir
  if Type is Fixed
    return Size == iconsize
  if Type is Scaled
    return MinSize &lt;= iconsize &lt;= MaxSize
  if Type is Threshold
    return Size - Threshold &lt;= iconsize &lt;= Size + Threshold
}

DirectorySizeDistance(subdir, size) {
  read Type and size data from subdir
  if Type is Fixed
    return abs(Size - iconsize)
  if Type is Scaled
    if iconsize &lt; MinSize
        return MinSize - iconsize
    if iconsize &gt; MaxSize
        return iconsize - MaxSize
    return 0
  if Type is Threshold
    if iconsize &lt; Size - Threshold
        return MinSize - iconsize
    if iconsize &gt; Size + Threshold
        return iconsize - MaxSize
    return 0
}
</programlisting>
    </para>
    <para>
    In some cases you don't always want to fall back to an icon in an
    inherited theme. For instance, sometimes you look for a set of
    icons, prefering any of them before using an icon from an inherited
    theme. To support such operations implementations can contain a
    function that finds the first of a list of icon names in the inheritance
    hierarchy. I.E. It would look something like this:
<programlisting>FindBestIcon(iconList, size) {
  theme = user selected theme
  do {
    for icon in iconList {
      filename = LookupIcon (icon, size, theme)
      if filename != none
        return filename
    }

    theme = theme.parentTheme()
  } while (theme)

  return LookupFallbackIcon (iconname)
}
</programlisting>
    This can be very useful for example when handling mimetype icons, where there
    are more and less "specific" versions of icons.
    </para>
  </sect1>

  <sect1 id="example">
    <title>Example</title>
    <para>
     Here is an example index.theme file:
     <programlisting>[Icon Theme]
Name=Birch
Name[sv]=Björk
Comment=Icon theme with a wooden look
Comment[sv]=Träinspirerat ikontema
Inherits=wood,default
Directories=48x48/apps,48x48/mimetypes,32x32/apps,scalable/apps,scalable/mimetypes

[scalable/apps]
Size=48
Type=Scalable
MinSize=1
MaxSize=256
Context=Applications

[scalable/mimetypes]
Size=48
Type=Scalable
MinSize=1
MaxSize=256
Context=MimeTypes

[32x32/apps]
Size=32
Type=Fixed
Context=Applications

[48x48/apps]
Size=48
Type=Fixed
Context=Applications

[48x48/mimetypes]
Size=48
Type=Fixed
Context=MimeTypes</programlisting>
     The corresponding directory tree in the /usr/share/icons
     directory could look like this:
     <programlisting>birch/index.theme
birch/scalable/apps/mozilla.svg
birch/scalable/mimetypes/mime_text_plain.svg
birch/scalable/mimetypes/mime_text_plain.icon
birch/48x48/apps/mozilla.png
birch/32x32/apps/mozilla.png
birch/48x48/mimetypes/mime_text_plain.png
birch/48x48/mimetypes/mime_text_plain.icon</programlisting>
Where birch/scalable/mimetypes/mime_text_plain.icon contains:
     <programlisting>[Icon Data]
DisplayName=Mime text/plain
EmbeddedTextRectangle=100,100,900,900
AttachPoints=200,200|800,200|500,500|200,800|800,800</programlisting>
And birch/48x48/mimetypes/mime_text_plain.icon contains:
     <programlisting>[Icon Data]
DisplayName=Mime text/plain
EmbeddedTextRectangle=8,8,40,40
AttachPoints=20,20|40,40|50,10|10,50</programlisting>
    </para>
    <para>
    In this example a lookup of "mozilla" would get the prerendered
    48x48 and 32x32 icons before the SVG icons due to the order of
    Directories.
    </para>

  </sect1>

  <sect1 id="install_icons">
    <title>Installing Application Icons</title>
    <para>
    So, you're an application author, and want to install application icons
    so that they work in the KDE and Gnome menus. Minimally you should install
    a 48x48 icon in the hicolor theme. This means installing a PNG file in
    $prefix/share/icons/hicolor/48x48/apps. Optionally you can install icons in different
    sizes. You might even want to install icons with a look that matches other
    well known themes so your application will fit in with some specific desktop
    environment. 
    </para>
    <para>
    It is recommended that the icons installed in the hicolor theme look neutral,
    since it is a fallback theme that will be used in combination with some very
    different looking themes. But if you don't have any neutral icon, please install
    whatever icon you have in the hicolor theme so that all applications get at
    least some icon in all themes.
    </para>
  </sect1>

  <sect1 id="implementation_notes">
    <title>Implementation Notes</title>
    <para>
    The algorithm as described in this document works by always
    looking up filenames in directories (a stat in unix
    terminology). A good implementation is expected to read the
    directories once, and do all lookups in memory using that
    information.
    </para>
    <para>
    This caching can make it impossible for users to add icons without
    having to restart applications. In order to handle this, any
    implementation that does caching is required to look at the mtime
    of the toplevel icon directories when doing a cache lookup, unless
    it already did so less than 5 seconds ago. This means that any
    icon editor or theme installation program need only to change the
    mtime of the the toplevel directory where it changed the theme to
    make sure that the new icons will eventually get used.
    </para>
  </sect1>

  <sect1 id="background">
    <title>Background</title>
    <para>
    The icon theme specification is based on the original
    KDE icon theme system designed by Antonio Larossa,
    Geert Janssen and Torsten Rahn. The common specification
    mostly adds support for .icon files, renames the icon theme
    description files and removes a few references to kde in them.
    </para>
  </sect1>
  
  <appendix id="changes">
    <title>Change history</title>
    <formalpara>
      <title>Version 0.10, 7 February 2006, Alexander Larsson</title>    
      <para>
	<itemizedlist>
	  <listitem>
	    <para>
            Clarify that icon lookup looks in all parent themes before
            falling back to nonthemed icons.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
            Added lookup function that takes a list of icon names (FindBestIcon)
	    </para>
	  </listitem>
	</itemizedlist>
      </para>
    </formalpara>
    <formalpara>
      <title>Version 0.9, 4 April 2005, Alexander Larsson</title>    
      <para>
	<itemizedlist>
	  <listitem>
	    <para>
            Cleanups and fixes to language from Rodney Dawes and
            Frans Englich.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
            Added section describing Contexts in more details (by
            Frans Englich).
	    </para>
	  </listitem>
	</itemizedlist>
      </para>
    </formalpara>
    <formalpara>
      <title>Version 0.8, 5 February 2004, Alexander Larsson</title>    
      <para>
	<itemizedlist>
	  <listitem>
	    <para>
            Fix language problems as pointed out by Rodney Dawes and
            Michael Terry.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
            Added background section.
	    </para>
	  </listitem>
	</itemizedlist>
      </para>
    </formalpara>
    <formalpara>
      <title>Version 0.7, 13 September 2003, Heinrich Wendel</title>    
      <para>
	<itemizedlist>
	  <listitem>
	    <para>
            Converted to basedir spec.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
            Changed type of MaxSize, MinSize and Threshold to integer.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
            Removed typo in code example.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
            Corrected path to default-icon-theme.
	    </para>
	  </listitem>
	</itemizedlist>
      </para>
    </formalpara>
    <formalpara>
      <title>Version 0.6, 2 December 2002, Alexander Larsson</title>    
      <para>
	<itemizedlist>
	  <listitem>
	    <para>
            Added Hidden key.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
            Removed multiple inheritance.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
            Renamed the default theme hicolor.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
            Added the application icon install section.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
            Fixed some xml issues.
	    </para>
	  </listitem>
	</itemizedlist>
      </para>
    </formalpara>
    <formalpara>
      <title>Version 0.5, 18 September 2002, Alexander Larsson</title>    
      <para>
	<itemizedlist>
	  <listitem>
	    <para>
            Added DisplayName to icon data.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
            Fixed up example svg icon data.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
            Fixed some spelling and grammar errors.
	    </para>
	  </listitem>
	</itemizedlist>
      </para>
    </formalpara>
    <formalpara>
      <title>Version 0.4, 16 May 2002, Alexander Larsson</title>    
      <para>
	<itemizedlist>
	  <listitem>
	    <para>
            Fixed some spelling and grammar errors.
	    </para>
	  </listitem>
	</itemizedlist>
      </para>
    </formalpara>
    <formalpara>
      <title>Version 0.3, 14 May 2002, Alexander Larsson</title>    
      <para>
	<itemizedlist>
	  <listitem>
	    <para>
            Made support for SVGs optional.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
            Added a default fallback theme.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
            Changed the example directory layout a bit to
            match the default theme.
	    </para>
	  </listitem>
	</itemizedlist>
      </para>
    </formalpara>
    <formalpara>
      <title>Version 0.2, 29 April 2002, Alexander Larsson</title>    
      <para>
	<itemizedlist>
	  <listitem>
	    <para>
              Changed search order to png, svg, xpm.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
              Added comment to say that xpm is supported for backwards
              compat and not recommended in new themes.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
              Default Type for a directory is now Threshold
	    </para>
	  </listitem>
	  <listitem>
	    <para>
              Added implementation notes section.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
              Added Example key.
	    </para>
	  </listitem>
	</itemizedlist>
      </para>
    </formalpara>
    <formalpara>
      <title>Version 0.1, 22 April 2002, Alexander Larsson</title>    
      <para>
	<itemizedlist>
	  <listitem>
	    <para>
              Created initial draft.
	    </para>
	  </listitem>
	</itemizedlist>
      </para>
    </formalpara>
  </appendix>
</article>