GNU bug report logs - #53720
Documentation for emacs-version

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 53720 in the body.
You can then email your comments to 53720 AT debbugs.gnu.org in the normal way.

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

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

From: goncholden <goncholden <at> protonmail.com>
To: Drew Adams <drew.adams <at> oracle.com>,
 "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: Documentation for emacs-version
Date: Wed, 02 Feb 2022 10:03:29 +0000

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

On Tuesday, February 1st, 2022 at 5:49 PM, Drew Adams <drew.adams <at> oracle.com> wrote:

> I am looking up documentation for emacs-version. But cannot understand the
>
> meaning of
>
> If optional argument HERE is non-nil, insert string at point.
>
> Doc:
>
> (emacs-version &optional HERE)
>
> Probably introduced at or before Emacs version 19.20.
>
> Return string describing the version of Emacs that is running.
>
> If optional argument HERE is non-nil, insert string at point.

This is the doc string for Emacs 27.2 (the latest release):

Return string describing the version of Emacs that is running.

If optional argument HERE is non-nil, insert string at point.

Don’t use this function in programs to choose actions according

to the system configuration; look at ‘system-configuration’ instead.

But it's still a poor doc string. It should, first

of all, describe the interactive use. It should say:

With a prefix argument, insert string at point.

^^^^^^^^^^^^^^^^^^^^^^

Only after that interactive description should it

give the Emacs-Lisp description of argument HERE:

When called from Lisp, optional argument HERE

corresponds to the prefix argument.

Consider filing a (doc) bug report for this:

`M-x report-emacs-bug'.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: goncholden <goncholden <at> protonmail.com>
Cc: 53720-done <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#53720: Documentation for emacs-version
Date: Wed, 02 Feb 2022 19:40:08 +0200

> Date: Wed, 02 Feb 2022 10:03:29 +0000
> From:  goncholden via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> > (emacs-version &optional HERE)
> > Probably introduced at or before Emacs version 19.20.
> > Return string describing the version of Emacs that is running.
> > If optional argument HERE is non-nil, insert string at point.
> 
> This is the doc string for Emacs 27.2 (the latest release):
> 
> Return string describing the version of Emacs that is running.
> If optional argument HERE is non-nil, insert string at point.
> Don’t use this function in programs to choose actions according
> to the system configuration; look at ‘system-configuration’ instead.
> But it's still a poor doc string. It should, first
> of all, describe the interactive use. It should say:
> With a prefix argument, insert string at point.
> ^^^^^^^^^^^^^^^^^^^^^^
> Only after that interactive description should it
> give the Emacs-Lisp description of argument HERE:
> When called from Lisp, optional argument HERE
> corresponds to the prefix argument.
> Consider filing a (doc) bug report for this:
> `M-x report-emacs-bug'.

Thanks, I fixed the wording of the doc string.

Previous Next

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