From: Karl Fogel <kfogel@red-bean.com>
Date: Wed, 26 May 2021 19:28:11 +0000 (-0500)
Subject: Improve some doc strings in bookmark.el
X-Git-Tag: emacs-28.0.90~2322
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=c4e8d1dbe2e79824c8696b4c7adc510ac4e5515e;p=emacs.git

Improve some doc strings in bookmark.el

* lisp/bookmark.el (bookmark-bmenu-load): Describe prefix argument
  behavior.  Refer to related functions for more information.
  (bookmark-bmenu-save): Likewise refer to related functions.

As discussed in this thread:

  https://lists.gnu.org/archive/html/emacs-devel/2021-05/msg00389.html

  From: Karl Fogel
  To: Eli Zaretskii
  Cc: Matthias Meulien, Drew Adams, Lars Ingebrigtsen,
      Stefan Monnier, Emacs Devel
  Subject: Re: [External] : Re: [PATCH] When deleting in bookmark menu,
           prompt for confirmation.
  Date: Sun, 09 May 2021 13:37:52 -0500
  Message-ID: <87h7jboirj.fsf@red-bean.com>
---

diff --git a/lisp/bookmark.el b/lisp/bookmark.el
index 64b467adfae..31e41a9273c 100644
--- a/lisp/bookmark.el
+++ b/lisp/bookmark.el
@@ -2054,7 +2054,10 @@ You can mark bookmarks with the \\<bookmark-bmenu-mode-map>\\[bookmark-bmenu-mar
 
 (defun bookmark-bmenu-save ()
   "Save the current list into a bookmark file.
-With a prefix arg, prompts for a file to save them in."
+With a prefix arg, prompts for a file to save them in.
+
+See also the related behaviors of `bookmark-load' and
+`bookmark-bmenu-load'."
   (interactive nil bookmark-bmenu-mode)
   (save-excursion
     (save-window-excursion
@@ -2063,7 +2066,19 @@ With a prefix arg, prompts for a file to save them in."
 
 
 (defun bookmark-bmenu-load ()
-  "Load the bookmark file and rebuild the bookmark menu-buffer."
+  "Load bookmarks from a file and rebuild the bookmark menu-buffer.
+Prompt for a file, with the default choice being the value of
+`bookmark-default-file'.
+
+With a prefix argument, replace the current ambient bookmarks
+(i.e., the ones in `bookmark-alist') with the ones from the selected
+file and make that file be the new value of `bookmark-default-file'.
+In other words, a prefix argument means \"switch over to the bookmark
+universe defined in the loaded file\".  Without a prefix argument,
+just add the loaded bookmarks into the current ambient set.
+
+See the documentation for `bookmark-load' for more details; see also
+the related behaviors of `bookmark-save' and `bookmark-bmenu-save'."
   (interactive nil bookmark-bmenu-mode)
   (bookmark-bmenu-ensure-position)
   (save-excursion