find topics of value.</para>
</sect1>
- <sect1 id="using-keywords">
- <title>Keyword Management</title>
- <para>NeoMutt has supported textual labels (usually known as X-Labels after
- the header that we use to store them) for many years. Since we initially
- added support for X-Labels, however, the larger community has evolved
- more common ways of using and managing such labels, often known as
- <quote>keywords</quote> or
- <quote>tags</quote>.</para>
- <para>If you are new to NeoMutt or to using keywords in NeoMutt, you only need
- to know that the <edit-label> binding will edit keywords, and that
- you can search for keywords using the
- <literal>~y</literal> pattern, and use the
- <literal>%y</literal> expando to display it in your
- <literal>$index_format</literal>. You also can sort by keyword. Keywords
- that you set will be stored to the
- <literal>X-Label:</literal>header by default.</para>
- <para>If you've been using X-Labels for a while, things have grown
- slightly. NeoMutt still supports X-Labels much as it has since 2000, but the
- scope of this support has expanded to support three additional
- header-based techniques for storing keyword metadata on messages:</para>
- <variablelist>
- <varlistentry>
- <term>X-Keywords</term>
- <listitem>
- <para>Informal design; space-delimited keywords</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>X-Mozilla-Keys</term>
- <listitem>
- <para>Informal design used by Mozilla-based agents; space-delimited
- keywords</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Keywords</term>
- <listitem>
- <para>Standardized in RFC2822 (2001); comma-space-delimited
- keywords</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>X-Label</term>
- <listitem>
- <para>NeoMutt-specific design; freeform text (but see
- <link linkend="xlabel-delimiter">$xlabel_delimiter</link>)</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>With X-Label, NeoMutt's only notion of a message keyword was the
- literal string value of the X-Label header. Under the new, integrated
- support, each message may have a list of distinct message keywords. When
- reading keywords from one of the headers in the list above, the header
- value is split on the indicated delimiter (space or comma-space) for
- X-Keywords:, X-Mozilla-Keys:, and Keywords:. By default, X-Label: is
- parsed as a single keyword. By setting $xlabel_delimiter, you can force
- splitting of X-Label: as well.</para>
- <para>Two boolean variables control how keywords are saved when writing
- messages to a mailbox. The default settings preserve backward
- compatibility within NeoMutt completely, but by changing these values you
- can transition to more standard keyword storage.
- <link linkend="keywords-legacy">$keywords_legacy</link>, if set, will
- tell NeoMutt to use only "legacy" headers -- i.e.,
- <literal>X-Keywords:</literal>,
- <literal>X-Mozilla-Keys</literal>,
- <literal>Keywords</literal>, or
- <literal>X-Label:</literal>. Keywords will be saved to whichever header
- was in use by the message the keyword was read from. If
- <link linkend="keywords-standard">$keywords_standard</link> is set,
- keywords will be saved without exception to the standard
- <literal>Keywords:</literal>header. (If both are set, both will be used;
- if both are unset, legacy headers are used.) Additionally,
- <link linkend="xlabel-delimiter">$xlabel_delimiter</link> is used to
- format the X-Label: header on saves.</para>
- <para>To migrate completely to the new standard, unset
- <literal>$keywords_legacy</literal> and set
- <literal>$keywords_standard</literal>, and set
- <literal>$xlabel_delimiter</literal> either to what you currently use to
- delimit keywords in X-Labels, or to
- <quote>, </quote>(comma space).</para>
- <para>Note that it is common practice to insert
- <literal>X-Label:</literal>or other keyword headers from proxmail or
- other mail filters. This is a useful trick for categorizing messages en
- masse as they are delivered to your inbox, and it is fully compatible
- with the new keywords code.</para>
- </sect1>
-
<sect1 id="display-munging">
<title>Display Munging</title>
<para>Working within the confines of a console or terminal window, it is
</sect2>
</sect1>
- <sect1 id="keywords">
- <title>Keywords Feature</title>
- <subtitle>Labels/Tagging for emails</subtitle>
-
- <sect2 id="keywords-support">
- <title>Support</title>
- <para>
- <emphasis role="bold">Since:</emphasis>NeoMutt 2016-05-30</para>
- <para>
- <emphasis role="bold">Dependencies:</emphasis>None</para>
- </sect2>
-
- <sect2 id="keywords-intro">
- <title>Introduction</title>
- <para>Unify label/keyword handling.</para>
- <para>Since x-labels were added to NeoMutt in 2000, a number of other
- approaches to what we now call
- <quote>tagging</quote> have also emerged. One of them was even made
- standard in RFC 2822. This update unifies the handling of all these
- strategies.</para>
- <para>We start by changing NeoMutt's internal keyword storage from a
- single string which may contain whitespace to a list of discrete
- keywords. This has advantages for keyword completion as well as for
- portability among varying "standards" for keyword storage. This may
- represent a significant change for existing NeoMutt users who have set
- x-labels containing spaces, and should be regarded with suspicion. The
- advantages are significant, though.</para>
- <para>Next we allow NeoMutt to parse keywords into this internal list from
- any of the following headers: X-Label (freeform), X-Keywords
- (space-delimited), X-Mozilla-Keys (space-delimited), and Keywords (RFC
- 2822, comma-space-delimited). NeoMutt remembers which headers it sourced
- keywords from, and can rewrite those headers when saving messages for
- compatibility with the mailer of origin.</para>
- <para>(X-Label was specified as freeform text by NeoMutt, its only known
- implementation. X-Labels have been used both as a
- <quote>tagging</quote> device, probably with space delimiting, and as a
- <quote>memo</quote> field, where space-delimited parsing would ruin the
- semantics of the memo. By default NeoMutt will not split X-Labels at all.
- Set $xlabel_delimiter if your needs vary.)</para>
- <para>Finally we add two booleans: $keywords_legacy=true and
- $keywords_standard=FALSE. When $keywords_legacy is true, NeoMutt will
- always save keyword to whatever original header it came from. When
- $keywords_standard=true, NeoMutt will save to the Keywords: header. If
- both are true NeoMutt saves to both; if neither is true, NeoMutt saves only
- to legacy headers to avoid complete loss of keywords.</para>
- <para>Overall this represents convergence path for all competing
- labelling/tagging/keywording systems toward one that is specified by
- RFC.</para>
- <para>You can change or delete the X-Label: field within NeoMutt using the
- edit-label command. This works for tagged messages, too.</para>
- </sect2>
-
- <sect2 id="keywords-variables">
- <title>Variables</title>
-
- <table id="table-keywords-variables">
- <title>Keywords Variables</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Name</entry>
- <entry>Type</entry>
- <entry>Default</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>keywords_legacy</literal>
- </entry>
- <entry>boolean</entry>
- <entry>
- <literal>yes</literal>
- </entry>
- </row>
- <row>
- <entry>
- <literal>keywords_standard</literal>
- </entry>
- <entry>boolean</entry>
- <entry>
- <literal>no</literal>
- </entry>
- </row>
- <row>
- <entry>
- <literal>xlabel_delimiter</literal>
- </entry>
- <entry>string</entry>
- <entry>(empty)</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </sect2>
-
- <sect2 id="keywords-functions">
- <title>Functions</title>
- <para>Keywords adds the following function to NeoMutt. By default, it is
- not bound to a key.</para>
-
- <table id="table-keywords-funcions">
- <title>Keyword 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><edit-label></literal>
- </entry>
- <entry>add, change, or delete a message's label</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </sect2>
-
- <sect2 id="keywords-sort">
- <title>Sort</title>
-
- <table id="table-keywords-sort">
- <title>Keywords Sort</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Sort</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>label</literal>
- </entry>
- <entry>Sort by label</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </sect2>
-
- <sect2 id="keywords-neomuttrc">
- <title>neomuttrc</title>
- <screen>
-<emphasis role="comment"># Example NeoMutt config file for the keywords feature.
-
-# --------------------------------------------------------------------------
-# VARIABLES - shown with their default values
-# --------------------------------------------------------------------------
-# Should NeoMutt save the keywords to whatever keyword it came from?</emphasis>
-set keywords_legacy = yes
-<emphasis role="comment"># Should NeoMutt use the "Keywords:" header?</emphasis>
-set keywords_standard = no
-<emphasis role="comment"># How should the keywords be separated?</emphasis>
-set xlabel_delimiter = ""
-<emphasis role="comment"># --------------------------------------------------------------------------
-# FUNCTIONS - shown with an example mapping
-# --------------------------------------------------------------------------
-# Bind 'y' to edit labels/keywords</emphasis>
-bind index,pager y edit-label
-
- <emphasis role="comment"># vim: syntax=neomuttrc</emphasis>
-</screen>
- </sect2>
-
- <sect2 id="keywords-see-also">
- <title>See Also</title>
- <itemizedlist>
- <listitem>
- <para>
- <link linkend="index-format">$index_format</link>
- </para>
- </listitem>
- <listitem>
- <para>
- <link linkend="index-color">index-color feature</link>
- </para>
- </listitem>
- <listitem>
- <para>
- <link linkend="folder-hook">folder-hook</link>
- </para>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <sect2 id="keywords-known-bugs">
- <title>Known Bugs</title>
- <para>None</para>
- </sect2>
-
- <sect2 id="keywords-credits">
- <title>Credits</title>
- <itemizedlist>
- <listitem>
- <para>David Champion
- <email>dgc@uchicago.edu</email></para>
- </listitem>
- <listitem>
- <para>Richard Russon
- <email>rich@flatcap.org</email></para>
- </listitem>
- </itemizedlist>
- </sect2>
- </sect1>
-
<sect1 id="kyoto-cabinet">
<title>Kyoto Cabinet Feature</title>
<subtitle>Kyoto Cabinet backend for the header cache</subtitle>
** from your spool mailbox to your $$mbox mailbox, or as a result of
** a ``$mbox-hook'' command.
*/
- { "keywords_legacy", DT_BOOL, R_NONE, OPT_KEYWORDS_LEGACY, 1 },
- /*
- ** .pp
- ** If \fIset\fP, keywords/labels/tags will be written to whatever
- ** legacy, nonstandard headers (X-Label, X-Keywords, X-Mozilla-Keys)
- ** they were sourced from.
- ** .pp
- ** If both ``$$keywords_legacy'' and
- ** ``$$keywords_standard'' are \fCfalse\fP, NeoMutt will save keywords
- ** to legacy headers to ensure that it does not lose your labels.
- */
- { "keywords_standard", DT_BOOL, R_NONE, OPT_KEYWORDS_STANDARD, 0 },
- /*
- ** .pp
- ** If \fIset\fP, keywords/labels/tags will be written to the
- ** RFC2822-standard Keywords: header; this may imply a conversion from
- ** legacy headers.
- ** .pp
- ** If both ``$$keywords_legacy'' and
- ** ``$$keywords_standard'' are \fCfalse\fP, NeoMutt will save keywords
- ** to legacy headers to ensure that it does not lose your labels.
- */
{ "mail_check", DT_NUMBER, R_NONE, UL &MailCheck, 5 },
/*
** .pp
{ "xterm_set_titles", DT_SYNONYM, R_NONE, UL "ts_enabled", 0 },
/*
*/
- { "xlabel_delimiter", DT_STRING, R_NONE, UL &XlabelDelimiter, UL "" },
- /*
- ** .pp
- ** The character used to delimit distinct keywords in X-Label headers.
- ** X-Label is primarily a NeoMutt artifact, and the semantics of the field
- ** were never defined: it is free-form text. However interaction with
- ** X-Keywords:, X-Mozilla-Keys:, and Keywords: requires that we adopt
- ** some means of identifying separate keywords within the field. Set
- ** this to your personal convention.
- ** .pp
- ** This affect both parsing existing X-Label headers and writing new
- ** X-Label headers. You can modify this variable in runtime to accomplish
- ** various kinds of conversion.
- */
#ifdef USE_NNTP
{ "x_comment_to", DT_BOOL, R_NONE, OPT_X_COMMENT_TO, 0 },
/*