[Emacs-diffs] Changes to emacs/lispref/variables.texi

[Luc Teirlinck]

Index: emacs/lispref/variables.texi
diff -c emacs/lispref/variables.texi:1.46 emacs/lispref/variables.texi:1.47
*** emacs/lispref/variables.texi:1.46   Mon Oct  6 12:44:15 2003
--- emacs/lispref/variables.texi        Tue Nov  4 23:31:43 2003
***************
*** 518,524 ****
  at top level in a file where its value does not matter.
  @end defspec
  
! @defspec defconst symbol [value [doc-string]]
  This special form defines @var{symbol} as a value and initializes it.
  It informs a person reading your code that @var{symbol} has a standard
  global value, established here, that should not be changed by the user
--- 518,524 ----
  at top level in a file where its value does not matter.
  @end defspec
  
! @defspec defconst symbol value [doc-string]
  This special form defines @var{symbol} as a value and initializes it.
  It informs a person reading your code that @var{symbol} has a standard
  global value, established here, that should not be changed by the user
***************
*** 526,535 ****
  symbol to be defined must appear explicitly in the @code{defconst}.
  
  @code{defconst} always evaluates @var{value}, and sets the value of
! @var{symbol} to the result if @var{value} is given.  If @var{symbol}
! does have a buffer-local binding in the current buffer, @code{defconst}
! sets the default value, not the buffer-local value.  (But you should not
! be making buffer-local bindings for a symbol that is defined with
  @code{defconst}.)
  
  Here, @code{pi} is a constant that presumably ought not to be changed
--- 526,535 ----
  symbol to be defined must appear explicitly in the @code{defconst}.
  
  @code{defconst} always evaluates @var{value}, and sets the value of
! @var{symbol} to the result.  If @var{symbol} does have a buffer-local
! binding in the current buffer, @code{defconst} sets the default value,
! not the buffer-local value.  (But you should not be making
! buffer-local bindings for a symbol that is defined with
  @code{defconst}.)
  
  Here, @code{pi} is a constant that presumably ought not to be changed
***************
*** 858,868 ****
    One other function for setting a variable is designed to add
  an element to a list if it is not already present in the list.
  
! @defun add-to-list symbol element
  This function sets the variable @var{symbol} by consing @var{element}
  onto the old value, if @var{element} is not already a member of that
  value.  It returns the resulting list, whether updated or not.  The
  value of @var{symbol} had better be a list already before the call.
  
  The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
  is an ordinary function, like @code{set} and unlike @code{setq}.  Quote
--- 858,873 ----
    One other function for setting a variable is designed to add
  an element to a list if it is not already present in the list.
  
! @defun add-to-list symbol element &optional append
  This function sets the variable @var{symbol} by consing @var{element}
  onto the old value, if @var{element} is not already a member of that
  value.  It returns the resulting list, whether updated or not.  The
  value of @var{symbol} had better be a list already before the call.
+ Membership is tested using @code{equal}.
+ 
+ Normally, if @var{element} is added, it is added to the front of
+ @var{symbol}, but if the optional argument @var{append} is
+ address@hidden, it is added at the end.
  
  The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
  is an ordinary function, like @code{set} and unlike @code{setq}.  Quote
***************
*** 1296,1302 ****
  A peculiar wrinkle of this feature is that binding the variable (with
  @code{let} or other binding constructs) does not create a buffer-local
  binding for it.  Only setting the variable (with @code{set} or
! @code{setq}) does so.
  
  The value returned is @var{variable}.
  
--- 1301,1314 ----
  A peculiar wrinkle of this feature is that binding the variable (with
  @code{let} or other binding constructs) does not create a buffer-local
  binding for it.  Only setting the variable (with @code{set} or
! @code{setq}), while the variable does not have a @code{let}-style
! binding that was made in the current buffer, does so.
! 
! If @var{variable} does not have a default value, then calling this
! command will give it a default value of @code{nil}.  If @var{variable}
! already has a default value, that value remains unchanged.
! Subsequently calling @code{makunbound} on @var{variable} will result
! in a void buffer-local value and leave the default value unaffected.
  
  The value returned is @var{variable}.
  
***************
*** 1556,1566 ****
--- 1568,1584 ----
  if some frame already has a value for @var{variable} as a frame
  parameter, that value automatically becomes a frame-local binding.
  
+ If @var{variable} does not have a default value, then calling this
+ command will give it a default value of @code{nil}.  If @var{variable}
+ already has a default value, that value remains unchanged.
+ 
  If the variable is terminal-local, this function signals an error,
  because such variables cannot have frame-local bindings as well.
  @xref{Multiple Displays}.  A few variables that are implemented
  specially in Emacs can be (and usually are) buffer-local, but can never
  be frame-local.
