What's in the file
The files must be called either
- ~/.themes/N/metacity-1/metacity-theme-V.xml for a theme used only by you, or
- /usr/share/themes/N/metacity-1/metacity-theme-V.xml for a theme installed for all users.
where N is the name of the theme and V is the version of the format. Version 2, introduced in October 2006, adds a few extra features, but it's rarely used. Version 1 is the original format. The formats are fixed once they're stable for both backwards and forwards compatibility; new features can't be added without introducing a new version number, which is why improvements come out rarely and in large clumps. metacity-1 in the names is a fossil and doesn't mean version 1 of anything.
The metacity-theme-V.xml files are GMarkup files, which are very similar to XML. For now, you actually have to write these in a text editor or something; you can either start with a blank page, or modify a theme someone else has made. (I am thinking of writing a general theme editor program, but that'll have to wait until I've reduced Metacity's open bug queue a little.) If you want to see a fully-fledged one, you can look at the current version of "Atlanta", one of the simplest themes, but even that is quite complicated-looking at first.
So, let's talk about what actually goes inside the files. As in any XML file, <!-- … > are comments. At its most basic, it would go:
<metacity_theme> <!-- Helper stuff: --> <info …> <!-- to be explained --> <constant …> <!-- maybe; to be explained --> <draw_ops …> <!-- maybe; to be explained --> <!-- Things we build the top level onto: --> <frame_geometry …> <!-- to be explained --> <frame_style …> <!-- to be explained --> <frame_style_set …> <!-- to be explained --> <!-- And the top level: --> <window type="normal" style_set="…" /> <window type="dialog" style_set="…" /> <window type="modal_dialog" style_set="…" /> <window type="menu" style_set="…" /> <window type="utility" style_set="…" /> <window type="border" style_set="…" /> </metacity_theme>