From 53112538e1f47ed446848c5787a87350a2cc6e31 Mon Sep 17 00:00:00 2001 From: mms Date: Tue, 12 Nov 2024 23:15:34 +0100 Subject: doc: fix readme --- README.html | 45 +++++++++---------- README.org | 3 +- README.txt | 143 ------------------------------------------------------------ 3 files changed, 24 insertions(+), 167 deletions(-) delete mode 100644 README.txt diff --git a/README.html b/README.html index a4c1b26..f037bc6 100644 --- a/README.html +++ b/README.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Chotto @@ -201,11 +201,12 @@

Table of Contents

@@ -221,8 +222,8 @@ Chotto is an initial tagging script for Notmuch Chotto is written in Ruby and had a (quite) nice DSL for configuration.

-
-

1. Naming & Afew

+
+

1. Naming & Afew

Notmuch ecosystem already has a great script for initial tagging - afew. @@ -237,8 +238,8 @@ And because I love Ruby!

-
-

2. Prerequisites

+
+

2. Prerequisites

Chotto expects: @@ -272,8 +273,8 @@ If you use Windows, you have my sympathy.

-
-

3. Configuration

+
+

3. Configuration

Chotto expects the configuration file to be present in @@ -289,8 +290,8 @@ The user needs to add (at least) two blocks to the file: config & rule sets

-
-

4. Config

+
+

4. Config

Presently, the only option Config expects is the absolute path to the Notmuch database: @@ -308,8 +309,8 @@ Please, adjust the path to the valid location

-
-

5. Rule sets

+
+

5. Rule sets

The actual magic happens in Rule Sets which are sets of filters & tag modifications. @@ -352,12 +353,12 @@ msg.tags returns a mutable array, and we can mutate is as such.

Lastly, we save! the message in the database.

+
+
-

-Filter language -

-
- +
+

6. Filter language

+

We can quite easily filter messages based. Chotto accepts filters as:

@@ -412,7 +413,7 @@ You can test what is produced by calling #to_query_string on messag

Author: User Mms

-

Created: 2024-11-12 Tue 23:12

+

Created: 2024-11-12 Tue 23:15

Validate

diff --git a/README.org b/README.org index 5a8b406..532a239 100644 --- a/README.org +++ b/README.org @@ -76,8 +76,7 @@ msg.tags returns a mutable array, and we can mutate is as such. Lastly, we save! the message in the database. -Filter language ------------------------------------------- +* Filter language We can quite easily filter messages based. Chotto accepts filters as: - Strings (from(=Subject:Hired!=)). diff --git a/README.txt b/README.txt deleted file mode 100644 index aabe8a7..0000000 --- a/README.txt +++ /dev/null @@ -1,143 +0,0 @@ - __________ - - 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 -- -- - -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//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: "").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 `' . - - 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. -- cgit v1.2.3