bug#60600: 30.0.50; [PATCH] Document manual desktop restore

bug#60600: 30.0.50; [PATCH] Document manual desktop restore

[Manuel Giraud]

[-- Attachment #1: Type: text/plain, Size: 63 bytes --]


Hi,

This patch document how to do a manual desktop restore.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Document-manual-desktop-restore.patch --]
[-- Type: text/x-patch, Size: 1523 bytes --]

From b7950b2c05bf22fb69d6554383bf09fc4eb8036a Mon Sep 17 00:00:00 2001
From: Manuel Giraud <manuel@ledu-giraud.fr>
Date: Fri, 6 Jan 2023 11:29:20 +0100
Subject: [PATCH] Document manual desktop restore

* doc/emacs/misc.texi (Saving Emacs Sessions): Precises how to do a
manual restore after a manual save.
---
 doc/emacs/misc.texi | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index c706b727e6f..ec24d43c46a 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -2733,11 +2733,13 @@ Saving Emacs Sessions
 @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 automatic saving of the desktop
-when you exit Emacs, and automatic restoration of the last saved
-desktop when Emacs starts: 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}):
+desktop-save}.  You can then restore the desktop manually with the
+command @kbd{M-x desktop-read}.  You can also enable automatic saving
+of the desktop when you exit Emacs, and automatic restoration of the
+last saved desktop when Emacs starts: 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}):
 
 @example
 (desktop-save-mode 1)
-- 
2.39.0


