There is nowhere to be found.
The 'index.theme' specification for GTK+ theme doesn't seem to be documented anymore since GNOME 2 had deprecated. Both GTK+ and GNOME Developer websites are essentially having zero documentation about 'index.theme' for GTK+ theme.
The earliest known documentation, GNOME 2.4 Desktop System Administration Guide, was last updated in 2003. That is possibly the original 'index.theme' specification for GTK+ theme.
[Desktop Entry] Type=X-GNOME-Metatheme Name=High Contrast Large Name[es]=Alto contraste grande Comment=Large black-on-white text and icons Comment[es]=Textos e iconos grandes en negro sobre blanco Encoding=UTF-8 [X-GNOME-Metatheme] GtkTheme=HighContrastLargePrint IconTheme=HighContrast MetacityTheme=Atlanta ApplicationFont=sans 18
Following that, some changes have been introduced in GNOME mailing list dated July 2004 and October 2004 (only latter is quoted below). Unfortunately, there is no updated documentation by GTK+ or GNOME developers to illustrate those changes.
gnome-theme-manager currently handles GTK, Metacity and Icon themes, but could be extended to handle splash screens and backgrounds (possible integration with current background chooser?).
A relatively new documentation, Gnome Theme Package format by Xfce, was last updated in 2010. This included more variables in the
index.theme file that are not found in the original specification and reflects some of the changes mentioned in GNOME mailing list.
[Desktop Entry] Name=example theme Type=X-GNOME-Metatheme Comment= Encoding=UTF-8 [X-GNOME-Metatheme] GtkTheme=Gilouche MetacityTheme=Gilouche IconTheme=gnome BackgroundImage=.local/share/wallpapers/Naptime.jpg MonospaceFont= ApplicationFont= DesktopFont= SoundTheme= GtkColorScheme=
Supporting fact has been found in Artwork/Documentation/GTK-Themes on Ubuntu Wiki, which mentioned one of the additional variables. This material however, was last updated in 2009.
In your index.theme file put a line like "
BackgroundImage=/absolute/path/to/image.png" under the X-GNOME-Metatheme header. For packaged themes wallpapers should be assumed to be placed in
To use or not
If you are less confident to use the provided example in outdated documentation, I'd suggest to copy
index.theme file from existing THEME and modify accordingly. GTK+ themes will include the file at
/usr/share/themes/THEME/index.theme in some Ubuntu and official flavours.
Another way to use
index.theme file is, by not having to write one.
There is at least one example that demonstrates custom GTK+ theme could just reference to existing file by using symbolic link. This way, it is possible to create slightly modified version of existing theme in less time and without having to worry about the specification of
TL;DR The most recent documentation that you can find today, albeit without explanation, is Gnome Theme Package format by Xfce. Or just forget that and follow what other themes do.
You can find a document here. I don't know how up to date it is though. It discusses the structure of the file, the possible keys that are allowed and their descriptions.
If you do have the time try joining #gtk+ and #gnome-design on IRC. They may be able to answer your queries better. See here for learning how.