Fix formatting of recent Gnus nnselect changes

* doc/misc/gnus.texi (Finding the Parent, Selection Groups)
(Searching, Basic Usage): Heed sentence-end-double-space.  Fix
formatting of prose and examples.
* etc/NEWS: Fix typo.
* lisp/gnus/gnus-srvr.el: Remove disabled autoload.
* lisp/gnus/gnus-cloud.el (gnus-cloud-available-chunks):
* lisp/gnus/gnus-group.el (gnus-group-read-ephemeral-search-group):
* lisp/gnus/gnus-sum.el (gnus-refer-thread-use-search)
(gnus-summary-refer-thread):
* lisp/gnus/gnus.el (gnus-kill-ephemeral-group):
* lisp/gnus/nnheader.el (nnheader-head-make-header)
(nnheader-parse-head):
* lisp/gnus/nnir.el:
(nnir-hyrex-remove-prefix, nnir-run-notmuch):
* lisp/gnus/nnselect.el: Fix formatting/indentation of commentary,
docstring, and/or code.
This commit is contained in:
Basil L. Contovounesios 2020-09-06 15:56:32 +01:00
parent 7d927fa8dd
commit d7197f9d99
10 changed files with 118 additions and 124 deletions

View file

@ -10417,12 +10417,12 @@ article (@code{gnus-summary-refer-references}).
@findex gnus-summary-refer-thread
@kindex A T @r{(Summary)}
Display the full thread where the current article appears
(@code{gnus-summary-refer-thread}). By default this command looks for
articles only in the current group. Some backends (currently only
'nnimap) know how to find articles in the thread directly. In other
cases each header in the current group must be fetched and examined,
so it usually takes a while. If you do it often, you may consider
setting @code{gnus-fetch-old-headers} to @code{invisible}
(@code{gnus-summary-refer-thread}). By default this command looks for
articles only in the current group. Some backends (currently only
@code{nnimap}) know how to find articles in the thread directly. In
other cases each header in the current group must be fetched and
examined, so it usually takes a while. If you do it often, you may
consider setting @code{gnus-fetch-old-headers} to @code{invisible}
(@pxref{Filling In Threads}). This won't have any visible effects
normally, but it'll make this command work a whole lot faster. Of
course, it'll make group entry somewhat slow.
@ -10441,12 +10441,13 @@ by giving the @kbd{A T} command a numerical prefix.
@vindex gnus-refer-thread-limit-to-thread
In most cases @code{gnus-refer-thread} adds any articles it finds to
the current summary buffer. (When @code{gnus-refer-thread-use-search}
the current summary buffer. (When @code{gnus-refer-thread-use-search}
is true and the initial referral starts from a summary buffer for a
non-virtual group this may not be possible. In this case a new summary
buffer is created holding a virtual group with the result of the thread
search). If @code{gnus-refer-thread-limit-to-thread} is non-nil then
the summary buffer will be limited to articles in the thread.
non-virtual group this may not be possible. In this case a new
summary buffer is created holding a virtual group with the result of
the thread search.) If @code{gnus-refer-thread-limit-to-thread} is
non-nil then the summary buffer will be limited to articles in the
thread.
@item M-^ (Summary)
@findex gnus-summary-refer-article
@ -17869,7 +17870,7 @@ whole groups together into virtual groups.
@menu
* Selection Groups:: Combining articles from many groups.
* Combined Groups:: Combining multiple groups.
* Combined Groups:: Combining multiple groups.
@end menu
@ -17882,36 +17883,35 @@ whole groups together into virtual groups.
Gnus provides the @dfn{nnselect} method for creating virtual groups
composed of collections of messages, even when these messages come
from groups that span multiple servers and backends. For the most part
these virtual groups behave like any other group: messages may be
from groups that span multiple servers and backends. For the most
part these virtual groups behave like any other group: messages may be
threaded, marked, moved, deleted, copied, etc.; groups may be
ephemeral or persistent; groups may be created via
@code{gnus-group-make-group} or browsed as foreign via
@code{gnus-group-browse-foreign-server}.
The key to using an nnselect group is specifying the messages to
include. Each nnselect group has a group parameter
include. Each nnselect group has a group parameter
@code{nnselect-specs} which is an alist with two elements: a function
@code{nnselect-function}; and arguments @code{nnselect-args} to be
passed to the function, if any.
The function @code{nnselect-function} must return a vector. Each
The function @code{nnselect-function} must return a vector. Each
element of this vector is in turn a 3-element vector corresponding to
one message. The 3 elements are: the fully-qualified group name; the
message number; and a "score" that can be used for additional
sorting. The values for the score are arbitrary, and are not used
directly by the nnselect method---they may, for example, all be set to
100.
one message. The 3 elements are: the fully-qualified group name; the
message number; and a "score" that can be used for additional sorting.
The values for the score are arbitrary, and are not used directly by
the nnselect method---they may, for example, all be set to 100.
Here is an example:
@lisp
(nnselect-specs
(nnselect-function . identity)
(nnselect-args .
[["nnimap+work:mail" 595 100]
["nnimap+home:sent" 223 100]
["nntp+news.gmane.org:gmane.emacs.gnus.general" 23666 100]]))
(nnselect-specs
(nnselect-function . identity)
(nnselect-args
. [["nnimap+work:mail" 595 100]
["nnimap+home:sent" 223 100]
["nntp+news.gmane.org:gmane.emacs.gnus.general" 23666 100]]))
@end lisp
The function is the identity and the argument is just the list of
@ -17920,21 +17920,21 @@ messages to include in the virtual group.
Or we may wish to create a group from the results of a search query:
@lisp
(nnselect-specs
(nnselect-function . nnir-run-query)
(nnselect-args
(nnir-query-spec
(query . "FLAGGED")
(criteria . ""))
(nnir-group-spec
("nnimap:home")
("nnimap:work"))))
(nnselect-specs
(nnselect-function . nnir-run-query)
(nnselect-args
(nnir-query-spec
(query . "FLAGGED")
(criteria . ""))
(nnir-group-spec
("nnimap:home")
("nnimap:work"))))
@end lisp
This creates a group including all flagged messages from all groups on
two imap servers, "home" and "work".
two IMAP servers, "home" and "work".
And one last example. Here is a function that runs a search query to
And one last example. Here is a function that runs a search query to
find all message that have been received recently from certain groups:
@lisp
@ -17946,45 +17946,44 @@ find all message that have been received recently from certain groups:
(time-subtract (current-time)
(days-to-time (car args)))))
(cons 'criteria "")))
(group-spec (cadr args)))
(nnir-run-query (cons 'nnir-specs
(list (cons 'nnir-query-spec query-spec)
(cons 'nnir-group-spec group-spec))))))
(group-spec (cadr args)))
(nnir-run-query (cons 'nnir-specs
(list (cons 'nnir-query-spec query-spec)
(cons 'nnir-group-spec group-spec))))))
@end lisp
Then an nnselect-specs
Then the following @code{nnselect-specs}:
@lisp
(nnselect-specs
(nnselect-function . my-recent-email)
(nnselect-args . (7 (("nnimap:home") ("nnimap:work")))))
(nnselect-specs
(nnselect-function . my-recent-email)
(nnselect-args . (7 (("nnimap:home") ("nnimap:work")))))
@end lisp
will provide a group composed of all messages on the home and work
servers received in the last 7 days.
Refreshing the selection of an nnselect group by running the
@code{nnselect-function} may take a long time to
complete. Consequently nnselect groups are not refreshed by default
when @code{gnus-group-get-new-news} is invoked. In those cases where
running the function is not too time-consuming, a non-nil group
parameter of @code{nnselect-rescan} will allow automatic refreshing. A
refresh can always be invoked manually through
@code{nnselect-function} may take a long time to complete.
Consequently nnselect groups are not refreshed by default when
@code{gnus-group-get-new-news} is invoked. In those cases where
running the function is not too time-consuming, a non-@code{nil} group
parameter of @code{nnselect-rescan} will allow automatic refreshing.
A refresh can always be invoked manually through
@code{gnus-group-get-new-news-this-group}.
The nnir interface (@pxref{nnir}) includes engines for searching a
variety of backends. While the details of each search engine vary, the
result of an nnir search is always a vector of the sort used by the
nnselect method, and the results of nnir queries are usually viewed
using an nnselect group. Indeed the standard search function
variety of backends. While the details of each search engine vary,
the result of an nnir search is always a vector of the sort used by
the nnselect method, and the results of nnir queries are usually
viewed using an nnselect group. Indeed the standard search function
@code{gnus-group-read-ephemeral-search-group} just creates an
ephemeral nnselect group with the appropriate nnir query as the
@code{nnselect-specs}. nnir originally included both the search
engines and the glue to connect search results to gnus. Over time this
glue evolved into the nnselect method. The two had
a mostly amicable parting so that nnselect could pursue its dream of
becoming a fully functioning backend, but occasional conflicts may
still linger.
engines and the glue to connect search results to gnus. Over time
this glue evolved into the nnselect method. The two had a mostly
amicable parting so that nnselect could pursue its dream of becoming a
fully functioning backend, but occasional conflicts may still linger.
@node Combined Groups
@subsection Combined Groups
@ -21383,22 +21382,21 @@ FIXME: A brief comparison of nnir, nnmairix, contrib/gnus-namazu would
be nice.
Gnus has various ways of finding articles that match certain criteria
(from a particular author, on a certain subject, etc). The simplest
(from a particular author, on a certain subject, etc.). The simplest
method is to enter a group and then either "limit" the summary buffer
to the desired articles using the limiting commands (@xref{Limiting}),
or searching through messages in the summary buffer (@xref{Searching
for Articles}).
Limiting commands and summary buffer searching work on subsets of the
articles already fetched from the servers, and these commands wont
articles already fetched from the servers, and these commands won't
query the server for additional articles. While simple, these methods
are therefore inadequate if the desired articles span multiple groups,
or if the group is so large that fetching all articles is
impractical. Many backends (such as imap, notmuch, namazu, etc.)
provide their own facilities to search for articles directly on the
server and gnus can take advantage of these methods. This chapter
describes tools for searching groups and servers for articles matching
a query.
or if the group is so large that fetching all articles is impractical.
Many backends (such as imap, notmuch, namazu, etc.) provide their own
facilities to search for articles directly on the server and Gnus can
take advantage of these methods. This chapter describes tools for
searching groups and servers for articles matching a query.
@menu
* nnir:: Searching with various engines.
@ -21446,7 +21444,7 @@ The @code{nnselect} group made in this way is an @code{ephemeral}
group, and will disappear upon exit from the group. However changes
made in the group are permanently reflected in the real groups from
which the articles are drawn. It is occasionally convenient to view
articles found through searching in their original group. You can
articles found through searching in their original group. You can
@emph{warp} (i.e., jump) to the original group for the article on the
current line with @kbd{A W}, aka @code{gnus-warp-to-article}.

View file

@ -328,8 +328,8 @@ obtaining the list of articles as a result of a search:
'gnus-group-make-search-group' ('G g') that will prompt for an 'nnir'
search query and create a dedicated group for that search. As part of
this addition, the user option 'nnir-summary-line-format' has been
removed; it's functionality is now available directly in the
'gnus-summary-line-format' '%G' and '%g' specs. The user option
removed; its functionality is now available directly in the
'gnus-summary-line-format' specs '%G' and '%g'. The user option
'gnus-refer-thread-use-nnir' has been renamed to
'gnus-refer-thread-use-search'.

View file

@ -414,8 +414,7 @@ When FULL is t, upload everything, not just a difference from the last full."
(while (setq head (nnheader-parse-head))
(when gnus-alter-header-function
(funcall gnus-alter-header-function head))
(push head headers))
))
(push head headers))))
(sort (nreverse headers)
(lambda (h1 h2)
(> (gnus-cloud-chunk-sequence (mail-header-subject h1))

View file

@ -3185,23 +3185,23 @@ mail messages or news articles in files that have numeric names."
(cons 'nnselect-args
(nnir-make-specs nnir-extra-parms specs)))))))))
(defun gnus-group-read-ephemeral-search-group (nnir-extra-parms &optional specs)
"Create an nnselect group based on a search. Prompt for a
search query and determine the groups to search as follows: if
called from the *Server* buffer search all groups belonging to
the server on the current line; if called from the *Group* buffer
search any marked groups, or the group on the current line, or
all the groups under the current topic. Calling with a prefix-arg
prompts for additional search-engine specific constraints. A
non-nil `specs' arg must be an alist with `nnir-query-spec' and
`nnir-group-spec' keys, and skips all prompting."
(defun gnus-group-read-ephemeral-search-group (nnir-extra-parms &optional specs)
"Create an nnselect group based on a search.
Prompt for a search query and determine the groups to search as
follows: if called from the *Server* buffer search all groups
belonging to the server on the current line; if called from the
*Group* buffer search any marked groups, or the group on the
current line, or all the groups under the current topic. Calling
with a prefix arg prompts for additional search-engine specific
constraints. A non-nil SPECS arg must be an alist with
`nnir-query-spec' and `nnir-group-spec' keys, and skips all
prompting."
(interactive "P")
(gnus-group-read-ephemeral-group
(concat "nnselect-" (message-unique-id))
(list 'nnselect "nnselect")
nil
(cons (current-buffer) gnus-current-window-configuration)
; nil
nil nil
(list
(cons 'nnselect-specs

View file

@ -35,7 +35,6 @@
(require 'gnus-cloud)
(autoload 'gnus-group-read-ephemeral-search-group "nnselect")
;;(autoload 'gnus-group-make-permanent-search-group "nnselect")
(defcustom gnus-server-exit-hook nil
"Hook run when exiting the server buffer."

View file

@ -145,8 +145,8 @@ If t, fetch all the available old headers."
(sexp :menu-tag "other" t)))
(defcustom gnus-refer-thread-use-search nil
"Search an entire server when referring threads. A
nil value will only search for thread-related articles in the
"Search an entire server when referring threads.
A nil value will only search for thread-related articles in the
current group."
:version "24.1"
:group 'gnus-thread
@ -8984,16 +8984,15 @@ Return the number of articles fetched."
result))
(defun gnus-summary-refer-thread (&optional limit)
"Fetch all articles in the current thread. For backends that
know how to search for threads (currently only 'nnimap) a
non-numeric prefix arg will search the entire
server; without a prefix arg only the current group is
searched. If the variable `gnus-refer-thread-use-search' is
non-nil the prefix arg has the reverse meaning. If no
backend-specific 'request-thread function is available fetch
LIMIT (the numerical prefix) old headers. If LIMIT is
non-numeric or nil fetch the number specified by the
`gnus-refer-thread-limit' variable."
"Fetch all articles in the current thread.
For backends that know how to search for threads (currently only
`nnimap') a non-numeric prefix arg will search the entire server;
without a prefix arg only the current group is searched. If the
variable `gnus-refer-thread-use-search' is non-nil the prefix arg
has the reverse meaning. If no backend-specific `request-thread'
function is available fetch LIMIT (the numerical prefix) old
headers. If LIMIT is non-numeric or nil fetch the number
specified by the `gnus-refer-thread-limit' variable."
(interactive "P")
(let* ((header (gnus-summary-article-header))
(id (mail-header-id header))

View file

@ -3159,7 +3159,7 @@ that that variable is buffer-local to the summary buffers."
(defun gnus-kill-ephemeral-group (group)
"Remove ephemeral GROUP from relevant structures."
(remhash group gnus-newsrc-hashtb)
(setq gnus-newsrc-alist
(setq gnus-newsrc-alist
(delq (assoc group gnus-newsrc-alist)
gnus-newsrc-alist)))

View file

@ -195,8 +195,8 @@ on your system, you could say something like:
(defsubst nnheader-head-make-header (number)
"Using data of type 'head in the current buffer
return a full mail header with article NUMBER."
"Return a full mail header with article NUMBER.
Do this using data of type `head' in the current buffer."
(let ((p (point-min))
(cur (current-buffer))
in-reply-to chars lines end ref)
@ -306,14 +306,13 @@ on your system, you could say something like:
out)))))
(defun nnheader-parse-head (&optional naked temp)
"Parse data of type 'header in the current buffer and return a
mail header, modifying the buffer contents in the process. The
buffer is assumed to begin each header with an \"Article
retrieved\" line with an article number; If NAKED is non-nil
this line is assumed absent, and the buffer should contain a
single header's worth of data. If TEMP is non-nil the data is
first copied to a temporary buffer leaving the original buffer
untouched."
"Parse data of type `header' in the current buffer and return a mail header.
Modify the buffer contents in the process. The buffer is assumed
to begin each header with an \"Article retrieved\" line with an
article number; if NAKED is non-nil this line is assumed absent,
and the buffer should contain a single header's worth of data.
If TEMP is non-nil the data is first copied to a temporary buffer
leaving the original buffer untouched."
(let ((cur (current-buffer))
(num 0)
(beg (point-min))
@ -326,22 +325,22 @@ on your system, you could say something like:
(setq num (read cur)
beg (point)
end (if (search-forward "\n.\n" nil t)
(goto-char (- (point) 2))
(goto-char (- (point) 2))
(point)))))
;; When TEMP copy the data to a temporary buffer
;; When TEMP copy the data to a temporary buffer.
(if temp
(progn
(set-buffer (setq buf (generate-new-buffer " *nnheader-temp*")))
(insert-buffer-substring cur beg end))
;; Otherwise just narrow to the data
;; Otherwise just narrow to the data.
(narrow-to-region beg end))
(let ((case-fold-search t)
(buffer-read-only nil)
header)
(nnheader-remove-cr-followed-by-lf)
(ietf-drums-unfold-fws)
(subst-char-in-region (point-min) (point-max) ?\t ? t)
(subst-char-in-region (point-min) (point-max) ?\r ? t)
(subst-char-in-region (point-min) (point-max) ?\t ?\s t)
(subst-char-in-region (point-min) (point-max) ?\r ?\s t)
(goto-char (point-min))
(insert "\n")
(setq header (nnheader-head-make-header num))

View file

@ -55,7 +55,7 @@
;; 'nnir-group-spec is a list with the specification of the
;; groups/servers to search. The format of the 'nnir-group-spec is
;; (("server1" ("group11" "group12")) ("server2" ("group21"
;; "group22"))). If any of the group lists is absent then all groups
;; "group22"))). If any of the group lists is absent then all groups
;; on that server are searched.
;; The output of `nnir-run-query' is a vector, each element of which
@ -335,7 +335,7 @@ Instead, use this:
(defcustom nnir-hyrex-remove-prefix (concat (getenv "HOME") "/Mail/")
"The prefix to remove from HyREX file names to get group names.
Restulting names have '/' in place of '.'.
Resulting names have '/' in place of '.'.
For example, suppose that HyREX returns file names such as
\"/home/john/Mail/mail/misc/42\". For this example, use the following
@ -1094,7 +1094,7 @@ Tested with Namazu 2.0.6 on a GNU/Linux system."
(nnir-artitem-rsv y)))))))))
(defun nnir-run-notmuch (query server &optional groups)
"Run QUERY with GROUPS from SERVER against notmuch.
"Run QUERY with GROUPS from SERVER against notmuch.
Returns a vector of (group name, file name) pairs (also vectors,
actually). If GROUPS is a list of group names, use them to
construct path: search terms (see the variable

View file

@ -18,16 +18,16 @@
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;; This is a "virtual" backend that allows an aribtrary list of
;; articles to be treated as a gnus group. An nnselect group uses an
;; nnselect-spec group parameter to specify this list of
;; articles. nnselect-spec is an alist with two keys:
;; nnselect-function, whose value should be a function that returns
;; the list of articles, and nnselect-args. The function will be
;; This is a "virtual" backend that allows an arbitrary list of
;; articles to be treated as a Gnus group. An nnselect group uses an
;; `nnselect-spec' group parameter to specify this list of
;; articles. `nnselect-spec' is an alist with two keys:
;; `nnselect-function', whose value should be a function that returns
;; the list of articles, and `nnselect-args'. The function will be
;; applied to the arguments to generate the list of articles. The
;; return value should be a vector, each element of which should in
;; turn be a vector of three elements: a real prefixed group name, an