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

From: James Thomas <[email-masked]>
Date: Tue, 23 Sep 2025 04:56:04 +0530

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

Sorry, corrected:

From 3b2992ad8079f4814a8001680c6bed716b6a9466 Mon Sep 17 00:00:00 2001
From: James Thomas <[email-masked]>
Date: Mon, 22 Sep 2025 03:15:54 +0530
Subject: [PATCH] ; * doc/misc/gnus.texi (Optional Back End Functions): Add
 newer ones.

---
 doc/misc/gnus.texi | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index afde6d5c4d6..d30e4481fae 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -30276,6 +30276,18 @@ Optional Back End Functions
 group-buffer = *active-line / *group-status
 @end example
 
+@item (nnchoke-retrieve-group-data-early SERVER &optional INFOS)
+
+This is for starting an early async retrieval from @var{server} to
+update @var{infos}, its current group info structure list.  The return
+value is a token for the corresponding
+@code{nnchoke-finish-retrieve-group-infos}.
+
+@item (nnchoke-finish-retrieve-group-infos SERVER INFOS DATA)
+
+This will be called later to conclude the async retrieval of
+@code{nnchoke-retrieve-group-data-early} -- whose token is passed as
+@var{data} -- and should update @var{infos}.
 
 @item (nnchoke-request-update-info GROUP INFO &optional SERVER)
 
-- 
2.51.0

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

From 2eeacc9439248643af6a2e4535e0ea2bf7253b5a Mon Sep 17 00:00:00 2001
From: James Thomas <[email-masked]>
Date: Tue, 23 Sep 2025 04:46:48 +0530
Subject: [PATCH] ; * doc/misc/gnus.texi Fix formatting.

---
 doc/misc/gnus.texi | 58 +++++++++++++++++++++++-----------------------
 1 file changed, 29 insertions(+), 29 deletions(-)

diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index d30e4481fae..a447f1547da 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -30030,7 +30030,7 @@ Required Back End Functions
 
 @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})
 
 @var{articles} is either a range of article numbers or a list of
 @code{Message-ID}s.  Current back ends do not fully support either---only
@@ -30099,7 +30099,7 @@ Required Back End Functions
 @pxref{Headers}.

-@item (nnchoke-open-server SERVER &optional DEFINITIONS)
+@item (nnchoke-open-server @code{server} &optional @code{definitions})
 
 @var{server} is here the virtual server name.  @var{definitions} is a
 list of @code{(VARIABLE VALUE)} pairs that define this virtual server.
@@ -30112,7 +30112,7 @@ Required Back End Functions
 non-@code{nil} value.  There should be no data returned.

-@item (nnchoke-close-server &optional SERVER)
+@item (nnchoke-close-server &optional @code{server})
 
 Close connection to @var{server} and free all resources connected
 to it.  Return @code{nil} if the server couldn't be closed for some
@@ -30131,7 +30131,7 @@ Required Back End Functions
 There should be no data returned.

-@item (nnchoke-server-opened &optional SERVER)
+@item (nnchoke-server-opened &optional @code{server})
 
 If @var{server} is the current virtual server, and the connection to the
 physical server is alive, then this function should return a
@@ -30141,14 +30141,14 @@ Required Back End Functions
 There should be no data returned.

-@item (nnchoke-status-message &optional SERVER)
+@item (nnchoke-status-message &optional @code{server})
 
 This function should return the last error message from @var{server}.
 
 There should be no data returned.

-@item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)
+@item (nnchoke-request-article @code{article} &optional @code{group} @code{server} @code{to-buffer})
 
 The result data from this function should be the article specified by
 @var{article}.  This might either be a @code{Message-ID} or a number.
@@ -30169,7 +30169,7 @@ Required Back End Functions
 on successful article retrieval.

-@item (nnchoke-request-group GROUP &optional SERVER FAST INFO)
+@item (nnchoke-request-group @code{group} &optional @code{server} @code{fast} @code{info})
 
 Get data on @var{group}.  This function also has the side effect of
 making @var{group} the current group.
