Document templates specification

[André Gillibert]

Simon McVittie wrote:
> On Wed, 07 Dec 2011 at 18:39:10 +0100, André Gillibert wrote:
>> AFAIK, Nautilus (GNOME) and Thunar (XFCE) simply uses files in
>> $XDG_TEMPLATES_DIR (~/Templates by default)

> I believe the point of this is to make it really easy for a user to
> create new templates, by having the directory be user-visible, so they
> can just Save As... into that directory and have them show up as templates
> (or, conversely, delete the file if the template is no longer wanted).

Yes, that's a feature(TM).
On nautilus, there's even a "Go to->Templates" shortcut.

> When looking for templates, search $XDG_TEMPLATES_DIR (defaulting to
> ~/Templates) followed by XDG_DATA_DIRS/templates according to the basedir spec
> (which means: respecting $XDG_DATA_HOME and $XDG_DATA_DIRS, but defaulting to
> ~/.local/share/templates and /usr/local/share/templates:/usr/share/templates
> respectively).
>

Good. That way, there's a reference $XDG_TEMPLATES_DIR where to store user-defined templates.

> In each of those locations, look for:
>
> * *.desktop: it's a KDE-style complex template
>
> * any other file: it's a GNOME-style raw file
>
> Then eliminate duplicates (presumably by dropping identical names), giving
> priority to XDG_TEMPLATES_DIR, then to XDG_DATA_HOME, then each element of
> XDG_DATA_DIRS; and within each directory, giving a .desktop file higher
> priority than the raw file that it references.
> 

Looks good, but there's an unfortunate side effect. Every .desktop file in ~/Templates us treated as a raw template file by current versions of Nautilus and Thunar. So, during some transitional state, some ugly entries may be shown in these file managers...
That's why, it would be better to either put *.desktop files in a sub-directory or in a separate set of directories (XDG_DESKTOP_TEMPLATES_DIR ?).

> (KDE could look in ~/.kde4/share too, as lower priority than XDG_DATA_HOME,
> to be compatible with older versions of itself.)

Ok.

Summary (pseudocode):
for each templatedir in ($XDG_TEMPLATES_DIR $XDG_DATA_DIRS/templates)
	for each file in $templatedir/Descriptions/*.desktop
		If this template (identified by the Name field for desktop files or
                by the filename without extension for nautilus-like templates)
                has not been met, this is the reference file for this template name.
		
		Else, if the template has already been met, ignore it.
	endfor
	for each non-directory file in $templatedir/*
		If this template (identified by the filename without extension)
		has not been met, this is the reference file for this template name

		Else, if the template has already been met, ignore it.
	endfor
endfor

This way, $templatedir/Descriptions/*.desktop files have higher priority (override) $templatedir/filename, which make it easy to pair them.
User templates override system-wide templates.
And finally, the way it works, the user should never see two entries with the name in the "Create New" menu, except in a localized languages.

Other possibility: Use the file name, with .desktop suffix removed, as key name.

With a symlink between /usr/share/Templates/Descriptions/ and /usr/share/templates, compatibility is preserved with existing packages.