bug#75305: 31.0.50; gnus-refer-thread-use-search isn't exact enough about how the current group is searched

[Eli Zaretskii <eliz@gnu.org>]

> From: Björn Bidar <bjorn.bidar@thaodan.de>
> Cc: 75305@debbugs.gnu.org
> Date: Sat, 04 Jan 2025 23:34:10 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Thanks, but the patch seems to include unrelated changes in the code?
> > I thought we were talking only about fixing the manual?  Or what did I
> > miss?
> >
> 
> I look at the situation further and noticed that adding the current
> group does not work without the user writing a custom hook to add it.
> I already wrote a hook to change gnus-refer-thread-use-search for
> another reason, to add the current gnus-message-archive-group to 
> gnus-refer-thread-use-search.
> To just add the current group writing a hook would be to clumsy.
> Using the current symbol similar as in gnus-refer-article-method is much
> simpler, makes the setting easier to understand and customize for new 
> users.
> 
> The customization changes are there to use better custom types which
> makes it easier to customize and harder to put false values into the
> option when using custom.

Then we'll need to wait for our Gnus expert (CC'ed) to review your
code changes.  I have some comments to the documentation part below:

> * lisp/gnus/gnus-sum.el (gnus-refer-thread-use-search):
> Make it easier to customize the variable by adding predefine choices
> as well as descriptions to each choice. Add option to add the value
> `current' to the list of servers and groups to add the current group.
> E.g. to add another group and the current group.
> * lisp/gnus/gnus-search.el (gnus-refer-thread-maybe-add-current-group,
> gnus-search-thread): Add helper function to determine if the option
> contains the value current. Use helper function.
> * lisp/gnus/nnselect.el (nnselect-request-thread): Use helper function
> to check if the value current is in gnus-refer-thread-use-search.
> * doc/misc/gnus.texi (gnus-refer-thread-use-search):
> Include the current value in the section. Format the section a little
> better to have a paragraph for each possible value that the option
> may contain. Explain the option to have a list of servers more detailed
> , i.e. similarly to the custom description. Highlight that the current
> group is not searched unless specified. Explain that unless the articles
> of that thread are contained in the searched groups not adding the
> current group might not be the desired effect.

Some of the lines in the log message are too long.  Please be sure to
wrap lines at column 64 if possible, and in any case before column 70.

> +If @code{gnus-refer-thread-use-search} is @code{current} or @code{nil}
> +(the default) then thread-referral only looks for articles in the current group.
                ^
Comma missing there (yes, it was also missing in the original text).

> +If this variable is @code{t} the server to which the current group
                               ^
Same here.

> +The variable can also be a list of server each server
> +in the list is searched.  The servers have to specified in a list
                                         ^^^^^^^^^^^^^^^^^
"have to be specified", right?

> +where the first element of this has to be the server and any remaining elements
> +can be the groups belonging to that server.

This is better rephrased in our usual style:

  The value can also be a list of the form
  @code{(@var{server} @var{group}@dots{})}, where @var{server} is the
  server and @var{group}s are the groups belonging to the server.

> +To search in the current group in addition to other groups the list of servers
                                                             ^
Again missing comma.

> +If @code{current} is not in the list the current group is not searched,
                                       ^
Same here.

> +note this may be not the desired effect if any of articles referred in
> +the thread are not contained in any of the searched groups.

I would divide this sentence into two:

   If @code{current} is not in the list, ... is not searched.  This
   may not be the desired effect if ...

> +(defun gnus-refer-thread-maybe-add-current-group (group)
> +  "Find if GROUP should be added to `gnus-refer-thread-use-search'."

"Find" is to abstract and withholds information.  Suggest to rephrase:

    Return t if GROUP should be added to `gnus-refer-thread-use-search'.
  Return nil otherwise.

> +The list of of server and groups may contain
> +the symbol `current' to refer to the current group.
> +For example to search in the current group in addition to other groups.
              ^
Comma missing there.

Thanks.