Skip to content

Commit

Permalink
documentation: installation and usage in docs/
Browse files Browse the repository at this point in the history 
The instructions in README.rst duplicated some of the information in
the more complete docs, but not enough to really get started using
afew. It is better to avoid duplication and refer new users directly
to the full documentation.

The README.rst installation instructions were slightly more complete
and recent, so they were copied to the
docs/sources/installation.rst.

While at it, fix broken links in the rst markup.

Fixes: afewmail/afew/afewmail#23.
  • Loading branch information
@pohly
pohly committed Apr 11, 2018
1 parent d4232f4 commit 9a88445
Show file tree
Hide file tree
Showing 2 changed files with 29 additions and 187 deletions.
184 changes: 8 additions & 176 deletions README.rst
View file
Expand Up @@ -32,8 +32,9 @@ fyi: afew plays nicely with alot, a GUI for notmuch mail ;)
IRC
---

Feel free to ask your questions and discuss usage in the [#afewmail IRC Channel](http://webchat.freenode.net/?channels=#afewmail) on freenode.
Feel free to ask your questions and discuss usage in the `#afewmail IRC Channel`_ on freenode.

.. _#afewmail IRC Channel: http://webchat.freenode.net/?channels=#afewmail


Features
Expand All @@ -53,183 +54,14 @@ Features



Installation
------------
Installation and Usage
----------------------

Make sure you have already installed your distribution's `notmuch`
package, and the notmuch python bindings, which might come in separate
`python-notmuch` and `python3-notmuch` packages.

Note: if you are installing `notmuch` using Homebrew on macOS, make sure
to run ``$ brew install --with-python3 notmuch``, because the brew formula
doesn't install python3 notmuch bindings by default.

It is recommended to install `afew` itself inside a virtualenv as an unprivileged
user, either via checking out the source code and installing via setup.py, or
via pip.

.. code:: bash
# create and activate virtualenv
$ python -m venv --system-site-packages .venv
$ source .venv/bin/activate
# install via pip from PyPI:
$ pip install afew
# or install from source:
$ python setup.py install
You might want to symlink `.venv/bin/afew` somewhere inside your path
(~/bin/ in this case):

.. code:: bash
$ ln -snr .venv/bin/afew ~/.bin/afew
Configuration
-------------

Make sure that ``~/.notmuch-config`` reads:

.. code:: ini
[new]
tags=new
Put a list of filters into ``~/.config/afew/config``:

.. code:: ini
# This is the default filter chain
[SpamFilter]
[KillThreadsFilter]
[ListMailsFilter]
[ArchiveSentMailsFilter]
[InboxFilter]
And configure rules to sort mails on your disk, if you want:

.. code:: ini
[MailMover]
folders = INBOX Junk
max_age = 15
# rules
INBOX = 'tag:spam':Junk 'NOT tag:inbox':Archive
Junk = 'NOT tag:spam AND tag:inbox':INBOX 'NOT tag:spam':Archive
Commandline help
----------------

.. code:: ini
$ afew --help
Usage: afew [options] [--] [query]
Options:
-h, --help show this help message and exit
Actions:
Please specify exactly one action.
-t, --tag run the tag filters
-m, --move-mails move mail files between maildir folders
Query modifiers:
Please specify either --all or --new or a query string.
-a, --all operate on all messages
-n, --new operate on all new messages
General options:
-C NOTMUCH_CONFIG, --notmuch-config=NOTMUCH_CONFIG
path to the notmuch configuration file [default:
$NOTMUCH_CONFIG or ~/.notmuch-config]
-e ENABLE_FILTERS, --enable-filters=ENABLE_FILTERS
filter classes to use, separated by ',' [default:
filters specified in afew's config]
-d, --dry-run don't change the db [default: False]
-R REFERENCE_SET_SIZE, --reference-set-size=REFERENCE_SET_SIZE
size of the reference set [default: 1000]
-T DAYS, --reference-set-timeframe=DAYS
do not use mails older than DAYS days [default: 30]
-v, --verbose be more verbose, can be given multiple times
Boring stuff
============

Simulation
----------
Adding ``--dry-run`` to any ``--tag`` or ``--sync-tags`` action prevents
modification of the notmuch db. Add some ``-vv`` goodness to see some
action.



Initial tagging
---------------
Basic tagging stuff requires no configuration, just run

.. code:: bash
$ afew --tag --new
To do this automatically you can add the following hook into your
``~/.offlineimaprc``:

.. code:: ini
postsynchook = ionice -c 3 chrt --idle 0 /bin/sh -c "notmuch new && afew --tag --new"
Tag filters
-----------
Tag filters are plugin-like modules that encapsulate tagging
functionality. There is a filter that handles the archiving of mails
you sent, one that handles spam, one for killed threads, one for
mailing list magic...

The tag filter concept allows you to easily extend afew's tagging
abilities by writing your own filters. Take a look at the default
configuration file (``afew/defaults/afew.config``) for a list of
available filters and how to enable filters and create customized
filter types.



Move mode
---------

To invoke afew in move mode, provide the ``--move-mails`` option on the
command line. Move mode will respect ``--dry-run``, so throw in
``--verbose`` and watch what effects a real run would have.

In move mode, afew will check all mails (or only recent ones) in the
configured maildir folders, deciding whether they should be moved to
another folder.

The decision is based on rules defined in your config file. A rule is
bound to a source folder and specifies a target folder into which a
mail will be moved that is matched by an associated query.

This way you will be able to transfer your sorting principles roughly
to the classic folder based maildir structure understood by your
traditional mail server. Tag your mails with notmuch, call afew
``--move-mails`` in an offlineimap presynchook and enjoy a clean inbox
in your webinterface/GUI-client at work.

For information on how to configure rules for move mode, what you can
do with it and what you can't, please refer to ``docs/move_mode``.
Full documentation is available in the `docs/source`_ directory and in
rendered form at afew.readthedocs.io_.

.. _afew.readthedocs.io: https://afew.readthedocs.io/en/latest
.. _docs/source: docs/source/

Have fun :)

Expand Down
32 changes: 21 additions & 11 deletions docs/source/installation.rst
View file
Expand Up @@ -11,23 +11,33 @@ On Debian/Ubuntu systems you can install these by doing:
$ sudo aptitude install notmuch python-notmuch python-dev python-setuptools
Note: if you are installing `notmuch` using Homebrew on macOS, make sure
to run ``$ brew install --with-python3 notmuch``, because the brew formula
doesn't install python3 notmuch bindings by default.

Unprivileged Install
--------------------

And I'd like to suggest to install afew as your unprivileged user.
It is recommended to install `afew` itself inside a virtualenv as an unprivileged
user, either via checking out the source code and installing via setup.py, or
via pip.

.. code-block:: sh
.. code:: bash
$ python setup.py install --prefix=~/.local
$ mkdir -p ~/.config/afew
# create and activate virtualenv
$ python -m venv --system-site-packages .venv
$ source .venv/bin/activate
If you do, make sure `~/.local/bin` is in your path, say by putting the
following in your `~/.bashrc`:
# install via pip from PyPI:
$ pip install afew
.. code-block:: sh
# or install from source:
$ python setup.py install --prefix=~/.local
You might want to symlink `.venv/bin/afew` somewhere inside your path
(~/bin/ in this case):

if [ -d ~/.local/bin ]; then
PATH=$PATH:~/.local/bin
fi
.. code:: bash
If you want to do a system wide install you can leave off the `--prefix` option.
$ ln -snr .venv/bin/afew ~/.bin/afew

0 comments on commit 9a88445

Please sign in to comment.