mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-06 06:20:55 -08:00
Code Issues Projects Releases Wiki Activity

; Avoid passive tense in Emacs manual

Browse source 
* doc/lispref/variables.texi (Defining Variables): Avoid passive
tense (bug#76135).
This commit is contained in:
Eli Zaretskii 2025-02-08 13:47:11 +02:00
parent be4cf26c16
commit 223ee56aae
1 changed files with 24 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

44
doc/lispref/variables.texi
View file

@ -499,33 +499,37 @@ initializes it only if it is originally void.
Definitions}. Definitions}.
@defspec defvar symbol [value [doc-string]] @defspec defvar symbol [value [doc-string]]
This special form defines @var{symbol} as a variable. Note that This special form defines @var{symbol} as a variable and optionally
@var{symbol} is not evaluated; the symbol to be defined should appear initializes and documents it. Note that it doesn't evaluate
explicitly in the @code{defvar} form. The variable is marked as @var{symbol}; the symbol to be defined should appear explicitly in the
@dfn{special}, meaning that it should always be dynamically bound @code{defvar} form. @code{defvar} also marks @var{symbol} as
@dfn{special}, meaning that its bindings should always be dynamic
(@pxref{Variable Scoping}). (@pxref{Variable Scoping}).
If @var{value} is specified, and @var{symbol} is void (i.e., it has no If @var{value} is specified, and @var{symbol} is void (i.e., it has no
dynamically bound value; @pxref{Void Variables}), then @var{value} is dynamically bound value; @pxref{Void Variables}), then @code{defvar}
evaluated and @var{symbol} is set to the result. But if @var{symbol} evaluates @var{value}, and initializes @var{symbol} by setting it to the
is not void, @var{value} is not evaluated, and @var{symbol}'s value is result of the evaluation. But if @var{symbol} is not void,
left unchanged. If @var{value} is omitted, the value of @var{symbol} @code{defvar} does not evaluate @var{value}, and leaves @var{symbol}'s
is not changed in any case. value unchanged. If @var{value} is omitted, @code{defvar} doesn't
change the value of @var{symbol} in any case.
Note that specifying a value, even @code{nil}, marks the variable as Note that specifying a value, even @code{nil}, marks the variable as
special permanently. Whereas if @var{value} is omitted then the special permanently. Whereas if @var{value} is omitted, then
variable is only marked special locally (i.e.@: within the current @code{defvar} marks the variable special only locally (i.e.@: within the
lexical scope, or file if at the top-level). This can be useful for current lexical scope, or within the current file, if @code{defvar} is
suppressing byte compilation warnings, see @ref{Compiler Errors}. at the top-level). This can be useful for suppressing byte compilation
warnings, see @ref{Compiler Errors}.
If @var{symbol} has a buffer-local binding in the current buffer, If @var{symbol} has a buffer-local binding in the current buffer, and
@code{defvar} acts on the default value, which is buffer-independent, @var{value} is specified, @code{defvar} modifies the default value of
rather than the buffer-local binding. It sets the default value if @var{symbol}, which is buffer-independent, rather than the buffer-local
the default value is void. @xref{Buffer-Local Variables}. binding. It sets the default value if the default value is void.
@xref{Buffer-Local Variables}.
If @var{symbol} is already let bound (e.g., if the @code{defvar} If @var{symbol} is already let bound (e.g., if the @code{defvar} form
form occurs in a @code{let} form), then @code{defvar} sets the toplevel occurs in a @code{let} form), then @code{defvar} sets the toplevel
default value, like @code{set-default-toplevel-value}. default value of @var{symbol}, like @code{set-default-toplevel-value}.
The let binding remains in effect until its binding construct exits. The let binding remains in effect until its binding construct exits.
@xref{Variable Scoping}. @xref{Variable Scoping}.