{"id":18736014,"url":"https://github.com/rileyrg/el-docstring-sap","last_synced_at":"2026-03-09T11:04:51.079Z","repository":{"id":138319321,"uuid":"360073107","full_name":"rileyrg/el-docstring-sap","owner":"rileyrg","description":"Display elisp documentation for the symbol at point.","archived":false,"fork":false,"pushed_at":"2025-01-24T03:39:00.000Z","size":725,"stargazers_count":10,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-12T19:39:55.209Z","etag":null,"topics":["context","docstring","elisp","emacs","ide","popup","posframe","quick-peek"],"latest_commit_sha":null,"homepage":"","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rileyrg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-04-21T07:32:14.000Z","updated_at":"2025-03-19T21:21:36.000Z","dependencies_parsed_at":"2023-11-26T08:22:03.362Z","dependency_job_id":"46125907-57b9-4eed-93ed-16f729e75971","html_url":"https://github.com/rileyrg/el-docstring-sap","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/rileyrg/el-docstring-sap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rileyrg%2Fel-docstring-sap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rileyrg%2Fel-docstring-sap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rileyrg%2Fel-docstring-sap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rileyrg%2Fel-docstring-sap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rileyrg","download_url":"https://codeload.github.com/rileyrg/el-docstring-sap/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rileyrg%2Fel-docstring-sap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30291854,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T02:57:19.223Z","status":"ssl_error","status_checked_at":"2026-03-09T02:56:26.373Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["context","docstring","elisp","emacs","ide","popup","posframe","quick-peek"],"created_at":"2024-11-07T15:19:04.653Z","updated_at":"2026-03-09T11:04:51.061Z","avatar_url":"https://github.com/rileyrg.png","language":"Emacs Lisp","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Table of Contents\n\n-   [Introduction](#orgbffa372)\n-   [Installation](#org6bff164)\n    -   [use-package](#org05b0e9d)\n-   [Configuration](#org140bf32)\n    -   [Enabling the minor mode](#org9739f77)\n    -   [Manually invoke `el-docstring-el-display`](#org2df78ef)\n    -   [Alternatives to `posframe` for displaying the docstring](#org3d9a9fe)\n        -   [quick-peek](#org4222cd7)\n        -   [popup](#org7be6ab4)\n        -   [`describe-symbol`](#orgd21c724)\n    -   [Programmatically set your display function](#orgc9c8e3d)\n    -   [Interactively choose  the docstring display function.](#org9486e1d)\n-   [Customisation](#org0d8646d)\n        -   [`el-docstring-sap--delay`](#org721aaa4)\n        -   [`el-docstring-sap--display-func`](#org1a56f51)\n        -   [`el-docstring-sap--save-history`](#org2c289b2)\n-   [el-docstring-sap.el](#org09fa342)\n    -   [header](#org0737d60)\n    -   [customisation group](#org42cf21e)\n    -   [main code (to be further broken down)](#org36b2792)\n\n\n\n\u003ca id=\"orgbffa372\"\u003e\u003c/a\u003e\n\n# Introduction\n\nAuto display elisp docstring for symbol at point\n\nlink: [el-docstring-sap.el](el-docstring-sap.el)\n\n[el-docstring-sap](./el-docstring-at-point.el) defines a minor mode `el-docstring-sap-mode` which enables a \"popup\" displaying the elisp docstring for the symbol at point after a [configured delay](#org721aaa4).  Typically you add `el-docstring-sap-mode` to `emacs-lisp-mode-hook` to enable.\n\nThe package assumes [posframe](https://github.com/tumashu/posframe) is available and falls back to it if you set `el-docstring-sap--display-func` to\nsomething that fails.\n\n\n\u003ca id=\"org6bff164\"\u003e\u003c/a\u003e\n\n# Installation\n\n\n\u003ca id=\"org05b0e9d\"\u003e\u003c/a\u003e\n\n## use-package\n\n    (use-package el-docstring-sap\n      :straight (el-docstring-sap :type git :host github :repo \"rileyrg/el-docstring-sap\" )\n      :custom  (el-docstring-sap--display-func 'el-docstring-sap--posframe)\n      :hook\n      (emacs-lisp-mode . el-docstring-sap-mode)\n      :bind\n      (\"M-\u003cf2\u003e\" . el-docstring-sap-display)\n      (\"M-\u003cf1\u003e\" . el-docstring-sap-mode))\n\n\n\u003ca id=\"org140bf32\"\u003e\u003c/a\u003e\n\n# Configuration\n\n\n\u003ca id=\"org9739f77\"\u003e\u003c/a\u003e\n\n## Enabling the minor mode\n\nTypically simply add to your emacs-lisp-mode-hook.\n\n    (add-hook 'emacs-lisp-mode-hook 'el-docstring-sap-mode)\n\n\n\u003ca id=\"org2df78ef\"\u003e\u003c/a\u003e\n\n## Manually invoke `el-docstring-el-display`\n\nBind a key to `el-docstring-sap-display` to call regardless of mode. Note, that if `el-docstring-sap-mode` isnt on, the displayed docstring wont auto disappear when you type, instead invoke again with the cursor on whitespace to turn off the display - this is by design.\n\n    (global-set-key (kbd \"M-\u003cf2\u003e\") #'el-docstring-sap-display)\n\n\n\u003ca id=\"org3d9a9fe\"\u003e\u003c/a\u003e\n\n## Alternatives to `posframe` for displaying the docstring\n\nYou need to explicitly  install the  libraries for `quick-peek` or `popup` if you want to use them else `el-docstring-sap--popup` or\n`el-docstring-sap--quick-peek` will fall back to `el-docstring-sap--posframe` after failing to load the required library.\n\n\n\u003ca id=\"org4222cd7\"\u003e\u003c/a\u003e\n\n### quick-peek\n\n\u003chttps://github.com/cpitclaudel/quick-peek\u003e\n\n\n\u003ca id=\"org7be6ab4\"\u003e\u003c/a\u003e\n\n### popup\n\n\u003chttps://github.com/kzk/elisp/blob/master/m/auto-complete/popup.el\u003e\n\n\n\u003ca id=\"orgd21c724\"\u003e\u003c/a\u003e\n\n### `describe-symbol`\n\nYou can set `el-docstring-sap-display-func` to `el-docstring-sap--describe-symbol` for standard help buffer viewing. See [display function customisation](#org1a56f51) below.\n\n\n\u003ca id=\"orgc9c8e3d\"\u003e\u003c/a\u003e\n\n## Programmatically set your display function\n\n`(setq el-docstring-sap--display-func 'el-docstring-sap--quick-peek)`\n\nThe display function accepts a non zero length string to be displayed. If nil or empty string then erase the last display. See `el-docstring-sap--display-funcs`.\n\n\n\u003ca id=\"org9486e1d\"\u003e\u003c/a\u003e\n\n## Interactively choose  the docstring display function.\n\n`el-docstring-sap-select-display-func` sets `el-docstring-sap--display-func`.\nNot permanent. Bring up the custom interface to save it. (`C-h v el-docstring-sap--display-func`).\n\n\n\u003ca id=\"org0d8646d\"\u003e\u003c/a\u003e\n\n# Customisation\n\nCustomisation group `el-docstring-sap`\n\n\n\u003ca id=\"org721aaa4\"\u003e\u003c/a\u003e\n\n### `el-docstring-sap--delay`\n\nDelay before docstring for symbol at  point\n\n\n\u003ca id=\"org1a56f51\"\u003e\u003c/a\u003e\n\n### `el-docstring-sap--display-func`\n\nFunction that takes a string. If nil or empty then hide previous.\nSee `el-docstring-sap--display-funcs` for candidates.\n\n-   `el-docstring-sap--posframe`\n\n    -   `el-docstring-sap--posframe-poshandler`\n    \n        The poshandler that `posframe-show` uses-\n    \n    -   `el-docstring-sap--posframe-arghandler-plist`\n    \n        Customise default values for posframe display.\n    \n    -   Example screenshot\n    \n        ![img](images/el-docstring-sap--posframe.png \"elisp docstring posframe\")\n\n-   `el-docstring-sap--describe-symbol`\n\n    -   Example screenshot\n    \n        ![img](images/el-docstring-sap--describe-symbol.png \"elisp docstring describe-symbol\")\n\n-   `el-docstring-sap--quick-peek`\n\n    -   Example screenshot\n    \n        ![img](images/el-docstring-sap--quick-peek.png \"elisp docstring quick-peek\")\n\n-   `el-docstring-sap--popup`\n\n    -   Example screenshot\n    \n        ![img](images/el-docstring-sap--popup.png \"elisp docstring popup\")\n\n\n\u003ca id=\"org2c289b2\"\u003e\u003c/a\u003e\n\n### `el-docstring-sap--save-history`\n\n**\u003cspan class=\"underline\"\u003eNot Used currently\u003c/span\u003e**.\n\nWhen non-nil save the symbol queried to `el-docstring-sap--history`\n\n\n\u003ca id=\"org09fa342\"\u003e\u003c/a\u003e\n\n# el-docstring-sap.el\n\nlink: [el-docstring-sap.el](el-docstring-sap.el)\n\n\n\u003ca id=\"org0737d60\"\u003e\u003c/a\u003e\n\n## header\n\n    ;;; el-docstring-sap.el --- A minor-mode display docstrings for the symbol at point\n    ;;\n    ;; maintained in el-docstring-sap.org\n    ;;\n    ;; Copyright (C) 2010-2021 rileyrg\n    ;;\n    ;; Author: rileyrg \u003crileyrg@gmx.de\u003e\n    ;; Created: 22 April 2021\n    ;; Keywords: internal lisp docs help maint tools\n    ;; Version : 1.0\n    ;; Package-Requires: ((emacs \"25.1\") (posframe \"1.0.1\"))\n    ;; Optional :  ((quick-peek \"1.0\") (popup \"0.5.8\"))\n    ;; URL: https://github.com/rileyrg/el-docstring-sap\n    ;;;\n    \n    ;;; commentary:\n    ;;\n    ;; Enable `el-docstring-sap-mode' to have docstrings auto generated using the function\n    ;; referenced by `el-docstring-sap--display-func'.  Defaults to `el-docstring-sap--posframe'.\n    ;;\n    ;; Usage example:\n    ;; (use-package el-docstring-sap\n    ;;   :straight (el-docstring-sap :type git :host github :repo \"rileyrg/el-docstring-sap\" )\n    ;;   :custom  (el-docstring-sap--display-func 'el-docstring-sap--posframe)\n    ;;   :hook\n    ;;   (emacs-lisp-mode . el-docstring-sap-mode)\n    ;;   :bind\n    ;;   (\"M-\u003cf2\u003e\" . 'el-docstring-sap-display)\n    ;;   (\"M-\u003cf1\u003e\" . 'el-docstring-sap-mode))\n    ;;\n    ;; Select display function:-\n    ;; M-x: el-docstring-sap-select-display-func\n    \n    ;;\n    ;;; code:\n\n\n\u003ca id=\"org42cf21e\"\u003e\u003c/a\u003e\n\n## customisation group\n\n    (defgroup  el-docstring-sap nil \"Customisation options for `el-docstring-sap-mode'.\" :group 'rgr)\n    \n    (defcustom el-docstring-sap--delay 2.5 \"How long to delay before `el-docstring-sap--display-func' is called.\" :type 'float)\n    \n    (defcustom el-docstring-sap--save-history t \"When non-nil store each search popup to `el-docstring-sap--history'.\" :type 'boolean)\n    (defvar el-docstring-sap--history nil \"Store history of docstring references.\")\n    \n    (require 'savehist)\n    (add-to-list 'savehist-additional-variables 'el-docstring-sap--history)\n    \n    (defcustom el-docstring-sap--lighter \" SapDoc\" \"Modeline indicator for `el-docstring-sap-mode'.\" :type 'string)\n    \n    (defcustom el-docstring-sap--display-funcs  '(el-docstring-sap--posframe el-docstring-sap--quick-peek el-docstring-sap--popup el-docstring-sap--describe-symbol)\n      \"Functions to provide `el-docstring-sap-mode' display.\" :type '(repeat function))\n    \n    (defcustom el-docstring-sap--display-func 'el-docstring-sap--posframe \"The function to display a docstring for symbol at point.\" :type\n      `(choice :value el-docstring-sap--posframe (const :tag \"default(posframe)\" 'el-docstring-sap--posframe)\n               ,(append '(radio :tag \"Supported docstring display functions\") (mapcar (lambda(e)(cons 'function-item (cons e nil))) el-docstring-sap--display-funcs ))))\n\n\n\u003ca id=\"org36b2792\"\u003e\u003c/a\u003e\n\n## TODO main code (to be further broken down)\n\n    (use-package posframe\n      :commands (posframe-hide posframe-show))\n    \n     (defvar el-docstring-sap--timer nil  \"Store the `el-docstring-sap-mode' timer.\" )\n     (defvar el-docstring-sap--lastsym nil  \"Don't idle-repeat the same symbol twice in a row.\")\n    \n    ;;;###autoload\n     (defun el-docstring-sap--describe-symbol(\u0026optional _docstring sym)\n    \n       \"Use the internal `describe-symbol' to show help for symbol SYM.\"\n       (if sym\n           (describe-symbol sym)\n         (let ((hw (get-buffer-window (help-buffer))))\n           (when (and hw (bound-and-true-p el-docstring-sap--auto-hide-describe-symbol-window))\n             (delete-window hw)))))\n      ;;;###autoload\n     (defun el-docstring-sap--docstring(sym)\n       \"Return the docstring attached to the symbol SYM.  If SYM has no docstring, return nil.\"\n       (if sym\n           (let ((docstring\n                  (if (or (fboundp sym) (boundp sym))\n                      (let ((help-xref-following t))\n                        (save-window-excursion\n                          (with-temp-buffer\n                            (help-mode)\n                            (describe-symbol sym)\n                            (buffer-string))))\n                    nil)))\n             (let((gd  (get sym 'group-documentation)))\n               (when gd\n                 (setq docstring (concat docstring \"\\n----\\ndefgroup \" (symbol-name sym) \":\\n\" gd))))\n             (when (facep sym)\n               (setq docstring (concat docstring \"\\n----\\nface \" (symbol-name sym) \":\\n\" (get sym 'face-documentation))))\n             (if (eq (length docstring) 0)\n                 nil\n               docstring))\n         nil))\n    \n     (defun el-docstring-sap--display-fail(\u0026optional docstring)\n       \"Inform an error occured and revert to dislpaying DOCSTRING with `el-docstring-sap--posframe.\"\n       (message \"Function  `%s' failed. Library loaded? Reverting to `el-docstring-sap--posframe'.\" el-docstring-sap--display-func)\n       (setq el-docstring-sap--display-func 'el-docstring-sap--posframe)\n       (el-docstring-sap--posframe docstring))\n    \n     (defun el-docstring-sap--hide()\n       \"Hide the the elisp docstring.\"\n       (funcall el-docstring-sap--display-func nil nil))\n    \n     (defun el-docstring-sap--timer-func()\n       \"Function called every `el-docstring-sap--delay' seconds when `el-docstring-sap-mode' is non-nil.\"\n       (when (bound-and-true-p el-docstring-sap-mode)\n         (let ((sym (symbol-at-point)))\n           (el-docstring-sap-display sym))))\n    \n     ;;;###autoload\n     (defun el-docstring-sap-display(\u0026optional sym)\n       \"Display docstring for optional SYM, defaulting to `symbol-at-point', using `el-docstring-sap--display-func'.\"\n       (interactive)\n       (when (called-interactively-p 'any)\n         ;; since there's not a pre-action hook to clean it in many cases\n         (el-docstring-sap--hide))\n       (let((sym (if sym sym (symbol-at-point))))\n         (if (not sym)\n             (when (called-interactively-p 'any)\n               (message \"No symbol at point.\"))\n           ;; only display if we specifically asked for it or it wasnt displayed\n           ;; in the last idle timer popup\n           (when (or (called-interactively-p 'any) (not (eq sym el-docstring-sap--lastsym)))\n             (let ((docstring (el-docstring-sap--docstring sym)))\n               (if docstring\n                   (progn\n                     (setq el-docstring-sap--lastsym sym)\n                     (when el-docstring-sap--save-history\n                       (add-to-history 'el-docstring-sap--history sym))\n                     (save-excursion\n                       (condition-case nil\n                           (funcall el-docstring-sap--display-func  docstring sym)\n                         (error (el-docstring-sap--display-fail docstring )))))))))))\n    \n     ;;;###autoload\n     (defun el-docstring-sap-select-display-func()\n       \"Select a `el-docstring-sap-mode' display function from `el-docstring-sap--display-funcs'.\"\n       (interactive)\n       (let* ((fl (mapcar (lambda(s)(cons (documentation s) s)) el-docstring-sap--display-funcs))\n              (f (alist-get (completing-read \"function: \" fl) fl nil nil #'equal)))\n         (when f\n           (setq el-docstring-sap--lastsym nil)\n           (setq el-docstring-sap--display-func f))))\n    \n     ;;;###autoload\n     (define-minor-mode el-docstring-sap-mode\n       \"minor-mode to popup help for the elisp symbol at point.\"\n       :lighter el-docstring-sap--lighter\n       (if (bound-and-true-p el-docstring-sap-mode)\n           (add-hook 'pre-command-hook 'el-docstring-sap--hide nil t)\n         (remove-hook 'pre-command-hook 'el-docstring-sap--hide t))\n       (el-docstring-sap--hide)\n       (unless el-docstring-sap--timer\n         (setq  el-docstring-sap--timer\n                (run-with-idle-timer\n                 el-docstring-sap--delay t\n                 'el-docstring-sap--timer-func))))\n    \n     (defcustom el-docstring-sap--posframe-poshandler  nil \"select the PosFrame :poshandler.\"\n       :type '(choice\n               (const :tag \"Show docstring at point.\" nil)\n               (radio :tag \"posframe :poshandler\"\n                      (function-item posframe-poshandler-frame-top-left-corner)\n                      (function-item posframe-poshandler-frame-top-center)\n                      (function-item posframe-poshandler-frame-top-right-corner)\n                      (function-item posframe-poshandler-frame-bottom-left-corner)\n                      (function-item posframe-poshandler-frame-bottom-center)\n                      (function-item posframe-poshandler-frame-bottom-right-corner)\n                      (function-item posframe-poshandler-frame-center)\n                      (function-item posframe-poshandler-window-top-left-corner)\n                      (function-item posframe-poshandler-window-top-center)\n                      (function-item posframe-poshandler-window-top-right-corner)\n                      (function-item posframe-poshandler-window-bottom-left-corner)\n                      (function-item posframe-poshandler-window-bottom-center)\n                      (function-item posframe-poshandler-window-bottom-right-corner)\n                      (function-item posframe-poshandler-window-center))))\n    \n     (defcustom el-docstring-sap--posframe-arghandler-plist  '(:width 80 :internal-border-width 2 :background-color \"#303030\" :border-width 2 :border-color \"orange\") \"Posfame's fallback config plist.\" :type 'plist )\n    \n     (defun el-docstring-sap--posframe-arghandler (_buffer-or-name arg-name value)\n       \"Function to override posframe VALUE for ARG-NAME with customs from the plist `el-docstring-sap--posframe-arghandler-plist'\"\n       (let ((info el-docstring-sap--posframe-arghandler-plist))\n         (or (plist-get info arg-name) value)))\n    \n    \n     ;;;###autoload\n     (defun el-docstring-sap--posframe(\u0026optional docstring _sym)\n       \"`posframe-show' to display  DOCSTRING. Pass nil to erase.\"\n       (interactive)\n       (posframe-hide \"*el-docstring*\")\n       (when docstring\n         (let ((p (point))\n               (posframe-arghandler 'el-docstring-sap--posframe-arghandler))\n           (save-window-excursion\n             (with-current-buffer\n                 (get-buffer-create \"*el-docstring*\")\n               (erase-buffer)\n               (insert docstring)\n               (posframe-show (current-buffer)\n                              :string docstring\n                              :poshandler el-docstring-sap--posframe-poshandler\n                              :position (if (bound-and-true-p el-docstring-sap--posframe-poshandler) t p)))))))\n    \n     ;;;###autoload\n     (defun el-docstring-sap--quick-peek(\u0026optional docstring _sym)\n       \"`quick-peek-show' to display  DOCSTRING.  Pass nil to erase.\"\n       (interactive)\n       (condition-case nil\n           (progn\n             (quick-peek-hide)\n             (when (not (featurep 'quick-peek))\n               (use-package quick-peek :commands (quick-peek-hide quick-peek-show)))\n             (when docstring\n               (quick-peek-show docstring)))\n         (error (el-docstring-sap--display-fail docstring))))\n    \n     ;;;###autoload\n     (defun el-docstring-sap--popup(\u0026optional docstring _sym)\n       \"`popup-tip' to display  DOCSTRING.  Pass nil to erase.\"\n       (interactive)\n       (condition-case nil\n           (progn\n             (when (not (featurep 'popup))\n               (use-package popup :commands (popup-tip)))\n             (when docstring\n               (popup-tip docstring)))\n         (error (el-docstring-sap--display-fail docstring))))\n    \n     (provide 'el-docstring-sap)\n\n(require 'org-capture)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frileyrg%2Fel-docstring-sap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frileyrg%2Fel-docstring-sap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frileyrg%2Fel-docstring-sap/lists"}