[-- Attachment #3: Type: text/plain, Size: 7865 bytes --]



In GNU Emacs 30.0.50 (build 1, x86_64-unknown-openbsd7.2, cairo version
 1.17.6) of 2023-01-06 built on computer
Repository revision: 3fcbb865853d7c364cf7c2986ead9e258f449f97
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12101004
System Description: OpenBSD computer 7.2 GENERIC.MP#903 amd64

Configured using:
 'configure --prefix=/home/manuel/emacs --bindir=/home/manuel/bin
 --with-x-toolkit=no --without-sound --without-compress-install
 CPPFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/lib'

Configured features:
CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GSETTINGS HARFBUZZ JPEG JSON
LCMS2 LIBOTF LIBXML2 MODULES NOTIFY KQUEUE OLDXMENU PDUMPER PNG RSVG
SQLITE3 THREADS TIFF TREE_SITTER WEBP X11 XDBE XIM XINPUT2 XPM ZLIB

Important settings:
  value of $LC_ALL: en_US.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Texinfo

Minor modes in effect:
  global-git-commit-mode: t
  magit-auto-revert-mode: t
  bug-reference-prog-mode: t
  auto-revert-mode: t
  display-time-mode: t
  display-battery-mode: t
  server-mode: t
  shell-dirtrack-mode: t
  repeat-mode: t
  global-eldoc-mode: t
  show-paren-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  line-number-mode: t
  auto-fill-function: do-auto-fill
  transient-mark-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t

Load-path shadows:
/home/manuel/.emacs.d/elpa/ef-themes-0.10.0/theme-loaddefs hides /home/manuel/emacs/share/emacs/30.0.50/lisp/theme-loaddefs
/home/manuel/.emacs.d/elpa/transient-0.3.7/transient hides /home/manuel/emacs/share/emacs/30.0.50/lisp/transient

Features:
(shadow sort mail-extr emacsbug whitespace magit-patch misearch
multi-isearch shortdoc help-fns radix-tree executable texinfo
texinfo-loaddefs magit-extras face-remap magit-bookmark magit-submodule
magit-obsolete magit-blame magit-stash magit-reflog magit-bisect
magit-push magit-pull magit-fetch magit-clone magit-remote magit-commit
magit-sequence magit-notes magit-worktree magit-tag magit-merge
magit-branch magit-reset magit-files magit-refs magit-status magit
magit-repos magit-apply magit-wip magit-log which-func magit-diff
smerge-mode diff git-commit log-edit pcvs-util add-log magit-core
magit-autorevert magit-margin magit-transient magit-process with-editor
magit-mode transient magit-git magit-section magit-utils dash pulse
ibuf-ext ibuffer ibuffer-loaddefs css-mode treesit smie imenu org-indent
rng-xsd xsd-regexp rng-cmpct rng-nxml rng-valid rng-loc rng-uri
rng-parse nxml-parse rng-match rng-dt rng-util rng-pttrn nxml-ns
nxml-mode nxml-outln nxml-rap sgml-mode facemenu nxml-util nxml-enc
xmltok view oc-basic org-element org-persist org-id org-refile avl-tree
ol-eww eww xdg url-queue mm-url ol-rmail ol-mhe ol-irc ol-info ol-gnus
nnselect ol-docview doc-view jka-compr image-mode exif ol-bibtex bibtex
ol-bbdb ol-w3m ol-doi org-link-doi epa-file bug-reference gnus-dired
autorevert filenotify vc-git diff-mode vc-dispatcher vc-svn desktop
frameset paredit edmacro time battery exwm-randr xcb-randr exwm-config
exwm exwm-input xcb-keysyms xcb-xkb exwm-manage exwm-floating xcb-cursor
xcb-render exwm-layout exwm-workspace exwm-core xcb-ewmh xcb-icccm xcb
xcb-xproto xcb-types xcb-debug kmacro server stimmung-themes
modus-operandi-theme modus-themes ytdious osm mingus libmpdee reporter
edebug debug backtrace transmission diary-lib diary-loaddefs color
calc-bin calc-ext calc calc-loaddefs rect calc-macs w3m-load mu4e
mu4e-org mu4e-main mu4e-view mu4e-headers mu4e-compose mu4e-draft
mu4e-actions smtpmail mu4e-search mu4e-lists mu4e-bookmarks mu4e-mark
mu4e-message flow-fill mule-util hl-line mu4e-contacts mu4e-update
mu4e-folders mu4e-server mu4e-context mu4e-vars mu4e-helpers mu4e-config
bookmark ido supercite regi ebdb-message ebdb-gnus gnus-msg gnus-art
mm-uu mml2015 mm-view mml-smime smime gnutls dig gnus-sum shr pixel-fill
kinsoku url-file svg dom gnus-group gnus-undo gnus-start gnus-dbus
gnus-cloud nnimap nnmail mail-source utf7 nnoo gnus-spec gnus-int
gnus-range message sendmail yank-media puny rfc822 mml mml-sec epa epg
rfc6068 epg-config mm-decode mm-bodies mm-encode mail-parse rfc2231
rfc2047 rfc2045 ietf-drums gmm-utils mailheader gnus-win gnus nnheader
gnus-util mail-utils range mm-util mail-prsvr ebdb-mua ebdb-com crm
ebdb-format ebdb mailabbrev eieio-opt cl-extra help-mode speedbar
ezimage dframe eieio-base pcase timezone org ob ob-tangle ob-ref ob-lob
ob-table ob-exp org-macro org-src ob-comint org-pcomplete org-list
org-footnote org-faces org-entities ob-emacs-lisp ob-core ob-eval
org-cycle org-table ol org-fold org-fold-core org-keys oc org-loaddefs
find-func cal-menu calendar cal-loaddefs org-version org-compat org-macs
visual-basic-mode cl web-mode derived disp-table erlang-start
smart-tabs-mode skeleton cc-mode cc-fonts cc-guess cc-menus cc-cmds
cc-styles cc-align cc-engine cc-vars cc-defs slime-asdf grep slime-tramp
tramp tramp-loaddefs trampver tramp-integration cus-edit cus-load
wid-edit files-x tramp-compat rx shell pcomplete parse-time iso8601
time-date ls-lisp format-spec slime-fancy slime-indentation
slime-cl-indent cl-indent slime-trace-dialog slime-fontifying-fu
slime-package-fu slime-references slime-compiler-notes-tree advice
slime-scratch slime-presentations bridge slime-macrostep macrostep
slime-mdot-fu slime-enclosing-context slime-fuzzy slime-fancy-trace
slime-fancy-inspector slime-c-p-c slime-editing-commands slime-autodoc
slime-repl slime-parse slime compile text-property-search etags fileloop
generator xref project arc-mode archive-mode noutline outline icons pp
comint ansi-osc ansi-color ring hyperspec thingatpt slime-autoloads
dired-aux dired-x dired dired-loaddefs notifications dbus xml repeat
easy-mmode stimmung-themes-autoloads rust-mode-autoloads ebdb-autoloads
magit-autoloads debbugs-autoloads git-commit-autoloads
magit-section-autoloads ef-themes-autoloads with-editor-autoloads
paredit-autoloads dash-autoloads ytdious-autoloads
transmission-autoloads transient-autoloads exwm-autoloads
hyperbole-autoloads detached-autoloads info package browse-url url
url-proxy url-privacy url-expand url-methods url-history url-cookie
generate-lisp-file url-domsuf url-util mailcap url-handlers url-parse
auth-source cl-seq eieio eieio-core cl-macs password-cache json subr-x
map byte-opt gv bytecomp byte-compile url-vars cl-loaddefs cl-lib rmc
iso-transl tooltip cconv eldoc paren electric uniquify ediff-hook
vc-hooks lisp-float-type elisp-mode mwheel term/x-win x-win
term/common-win x-dnd tool-bar dnd fontset image regexp-opt fringe
tabulated-list replace newcomment text-mode lisp-mode prog-mode register
page tab-bar menu-bar rfn-eshadow isearch easymenu timer select
scroll-bar mouse jit-lock font-lock syntax font-core term/tty-colors
frame minibuffer nadvice seq simple cl-generic indonesian philippine
cham georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao
korean japanese eucjp-ms cp51932 hebrew greek romanian slovak czech
european ethiopic indian cyrillic chinese composite emoji-zwj charscript
charprop case-table epa-hook jka-cmpr-hook help abbrev obarray oclosure
cl-preloaded button loaddefs theme-loaddefs faces cus-face macroexp
files window text-properties overlay sha1 md5 base64 format env
code-pages mule custom widget keymap hashtable-print-readable backquote
threads dbusbind kqueue lcms2 dynamic-setting system-font-setting
font-render-setting cairo xinput2 x multi-tty make-network-process
emacs)

Memory information:
((conses 16 755171 92149)
 (symbols 48 59596 3)
 (strings 32 194558 7376)
 (string-bytes 1 6141566)
 (vectors 16 113719)
 (vector-slots 8 2244387 111508)
 (floats 8 618 373)
 (intervals 56 24661 1377)
 (buffers 984 91))

-- 
Manuel Giraud

bug#60600: 30.0.50; [PATCH] Document manual desktop restore

[Eli Zaretskii]

> From: Manuel Giraud <manuel@ledu-giraud.fr>
> Date: Fri, 06 Jan 2023 11:33:20 +0100
> 
> diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
> index c706b727e6f..ec24d43c46a 100644
> --- a/doc/emacs/misc.texi
> +++ b/doc/emacs/misc.texi
> @@ -2733,11 +2733,13 @@ Saving Emacs Sessions
>  @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 automatic saving of the desktop
> -when you exit Emacs, and automatic restoration of the last saved
> -desktop when Emacs starts: 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}):
> +desktop-save}.  You can then restore the desktop manually with the
> +command @kbd{M-x desktop-read}.  You can also enable automatic saving
> +of the desktop when you exit Emacs, and automatic restoration of the
> +last saved desktop when Emacs starts: 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}):

