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

Previous Next

To reply to this bug, email your comments to 79484 AT debbugs.gnu.org.
There is no need to reopen the bug first.

Toggle the display of automated, internal messages from the tracker.

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

From: James Thomas <jimjoe <at> gmx.net>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] ; * doc/misc/gnus.texi (Optional Back End Functions): Add
 new ones
Date: Mon, 22 Sep 2025 04:19:28 +0530

[Message part 1 (text/plain, inline)]

As used in gnus-start.el & gnus-int.el (for nntp & nnimap as of now).

[0001-doc-misc-gnus-texi--Optional-Back-End-Function.patch (text/x-patch, attachment)]

[Message part 3 (text/plain, inline)]

--

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.

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

From: James Thomas <jimjoe <at> gmx.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 79484 <at> debbugs.gnu.org
Subject: Re: bug#79484: [PATCH] ; * doc/misc/gnus.texi (Optional Back End
 Functions): Add new ones
Date: Tue, 23 Sep 2025 04:56:04 +0530

[Message part 1 (text/plain, inline)]

Eli Zaretskii wrote:

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

Sorry, corrected:

[0001-doc-misc-gnus-texi--Optional-Back-End-Function.patch (text/x-patch, attachment)]

[Message part 3 (text/plain, inline)]

> (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.)

I have done that as a separate patch, for absolution. :-)

[0002-doc-misc-gnus-texi-Fix-formatting.patch (text/x-patch, attachment)]

[Message part 5 (text/plain, inline)]

--

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

From: James Thomas <jimjoe <at> gmx.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 79484 <at> debbugs.gnu.org
Subject: Re: bug#79484: [PATCH] ; * doc/misc/gnus.texi (Optional Back End
 Functions): Add new ones
Date: Tue, 23 Sep 2025 05:25:01 +0530

[Message part 1 (text/plain, inline)]

James Thomas wrote:

> Eli Zaretskii wrote:
>
>>> 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.
>>
>> ...
>
> Sorry, corrected:
>
>
>
>> (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.)
>
> I have done that as a separate patch, for absolution. :-)

Should be better the other way round:

[0001-doc-misc-gnus-texi-Fix-formatting.patch (text/x-patch, attachment)]

[0002-doc-misc-gnus-texi--Optional-Back-End-Function.patch (text/x-patch, attachment)]

[Message part 4 (text/plain, inline)]

--

Message #17 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: Sat, 27 Sep 2025 12:12:29 +0300

> From: James Thomas <jimjoe <at> gmx.net>
> Cc: 79484 <at> debbugs.gnu.org
> Date: Tue, 23 Sep 2025 05:25:01 +0530
> 
> James Thomas wrote:
> 
> > Eli Zaretskii wrote:
> >
> >>> 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.
> >>
> >> ...
> >
> > Sorry, corrected:
> >
> >
> >
> >> (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.)
> >
> > I have done that as a separate patch, for absolution. :-)
> 
> Should be better the other way round:

Thanks.  However, it sounds like I failed to explain myself:

>  @table @code
>  
> -@item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)
> +@item (nnchoke-retrieve-headers @code{articles} &optional @code{group} @code{server} @code{fetch-old})

The arguments of the function should have the @var markup, not @code,
in the @item lines as well as in the descriptive text.  (@code is
redundant anyway, since this is "@table @code", so @code is ON by
default.)

Sorry for not being more clear in my comments.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: 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: Sat, 11 Oct 2025 11:31:22 +0300

Ping!  Can we make some progress with this?

> Cc: 79484 <at> debbugs.gnu.org
> Date: Sat, 27 Sep 2025 12:12:29 +0300
> From: Eli Zaretskii <eliz <at> gnu.org>
> 
> > From: James Thomas <jimjoe <at> gmx.net>
> > Cc: 79484 <at> debbugs.gnu.org
> > Date: Tue, 23 Sep 2025 05:25:01 +0530
> > 
> > James Thomas wrote:
> > 
> > > Eli Zaretskii wrote:
> > >
> > >>> 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.
> > >>
> > >> ...
> > >
> > > Sorry, corrected:
> > >
> > >
> > >
> > >> (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.)
> > >
> > > I have done that as a separate patch, for absolution. :-)
> > 
> > Should be better the other way round:
> 
> Thanks.  However, it sounds like I failed to explain myself:
> 
> >  @table @code
> >  
> > -@item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)
> > +@item (nnchoke-retrieve-headers @code{articles} &optional @code{group} @code{server} @code{fetch-old})
> 
> The arguments of the function should have the @var markup, not @code,
> in the @item lines as well as in the descriptive text.  (@code is
> redundant anyway, since this is "@table @code", so @code is ON by
> default.)
> 
> Sorry for not being more clear in my comments.
> 
> 
> 
> 

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

