bug#44016: 28.0.50; Add new "gnus-search" search interface to Gnus

[Basil L. Contovounesios]

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