Subject: bug#56863: closed (Re: bug#56863: 28.1; "internal variable" in doc)

From: [email-masked] (GNU bug Tracking System)
Date: Mon, 01 Aug 2022 17:04:01 +0000

Your bug report

#56863: 28.1; "internal variable" in doc

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].

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

Subject: Re: bug#56863: 28.1; "internal variable" in doc
From: Eli Zaretskii <[email-masked]>
To: Drew Adams <[email-masked]>
Cc: [email-masked]
Date: Mon, 01 Aug 2022 20:03:23 +0300
List-Id: <debbugs-submit.debbugs.gnu.org>

> From: Drew Adams <[email-masked]>
> Date: Sun, 31 Jul 2022 20:17:58 +0000
> 
>  (defvar foo 50)
> (defvaralias 'fill-column 'foo)
> 
> --> Error "Cannot make an internal variable an alias"
> 
> The error msg should show the name of the variable in question.

I added the name to the message.

> But the real bug is that "internal variable" isn't clear/defined.

I made it say "built-in" instead of "internal".

Thanks.

Subject: 28.1; "internal variable" in doc
From: Drew Adams <[email-masked]>
To: "[email-masked]" <[email-masked]>
Date: Sun, 31 Jul 2022 20:17:58 +0000
List-Id: <debbugs-submit.debbugs.gnu.org>

 (defvar foo 50)
(defvaralias 'fill-column 'foo)

--> Error "Cannot make an internal variable an alias"

The error msg should show the name of the variable in question.

But the real bug is that "internal variable" isn't clear/defined.  Nor
is it otherwise clear what the error message means or why it's an error
to (apparently) try to alias a defvar defined in C to some other defvar.

Searching the Elisp manual for "internal variable" shows only one
occurrence, in node `Documentation Tips', where the term has a very
different meaning:

  An internal variable or subroutine of a Lisp program might as well
  have a documentation string.  Documentation strings take up very
  little space in a running Emacs.

It's not clear what it means there either, but it's pretty clear that
whatever meaning is intended there is unrelated to whatever meaning is
intended in that error message.

Please clean up the doc to make clear what's meant, in both cases.

For a function defined in C and callable from Lisp we use the terms
"primitive" and "built-in function".  I haven't found a term for defvars
(or defcustoms) that are defined in C.  But certainly such variables are
in no way "internal" to anything, AFAICT.  They are defined in C; that's
all.

Furthermore, the presentation of `defvaralias' in the Elisp manual (node
`Variable Aliases') says nothing about any restriction of which defvars
it applies to - nothing about "internal variables", even under some
other name.  AFAICT.

Secondarily, searching for "internal" in the Elisp manual takes you to
node `Function Names' where the `--' convention for names of internal
functions is presented.  I haven't found any such presentation of `--'
for names of "internal" variables.  But presumably a variable name with
`--' is internal in yet another sense (presumably the same sense as for
"internal function").

Also secondarily, node `Tips for Defining' mentions variable names with
`PREFIX-...' and `...-internal' as being "internal".  Should that node
also mention names with `--'?

Also secondarily, node `Creating Buffer-Local' says this:

  For example, when a variable is used for internal purposes in a Lisp
  program which depends on having separate values in separate buffers

Yet another use of "internal" for variables.  My suggestion here is to
simply remove the word "internal", or even "for internal purposes" -
that adds nothing here and can only confuse.  Just a suggestion.

(There are of course multiple uses of "internal" in the docs, with
differences in meaning according to the context.  No problem there.
This bug report is about mention of "internal" variables.)

In GNU Emacs 28.1 (build 2, x86_64-w64-mingw32)
 of 2022-04-21 built on AVALON
Windowing system distributor 'Microsoft Corp.', version 10.0.19044
System Description: Microsoft Windows 10 Pro (v10.0.2009.19044.1826)

Configured using:
 'configure --with-modules --without-dbus --with-native-compilation
 --without-compress-install CFLAGS=-O2'

Configured features:
ACL GIF GMP GNUTLS HARFBUZZ JPEG JSON LCMS2 LIBXML2 MODULES NATIVE_COMP
NOTIFY W32NOTIFY PDUMPER PNG RSVG SOUND THREADS TIFF TOOLKIT_SCROLL_BARS
XPM ZLIB

(NATIVE_COMP present but libgccjit not available)