Configuration Files in PalmPython 0.5.0
---------------------------------------

Recently, there have been discussions on the pilot-unix mailing list
about a common configuration file format for Palm-aware applications
on Unix, which would eliminate the need for every program to have its
own method of setting basic information like ports, default user
names, and so forth.  Version 0.5.0 of PalmPython has a new
configuration file system as a first try at something which will be
more generally useful than the previous exec-and-pickle one.

The basic file format resembles a Windows INI file (yeah, I know, but
it's easy to parse).  Each section begins with a name in brackets, and
each line includes a variable=value pair.  For example:

  [defaults]
  port = /dev/pilot
  user = Rob Tillotson

The gritty details have not been finalized yet; at present, I assume
that whitespace is insignificant at the beginning and end of lines and
around the '=', that continuation lines are not allowed, and that a
list of values can be specified by adding another 'variable=value'
pair with the same name.  (For example, if you have three cradles, you
can have three 'port' lines.)

When the configuration is loaded, PalmPython first looks in
/etc/palm.conf, then in ~/.palm.conf, and finally (once the PalmOS
user name has been determined) in the data directory (see below) for a
user-specific configuration file.  Each of these overrides the
previous one in the sequence, on a variable by variable basis.

It is expected that /etc/palm.conf will specify port settings only,
and that user name/id settings will go in ~/.palm.conf.

**** These details -- and the names of options discussed below --
**** might change in the near future!

Options:

  The [defaults] section can contain the following options.

    port
      The name of a port a cradle is connected to

    default-port
      The port to use by default.  If not specified, uses the first
      one listed, or just /dev/pilot.

    user
      The default user name.

    uid
      The default user ID. (See "A note about user IDs" below.)

    data-directory
      The location of the common data directory (See "The data
      directory" below.).  Default is /var/palm.

  The [PalmPython] section contains options for all PalmPython
  conduits et. al.  In general, you can set a conduit option by
  appending 'Conduit.<conduit-name>.' to it.  For instance,

    Conduit.Backup.incremental = 1

  sets the 'incremental' option for the Backup conduit.

  IN addition, the variable 'HotSync.conduits' is a comma-separated
  list of conduit names (case sensitive, and matching their names in
  the Conduits subpackage) which will be run during a HotSync session,
  for example:

    HotSync.conduits = TimeSync, Backup, Install


The Data Directory:

  PalmPython assumes the presence of a common data directory, which
  contains both general and application-specific sections.  It can be
  in each user's home directory, or you can share it, which might be
  useful if you have multiple machines with cradles used by multiple
  users.

  The data directory contains a subdirectory for each PalmOS user.
  Inside that, there is a configuration file (called palm.conf, of
  course) and subdirectories called "backup" and "install".

  The "backup" directory holds PalmOS databases; it should represent a
  backup of the device.  The "install" directory should hold PalmOS
  databases waiting to be installed on the next sync run.  Note that
  when I says "holds PalmOS databases", I mean that nothing else
  should go in these directories; application-specific stuff should go
  elsewhere.

  If PalmPython ever has any application-specific stuff to put in the
  data directory, it will go in a subdirectory (alongside "backup" and
  "install") called "PalmPython".  A useful convention might be that
  each package can create a directory like this, using the same name
  it uses to find its own options in the configuration files.


A Note About User IDs:

  Technically, the numeric user id is part of the unique
  identification of a PalmOS user.  However, it is my opinion that in
  the majority of cases, it is redundant.  As long as I am the only
  "Rob Tillotson" syncing to my machine, the name alone should be
  enough to match me with my data.  Even in a multi-user environment,
  it is likely that there won't be more than one person with the same
  PalmOS user name, barring special circumstances like a fleet of
  identically-configured Pilots.

  As a result, PalmPython mostly ignores the numeric ID.  However, if
  you want to require it, you can add it to the user name when
  creating the user-specific data directory.  For instance, instead of
  /var/palm/Rob Tillotson/, you might create
  /var/palm/Rob Tillotson.12345/.  PalmPython will try to locate
  the correct user directory using both the ID and name, before
  falling back on the name alone.

  Note that PalmPython's user handling is currently not very robust,
  in part because I'm not entirely sure how to handle odd situations.
  I plan to write a "user manager" with a nice interface to creating
  user directories, installing user names on the device,
  etc.... suggestions on semantics for dealing with PalmOS users are
  welcome.
