Implement icon theme caching. (#154034, Martijn Vernooij, caching schema

2004-10-19  Matthias Clasen  <mclasen@redhat.com>

	Implement icon theme caching.  (#154034, Martijn Vernooij,
	caching schema proposed by Owen Taylor, initial implementation
	by Anders Carlsson)

	* gtk/gtkdebug.h:
	* gtk/gtkmain.c: Add a "icontheme" debug flag.

	* gtk/Makefile.am (gtk_c_sources): Add gtkiconcache.c
	(gtk_private_h_sources): Add gtkiconcache.h
	(bin_PROGRAMS): Add gtk-update-icon-cache

	* gtk/gtkicontheme.c: Use icon caches if they are available.
	Currently, GTK+ uses the cache to get information about the
	available sizes, image file formats and .icon files. The
	actual image data, and the .icon file contents are not
	cached yet.

	* gtk/updateiconcache.c: A cmdline utility for generating
	icon cache files.

	* gtk/gtkiconcache.h:
	* gtk/gtkiconcache.c: The glue code to mmap an icon cache
	file and manage the information it contains.

5 files changed, 114 insertions, 1 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index f7f9929bf..b5b11b104 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,11 @@
+2004-10-19  Matthias Clasen  <mclasen@redhat.com>
+
+	* gtk/gtk-update-icon-cache.xml: A man page for gtk-update-icon-cache.
+
+	* gtk/gtk-docs.sgml: Add it here	
+
+	* gtk/Makefile.am (man_MANS): ...and here.
+
 2004-10-16  Matthias Clasen  <mclasen@redhat.com>
 
 	* gtk/glossary.xml: Additions.
diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index 52b66bf38..57ab11c30 100644
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -104,6 +104,7 @@ content_files =					\
 	windows.sgml				\
 	x11.sgml				\
 	gtk-query-immodules-2.0.xml		\
+	gtk-update-icon-cache.xml		\
 	visual_index.xml
 
 # Images to copy into HTML directory
@@ -240,7 +241,7 @@ EXTRA_DIST += version.xml.in
 
 ########################################################################
 
-man_MANS = gtk-query-immodules-2.0.1 
+man_MANS = gtk-query-immodules-2.0.1 gtk-update-icon-cache.1 
 
 if ENABLE_MAN
 
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 2ced4af89..462afea8a 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -193,6 +193,7 @@
 <!ENTITY gtk-migrating-GtkComboBox SYSTEM "migrating-GtkComboBox.sgml">
 <!ENTITY version SYSTEM "version.xml">
 <!ENTITY gtk-query-immodules SYSTEM "gtk-query-immodules-2.0.xml">
+<!ENTITY gtk-update-icon-cache SYSTEM "gtk-update-icon-cache.xml">
 <!ENTITY gtk-glossary SYSTEM "glossary.xml">
 ]>
 <book id="index">
@@ -576,6 +577,7 @@ that is, GUI components such as <link linkend="GtkButton">GtkButton</link> or
     <title>GTK+ Tools</title>
 
      &gtk-query-immodules;
+     &gtk-update-icon-cache;
   </part>
 
   &gtk-glossary;
diff --git a/docs/reference/gtk/gtk-update-icon-cache.1 b/docs/reference/gtk/gtk-update-icon-cache.1
new file mode 100644
index 000000000..162a97faf
--- /dev/null
+++ b/docs/reference/gtk/gtk-update-icon-cache.1
@@ -0,0 +1,49 @@
+.\"Generated by db2man.xsl. Don't modify this, modify the source.
+.de Sh \" Subsection
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Ip \" List item
+.br
+.ie \\n(.$>=3 .ne \\$3
+.el .ne 3
+.IP "\\$1" \\$2
+..
+.TH "GTK-UPDATE-ICON-CA" 1 "" "" ""
+.SH NAME
+gtk-update-icon-cache \- Icon theme caching utility
+.SH "SYNOPSIS"
+.ad l
+.hy 0
+.HP 22
+\fBgtk\-update\-icon\-cache\fR [\-\-force] {iconpath}
+.ad
+.hy
+
+.SH "DESCRIPTION"
+
+.PP
+ \fBgtk\-update\-icon\-cache\fR creates mmap()able cache files for icon themes\&.
+
+.PP
+If expects to be given the path to a icon theme directory, e\&.g\&. \fI/usr/share/icons/hicolor\fR, and writes a \fIicon\-theme\&.cache\fR containing cached information about the icons in the directory tree below the given directory\&.
+
+.PP
+GTK+ can use the cache files created by \fBgtk\-update\-icon\-cache\fR to avoid a lot of system call and disk seek overhead when the application starts\&. Since the format of the cache files allows them to be mmap()ed shared between multiple applications, the overall memory consumption is reduced as well\&.
+
+.PP
+If called with the [\-\-force] argument, \fBgtk\-update\-icon\-cache\fR will overwrite an existing cache file even if it appears to be uptodate\&.
+
+.SH "BUGS"
+
+.PP
+None known yet\&.
+
diff --git a/docs/reference/gtk/gtk-update-icon-cache.xml b/docs/reference/gtk/gtk-update-icon-cache.xml
new file mode 100644
index 000000000..e7baad89d
--- /dev/null
+++ b/docs/reference/gtk/gtk-update-icon-cache.xml
@@ -0,0 +1,53 @@
+<refentry id="gtk-update-icon-cache">
+
+<refmeta>
+<refentrytitle>gtk-update-icon-cache</refentrytitle>
+<manvolnum>1</manvolnum>
+</refmeta>
+
+<refnamediv>
+<refname>gtk-update-icon-cache</refname>
+<refpurpose>Icon theme caching utility</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+<command>gtk-update-icon-cache</command>
+<arg choice="opt">--force</arg>
+<arg choice="req">iconpath</arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para>
+<command>gtk-update-icon-cache</command> creates mmap()able cache files for
+icon themes. 
+</para>
+<para>
+If expects to be given the path to a icon theme directory, e.g. 
+<filename>/usr/share/icons/hicolor</filename>, and writes a 
+<filename>icon-theme.cache</filename> containing cached information
+about the icons in the directory tree below the given directory.
+</para>
+<para>
+GTK+ can use the cache files created by <command>gtk-update-icon-cache</command>
+to avoid a lot of system call and disk seek overhead when the application starts.
+Since the format of the cache files allows them to be mmap()ed shared between
+multiple applications, the overall memory consumption is reduced as well.
+</para>
+<para>
+If called with the --force argument, 
+<command>gtk-update-icon-cache</command> will overwrite an existing cache
+file even if it appears to be uptodate.
+</para>
+</refsect1>
+
+<refsect1><title>Bugs</title>
+<para>
+None known yet.
+</para>
+</refsect1>
+
+</refentry>
+
+