Commit 16358d4f authored by Eli Zaretskii's avatar Eli Zaretskii
Browse files

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.
parent a89f0b6f
......@@ -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
......
......@@ -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
......
......@@ -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"));
......
......@@ -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"));
......
......@@ -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"));
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment