`gnus-build-sparse-threads' docstring

`gnus-build-sparse-threads' docstring

[Garreau, Alexandre]

Hi,

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'.

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

[Garreau, Alexandre]

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.

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

[Eric Abrahamsen]

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

> Hi,
>
> 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'.

The automatic hyperlinking can be disabled when inappropriate by having
the word "symbol" in front of the actual symbol. Here's a version that
creates no hyperlinks, though it's a tiny bit strained:

"If non-nil, fill in the gaps in threads.
If set to the symbol `some', only fill in the gaps that are
needed to tie loose threads together.  If the symbol `more', fill
in all leaf nodes that Gnus can find.  If neither nil nor the
symbol `some', fill in all gaps that Gnus manages to guess."

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

[Garreau, Alexandre]

Le 18/10/2018 à 09h22, Eric Abrahamsen a écrit :
> "Garreau, Alexandre" <galex-713@galex-713.eu> writes:
>> 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'.
>
> The automatic hyperlinking can be disabled when inappropriate by having
> the word "symbol" in front of the actual symbol. Here's a version that
> creates no hyperlinks, though it's a tiny bit strained:
>
> "If non-nil, fill in the gaps in threads.
> If set to the symbol `some', only fill in the gaps that are
> needed to tie loose threads together.  If the symbol `more', fill
> in all leaf nodes that Gnus can find.  If neither nil nor the
> symbol `some', fill in all gaps that Gnus manages to guess."

While discussing it on the emacs-devel mailing-list, I found it out
myself in the elisp manual ^^ I was going to write it out here before
reading your message x)

Shouldn’t it be changed in Gnus so the docstring displays correctly?

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

[Eric Abrahamsen]

"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.

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

[Eric Abrahamsen]

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

> Le 18/10/2018 à 09h22, Eric Abrahamsen a écrit :
>> "Garreau, Alexandre" <galex-713@galex-713.eu> writes:
>>> 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'.
>>
>> The automatic hyperlinking can be disabled when inappropriate by having
>> the word "symbol" in front of the actual symbol. Here's a version that
>> creates no hyperlinks, though it's a tiny bit strained:
>>
>> "If non-nil, fill in the gaps in threads.
>> If set to the symbol `some', only fill in the gaps that are
>> needed to tie loose threads together.  If the symbol `more', fill
>> in all leaf nodes that Gnus can find.  If neither nil nor the
>> symbol `some', fill in all gaps that Gnus manages to guess."
>
> While discussing it on the emacs-devel mailing-list, I found it out
> myself in the elisp manual ^^ I was going to write it out here before
> reading your message x)
>
> Shouldn’t it be changed in Gnus so the docstring displays correctly?

Probably, yes. I've opened bug bug#33090 with a patch for this.

Thanks,
Eric