@@ -30204,7 +30204,7 @@ Required Back End Functions
 @end example

-@item (nnchoke-close-group GROUP &optional SERVER)
+@item (nnchoke-close-group @code{group} &optional @code{server})
 
 Close @var{group} and free any resources connected to it.  This will be
 a no-op on most back ends.
@@ -30212,7 +30212,7 @@ Required Back End Functions
 There should be no data returned.

-@item (nnchoke-request-list &optional SERVER)
+@item (nnchoke-request-list &optional @code{server})
 
 Return a list of all groups available on @var{server}.  And that means
 @emph{all}.
@@ -30241,7 +30241,7 @@ Required Back End Functions
 (@samp{=other-group}) or none of the above (@samp{y}).

-@item (nnchoke-request-post &optional SERVER)
+@item (nnchoke-request-post &optional @code{server})
 
 This function should post the current buffer.  It might return whether
 the posting was successful or not, but that's not required.  If, for
@@ -30260,7 +30260,7 @@ Optional Back End Functions
 
 @table @code
 
-@item (nnchoke-retrieve-groups GROUPS &optional SERVER)
+@item (nnchoke-retrieve-groups @code{groups} &optional @code{server})
 
 @var{groups} is a list of groups, and this function should request data
 on all those groups.  How it does it is of no concern to Gnus, but it
@@ -30276,20 +30276,20 @@ Optional Back End Functions
 group-buffer = *active-line / *group-status
 @end example
 
-@item (nnchoke-retrieve-group-data-early SERVER &optional INFOS)
+@item (nnchoke-retrieve-group-data-early @code{server} &optional @code{infos})
 
 This is for starting an early async retrieval from @var{server} to
 update @var{infos}, its current group info structure list.  The return
 value is a token for the corresponding
 @code{nnchoke-finish-retrieve-group-infos}.
 
-@item (nnchoke-finish-retrieve-group-infos SERVER INFOS DATA)
+@item (nnchoke-finish-retrieve-group-infos @code{server} @code{infos} @code{data})
 
 This will be called later to conclude the async retrieval of
 @code{nnchoke-retrieve-group-data-early} -- whose token is passed as
 @var{data} -- and should update @var{infos}.
 
-@item (nnchoke-request-update-info GROUP INFO &optional SERVER)
+@item (nnchoke-request-update-info @code{group} @code{info} &optional @code{server})
 
 A Gnus group info (@pxref{Group Info}) is handed to the back end for
 alterations.  This comes in handy if the back end really carries all
@@ -30302,7 +30302,7 @@ Optional Back End Functions
 There should be no result data from this function.

-@item (nnchoke-request-type GROUP &optional ARTICLE)
+@item (nnchoke-request-type @code{group} &optional @code{article})
 
 When the user issues commands for ``sending news'' (@kbd{F} in the
 summary buffer, for instance), Gnus has to know whether the article the
@@ -30316,7 +30316,7 @@ Optional Back End Functions
 There should be no result data from this function.

-@item (nnchoke-request-set-mark GROUP ACTION &optional SERVER)
+@item (nnchoke-request-set-mark @code{group} @code{action} &optional @code{server})
 
 Set/remove/add marks on articles.  Normally Gnus handles the article
 marks (such as read, ticked, expired etc.)@: internally, and store them in
@@ -30327,7 +30327,7 @@ Optional Back End Functions
 @var{action} is a list of mark setting requests, having this format:
 
 @example
-(RANGE ACTION MARK)
+(@code{range} @code{action} @code{mark})
 @end example
 
 @var{range} is a range of articles you wish to update marks on.
@@ -30357,7 +30357,7 @@ Optional Back End Functions
 
 There should be no result data from this function.
 
