On Fri, Jan 16, 2009 at 9:45 AM, Edward K. Ream <[email protected]> wrote: > > 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.
Maybe some simplification is possible. What is the rationale for 'leoSettings.leo' in home or local? I would consider config in those locations to be, by definition, mine. Come to think of it, what is the need for both names, leoSettings.leo and myLeoSettings.leo? The only reason I can think of for 2 names is to allow both files to exist in the same directory. When would this be needed? What use cases would be unmet if Leo settings files were always named leoSettings.leo? Thanks, Kent > > 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 -~----------~----~----~----~------~----~------~--~---
