</listitem>
</itemizedlist>
</sect2>
+ </sect1>
+
+ <sect1 id="custom-tags">
+ <title>Custom backend based Tags Feature</title>
+ <subtitle>Implements with Notmuch tag and Imap keywords</subtitle>
+
+ <sect2 id="custom-tags-support">
+ <title>Support</title>
+ <para>
+ <emphasis role="bold">Since:</emphasis>NeoMutt 2017-10-16</para>
+ <para>
+ <emphasis role="bold">Dependencies:</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <link linkend="quasi-delete">quasi-delete feature</link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="index-color">index-color feature</link>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="custom-tags-intro">
+ <title>Introduction</title>
+ <para>Some backend allow to indexes and tags mail without storing the
+ tags within the mail envelope. Two backends are currently
+ implementing this feature. Notmuch handles them natively. And Imap stores them
+ in custom Imap keywords.</para>
+ </sect2>
+
+ <sect2 id="custom-tags-variables">
+ <title>Variables</title>
+
+ <table id="table-custom-tags-variables">
+ <title>Custom tags Variables</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Type</entry>
+ <entry>Default</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>hidden_tags</literal>
+ </entry>
+ <entry>string</entry>
+ <entry>
+ <literal>
+ unread,draft,flagged,passed,replied,attachment,signed,encrypted</literal>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect2>
+
+ <sect2 id="custom-tags-functions">
+ <title>Functions</title>
+ <para>Notmuch adds the following functions to NeoMutt. By default, none of
+ them are bound to keys.</para>
+
+ <table id="table-custom-tags-functions">
+ <title>Notmuch Functions</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Menus</entry>
+ <entry>Function</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>index,pager</entry>
+ <entry>
+ <literal><modify-labels></literal>
+ </entry>
+ <entry>add, remove, or toggle tags:
+ Imap: edit the tags list
+ Notmuch: [+]<tag> to add,
+ -<tag> to remove, !<tag> to toggle(notmuch) tags.
+ Note: Tab completion of tag names is available</entry>
+ </row>
+ <row>
+ <entry>index,pager</entry>
+ <entry>
+ <literal><modify-labels-then-hide></literal>
+ </entry>
+ <entry>add, remove, or toggle tags
+ Imap: edit the tags list
+ Notmuch: [+]<tag> to
+ add, -<tag> to remove, !<tag> to togglelabels and
+ then hide or unhide the message by changing the "quasi-deleted"
+ to match if it would be shown when requerying.
+ Normal redisplay rules apply here, so the user must call
+ <sync-mailbox> for the changes to be displayed. Note:
+ Tab completion of tag names is available.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect2>
+
+ <sect2 id="custom-tags-commands">
+ <title>Commands</title>
+ <cmdsynopsis>
+ <command>tag-transforms</command>
+ <arg choice="plain">
+ <replaceable class="parameter">tag</replaceable>
+ <arg choice="plain">
+ <replaceable class="parameter">transformed-string</replaceable>
+ </arg>
+ </arg>
+ <group choice="req" rep="repeat">
+ <arg choice="plain">
+ <replaceable class="parameter">tag</replaceable>
+ <arg choice="plain">
+ <replaceable class="parameter">transformed-string</replaceable>
+ </arg>
+ </arg>
+ </group>
+ <command>tag-formats</command>
+ <arg choice="plain">
+ <replaceable class="parameter">tag</replaceable>
+ <arg choice="plain">
+ <replaceable class="parameter">format-string</replaceable>
+ </arg>
+ </arg>
+ <group choice="req" rep="repeat">
+ <arg choice="plain">
+ <replaceable class="parameter">tag</replaceable>
+ <arg choice="plain">
+ <replaceable class="parameter">format-string</replaceable>
+ </arg>
+ </arg>
+ </group>
+ </cmdsynopsis>
+ </sect2>
+
+ <sect2 id="custom-tags-colors">
+ <title>Colors</title>
+ <para>Adds these to index-color feature:</para>
+
+ <table id="table-custom-tags-colors">
+ <title>Index Colors</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Object</entry>
+ <entry>Pattern</entry>
+ <entry>Highlights</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>index_tag</literal>
+ </entry>
+ <entry>yes</entry>
+ <entry>an individual message tag, %G, uses tag name</entry>
+ </row>
+ <row>
+ <entry>
+ <literal>index_tags</literal>
+ </entry>
+ <entry>no</entry>
+ <entry>the transformed message tags, %g or %J</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect2>
+
+ <sect2 id="custom-tags-neomuttrc">
+ <title>neomuttrc</title>
+ <screen>
+<emphasis role="comment"># Example NeoMutt config file for the custom tags feature.
+
+# VARIABLES - shown with their default values
+# --------------------------------------------------------------------------
+# This variable specifies private notmuch tags which should not be printed
+# on screen (index, pager).</emphasis>
+set nm_hidden_tags = "unread,draft,flagged,passed,replied,attachment,signed,encrypted"
+<emphasis role="comment"># --------------------------------------------------------------------------
+# FUNCTIONS - shown with an example mapping
+# --------------------------------------------------------------------------
+# modify (notmuch/imap) tags</emphasis>
+bind index,pager \` modify-labels
+<emphasis role="comment"># modify (notmuch) tag non-interactively.</emphasis>
+bind index,pager tt "<modify-labels>!todo\n" "Toggle the 'todo' tag"
+<emphasis role="comment"># modify labels and then hide message
+# bind index,pager ??? modify-labels-then-hide
+# --------------------------------------------------------------------------
+# COMMANDS - shown with an example
+# --------------------------------------------------------------------------
+# Replace some tags with icons
+# tag-transforms tag transformed-string { tag transformed-string ...}
+# tag-transforms "inbox" "i" \
+# "unread" "u" \
+# "replied" "↻ " \
+# "sent" "➥ " \
+# "todo" "T" \
+# "deleted" "DEL" \
+# "invites" "CAL"
+
+# The formats must start with 'G' and the entire sequence is case sensitive.
+# tag-formats tag format-string { tag format-string ...}
+# tag-formats "inbox" "GI" \
+# "unread" "GU" \
+# "replied" "GR" \
+# "sent" "GS" \
+# "todo" "Gt" \
+# "deleted" "GD" \
+# "invites" "Gi"
+
+# Now instead of using '%g' or '%J' in your $index_format, which lists all tags
+# in a non-deterministic order, you can something like the following which puts
+# a transformed tag name in a specific spot on the index line:
+# set index_format='%4C %S %[%y.%m.%d] %-18.18n %?GU?%GU& ? %?GR?%GR& ? %?GI?%GI& ? %s'
+
+# The %G formatting sequence may display all tags including tags hidden by
+# nm_hidden_tags.
+#
+# --------------------------------------------------------------------------
+# COLORS - some unpleasant examples are given
+# --------------------------------------------------------------------------
+# These symbols are added to the index-color feature:
+# an individual message tag, %G, uses tag name
+# this symbol uses a pattern</emphasis>
+color index_tag red white "inbox"
+<emphasis role="comment"># the transformed message tags, %g
+# this symbol does not use a pattern</emphasis>
+color index_tags green default
+<emphasis role="comment"># --------------------------------------------------------------------------
+# vim: syntax=neomuttrc</emphasis>
+</screen>
+ </sect2>
+
+ <sect2 id="custom-tags-credits">
+ <title>Credits</title>
+ <itemizedlist>
+ <listitem>
+ <para>Mehdi Abaakouk
+ <email>sileht@sileht.net</email></para>
+ </listitem>
+ <listitem>
+ <para>Richard Russon
+ <email>rich@flatcap.org</email></para>
+ </listitem>
+ <listitem>
+ <para>Bernard 'Guyzmo' Pratz
+ <email>guyzmo+github+pub@m0g.net</email></para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
</sect1>
<sect1 id="notmuch">
<entry>string</entry>
<entry>(empty)</entry>
</row>
- <row>
- <entry>
- <literal>nm_hidden_tags</literal>
- </entry>
- <entry>string</entry>
- <entry>
- <literal>
- unread,draft,flagged,passed,replied,attachment,signed,encrypted</literal>
- </entry>
- </row>
<row>
<entry>
<literal>nm_open_timeout</literal>
</tbody>
</tgroup>
</table>
+ <para>
+ More variables about tags configuration can be found in
+ <link linkend="custom-tags-variables">Custom backend Tags Feature</link>
+ </para>
</sect2>
<sect2 id="notmuch-functions">
</entry>
<entry>read entire thread of the current message</entry>
</row>
- <row>
- <entry>index,pager</entry>
- <entry>
- <literal><modify-labels></literal>
- </entry>
- <entry>add, remove, or toggle notmuch tags; [+]<tag> to
- add, -<tag> to remove, !<tag> to toggle(notmuch)
- tags. Note: Tab completion of tag names is available</entry>
- </row>
- <row>
- <entry>index,pager</entry>
- <entry>
- <literal><modify-labels-then-hide></literal>
- </entry>
- <entry>add, remove, or toggle notmuch tags; [+]<tag> to
- add, -<tag> to remove, !<tag> to togglelabels and
- then hide or unhide the message by changing the "quasi-deleted"
- to match if it would be shown when requerying.
- Normal redisplay rules apply here, so the user must call
- <sync-mailbox> for the changes to be displayed. Note:
- Tab completion of tag names is available.</entry>
- </row>
<row>
<entry>index,pager</entry>
<entry>
</row>
</tbody>
</tgroup>
- </table>
+ </table>
+ <para>
+ More functions about tags can be found in
+ <link linkend="custom-tags-functions">Custom backend Tags Feature</link>
+ </para>
</sect2>
<sect2 id="notmuch-commands">
<replaceable class="parameter">mailbox</replaceable>
</arg>
</group>
- <command>tag-transforms</command>
- <arg choice="plain">
- <replaceable class="parameter">tag</replaceable>
- <arg choice="plain">
- <replaceable class="parameter">transformed-string</replaceable>
- </arg>
- </arg>
- <group choice="req" rep="repeat">
- <arg choice="plain">
- <replaceable class="parameter">tag</replaceable>
- <arg choice="plain">
- <replaceable class="parameter">transformed-string</replaceable>
- </arg>
- </arg>
- </group>
- <command>tag-formats</command>
- <arg choice="plain">
- <replaceable class="parameter">tag</replaceable>
- <arg choice="plain">
- <replaceable class="parameter">format-string</replaceable>
- </arg>
- </arg>
- <group choice="req" rep="repeat">
- <arg choice="plain">
- <replaceable class="parameter">tag</replaceable>
- <arg choice="plain">
- <replaceable class="parameter">format-string</replaceable>
- </arg>
- </arg>
- </group>
</cmdsynopsis>
+ <para>
+ More commands about tags can be found in
+ <link linkend="custom-tags-commands">Custom backend Tags Feature</link>
+ </para>
</sect2>
<sect2 id="notmuch-colors">
<title>Colors</title>
- <para>Adds these to index-color feature:</para>
-
- <table id="table-notmuch-colors">
- <title>Index Colors</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Object</entry>
- <entry>Pattern</entry>
- <entry>Highlights</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>index_tag</literal>
- </entry>
- <entry>yes</entry>
- <entry>an individual message tag, %G, uses tag name</entry>
- </row>
- <row>
- <entry>
- <literal>index_tags</literal>
- </entry>
- <entry>no</entry>
- <entry>the transformed message tags, %g</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <para>
+ See <link linkend="custom-tags-colors">Custom backend Tags colors</link>
+ </para>
</sect2>
<sect2 id="notmuch-neomuttrc">
<emphasis role="comment"># The messages tagged with these tags are excluded and not loaded
# from notmuch DB to NeoMutt unless specified explicitly.</emphasis>
set nm_exclude_tags = ""
-<emphasis role="comment"># This variable specifies private notmuch tags which should not be printed
-# on screen (index, pager).</emphasis>
-set nm_hidden_tags = "unread,draft,flagged,passed,replied,attachment,signed,encrypted"
<emphasis role="comment"># This option specifies timeout for Notmuch database. Default is 5 seconds.</emphasis>
set nm_open_timeout = 5
<emphasis role="comment"># This variable specifies notmuch query type, supported types: 'threads' and
bind index,pager X change-vfolder
<emphasis role="comment"># read entire thread of the current message</emphasis>
bind index,pager + entire-thread
-<emphasis role="comment"># modify (notmuch) tags</emphasis>
-bind index,pager \` modify-labels
-<emphasis role="comment"># modify (notmuch) tag non-interactively.</emphasis>
-bind index,pager tt "<modify-labels>!todo\n" "Toggle the 'todo' tag"
<emphasis role="comment"># generate virtual folder from query</emphasis>
bind index,pager \eX vfolder-from-query
<emphasis role="comment"># generate virtual folder from query with time window</emphasis>
bind index,pager < vfolder-window-backward
bind index,pager > vfolder-window-forward
-<emphasis role="comment"># modify labels and then hide message
-# bind index,pager ??? modify-labels-then-hide
# toggle between mailboxes and virtual mailboxes
# bind index,pager ??? sidebar-toggle-virtual
# --------------------------------------------------------------------------
# virtual-mailboxes description notmuch-URI { description notmuch-URI ...}
# virtual-mailboxes "Climbing" "notmuch://?query=climbing"
# unvirtual-mailboxes { * | mailbox ...}
-# Replace some tags with icons
-# tag-transforms tag transformed-string { tag transformed-string ...}
-# tag-transforms "inbox" "i" \
-# "unread" "u" \
-# "replied" "↻ " \
-# "sent" "➥ " \
-# "todo" "T" \
-# "deleted" "DEL" \
-# "invites" "CAL"
-
-# The formats must start with 'G' and the entire sequence is case sensitive.
-# tag-formats tag format-string { tag format-string ...}
-# tag-formats "inbox" "GI" \
-# "unread" "GU" \
-# "replied" "GR" \
-# "sent" "GS" \
-# "todo" "Gt" \
-# "deleted" "GD" \
-# "invites" "Gi"
-
-# Now instead of using '%g' in your $index_format, which lists all tags
-# in a non-deterministic order, you can something like the following which puts
-# a transformed tag name in a specific spot on the index line:
-# set index_format='%4C %S %[%y.%m.%d] %-18.18n %?GU?%GU& ? %?GR?%GR& ? %?GI?%GI& ? %s'
-
-# The %G formatting sequence may display all tags including tags hidden by
-# nm_hidden_tags.
#
-# --------------------------------------------------------------------------
-# COLORS - some unpleasant examples are given
-# --------------------------------------------------------------------------
-# These symbols are added to the index-color feature:
-# an individual message tag, %G, uses tag name
-# this symbol uses a pattern</emphasis>
-color index_tag red white "inbox"
-<emphasis role="comment"># the transformed message tags, %g
-# this symbol does not use a pattern</emphasis>
-color index_tags green default
<emphasis role="comment"># --------------------------------------------------------------------------
# vim: syntax=neomuttrc</emphasis>
</screen>
projects / neomutt / commitdiff