In this thread I'd like to clarify, as much as possible, exactly how
Leo handles settings. I'll also propose some "safe rules" that may
help to reduce confusion, especially for power users.
I shall start with the big picture, and then add more details. This
thread will be pre-writing for a revision of Leo's docs.
=====
Settings files are .leo files that contain an @settings node. To be
active, a setting must be a descendant of the first @settings node in
the .leo file.
There are four kinds of settings files:
1. Default settings files called leoSettings.leo.
2. Personal settings files called myLeoSettings.leo.
3. Option files (optionFile): any .leo file (in any location)
specified using Leo's -c command-line option.
4. The .leo file being loaded (loadedFile)
These settings files can be found in the following places:
- homeDir: the user's home directory.
- configDir: The global configuration directory: leo/config.
- machineDir: a machine-specific directory.
- localDir, the directory containing the .leo file being loaded.
The user may specify the location of homeDir and machineDir. (Details
omitted from this post).
When Leo reads a .leo file, Leo looks for settings in default settings
files first, then settings in personal settings files, and finally
settings in local settings files. The exact search order is:
1. Default settings files:
1a. leo/config/leoSettings.leo
1b. homeDir/leoSettings.leo
1c. localDir/leoSettings.leo
2. Personal settings files:
2a. leo/config/myLeoSettings.leo
2b. homeDir/myLeoSettings.leo
3c. homeDir/<machine-name>LeoSettings.leo (note capitalization)
3d. localDir/myLeoSettings.leo
3. Local settings files.
3a. optionFile
3b. loadedFile
Notes:
- For a variety of reasons, the same file might appear several times
in this list. Leo detects such duplicate file names and only loads
each settings file once.
- Leo remembers all the settings in default and personal settings
files and does not reread those settings when reading another .leo
file.
- Settings that appear later in this list override settings that
appear earlier in this list. This happens on a setting-by-setting
basis, *not* on a file-by-file basis. In other words, each individual
setting overrides only the *corresponding* setting in previously-read
files. Reading a setting file does *not* reset all previous settings.
Because options are treated individually, settings that are loaded
first can provide defaults that may be individually overridden by
settings that are loaded later.
- The value of localDir can change when Leo reads additional files.
This can result in Leo finding new default and personal settings
files. The values of these newly-read settings files will, as always,
override any previously-read settings.
To avoid potential confusion, you should use special care when placing
default or personal settings files in "local" directories, that is,
directories other than homeDir, configDir or machineDir. Let us say
that settings file A.leo **covers** settings file if B.leo if all
settings in B.leo occur in A.leo. A safe rule for placing settings
files in local directories is:
Settings files in local directories should
cover all other settings files.
This will ensure that the per-directory defaults specified in the
local settings file will take precedence over all previously-read
default and personal settings files. Ignore this principle at your
peril.
Enabling plugins: a special case
Leo handles @enabled-plugins nodes a bit differently from other kinds
of settings.
Let us distinguish two different situations. First, what Leo does
when
loading a file, say x.leo. Second, what Leo does when loading a
second file, say y.leo, *from x.leo*.
In the first case (when Leo reads x.leo) Leo will enable all plugins
found in the @enabled-plugins node it finds *last* in the search
order. Leo does *not* enable plugins found in any other @enabled-
plugins node. Thus, you can not specify a list of default plugins by
placing that list in a settings file that appears early in the search
list. Instead, the last @enabled-plugins node found in the search
list specifies exactly the desired plugins.
In the second case, when loading y.leo from x.leo, plugins have
**already** been loaded and enabled. There is no way, in general, to
disable previously loaded-and-enabled plugins. But local settings
files can enable additional plugins.
This suggests a similar rule for avoiding confusion with @enabled-
settings files. We can say that an @enabled-plugin node in file A.leo
**covers** an @enabled-plugin node in file B.leo if all plugins
specified in B's @enabled-plugin node appear A's @enabled-plugin
node. The safe rule then becomes:
@enabled-plugin nodes in settings files in local directories
should cover @enabled-plugins nodes in all other settings files.
All comments welcome. I believe the safe rules mentioned here can
eliminate most confusion regarding settings. They should make it
possible to specify reasonable defaults in most situations, even for
power users.
Edward
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"leo-editor" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/leo-editor?hl=en
-~----------~----~----~----~------~----~------~--~---
