diff options
| author | mms <git@sapka.me> | 2024-11-12 23:15:34 +0100 |
|---|---|---|
| committer | mms <git@sapka.me> | 2024-11-12 23:15:34 +0100 |
| commit | 53112538e1f47ed446848c5787a87350a2cc6e31 (patch) | |
| tree | e3257eb5177b855c32f45fab0f697b77980612c7 | |
| parent | 22560fbfbe2214f260c71c0ae5c928f81a431b76 (diff) | |
doc: fix readme
| -rw-r--r-- | README.html | 45 | ||||
| -rw-r--r-- | README.org | 3 | ||||
| -rw-r--r-- | README.txt | 143 |
3 files changed, 24 insertions, 167 deletions
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"> <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> <head> -<!-- 2024-11-12 Tue 23:12 --> +<!-- 2024-11-12 Tue 23:15 --> <meta http-equiv="Content-Type" content="text/html;charset=utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <title>Chotto</title> @@ -201,11 +201,12 @@ <h2>Table of Contents</h2> <div id="text-table-of-contents" role="doc-toc"> <ul> -<li><a href="#org0d48161">1. Naming & Afew</a></li> -<li><a href="#org0154d9d">2. Prerequisites</a></li> -<li><a href="#org8d840c5">3. Configuration</a></li> -<li><a href="#org4259fc2">4. Config</a></li> -<li><a href="#orgb9835ee">5. Rule sets</a></li> +<li><a href="#orgdea3aac">1. Naming & Afew</a></li> +<li><a href="#org94b9395">2. Prerequisites</a></li> +<li><a href="#org0e2ddf0">3. Configuration</a></li> +<li><a href="#org46389b5">4. Config</a></li> +<li><a href="#orgf4ff526">5. Rule sets</a></li> +<li><a href="#org8263f11">6. Filter language</a></li> </ul> </div> </div> @@ -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. </p> -<div id="outline-container-org0d48161" class="outline-2"> -<h2 id="org0d48161"><span class="section-number-2">1.</span> Naming & Afew</h2> +<div id="outline-container-orgdea3aac" class="outline-2"> +<h2 id="orgdea3aac"><span class="section-number-2">1.</span> Naming & Afew</h2> <div class="outline-text-2" id="text-1"> <p> Notmuch ecosystem already has a great script for initial tagging - afew. @@ -237,8 +238,8 @@ And because I love Ruby! </div> </div> -<div id="outline-container-org0154d9d" class="outline-2"> -<h2 id="org0154d9d"><span class="section-number-2">2.</span> Prerequisites</h2> +<div id="outline-container-org94b9395" class="outline-2"> +<h2 id="org94b9395"><span class="section-number-2">2.</span> Prerequisites</h2> <div class="outline-text-2" id="text-2"> <p> Chotto expects: @@ -272,8 +273,8 @@ If you use <b>Windows</b>, you have my sympathy. </div> </div> -<div id="outline-container-org8d840c5" class="outline-2"> -<h2 id="org8d840c5"><span class="section-number-2">3.</span> Configuration</h2> +<div id="outline-container-org0e2ddf0" class="outline-2"> +<h2 id="org0e2ddf0"><span class="section-number-2">3.</span> Configuration</h2> <div class="outline-text-2" id="text-3"> <p> 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 </div> </div> -<div id="outline-container-org4259fc2" class="outline-2"> -<h2 id="org4259fc2"><span class="section-number-2">4.</span> Config</h2> +<div id="outline-container-org46389b5" class="outline-2"> +<h2 id="org46389b5"><span class="section-number-2">4.</span> Config</h2> <div class="outline-text-2" id="text-4"> <p> 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 </div> </div> -<div id="outline-container-orgb9835ee" class="outline-2"> -<h2 id="orgb9835ee"><span class="section-number-2">5.</span> Rule sets</h2> +<div id="outline-container-orgf4ff526" class="outline-2"> +<h2 id="orgf4ff526"><span class="section-number-2">5.</span> Rule sets</h2> <div class="outline-text-2" id="text-5"> <p> The actual magic happens in <code>Rule Sets</code> which are sets of filters & tag modifications. @@ -352,12 +353,12 @@ msg.tags returns a mutable array, and we can mutate is as such. <p> Lastly, we save! the message in the database. </p> +</div> +</div> -<p> -Filter language -</p> -<hr /> - +<div id="outline-container-org8263f11" class="outline-2"> +<h2 id="org8263f11"><span class="section-number-2">6.</span> Filter language</h2> +<div class="outline-text-2" id="text-6"> <p> We can quite easily filter messages based. Chotto accepts filters as: </p> @@ -412,7 +413,7 @@ You can test what is produced by calling <code>#to_query_string</code> on messag </div> <div id="postamble" class="status"> <p class="author">Author: User Mms</p> -<p class="date">Created: 2024-11-12 Tue 23:12</p> +<p class="date">Created: 2024-11-12 Tue 23:15</p> <p class="validation"><a href="https://validator.w3.org/check?uri=referer">Validate</a></p> </div> </body> @@ -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 -- <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. |