bug#56863: 28.1; "internal variable" in doc

[Drew Adams]

 (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)