Thanks.

The new text seems to imply that using "M-x desktop-save" necessarily
means restoring must also be manual.  But this is only true if
desktop-save-mode was not enabled.  I have the mode enabled, and I
still sometimes save the desktop manually, whenever I make some
significant change to the session, to make sure the new arrangement is
saved and not lost due to some catastrophe.

So the change needs to be reworded not to imply the mistaken
interpretation that saving manually requires restoring manually.

bug#60600: 30.0.50; [PATCH] Document manual desktop restore

[Manuel Giraud]

Eli Zaretskii <eliz@gnu.org> writes:

Hi Eli,

[...]

> The new text seems to imply that using "M-x desktop-save" necessarily
> means restoring must also be manual.  But this is only true if
> desktop-save-mode was not enabled.  I have the mode enabled, and I
> still sometimes save the desktop manually, whenever I make some
> significant change to the session, to make sure the new arrangement is
> saved and not lost due to some catastrophe.
>
> So the change needs to be reworded not to imply the mistaken
> interpretation that saving manually requires restoring manually.

Ok but OTOH, when you are not using desktop-save-mode (as I do) after
the manual save explanation you are left wondering « how could I restore
it when I need to? » and then the text goes on about setting up
desktop-save-mode.  That's why I placed this sentence here.  Maybe it
need some rewording but I don't know how I could do it.

