Mercurial > emacs
annotate lisp/info-xref.el @ 51708:380202c09939
*** empty log message ***
author | Luc Teirlinck <teirllm@auburn.edu> |
---|---|
date | Wed, 02 Jul 2003 00:53:46 +0000 |
parents | f3c2ee28113b |
children | 695cf19ef79e d7ddb3e565de |
rev | line source |
---|---|
49698 | 1 ;;; info-xref.el --- check external references in an Info document. |
2 | |
3 ;; Copyright 2003 Free Software Foundation, Inc | |
4 ;; | |
5 ;; Author: Kevin Ryde <user42@zip.com.au> | |
6 ;; Keywords: docs | |
7 ;; | |
8 ;; info-xref.el is free software; you can redistribute it and/or modify | |
9 ;; it under the terms of the GNU General Public License as published by the | |
10 ;; Free Software Foundation; either version 2, or (at your option) any later | |
11 ;; version. | |
12 ;; | |
13 ;; info-xref.el is distributed in the hope that it will be useful, but | |
14 ;; WITHOUT ANY WARRANTY; without even the implied warranty of | |
15 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General | |
16 ;; Public License for more details. | |
17 ;; | |
18 ;; You can get a copy of the GNU General Public License online at | |
19 ;; http://www.gnu.org/licenses/gpl.txt, or you should have one in the file | |
20 ;; COPYING which comes with GNU Emacs and other GNU programs. Failing that, | |
21 ;; write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, | |
22 ;; Boston, MA 02111-1307, USA. | |
23 | |
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. | |
62 | |
63 | |
64 ;;; Install: | |
65 | |
66 ;; Put info-xref.el somewhere in your `load-path', and in your .emacs put | |
67 ;; | |
68 ;; (autoload 'info-xref-check "info-xref" nil t) | |
69 ;; (autoload 'info-xref-check-all "info-xref" nil t) | |
70 ;; | |
71 ;; then | |
72 ;; | |
73 ;; M-x info-xref-check | |
74 ;; | |
75 ;; and enter an info file name. | |
76 | |
77 | |
78 ;;; Emacsen: | |
79 | |
80 ;; Designed for use with GNU Emacs 21. | |
81 | |
82 | |
83 ;;; History: | |
84 | |
85 ;; Version 1 - the first version. | |
86 | |
87 | |
88 ;;; Code: | |
89 | |
90 (require 'info) | |
91 | |
92 (defconst info-xref-results-buffer "*info-xref results*" | |
93 "Name of the buffer for info-xref results.") | |
94 | |
95 ;;;###autoload | |
96 (defun info-xref-check (filename) | |
97 "Check external references in FILENAME, an info document." | |
98 (interactive | |
99 (list | |
100 (let* ((default-filename | |
101 (cond ((eq major-mode 'Info-mode) | |
102 Info-current-file) | |
103 ((eq major-mode 'texinfo-mode) | |
104 ;; look for @setfilename like makeinfo.el does | |
105 (save-excursion | |
106 (goto-char (point-min)) | |
107 (if (re-search-forward | |
108 "^@setfilename[ \t]+\\([^ \t\n]+\\)[ \t]*" | |
49729
f3c2ee28113b
(info-xref-check): Use line-beginning-position.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
49717
diff
changeset
|
109 (line-beginning-position 100) t) |
49698 | 110 (expand-file-name (match-string 1))))))) |
111 (prompt (if default-filename | |
112 (format "Info file (%s): " default-filename) | |
113 "Info file: "))) | |
49729
f3c2ee28113b
(info-xref-check): Use line-beginning-position.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
49717
diff
changeset
|
114 (read-file-name prompt nil default-filename t)))) |
49698 | 115 (info-xref-check-list (list filename))) |
116 | |
117 ;;;###autoload | |
118 (defun info-xref-check-all () | |
119 "Check external references in all info documents in the usual path. | |
120 The usual path is `Info-directory-list' and `Info-additional-directory-list'." | |
121 (interactive) | |
122 (info-xref-check-list (info-xref-all-info-files))) | |
123 | |
124 ;; An alternative to trying to get only top-level files here would be to | |
125 ;; simply return all files, and have info-xref-check-list not follow | |
126 ;; Indirect:. The current way seems a bit nicer though, because it gets the | |
127 ;; proper top-level filename into the error messages, and suppresses | |
128 ;; duplicate "not available" messages for all subfiles of a single document. | |
129 | |
130 (defun info-xref-all-info-files () | |
131 "Return a list of all available info files. | |
132 Only top-level files are returned, subfiles are excluded. | |
133 | |
134 Since info files don't have to have a .info suffix, all files in the | |
135 relevant directories are considered, which might mean a lot of extraneous | |
136 things are returned if for instance a source code directory is in the path." | |
137 | |
138 (info-initialize) ;; establish Info-directory-list | |
49729
f3c2ee28113b
(info-xref-check): Use line-beginning-position.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
49717
diff
changeset
|
139 (apply 'nconc |
49698 | 140 (mapcar |
141 (lambda (dir) | |
142 (let ((result nil)) | |
143 (dolist (name (directory-files dir t)) | |
49729
f3c2ee28113b
(info-xref-check): Use line-beginning-position.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
49717
diff
changeset
|
144 (unless (or (file-directory-p name) (info-xref-subfile-p name)) |
f3c2ee28113b
(info-xref-check): Use line-beginning-position.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
49717
diff
changeset
|
145 (push name result))) |
f3c2ee28113b
(info-xref-check): Use line-beginning-position.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
49717
diff
changeset
|
146 (nreverse result))) |
49698 | 147 (append Info-directory-list Info-additional-directory-list)))) |
148 | |
149 (defun info-xref-subfile-p (filename) | |
150 "Return t if FILENAME is an info subfile. | |
151 If removing the last \"-<NUM>\" from the filename gives a file that exists, | |
152 then consider FILENAME a subfile. This is an imperfect test, we probably | |
153 should open up the purported top file and see what subfiles it says." | |
154 (and (string-match "\\`\\(\\([^-]*-\\)*[^-]*\\)-[0-9]+\\(.*\\)\\'" filename) | |
155 (file-exists-p (concat (match-string 1 filename) | |
156 (match-string 3 filename))))) | |
157 | |
158 | |
159 ;; Some dynamic variables are used to share information with sub-functions | |
160 ;; below. | |
161 ;; | |
162 ;; info-xref-filename - current top-level filename, eg. /usr/info/foo.info.gz | |
163 ;; | |
164 ;; info-xref-filename-header - a heading message for the current top-level | |
165 ;; filename, or "" when it's been printed. | |
166 ;; | |
167 ;; info-xref-good - count of good cross references. | |
168 ;; | |
169 ;; info-xref-bad - count of bad cross references. | |
170 ;; | |
171 ;; info-xref-xfile-alist - indexed by "(foo)" with value nil or t according | |
172 ;; to whether "(foo)" exists or not. This is used to suppress duplicate | |
173 ;; messages about foo not being available. (Duplicates within one | |
174 ;; top-level file that is.) | |
175 | |
176 (defun info-xref-check-list (filename-list) | |
177 "Check external references in info documents in FILENAME-LIST." | |
178 (pop-to-buffer info-xref-results-buffer t) | |
179 (erase-buffer) | |
180 (let ((info-xref-good 0) | |
181 (info-xref-bad 0)) | |
182 (dolist (info-xref-filename filename-list) | |
183 (let ((info-xref-filename-heading | |
184 (format "In file %s:\n" info-xref-filename)) | |
185 (info-xref-xfile-alist nil)) | |
186 (with-temp-message (format "Looking at %s" info-xref-filename) | |
187 (with-temp-buffer | |
188 (info-insert-file-contents info-xref-filename) | |
189 (goto-char (point-min)) | |
190 (if (re-search-forward "\^_\nIndirect:\n" nil t) | |
191 (let ((dir (file-name-directory info-xref-filename))) | |
192 (while (looking-at "\\(.*\\): [0-9]+\n") | |
193 (let ((subfile (match-string 1))) | |
194 (with-temp-buffer | |
195 (info-insert-file-contents | |
196 (expand-file-name subfile dir)) | |
197 (info-xref-check-buffer))) | |
198 (forward-line))) | |
199 (info-xref-check-buffer)))))) | |
200 (insert (format "done, %d good, %d bad\n" info-xref-good info-xref-bad)))) | |
201 | |
202 (defun info-xref-check-buffer () | |
203 "Check external references in the info file in the current buffer. | |
49717
ecb17cef5c44
(info-xref-check-buffer): Fix typo.
Juanma Barranquero <lekktu@gmail.com>
parents:
49698
diff
changeset
|
204 This should be the raw file contents, not `Info-mode'." |
49698 | 205 (goto-char (point-min)) |
206 (while (re-search-forward | |
207 "\\*[Nn]ote[ \n\t]+[^:]*:[ \n\t]+\\(\\(([^)]+)\\)[^.,]+\\)[.,]" | |
208 nil t) | |
209 (let* ((file (match-string 2)) | |
49729
f3c2ee28113b
(info-xref-check): Use line-beginning-position.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
49717
diff
changeset
|
210 (node ;; Canonicalize spaces: we could use "[\t\n ]+" but |
f3c2ee28113b
(info-xref-check): Use line-beginning-position.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
49717
diff
changeset
|
211 ;; we try to avoid uselessly replacing " " with " ". |
f3c2ee28113b
(info-xref-check): Use line-beginning-position.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
49717
diff
changeset
|
212 (replace-regexp-in-string "[\t\n][\t\n ]*\\| [\t\n ]+" " " |
f3c2ee28113b
(info-xref-check): Use line-beginning-position.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
49717
diff
changeset
|
213 (match-string 1) t t))) |
49698 | 214 ;; see if the file exists, if we haven't tried it before |
215 (unless (assoc file info-xref-xfile-alist) | |
216 (let ((found (info-xref-goto-node-p file))) | |
49729
f3c2ee28113b
(info-xref-check): Use line-beginning-position.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
49717
diff
changeset
|
217 (push (cons file found) info-xref-xfile-alist) |
f3c2ee28113b
(info-xref-check): Use line-beginning-position.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
49717
diff
changeset
|
218 (unless found |
f3c2ee28113b
(info-xref-check): Use line-beginning-position.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
49717
diff
changeset
|
219 (info-xref-output (format "Not available to check: %s\n" file))))) |
49698 | 220 ;; if the file exists, try the node, if we haven't before |
221 (when (cdr (assoc file info-xref-xfile-alist)) | |
222 (unless (assoc node info-xref-xfile-alist) | |
223 (if (info-xref-goto-node-p node) | |
224 (setq info-xref-good (1+ info-xref-good)) | |
225 (setq info-xref-bad (1+ info-xref-bad)) | |
226 (info-xref-output (format "No such node: %s\n" node)))))))) | |
227 | |
228 (defun info-xref-output (str) | |
229 "Emit STR as an info-xref result message." | |
230 (with-current-buffer info-xref-results-buffer | |
49729
f3c2ee28113b
(info-xref-check): Use line-beginning-position.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
49717
diff
changeset
|
231 (insert info-xref-filename-heading str) |
f3c2ee28113b
(info-xref-check): Use line-beginning-position.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
49717
diff
changeset
|
232 (setq info-xref-filename-heading ""))) |
49698 | 233 |
234 ;; When asking Info-goto-node to fork, *info* needs to be the current | |
235 ;; buffer, otherwise it seems to clone the current buffer but then do the | |
236 ;; goto-node in plain *info*. | |
237 ;; | |
238 ;; We only fork if *info* already exists, if it doesn't then we can create | |
239 ;; and destroy just that instead of a new name. | |
240 ;; | |
241 ;; If Info-goto-node can't find the file, then no new buffer is created. If | |
242 ;; it finds the file but not the node, then a buffer is created. Handle | |
243 ;; this difference by checking before killing. | |
244 ;; | |
245 (defun info-xref-goto-node-p (node) | |
49729
f3c2ee28113b
(info-xref-check): Use line-beginning-position.
Stefan Monnier <monnier@iro.umontreal.ca>
parents:
49717
diff
changeset
|
246 "Return t if it's possible to go to the given NODE." |
49698 | 247 (let ((oldbuf (current-buffer))) |
248 (save-excursion | |
249 (save-window-excursion | |
250 (prog1 | |
251 (condition-case err | |
252 (progn | |
253 (Info-goto-node node | |
254 (when (get-buffer "*info*") | |
255 (set-buffer "*info*") | |
256 "xref - temporary")) | |
257 t) | |
258 (error nil)) | |
259 (unless (equal (current-buffer) oldbuf) | |
260 (kill-buffer (current-buffer)))))))) | |
261 | |
262 (provide 'info-xref) | |
263 | |
264 ;;; info-xref.el ends here |