How To Install:
---------------

To use SyncBBDB as a stand-alone program, copy the bbdb, SyncBBDB
and SyncUtil directories to someplace on the Perl include path, and
copy the script "bootstrap" to someplace on your PATH.  Run
bootstrap -help for configuration options.

To use SyncBBDB as a PilotManager conduit, either

  - If you're using PilotManager version 1.108 or higher, and you gave
  a -conduitdir argument to PilotManager's Setup.pl script, then copy
  the directories bbdb, SyncBBDB, and SyncUtil and the file
  SyncBBDB.pm to the conduitdir directory.

  - Otherwise, copy the bbdb, SyncBBDB, and SyncUtil directories to
  lib/perl5 inside the PilotManager directory, and copy the file
  SyncBBDB.pm to the top level of the PilotManager directory.

Then run PilotManager, go to File->Properties, move SyncBBDB from
the inactive list to the active list, and click Configure to configure
it.

Other than that things should take care of themselves.  The first time
you sync all your bbdb records will go to the pilot and vice versa.
This may result in many duplicate records in which case you might want
to use the 'bbdb-show-duplicate-records' function in bbdb to help
merge things.



Credits and Contact Information
--------------------

SyncBBDB was written by Thomas DeWeese, and is now maintained by Aaron
Kaplan.  Up-to-date contact information can currently be found at
http://syncbbdb2.sourceforge.net/ .




Directions for users upgrading from 1.x
---------------------------------------
   The easiest way to fully 2.0ify your bbdb is:

1) Sync your palm one last time with the old version of the software.  
2) Shut down PilotManager.
3) Install the 2.x version of SyncBBDB
4) Delete or move your ids file 
   (the pilot mgr default: ~/.pilotmgr/SyncBBDB/ids.<user name>_<pilot id>).
5) Start PilotManager (make sure the version for SyncBBDB is 2.x).
6) Sync your palm again.

   This will make the software think all your records in bbdb are
modified.  It will then proceed to merge all the records with the
pilot records, in the process it will update all the 'pilot-id' fields
in the bbdb records.

   If you don't do this up front, over time, as records are synched,
the 'pilot-id' field will be updated 'as needed'.  Personally I
prefer/recommend the all at once especially since this will force the
creation of the currently lacking multiple pilot records for multiple
addresses (See below).


Version history (see ChangeLog for details):

Version 2.5
-----------

   Aaron Kaplan takes over maintenance of SyncBBDB.

   Fixed major bug: if connection is dropped during sync, entries can be
   erroneously deleted.  You could lose your whole address book this
   way!
	
   Bring "bootstrap" up to date so that it works again.

   More fixes for non-ASCII characters, although you may still have
   problems depending on the combination of encodings used on your
   Palm and your desktop.



Version 2.4
-----------
    Never officially released, but some people downloaded it from
    CVS.  

    It once again deletes records in BBDB when deleted on Pilot.

    Only sets first name, last name and company on pilot if a value
    was given on the pilot (minor issue really). 


Version 2.3
-----------
    Added support for bbdb file format version 6

    Incorperated a fix for bbdb files containing Non-ASCII
chars. Contributed by Aaron Kaplan, thanks!.

    Now updates timestamp, and creates creation-date as appropriate.


Version 2.2
-----------
   Starting with this version if a bbdb record has a note called
'pilot-ignore' the record will not be considered for syncing with your
palm pilot.

   This version also fixes a number of small bugs and inconveniences
in the previous versions.  See ChangeLog for details.

Version 2.1
-----------
   This fixes an apparent problem with fast/slow sync detection.
While I haven't seen an issue here, I did receive a bug report. Even
if what I was doing wasn't wrong it was different from all the other
conduits so I decided to switch methods to be more consistent.

Version 2.0
-----------
   
   Small number of cosmetic/usability improvements from 2.0b3. See
ChangeLog for details.

   First non-beta release of 2.0.  I now consider this more reliable
than the 1.x series in the face of normal modifications over time
(especially new/modified fields).

Version 2.0b3 (Still BETA, but is my main conduit)
-------------

   Fixed a bug that affected the importing of new pilot addresses.

   Added a few more refinements to the StandaloneHost status stuff.

   Changed the format of the BBDB Mapping.  All the pilot and bbdb fields
are now quoted.  This helps to ensure that bbdb 'locations' that have 
spaces in them are ok.  Currently it will read both of them with no
problem however some time in the future I plan to remove support for
the old unquoted format.  So I suggest forcing a full bbdb<->pilot merge
(most easily accomplished by removing your 'ids' file, see below).

   I also added code to 'fix' pilot labels to be valid lisp identifiers
(spaces -> '-', etc).  This is needed because the note labels in bbdb are 
read as lisp identifiers.

   

Version 2.0b2 (Currently BETA use with caution)
-----------

   This represents what I would consider the first fully functional 
implementation of a BBDB<->Pilot conduit.

Major new features:

1) Multiple Pilot records for each BBDB record.
   By default each address in a BBDB record will be mapped to a pilot
   record.  It will associate a phone with a 'location' that matches
   the address location as the primary phone for each address.

   If you change a phone in one pilot record it will be updated in
   the associated BBDB record _and_ all other pilot records that are
   associated with the same BBDB record (assuming they include that 
   phone of course) during the sync operation.

