[Emacs-diffs] emacs-26 16358d4: Improve documentation of "constant" symbols

[Eli Zaretskii]

branch: emacs-26
commit 16358d4fcbad3fa60ff36167ae666b1ec7e7c02a
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Improve documentation of "constant" symbols
    
    * src/font.c (syms_of_font) <font-weight-table, font-slant-table>
    <font-width-table>:
    * src/data.c (syms_of_data) <most-positive-fixnum>
    <most-negative-fixnum>:
    * src/buffer.c (syms_of_buffer) <enable-multibyte-characters>:
    Mention in the doc strings that these variables are read-only.
    
    * doc/lispref/variables.texi (Creating Buffer-Local): Document
    that making a constant variable buffer-local signals an error.
    * doc/lispref/variables.texi (Constant Variables):
    * doc/lispref/errors.texi (Standard Errors): More accurate and
    up-to-date documentation of which symbols cannot be assigned
    values.
---
 doc/lispref/errors.texi    |  7 +++++--
 doc/lispref/variables.texi | 13 +++++++++++++
 src/buffer.c               |  2 ++
 src/data.c                 |  6 ++++--
 src/font.c                 |  9 ++++++---
 5 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi
index 1f67819..cd22b70 100644
--- a/doc/lispref/errors.texi
+++ b/doc/lispref/errors.texi
@@ -172,8 +172,11 @@ The message is @samp{Search failed}.  @xref{Searching and 
Matching}.
 
 @item setting-constant
 The message is @samp{Attempt to set a constant symbol}.  This happens
-when attempting to assign values to @code{nil}, @code{t}, and keyword
-symbols.  @xref{Constant Variables}.
+when attempting to assign values to @code{nil}, @code{t},
address@hidden, @code{most-negative-fixnum}, and keyword
+symbols.  It also happens when attempting to assign values to
address@hidden and some other symbols whose direct
+assignment is not allowed for some reason.  @xref{Constant Variables}.
 
 @c simple.el
 @item text-read-only
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 99bbfc9..a871352 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -139,6 +139,13 @@ Variables}).  A @code{defconst} form serves to inform 
human readers
 that you do not intend to change the value of a variable, but Emacs
 does not raise an error if you actually change it.
 
address@hidden read-only variables
+A small number of additional symbols are made read-only for various
+practical reasons.  These include @code{enable-multibyte-characters},
address@hidden, @code{most-negative-fixnum}, and a few
+others.  Any attempt to set or bind these also signals a
address@hidden error.
+
 @node Local Variables
 @section Local Variables
 @cindex binding local variables
@@ -1355,6 +1362,9 @@ is not current either on entry to or exit from the 
@code{let}.  This is
 because @code{let} does not distinguish between different kinds of
 bindings; it knows only which variable the binding was made for.
 
+It is an error to make a constant or a read-only variable
+buffer-local.  @xref{Constant Variables}.
+
 If the variable is terminal-local (@pxref{Multiple Terminals}), this
 function signals an error.  Such variables cannot have buffer-local
 bindings as well.
@@ -1394,6 +1404,9 @@ in a void buffer-local value and leave the default value 
unaffected.
 
 The value returned is @var{variable}.
 
+It is an error to make a constant or a read-only variable
+buffer-local.  @xref{Constant Variables}.
+
 @strong{Warning:} Don't assume that you should use
 @code{make-variable-buffer-local} for user-option variables, simply
 because users @emph{might} want to customize them differently in
diff --git a/src/buffer.c b/src/buffer.c
index 6e3412c..c6f9eb2 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -5620,6 +5620,8 @@ file I/O and the behavior of various editing commands.
 
 This variable is buffer-local but you cannot set it directly;
 use the function `set-buffer-multibyte' to change a buffer's representation.
+To prevent any attempts to set it or make it buffer-local, Emacs will
+signal an error in those cases.
 See also Info node `(elisp)Text Representations'.  */);
   make_symbol_constant (intern_c_string ("enable-multibyte-characters"));
 
diff --git a/src/data.c b/src/data.c
index b4f6fd5..d54c46d 100644
--- a/src/data.c
+++ b/src/data.c
@@ -3880,12 +3880,14 @@ syms_of_data (void)
   set_symbol_function (Qwholenump, XSYMBOL (Qnatnump)->u.s.function);
 
   DEFVAR_LISP ("most-positive-fixnum", Vmost_positive_fixnum,
-              doc: /* The largest value that is representable in a Lisp 
integer.  */);
+              doc: /* The largest value that is representable in a Lisp 
integer.
+This variable cannot be set; trying to do so will signal an error.  */);
   Vmost_positive_fixnum = make_number (MOST_POSITIVE_FIXNUM);
   make_symbol_constant (intern_c_string ("most-positive-fixnum"));
 
   DEFVAR_LISP ("most-negative-fixnum", Vmost_negative_fixnum,
-              doc: /* The smallest value that is representable in a Lisp 
integer.  */);
+              doc: /* The smallest value that is representable in a Lisp 
integer.
+This variable cannot be set; trying to do so will signal an error.  */);
   Vmost_negative_fixnum = make_number (MOST_NEGATIVE_FIXNUM);
   make_symbol_constant (intern_c_string ("most-negative-fixnum"));
 
diff --git a/src/font.c b/src/font.c
index 51625b4..f7cebdc 100644
--- a/src/font.c
+++ b/src/font.c
@@ -5421,19 +5421,22 @@ gets the repertory information by an opened font and 
ENCODING.  */);
               doc: /*  Vector of valid font weight values.
 Each element has the form:
     [NUMERIC-VALUE SYMBOLIC-NAME ALIAS-NAME ...]
-NUMERIC-VALUE is an integer, and SYMBOLIC-NAME and ALIAS-NAME are symbols. */);
+NUMERIC-VALUE is an integer, and SYMBOLIC-NAME and ALIAS-NAME are symbols.
+This variable cannot be set; trying to do so will signal an error.  */);
   Vfont_weight_table = BUILD_STYLE_TABLE (weight_table);
   make_symbol_constant (intern_c_string ("font-weight-table"));
 
   DEFVAR_LISP_NOPRO ("font-slant-table", Vfont_slant_table,
               doc: /*  Vector of font slant symbols vs the corresponding 
numeric values.
-See `font-weight-table' for the format of the vector. */);
+See `font-weight-table' for the format of the vector.
+This variable cannot be set; trying to do so will signal an error.  */);
   Vfont_slant_table = BUILD_STYLE_TABLE (slant_table);
   make_symbol_constant (intern_c_string ("font-slant-table"));
 
   DEFVAR_LISP_NOPRO ("font-width-table", Vfont_width_table,
               doc: /*  Alist of font width symbols vs the corresponding 
numeric values.
-See `font-weight-table' for the format of the vector. */);
+See `font-weight-table' for the format of the vector.
+This variable cannot be set; trying to do so will signal an error.  */);
   Vfont_width_table = BUILD_STYLE_TABLE (width_table);
   make_symbol_constant (intern_c_string ("font-width-table"));