[Emacs-diffs] Changes to emacs/man/misc.texi

[Richard M. Stallman]

Index: emacs/man/misc.texi
diff -c emacs/man/misc.texi:1.47 emacs/man/misc.texi:1.48
*** emacs/man/misc.texi:1.47    Tue Sep 30 03:24:14 2003
--- emacs/man/misc.texi Tue Sep 30 16:38:51 2003
***************
*** 1875,1912 ****
  @cindex reload files
  @cindex desktop
  
!   You can use the desktop library to save the state of Emacs from one
! session to another.  Saving the state means that Emacs starts up with
! the same set of buffers, major modes, buffer positions, and so on that
! the previous Emacs session had. Such a state is referred to as a ``desktop''.
  
!   The saveplace library provides a simpler feature that records your
! position in each file when you kill its buffer (or kill Emacs), and
! jumps to the same position when you visit the file again (even in
! another Emacs session).
! 
! @menu
! The desktop library
! * Desktop Save Mode::          How to enable desktop saving.
! * Desktop file and directory:: About desktop files and desktop directory.
! * Saving manually::            How to saving the desktop manually and why.
! * Information saved::          Controlling which information to save.
! * Desktop clear::              Clearing the desktop.
! * File name format::           Different formats to save file names in.
! 
! The saveplace library
! * Saveplace::                  Recording the position in each file.
! @end menu
! 
! @node Desktop Save Mode
! @subsection Desktop Save Mode
! @findex desktop-save-mode
  @vindex desktop-save-mode
!   Desktop Save Mode is a global minor mode. @pxref{Minor Modes}.
! To enable desktop saving, you should use the Customization buffer
! (@pxref{Easy Customization}) to set @code{desktop-save-mode} to a
! address@hidden value for future sessions, or add this line somewhere
! in your @file{.emacs} file:
  
  @example
  (desktop-save-mode 1)
--- 1875,1892 ----
  @cindex reload files
  @cindex desktop
  
!    Use the desktop library to save the state of Emacs from one session
! to another.  Once you save the Emacs @dfn{desktop}---the buffers,
! their file names, major modes, buffer positions, and so on---then
! subsequent Emacs sessions reload the saved desktop.
  
! @findex desktop-save
  @vindex desktop-save-mode
!   You can save the desktop manually with the command @kbd{M-x
! desktop-save}.  You can also enable automatical desktop saving when
! you exit Emacs: use the Customization buffer (@pxref{Easy
! Customization}) to set @code{desktop-save-mode} to @code{t} for future
! sessions, or add this line in your @file{~/.emacs} file:
  
  @example
  (desktop-save-mode 1)
***************
*** 1914,2062 ****
  
  @findex desktop-change-dir
  @findex desktop-revert
! @findex desktop-read
! @vindex desktop-after-read-hook
!   In order for Emacs to recover the desktop from a previous session, you
! must start it with the same current directory as you used when you
! started the previous session.  This is because @code{desktop-read} looks
! in the current directory for the desktop file to read.  This means that you 
can
! have separate saved desktops in different directories; the directory in
! which you start Emacs will control which saved desktop to use.
! You can also save the current desktop and recover one saved in another 
directory
! by typing @kbd{M-x desktop-change-dir}.
! Typing @kbd{M-x desktop-revert} reverts to the last recovered desktop.
! 
! You may want Emacs to display a buffer list when a desktop is
! loaded.  This is possible by adding e.g.@: the function @code{buffer-menu} to
! @code{desktop-after-read-hook}. @pxref{Buffers}.
! 
! Specify the option @samp{--no-desktop} on the command line when you don't want
! any desktop to be loaded (even when desktop saving is enabled).
! 
! @node Desktop file and directory
! @subsection Desktop file and desktop directory
! @cindex desktop file
! @cindex desktop directory
! @vindex desktop-dirname
! @vindex desktop-base-file-name
! @vindex desktop-path
!   Emacs sessions are stored in desktop files.  When Emacs starts, it
! looks for a desktop file in the current directory and in your home
! directory, in that order.  Thus, if you save a desktop file in your
! home directory, it will act as a default desktop when you start Emacs
! from a directory that doesn't have its own.  Once a desktop file is
! found, the session described in it will be restored, and the directory
! where the desktop file was found will become the desktop directory.
! The desktop directory is the directory in which the desktop file is
! saved when Emacs is exited; it is saved in the variable
! @code{desktop-dirname}.
! 
!   You can change the base name of the desktop file and the list of
! directories where Emacs should look for a desktop file at startup by
! customizing the variables @code{desktop-base-file-name} and
! @code{desktop-path}.
! 
! @node Saving manually
! @subsection Saving the desktop manually
! @vindex desktop-save
! @findex desktop-save
! @findex desktop-save-in-desktop-dir
!   If you prefer to save desktops manually rather than having Emacs
! save them automatically at exit, set the customizable variable
! @code{desktop-save} to the value @code{nil}.  Then desktops are never
! saved automatically, instead you can save then by typing @kbd{M-x
! desktop-save} or @kbd{M-x desktop-save-in-desktop-dir}.  The first of
! these commands prompts for a directory to save the desktop in, the
! second saves it in the desktop directory.  Customization of the
! variable @code{desktop-save} also lets you control when the desktop
! should be saved, based upon whether a desktop file already exists in
! the desktop directory -- see the documentation of the variable.
  
