From: Eli Zaretskii Date: Sun, 26 Nov 2017 18:23:15 +0000 (+0200) Subject: Improve documentation of "constant" symbols X-Git-Tag: emacs-26.0.91~241 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=16358d4fcbad3fa60ff36167ae666b1ec7e7c02a;p=emacs.git Improve documentation of "constant" symbols * src/font.c (syms_of_font) : * src/data.c (syms_of_data) : * src/buffer.c (syms_of_buffer) : 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. --- diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index 1f67819c34e..cd22b70800d 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}, +@code{most-positive-fixnum}, @code{most-negative-fixnum}, and keyword +symbols. It also happens when attempting to assign values to +@code{enable-multibyte-characters} 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 99bbfc91243..a871352b004 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. +@cindex read-only variables +A small number of additional symbols are made read-only for various +practical reasons. These include @code{enable-multibyte-characters}, +@code{most-positive-fixnum}, @code{most-negative-fixnum}, and a few +others. Any attempt to set or bind these also signals a +@code{setting-constant} 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 6e3412c3d05..c6f9eb28e25 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 b4f6fd5c652..d54c46d72bf 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 51625b49fa8..f7cebdce78c 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"));