Re: When will emacs 27.1 be officially released?

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

On 7/2/20 1:29 PM, Tassilo Horn wrote:
> 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}.

That is incorrect style for @var.  @var{coin} refers to the value of
the argument named 'coin', as a proper name.  It does not mean a
_type_ of value, it means _the value_.

It is incorrect style to use an article before @var.

Here's the start of the definition of 'nth':

    @defun nth n list
    @anchor{Definition of nth}
    This function returns the @var{n}th element of @var{list}.  Elements
    are numbered starting with zero, so the @sc{car} of @var{list} is
    element number zero.  If the length of @var{list} is @var{n} or less,
    the value is @code{nil}.

If you want to describe the type of something, to say that it is a list,
write "list" with NO markup.

Ironically, this is one style point on which we treat doc strings the same
as manuals.  Here's the doc string of nth:

    Return the Nth element of LIST.
    N counts from zero.  If LIST is not that long, nil is returned.

Once again, no article before an argument name.

When the argument name is a data type name, you can take that
to mean that the value should have that type.  Thus, LIST should be a list.

Does the Texinfo manual explain these conventions?  ISTR it does.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)