And BTW, shouldn't desktop-revert be the user facing interface here?
-- 
Manuel Giraud

bug#60600: 30.0.50; [PATCH] Document manual desktop restore

[Eli Zaretskii]

> From: Manuel Giraud <manuel@ledu-giraud.fr>
> Cc: 60600@debbugs.gnu.org
> Date: Fri, 06 Jan 2023 13:26:27 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > The new text seems to imply that using "M-x desktop-save" necessarily
> > means restoring must also be manual.  But this is only true if
> > desktop-save-mode was not enabled.  I have the mode enabled, and I
> > still sometimes save the desktop manually, whenever I make some
> > significant change to the session, to make sure the new arrangement is
> > saved and not lost due to some catastrophe.
> >
> > So the change needs to be reworded not to imply the mistaken
> > interpretation that saving manually requires restoring manually.
> 
> Ok but OTOH, when you are not using desktop-save-mode (as I do) after
> the manual save explanation you are left wondering « how could I restore
> it when I need to? » and then the text goes on about setting up
> desktop-save-mode.  That's why I placed this sentence here.  Maybe it
> need some rewording but I don't know how I could do it.

I find the organization of the text in that section not very logical
in general.  It begins by describing not-very-important optional
features.  It should instead start by describing desktop-save-mode,
since this is the recommended use of this facility, and leave the
manual saving/restoring for later (explaining why one would want to do
it manually).  When it describes desktop-save-mode, it should mention
that saving happens also from time to time, not just upon exit,
something that for some reason is described much later in the section.
And the order of describing the various optional features seems to
lack any logic, which at least should be to describe the more
significant/important options (such as desktop-load-locked-desktop,
for example) first.

Feel free to rewrite the section along the above lines; if not, I will
do that soon, hopefully also taking care of the issue you raise.

> And BTW, shouldn't desktop-revert be the user facing interface here?

What do you mean?  desktop-revert is described in that section (again,
without any hint about when it could be useful).

bug#60600: 30.0.50; [PATCH] Document manual desktop restore

[Manuel Giraud]

Eli Zaretskii <eliz@gnu.org> writes:

[...]

> I find the organization of the text in that section not very logical
> in general.  It begins by describing not-very-important optional
> features.  It should instead start by describing desktop-save-mode,
> since this is the recommended use of this facility, and leave the
> manual saving/restoring for later (explaining why one would want to do
> it manually).  When it describes desktop-save-mode, it should mention
> that saving happens also from time to time, not just upon exit,
> something that for some reason is described much later in the section.
> And the order of describing the various optional features seems to
> lack any logic, which at least should be to describe the more
> significant/important options (such as desktop-load-locked-desktop,
> for example) first.

Yes.  I had the same feeling when reading this section.  It starts
talking about desktop-restore-frames before I had grasp what is the
purpose of desktop.

I'll see if I can come up with something and report here.

>> And BTW, shouldn't desktop-revert be the user facing interface here?
>
> What do you mean?  desktop-revert is described in that section (again,
> without any hint about when it could be useful).

I think I was mistaken desktop-read seems to be the correct interface as
documented in desktop-save-mode function.
-- 
Manuel Giraud

bug#60600: 30.0.50; [PATCH] Document manual desktop restore

[Eli Zaretskii]

> From: Manuel Giraud <manuel@ledu-giraud.fr>
> Cc: 60600@debbugs.gnu.org
> Date: Fri, 06 Jan 2023 14:30:39 +0100
> 
> >> And BTW, shouldn't desktop-revert be the user facing interface here?
> >
> > What do you mean?  desktop-revert is described in that section (again,
> > without any hint about when it could be useful).
> 
> I think I was mistaken desktop-read seems to be the correct interface as
> documented in desktop-save-mode function.

Yes, desktop-read should be mentioned there, as desktop-revert is only
TRT if one ever uses a single desktop file.

bug#60600: 30.0.50; [PATCH] Document manual desktop restore

[Manuel Giraud]

[-- Attachment #1: Type: text/plain, Size: 327 bytes --]

Here is a rewrite/reshuffle of (Saving Emacs Sessions) node.

I tried to explain desktop-save-mode right from the start.  Then go on
with the options by order of importance.  As you suggest, I left
desktop-load-locked-desktop quite high even though I find it a bit
verbose and quite « implementation detail ».  WDYT?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Rewrite-Saving-Emacs-Sessions-bug-60600.patch --]
[-- Type: text/x-patch, Size: 9462 bytes --]

