1 files changed, 128 insertions, 0 deletions
diff --git a/vendor/ruby-msg/README b/vendor/ruby-msg/README
new file mode 100644
index 000000000..bd16dfcc4
--- /dev/null
+++ b/vendor/ruby-msg/README
@@ -0,0 +1,128 @@
+= Introduction
+
+Generally, the goal of the project is to enable the conversion of
+msg and pst files into standards based formats, without reliance on
+outlook, or any platform dependencies. In fact its currently <em>pure
+ruby</em>, so it should be easy to get running.
+
+It is targeted at people who want to migrate their PIM data from outlook,
+converting msg and pst files into rfc2822 emails, vCard contacts,
+iCalendar appointments etc. However, it also aims to be a fairly complete
+mapi message store manipulation library, providing a sane model for
+(currently read-only) access to msg and pst files (message stores).
+
+I am happy to accept patches, give commit bits etc.
+
+Please let me know how it works for you, any feedback would be welcomed.
+
+= Features
+
+Broad features of the project:
+
+* Can be used as a general mapi library, where conversion to and working
+  on a standard format doesn't make sense.
+
+* Supports conversion of messages to standard formats, like rfc2822
+  emails, vCard, etc.
+
+* Well commented, and easily extended.
+
+* Basic RTF converter, for providing a readable body when only RTF
+  exists (needs work)
+
+* RTF decompression support included, as well as HTML extraction from
+  RTF where appropriate (both in pure ruby, see <tt>lib/mapi/rtf.rb</tt>)
+
+* Support for mapping property codes to symbolic names, with many
+  included.
+
+Features of the msg format message store:
+
+* Most key .msg structures are understood, and the only the parsing
+  code should require minor tweaks. Most of remaining work is in achieving
+  high-fidelity conversion to standards formats (see [TODO]).
+
+* Supports both types of property storage (large ones in +substg+
+  files, and small ones in the +properties+ file.
+
+* Complete support for named properties in different GUID namespaces.
+
+* Initial support for handling embedded ole files, converting nested
+  .msg files to message/rfc822 attachments, and serializing others
+  as ole file attachments (allows you to view embedded excel for example).
+
+Features of the pst format message store:
+
+* Handles both Outlook 1997 & 2003 format pst files, both with no-
+  and "compressible-" encryption.
+
+* Understanding of the file format is still very superficial.
+
+= Usage
+
+At the command line, it is simple to convert individual msg or pst
+files to .eml, or to convert a batch to an mbox format file. See mapitool
+help for details:
+
+  mapitool -si some_email.msg > some_email.eml
+  mapitool -s *.msg > mbox
+
+There is also a fairly complete and easy to use high level library
+access:
+
+  require 'mapi/msg'
+  
+  msg = Mapi::Msg.open filename
+  
+  # access to the 3 main data stores, if you want to poke with the msg
+  # internals
+  msg.recipients
+  # => [#<Recipient:'\'Marley, Bob\' <bob.marley@gmail.com>'>]
+  msg.attachments
+  # => [#<Attachment filename='blah1.tif'>, #<Attachment filename='blah2.tif'>]
+  msg.properties
+  # => #<Properties ... normalized_subject='Testing' ... 
+  # creation_time=#<DateTime: 2454042.45074714,0,2299161> ...>
+
+To completely abstract away all msg peculiarities, convert the msg
+to a mime object. The message as a whole, and some of its main parts
+support conversion to mime objects.
+
+  msg.attachments.first.to_mime
+  # => #<Mime content_type='application/octet-stream'>
+  mime = msg.to_mime
+  puts mime.to_tree
+  # =>
+  - #<Mime content_type='multipart/mixed'>
+    |- #<Mime content_type='multipart/alternative'>
+    |  |- #<Mime content_type='text/plain'>
+    |  \- #<Mime content_type='text/html'>
+    |- #<Mime content_type='application/octet-stream'>
+    \- #<Mime content_type='application/octet-stream'>
+  
+  # convert mime object to serialised form,
+  # inclusive of attachments etc. (not ideal in memory, but its wip).
+  puts mime.to_s
+
+= Thanks
+
+* The initial implementation of parsing msg files was based primarily
+  on msgconvert.pl[http://www.matijs.net/software/msgconv/].
+
+* The basis for the outlook 97 pst file was the source to +libpst+.
+
+* The code for rtf decompression was implemented by inspecting the
+  algorithm used in the +JTNEF+ project.
+
+= Other
+
+For more information, see
+
+* TODO
+
+* MsgDetails[http://code.google.com/p/ruby-msg/wiki/MsgDetails]
+
+* PstDetails[http://code.google.com/p/ruby-msg/wiki/PstDetails]
+
+* OleDetails[http://code.google.com/p/ruby-ole/wiki/OleDetails]
+