org-ctags.el: Do not activate on load

* etc/ORG-NEWS: Announce the change breaking for `org-ctags' users and
provide init file code to enable the feature.
* lisp/org-ctags.el (org-ctags-enable): Do no invoke this function
during library loading.  Collect all initialization code in its body.

Setting up hooks during library loading leads to various issues.
- Emacs coding conventions insist on incompatible changes if loading
  a library modifies behavior, see
  Info node `(elisp) Coding Conventions'.
- The library may be autoloaded for the sake of help completion
  breaking `org-open-at-point':
  Nick Dokos. org-ctags land grab. Mon, 20 Mar 2023 23:36:09 -0400.
  <https://list.orgmode.org/87o7omg4ie.fsf@alphaville.usersys.redhat.com>
- Unrelated unit tests fail due to user prompt:
  Ihor Radchenko. Re: [PATCH] org-ctags.el: Protect shell specials
  in directory name. Sun, 28 Apr 2024 12:53:38 +0000.
  <https://list.orgmode.org/87a5ldk5rh.fsf@localhost>

etc/ORG-NEWS

@@ -649,6 +649,18 @@ This behaviour has been expanded to store an additional =CUSTOM_ID=
 link when storing any type of external link type in an Org file, not
 just =id:= links.
 
+*** ~org-ctags~ is not activated by default any more
+
+To follow Emacs [[info:elisp#Coding Conventions][coding conventions]] and to avoid confusion of users
+who accidentally get ~org-ctags~ autoloaded due to help completion,
+the library does not modify ~org-open-link-functions~ during loading
+any more.  Run ~org-ctags-enable~ to setup hooks and advices:
+
+#+begin_src emacs-lisp
+(with-eval-after-load "org-ctags"
+  (org-ctags-enable))
+#+end_src
+
 ** New and changed options
 *** ~org-babel-lua-multiple-values-separator~
 

lisp/org-ctags.el

@@ -57,6 +57,12 @@
 ;;    (add-hook 'org-mode-hook
 ;;      (lambda ()
 ;;        (define-key org-mode-map "\C-co" 'org-ctags-find-tag-interactive)))
+;;    (with-eval-after-load "org-ctags"
+;;      (org-ctags-enable))
+;;
+;; To activate the library, you need to call `org-ctags-enable' explicitly.
+;; It used to be invoked during library loading, but it was against Emacs
+;; policy and caused inconvenience of Org users who do not use `org-ctags'.
 ;;
 ;; By default, with org-ctags loaded, org will first try and visit the tag
 ;; with the same name as the link; then, if unsuccessful, ask the user if
@@ -211,10 +217,8 @@ A function for `org-mode-hook."
                     "/TAGS"))))
       (when (file-exists-p tags-filename)
         (visit-tags-table tags-filename)))))
-(add-hook 'org-mode-hook #'org-ctags--visit-tags-table)
 
 
-(advice-add 'visit-tags-table :after #'org--ctags-load-tag-list)
 (defun org--ctags-load-tag-list (&rest _)
   (when (and org-ctags-enabled-p tags-file-name)
     (setq-local org-ctags-tag-list
@@ -222,6 +226,11 @@ A function for `org-mode-hook."
 
 
 (defun org-ctags-enable ()
+  (add-hook 'org-mode-hook #'org-ctags--visit-tags-table)
+  (advice-add 'visit-tags-table :after #'org--ctags-load-tag-list)
+  (advice-add 'xref-find-definitions :before
+              #'org--ctags-set-org-mark-before-finding-tag)
+
   (put 'org-mode 'find-tag-default-function 'org-ctags-find-tag-at-point)
   (setq org-ctags-enabled-p t)
   (dolist (fn org-ctags-open-link-functions)
@@ -314,8 +323,6 @@ The new topic will be titled NAME (or TITLE if supplied)."
 ;;;; Misc interoperability with etags system =================================
 
 
-(advice-add 'xref-find-definitions :before
-            #'org--ctags-set-org-mark-before-finding-tag)
 (defun org--ctags-set-org-mark-before-finding-tag (&rest _)
   "Before trying to find a tag, save our current position on org mark ring."
   (save-excursion
@@ -543,8 +550,6 @@ a new topic."
 	 'org-open-link-functions tag))))))
 
 
-(org-ctags-enable)
-
 (provide 'org-ctags)
 
 ;;; org-ctags.el ends here