From 8405788f2710c65e9dd54b0d9f0b45839b63b983 Mon Sep 17 00:00:00 2001 From: "Dirk-Jan C. Binnema" Date: Fri, 12 Feb 2021 18:49:55 +0200 Subject: [PATCH] docs: update documentation Update the mu-find man-page; update NEWS.org and mu4e.texi for the way threading works. --- NEWS.org | 13 ++++++------- man/mu-find.1 | 14 +++++--------- mu4e/mu4e-headers.el | 6 +++++- mu4e/mu4e.texi | 33 +++++++++++++++++++++++++-------- 4 files changed, 41 insertions(+), 25 deletions(-) diff --git a/NEWS.org b/NEWS.org index d2771a15..3d7b7383 100644 --- a/NEWS.org +++ b/NEWS.org @@ -5,13 +5,13 @@ *** mu - - Where available (and with suitable ~libglib~), log to the systemd journal - instead of a ~~/.cache/mu.log~. The ~--debug~ option to ~mu~ much + - Where available (and with suitably equiped ~libglib~), log to the ~systemd~ + journal instead of ~~/.cache/mu.log~. Passing the ~--debug~ option to ~mu~ increases the amount that is logged. - Follow symlinks in maildirs, and support moving messsages across - filesystems (but note that that is quite a bit slower than the - single-filesystem case) + filesystems. Obviously, that is typically quite a bit slower than the + single-filesystem case, but can be still be useful. - Optionally provide readline support for the ~mu~ server (when in tty-mode) @@ -32,8 +32,7 @@ - Modernized the querying/threading machinery; this is makes some old code a lot easier to understand and maintain, and even while not an explicit - goal, is also faster (e.g. the threading seems to be roughly twice as - fast) + goal, is also faster. - Experimental support for the Meson build system. @@ -53,7 +52,7 @@ - Honor ~truncate-string-ellipsis~ so you can now use 'fancy' ellipses for truncated strings with ~(setq truncate-string-ellipsis "…")~ - - Add a variable ~mu4e-mu-debug~ which, when set to non-~nil~ makes the ~mu~ + - Add a variable ~mu4e-mu-debug~ which, when set to non-~nil,~ makes the ~mu~ server log more verbosely (to ~mu.log~ or the journal) - Better alignment in headers-buffers; this looks nicer, but is also a bit diff --git a/man/mu-find.1 b/man/mu-find.1 index 5e464877..c9805939 100644 --- a/man/mu-find.1 +++ b/man/mu-find.1 @@ -1,11 +1,9 @@ -.TH MU FIND 1 "19 April 2015" "User Manuals" +.TH MU FIND 1 "12 February 2021" "User Manuals" .SH NAME mu find \- find e-mail messages in the \fBmu\fR database. -mu mfind \- find e-mail messages in the \fBmu\fR database with mu4e defaults. - .SH SYNOPSIS .B mu find [options] @@ -15,9 +13,6 @@ mu mfind \- find e-mail messages in the \fBmu\fR database with mu4e defaults. \fBmu find\fR is the \fBmu\fR command for searching e-mail message that were stored earlier using \fBmu index\fR(1). -\fBmu mfind\fR is a version of \fBmu find\fR that defaults to -\f--include-related\fR and \fB--skip-dups\fR, just like \fBmu4e\fR does. - .SH SEARCHING MAIL \fBmu find\fR starts a search for messages in the database that match @@ -226,9 +221,10 @@ Gmail-style 'conversations'. Note, finding these related messages make searches slower. .TP -\fB\-t\fR, \fB\-\-threads\fR show messages in a 'threaded' format -- that is, -with indentation and arrows showing the conversation threads in the list of -matching messages. +\fB\-t\fR, \fB\-\-threads\fR show messages in a 'threaded' format -- +that is, with indentation and arrows showing the conversation threads +in the list of matching messages. When using this, sorting is +chronological (by date), based on the newest message in a thread. Messages in the threaded list are indented based on the depth in the discussion, and are prefix with a kind of arrow with thread-related diff --git a/mu4e/mu4e-headers.el b/mu4e/mu4e-headers.el index 6f5c2e6a..88ebe48b 100644 --- a/mu4e/mu4e-headers.el +++ b/mu4e/mu4e-headers.el @@ -220,7 +220,11 @@ but also manually invoked searches." (defvar mu4e-headers-sort-field :date "Field to sort the headers by. Must be a symbol, one of: `:date', `:subject', `:size', `:prio', `:from', `:to.', -`:list'") +`:list'. + +Note that when threading is enabled (through +`mu4e-headers-show-threads'), the headers are exclusively sorted +chronologically (`:date') by the newest message in the thread.") (defvar mu4e-headers-sort-direction 'descending "Direction to sort by; a symbol either `descending' (sorting diff --git a/mu4e/mu4e.texi b/mu4e/mu4e.texi index 8803d35e..ebd05883 100644 --- a/mu4e/mu4e.texi +++ b/mu4e/mu4e.texi @@ -379,12 +379,24 @@ configuration before trying again: (add-to-list 'load-path "/usr/local/share/emacs/site-lisp/mu4e") @end lisp +@subsection Building using the meson build system + +As an (experimental) alternative to the @t{autotools}-build, it is possible to use +the Meson@footnote{@url{https://mesonbuild.com/}} build-system instead. + +@example +$ git clone git://github.com/djcb/mu.git +$ cd mu +$ meson build && ninja -C build +$ sudo ninja -C install +@end example + @subsection mu4e and emacs customization There is some support for using the Emacs customization system in -@t{mu4e}, but for now, we recommend setting the values manually. Please refer -to @ref{Example configs} for a couple of examples of this; here we go -through things step-by-step. +@t{mu4e}, but for now, we recommend setting the values +manually. Please refer to @ref{Example configs} for a couple of +examples of this; here we go through things step-by-step. @node Getting mail @section Getting mail @@ -1046,17 +1058,19 @@ For more information about marking, see @ref{Marking}. @node Sorting and threading @section Sorting and threading -By default, @t{mu4e} sorts messages by date, in descending order: the most -recent messages are shown at the top. In addition, the messages are -@emph{threaded}, i.e., shown in the context of a discussion thread; this also -affects the sort order. +By default, @t{mu4e} sorts messages by date, in descending order: the +most recent messages are shown at the top. In addition, be default +@t{mu4e} shows the message @emph{threads}, i.e., the tree structure +representing a discussion thread; this also affects the sort order: +the top-level messages are sorted by the date of the @emph{newest} +message in the thread. The header field used for sorting is indicated by ``@t{V}'' or ``@t{^}''@footnote{or you can use little graphical triangles; see variable @code{mu4e-use-fancy-chars}}, indicating the sort order (descending or ascending, respectively). -You can change the sort order by clicking the corresponding field with the +You can change the sort order by clicking the corresponding column with the mouse, or with @kbd{M-x mu4e-headers-change-sorting} (@key{O}); note that not all fields can be used for sorting. You can toggle threading on/off using @kbd{M-x mu4e-headers-toggle-threading} or @key{P}. For both of these functions, @@ -1064,6 +1078,9 @@ unless you provide a prefix argument (@key{C-u}), the current search is updated immediately using the new parameters. You can toggle full-search (@ref{Searching}) using @kbd{M-x mu4e-headers-toggle-full-search} or @key{Q}. +Note that with threading enabled, the sorting is exclusively by date, +regardless of the column clicked. + If you want to change the defaults for these settings, you can use the variables @code{mu4e-headers-sort-field} and @code{mu4e-headers-show-threads}, as well as