This document details the choices system, as used in the ROX desktop. Comments are welcome. Programmers writing programs which have nothing to do with the ROX Desktop are still encouraged to consider using this system.
02-Jun-2000: The default value for the CHOICESPATH variable has changed. Please update your programs...
06-Jan-2004: Freedesktop.org are developing a similar system: the Desktop base directory spec. It works in much the same way as the choices system described below, and we may well adopt it at some point. To avoid name conflicts, subdirectories should probably be created with a domain name you control (eg ~/.config/rox.sourceforge.net/...).
Traditionally, Unix programs have stored user choices inside a file starting with '.' inside the user's home directory. This new system attempts to provide a better way - here are its main features:
The choices system is controlled by a single environment variable, CHOICESPATH. Usuaully this will not be set, in which case the default value of ${HOME}/Choices:/usr/local/share/Choices:/usr/share/Choices will always be assumed (where ${HOME} is replaced by the user's home directory).
Distribution-wide choices go in the directory /usr/share/Choices. These will be set up by the people who made your distribution and you never need to change these. Installing new packages may put new defaults in here. System-wide choices that override these go in /usr/local/share/Choices. Whoever manages your system controls what goes here. Your personal choices, which override distribution-wide and system-wide choices, go in /home/fred/Choices (replace /home/fred with your home directory).
If you want your choices hidden, set CHOICESPATH so that your Choices directory starts with a dot, eg: /home/fred/.choices:/usr/local/share/Choices:/usr/share/Choices.
If you don't want any choices to be saved then put a colon at the start, eg: :/home/fred/.choices:/usr/local/share/Choices:/usr/share/Choices.
The environment variable is a list of directories, separated by colons. Each of these directories contains sub-directories - one for each program which has saved choices. When a program wishes to load a configuration file it checks each directory in the path in turn (left to right) for a directory with the program's name containing the required file.
So, if a program called ROX-Filer wants to load a file called options then, with the default value of CHOICESPATH for the user fred, it will check for the following files, in order:
It will use the first one it finds. A program may, at its option, choose to merge the values in all of these files provided that options set in the earlier files always override options set in the later ones. Any options not set should use built-in default values.
CHOICESPATH may start with a colon - simply ignore the colon. If CHOICESPATH is set, but to an empty string, then there are no choices to load. Do not complain to the user in either case.
It is not an error if some of the directories in CHOICESPATH do not exist or if they do not contain a sub-directory with your program's name - simply ignore these directories.
I recommend that if you cannot find any configuration files when you load that you do NOT automatically create some (or prompt the user). If you can generate some default values now, you can do it next time you load too. In particular, you should NEVER create or offer to create config files if the user has disabled saving of choices (see User's view).
When you wish to save some options / state data you should:
If CHOICESPATH is set, but starts with a colon or is an empty string then choices cannot be saved. Automatic saving of state should simply be skipped. If the user specifically asked the program to save then display an error message.
Example:
Imagine that the user has quit your program, MegaEdit, and
you want to save the current files, colours, etc:
