bug#49373: 28.0.50; [PATCH] Use 'remember-buffer' in remember.el doc strings

bug#49373: 28.0.50; [PATCH] Use 'remember-buffer' in remember.el doc strings

[Gabriel]

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

This patch replaces the hard coded '*Remember*' string with
'remember-buffer' in all doc strings occurrences in remember.el.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Use-remember-buffer-in-remember.el-doc-strings.patch --]
[-- Type: text/x-patch, Size: 2287 bytes --]

From c60201aeff21521a036d4fdc990de9ffedd94ffd Mon Sep 17 00:00:00 2001
From: Gabriel do Nascimento Ribeiro <gabriel376@hotmail.com>
Date: Sun, 4 Jul 2021 02:06:12 -0300
Subject: [PATCH 1/1] Use 'remember-buffer' in remember.el doc strings.

lispt/textmodes/remember.el (remember-initial-contents)
(remember-before-remember-hook, remember, remember-region)
(remember-destroy): Ditto.
---
 lisp/textmodes/remember.el | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/lisp/textmodes/remember.el b/lisp/textmodes/remember.el
index 4acdc9f4d8..4daeb336da 100644
--- a/lisp/textmodes/remember.el
+++ b/lisp/textmodes/remember.el
@@ -240,10 +240,10 @@ remember-annotation-functions
 (defvar remember-annotation nil
   "Current annotation.")
 (defvar remember-initial-contents nil
-  "Initial contents to place into *Remember* buffer.")
+  "Initial contents to place into `remember-buffer'.")
 
 (defcustom remember-before-remember-hook nil
-  "Functions run before switching to the *Remember* buffer."
+  "Functions run before switching to the `remember-buffer'."
   :type 'hook)
 
 (defcustom remember-run-all-annotation-functions-flag nil
@@ -253,8 +253,8 @@ remember-run-all-annotation-functions-flag
 ;;;###autoload
 (defun remember (&optional initial)
   "Remember an arbitrary piece of data.
-INITIAL is the text to initially place in the *Remember* buffer,
-or nil to bring up a blank *Remember* buffer.
+INITIAL is the text to initially place in the `remember-buffer',
+or nil to bring up a blank `remember-buffer'.
 
 With a prefix or a visible region, use the region as INITIAL."
   (interactive
@@ -422,7 +422,7 @@ remember-append-to-file
 
 (defun remember-region (&optional beg end)
   "Remember the data from BEG to END.
-It is called from within the *Remember* buffer to save the text
+It is called from within the `remember-buffer' to save the text
 that was entered.
 
 If BEG and END are nil, the entire buffer will be remembered.
@@ -478,7 +478,7 @@ remember-finalize
   (remember-region (point-min) (point-max)))
 
 (defun remember-destroy ()
-  "Destroy the current *Remember* buffer."
+  "Destroy the current `remember-buffer'."
   (interactive)
   (when (equal remember-buffer (buffer-name))
     (kill-buffer (current-buffer))
-- 
2.32.0

bug#49373: 28.0.50; [PATCH] Use 'remember-buffer' in remember.el doc strings

[Eli Zaretskii]

> From: Gabriel <gabriel376@hotmail.com>
> Date: Sun, 04 Jul 2021 02:15:14 -0300
> 
> This patch replaces the hard coded '*Remember*' string with
> 'remember-buffer' in all doc strings occurrences in remember.el.

remember-buffer is an internal variable, so exposing it in the doc
strings of public functions, let alone commands, is not necessarily
TRT?

bug#49373: 28.0.50; [PATCH] Use 'remember-buffer' in remember.el doc strings

[Gabriel]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Gabriel <gabriel376@hotmail.com>
>> Date: Sun, 04 Jul 2021 02:15:14 -0300
>> 
>> This patch replaces the hard coded '*Remember*' string with
>> 'remember-buffer' in all doc strings occurrences in remember.el.
>
> remember-buffer is an internal variable, so exposing it in the doc
> strings of public functions, let alone commands, is not necessarily
> TRT?

Hi Eli,

Good catch! I didn't notice that 'remember-buffer' is a defvar. Indeed
it does not make sense to refer to an internal variable in the doc
string of public functions.

Perhaps the 'remember-buffer' could be changed to a defcustom?

By the way, the 'remember-initial-contents' seems to be another
candidate for a defcustom, but I am not sure if I really understood its
use case. It's an internal variable, with a default value of nil, that
is not set anywhere and reset to nil on every call of 'remember'. If we
set a value and remove the reset inside 'remember', it works as
described by the name and by the doc string: "Initial contents to place
into *Remember* buffer.".

If the maintainers decide to not change any defvar to defcustom, feel
free to close this bug report.

Thank you,
Gabriel

bug#49373: 28.0.50; [PATCH] Use 'remember-buffer' in remember.el doc strings

[Eli Zaretskii]

> From: Gabriel <gabriel376@hotmail.com>
> Date: Sun, 04 Jul 2021 12:21:42 -0300
> 
> > remember-buffer is an internal variable, so exposing it in the doc
> > strings of public functions, let alone commands, is not necessarily
> > TRT?
> 
> Hi Eli,
> 
> Good catch! I didn't notice that 'remember-buffer' is a defvar. Indeed
> it does not make sense to refer to an internal variable in the doc
> string of public functions.
> 
> Perhaps the 'remember-buffer' could be changed to a defcustom?

I won't object, if that would help in some use cases.

Lars, WDYT?

> By the way, the 'remember-initial-contents' seems to be another
> candidate for a defcustom, but I am not sure if I really understood its
> use case. It's an internal variable, with a default value of nil, that
> is not set anywhere and reset to nil on every call of 'remember'. If we
> set a value and remove the reset inside 'remember', it works as
> described by the name and by the doc string: "Initial contents to place
> into *Remember* buffer.".

Same response here: would that be useful enough?

bug#49373: 28.0.50; [PATCH] Use 'remember-buffer' in remember.el doc strings

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> Perhaps the 'remember-buffer' could be changed to a defcustom?
>
> I won't object, if that would help in some use cases.
>
> Lars, WDYT?

Sure; fine by me.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#49373: 28.0.50; [PATCH] Use 'remember-buffer' in remember.el doc strings

[Lars Ingebrigtsen]

Gabriel <gabriel376@hotmail.com> writes:

> This patch replaces the hard coded '*Remember*' string with
> 'remember-buffer' in all doc strings occurrences in remember.el.

Thanks; applied to Emacs 28 (and I also made remember-buffer into a
defcustom).

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no