Subject: bug#53720: closed (Re: bug#53720: Documentation for emacs-version)

From: [email-masked] (GNU bug Tracking System)
Date: Wed, 02 Feb 2022 17:42:01 +0000

Your bug report

#53720: Documentation for emacs-version

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
53720: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=53720
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#53720: Documentation for emacs-version
From: Eli Zaretskii <[email-masked]>
To: goncholden <[email-masked]>
Cc: [email-masked], [email-masked]
Date: Wed, 02 Feb 2022 19:40:08 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

> Date: Wed, 02 Feb 2022 10:03:29 +0000
> From:  goncholden via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <[email-masked]>
> 
> > (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.

Subject: Documentation for emacs-version
From: goncholden <[email-masked]>
To: Drew Adams <[email-masked]>, "[email-masked]" <[email-masked]>
Date: Wed, 02 Feb 2022 10:03:29 +0000
List-Id: <debbugs-submit.debbugs.gnu.org>

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

On Tuesday, February 1st, 2022 at 5:49 PM, Drew Adams <[email-masked]> 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'.