+ 
+ This command returns @var{variable}.
  @end deffn
  
    Buffer-local bindings take precedence over frame-local bindings.  Thus,
***************
*** 1675,1681 ****
  
  If the @var{docstring} argument is address@hidden, it specifies the
  documentation for @var{alias-var}; otherwise, the alias gets the same
! documentation as @var{base-var} has, if any.
  @end defun
  
  @defun indirect-variable variable
--- 1693,1703 ----
  
  If the @var{docstring} argument is address@hidden, it specifies the
  documentation for @var{alias-var}; otherwise, the alias gets the same
! documentation as @var{base-var} has, if any, unless @var{base-var} is
! itself an alias, in which case @var{alias-var} gets the documentation
! of the variable at the end of the chain of aliases.
! 
! This function returns @var{base-var}.
  @end defun
  
  @defun indirect-variable variable
***************
*** 1693,1700 ****
--- 1715,1724 ----
  (setq bar 2)
  bar
       @result{} 2
+ @group
  foo
       @result{} 2
+ @end group
  (setq foo 0)
  bar
       @result{} 0
***************
*** 1706,1712 ****
  @section File Local Variables
  
    This section describes the functions and variables that affect
! processing of local variables lists in files.
  
  @defopt enable-local-variables
  This variable controls whether to process file local variables lists.  A
--- 1730,1738 ----
  @section File Local Variables
  
    This section describes the functions and variables that affect
! processing of local variables lists in files. @xref{File variables, ,
! Local Variables in Files, emacs, The GNU Emacs Manual}, for basic
! information about file local variables.
  
  @defopt enable-local-variables
  This variable controls whether to process file local variables lists.  A
***************
*** 1715,1727 ****
  the user what to do for each file.  The default value is @code{t}.
  @end defopt
  
! @defun hack-local-variables &optional force
  This function parses, and binds or evaluates as appropriate, any local
  variables specified by the contents of the current buffer.  The variable
! @code{enable-local-variables} has its effect here.
! 
! The argument @var{force} usually comes from the argument @var{find-file}
! given to @code{normal-mode}.
  @end defun
  
    If a file local variable list could specify a function that will
--- 1741,1759 ----
  the user what to do for each file.  The default value is @code{t}.
  @end defopt
  
! @defun hack-local-variables &optional mode-only
  This function parses, and binds or evaluates as appropriate, any local
  variables specified by the contents of the current buffer.  The variable
! @code{enable-local-variables} has its effect here.  However, this
! function does not look for the @samp{mode:} local variable in the
! @address@hidden line.  @code{set-auto-mode} does that, also taking
! @code{enable-local-variables} into account.
! 
! If the optional argument @var{mode-only} is address@hidden, then all
! this function does is return @code{t} if the @address@hidden line
! specifies a mode and @code{nil} otherwise.  It does not set the mode
! nor any other file local variable.  It does not check whether a mode
! is specified in the local variables list at the end of the file.
  @end defun
  
    If a file local variable list could specify a function that will
***************
*** 1738,1744 ****
  variable's meaning.  The variables @samp{font-lock-keywords},
  @samp{font-lock-keywords-[0-9]}, and
  @samp{font-lock-syntactic-keywords} cannot be set in a local variable
! list, either.
  
    In addition, any variable whose name has a address@hidden
  @code{risky-local-variable} property is also ignored.  So are all
--- 1770,1784 ----
  variable's meaning.  The variables @samp{font-lock-keywords},
  @samp{font-lock-keywords-[0-9]}, and
  @samp{font-lock-syntactic-keywords} cannot be set in a local variable
! list, either.  These rules can be overridden by giving the variable's
! name a address@hidden @code{safe-local-variable} property.  If one
! gives it a @code{safe-local-variable} property of @code{t}, then one
! can give the variable any file local value.  One can also give any
! symbol, including the above, a @code{safe-local-variable} property
! that is a function taking exactly one argument.  In that case, giving
! a variable with that name a file local value is only allowed if the
! function returns address@hidden when called with that value as
! argument.
  
    In addition, any variable whose name has a address@hidden
  @code{risky-local-variable} property is also ignored.  So are all
***************
*** 1750,1758 ****
  for one of these variables is ignored.
  @end defvar
  
! @defun risky-local-variable-p sym
! Returns address@hidden if @var{sym} is risky for any of the reasons
! stated above.
  @end defun
  
    The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs
--- 1790,1801 ----
  for one of these variables is ignored.
  @end defvar
  
! @defun risky-local-variable-p sym &optional val
! If @var{val} is address@hidden, returns address@hidden if giving
! @var{sym} a file local value of @var{val} would be risky, for any of
! the reasons stated above.  If @var{val} is @code{nil} or omitted, only
! returns @code{nil} if @var{sym} can be safely assigned any file local
! value whatsoever.
  @end defun
  
    The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs