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