1 files changed, 143 insertions, 0 deletions
diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..aabe8a7
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,143 @@
+                               __________
+
+                                 CHOTTO
+
+                                User Mms
+                               __________
+
+
+Table of Contents
+_________________
+
+1. Naming & Afew
+2. Prerequisites
+3. Configuration
+4. Config
+5. Rule sets
+
+
+Chotto is an initial tagging script for Notmuch
+- <http://notmuchmail.org/>
+- <http://notmuchmail.org/initial_tagging/>
+
+Chotto is written in Ruby and had a (quite) nice DSL for configuration.
+
+
+1 Naming & Afew
+===============
+
+  Notmuch ecosystem already has a great script for initial tagging -
+  afew.  However it is written in Python and therefore it's always a
+  gamble if it will consider the user worthy or running.
+
+  Chotto, `a few' in Japanese.  Because afew refused to work on my
+  system.  And because I love Ruby!
+
+
+2 Prerequisites
+===============
+
+  Chotto expects:
+  - ruby 3x
+  - notmuch
+  - notmuch ruby bindings.
+
+  While the first 2 are obvious, getting ruby bindings to work may be an
+  adventure on its own.
+
+  *FreeBSD* provides a ready package `ruby-notmuch'.
+
+  *MacOS* requires compiling from source, which will be problematic due
+  to linking difficulties.  It's not an OS designed for technical folks.
+
+  Some *Linux* distros provide the bindings in their package managers,
+  but otherwise compiling should be easy.
+
+  If you use *Windows*, you have my sympathy.
+
+
+3 Configuration
+===============
+
+  Chotto expects the configuration file to be present in
+
+  `~/.config/chotto/config.rb'
+
+  The user needs to add (at least) two blocks to the file: config & rule
+  sets
+
+
+4 Config
+========
+
+  Presently, the only option Config expects is the absolute path to the
+  Notmuch database:
+
+  Chotto.configure do config.database_path = `/home/<user>/mail' end
+
+  Please, adjust the path to the valid location
+
+
+5 Rule sets
+===========
+
+  The actual magic happens in `Rule Sets' which are sets of filters &
+  tag modifications.  A very simple rule set can look like:
+
+  ,----
+  | Chotto.rule_set "notes" do
+  |   messages.filter(from: "<my email>").each do |msg|
+  |      msg.tags << "note" 
+  |      msg.save!
+  |   end
+  | end
+  `----
+
+  Let's break it down.
+
+  First, we define a named `rule_set'.  The name can be a string or a
+  hash and is currently not used anywhere.  It makes it easier to
+  manager bigger rule sets.
+
+  Then we search for messages.  In this case, we want all messages sent
+  from `<my email>' .
+
+  After, we loop over each found message.
+
+  msg.tags returns a mutable array, and we can mutate is as such.
+
+  Lastly, we save! the message in the database.
+
+  Filter language
+  ----------------------------------------------------------------------
+
+  We can quite easily filter messages based. Chotto accepts filters as:
+  - Strings (from(`Subject:Hired!')).  The string will not be modified.
+  - Hash with string values (from(subject: `Hired')).  The key of each
+    hash element is a modified header value - it's down cased, and `-'
+    becomes `_', therefore:
+    - `X-Spam-Id' becomes `x_spam_id'
+    - `X-Thread-Id' becomes `x_thread_id'
+
+    The values on the other hand can be:
+    - String.  Kind of obvious.
+    - Array.  Arrays here are treated as the current conjunctions.  The
+      default conjunction here is `OR', so `k: [1,2]' will become `key:1
+      OR key:2'
+
+    User can add multiple elements to the hash, and they will be join in
+    the current conjunction mode.  By default the mode is `AND',
+    therefore:
+
+    {key: 'val1', key2: 'val2'} are treated as `key:val1 AND key2:val2'.
+
+    `filter' returns self, therefore we can combine multiple filters
+    `filter(key1: 'val').filter(key2: 'val2')'.  Filters will be joined
+    in the current conjunction mode.
+
+    Conjunction mode can be changed using the `or' and `and' methods:
+    filter(key1: `val1').or.filter(key2: `val2').
+
+    The language is simple, but gives huge chances to go wrong.  You can
+    test what is produced by calling `#to_query_string' on messages
+    instance.