flesh out readme

Gemfile.lock

@@ -1,14 +1,14 @@
 GIT
   remote: https://github.com/tmaher/corefoundation.git
-  revision: 73a97c6e7d268d21d17f671c94e98185153c5e3f
+  revision: e4cb21a7985577c44cd0aa8f9f17e9b6b6e09141
   specs:
     corefoundation (0.1.4)
       ffi
 
 PATH
   remote: .
   specs:
-    yakg (0.0.0)
+    yakg (0.0.1)
       corefoundation
       ffi
 
@@ -24,7 +24,7 @@ GEM
       rspec-core (~> 2.12.0)
       rspec-expectations (~> 2.12.0)
       rspec-mocks (~> 2.12.0)
-    rspec-core (2.12.0)
+    rspec-core (2.12.1)
     rspec-expectations (2.12.0)
       diff-lcs (~> 1.1.3)
     rspec-mocks (2.12.0)

README.md

@@ -65,3 +65,35 @@ irb(main):007:0> Yakg.list "awesome other service"
 => ["user1", "harry.bovik"]
 ```
 
+Technical Details
+=================
+
+This gem wrapps Apple's Security Framework (a C library) using the
+excellent `ffi` gem. References for the full Keychain Services API can
+be found at
+https://developer.apple.com/library/mac/#documentation/security/Reference/keychainservices/Reference/reference.html
+
+My views on the virtues of wrapping Security Framework and calling it
+from the Ruby process, as opposed to use of helper programs such as
+`git-password`, can be found at https://gist.github.com/4116645
+
+
+Related Work
+============
+
+* https://github.com/xli/mac-keychain also wraps Security Framework
+  but with RubyCocoa. That makes it more difficult to use with local
+  Ruby builds
+
+* https://github.com/seattlerb/osx_keychain uses RubyInline to call
+  into the underlying C library. That necessitates a C compiler.
+
+* https://github.com/jprichardson/keychain_manager shells out to call
+  the `security` CLI tool.  It's also less oriented around password
+  management, and more geared towards PKI.
+
+* https://github.com/fcheung/keychain also wraps Security Framework
+  with ffi.  It's far more feature-complete than Yakg, but I wanted a
+  more minimalist API. Both approaches absolutely have their place.
+  Yakg shares some code, specifically fcheung/corefoundation for error
+  message string handling, and I am indebted to Mr. Cheung for it.