From: Richard Russon Date: Tue, 2 Aug 2016 09:05:47 +0000 (+0100) Subject: docs: keywords X-Git-Tag: neomutt-20160822~24^2~14 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=a42bfbdfcf06b9a50c147fa5fb7e7a4dbe577aa9;p=neomutt docs: keywords --- diff --git a/doc/manual.xml.head b/doc/manual.xml.head index 0b6d1223d..24925681d 100644 --- a/doc/manual.xml.head +++ b/doc/manual.xml.head @@ -548,7 +548,7 @@ descriptions. ^E or <End><eol>move to the end of the line ^F or <Right><forward-char>move forward one char Esc F<forward-word>move forward one word -<Tab><complete>complete filename or alias +<Tab><complete>complete filename, alias, or label ^T<complete-query>complete address with query ^K<kill-eol>delete to the end of the line Esc d<kill-eow>delete to the end of the word @@ -4567,8 +4567,8 @@ Mutt adds some other modifiers to format strings. If you use an equals symbol (=) as a numeric prefix (like the minus above), it will force the string to be centered within its minimum space range. For example, %=14y will reserve 14 characters -for the %y expansion — that's the X-Label: header, in $index_format. If the expansion results in +for the %y expansion — that's the set of message keywords (formerly +X-Label). If the expansion results in a string less than 14 characters, it will be centered in a 14-character space. If the X-Label for a message were test, that expansion would look like @@ -5182,7 +5182,7 @@ shows several ways to select messages. ~Vcryptographically verified messages ~x EXPRmessages which contain EXPR in the References or In-Reply-To field ~X [MIN]-[MAX]messages with MIN to MAX attachments *) -~y EXPRmessages which contain EXPR in the X-Label field +~y EXPRmessages which contain EXPR in their keywords ~z [MIN]-[MAX]messages with a size in the range MIN to MAX *) **) ~=duplicated messages (see $duplicate_threads) ~$unreferenced messages (requires threaded view) @@ -6051,18 +6051,6 @@ field. When set to yes, the Reply-To field will be used when present. - -The X-Label: header field can be used to further identify -mailing lists or list subject matter (or just to annotate messages -individually). The $index_format -variable's %y and %Y expandos can be used -to expand X-Label: fields in the index, and Mutt's -pattern-matcher can match regular expressions to X-Label: -fields with the ~y selector. X-Label: is -not a standard message header field, but it can easily be inserted by -procmail and other mail filtering agents. - - Lastly, Mutt has the ability to sort the mailbox into threads. A thread is a @@ -6076,6 +6064,121 @@ threads and quickly find topics of value. + +Keyword Management + + +Mutt 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-Lanels, however, the larger community +has evolved more common ways of using and managing such labels, often +known as keywords or tags. + + + +If you are new to Mutt or to using keywords in Mutt, you only need +to know that the <edit-label> binding (y by +default) will edit keywords, and that you can search for keywords +using the ~y pattern, and use the %y +expando to display it in your $index_format. You also +can sort by keyword. Keywords that you set will be stored to the +X-Label: header by default. + + + +If you've been using X-Labels for a while, things have grown slightly. +Mutt 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: + + + + + +X-Keywords + + +Informal design; space-delimited keywords + + + + + +X-Mozilla-Keys + + +Informal design used by Mozilla-based agents; space-delimited keywords + + + + + +Keywords + + +Standardized in RFC2822 (2001); comma-space-delimited keywords + + + + + +X-Label + + +Mutt-specific design; freeform text (but see $xlabel_delimiter) + + + + + + + +With X-Label, mutt'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. + + + +Two boolean variables control how keywords are saved when writing +messages to a mailbox. The default settings preserve backward +compatibility within mutt completely, but by changing these +values you can transition to more standard keyword storage. $keywords_legacy, if set, will tell +mutt to use only "legacy" headers -- i.e., X-Keywords:, +X-Mozilla-Keys, Keywords, or +X-Label:. Keywords will be saved to whichever +header was in use by the message the keyword was read from. If +$keywords_standard is +set, keywords will be saved without exception to the standard +Keywords: header. (If both are set, both will be used; +if both are unset, legacy headers are used.) Additionally, $xlabel_delimiter is used to format +the X-Label: header on saves. + + + +To migrate completely to the new standard, +unset $keywords_legacy and set +$keywords_standard, and set +$xlabel_delimiter either to what you currently use to +delimit keywords in X-Labels, or to ,  (comma +space). + + + +Note that it is common practice to insert X-Label: 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. + + + + New Mail Detection @@ -9606,6 +9709,245 @@ set index_format='%4C %Z %{%b %d} %I (%?l?%4l&%4c?) %s' + + Keywords Patch + Labels/Tagging for emails + + + Patch + + + To check if Mutt supports Keywords, look for + patch-keywords in the mutt version. + See: . + + + + Dependencies: + mutt-1.6.2 + + + This patch is part of the NeoMutt Project. + + + + Introduction + + + Unify label/keyword handling. + + + + Since x-labels were added to mutt in 2000, a number of other approaches + to what we now call tagging have also emerged. + One of them was even made standard in RFC 2822. + This update unifies the handling of all these strategies. + + + + We start by changing mutt'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 portabilty + among varying "standards" for keyword storage. This may represent + a significant change for existing mutt users who have set x-labels + containing spaces, and should be regarded with suspicion. The + advantages are significant, though. + + + + Next we allow mutt 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). Mutt remembers which headers it sourced + keywords from, and can rewrite those headers when saving messages for + compatibility with the mailer of origin. + + + + (X-Label was specified as freeform text by mutt, its only known + implementation. X-Labels have been used both as a + tagging device, probably with space delimiting, and as a + memo field, where space-delimited parsing would ruin the + semantics of the memo. By default mutt will not split X-Labels at all. + Set $xlabel_delimiter if your needs vary.) + + + + Finally we add two booleans: $keywords_legacy=true and + $keywords_standard=FALSE. When $keywords_legacy is true, mutt will + always save keyword to whatever original header it came from. When + $keywords_standard=true, mutt will save to the Keywords: header. If + both are true mutt saves to both; if neither is true, mutt saves only + to legacy headers to avoid complete loss of keywords. + + + + Overall this represents convergence path for all competing + labelling/tagging/keywording systems toward one that is specified by + RFC. + + + + You can change or delete the X-Label: field within + Mutt using the edit-label command. + This works for tagged messages, too. + + + + + Variables + + + Keywords Variables + + + + Name + Type + Default + + + + + keywords_legacy + boolean + yes + + + keywords_standard + boolean + no + + + xlabel_delimiter + string + (empty) + + + +
+ + + + Functions + + + Keywords adds the following function to Mutt. + By default, it is not bound to a key. + + + + Keyword Functions + + + + Menus + Function + Description + + + + + index,pager + <edit-label> + add, change, or delete a message's label + + + +
+ + + + + + Sort + + Keywords Sort + + + + Sort + Description + + + + + label + Sort by label + + + +
+ + + + Muttrc + + +# This is a complete list of keywords-related configuration. + +# -------------------------------------------------------------------------- +# VARIABLES - shown with their default values +# -------------------------------------------------------------------------- + +# Should Mutt save the keywords to whatever keyword it came from? +set keywords_legacy = yes + +# Should Mutt use the "Keywords:" header? +set keywords_standard = no + +# How should the keywords be separated? +set xlabel_delimiter = "" + +# -------------------------------------------------------------------------- +# FUNCTIONS - shown with an example mapping +# -------------------------------------------------------------------------- + +# Bind 'y' to edit labels/keywords +bind index,pager y edit-label + +# -------------------------------------------------------------------------- + +# vim: syntax=muttrc + + + + + See Also + + + NeoMutt Project + $index_format + index-color patch + folder-hook + + + + + Known Bugs + + None + + + + + Credits + + David Champion dgc@uchicago.edu + Richard Russon rich@flatcap.org + + + + Sidebar Overview of mailboxes diff --git a/doc/muttrc.keywords b/doc/muttrc.keywords new file mode 100644 index 000000000..5b72d4bbe --- /dev/null +++ b/doc/muttrc.keywords @@ -0,0 +1,23 @@ +# This is a complete list of keywords-related configuration. + +# -------------------------------------------------------------------------- +# VARIABLES - shown with their default values +# -------------------------------------------------------------------------- + +# Should Mutt save the keywords to whatever keyword it came from? +set keywords_legacy = yes + +# Should Mutt use the "Keywords:" header? +set keywords_standard = no + +# How should the keywords be separated? +set xlabel_delimiter = "" + +# -------------------------------------------------------------------------- +# FUNCTIONS - shown with an example mapping +# -------------------------------------------------------------------------- + +# Bind 'y' to edit labels/keywords +bind index,pager y edit-label + +# vim: syntax=muttrc diff --git a/doc/vimrc.keywords b/doc/vimrc.keywords new file mode 100644 index 000000000..e217ed3d4 --- /dev/null +++ b/doc/vimrc.keywords @@ -0,0 +1,10 @@ +" Vim syntax file for the mutt keywords patch + +syntax keyword muttrcVarBool contained skipwhite keywords_legacy nextgroup=muttrcSetBoolAssignment,muttrcVPrefix,muttrcVarBool,muttrcVarQuad,muttrcVarNum,muttrcVarStr +syntax keyword muttrcVarBool contained skipwhite keywords_standard nextgroup=muttrcSetBoolAssignment,muttrcVPrefix,muttrcVarBool,muttrcVarQuad,muttrcVarNum,muttrcVarStr + +syntax keyword muttrcVarStr contained skipwhite xlabel_delimiter nextgroup=muttrcVarEqualsIdxFmt + +syntax match muttrcFunction contained "\" + +" vim: syntax=vim