From 7b38bc4b21ebb488a434a5c658f8d463d0131714 Mon Sep 17 00:00:00 2001
From: Manuel Giraud <manuel@ledu-giraud.fr>
Date: Fri, 6 Jan 2023 11:29:20 +0100
Subject: [PATCH] Rewrite "Saving Emacs Sessions" (bug#60600)

* doc/emacs/misc.texi (Saving Emacs Sessions): Organize this node more
logically with main behaviour and important features at the top.
---
 doc/emacs/misc.texi | 136 +++++++++++++++++++++++---------------------
 1 file changed, 70 insertions(+), 66 deletions(-)

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index c706b727e6f..167181f5d1e 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -2704,38 +2704,13 @@ Saving Emacs Sessions
 @cindex reload files
 @cindex desktop
 
-@vindex desktop-restore-frames
    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.  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.
+to another.  The Emacs @dfn{desktop} consists of the buffers, their
+file names, major modes, buffer positions, and so on.
 
-@vindex frameset-filter-alist
-   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
-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.
-
-@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 automatic saving of the desktop
-when you exit Emacs, and automatic restoration of the last saved
-desktop when Emacs starts: use the Customization buffer (@pxref{Easy
+@findex desktop-save-mode
+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}):
 
@@ -2743,25 +2718,69 @@ Saving Emacs Sessions
 (desktop-save-mode 1)
 @end example
 
-@findex desktop-change-dir
-@findex desktop-revert
 @vindex desktop-path
+@vindex desktop-auto-save-timeout
   If you turn on @code{desktop-save-mode} in your init file, then when
-Emacs starts, it looks for a saved desktop in the current directory.
-(More precisely, it looks in the directories specified by
-@code{desktop-path}, and uses the first desktop it finds.)
-Thus, you can have separate saved desktops in different directories,
-and the starting directory determines which one Emacs reloads.  You
+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.
+
+@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.
 
-  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.
+@vindex desktop-load-locked-desktop
+  The file in which Emacs saves the desktop is locked while the
+session runs, to avoid inadvertently overwriting it from another Emacs
+session.  That lock is normally removed when Emacs exits, but if Emacs
+or your system crashes, the lock stays, and when you restart Emacs, it
+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.
+
+@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.
+
+@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.
+
+@vindex frameset-filter-alist
+   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
+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.
 
 @vindex desktop-restore-eager
   By default, all the buffers in the desktop are restored in one go.
@@ -2780,30 +2799,12 @@ Saving Emacs Sessions
 @code{desktop-clear-preserve-buffers-regexp}, whose value is a regular
 expression matching the names of buffers not to kill.
 
-  If you want to save minibuffer history from one session to
-another, use the @code{savehist} library.
-
-@vindex desktop-auto-save-timeout
-  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.
-
-@vindex desktop-load-locked-desktop
-  The file in which Emacs saves the desktop is locked while the
-session runs, to avoid inadvertently overwriting it from another Emacs
-session.  That lock is normally removed when Emacs exits, but if Emacs
-or your system crashes, the lock stays, and when you restart Emacs, it
-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.
+  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,
@@ -2817,6 +2818,9 @@ Saving Emacs Sessions
 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.
+
 @node Recursive Edit
 @section Recursive Editing Levels
 @cindex recursive editing level
-- 
2.39.0


[-- Attachment #3: Type: text/plain, Size: 18 bytes --]

-- 
Manuel Giraud

bug#60600: 30.0.50; [PATCH] Document manual desktop restore

[Eli Zaretskii]

> From: Manuel Giraud <manuel@ledu-giraud.fr>
> Cc: 60600@debbugs.gnu.org
> Date: Fri, 06 Jan 2023 16:15:08 +0100
> 
> Here is a rewrite/reshuffle of (Saving Emacs Sessions) node.
> 
> I tried to explain desktop-save-mode right from the start.  Then go on
> with the options by order of importance.  As you suggest, I left
> desktop-load-locked-desktop quite high even though I find it a bit
> verbose and quite « implementation detail ».  WDYT?

Thanks, this LGTM.  So I've installed it on the emacs-29 release
branch, and then made a few minor changes in the wording and the
arrangement of the text.

And with this, I'm closing this bug.