Document templates specification

[André Gillibert]

Good day.

I didn't find any freedesktop specification on document templates. The
only thing given is XDG_TEMPLATES_DIR, which doesn't explain how it's
used.

AFAIK, Nautilus (GNOME) and Thunar (XFCE) simply uses files in
$XDG_TEMPLATES_DIR (~/Templates by default), while Dolphin (KDE4) uses a
more complex scheme.

~/.kde4/share/templates/*.desktop and /usr/share/templates/*.desktop
are files, each describing a template.
A second file is required, the actual template file. It's refered from
the .desktop file.

Example extracted from libreoffice-kde_3.3.2-1ubuntu4_i386.deb:

$ cat /usr/share/templates/soffice.odt.desktop
[Desktop Entry]
Name=LibreOffice Writer  ...
Comment=Enter LibreOffice Writer filename:
Comment[de]=Name der LibreOffice Writer-Datei eingeben:
Type=Link
URL=.source/soffice.odt
Icon=libreoffice3-oasis-text

$ stat /usr/share/templates/.source/soffice.odt
  File: `usr/share/templates/.source/soffice.odt'
  Size: 7334            Blocks: 16         IO Block: 4096   regular file

Pros of the KDE way:
1) Packages can contain system-wide templates.
2) Strings can be localized, which is useful for packages, and nice
meta-information can be added, such as a longer description (comment).
The icon is not the most important part as Thunar compute it from the
file MIME type, as it does for conventional files in the directory view.

Pros of the nautilus/thunar way:
1) Easier for users to create new document templates. A single template
file is required.
2) Honors XDG_TEMPLATES_DIR and doesn't contain any "kde" string in
paths.
3) The user doesn't need to explicitly specify an icon. Thunar computes
it automatically.

I feel we can get the best of both worlds and even more, and keep
compatibility with existing tools.

Proposal:
Allow XDG_TEMPLATES_DIR to contain a colon-separated list of
directories ($XDG_DATA_HOME:$XDG_DATA_DIR by default), so that system-wide templates dir can be used.
These directories would contain raw templates file, as is currently
used by Thunar and Nautilus.

Each template file could optionally be paired with a KDE-like .desktop
file giving more specific details. If no .desktop file is found, the
name would default to the template file name, and the icon would be
computed from the MIME type.

How would the pairing be done?
Proposal: Each template directory could contain a ./Descriptions/
sub-directory containing ./Descriptions/*.desktop files, with a URL
entry pointing to the template file. The link would not necessarily
point to a file in a template directory (for backward compatibility
with KDE), and the file name would not necessarily match (for the same
reason).

This way, one could  keep all the existing KDE templates without loss.
$ mv ~/.kde4/share/templates/* ~/.local/share/Templates/Descriptions/
$ rmdir ~/.kde4/share/templates
$ ln -s ../../.local/share/Templates/Descriptions ~/.kde4/share/templates

The same thing could be done for the /usr/share/templates system-wide directory, linked to /usr/share/Templates.

Example:
$ ls $HOME/.local/share/Templates/
Text file.txt
C++ file.C
$ ls $HOME/.local/share/Templates/Descriptions
txt-file.desktop
c-file.desktop
$ cat $HOME/.local/share/Templates/Descriptions/txt-file.desktop
[Desktop Entry]
Name=Text file
Name[fr]=Fichier texte
Type=Link
URL=../Text file.txt
$ cat $HOME/.local/share/Templates/Descriptions/c-file.desktop
[Desktop Entry]
Name=C source file
Name[fr]=Fichier source C
Type=Link
URL=.source/C file.txt
$ ls $HOME/.local/share/Templates/Descriptions/.source/
C file.txt

The "Create New" menu would contain these 3 items:
Text file
C++ file
C source file

Basically, the algorithm would be:
1) For each templatedir in $XDG_TEMPLATES_DIR, list $templatedir/Descriptions/*.desktop.
2) For each .desktop file, remember the link target (URL entry in .desktop file) canonical name (see realpath(3) or canonicalize_file_name(3)).
3) For each file in some $tempatedir/*, add an entry in the create menu, unless it has already been linked by a .desktop file.

In other words, we use a KDE-like algorithm, and then, grab the missed nautilus/thunar files.

In addition to this, we could add two features.
Feature #1: Negative .desktop files, in order to let any user disable a system-wide template he doesn't like.
$ cat $HOME/.local/share/Templates/Descriptions/ods-negative.desktop
[Desktop Entry]
URL=*.ods
Name=ODS file
Type=NegativeLink

The match would be done on file extension? Or maybe Name? Or maybe file name?
Similarly, one could override a desktop file he doesn't like.
$ cat $HOME/.local/share/Templates/Descriptions/odt-override.desktop
[Desktop Entry]
Type=Link
Name=ODT file
URL=../my-odt-template.odt

Feature #2: Desktop environment specific templates.
$ cat $HOME/.local/share/Templates/Descriptions/gnome-specific-file.desktop
[Desktop Entry]
Type=Link
Name=GNOME specific file
URL=../gnome-specific.gsf
OnlyShowIn=GNOME

Other possibility: Storing .desktop files along with templates file rather than in a Descriptions sub-directory.
Con: Messy, Pro: magically more compatible with existing user kde templates, because, ../../ refer to the home directory from .kde/share/templates as well as from .kde/share/Descriptions
Third possibility: Storing .desktop files in Descriptions/, but use paths relative to the Templates/ directory, so that it's more compatible with KDE. Moreover, it would usually make prettier links, without ".." in them.

Issue #1: /usr/share/templates and /usr/share/Templates only differ by case. That's not nice. 
Issue #2: This proposal is a bit complex.

Any idea?

-- 
Regards.
André Gillibert