Re: Removing obsolete function `org-truely-invisible-p'.

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

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

On 05 Apr 2022, Ihor Radchenko wrote: 
>Sorry for not being clear. I was referring to the commit message 
>- it is
>what you commonly see in git log.
>
>Having something like
>
>>>> commit-hash Mark function obsolete & fix spelling of its name
>
>in git log is confusing because it is unclear what the commit is
>changing. If you look at
>https://git.savannah.gnu.org/cgit/emacs/org-mode.git/log/
>then you can see that we generally follow certain style of the
>commit messages: changed-file-or-library: What is changed
>Also see 
>https://orgmode.org/worg/org-contribute.html#commit-messages

Oh, it was clear you were referring to the commit message -- what 
I now realize is that you were referring to the first line of the 
commit message (the summary line).

Unfortunately, the 'CONTRIBUTE' file at the top level of the Org 
Mode source tree gives incomplete guidance on commit messages (it 
just says to follow what Emacs does, so I did that).  I didn't 
realize that 
https://orgmode.org/worg/org-contribute.html#commit-messages has 
further, slightly different guidance.

Thanks.  I'm happy to adhere to the local standards, once I figure 
out what they are :-).

>I think we have a misunderstanding here. Unused functions are not
>necessarily obsolete. For example, we have org-list-to-texinfo, 
>which is
>not used anywhere in the codebase, but could be useful for 
>developers.
>
>org-compat.el contains functions that are planned for removal in 
>future
>(and obsolete for the time being), obsolete function/variable 
>names, and
>compatibility functions.
>
>As I mentioned in my previous email, I am slightly reluctant to 
>remove
>org-truely-invisible-p. It means that it should remain available 
>and no
>plans to remove it should be made (unless there are multiple 
>devs/users
>who prefer removal). Hence, the function should stay in 
>org-macs.el.
>org-macs.el is meant to store general-purpose functions that can 
>be
>useful for development of the whole Org mode ecosystem.
>
>If we decide that org-truely-invisible-p stays in org-macs, we 
>should
>fix the issue with its name. Renaming requires creating obsolete
>function name alias in org-compat.el to make sure that nothing 
>gets
>broken unexpectedly for people who use org-truely-invisible-p 
>with its
>current name.
>
>Hope I clarified my logic.

You did!

>FYI, I do not know an easy way to search mailing list archives by
>Message-ID. Message-ID itself does not even provide information 
>which
>mailing list it is referring to (maybe it is e.g. Emacs devel).
>That's why I prefer links - they can often be found using 
>archive.org if
>nothing.
>
>On the other hand, extra information would not heart. In addition 
>to
>link.

Makes sense, yup.  Actually, I usually include the link -- I just 
didn't think of it in this case because I rarely visit the Org 
Mode mailing list archives (unlike the Emacs Devel archives, which 
I often do visit, and therefore my commits in Emacs always include 
the link when referring to a mailing list post).

A revised patch is attached.  Now it's so simple that I think the 
commit message doesn't need to point to the mailing list 
discussion anyway.  Review welcome.

Best regards,
-Karl


[-- Attachment #2: 0001-lisp-org-macs.el-Fix-spelling-of-org-truly-invisible.patch --]
[-- Type: text/plain, Size: 1472 bytes --]

From 2cef1fdbe2b2aa40a2bb081eab4b2e2808000670 Mon Sep 17 00:00:00 2001
From: Karl Fogel <kfogel@red-bean.com>
Date: Thu, 31 Mar 2022 19:02:38 -0500
Subject: [PATCH] lisp/org-macs.el: Fix spelling of `org-truly-invisible-p'

* lisp/org-macs.el (org-truly-invisible-p): Fix spelling of name.
* lisp/org-compat.el (org-truely-invisible-p): Add compatibility
  alias for the old name.
---
 lisp/org-compat.el | 4 ++++
 lisp/org-macs.el   | 2 +-
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git lisp/org-compat.el lisp/org-compat.el
index 38d330de6..00716ae13 100644
--- lisp/org-compat.el
+++ lisp/org-compat.el
@@ -752,6 +752,10 @@ context.  See the individual commands for more information."
 
 (define-obsolete-function-alias 'org-get-last-sibling 'org-get-previous-sibling "9.4")
 
+(define-obsolete-function-alias 'org-truely-invisible-p
+  'org-truly-invisible-p "9.6"
+  "Compatibility alias for legacy misspelling of `org-truly-invisible-p'.")
+
 ;;;; Obsolete link types
 
 (eval-after-load 'ol
diff --git lisp/org-macs.el lisp/org-macs.el
index b39af9103..a09115e7c 100644
--- lisp/org-macs.el
+++ lisp/org-macs.el
@@ -1151,7 +1151,7 @@ fontification."
 	  (folding-only (memq value '(org-hide-block outline)))
 	  (t value))))
 
-(defun org-truely-invisible-p ()
+(defun org-truly-invisible-p ()
   "Check if point is at a character currently not visible.
 This version does not only check the character property, but also
 `visible-mode'."
-- 
2.35.1