Re: When will emacs 27.1 be officially released?

[Tassilo Horn]

Paul Eggert <eggert@cs.ucla.edu> writes:

>> I just looked at the docs and it seems that in large parts the
>> function descriptions in the manual read
>> 
>>   This function takes a @var{coin} and returns a @var{beer}.
>> 
>> (indicative) whereas the docstring reads
>> 
>>   Take a COIN and return a BEER.
>> 
>> (imperative).  I know the latter is our convention for function
>> docstrings.  Is the former our convention for documenting functions
>> in the manual?
>
> Yes but I'd rather we switched to imperative, for consistency and
> brevity.

I'm all for consistency though the imperative style feels a bit awkward
to me.  Oftentimes, it's applied only to the first sentence of a
docstring and not completely.  For example, find-file-noselect's
docstring almost gets it right but then has the indicative sentence

  The buffer is not selected, just returned to the caller.

in the middle instead of the proper

  Do not select the buffer, just return it to the caller.

Bye,
Tassilo