2 Getting ASynK and Installation

The official website for ASynK is at: http://asynk.io. You will find links to latest downloads, complete and latest documentaiton, announcements and other information on that website.

The source code for ASynK is hosted on Github at: https://github.com/skarra/AsynK (earlier hosted at: https://github.com/skarra/Gout) Visit the site to grab the bleeding edge development version, or to register an issue you have identified.

2.1 Pre-packaged Bundle

You can download the latest version by visiting the downloads section of the official website at http://asynk.io/downloads/.

2.2 From Source

You can clone the git repository by using a command such as git clone git://github.com/skarra/ASynK.git. Then run asynk.py as per instructions given in the Using ASynK, section below.

2.3 Dependencies / Notes

2.3.1 General Dependencies

Python 2.7. You can download Python from: http://www.python.org/download/releases/
If you want to build the documentation yourself you will need some additional tools:
1. makeinfo: Is needed to build documentation in Info, docbook and xml formats. Version 4.8 is known to work with our sources.
2. texi2html: Is needed to build documentation in html format. Version 1 .70 is known to work with our sources.
3. texi2pdf: Is needed to build the documentation in PDF format. Version 1.34 is known to work with our sources.

2.3.2 Microsoft Exchange Specific Notes

If you want to synchronize to your Exchange Server you could do that from any machine or operating system that can access your Exchange server over the internet. You will need to ask your system administrators for:

Your full email address
Your account password
The exchange mailbox url

2.3.3 Windows / Outlook Specific Notes

If you have contacts on your own machine inside a Outlook PST file you can sycn them too. But there are a few additional dependencies:

Microsoft Windows: You must run ASynK on a Windows machine. Any recent version such as XP onwards will do.
MS Outlook: Outlook should be installed. Direct read/write of PST files is not possible. Any recent version should work. ASynK has been reported to work with Office 2007, Office 2008, Office 2010, Office 2013
Pywin32 for Python 2.7: It is available for download http://sourceforge.net/projects/pywin32/files/pywin32

2.3.4 CardDAV Specific Notes

Keep in mind that unlike Google Contacts, CardDAV servers do not support a roll back feature. This means any ASynK bugs could potentially lead to loss of information for you. While there have been no complaints of ASynK eating up people’s data, please take your own precautions before you deploy this on your live data. The use of the --user-dir= option is also high encouraged.

At the moment the following fields are synched in both ways. More may be supported over time. Important: Fields not mentioned here will be lost in transit!

First name
Last name
Middle name
Formatted name
Suffix, Prefix
Gender
Email addresses
Phone numbers
Title
Department
Company name
Notes

Specifically, the following are not synched:

IM
WWW
Postal Addresses
Custom fields

2.3.5 BBDB Specific Notes

ASynK can parse and write BBDB files without the need for Emacs or BBDB. However, ensure you are NOT using BBDB at the time ASynK is reading/writing the database. Bad things can happen if you are not careful with this. Furthermore, note the following:

BBDB V3: ASynK works best if you use BBDBV3. V3 is the future of BBDB and a significant rewrite of large portions of the code base, but is decidedly not backward compatible with most user customization. You can download it at http://savannah.nongnu.org/projects/bbdb.
Importantly for ASynK, the file format used by V3 provides for granular time stamps with timezone information and ASynK will just work “out of the box”. There are also other important changes to the structure of the BBDB record in file format version 7.
Timestamp Customization: ASynK expects timestamps to be in UTC - i.e. they should all end with the +0000. If you have customized your BBDB timestamp format, it can lead to confusing results.

BBDB-2.x: Starting release v0.2.1 ASynK has added limited support for BBDB file format version 6 which is the latest version used by the 2.x releases of BBDB. This version of BBDB is not actively maintained, but is more widely deployed because of its age and availability on XEmacs.

Support is limited in the sense that the native ver 6 file format timestamps only store year, month and day. So BBDB will overwrite the granular ASynK timestamps with a yyyy-mm-dd timestamp, and your bi-directional sync will not quite work as you would like.

The above limitation can be overcome by applying the following simple patch. With this patch in place ASynK will work quite well. There is a downside, however - certain time-based search in BBDB may behave differently (search newer, search older etc. will behave differently owing to differences in timestamp format). But one would like to think the ability to do bidirectional sync outweighs this minor irritation.

