Re: [External] : Re: [PATCH] When deleting in bookmark menu, prompt for confirmation.

[Karl Fogel <kfogel@red-bean.com>]

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

On 25 May 2021, Eli Zaretskii wrote:
>> From: Karl Fogel <kfogel@red-bean.com>
>> Cc: orontee@gmail.com,  drew.adams@oracle.com,  larsi@gnus.org,
>>   monnier@iro.umontreal.ca,  emacs-devel@gnu.org
>> Date: Tue, 25 May 2021 00:38:22 -0500
>> 
>> >> Thoughts?
>> >
>> >I'll have thoughts when I see the result ;-)
>> 
>> Heh, fair enough.  My inquiry was about the general practice of 
>> having one function's doc string referring out to another 
>> function's.
>
>It depends on what you need to say, thus my response above.
>
>Given what you wrote, and what bookmark-load does with the prefix
>argument, I think it is better to say that explicitly in
>bookmark-bmenu-load's doc string, since you only need a single 
>quite
>simple sentence to say that, whereas the doc strong of 
>bookmark-load
>is quite long.

Well, now that I've done it, I think your way is an improvement -- 
although it turned out to be slightly more doc change than I 
expected.  Revised patch attached for review.

Best regards,
-Karl


[-- Attachment #2: 0001-Improve-some-doc-strings-in-bookmark.el.patch --]
[-- Type: text/plain, Size: 2410 bytes --]

From 5817bd661775f4f9ecb1ab0efc831a36fef44578 Mon Sep 17 00:00:00 2001
From: Karl Fogel <kfogel@red-bean.com>
Date: Tue, 25 May 2021 00:26:57 -0500
Subject: [PATCH] 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>
---
 lisp/bookmark.el | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git lisp/bookmark.el lisp/bookmark.el
index 64b467adfa..31e41a9273 100644
--- lisp/bookmark.el
+++ lisp/bookmark.el
@@ -2054,7 +2054,10 @@ bookmark-bmenu-any-marks
 
 (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 @@ bookmark-bmenu-save
 
 
 (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
-- 
2.30.2