backend stuff for the manual

backend stuff for the manual

[Paul Jarc]

For nnchoke-request-newgroups, the description of the date format is
not very informative.  It should be mentioned that it is the format
produced by (current-time-string), and that it can be converted to a
(high . low) date via (date-to-time).  nnml ignores the date; the
manual should mention that it is safe to do this, and that the date is
useful only if listing the new groups is faster than listing all
groups.  (Assuming this is indeed correct; is it?)

For nnchoke-request-create-group, the third argument is not
documented.  How is it supposed to be used?


paul

Re: backend stuff for the manual

[Kai Großjohann]

prj@po.cwru.edu (Paul Jarc) writes:

> For nnchoke-request-newgroups, the description of the date format is
> not very informative.  It should be mentioned that it is the format
> produced by (current-time-string), and that it can be converted to a
> (high . low) date via (date-to-time).  nnml ignores the date; the
> manual should mention that it is safe to do this, and that the date is
> useful only if listing the new groups is faster than listing all
> groups.  (Assuming this is indeed correct; is it?)

What do you think of the following paragraph?

/----
| @item (nnchoke-request-newgroups DATE &optional 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
| (i.e., the date format used in mail and news headers, and returned by
| the function @code{current-time-string} by default).  The data should be
| in the active buffer format.  (It is okay for this function to return
| `too many' groups; some backends might find it cheaper to return the
| full list of groups, rather than just the new groups.  But don't do this
| for backends with too many groups.)
\----


kai
-- 
Symbol's function definition is void: signature

Re: backend stuff for the manual

[Kai Großjohann]

prj@po.cwru.edu (Paul Jarc) writes:

> For nnchoke-request-create-group, the third argument is not
> documented.  How is it supposed to be used?

I think it isn't used at all?!?

I looked at nnmbox-, nnfolder-, nnml-, and
nnimap-request-create-group.  These functions don't use the ARGS
argument.

I looked at gnus-request-create-group which presumably calls these
functions.  It just passes on its own ARGS parameter.

I then looked for callers of gnus-request-create-group.  None passed
ARGS, except for gnus-group-make-group, which passes on its own ARGS
parameter.

I then looked for callers of gnus-group-make-group.  The ARGS
parameter was not used.

[time passes]

OK, now I searched for all occurrences of -request-create-group, and
the ARGS parameter was not used in calls, except for functions which
just passed on their own ARGS parameter.

I think that this means that ARGS is not used.

Is anybody adventurous enough to try deleting it?  If it works, submit
a patch, then it will be deleted from the Gnus sources.  (This job can
be done by anybody, I think, no Lisp experience required.  Just a good
backup of your mail  :-)

kai
-- 
Symbol's function definition is void: signature

Re: backend stuff for the manual

[Paul Jarc]

Kai.Grossjohann@CS.Uni-Dortmund.DE (Kai Großjohann) wrote:
> What do you think of the following paragraph?

I like it.

>| The result data from this function should be all groups that were

Maybe "should include all groups"?  Just to be a bit less
contradictory with the note that follows.

>| in the active buffer format.  (It is okay for this function to return
>| `too many' groups; some backends might find it cheaper to return the
>| full list of groups, rather than just the new groups.  But don't do this
>| for backends with too many groups.)

Maybe also add a note about how to predict whether there are "too
many" groups:

If the user controls the server's list of groups (as with mail
backends), then there are likely to be few groups.  If the user does
not control the server's list of groups (as with NNTP), then there are
likely to be many groups that aren't of interest.

Or maybe not.


paul

Re: backend stuff for the manual

[Kai Großjohann]

prj@po.cwru.edu (Paul Jarc) writes:

> Kai.Grossjohann@CS.Uni-Dortmund.DE (Kai Großjohann) wrote:
> > What do you think of the following paragraph?
>
> I like it.
>
>>| The result data from this function should be all groups that were
>
> Maybe "should include all groups"?  Just to be a bit less
> contradictory with the note that follows.

Hm.  Maybe.

>>| in the active buffer format.  (It is okay for this function to return
>>| `too many' groups; some backends might find it cheaper to return the
>>| full list of groups, rather than just the new groups.  But don't do this
>>| for backends with too many groups.)
>
> Maybe also add a note about how to predict whether there are "too
> many" groups:

I tried to add that.

kai
-- 
Symbol's function definition is void: signature