From 952364471243bd044a406b09ca790f048762b015 Mon Sep 17 00:00:00 2001 From: Patrick Totzke Date: Sun, 11 Nov 2018 13:37:54 +0000 Subject: docs: reformat faq the html one is now on top --- docs/source/faq.rst | 122 +++++++++++++++++++++++++++------------------------- 1 file changed, 63 insertions(+), 59 deletions(-) (limited to 'docs') diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 17833a05..75fb5963 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -1,83 +1,87 @@ -FAQ -*** +Frequently Asked Questions +************************** -1. Why reinvent the wheel? Why not extend an existing MUA to work nicely with notmuch? +.. _faq_1: +.. rubric:: 1. Help! I don't see `text/html` content! - alot makes use of existing solutions where possible: It does not fetch, send or edit - mails; it lets `notmuch `_ handle your mailindex and uses a - `toolkit `_ to render its display. You are responsible for - `automatic initial tagging `_. +You need to set up a mailcap entry to declare an external renderer for `text/html`. +Try `w3m `_ and put the following into your +:file:`~/.mailcap`:: - This said, there are few CLI MUAs that could be easily and naturally adapted to using notmuch. - Rebuilding an interface from scratch using `friendly and extensible tools `_ - seemed easier and more promising. + text/html; w3m -dump -o document_charset=%{charset} '%s'; nametemplate=%s.html; copiousoutput - Update: see `mutt-kz `_ for a fork of mutt.. +Most `text based browsers `_ have +a dump mode that can be used here. -2. What's with the snotty name? +.. _faq_2: +.. rubric:: 2. Why reinvent the wheel? Why not extend an existing MUA to work nicely with notmuch? - It's not meant to be presumptuous. I like the dichotomy; I like to picture the look on - someone's face who reads the :mailheader:`User-Agent` header "notmuch/alot"; I like cookies; I like - `this comic strip `_. +alot makes use of existing solutions where possible: It does not fetch, send or edit +mails; it lets `notmuch `_ handle your mailindex and uses a +`toolkit `_ to render its display. You are responsible for +`automatic initial tagging `_. -3. I want feature X! +This said, there are few CLI MUAs that could be easily and naturally adapted to using notmuch. +Rebuilding an interface from scratch using `friendly and extensible tools `_ +seemed easier and more promising. - Me too! Feel free to file a new or comment on existing - `issues `_ if you don't want/have the time/know how to - implement it yourself. Be verbose as to how it should look or work when it's finished and - give it some thought how you think we should implement it. We'll discuss it from there. +Update: see `mutt-kz `_ for a fork of mutt.. -4. Why are the default key bindings so counter-intuitive? +.. _faq_3: +.. rubric:: 3. What's with the snotty name? - Be aware that the bindings for all modes are :ref:`fully configurable `. - That said, I choose the bindings to be natural for me. I use `vim `_ and - `pentadactyl `_ a lot. However, I'd be - interested in discussing the defaults. If you think your bindings are more intuitive or - better suited as defaults for some reason, don't hesitate to send me your config. The same - holds for the theme settings you use. Tell me. Let's improve the defaults. +It's not meant to be presumptuous. I like the dichotomy; I like to picture the look on +someone's face who reads the :mailheader:`User-Agent` header "notmuch/alot"; I like cookies; I like +`this comic strip `_. -5. Help! I don't see `text/html` content! +.. _faq_4: +.. rubric:: 4. I want feature X! - better: How do I properly set up an inline renderer for `text/html`? - Try `w3m `_ and put the following into your - :file:`~/.mailcap`:: +Me too! Feel free to file a new or comment on existing +`issues `_ if you don't want/have the time/know how to +implement it yourself. Be verbose as to how it should look or work when it's finished and +give it some thought how you think we should implement it. We'll discuss it from there. - text/html; w3m -dump -o document_charset=%{charset} '%s'; nametemplate=%s.html; copiousoutput +.. _faq_5: +.. rubric:: 5. Why are the default key bindings so counter-intuitive? - Most `text based browsers `_ have - a dump mode that can be used here. +Be aware that the bindings for all modes are :ref:`fully configurable `. +That said, I choose the bindings to be natural for me. I use `vim `_ and +`pentadactyl `_ a lot. However, I'd be +interested in discussing the defaults. If you think your bindings are more intuitive or +better suited as defaults for some reason, don't hesitate to send me your config. The same +holds for the theme settings you use. Tell me. Let's improve the defaults. -6. Why are you doing $THIS not $THAT way? +.. _faq_6: +.. rubric:: 6. Why are you doing $THIS not $THAT way? - Lazyness and Ignorance: In most cases I simply did not or still don't know a better solution. - I try to outsource as much as I can to well established libraries and be it only to avoid - having to read rfc's. But there are lots - of tasks I implemented myself, possibly overlooking a ready made and available solution. - Twisted is such a feature-rich but gray area in my mind for example. - If you think you know how to improve the current implementation let me know! +Lazyness and Ignorance: In most cases I simply did not or still don't know a better solution. +I try to outsource as much as I can to well established libraries and be it only to avoid +having to read rfc's. But there are lots +of tasks I implemented myself, possibly overlooking a ready made and available solution. +Twisted is such a feature-rich but gray area in my mind for example. +If you think you know how to improve the current implementation let me know! - The few exceptions to above stated rule are the following: +The few exceptions to above stated rule are the following: - * The modules cmd and cmd2, that handle all sorts of convenience around command objects - hate urwid: They are painfully strongly coupled to user in/output via stdin and out. - * `notmuch reply` is not used to format reply messages because 1. it is not offered by - notmuch's library but is a feature of the CLI. This means we would have to call the notmuch - binary, something that is avoided where possible. 2. As there is no `notmuch forward` equivalent, - this (very similar) functionality would have to be re-implemented anyway. +* The modules cmd and cmd2, that handle all sorts of convenience around command objects + hate urwid: They are painfully strongly coupled to user in/output via stdin and out. +* `notmuch reply` is not used to format reply messages because 1. it is not offered by + notmuch's library but is a feature of the CLI. This means we would have to call the notmuch + binary, something that is avoided where possible. 2. As there is no `notmuch forward` equivalent, + this (very similar) functionality would have to be re-implemented anyway. .. _faq_7: +.. rubric:: 7. I thought alot ran on Python 2? -7. I thought alot ran on Python 2? - - It used to. When we made the transition to Python 3 we didn't maintain - Python 2 support. If you still need Python 2 support the 0.7 release is your - best bet. +It used to. When we made the transition to Python 3 we didn't maintain +Python 2 support. If you still need Python 2 support the 0.7 release is your +best bet. .. _faq_8: +.. rubric:: 8. I thought alot used twisted? -8. I thought alot used twisted? - - It used to. After we switched to python 3 we decided to switch to asyncio, - which reduced the number of dependencies we have. Twisted is an especially - heavy dependency, when we only used their async mechanisms, and not any of - the other goodness that twisted has to offer. +It used to. After we switched to python 3 we decided to switch to asyncio, +which reduced the number of dependencies we have. Twisted is an especially +heavy dependency, when we only used their async mechanisms, and not any of +the other goodness that twisted has to offer. -- cgit v1.2.3