[Emacs-diffs] Changes to emacs/lispref/modes.texi [emacs-unicode-2]

[Miles Bader]

Index: emacs/lispref/modes.texi
diff -c emacs/lispref/modes.texi:1.58.2.1 emacs/lispref/modes.texi:1.58.2.2
*** emacs/lispref/modes.texi:1.58.2.1   Mon Apr 19 07:01:42 2004
--- emacs/lispref/modes.texi    Mon Jun 28 07:28:50 2004
***************
*** 26,31 ****
--- 26,33 ----
  * Imenu::              How a mode can provide a menu
                           of definitions in the buffer.
  * Font Lock Mode::     How modes can highlight text according to syntax.
+ * Desktop Save Mode::  How modes can have buffer state saved between
+                          Emacs sessions.
  * Hooks::              How to use hooks; how to write code that provides 
hooks.
  @end menu
  
***************
*** 877,884 ****
  off if it is on).  It should turn the mode on if the argument is a
  positive integer, the symbol @code{t}, or a list whose @sc{car} is one
  of those.  It should turn the mode off if the argument is a negative
! integer or zero, the symbol @code{-}, or a list whose @sc{car} is one
! of those.  The meaning of other arguments is not specified.
  
  Here is an example taken from the definition of @code{transient-mark-mode}.
  It shows the use of @code{transient-mark-mode} as a variable that enables or
--- 879,887 ----
  off if it is on).  It should turn the mode on if the argument is a
  positive integer, the symbol @code{t}, or a list whose @sc{car} is one
  of those.  It should turn the mode off if the argument is a negative
! integer or zero, the symbol @code{-}, or a list whose @sc{car} is a
! negative integer or zero.  The meaning of other arguments is not
! specified.
  
  Here is an example taken from the definition of @code{transient-mark-mode}.
  It shows the use of @code{transient-mark-mode} as a variable that enables or
***************
*** 1452,1462 ****
  @end defvar
  
  @defvar global-mode-string
! This variable holds a mode-line spec that appears in the mode line by
! default, just after the buffer name.  The command @code{display-time}
  sets @code{global-mode-string} to refer to the variable
! @code{display-time-string}, which holds a string containing the time and
! load information.
  
  The @samp{%M} construct substitutes the value of
  @code{global-mode-string}, but that is obsolete, since the variable is
--- 1455,1466 ----
  @end defvar
  
  @defvar global-mode-string
! This variable holds a mode-line spec that, by default, appears in the
! mode line just after the @code{which-func-mode} minor mode if set,
! else after @code{mode-line-modes}.  The command @code{display-time}
  sets @code{global-mode-string} to refer to the variable
! @code{display-time-string}, which holds a string containing the time
! and load information.
  
  The @samp{%M} construct substitutes the value of
  @code{global-mode-string}, but that is obsolete, since the variable is
***************
*** 1998,2004 ****
  it finds using @code{font-lock-keyword-face}.
  
  When @var{function} is called, it receives one argument, the limit of
! the search; it should searching at point, and not search beyond the
  limit.  It should return address@hidden if it succeeds, and set the
  match data to describe the match that was found.  Returning @code{nil}
  indicates failure of the search.
--- 2002,2008 ----
  it finds using @code{font-lock-keyword-face}.
  
  When @var{function} is called, it receives one argument, the limit of
! the search; it should begin searching at point, and not search beyond the
  limit.  It should return address@hidden if it succeeds, and set the
  match data to describe the match that was found.  Returning @code{nil}
  indicates failure of the search.
***************
*** 2426,2431 ****
--- 2430,2488 ----
  
  @end defvar
  
+ @node Desktop Save Mode
+ @section Desktop Save Mode
+ @cindex desktop save mode
+ 
+ @dfn{Desktop Save Mode} is a feature to save the state of Emacs from
+ one session to another.  The user-level commands for using Desktop
+ Save Mode are described in the GNU Emacs Manual (@pxref{Saving Emacs
+ Sessions,,, emacs, the GNU Emacs Manual}).  Modes whose buffers visit
+ a file, don't have to do anything to use this feature.
+ 
+ For buffers not visiting a file to have their state saved, the major
+ mode must bind the buffer local variable @code{desktop-save-buffer} to
+ a non-nil value.
+ 
+ @defvar desktop-save-buffer
+ If this buffer-local variable is address@hidden, the buffer will have
+ its state saved in the desktop file at desktop save.  If the value is
+ a function, it is called at desktop save with argument
+ @var{desktop-dirname}, and its value is saved in the desktop file along
+ with the state of the buffer for which it was called.  When file names
+ are returned as part of the auxiliary information, they should be
+ formatted using the call
+ 
+ @example
+ (desktop-file-name @var{file-name} @var{desktop-dirname})
+ @end example
+ 
+ @end defvar
+ 
+ For buffers not visiting a file to be restored, the major mode must
+ define a function to do the job, and that function must be listed in
+ the alist @code{desktop-buffer-mode-handlers}.
+ 
+ @defvar desktop-buffer-mode-handlers
+ Alist with elements
+ 
+ @example
+ (@var{major-mode} . @var{restore-buffer-function})
+ @end example
+ 
+ The function @var{restore-buffer-function} will be called with
+ argument list
+ 
+ @example
+ (@var{buffer-file-name} @var{buffer-name} @var{desktop-buffer-misc})
+ @end example
+ 
+ and it should return the restored buffer.
+ Here @var{desktop-buffer-misc} is the value returned by the function
+ optionally bound to @code{desktop-save-buffer}.
+ 
+ @end defvar
+ 
  @node Hooks
  @section Hooks
  @cindex hooks