can you explain the sentence about defvar in elisp?

[waterloo]

When you specified a variable using the `defvar' special form, you
could distinguish a readily settable variable from others by typing an
asterisk, `*', in the first column of its documentation string.  For
example:

     (defvar shell-command-default-error-buffer nil
       "*Buffer name for `shell-command' ... error output.
     ... ")

I can not understant it "distinguish a readily settable variable from others" ?

Thanks

[Drew Adams]

> When you specified a variable using the `defvar' special form, you
> could distinguish a readily settable variable from others by typing an
> asterisk, `*', in the first column of its documentation string. For
> example:

> (defvar shell-command-default-error-buffer nil

> "*Buffer name for `shell-command'...error output...")

> I can not understant it "distinguish a readily settable variable
> from others" ?

What is meant is a "user option", sometimes called a "user variable" or just an
"option". See the Emacs manual, node `Variables'.

An option is, by definition, any variable that can be set using command
`set-variable' or using the so-called "Customize" or "Easy Customization" user
interface. In recent versions of Emacs, every option that can be set using
Customize can also be set using `M-x set-variable'. See the Emacs manual, node
`Easy Customization' for more information about Customize.

The terms "customizable" and "customize" are a bit ambiguous. Sometimes they are
used to refer only to the use of the Customize UI (Easy Customization). But
sometimes they are used to refer to any changes made by users. In addition to
variable values, you can use Customize to customize Emacs faces. Emacs key
bindings are typically customized using functions such as `global-set-key' and
`define-key'.

In Emacs Lisp:

. `defvar' defines a global variable. If `*' is the first character of the doc
string, then the variable is a user variable, but it is not customizable using
Customize.

. `defcustom' defines a global option that is customizable using Customize. In
recent versions of Emacs, the first doc-string character need not be `*' for the
option to also be settable using `M-x set-variable'.

See also: http://www.emacswiki.org/emacs/CustomizingAndSaving

----

BTW, I don't see the text or the example that you cited anywhere in the Elisp
manual - in Emacs 20, 21, 22, or 23. Where did you find this? In the Elisp
manual, node `Defining Variables', I see `*' described explicitly as pertaining
to command `set-variable'.

If the text you cited is in an Emacs 23 manual somewhere, then please file an
Emacs (doc) bug, using `M-x report-emacs-bug'. Explain that the text you cited
is not clear to you. In particular, "readily settable variable" is unclear. What
is missing (in the text you cited) is an explicit reference to _interactive_
setting using `M-x set-variable'.

[waterloo]

thanks

it is in 8.5.1 `defvar' and an asterisk of  emacs23.0.95.1.

2009/7/4 Drew Adams <drew....@oracle.com>

[Drew Adams]

> it is in 8.5.1 `defvar' and an asterisk of emacs23.0.95.1.

[waterloo]

it is 8.5.1 in Introduction to emacs lisp of emacs23.0.95.1

thanks

2009/7/4 Drew Adams <drew....@oracle.com>

[Drew Adams]

> it is 8.5.1 in Introduction to emacs lisp of emacs23.0.95.1

Fine. As I said:

"then please file an Emacs (doc) bug, using `M-x report-emacs-bug'."

I made a suggestion of what to report:

"Explain that the text you cited is not clear to you. In particular,
`readily settable variable' is unclear. What is missing (in the text
you cited) is an explicit reference to _interactive_
setting using `M-x set-variable'."

But that's just a suggestion. It's _your_ bug report; explain the problem as you
see it. help-gnu-emacs is a help mailing list; it is not the place to report
bugs. Use `M-x report-emacs-bug' to report a bug.

The location is indeed section 8.5.1 in the manual `An Introduction to
Programming in Emacs Lisp', that is, Info node `defvar and asterisk'.