commit eb6ba8d342a46d61c45b0ce4c1de7711ff011466
Author: Sriram Karra <karra.etc@gmail.com>
Date:   Wed May 16 18:09:50 2012 +0530

    Include UTC time as part of timestamp
    
    This is a feature in file format 7 available with BBDB v3. However
    that is not available with the 2.x series. A detailed timestamp
    is needed to do a sync with a third party.
    
    The ideal way would have been to fully implement the version 7
    changes on 2.36. However that involves a lot of changes and is
    risky - for e.g. introducing a new key name field (affix)
    will stretch my understanding of BBDB internals. Best to just
    provide a quick hack for those willing to live with it only to
    try ASynK or similar sync software.
    
    The obvious pitfall is that commands that work on the timestamp
    field (like newer or older filters and delete) will start
    to behave differently because a string comparison is done to
    check if a date is newer or older.
    
       *** You have been warned ***

diff --git a/lisp/bbdb-hooks.el b/lisp/bbdb-hooks.el
index 01de4f2..b9f0d9d 100644
--- a/lisp/bbdb-hooks.el
+++ b/lisp/bbdb-hooks.el
@@ -59,7 +59,7 @@
 (defvar mh-show-buffer)
 
 
-(defvar bbdb-time-internal-format "%Y-%m-%d"
+(defvar bbdb-time-internal-format "%Y-%m-%d %T %z"
   "The internal date format.")
 
 ;;;###autoload
@@ -69,7 +69,7 @@ for the given record which contains the time when it was last modified.  If
 there is such a field there already, it is changed, otherwise it is added."
   (bbdb-record-putprop record 'timestamp (format-time-string
                       bbdb-time-internal-format
-                      (current-time))))
+                      (current-time) t)))
 
 ;;;###autoload
 (defun bbdb-creation-date-hook (record)
@@ -78,7 +78,7 @@ which is the current time string."
   ;; hey buddy, we've known about your antics since the eighties...
   (bbdb-record-putprop record 'creation-date (format-time-string
                           bbdb-time-internal-format
-                          (current-time))))
+                          (current-time) t)))
 
 
 ;;; Determining whether to create a record based on the content of the
diff --git a/lisp/bbdb.el b/lisp/bbdb.el
index cc12045..dabbf05 100644
--- a/lisp/bbdb.el
+++ b/lisp/bbdb.el
@@ -1214,7 +1214,7 @@ from string."
 
 ;;; Address formatting.
 
-(defcustom bbdb-time-display-format "%d %b %Y"
+(defcustom bbdb-time-display-format "%d %b %Y %T %z"
   "The format for the timestamp to be used in the creation-date and
 timestamp fields.  See the documentation for `format-time-string'."
   :group 'bbdb :type 'string)
@@ -1223,11 +1223,13 @@ timestamp fields.  See the documentation for `format-time-string'."
   "Convert a date from the BBDB internal format to the format
 determined by FORMAT (or `bbdb-time-display-format' if FORMAT not
 present).  Returns a string containing the date in the new format."
-  (let ((parts (bbdb-split date "-")))
-    (format-time-string (or format bbdb-time-display-format)
-                        (encode-time 0 0 0 (string-to-number (caddr parts))
-                                     (string-to-number (cadr parts))
-                                     (string-to-number (car parts))))))
+  (format-time-string (or format bbdb-time-display-format)
+		      (condition-case err
+			  (date-to-time date)
+			(error nil
+			       (date-to-time (concat date " 00:00:00
+			       +0000"))))
+		      t))
 
 (defalias 'bbdb-format-record-timestamp 'bbdb-time-convert)
 (defalias 'bbdb-format-record-creation-date 'bbdb-time-convert)

2.4 Building & Installing Documentation

The user documentation is in the directory called doc/ in the root of the ASynK source tree. The main source file is asynk.texi in TexInfo format. HTML, PDF and Info files are available on the project home page at: http://asynk.io

If you wish to build the documentation from source, you can try the Makefile in the documentation directory, like so:

   $ cd doc
   $ make pdf
   $ make       # Builds all the targets
   $ make clean
   $ make distclean

The supported doc types are: ’pdf’, ’html’, ’info’, ’docbook’, and ’text’. You may have to install additional programs like makeinfo, texi2html etc. See the "Dependencies" section above.

This document was generated on November 10, 2017 using texi2html 5.0.