eldo.el 5.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153
  1. ;;; eldo.el --- Elisp Doc-to-Org converter
  2. ;; Copyright (C) 2012--2014 Bastien Guerry
  3. ;;
  4. ;; Author: Bastien Guerry <bzg@gnu.org>
  5. ;; Keywords: elisp, documentation, org
  6. ;; Homepage: https://orgmode.org
  7. ;;
  8. ;; This file is not part of GNU Emacs.
  9. ;;
  10. ;; GNU Emacs is free software: you can redistribute it and/or modify
  11. ;; it under the terms of the GNU General Public License as published by
  12. ;; the Free Software Foundation, either version 3 of the License, or
  13. ;; (at your option) any later version.
  14. ;; GNU Emacs is distributed in the hope that it will be useful,
  15. ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  16. ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17. ;; GNU General Public License for more details.
  18. ;; You should have received a copy of the GNU General Public License
  19. ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
  20. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  21. ;;
  22. ;;; Commentary:
  23. ;;
  24. ;; M-x eldo-make-doc RET will create a file with documentation for hooks,
  25. ;; commands and options, given a subset of *.el files. Use an .org file
  26. ;; to write the documentation.
  27. ;;
  28. ;; This file is inspired by Nic Ferrier's wikidoc.el, with contributions
  29. ;; from Eric Schulte and Thorsten Jolitz.
  30. ;;
  31. ;;; Todo:
  32. ;;
  33. ;; - refactor and add customizable variables?
  34. (defvar eldo-keymaps nil)
  35. (defvar eldo-git-raw-file
  36. "https://orgmode.org/cgit.cgi/org-mode.git/plain/lisp/%s")
  37. (defvar eldo-git-search-string
  38. "https://orgmode.org/cgit.cgi/org-mode.git/log/?qt=grep&q=%s")
  39. (defvar eldo-file nil)
  40. (defun eldo-load (dir prefix)
  41. "Load Elisp files in DIR with PREFIX."
  42. (if (string= (file-name-extension dir) "el")
  43. (load-file dir)
  44. (dolist (file (directory-files
  45. (expand-file-name dir)
  46. 'full (concat (or prefix "") ".*\.el$")))
  47. (load-file file))))
  48. (defun eldo-make-doc (dir prefix)
  49. "Insert documentation in the current buffer."
  50. (interactive "fDirectory or file: \nsPrefix: ")
  51. (eldo-load dir prefix)
  52. (let (eldo-keymaps hks cmds opts vars funcs)
  53. (mapatoms
  54. (lambda(a)
  55. (when (string-prefix-p prefix (symbol-name a))
  56. (cond ((keymapp a) (setq eldo-keymaps (cons a eldo-keymaps)))
  57. ((string-match "hook$\\|functions$" (symbol-name a))
  58. (setq hks (cons a hks)))
  59. ((commandp a) (setq cmds (cons a cmds)))
  60. ((get a 'custom-type) (setq opts (cons a opts)))
  61. ((fboundp a) (setq funcs (cons a funcs)))
  62. (t (setq vars (cons a vars)))))))
  63. (find-file (or eldo-file (read-file-name "Write to file: ")))
  64. (org-mode)
  65. (eldo-write-hooks hks)
  66. (eldo-write-commands cmds)
  67. (eldo-write-options opts)))
  68. (defun eldo-write-hooks (hooks)
  69. "Write hooks documentation in the current buffer."
  70. (insert "* Hooks\n")
  71. (org-set-property "CUSTOM_ID" "hooks")
  72. (dolist (h hooks)
  73. (unless (null (find-lisp-object-file-name h 'defvar))
  74. (insert "\n\n** " (symbol-name h))
  75. (let ((f (file-name-nondirectory (find-lisp-object-file-name h 'defvar)))
  76. (val (replace-regexp-in-string
  77. "\n" "\\\\n"
  78. (prin1-to-string (car (get h 'standard-value)))))
  79. (version (get h 'custom-version))
  80. (d (get h 'variable-documentation)))
  81. (if (> (length val) 30) (setq val (concat (substring val 0 30) "...")))
  82. (insert
  83. " =" val "=\n"
  84. (if version (format "- *Since:* Emacs version %s\n" version) "")
  85. (format (concat "- *In file:* [[" eldo-git-raw-file "][%s]]\n") f f)
  86. (format (concat "- [[" eldo-git-search-string
  87. "][Find modifications in git logs]]\n\n") (symbol-name h)))
  88. (when (stringp d) (insert (eldo-make-verbatim d)))))
  89. (org-set-property "CUSTOM_ID" (symbol-name h))
  90. (goto-char (point-max))))
  91. (defun eldo-write-commands (commands)
  92. "Write commands documentaiton in the current buffer."
  93. (insert "\n* Commands\n")
  94. (org-set-property "CUSTOM_ID" "commands")
  95. (dolist (c commands)
  96. (when (find-lisp-object-file-name c 'defun)
  97. (let ((f (file-name-nondirectory (find-lisp-object-file-name c 'defun)))
  98. (key (mapconcat 'key-description (where-is-internal c eldo-keymaps) ", "))
  99. (args (help-function-arglist c t))
  100. (d (documentation c)))
  101. (insert "\n** " (symbol-name c) (if args (format " =%s=\n" args) "\n"))
  102. (org-set-property "CUSTOM_ID" (symbol-name c))
  103. (insert
  104. (if (and key (not (string= key ""))) (format "\n- *Access:* ~%s~" key) "")
  105. (format (concat "\n- *In file:* [[" eldo-git-raw-file "][%s]]\n") f f)
  106. (format (concat "- [[" eldo-git-search-string
  107. "][Find modifications in git logs]]\n\n") (symbol-name c)))
  108. (when (stringp d) (insert (eldo-make-verbatim d))))
  109. (goto-char (point-max)))))
  110. (defun eldo-write-options (options)
  111. "Write options documentation in the current buffer."
  112. (insert "\n* Options\n")
  113. (org-set-property "CUSTOM_ID" "options")
  114. (dolist (o options)
  115. (when (find-lisp-object-file-name o 'defvar)
  116. (insert "\n\n** " (symbol-name o))
  117. (let ((f (file-name-nondirectory (find-lisp-object-file-name o 'defvar)))
  118. (val (replace-regexp-in-string
  119. "\n" "\\\\n"
  120. (prin1-to-string (car (get o 'standard-value)))))
  121. (version (get o 'custom-version))
  122. (type (prin1-to-string (get o 'custom-type)))
  123. (d (get o 'variable-documentation)))
  124. (if (> (length val) 30) (setq val (concat (substring val 0 30) "...")))
  125. (if (> (length type) 30) (setq type (concat (substring type 0 30) "...")))
  126. (insert
  127. " =" val "=\n\n"
  128. (format "- *Type:* %s\n" type)
  129. (if version (format "- *Since:* Emacs version %s\n" version) "")
  130. (format (concat "- *In file:* [[" eldo-git-raw-file "][%s]]\n") f f)
  131. (format (concat "- [[" eldo-git-search-string
  132. "][Find modifications in git logs]]\n\n") (symbol-name o)))
  133. (when (stringp d) (insert (eldo-make-verbatim d)))))
  134. (org-set-property "CUSTOM_ID" (symbol-name o))
  135. (goto-char (point-max))))
  136. (defun eldo-make-verbatim (string)
  137. "Convert STRING to a verbatim region in Org."
  138. (let ((str (split-string string "\n")))
  139. (mapconcat (lambda(s) (concat ": " s)) str "\n")))