[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master d7197f9: Fix formatting of recent Gnus nnselect changes
|
From: |
Basil L. Contovounesios |
|
Subject: |
master d7197f9: Fix formatting of recent Gnus nnselect changes |
|
Date: |
Sun, 6 Sep 2020 11:07:26 -0400 (EDT) |
branch: master
commit d7197f9d99ca6aa326d38e64ca9eb1d13e18d664
Author: Basil L. Contovounesios <contovob@tcd.ie>
Commit: Basil L. Contovounesios <contovob@tcd.ie>
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.
---
doc/misc/gnus.texi | 138 ++++++++++++++++++++++++------------------------
etc/NEWS | 4 +-
lisp/gnus/gnus-cloud.el | 3 +-
lisp/gnus/gnus-group.el | 22 ++++----
lisp/gnus/gnus-srvr.el | 1 -
lisp/gnus/gnus-sum.el | 23 ++++----
lisp/gnus/gnus.el | 2 +-
lisp/gnus/nnheader.el | 29 +++++-----
lisp/gnus/nnir.el | 6 +--
lisp/gnus/nnselect.el | 14 ++---
10 files changed, 118 insertions(+), 124 deletions(-)
diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index de5e8f3..789b1de 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -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 won’t
+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}.
diff --git a/etc/NEWS b/etc/NEWS
index 749b28a..f0644c8 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -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'.
diff --git a/lisp/gnus/gnus-cloud.el b/lisp/gnus/gnus-cloud.el
index e40b2eb..3e23e26 100644
--- a/lisp/gnus/gnus-cloud.el
+++ b/lisp/gnus/gnus-cloud.el
@@ -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))
diff --git a/lisp/gnus/gnus-group.el b/lisp/gnus/gnus-group.el
index cafaf69..a90243b 100644
--- a/lisp/gnus/gnus-group.el
+++ b/lisp/gnus/gnus-group.el
@@ -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
diff --git a/lisp/gnus/gnus-srvr.el b/lisp/gnus/gnus-srvr.el
index 8cb80b2..6beb543 100644
--- a/lisp/gnus/gnus-srvr.el
+++ b/lisp/gnus/gnus-srvr.el
@@ -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."
diff --git a/lisp/gnus/gnus-sum.el b/lisp/gnus/gnus-sum.el
index 0cde893..dc4f1c6 100644
--- a/lisp/gnus/gnus-sum.el
+++ b/lisp/gnus/gnus-sum.el
@@ -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))
diff --git a/lisp/gnus/gnus.el b/lisp/gnus/gnus.el
index 561e6b8..8cd35e3 100644
--- a/lisp/gnus/gnus.el
+++ b/lisp/gnus/gnus.el
@@ -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)))
diff --git a/lisp/gnus/nnheader.el b/lisp/gnus/nnheader.el
index 1a50697..67dc379 100644
--- a/lisp/gnus/nnheader.el
+++ b/lisp/gnus/nnheader.el
@@ -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))
diff --git a/lisp/gnus/nnir.el b/lisp/gnus/nnir.el
index 2ec39cf..6ba0334 100644
--- a/lisp/gnus/nnir.el
+++ b/lisp/gnus/nnir.el
@@ -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
diff --git a/lisp/gnus/nnselect.el b/lisp/gnus/nnselect.el
index 460bc63..1965a26 100644
--- a/lisp/gnus/nnselect.el
+++ b/lisp/gnus/nnselect.el
@@ -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
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- master d7197f9: Fix formatting of recent Gnus nnselect changes,
Basil L. Contovounesios <=