From: James Thomas <jimjoe <at> gmx.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 79484 <at> debbugs.gnu.org
Subject: Re: bug#79484: [PATCH] ; * doc/misc/gnus.texi (Optional Back End
 Functions): Add new ones
Date: Sun, 12 Oct 2025 14:28:03 +0530

[Message part 1 (text/plain, inline)]

Eli Zaretskii <> writes:

> Ping!  Can we make some progress with this?
>
>> Cc: 79484 <at> debbugs.gnu.org
>> Date: Sat, 27 Sep 2025 12:12:29 +0300
>> From: Eli Zaretskii <>
>> 
>> > From: James Thomas <>
>> > Cc: 79484 <at> debbugs.gnu.org
>> > Date: Tue, 23 Sep 2025 05:25:01 +0530
>> > 
>> > James Thomas wrote:
>> > 
>> > > Eli Zaretskii wrote:
>> > >
>> > >>> 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.
>> > >>
>> > >> ...
>> > >
>> > > Sorry, corrected:
>> > >
>> > >
>> > >
>> > >> (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.)
>> > >
>> > > I have done that as a separate patch, for absolution. :-)
>> > 
>> > Should be better the other way round:
>> 
>> Thanks.  However, it sounds like I failed to explain myself:
>> 
>> >  @table @code
>> >  
>> > -@item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER
>> > FETCH-OLD)
>> > +@item (nnchoke-retrieve-headers @code{articles} &optional
>> > @code{group} @code{server} @code{fetch-old})
>> 
>> The arguments of the function should have the @var markup, not
>> @code,
>> in the @item lines as well as in the descriptive text.  (@code is
>> redundant anyway, since this is "@table @code", so @code is ON by
>> default.)
>> 
>> Sorry for not being more clear in my comments.

How about now:

[0002-doc-misc-gnus.texi-Optional-Back-End-Functions-Add-n.patch (text/x-patch, attachment)]

[0001-doc-misc-gnus.texi-Fix-formatting.patch (text/x-patch, attachment)]

[Message part 4 (text/plain, inline)]

(It also conforms to the Economist and NYT Manuals of Style, just in
case ;-))

--

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: James Thomas <jimjoe <at> gmx.net>
Cc: 79484-done <at> debbugs.gnu.org
Subject: Re: bug#79484: [PATCH] ; * doc/misc/gnus.texi (Optional Back End
 Functions): Add new ones
Date: Sun, 12 Oct 2025 12:46:08 +0300

> From: James Thomas <jimjoe <at> gmx.net>
> Cc: 79484 <at> debbugs.gnu.org
> Date: Sun, 12 Oct 2025 14:28:03 +0530
> 
> Eli Zaretskii <> writes:
> 
> > Ping!  Can we make some progress with this?
> >
> >> Cc: 79484 <at> debbugs.gnu.org
> >> Date: Sat, 27 Sep 2025 12:12:29 +0300
> >> From: Eli Zaretskii <>
> >> 
> >> > From: James Thomas <>
> >> > Cc: 79484 <at> debbugs.gnu.org
> >> > Date: Tue, 23 Sep 2025 05:25:01 +0530
> >> > 
> >> > James Thomas wrote:
> >> > 
> >> > > Eli Zaretskii wrote:
> >> > >
> >> > >>> 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.
> >> > >>
> >> > >> ...
> >> > >
> >> > > Sorry, corrected:
> >> > >
> >> > >
> >> > >
> >> > >> (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.)
> >> > >
> >> > > I have done that as a separate patch, for absolution. :-)
> >> > 
> >> > Should be better the other way round:
> >> 
> >> Thanks.  However, it sounds like I failed to explain myself:
> >> 
> >> >  @table @code
> >> >  
> >> > -@item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER
> >> > FETCH-OLD)
> >> > +@item (nnchoke-retrieve-headers @code{articles} &optional
> >> > @code{group} @code{server} @code{fetch-old})
> >> 
> >> The arguments of the function should have the @var markup, not
> >> @code,
> >> in the @item lines as well as in the descriptive text.  (@code is
> >> redundant anyway, since this is "@table @code", so @code is ON by
> >> default.)
> >> 
> >> Sorry for not being more clear in my comments.
> 
> How about now:

Perfect, thanks!  Installed on master, and closing the bug.

Previous Next

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