-@item (nnchoke-request-update-mark GROUP ARTICLE MARK)
+@item (nnchoke-request-update-mark @code{group} @code{article} @code{mark})
 
 If the user tries to set a mark that the back end doesn't like, this
 function may change the mark.  Gnus will use whatever this function
@@ -30373,7 +30373,7 @@ Optional Back End Functions
 There should be no result data from this function.

-@item (nnchoke-request-scan &optional GROUP SERVER)
+@item (nnchoke-request-scan &optional @code{group} @code{server})
 
 This function may be called at any time (by Gnus or anything else) to
 request that the back end check for incoming articles, in one way or
@@ -30387,7 +30387,7 @@ Optional Back End Functions
 There should be no result data from this function.

-@item (nnchoke-request-group-description GROUP &optional SERVER)
+@item (nnchoke-request-group-description @code{group} &optional @code{server})
 
 The result data from this function should be a description of
 @var{group}.
@@ -30398,7 +30398,7 @@ Optional Back End Functions
 description      = <text>
 @end example
 
-@item (nnchoke-request-list-newsgroups &optional SERVER)
+@item (nnchoke-request-list-newsgroups &optional @code{server})
 
 The result data from this function should be the description of all
 groups available on the server.
@@ -30408,7 +30408,7 @@ Optional Back End Functions
 @end example

-@item (nnchoke-request-newgroups DATE &optional SERVER)
+@item (nnchoke-request-newgroups @code{date} &optional @code{server})
 
 The result data from this function should be all groups that were
 created after @samp{date}, which is in normal human-readable date format
@@ -30425,14 +30425,14 @@ Optional Back End Functions
 server, it is quite likely that there can be many groups.

-@item (nnchoke-request-create-group GROUP &optional SERVER)
+@item (nnchoke-request-create-group @code{group} &optional @code{server})
 
 This function should create an empty group with name @var{group}.
 
 There should be no return data.

-@item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)
+@item (nnchoke-request-expire-articles @code{articles} &optional @code{group} @code{server} @code{force})
 
 This function should run the expiry process on all articles in the
 @var{articles} range (which is currently a simple list of article
@@ -30447,7 +30447,7 @@ Optional Back End Functions
 There should be no result data returned.

-@item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM &optional LAST)
+@item (nnchoke-request-move-article @code{article} @code{group} @code{server} @code{accept-form} &optional @code{last})
 
 This function should move @var{article} (which is a number) from
 @var{group} by calling @var{accept-form}.
@@ -30469,7 +30469,7 @@ Optional Back End Functions
 There should be no data returned.

-@item (nnchoke-request-accept-article GROUP &optional SERVER LAST)
+@item (nnchoke-request-accept-article @code{group} &optional @code{server} @code{last})
 
 This function takes the current buffer and inserts it into @var{group}.
 If @var{last} in @code{nil}, that means that there will be more calls to
@@ -30484,7 +30484,7 @@ Optional Back End Functions
 There should be no data returned.

-@item (nnchoke-request-replace-article ARTICLE GROUP BUFFER)
+@item (nnchoke-request-replace-article @code{article} @code{group} @code{buffer})
 
 This function should remove @var{article} (which is a number) from
 @var{group} and insert @var{buffer} there instead.
@@ -30492,7 +30492,7 @@ Optional Back End Functions
 There should be no data returned.

-@item (nnchoke-request-delete-group GROUP FORCE &optional SERVER)
+@item (nnchoke-request-delete-group @code{group} @code{force} &optional @code{server})
 
 This function should delete @var{group}.  If @var{force}, it should
 really delete all the articles in the group, and then delete the group
@@ -30501,7 +30501,7 @@ Optional Back End Functions
 There should be no data returned.

-@item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)
+@item (nnchoke-request-rename-group @code{group} @code{new-name} &optional @code{server})
 
 This function should rename @var{group} into @var{new-name}.  All
 articles in @var{group} should move to @var{new-name}.
-- 
2.51.0

--