org-tag-eldoc.el

   1 ;;; org-tag-eldoc.el --- Display tag explanation in Eldoc -*- lexical-binding: t; -*-
   2 ;; -*- coding: utf-8 -*-
   3
   4 ;; Copyright (C) 2020-2021 Free Software Foundation, Inc.
   5
   6 ;;; Commentary:
   7
   8 ;;; Display tag explanation in Eldoc when point on tag.
   9
  10 ;;; Code:
  11 \f
  12 (defcustom org-tag-eldoc-tag-explanations-alist
  13   '(("Linux" . "Linux (/ˈlɪnʊks/ LIN-uuks) is a family of open-source Unix-like operating systems based on the Linux kernel, an operating system kernel first released on September 17, 1991, by Linus Torvalds.")
  14     ("Emacs" . "Emacs /ˈiːmæks/ ⓘ, originally named EMACS (an acronym for \"Editor Macros\"), is a family of text editors that are characterized by their extensibility. The manual for the most widely used variant, GNU Emacs, describes it as \"the extensible, customizable, self-documenting, real-time display editor\". Development of the first Emacs began in the mid-1970s, and work on GNU Emacs, directly descended from the original, is ongoing; its latest version is 29.2, released January 2024.")
  15     ("GNU" . "GNU (/ɡnuː/ ⓘ) is an extensive collection of free software (385 packages as of September 2023), which can be used as an operating system or can be used in parts with other operating systems. The use of the completed GNU tools led to the family of operating systems popularly known as Linux. Most of GNU is licensed under the GNU Project's own General Public License (GPL)."))
  16   "Alist of cons cell with tag and explanation."
  17   :type 'alist
  18   :safe #'listp
  19   :group 'org-tags)
  20
  21 (defun org-tag-eldoc-tag-explanation (&optional tag)
  22   "Display tag explanation in Eldoc when point on TAG."
  23   (let ((tag (or tag (thing-at-point 'symbol))))
  24     (cdr (assoc tag org-tag-eldoc-tag-explanations-alist))))
  25
  26 (defun org-tag-eldoc-function (&rest args)
  27   "The eldoc function to be added into `eldoc-documentation-functions'."
  28   ;; TODO: `org-element-at-point' return `headline' instead of `tags.' Need Org mode to implement it.
  29   ;; Use `thing-at-point' to workaround the missing `tags' syntax element node in `org-element-at-point' / `org-context'.
  30   (when (member (thing-at-point 'symbol) (org-get-local-tags))
  31     (org-tag-eldoc-tag-explanation)))
  32
  33 ;;; `eldoc-documentation-function', `eldoc-documentation-functions'
  34 ;;;###autoload
  35 (defun org-tag-eldoc-setup ()
  36   "Setup `eldoc-documentation-functions'."
  37   (add-hook 'eldoc-documentation-functions #'org-tag-eldoc-function nil t))
  38
  39 (add-hook 'org-mode-hook #'org-tag-eldoc-setup)
  40
  41 ;;; TODO: Add mouse hover popup info support.
  42
  43
  44 \f
  45
  46 (provide 'org-tag-eldoc)
  47
  48 ;;; org-tag-eldoc.el ends here