well-known user folders, a proposal

[Alexander Larsson]

For quite some time now we've discussed possible solutions to the
problem of "well-known" folders in both Gnome and in the Fedora
project. By this I mean folders in the users home directory like the
desktop directory or the "download" directory. The main use for
directories like this is so we can default some settings and things
like initial file selector directory to a slightly more helpful place
than the home directory. 

Strongly related to this is the localization (i.e. translation) of
said directories. Now, there are two basic ways to handle this, either
you use english foldernames (this is de-facto what we do now with
~/Desktop) and translate it in the user interface, or you use
localized folder names and somehow store a pointer to the folder
that is used. Both of these methods have advantages and disadvantages,
so unfortunately all discussions tend to turn into flamewars, which
means we've never really gotten anywhere with this.

I really, really want to solve this for Fedora 7 though, and if
possible it would be nice if we could come up with a shared standard
for this. So, I've come up with a proposal that I think is a good
starting point, and I'd like some feedback on it.

I've picked the localized filenames on disk approach for two main
reasons. First of all, its the only solution that has any chance to
create a consistant user interface. We'll get translated filenames not
only in Gnome and KDE, but also in 3rd party apps like acroread. There
is also no discrepancy between what is showed in the UI and what goes
in filenames. Secondly, its the approach that is easiest to opt out of
(if you hate this idea) or configure as you'd like (if you have a 10
year old homedir structure).

One of the risks with localized filenames on disk is that people don't
use the right API to find the right place, but instead just hardcode
$HOME/Desktop. This is a common problem in windows where people
hardcode the path to "Programs Files", instead of using the right API
to find it, causing most users of non-english windows to have two such
dirs (one translated, one english). So, we need to make it as easy as
possible to look up the right directory. Especially from scripts,
which are the most likely to otherwise hardcode the directory.

I've put up a rough version of my approach here:
http://www.gnome.org/~alexl/xdg-user-dirs-0.0.1.tar.gz
(It has no dependencies but libc)

Here is how it works:
Somewhere (early) in the login scripts we run the command
xdg-user-dirs-update. It reads a config file (/etc/xdg/user-dirs.conf)
and a list of user dir defaults (/etc/xdg/user-dirs.defaults). (By
default, it also respects the xdg basedir spec env vars.) It also loads
the current user dir configuration (~/.config/user-dirs.dirs) if it
exists.

For each default specified dir type (DESKTOP, DOWNLOAD, etc) that is
not already in the user config the we create the directory and add it
to the config file. The directory name used is based on the config
file, but we also use gettext with the translations from the package
to translate pathname elements.

Some old directories (like ~/Desktop) are special cased such that a
translated version of them are not created if the old one exists
already. This gives some backwards compatibility.

If a user-configured directory doesn't exist anymore (i.e. the user
deleted it) we don't recreate it, instead we change the setting to
point it to $HOME for this dir. This means that its effectively
disabled, and apps work as they do now (defaulting to $HOME).

There is also a --force flag that ignores any existing user settings
and just creates and sets up localized dirs. This is useful if there
has been a new translation added and you want to update to that. We
can't really do this automatically since the old filename might be
stored in all sorts of places.

In order to make it really easy for scripts to use this we store the
user settings in a form that is compatible with /bin/sh. This means
you can use them as simple as:
source ~/.config/user-dirs.dirs
echo $XDG_DOWNLOAD_DIR

Here is how the current default config files look, as an example.
The actual set is not final, I just made up some that I think make
sense. Maybe we should have more/others.

/etc/xdg/user-dirs.conf:
--------------------
enabled=True
--------------------

/etc/xdg/user-dirs.defaults:
--------------------
# Default settings for user directories
#
# The values are relative pathnames from the home directory and
# will be translated on a per-path-element basis into the users locale
DESKTOP=Desktop
DOWNLOAD=Download
TEMPLATES=Templates
PUBLICSHARE=Public
DOCUMENTS=Documents
MUSIC=Music
PHOTOS=Photos
# Another alternative is:
#MUSIC=Documents/Music
#PHOTOS=Documents/Photos
--------------------

And here is a typical ~/.config/user-dirs.dir 
--------------------
# This file is written by xdg-user-dirs-update
# If you want to change or add directories, just edit the line your
interested in
# All local changes will be retained on the next run
# Format is XDG_xxx_DIR="$HOME/yyy", where yyy is shell-escaped. No
other format supported.
# 
XDG_DESKTOP_DIR="$HOME/Desktop"
XDG_DOWNLOAD_DIR="$HOME/Nerladdat"
XDG_TEMPLATES_DIR="$HOME/Templates"
XDG_PUBLICSHARE_DIR="$HOME/Public"
XDG_DOCUMENTS_DIR="$HOME/Dokument"
XDG_MUSIC_DIR="$HOME/Musik"
XDG_PHOTOS_DIR="$HOME/Foton"
--------------------

Also included in the sources is a ANSI-C version of
xdg_user_dir_lookup() (in xdg-user-dir-lookup.c). Its very simple,
uses only libc and is fully contained in one functions. This makes it
really easy to cut and paste into any C/C++ program (for instance as a
distro patch). For real desktop integration however, I expect that
each desktop adds some form of API in their platform so that desktop
applications can easily find these directories. Not to mention that
each desktop should probably integrate this into the GUI. For instance
music apps could add the music dir as a shortcut in the file selector,
etc. The details of that is up to each project.

Some open questions:

* Local translations
Generally filename translations will be shipping with the
xdg-user-dirs package, but it would be nice if admins could add local
translations if the shipped ones don't exist, or if they are
wrong. The admin could just change the defaults to be pre-translated,
but that doesn't work if users use different locales. Unfortunately
editing po-files isn't something i think most admins want to do, maybe
there is a better way to support additional translations?

* Filename encoding
Right now all directories are created in UTF-8. It would be nice to
add a config option to use a specific filename encoding, or to use the
encoding of the users locale. Should be an easy addition to the conf
file.

* Set of directories
I sort of pulled the set of directories out of my ass. Clearly there
need to be a bit more discussion about exactly what we want.


I'd like some feedback from the various desktop projects. Do you think
this is an important area to standardize? Does my approach make sense?
Is my code full of holes?

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 Alexander Larsson                                            Red Hat, Inc 
                   alexl at redhat.com    alla at lysator.liu.se 
He's an impetuous drug-addicted cyborg possessed of the uncanny powers of an 
insect. She's a mistrustful gypsy safe cracker living on borrowed time. They 
fight crime!