lisp/info-xref.el

   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]*"
 109                            (line-beginning-position 100) t)
 110                           (expand-file-name (match-string 1)))))))
 111            (prompt (if default-filename
 112                        (format "Info file (%s): " default-filename)
 113                      "Info file: ")))
 114       (read-file-name prompt nil default-filename t))))
 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
 139   (apply 'nconc
 140          (mapcar
 141           (lambda (dir)
 142             (let ((result nil))
 143               (dolist (name (directory-files dir t))
 144                 (unless (or (file-directory-p name) (info-xref-subfile-p name))
 145                   (push name result)))
 146               (nreverse result)))
 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.
 204 This should be the raw file contents, not `Info-mode'."
 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))
 210            (node ;; Canonicalize spaces: we could use "[\t\n ]+" but
 211             ;; we try to avoid uselessly replacing " " with " ".
 212             (replace-regexp-in-string "[\t\n][\t\n ]*\\| [\t\n ]+" " "
 213                                       (match-string 1) t t)))
 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)))
 217           (push (cons file found) info-xref-xfile-alist)
 218           (unless found
 219             (info-xref-output (format "Not available to check: %s\n" file)))))
 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
 231     (insert info-xref-filename-heading str)
 232     (setq info-xref-filename-heading "")))
 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)
 246   "Return t if it's possible to go to the given NODE."
 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