Subject: Re: bug#79484: [PATCH] ; * doc/misc/gnus.texi (Optional Back End Functions): Add new ones

From: Eli Zaretskii <[email-masked]>
Date: Mon, 22 Sep 2025 09:34:38 +0300

> Date: Mon, 22 Sep 2025 04:19:28 +0530
> From:  James Thomas via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <[email-masked]>
> 
> As used in gnus-start.el & gnus-int.el (for nntp & nnimap as of now).

Thanks.

The patch as submitted has several markup and Texinfo usage issues,
see below.

> +@item (nnchoke-retrieve-group-data-early SERVER &optional INFOS)

The arguments should be in @var{...} and should not be capitalized.
(Yes, I know all the rest of this node and its parent and siblings use
this incorrect practice, but at the very least we should not
proliferate the mistakes.  Bonus points for fixing those other nodes
as well.)

> +This is for starting an early async retrieval from @code{server} to
> +update @code{infos},

References to function arguments should use @var, not @code.

>                       its current @xref{Group Info} list. The return

@xref is only appropriate at the beginning of a sentence, because it
produces a capitalized "See".  Also, our convention is to leave 2
spaces between sentences.

> +value is a token for the corresponding ``-finish-'' function (below).
                                          ^^^^^^^^^^^^
This should be in @code, not quoted by ``...''.

> +@item (nnchoke-finish-retrieve-group-infos SERVER INFOS DATA)
> +
> +This will be called later to conclude the async retrieval (above) -
> +whose token is passed as @code{data} - and should update @code{infos}.

Same here.  Also, please use "--" for a dash, since a single "-" will
be typeset as a minus sign, which is not what you want.