From d843c9eb8e74f94809cfa47bd0ccdb479218a2ef Mon Sep 17 00:00:00 2001 From: "Dirk-Jan C. Binnema" Date: Wed, 13 Aug 2025 21:56:45 +0300 Subject: [PATCH] man: update man-pages (label / typos) --- man/mu-easy.7.org | 42 ++++++++++++++++++++++++++++++++++++++---- man/mu-find.1.org | 24 ++++++++++++------------ man/mu-query.7.org | 10 ++++++---- 3 files changed, 56 insertions(+), 20 deletions(-) diff --git a/man/mu-easy.7.org b/man/mu-easy.7.org index 98913213..aafeff47 100644 --- a/man/mu-easy.7.org +++ b/man/mu-easy.7.org @@ -23,8 +23,7 @@ your mail. By default, *mu* uses colorized output when it thinks your terminal is capable of doing so. If you don't like color, you can use the *--nocolor* command-line -option, or set either the *MU_NOCOLOR* or the *NO_COLOR* environment variable to -non-empty. +option, or set the *NO_COLOR* environment variable to non-empty. * SETTING THINGS UP @@ -284,7 +283,7 @@ $ mu cfind julius #+end_example will find all contacts with `julius' in either name or e-mail address. Note that -*mu cfind* accepts a =regular expression= (as per {{{man-link(pcre,3)}}} +*mu cfind* accepts a =regular expression= (as per {{{man-link(pcre,3)}}}). *mu cfind* also supports a *--format=*-parameter, which sets the output to some specific format, so the results can be imported into another program. For @@ -296,7 +295,41 @@ $ mu cfind --format=mutt-alias > ~/mutt-aliases #+end_example Then, you can use them in *mutt* if you add something like *source ~/mutt-aliases* -to your _muttrc_. +to your ~muttrc~. + +* LABELING MESSAGES + +It is possible to associate /labels/ with messages. These are user-provided +strings you can search for. They are a bit different from the other search +fields, since labels are not intrinsic parts of messages, so removing your +message database, and then re-indexing won't bring back your labels. + +For that reason, you can export labels to a file and later import them again +(see {{{man-link(mu-label,1)}}}) + +Some examples: + +#+begin_example +# label optimization-related messages with a label optimization +$ mu label update --labels=+performance "subject:performance or subject:optimization or subject:profiling" +#+end_example + +Now, we can search for such messages: +#+begin_example +mu find label:performance +#+end_example> + +You can also remove labels, for instance: +#+begin_example +# remove the performance label from Bill's messages +$ mu label update --labels=-performance "from:bill" +#+end_example> + +There's also *mu label clear* to remove all labels from matching messages; and the +the mutating *label* subcommands (*update*, *clear*, *import*) accept a *--dry-run* option +for just printing what they /would/ change, without actually changing anything. + +{{{man-link(mu-label,1)}}} has all the details. #+include: "prefooter.inc" :minlevel 1 @@ -310,3 +343,4 @@ to your _muttrc_. {{{man-link(mu-mkdir,1)}}}, {{{man-link(mu-view,1)}}}, {{{man-link(mu-extract,1)}}} +{{{man-link(mu-label,1)}}} diff --git a/man/mu-find.1.org b/man/mu-find.1.org index dfb65135..f268f2ec 100644 --- a/man/mu-find.1.org +++ b/man/mu-find.1.org @@ -33,10 +33,9 @@ would find all messages in 2009 with `snow' in the subject field, e.g: 2009-03-05 18:38:24 EET Marius Re: running in the snow #+end_example -Note, this the default, plain-text output, which is the default, so you don't -have to use *--format=plain*. For other types of output (such as symlinks, XML, -s-expressions or JSON), see the discussion in the *OPTIONS*-section below about -*--format*. +This uses the default, *plain* output (implicitly, *--format=plain)*. For other +output formats (such as symlinks, XML, s-expressions or JSON), see the +discussion of *--format* in the *OPTIONS*-section below. The search pattern is taken as a command-line parameter. If the search parameter consists of multiple parts (as in the example) they are @@ -68,8 +67,8 @@ $ mu find subject:snow --fields "d f s" lists the date, subject and sender of all messages with `snow' in the their subject. -The table of replacement characters is superset of the list mentions for search -parameters, such as: +The table of replacement characters is super-set of the list mentioned for +search parameters, such as: #+begin_example t *t*o: recipient d Sent *d*ate of the message @@ -84,8 +83,8 @@ parameters, such as: For the complete list, try the command: *mu info fields*. The message flags are described in {{{man-link(mu-query,7)}}}. As an example, a -message which is `seen', has an attachment and is signed would have `asz' as its -corresponding output string, while an encrypted new message would have `nx'. +message which is `seen', has an attachment and is signed has *asz* as its +corresponding output string, while an encrypted new message has *nx*. ** -s, --sortfield _field_ and -z,--reverse Specify the field to sort the search results by and the direction (i.e., @@ -127,7 +126,7 @@ If _number_ > 0, use that number of lines of the message to provide a summary. Output results in the specified format. -- The default is *plain*, i.e normal output with one line per message. +- The default is *plain*, i.e., normal output with one line per message. - *links* outputs the results as a maildir with symbolic links to the found messages. This enables easy integration with mail-clients (see below for more information). This requires *--linksdir*. @@ -174,7 +173,7 @@ could specify This is assuming the GNU *date* command. ** --exec _command_ -The *--exec* coption causes _command_ to be executed on each matched message; +The *--exec* option causes _command_ to be executed on each matched message; for example, to see the raw text of all messages matching `milkshake', you could use: #+begin_example @@ -286,8 +285,9 @@ After restarting Wanderlust, the virtual folders should appear. * ENCODING -*mu find* output is encoded according to the locale for *--format=plain* (the -default format), and UTF-8 for all other formats (=sexp=, =xml=). +*mu find* output is encoded according to the locale wwhen using *--format=plain* +(the default format), and UTF-8 for all other formats (=sexp=, =xml=). + * PERFORMANCE Some notes on performance, comparing the timings between some recent releases; diff --git a/man/mu-query.7.org b/man/mu-query.7.org index a561793d..86be5be8 100644 --- a/man/mu-query.7.org +++ b/man/mu-query.7.org @@ -174,12 +174,12 @@ may be good enough, and easier to type. ** Anchors in regular expressions -Since the underlying Xapian database does not support regular expressions (it +Since the underlying Xapian database does /not/ support regular expressions (it does support wildcards), *mu* implements the regular-expression search by matching the user's regular expression against all "terms" (words or phrases) that in the database for a given field. -That implementation detail explain why "anchored" regular expressions (with *^* +That implementation detail explains why "anchored" regular expressions (with *^* and *$* to mark begin/end, respectively) can get unexpected results. Suppose you want to match all messages that start with "pie", and you search @@ -230,7 +230,7 @@ full table with all details, including single-char shortcuts, try the command: +------------+-----------+-------+---------+-------+------+-------------------------------+----------------------------------+ | priority | prio | p | boolean | yes | yes | prio:high | Priority | +------------+-----------+-------+---------+-------+------+-------------------------------+----------------------------------+ -| references | ref | r | boolean | yes | yes | | References to related messages | +| references | ref | r | boolean | yes | yes | ref:E1rQJDx123@example.com | References to related messages | +------------+-----------+-------+---------+-------+------+-------------------------------+----------------------------------+ | size | | z | range | yes | yes | size:1M..5M | Message size in bytes | +------------+-----------+-------+---------+-------+------+-------------------------------+----------------------------------+ @@ -238,10 +238,12 @@ full table with all details, including single-char shortcuts, try the command: +------------+-----------+-------+---------+-------+------+-------------------------------+----------------------------------+ | tags | tag | x | boolean | yes | yes | tag:projectx | Message tags | +------------+-----------+-------+---------+-------+------+-------------------------------+----------------------------------+ -| thread | | w | boolean | yes | no | | Thread a message belongs to | +| thread | | w | boolean | yes | no | thread:abcde789@example.com | Thread a message belongs to | +------------+-----------+-------+---------+-------+------+-------------------------------+----------------------------------+ | to | | t | phrase | yes | yes | to:flimflam@example.com | Message recipient | +------------+-----------+-------+---------+-------+------+-------------------------------+----------------------------------+ +| labels | label | q | boolean | yes | yes | label:projectx | Message label(s) | ++------------+-----------+-------+---------+-------+------+-------------------------------+----------------------------------+ #+end_example There are also *combination fields* which allow you to search for multiple related