comparison lispintro/emacs-lisp-intro.texi @ 89909:68c22ea6027c

Sync to HEAD

89908:ee1402f7b568

@c clear print-postscript-figures
@c ---------

@comment %**end of header

@set edition-number 2.10
@set update-date 2003 July 15

@ignore
 ## Summary of shell commands to create various output formats:

    ## Info output

@code{(interactive)}.  The @code{mark-whole-buffer} function is like
this.

Alternatively, if the special letter-codes are not right for your
application, you can pass your own arguments to @code{interactive} as
a list.  @xref{interactive, , Using @code{Interactive}, elisp, The
GNU Emacs Lisp Reference Manual}, for more information about this advanced
technique.

@node Permanent Installation, let, Interactive Options, Writing Defuns
@comment  node-name,  next,  previous,  up

In the past, Emacs used the @code{defvar} special form both for
internal variables that you would not expect a user to change and for
variables that you do expect a user to change.  Although you can still
use @code{defvar} for user customizable variables, please use
@code{defcustom} instead, since that special form provides a path into
the Customization commands.  (@xref{defcustom, , Setting Variables
with @code{defcustom}}.)

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

  "*Buffer name for `shell-command' @dots{} error output.
@dots{} ")
@end group
@end smallexample

@noindent
This means that you could (and still can) use the @code{edit-options}
command to change the value of
@code{shell-command-default-error-buffer} temporarily.

@findex edit-options
However, options set using @code{edit-options} are set only for the
duration of your editing session.  The new values are not saved
between sessions.  Each time Emacs starts, it reads the original
value, unless you change the value within your @file{.emacs} file,
either by setting it manually or by using @code{customize}.
@xref{Emacs Initialization, , Your @file{.emacs} File}.

For me, the major use of the @code{edit-options} command is to suggest
variables that I might want to set in my @file{.emacs} file.  I urge
you to look through the list.  (@xref{Edit Options, , Editing Variable
Values, emacs, The GNU Emacs Manual}.)

@node copy-region-as-kill, cons & search-fwd Review, defvar, Cutting & Storing Text
@comment  node-name,  next,  previous,  up
@section @code{copy-region-as-kill}
@findex copy-region-as-kill

to say, the symbol @code{flowers} holds the address of the pair of
address-boxes, the first of which holds the address of @code{violet},
and the second of which holds the address of @code{buttercup}.

A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted
pair}.  @xref{List Type, , List Type , elisp, The GNU Emacs Lisp
Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair
Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more
information about cons cells and dotted pairs.

@need 1200

@smallexample
(custom-set-variables '(eval-expression-print-length nil))
@end smallexample

@noindent
(@xref{defcustom, , Setting Variables with @code{defcustom}}.
Then evaluate the @code{lengths-list-file} expression.)

@need 1200
The lengths' list for @file{debug.el} takes less than a second to
produce and looks like this:

@noindent
The name of the variable is @code{text-mode-hook}; it has no default
value; and its documentation string tells you what it does.

The @code{:type} keyword tells Emacs what kind of data
@code{text-mode-hook} should be set to and how to display the value in
a Customization buffer.

The @code{:options} keyword specifies a suggested list of values for
the variable.  Currently, you can use @code{:options} only for a hook.
The list is only a suggestion; it is not exclusive; a person who sets
the variable may set it to other values; the list shown following the

@evenheading @thispage @| @| @thistitle
@oddheading            @| @| @thispage
@end iftex

@bye

89909:68c22ea6027c

@c clear print-postscript-figures
@c ---------

@comment %**end of header

@set edition-number 2.12
@set update-date 2003 Nov 19

@ignore
 ## Summary of shell commands to create various output formats:

    ## Info output

@code{(interactive)}.  The @code{mark-whole-buffer} function is like
this.

Alternatively, if the special letter-codes are not right for your
application, you can pass your own arguments to @code{interactive} as
a list.  @xref{Using Interactive, , Using @code{Interactive}, elisp, The
GNU Emacs Lisp Reference Manual}, for more information about this advanced
technique.

@node Permanent Installation, let, Interactive Options, Writing Defuns
@comment  node-name,  next,  previous,  up

In the past, Emacs used the @code{defvar} special form both for
internal variables that you would not expect a user to change and for
variables that you do expect a user to change.  Although you can still
use @code{defvar} for user customizable variables, please use
@code{defcustom} instead, since that special form provides a path into
the Customization commands.  (@xref{defcustom, , Specifying Variables
using @code{defcustom}}.)

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

  "*Buffer name for `shell-command' @dots{} error output.
@dots{} ")
@end group
@end smallexample

@findex set-variable
@noindent
You could (and still can) use the @code{set-variable} command to
change the value of @code{shell-command-default-error-buffer}
temporarily.  However, options set using @code{set-variable} are set
only for the duration of your editing session.  The new values are not
saved between sessions.  Each time Emacs starts, it reads the original
value, unless you change the value within your @file{.emacs} file,
either by setting it manually or by using @code{customize}.
@xref{Emacs Initialization, , Your @file{.emacs} File}.

For me, the major use of the @code{set-variable} command is to suggest
variables that I might want to set in my @file{.emacs} file.  There
are now more than 700 such variables --- far too many to remember
readily.  Fortunately, you can press @key{TAB} after calling the
@code{M-x set-variable} command to see the list of variables.
(@xref{Examining, , Examining and Setting Variables, emacs,
The GNU Emacs Manual}.)

@node copy-region-as-kill, cons & search-fwd Review, defvar, Cutting & Storing Text
@comment  node-name,  next,  previous,  up
@section @code{copy-region-as-kill}
@findex copy-region-as-kill

to say, the symbol @code{flowers} holds the address of the pair of
address-boxes, the first of which holds the address of @code{violet},
and the second of which holds the address of @code{buttercup}.

A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted
pair}.  @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU Emacs Lisp
Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair
Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more
information about cons cells and dotted pairs.

@need 1200

@smallexample
(custom-set-variables '(eval-expression-print-length nil))
@end smallexample

@noindent
(@xref{defcustom, , Specifying Variables using @code{defcustom}}.)
Then evaluate the @code{lengths-list-file} expression.)

@need 1200
The lengths' list for @file{debug.el} takes less than a second to
produce and looks like this:

@noindent
The name of the variable is @code{text-mode-hook}; it has no default
value; and its documentation string tells you what it does.

The @code{:type} keyword tells Emacs the kind of data to which
@code{text-mode-hook} should be set and how to display the value in a
Customization buffer.

The @code{:options} keyword specifies a suggested list of values for
the variable.  Currently, you can use @code{:options} only for a hook.
The list is only a suggestion; it is not exclusive; a person who sets
the variable may set it to other values; the list shown following the

@evenheading @thispage @| @| @thistitle
@oddheading            @| @| @thispage
@end iftex

@bye

@ignore
   arch-tag: da1a2154-531f-43a8-8e33-fc7faad10acf
@end ignore