2) Specification of BBDB<->Pilot field mappings.
   There is a new file called 'translate' that lives in the SyncBBDB
   directory for PilotManager (you can specify the file to use for
   'bootstrap').  This file consists of name pairs one per line:
     <pilot field name> <bbdb field name>
   This will be used when trying to see if it is appropriate to put a bbdb 
   field into the pilot, and will be used to determine the name used in for
   Pilot fields.  Note that generally this only applies to future syncs
   So don't change this file and expect everything to suddenly be updated
   in your Pilot.

General Improvements:

   The code is more aggressive about trying to put bbdb fields into the
pilot.  This is most noticeable in conjunction with the field translation file
but even with out it you will likely see more fields translated to the pilot.
than previous versions.

   It now provides feedback as the sync proceeds (most notably when it
is loading the Address database during a full sync).

   The mapping between a BBDB and palm record is editable.  Once the 
initial mapping is made you can adjust it from bbdb.  The complete 
description of the last mapping is stored in a new bbdb field 'pilot-id'.  
The basic format is:

<pilot-id> <Category> <Address>
  <Pilot Field>[:<label #>] <bbdb field type>:(<bbdb field name>|0)
  ...
  <Pilot Field>[:<label #>] <bbdb field type>:(<bbdb field name>|0)
  BBDB-Unused: <comma separated list of unused bbdb fields>

<pilot-id> Don't mess with this...

<category> The category to associate record with (Quoted in 2.0b3)

<address>  The 'location' for the address that is synced into
           the Address, City, State, Zip and Country fields of the record.
           If you don't want to sync an address use '-NO-ADDRESS-'
           (Quoted in 2.0b3)

<Pilot Field> can be any of:
   'Last',    'First',   'Title',   'Company', 'Note'
   'Address', 'City',    'State',   'Zip',     'Country',
   'Field1',  'Field2',  'Field3',  'Field4',  'Field5',
   'Custom1', 'Custom2', 'Custom3', 'Custom4',

    Although, I suggest sticking to Field[1-5] and Custom[1-4] here.

    For fields 'Field[1-5]' you can also set the associated label by 
including a number (0-7) after a colon (I don't use the normal names 
["Work", "Home", "Fax", "E-mail", "Main", "Pager", "Mobile"] because 
I believe they are subject to change - localization).

    Whole thing (field and lable) is quoted in 2.0b3.

<bbdb field type> One of 'phone', 'note', 'aka', 'net'.

<bbdb field name> 
    phone       - this is the 'location' of the phone
    note        - this is the 'label' for the note
    aka and net - this is currently always '0'

    Combination is quoted in 2.0b3.


'BBDB-Unused:' 
    This allows the conduit to detect new fields in the BBDB record
(such as new addresses or phone's that it should consider mapping into
bbdb records).  In retrospect I probably should have put all fields in
here not just the ones that aren't used by any mappings.

    Eventually I hope to write some e-lisp that makes editing this
a bit more straight forward. but hand editing will have to do for now.

Version 1.4 (Branch from 1.3)
-----------
   This fixes a wierd bug where new pilot records that don't have addresses
end up picking up an address from the next new pilot record that has an
address.

   There are also a few small fixes to the bbdbAddr to String method.

Version 1.3
-----------
   This fixes a problem introduced with the support of International
Zip codes.  In the US we have what is called ZIP+4 (a 6 digit zip plus
an additional 4 digit zip).  If One of these was entered on the Palm
the resulting pilot record would have [... 012345-6789 "USA"] The zip
needs to be split into a pair.  The new code will split the zip based
on any combination of dashes and spaces if the zip is comprised
entirely of numbers dashes and spaces (US case, which is not normally
true for international zips as I understand it).
   Other wise it reverts to only splitting on spaces.  If it falls into
this case with only one item in the zip (illegal really) it will
append an empty string to the zips list.  This may lead to slightly
funny formatting, but is at least a valid BBDB zip.

   We really need to switch to a pure string rep for zips.

Version 1.1 & 1.2
-----------------
   If you used 1.0 it is likely that many (all) of your records will
appear as changed in BBDB due to a change in the handling of zip
codes.  The code now attempts to store zip's as strings more of the
time.  This should in the long run at least help with the problem that
currently BBDB tends to drop leading zero's from US Zips for example
01106 -> 1106 :(.  Current I can't do it for single value zips like
the example given since single values must be numbers otherwise BBDB
barfs.

Because of this change US people may be surprised to see addresses
appear in European format (Zip, City, State).  Here is some e-lisp that
helps this problem:

(defun my-bbdb-address-is-us (addr)
  "Return non-nil if address is a US address.
For me that means that country is nil or 'USA?'"
  (let ((country (bbdb-address-country addr)))
    (or (not country)  ;; Country nil -> USA
        (string-equal "" country)
        (string-match "^[uU][sS]" country))))

(setq bbdb-address-formatting-alist
      '((my-bbdb-address-is-us       . bbdb-format-address-default)
        (bbdb-address-is-continental . bbdb-format-address-continental)
        (nil . bbdb-format-address-default)))

Thanks to Kevin Davidson
   He provided several proto-patches to improve handling of
international Phone numbers and zip codes.  He also provided some
example code for handing bbdb version 5.
