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

Previous Next

Full log

Message #8 received at 79484 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: James Thomas <jimjoe <at> gmx.net>
Cc: 79484 <at> debbugs.gnu.org
Subject: Re: bug#79484: [PATCH] ;
 * doc/misc/gnus.texi (Optional Back End Functions): Add new ones
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" <bug-gnu-emacs <at> gnu.org>
> 
> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.