Re: `gnus-build-sparse-threads' docstring

[Eric Abrahamsen <eric@ericabrahamsen.net>]

"Garreau, Alexandre" <galex-713@galex-713.eu> writes:

> On 2018/10/18 at 15:57, Garreau, Alexandre wrote:
>>
>> When putting a raw symbol, not to be evaluated, in docstring,
>> `describe-variable' highlights these as links to same-name symbol
>> description (`describe-symbol').  Yet in `gnus-build-sparse-threads',
>> “'some” doesn’t refer to `some' (the cl function, alias for `cl-some'),
>> so I guess it would be more correctly written as “'some” or 'some
>> directly, instead of `some'.
>
> Also I find the docstring rather less explanative about the use of
> “'all”/t (what’s the difference with “more”?), see afterwards:
>
> Docstring:
>   "*If non-nil, fill in the gaps in threads.
> If `some', only fill in the gaps that are needed to tie loose threads
> together.  If `more', fill in all leaf nodes that Gnus can find.  If
> non-nil and non-`some', fill in all gaps that Gnus manages to guess."
>
> Manual:
>      Fetching old headers can be slow.  A low-rent similar effect can be
>      gotten by setting this variable to ‘some’.  Gnus will then look at
>      the complete ‘References’ headers of all articles and try to string
>      together articles that belong in the same thread.  This will leave
>      “gaps” in the threading display where Gnus guesses that an article
>      is missing from the thread.  (These gaps appear like normal summary
>      lines.  If you select a gap, Gnus will try to fetch the article in
>      question.)  If this variable is ‘t’, Gnus will display all these
>      “gaps” without regard for whether they are useful for completing
>      the thread or not.  Finally, if this variable is ‘more’, Gnus won’t
>      cut off sparse leaf nodes that don’t lead anywhere.  This variable
>      is ‘nil’ by default.

I agree this is a little confusing, particularly regarding the
difference between `some' and `more'. I guess `some' will only collect
unread messages together, while `more' will do that, but also pull in
sibling messages (?), while `all' will try to travel all the way up to
the thread roots. Maybe.