From 7f9588685a0e1fe2dd0fcc5c3204426ac81cc6ac Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 7 Jan 2023 10:47:44 +0200 Subject: [PATCH] ; Fix last change * doc/emacs/misc.texi (Saving Emacs Sessions): Minor rewording and rearrangements. (Bug#60600) --- doc/emacs/misc.texi | 125 ++++++++++++++++++++++++-------------------- 1 file changed, 69 insertions(+), 56 deletions(-) diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index b707a7faa7c..e2764c34482 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -2705,15 +2705,16 @@ when point is on the first byte of a multibyte sequence in the file. @cindex restore session @cindex remember editing session @cindex reload files -@cindex desktop - Use the desktop library to save the state of Emacs from one session -to another. The Emacs @dfn{desktop} consists of the buffers, their -file names, major modes, buffer positions, and so on. +@cindex desktop configuration + You can use the desktop library to save the state of Emacs from one +session to another. The saved Emacs @dfn{desktop configuration} +includes the buffers, their file names, major modes, buffer positions, +window and frame configuration, and some important global variables. @vindex desktop-save-mode @findex desktop-save-mode -To enable this feature, use the Customization buffer (@pxref{Easy + To enable this feature, 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 init file (@pxref{Init File}): @@ -2728,17 +2729,27 @@ Emacs starts, it looks for a saved desktop in @code{desktop-path} (which defaults to @code{user-emacs-directory} and then your home directory) and uses the first desktop it finds. While Emacs runs with @code{desktop-save-mode} turned on, it by default auto-saves the -desktop whenever any of it changes. The variable -@code{desktop-auto-save-timeout} determines how frequently Emacs -checks for modifications to your desktop. The desktop is also saved -when you exit Emacs. +desktop whenever any of the desktop configuration changes. The +variable @code{desktop-auto-save-timeout} determines how frequently +Emacs checks for modifications to your desktop. The desktop is also +saved when you exit Emacs. + +@cindex disable restoring of desktop configuration + Specify the option @samp{--no-desktop} on the Emacs command line +when you don't want it to reload any saved desktop configurations. +This turns off @code{desktop-save-mode} for the current session. +Starting Emacs with the @samp{--no-init-file} option also disables +desktop reloading, since it bypasses the init file, where +@code{desktop-save-mode} is usually turned on. @findex desktop-change-dir @findex desktop-revert - You can have separate saved desktops in different directories. 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. + You can have separate saved desktop configurations in different +directories; starting Emacs from a directory where you have a saved +desktop configuration will restore that configuration. You can save +the current desktop and reload the one saved in another directory by +typing @kbd{M-x desktop-change-dir}. Typing @kbd{M-x desktop-revert} +reverts to the previously reloaded desktop. @vindex desktop-load-locked-desktop The file in which Emacs saves the desktop is locked while the @@ -2749,33 +2760,46 @@ will by default ask you whether to use the locked desktop file. You can avoid the question by customizing the variable @code{desktop-load-locked-desktop} to either @code{nil}, which means never load the desktop in this case, or @code{t}, which means load the -desktop without asking. Finally, the @code{check-pid} value means to -load the file if the Emacs process that has locked the desktop is not -running on the local machine. This should not be used in -circumstances where the locking Emacs might still be running on -another machine. This could be the case in multi-user environments -where your home directory is mounted remotely using NFS or similar. +desktop without asking. You can also customize the variable to the +special value @code{check-pid}, which means to load the file if the +Emacs process that has locked the desktop is not running on the local +machine. This should not be used in circumstances where the locking +Emacs might still be running on another machine, which could be the +case in multi-user environments where your home directory is mounted +remotely using NFS or similar. + +@cindex desktop restore in daemon mode + When Emacs starts in daemon mode, it cannot ask you any questions, +so if it finds the desktop file locked, it will not load it, unless +@code{desktop-load-locked-desktop} is @code{t}. Note that restoring +the desktop in daemon mode is somewhat problematic for other reasons: +e.g., the daemon cannot use GUI features, so parameters such as frame +position, size, and decorations cannot be restored. For that reason, +you may wish to delay restoring the desktop in daemon mode until the +first client connects, by calling @code{desktop-read} (see below) in a +hook function that you add to @code{server-after-make-frame-hook} +(@pxref{Creating Frames,,, elisp, The Emacs Lisp Reference Manual}). @findex desktop-save @findex desktop-read Whenever you want, you can use the command @kbd{M-x desktop-save} to -force saving the current desktop. If you do not want to use the -automatic @code{desktop-save-mode}, you can use @kbd{M-x desktop-save} -and then @kbd{M-x desktop-read} to restore a previous desktop. +force immediate saving of the current desktop. This is useful either +if you do not want to use the automatic desktop restoration, and thus +don't turn on @code{desktop-save-mode}, or when you have made +significant changes to the desktop, and want to make sure the +configuration doesn't get lost if Emacs or your system crashes. You +can use @kbd{M-x desktop-read} to restore a previously-saved desktop +if the current Emacs session didn't load any desktop yet. @vindex desktop-restore-frames - By default, the desktop also tries to save the frame and window -configuration. To disable this, set @code{desktop-restore-frames} to -@code{nil}. (See that variable's documentation for some related -options that you can customize to fine-tune this behavior.) - -@vindex desktop-files-not-to-save - Information about buffers visiting remote files is not saved by -default. Customize the variable @code{desktop-files-not-to-save} to -change this. + By default, the desktop tries to save and restore the frame and +window configuration. To disable this, set +@code{desktop-restore-frames} to @code{nil}. (See that variable's +documentation for some related options that you can customize to +fine-tune this behavior.) @vindex frameset-filter-alist - When the desktop restores the frame and window configuration, it + When the desktop restores the frame and window configuration, it uses the recorded values of frame parameters, disregarding any settings for those parameters you have in your init file (@pxref{Init File}). This means that frame parameters such as fonts and faces for @@ -2783,7 +2807,13 @@ the restored frames will come from the desktop file, where they were saved when you exited your previous Emacs session; any settings for those parameters in your init file will be ignored. To disable this, customize the value of @code{frameset-filter-alist} to filter out the -frame parameters you don't want to be restored. +frame parameters you don't want to be restored; they will then be set +according to your customizations in the init file. + +@vindex desktop-files-not-to-save + Information about buffers visiting remote files is not saved by +default. Customize the variable @code{desktop-files-not-to-save} to +change this. @vindex desktop-restore-eager By default, all the buffers in the desktop are restored in one go. @@ -2795,32 +2825,15 @@ remaining buffers are restored lazily, when Emacs is idle. @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 + Type @kbd{M-x desktop-clear} to empty the Emacs desktop; this can be +useful, for example, if you want to switch to another desktop by +invoking @kbd{M-x desktop-read} next. The @code{desktop-clear} +command kills all buffers except for internal ones, and clears the +global variables listed in @code{desktop-globals-to-clear}. If you +want it 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. - Specify the option @samp{--no-desktop} on the command line when you -don't want it to reload any saved desktop. This turns off -@code{desktop-save-mode} for the current session. Starting Emacs with -the @samp{--no-init-file} option also disables desktop reloading, -since it bypasses the init file, where @code{desktop-save-mode} is -usually turned on. - -@cindex desktop restore in daemon mode - When Emacs starts in daemon mode, it cannot ask you any questions, -so if it finds the desktop file locked, it will not load it, unless -@code{desktop-load-locked-desktop} is @code{t}. Note that restoring -the desktop in daemon mode is somewhat problematic for other reasons: -e.g., the daemon cannot use GUI features, so parameters such as frame -position, size, and decorations cannot be restored. For that reason, -you may wish to delay restoring the desktop in daemon mode until the -first client connects, by calling @code{desktop-read} in a hook -function that you add to @code{server-after-make-frame-hook} -(@pxref{Creating Frames,,, elisp, The Emacs Lisp Reference Manual}). - If you want to save minibuffer history from one session to another, use the @code{savehist} library. -- 2.39.2