54544
|
1 ;;; info-xref.el --- check external references in an Info document
|
49698
|
2
|
68651
|
3 ;; Copyright (C) 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
|
54544
|
4
|
49698
|
5 ;; Author: Kevin Ryde <user42@zip.com.au>
|
|
6 ;; Keywords: docs
|
54544
|
7
|
|
8 ;; This file is 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 2, or (at your option)
|
|
13 ;; any later version.
|
|
14
|
|
15 ;; GNU Emacs is distributed in the hope that it will be useful,
|
|
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
18 ;; GNU General Public License for more details.
|
|
19
|
|
20 ;; You should have received a copy of the GNU General Public License
|
|
21 ;; along with GNU Emacs; see the file COPYING. If not, write to the
|
64091
|
22 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
|
|
23 ;; Boston, MA 02110-1301, USA.
|
49698
|
24
|
|
25 ;;; Commentary:
|
|
26
|
|
27 ;; This file implements some simple checking of external cross references in
|
|
28 ;; info files, by attempting to visit the nodes specified.
|
|
29 ;;
|
|
30 ;; "makeinfo" checks references internal to a document, but not external
|
|
31 ;; references, which makes it rather easy for mistakes to creep in or node
|
|
32 ;; name changes to go unnoticed. `Info-validate' doesn't check external
|
|
33 ;; references either.
|
|
34 ;;
|
|
35 ;; `M-x info-xref-check' checks one file. When invoked from an Info-mode or
|
|
36 ;; texinfo-mode buffer, the current info file is the default at the prompt.
|
|
37 ;;
|
|
38 ;; `M-x info-xref-check-all' looks at everything in the normal info path.
|
|
39 ;; This might be a lot of files but it's a good way to check the consistency
|
|
40 ;; of the whole system.
|
|
41 ;;
|
|
42 ;; Results are shown in a buffer. The format is a bit rough, but hopefully
|
|
43 ;; there won't be too many problems normally, and correcting them is a
|
|
44 ;; manual process anyway, a case of finding the right spot in the original
|
|
45 ;; .texi and finding what node it ought to point to.
|
|
46 ;;
|
|
47 ;; When a target info file doesn't exist there's clearly no way to validate
|
|
48 ;; node references within it. A message is given for missing target files
|
|
49 ;; (once per source document), it could be simply that the target hasn't
|
|
50 ;; been installed, or it could be a mistake in the reference.
|
|
51 ;;
|
|
52 ;; Indirect info files are understood, just pass the top-level foo.info to
|
|
53 ;; `info-xref-check' and it traverses all sub-files. Compressed info files
|
|
54 ;; are accepted too, as usual for `Info-mode'.
|
|
55 ;;
|
|
56 ;; `info-xref-check-all' is rather permissive in what it considers an info
|
|
57 ;; file. It has to be since info files don't necessarily have a ".info"
|
|
58 ;; suffix (eg. this is usual for the emacs manuals). One consequence of
|
|
59 ;; this is that if for instance there's a source code directory in
|
|
60 ;; `Info-directory-list' then a lot of extraneous files might be read, which
|
|
61 ;; will be time consuming but should be harmless.
|
54543
|
62 ;;
|
|
63 ;; `M-x info-xref-check-all-custom' is a related command, it goes through
|
|
64 ;; all info document references in customizable variables, checking them
|
|
65 ;; like info file cross references.
|
49698
|
66
|
|
67 ;;; Code:
|
|
68
|
|
69 (require 'info)
|
|
70
|
|
71 (defconst info-xref-results-buffer "*info-xref results*"
|
|
72 "Name of the buffer for info-xref results.")
|
|
73
|
|
74 ;;;###autoload
|
|
75 (defun info-xref-check (filename)
|
|
76 "Check external references in FILENAME, an info document."
|
|
77 (interactive
|
|
78 (list
|
|
79 (let* ((default-filename
|
|
80 (cond ((eq major-mode 'Info-mode)
|
|
81 Info-current-file)
|
|
82 ((eq major-mode 'texinfo-mode)
|
|
83 ;; look for @setfilename like makeinfo.el does
|
|
84 (save-excursion
|
|
85 (goto-char (point-min))
|
|
86 (if (re-search-forward
|
|
87 "^@setfilename[ \t]+\\([^ \t\n]+\\)[ \t]*"
|
49729
|
88 (line-beginning-position 100) t)
|
49698
|
89 (expand-file-name (match-string 1)))))))
|
|
90 (prompt (if default-filename
|
|
91 (format "Info file (%s): " default-filename)
|
|
92 "Info file: ")))
|
49729
|
93 (read-file-name prompt nil default-filename t))))
|
49698
|
94 (info-xref-check-list (list filename)))
|
|
95
|
|
96 ;;;###autoload
|
|
97 (defun info-xref-check-all ()
|
|
98 "Check external references in all info documents in the usual path.
|
|
99 The usual path is `Info-directory-list' and `Info-additional-directory-list'."
|
|
100 (interactive)
|
|
101 (info-xref-check-list (info-xref-all-info-files)))
|
|
102
|
|
103 ;; An alternative to trying to get only top-level files here would be to
|
|
104 ;; simply return all files, and have info-xref-check-list not follow
|
|
105 ;; Indirect:. The current way seems a bit nicer though, because it gets the
|
|
106 ;; proper top-level filename into the error messages, and suppresses
|
|
107 ;; duplicate "not available" messages for all subfiles of a single document.
|
|
108
|
|
109 (defun info-xref-all-info-files ()
|
|
110 "Return a list of all available info files.
|
|
111 Only top-level files are returned, subfiles are excluded.
|
|
112
|
|
113 Since info files don't have to have a .info suffix, all files in the
|
|
114 relevant directories are considered, which might mean a lot of extraneous
|
|
115 things are returned if for instance a source code directory is in the path."
|
|
116
|
|
117 (info-initialize) ;; establish Info-directory-list
|
49729
|
118 (apply 'nconc
|
49698
|
119 (mapcar
|
|
120 (lambda (dir)
|
|
121 (let ((result nil))
|
|
122 (dolist (name (directory-files dir t))
|
49729
|
123 (unless (or (file-directory-p name) (info-xref-subfile-p name))
|
|
124 (push name result)))
|
|
125 (nreverse result)))
|
49698
|
126 (append Info-directory-list Info-additional-directory-list))))
|
|
127
|
|
128 (defun info-xref-subfile-p (filename)
|
|
129 "Return t if FILENAME is an info subfile.
|
|
130 If removing the last \"-<NUM>\" from the filename gives a file that exists,
|
|
131 then consider FILENAME a subfile. This is an imperfect test, we probably
|
|
132 should open up the purported top file and see what subfiles it says."
|
|
133 (and (string-match "\\`\\(\\([^-]*-\\)*[^-]*\\)-[0-9]+\\(.*\\)\\'" filename)
|
|
134 (file-exists-p (concat (match-string 1 filename)
|
|
135 (match-string 3 filename)))))
|
|
136
|
|
137
|
|
138 ;; Some dynamic variables are used to share information with sub-functions
|
|
139 ;; below.
|
|
140 ;;
|
65137
|
141 ;; info-xref-filename-header - a heading message for the current top-level
|
|
142 ;; filename, or "" when it's been printed.
|
|
143 ;;
|
|
144 (defvar info-xref-xfile-alist)
|
|
145 ;;
|
|
146 ;; info-xref-good - count of good cross references.
|
|
147 ;;
|
|
148 (defvar info-xref-good)
|
|
149 ;;
|
|
150 ;; info-xref-bad - count of bad cross references.
|
|
151 ;;
|
|
152 (defvar info-xref-bad)
|
|
153 ;;
|
|
154 ;; info-xref-xfile-alist - indexed by "(foo)" with value nil or t according
|
|
155 ;; to whether "(foo)" exists or not. This is used to suppress duplicate
|
|
156 ;; messages about foo not being available. (Duplicates within one
|
|
157 ;; top-level file that is.)
|
|
158 ;;
|
|
159 (defvar info-xref-filename-heading)
|
49698
|
160
|
|
161 (defun info-xref-check-list (filename-list)
|
|
162 "Check external references in info documents in FILENAME-LIST."
|
|
163 (pop-to-buffer info-xref-results-buffer t)
|
|
164 (erase-buffer)
|
|
165 (let ((info-xref-good 0)
|
|
166 (info-xref-bad 0))
|
|
167 (dolist (info-xref-filename filename-list)
|
|
168 (let ((info-xref-filename-heading
|
|
169 (format "In file %s:\n" info-xref-filename))
|
|
170 (info-xref-xfile-alist nil))
|
|
171 (with-temp-message (format "Looking at %s" info-xref-filename)
|
|
172 (with-temp-buffer
|
|
173 (info-insert-file-contents info-xref-filename)
|
|
174 (goto-char (point-min))
|
|
175 (if (re-search-forward "\^_\nIndirect:\n" nil t)
|
|
176 (let ((dir (file-name-directory info-xref-filename)))
|
|
177 (while (looking-at "\\(.*\\): [0-9]+\n")
|
|
178 (let ((subfile (match-string 1)))
|
|
179 (with-temp-buffer
|
|
180 (info-insert-file-contents
|
|
181 (expand-file-name subfile dir))
|
|
182 (info-xref-check-buffer)))
|
|
183 (forward-line)))
|
|
184 (info-xref-check-buffer))))))
|
|
185 (insert (format "done, %d good, %d bad\n" info-xref-good info-xref-bad))))
|
|
186
|
|
187 (defun info-xref-check-buffer ()
|
|
188 "Check external references in the info file in the current buffer.
|
49717
|
189 This should be the raw file contents, not `Info-mode'."
|
49698
|
190 (goto-char (point-min))
|
|
191 (while (re-search-forward
|
54543
|
192 "\\*[Nn]ote[ \n\t]+[^:]*:[ \n\t]+\\(\\(([^)]*)\\)[^.,]+\\)[.,]"
|
49698
|
193 nil t)
|
|
194 (let* ((file (match-string 2))
|
49729
|
195 (node ;; Canonicalize spaces: we could use "[\t\n ]+" but
|
|
196 ;; we try to avoid uselessly replacing " " with " ".
|
|
197 (replace-regexp-in-string "[\t\n][\t\n ]*\\| [\t\n ]+" " "
|
|
198 (match-string 1) t t)))
|
54543
|
199 (if (string-equal "()" file)
|
|
200 (info-xref-output "Empty filename part: %s\n" node)
|
|
201 ;; see if the file exists, if we haven't tried it before
|
|
202 (unless (assoc file info-xref-xfile-alist)
|
|
203 (let ((found (info-xref-goto-node-p file)))
|
|
204 (push (cons file found) info-xref-xfile-alist)
|
|
205 (unless found
|
|
206 (info-xref-output "Not available to check: %s\n" file))))
|
|
207 ;; if the file exists, try the node
|
|
208 (when (cdr (assoc file info-xref-xfile-alist))
|
49698
|
209 (if (info-xref-goto-node-p node)
|
|
210 (setq info-xref-good (1+ info-xref-good))
|
|
211 (setq info-xref-bad (1+ info-xref-bad))
|
54543
|
212 (info-xref-output "No such node: %s\n" node)))))))
|
49698
|
213
|
54543
|
214 (defun info-xref-output (str &rest args)
|
|
215 "Emit a `format'-ed message STR+ARGS to the info-xref output buffer."
|
49698
|
216 (with-current-buffer info-xref-results-buffer
|
54543
|
217 (insert info-xref-filename-heading
|
|
218 (apply 'format str args))
|
|
219 (setq info-xref-filename-heading "")
|
|
220 ;; all this info-xref can be pretty slow, display now so the user can
|
|
221 ;; see some progress
|
|
222 (sit-for 0)))
|
49698
|
223
|
|
224 ;; When asking Info-goto-node to fork, *info* needs to be the current
|
|
225 ;; buffer, otherwise it seems to clone the current buffer but then do the
|
|
226 ;; goto-node in plain *info*.
|
|
227 ;;
|
|
228 ;; We only fork if *info* already exists, if it doesn't then we can create
|
|
229 ;; and destroy just that instead of a new name.
|
|
230 ;;
|
|
231 ;; If Info-goto-node can't find the file, then no new buffer is created. If
|
|
232 ;; it finds the file but not the node, then a buffer is created. Handle
|
|
233 ;; this difference by checking before killing.
|
|
234 ;;
|
|
235 (defun info-xref-goto-node-p (node)
|
49729
|
236 "Return t if it's possible to go to the given NODE."
|
49698
|
237 (let ((oldbuf (current-buffer)))
|
|
238 (save-excursion
|
|
239 (save-window-excursion
|
|
240 (prog1
|
|
241 (condition-case err
|
|
242 (progn
|
|
243 (Info-goto-node node
|
|
244 (when (get-buffer "*info*")
|
|
245 (set-buffer "*info*")
|
|
246 "xref - temporary"))
|
|
247 t)
|
|
248 (error nil))
|
|
249 (unless (equal (current-buffer) oldbuf)
|
|
250 (kill-buffer (current-buffer))))))))
|
|
251
|
54543
|
252 ;;;###autoload
|
|
253 (defun info-xref-check-all-custom ()
|
|
254 "Check info references in all customize groups and variables.
|
|
255 `custom-manual' and `info-link' entries in the `custom-links' list are checked.
|
|
256
|
|
257 `custom-load' autoloads for all symbols are loaded in order to get all the
|
|
258 link information. This will be a lot of lisp packages loaded, and can take
|
|
259 quite a while."
|
|
260
|
|
261 (interactive)
|
|
262 (pop-to-buffer info-xref-results-buffer t)
|
|
263 (erase-buffer)
|
|
264 (let ((info-xref-filename-heading ""))
|
|
265
|
|
266 ;; `custom-load-symbol' is not used, since it quietly ignores errors,
|
|
267 ;; but we want to show them (since they may mean incomplete checking).
|
|
268 ;;
|
|
269 ;; Just one pass through mapatoms is made. There shouldn't be any new
|
|
270 ;; custom-loads setup by packages loaded.
|
|
271 ;;
|
|
272 (info-xref-output "Loading custom-load autoloads ...\n")
|
|
273 (require 'cus-start)
|
|
274 (require 'cus-load)
|
|
275 (let ((viper-mode nil)) ;; tell viper.el not to ask about viperizing
|
|
276 (mapatoms
|
|
277 (lambda (symbol)
|
|
278 (dolist (load (get symbol 'custom-loads))
|
|
279 (cond ((symbolp load)
|
|
280 (condition-case cause (require load)
|
|
281 (error
|
|
282 (info-xref-output "Symbol `%s': cannot require '%s: %s\n"
|
|
283 symbol load cause))))
|
|
284 ;; skip if previously loaded
|
|
285 ((assoc load load-history))
|
|
286 ((assoc (locate-library load) load-history))
|
|
287 (t
|
|
288 (condition-case cause (load load)
|
|
289 (error
|
|
290 (info-xref-output "Symbol `%s': cannot load \"%s\": %s\n"
|
|
291 symbol load cause)))))))))
|
|
292
|
|
293 ;; Don't bother to check whether the info file exists as opposed to just
|
|
294 ;; a missing node. If you have the lisp then you should have the
|
|
295 ;; documentation, so missing node name will be the usual fault.
|
|
296 ;;
|
|
297 (info-xref-output "\nChecking custom-links references ...\n")
|
|
298 (let ((good 0)
|
|
299 (bad 0))
|
|
300 (mapatoms
|
|
301 (lambda (symbol)
|
|
302 (dolist (link (get symbol 'custom-links))
|
|
303 (when (memq (car link) '(custom-manual info-link))
|
|
304 (if (info-xref-goto-node-p (cadr link))
|
|
305 (setq good (1+ good))
|
|
306 (setq bad (1+ bad))
|
|
307 ;; symbol-file gives nil for preloaded variables, would need
|
|
308 ;; to copy what describe-variable does to show the right place
|
|
309 (info-xref-output "Symbol `%s' (in %s): cannot goto node: %s\n"
|
|
310 symbol (symbol-file symbol) (cadr link)))))))
|
|
311 (info-xref-output "%d good, %d bad\n" good bad))))
|
|
312
|
49698
|
313 (provide 'info-xref)
|
|
314
|
52401
|
315 ;;; arch-tag: 69d4d528-69ed-4cc2-8eb4-c666a0c1d5ac
|
49698
|
316 ;;; info-xref.el ends here
|