! @node Information saved
! @subsection Controlling which information to save
! @vindex desktop-files-not-to-save
! @vindex desktop-modes-not-to-save
! @vindex desktop-buffer-modes-to-save
! @vindex desktop-globals-to-save
! @vindex desktop-locals-to-save
!   The customizable variable @code{desktop-files-not-to-save} controls
! which files are excluded from state saving.  Its value is a regular
! expression that matches the files to exclude.  By default, remote
! (ssh- or ftp-accessed) files are excluded; this is because visiting
! them again in a subsequent session would be slow.  If you want to
! include these files in state saving, set
! @code{desktop-files-not-to-save} to @code{"^$"}.  @xref{Remote Files}.
! You can also exclude buffers from state saving based on their mode by
! customizing @code{desktop-modes-not-to-save}.
  
-   It is possible to save the state of buffers not visiting files,
- based on their mode.  To do that, mention their mode it the
- customizable variable @code{desktop-buffer-modes-to-save}.  However,
- only certain non-visiting modes will have their buffers recreated when
- the desktop is loaded.  These are @code{dired-mode}, @code{Info-mode},
- @code{rmail-mode} and @code{mh-folder-mode}.
- 
- @vindex desktop-save-hook
- @findex desktop-truncate
-   To control which variables will be saved in the desktop file,
- customize the variables @code{desktop-globals-to-save} and
- @code{desktop-locals-to-save}.  List variables, such as
- @code{search-ring} and @code{regexp-search-ring}, may contain
- excessive amounts of data.  If you want to save only the first
- e.g.@: three elements, add to @code{desktop-save-hook} the function
- 
- @example
- '(lambda ()
-   (desktop-truncate search-ring 3)
-   (desktop-truncate regexp-search-ring 3))
- @end example
- 
- @node Desktop clear
- @subsection Clearing the desktop
  @findex desktop-clear
- @findex desktop-change-dir
- @findex desktop-revert
- @findex desktop-read
  @vindex desktop-globals-to-clear
  @vindex desktop-clear-preserve-buffers-regexp
! @vindex desktop-no-desktop-file-hook
!   Type @kbd{M-x desktop-clear} to empty the desktop.  This will kill
! all buffers except for internal ones and it will clear the global
! variables listed in @code{desktop-globals-to-clear}.  If you want to
  preserve certain buffers, customize the variable
! @code{desktop-clear-preserve-buffers-regexp}.  Its value is a regular
! expression matching the names of buffers not to kill.  The commands
! @code{desktop-change-dir} and @code{desktop-revert} both calls
! @code{desktop-clear} before loading the desktop.  Furthermore,
! @code{desktop-read} calls @code{desktop-clear} if no desktop file is
! found to load.  If you want a dired buffer showing the desktop
! directory in when no desktop file is found, customize
! @code{desktop-no-desktop-file-hook} to have the value
! @code{((lambda () (dired desktop-dirname)))}. @pxref{Dired}.
! 
! @node File name format
! @subsection File name format
! @vindex desktop-file-name-format
!   The customizable variable @code{desktop-file-name-format} controls
! the format in which file names are saved in the desktop buffer.  The
! default value is @code{absolute}, which means that file names are
! absolute.  If you change this to @code{tilde}, file names are relative
! to your home directory.  This means that desktop files might be copied
! from one machine to another, altough the absolute name of the home
! directories differ.  If you change @code{desktop-file-name-format} to
! @code{local}, file names are relative to the desktop directory.
! 
! @node Saveplace
! @subsection Saveplace 
! @vindex save-place
! @cindex Saveplace
! @findex toggle-save-place
!   The Saveplace library provides a simpler feature that records your
! position in each file when you kill its buffer (or kill Emacs), and
! jumps to the same position when you visit the file again (even in
! another Emacs session).  Use @kbd{M-x toggle-save-place} to turn on
! place-saving in a given file.  Customize the option @code{save-place}
! to turn it on for all files in each session.
  
  @node Recursive Edit, Emulation, Saving Emacs Sessions, Top
  @section Recursive Editing Levels
--- 1894,1918 ----
  
  @findex desktop-change-dir
  @findex desktop-revert
!   When Emacs starts, it looks for a saved desktop in the current
! directory.  Thus, you can have separate saved desktops in different
! directories, and the starting directory determines which one Emacs
! reloads.  You can save the current desktop and reload one saved in
! another directory by typing @kbd{M-x desktop-change-dir}.  Typing
! @kbd{M-x desktop-revert} reverts to the desktop previously reloaded.
  
!   Specify the option @samp{--no-desktop} on the command line when you
! don't want it to reload any saved desktop.
  
  @findex desktop-clear
  @vindex desktop-globals-to-clear
  @vindex desktop-clear-preserve-buffers-regexp
!   Type @kbd{M-x desktop-clear} to empty the Emacs desktop.  This kills
! all buffers except for internal ones, and clears the global variables
! listed in @code{desktop-globals-to-clear}.  If you want this to
  preserve certain buffers, customize the variable
! @code{desktop-clear-preserve-buffers-regexp}, whose value is a regular
! expression matching the names of buffers not to kill.
  
  @node Recursive Edit, Emulation, Saving Emacs Sessions, Top
  @section Recursive Editing Levels