From: "Basil L. Contovounesios" <contovob@tcd.ie>
To: Eric Abrahamsen <eric@ericabrahamsen.net>
Cc: Lars Ingebrigtsen <larsi@gnus.org>, 44016@debbugs.gnu.org
Subject: bug#44016: 28.0.50; Add new "gnus-search" search interface to Gnus
Date: Sun, 01 Nov 2020 18:10:39 +0000 [thread overview]
Message-ID: <87v9ep9cdc.fsf@tcd.ie> (raw)
In-Reply-To: <874km9d4mc.fsf@ericabrahamsen.net> (Eric Abrahamsen's message of "Sat, 31 Oct 2020 22:32:11 -0700")
Eric Abrahamsen <eric@ericabrahamsen.net> writes:
> Finally done! I think. Most of the final work was writing the docs.
Thanks! I only had time to look through the manual, and it looks good,
modulo some minor markup nits.
> +It's possible to search a backend more thoroughly using an associated
> +search engine. Some backends come with their own search engine: IMAP
> +servers, for instance, do their own searching. Other backends, for
> +example a local @code{nnmaildir} installation, might require the user
> +to manually set up some sort of search indexing. Default associations
> +between backends and engines can be defined in
> +@code{gnus-search-default-engines}, and engines can also be defined on
> +a per-backend basis (@xref{Search Engines}).
Should this and other parenthesised xrefs be pxref instead?
(I haven't tested the difference.)
> +Once the search engines are set up, you can search for messages in
> +groups from one or more backends, and show the results in a group.
> +The groups that hold search results are created on the nnselect
> +backend, and can be either ephemeral or persistent (@xref{Creating
> +Search Groups}).
> +
> +@vindex: gnus-search-use-parsed-queries
Is the colon necessary?
> +Search queries can be specified one of two ways: either using the
> +syntax of the engine responsible for the group you're searching, or
> +using Gnus' generalized search syntax. Set the option
> +@code{gnus-search-use-parsed-queries} to a non-nil value to used the
> +generalized syntax. The advantage of this syntax is that, if you have
> +multiple backends indexed by different engines, you don't need to
> +remember which one you're searching -- it's also possible to issue the
I think Texinfo conventionally uses three hyphens for punctuation in
sentences (info "(texinfo) Conventions"). (Here and elsewhere.)
> +same query against multiple groups, indexed by different engines, at
> +the same time. It also provides a few other conveniences including
> +relative date parsing and tie-ins into other Emacs packages. For
> +details on Gnus' query language, @xref{Search Queries}.
I think @xref is used at the start of sentences and @ref at the end.
> +@vindex gnus-search-default-engines
> +The option @code{gnus-search-default-engines} assigns search engines
> +by server type. Its value is an alist mapping symbols indicating a
> +server type (e.g. @code{nnmaildir} or @code{nnml}) to symbols
My impression is that Emacs uses the (US?) convention of following
e.g. with a comma (but I could be wrong). (Here and elsewhere.)
> +These engines have a handful of configuration parameters that can
> +either be set as a default option for all engines of that type, or set
> +per-engine in your server config. These common paramters are:
paramters -> parameters
> +
> +@itemize
> +@item
> +@code{program}: The name of the executable. Defaults to the plain
I think listing definitions, particularly when they need markup, is
better done with e.g. '@table @code' rather than @itemize.
(Here and elsewhere.)
> +program name such as ``notmuch'' or ``namazu''.
Should command names be marked as @command? (Here or elsewhere.)
> +The customization options are formed on the pattern
> +@code{gnus-search-<engine>-<parameter>}. For instance, to use a
Don't know whether it's preferable here, but there's also the
metavariable syntax @code{gnus-search-@var{engine}-@var{parameter}},
with which you can e.g. refer to individual @vars in subsequent prose.
> +non-standard notmuch program, you might set
> +@code{gnus-search-notmuch-program} to ``/usr/local/bin/notmuch''.
@file?
> -By default the whole message will be searched. The query can be limited
> -to a specific part of a message by using a prefix-arg. After inputting
> -the query this will prompt (with completion) for a message part.
> -Choices include ``Whole message'', ``Subject'', ``From'', and
I think literal text (here and elsewhere) is usually written as @samp.
> +(from:john or from:peter) subject: ``lunch tomorrow'' since:3d
I think quoting in examples should use "" instead of ``'' (here and
elsewhere).
> +@item
> +mark: Accepts ``flag'', ``seen'', ``read'' or ``replied'', or any of
> +Gnus' single-letter representations of those marks, i.e. ``mark:R''
i.e. -> e.g.?
> +for ``read''.
> -@end table
> +@vindex gnus-search-contact-sources
> +If an elisp-based contact management packages (e.g. BBDB or EBDB)
packages -> package
elisp -> Elisp?
> -@node Customizations
> -@subsubsection Customizations
> +@vindex gnus-search-date-keys
> +Date-type keys (see @code{gnus-search-date-keys}) will accept a wide
> +variety of values. First, anything that @code{parse-time-string} can
> +parse is acceptable. Dates with missing values will be interpreted as
> +the most recent occurance thereof: for instance ``march 03'' is the
occurance -> occurrence (here and elsewhere)
--
Basil
next prev parent reply other threads:[~2020-11-01 18:10 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-10-15 16:47 bug#44016: 28.0.50; Add new "gnus-search" search interface to Gnus Eric Abrahamsen
2020-10-16 5:08 ` Lars Ingebrigtsen
2020-10-16 15:49 ` Eric Abrahamsen
2020-11-01 5:32 ` Eric Abrahamsen
2020-11-01 18:10 ` Basil L. Contovounesios [this message]
2020-11-01 18:22 ` Eli Zaretskii
2020-11-01 21:19 ` Eric Abrahamsen
2020-11-01 21:38 ` Eric Abrahamsen
2020-11-01 23:50 ` Stefan Monnier
2020-11-02 3:43 ` Eric Abrahamsen
2020-11-02 14:24 ` Stefan Monnier
2020-11-02 16:16 ` Eric Abrahamsen
2020-11-02 20:11 ` Eric Abrahamsen
2020-11-04 5:22 ` Eric Abrahamsen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87v9ep9cdc.fsf@tcd.ie \
--to=contovob@tcd.ie \
--cc=44016@debbugs.gnu.org \
--cc=eric@ericabrahamsen.net \
--cc=larsi@gnus.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).