Some doc edits related to desktop-restore-frames

* doc/emacs/misc.texi (Saving Emacs Sessions):
Be briefer about desktop's handling of frames.
The manual does not need to mention every option, nor should
it just repeat the doc-strings.

* lisp/desktop.el (desktop-restore-frames)
(desktop-restore-in-current-display, desktop-restore-forces-onscreen)
(desktop-restore-reuses-frames): Doc tweaks.

* etc/NEWS: Related edits.

5 files changed, 31 insertions, 42 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 67987ddc9e6..6adfa7fb90c 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -8,6 +8,9 @@
 
 2014-03-12  Glenn Morris  <rgm@gnu.org>
 
+        * misc.texi (Saving Emacs Sessions): Be briefer about desktop's
+        handling of frames.
+
         * indent.texi (Indent Convenience): Mention electric-indent-local-mode.
 
 2014-03-02  Xue Fuqiao  <xfq@gnu.org>
diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 801d9f9e4e6..f935b2e68d6 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -2132,10 +2132,13 @@ hexl-@key{RET}} for details.
 @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.
+subsequent Emacs sessions reload the saved desktop.  By default,
+the desktop also tries to save the frame and window configuration.
+To disable this, customize @code{desktop-restore-frames} to @code{nil}.
 
 @findex desktop-save
 @vindex desktop-save-mode
@@ -2193,32 +2196,6 @@ 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.
 
-@vindex desktop-restore-frames
-@code{desktop-restore-frames}, enabled by default, a non-@code{nil}
-means save frames (@pxref{Frames}) to desktop file.
-
-@vindex desktop-restore-in-current-display
-If the value of @code{desktop-restore-in-current-display} is @code{t},
-frames are restored in the current display.  If @code{nil} (the
-default), frames are restored in their original displays if possible.
-If @samp{delete}, frames on other displays are deleted instead of
-restored.
-
-@vindex desktop-restore-reuses-frames
-If the value of @code{desktop-restore-reuses-frames} is @code{t} (the
-default), restoring frames will reuse existing frames.  If @code{nil},
-existing frames are deleted.  If @samp{:keep}, existing frames are
-kept but not reused.
-
-@vindex desktop-restore-forces-onscreen
-If the value of @code{desktop-restore-forces-onscreen} is @code{t}
-(the default), offscreen frames are restored onscreen.  If
-@samp{:all}, frames that are partially offscreen are also forced
-onscreen.  @strong{Notice:} Checking of frame boundaries is
-approximate.  It may not reliably detect frames whose
-onscreen/offscreen state depends on a few pixels, especially near the
-right and/or bottom borders of the screen.
-
   If you want to save minibuffer history from one session to
 another, use the @code{savehist} library.
 
diff --git a/etc/NEWS b/etc/NEWS
index 910c8385706..04796bf37e2 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -572,10 +572,10 @@ after `desktop-auto-save-timeout'.  To disable this, customize that option
 to nil (or zero).
 
 +++
-*** `desktop-restore-frames', enabled by default, allows saving and
-restoring the frame/window configuration (frameset).  Additional options
-`desktop-restore-in-current-display', `desktop-restore-reuses-frames'
-and `desktop-restore-forces-onscreen' offer further customization.
+*** Desktop now saves and restores the frame/window configuration.
+To disable this, set `desktop-restore-frames' to nil.
+See also related options `desktop-restore-reuses-frames',
+`desktop-restore-in-current-display', and `desktop-restore-forces-onscreen'.
 
 +++
 ** New Dired minor mode `dired-hide-details-mode' toggles whether details,
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 9d99bdecd38..acc0f016caa 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,5 +1,9 @@
 2014-03-12  Glenn Morris  <rgm@gnu.org>
 
+        * desktop.el (desktop-restore-frames)
+        (desktop-restore-in-current-display, desktop-restore-forces-onscreen)
+        (desktop-restore-reuses-frames): Doc tweaks.
+
         * electric.el (electric-indent-mode): Doc fix.
 
 2014-03-12  Juanma Barranquero  <lekktu@gmail.com>
diff --git a/lisp/desktop.el b/lisp/desktop.el
index dbddfb7c1d3..5e43c03ade7 100644
--- a/lisp/desktop.el
+++ b/lisp/desktop.el
@@ -387,15 +387,18 @@ modes are restored automatically; they should not be listed here."
   :group 'desktop)
 
 (defcustom desktop-restore-frames t
-  "When non-nil, save frames to desktop file."
+  "When non-nil, save and restore the frame and window configuration.
+See related options `desktop-restore-reuses-frames',
+`desktop-restore-in-current-display', and `desktop-restore-forces-onscreen'."
   :type 'boolean
   :group 'desktop
   :version "24.4")
 
 (defcustom desktop-restore-in-current-display nil
-  "If t, frames are restored in the current display.
-If nil, frames are restored, if possible, in their original displays.
-If `delete', frames on other displays are deleted instead of restored."
+  "Controls how restoring of frames treats displays.
+If t, restores frames into the current display.
+If nil, restores frames into their original displays (if possible).
+If `delete', deletes frames on other displays instead of restoring them."
   :type '(choice (const :tag "Restore in current display" t)
                  (const :tag "Restore in original display" nil)
                  (const :tag "Delete frames in other displays" delete))
@@ -403,11 +406,13 @@ If `delete', frames on other displays are deleted instead of restored."
   :version "24.4")
 
 (defcustom desktop-restore-forces-onscreen t
-  "If t, offscreen frames are restored onscreen instead.
-If `all', frames that are partially offscreen are also forced onscreen.
-NOTE: Checking of frame boundaries is only approximate and can fail
-to reliably detect frames whose onscreen/offscreen state depends on a
-few pixels, especially near the right / bottom borders of the screen."
+  "If t, restores frames that are fully offscreen onscreen instead.
+If `all', also restores frames that are partially offscreen onscreen.
+
+Note that checking of frame boundaries is only approximate.
+It can fail to reliably detect frames whose onscreen/offscreen state
+depends on a few pixels, especially near the right / bottom borders
+of the screen."
   :type '(choice (const :tag "Only fully offscreen frames" t)
                  (const :tag "Also partially offscreen frames" all)
                  (const :tag "Do not force frames onscreen" nil))
@@ -416,8 +421,8 @@ few pixels, especially near the right / bottom borders of the screen."
 
 (defcustom desktop-restore-reuses-frames t
   "If t, restoring frames reuses existing frames.
-If nil, existing frames are deleted.
-If `keep', existing frames are kept and not reused."
+If nil, deletes existing frames.
+If `keep', keeps existing frames and does not reuse them."
   :type '(choice (const :tag "Reuse existing frames" t)
                  (const :tag "Delete existing frames" nil)
                  (const :tag "Keep existing frames" :keep))