Fix get_dyna_doc CHAR_IO issue sync

[sxemacs] / lisp / info.el

;;; info.el --- info package for SXEmacs.
;; Keywords: help

;; Copyright (C) 1985, 1986, 1993, 1997 Free Software Foundation, Inc.
;; Copyright (C) 2005 Steve Youngs.

;; Author: Dave Gillespie <daveg@synaptics.com>
;;         Richard Stallman <rms@gnu.ai.mit.edu>
;; Maintainer: Dave Gillespie <daveg@synaptics.com>
;; Version: 1.07 of 7/22/93
;; Keywords: docs, help

;; This file is part of SXEmacs.

;; SXEmacs 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.

;; SXEmacs 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 this program.  If not, see <http://www.gnu.org/licenses/>.

;;; Synched up with: Not synched with FSF.

;; Commentary:

;; This is based on an early Emacs 19 info.el file.
;;
;; Note that Info-directory has been replaced by Info-directory-list,
;; a search path of directories in which to find Info files.
;; Also, Info tries adding ".info" to a file name if the name itself
;; is not found.
;;
;; See the change log below for further details.


;; LCD Archive Entry:
;; info-dg|Dave Gillespie|daveg@synaptics.com
;; |Info reader with many enhancements; replaces standard info.el.
;; |93-07-22|1.07|~/modes/info.el

;; Also available from anonymous FTP on csvax.cs.caltech.edu.


;; Change Log:

;; Modified 3/7/1991 by Dave Gillespie:
;; (Author's address: daveg@synaptics.com or daveg@csvax.cs.caltech.edu)
;;
;; Added keys:  i, t, <, >, [, ], {, }, 6, 7, 8, 9, 0.
;; Look at help for info-mode (type ? in Info) for descriptions.
;;
;; If Info-directory-list is undefined and there is no INFOPATH
;; in the environment, use value of Info-directory for compatibility
;; with Emacs 18.57.
;;
;; All files named "localdir" found in the path are appended to "dir",
;; the Info directory.  For this to work, "dir" should contain only
;; one node (Top), and each "localdir" should contain no ^_ or ^L
;; characters.  Generally they will contain only one or several
;; additional lines for the top-level menu.  Note that "dir" is
;; modified in memory each time it is loaded, but not on disk.
;;
;; If "dir" contains a line of the form:  "* Locals:"
;; then the "localdir"s are inserted there instead of at the end.


;; Modified 4/3/1991 by Dave Gillespie:
;;
;; Added Info-mode-hook (suggested by Sebastian Kremer).
;; Also added epoch-info-startup/select-hooks from Simon Spero's info.el.
;;
;; Added automatic decoding of compressed Info files.
;; See documentation for the variable Info-suffix-list.  Default is to
;; run "uncompress" on ".Z" files and "unyabba" on ".Y" files.
;; (See comp.sources.unix v24i073-076 for yabba/unyabba, a free software
;; alternative to compress/uncompress.)
;; Note: "dir" and "localdir" files should not be compressed.
;;
;; Changed variables like Info-enable-edit to be settable by M-x set-variable.
;;
;; Added Info-auto-advance variable.  If t, SPC and DEL will act like
;; } and {, i.e., they advance to the next/previous node if at the end
;; of the buffer.
;;
;; Changed `u' to restore point to most recent location in that node.
;; Added `=' to do this manually at any time.  (Suggested by David Fox).
;;
;; Changed `m' and `0-9' to try interpreting menu name as a file name
;; if not found as a node name.  This allows (dir) menus of the form,
;;     Emacs::          Cool text editor
;; as a shorthand for
;;     Emacs:(emacs).   Cool text editor
;;
;; Enhanced `i' to use line-number information in the index.
;; Added `,' to move among all matches to a previous `i' command.
;;
;; Added `a' (Info-annotate) for adding personal notes to any Info node.
;; Notes are not stored in the actual Info files, but in the user's own
;; ~/.infonotes file.
;;
;; Added Info-footnote-tag, made default be "Ref" instead of "Note".
;;
;; Got mouse-click stuff to work under Emacs version 18.  Check it out!
;; Left and right clicks scroll the Info window.
;; Middle click goes to clicked-on node, e.g., "Next:", a menu, or a note.


;; Modified 6/29/1991 by Dave Gillespie:
;;
;; Renamed epoch-info-startup/select-hooks to Info-startup/select-hook.
;;
;; Made Info-select-node into a command on the `!' key.
;;
;; Added Info-mouse-support user option.
;;
;; Cleaned up the implementation of some routines.
;;
;; Added special treatment of quoted words in annotations:  The `g'
;; command for a nonexistent node name scans for an annotation
;; (in any node of any file) containing that name in quotes:  g foo RET
;; looks for an annotation containing:  "foo"  or:  <<foo>>
;; If found, it goes to that file and node.
;;
;; Added a call to set up Info-directory-list in Info-find-node to
;; work around a bug in GNUS where it calls Info-goto-node before info.
;;
;; Added completion for `g' command (inspired by Richard Kim's infox.el).
;; Completion knows all node names for the current file, and all annotation
;; tags (see above).  It does not complete file names or node names in
;; other files.
;;
;; Added `k' (Info-emacs-key) and `*' (Info-elisp-ref) commands.  You may
;; wish to bind these to global keys outside of Info mode.
;;
;; Allowed localdir files to be full dir-like files; only the menu part
;; of each localdir is copied.  Also, redundant menu items are omitted.
;;
;; Changed Info-history to hold only one entry at a time for each node,
;; and to be circular so that multiple `l's come back again to the most
;; recent node.  Note that the format of Info-history entries has changed,
;; which may interfere with external programs that try to operate on it.
;; (Also inspired by Kim's infox.el).
;;
;; Changed `n', `]', `l', etc. to accept prefix arguments to move several
;; steps at once.  Most accept negative arguments to move oppositely.
;;
;; Changed `?' to bury *Help* buffer afterwards to keep it out of the way.
;;
;; Rearranged `?' key's display to be a little better for new users.
;;
;; Changed `a' to save whole window configuration and restore on C-c C-c.
;;
;; Fixed the bug reported by Bill Reynolds on gnu.emacs.bugs.
;;
;; Changed Info-last to restore window-start as well as cursor position.
;;
;; Changed middle mouse button in space after end of node to do Info-last
;; if we got here by following a cross reference, else do Info-global-next.
;;
;; Added some new mouse bindings: shift-left = Info-global-next,
;; shift-right = Info-global-prev, shift-middle = Info-last.
;;
;; Fixed Info-follow-reference not to make assumptions about length
;; of Info-footnote-tag [Linus Tolke].
;;
;; Changed default for Info-auto-advance mode to be press-twice-for-next-node.
;;
;; Modified x-mouse-ignore to preserve last-command variable, so that
;; press-twice Info-auto-advance mode works with the mouse.


;; Modified 3/4/1992 by Dave Gillespie:
;;
;; Added an "autoload" command to help autoload.el.
;;
;; Changed `*' command to look for file `elisp' as well as for `lispref'.
;;
;; Fixed a bug involving footnote names containing regexp special characters.
;;
;; Fixed a bug in completion during `f' (or `r') command.
;;
;; Added TAB (Info-next-reference), M-TAB, and RET keys to Info mode.
;;
;; Added new bindings, `C-h C-k' for Info-emacs-key and `C-h C-f' for
;; Info-elisp-ref.  These bindings are made when info.el is loaded, and
;; only if those key sequences were previously unbound.  These bindings
;; work at any time, not just when Info is already running.


;; Modified 3/8/1992 by Dave Gillespie:
;;
;; Fixed some long lines that were causing trouble with mailers.


;; Modified 3/9/1992 by Dave Gillespie:
;;
;; Added `C-h C-i' (Info-query).
;;
;; Added Info-novice mode, warns if the user attempts to switch to
;; a different Info file.
;;
;; Fixed a bug that caused problems using compressed Info files
;; and Info-directory-list at the same time.
;;
;; Disabled Info-mouse-support by default if Epoch or Hyperbole is in use.
;;
;; Added an expand-file-name call to Info-find-node to fix a small bug.


;; Modified 5/22/1992 by Dave Gillespie:
;;
;; Added "standalone" operation:  "emacs -f info" runs Emacs specifically
;; for use as an Info browser.  In this mode, the `q' key quits Emacs
;; itself.  Also, "emacs -f info arg" starts in Info file "arg" instead
;; of "dir".
;;
;; Changed to prefer "foo.info" over "foo".  If both exist, "foo" is
;; probably a directory or executable program!
;;
;; Made control-mouse act like regular-mouse does in other buffers.
;; (In most systems, this will be set-cursor for left-mouse, x-cut
;; for right-mouse, and x-paste, which will be an error, for
;; middle-mouse.)
;;
;; Improved prompting and searching for `,' key.
;;
;; Fixed a bug where some "* Menu:" lines disappeared when "dir"
;; contained several nodes.


;; Modified 9/10/1992 by Dave Gillespie:
;;
;; Mixed in support for XEmacs.  Mouse works the same as in
;; the other Emacs versions by default; added Info-lucid-mouse-style
;; variable, which enables mouse operation similar to XEmacs's default.
;;
;; Fixed a bug where RET couldn't understand "* Foo::" if "Foo" was a
;; file name instead of a node name.
;;
;; Added `x' (Info-bookmark), a simple interface to the annotation
;; tags feature.  Added `j' (Info-goto-bookmark), like `g' but only
;; completes bookmarks.
;;
;; Added `<<tag>>' as alternate to `"tag"' in annotations.
;;
;; Added `v' (Info-visit-file), like Info-goto-node but specialized
;; for going to a new Info file (with file name completion).
;;
;; Added recognition of gzip'd ".z" files.


;; Modified 5/9/1993 by Dave Gillespie:
;;
;; Merged in various things from FSF's latest Emacs 19 info.el.

;; Modified 6/2/1993 by Dave Gillespie:
;;
;; Changed to use new suffix ".gz" for gzip files.


;; Modified 7/22/1993 by Dave Gillespie:
;;
;; Changed Info-footnote-tag to "See" instead of "Ref".
;;
;; Extended Info-fontify-node to work with FSF version of Emacs 19.

;; Modified 7/30/1993 by Jamie Zawinski:
;;
;; Commented out the tty and fsf19 mouse support, because why bother.
;; Commented out the politically incorrect version of XEmacs mouse support.
;; Commented out mouse scrolling bindings because the party line on that
;;  is "scrollbars are coming soon."
;; Commented out munging of help-for-help's doc; put it in help.el.
;; Did Info-edit-map the modern XEmacs way.
;; Pruned extra cruft from fontification and mouse handling code.
;; Fixed ASCII-centric bogosity in unreading of events.

;; Modified 8/11/95 by Chuck Thompson:
;;
;; Removed any pretense of ever referencing Info-directory since it
;; wasn't working anyhow.

;; Modified 4/5/97 by Tomasz J. Cholewo:
;;
;; Modified Info-search to use with-caps-disable-folding

;; Modified 6/21/97 by Hrvoje Niksic
;;
;; Fixed up Info-next-reference to work sanely when n < 0.
;; Added S-tab binding.

;; Modified 1997-07-10 by Karl M. Hegbloom
;;
;; Added `Info-minibuffer-history'
;; (also added to defaults in "lisp/utils/savehist.el")
;;  Other changes in main ChangeLog.

;; Modified 1998-03-29 by Oscar Figueiredo
;;
;; Added automatic dir/localdir (re)building capability for directories that
;; contain none or when it has become older than info files in the same
;; directory.

;; Modified 1998-09-23 by Didier Verna <didier@xemacs.org>
;;
;; Use the new macro `with-search-caps-disable-folding'

;; Code:
(eval-when-compile
  (condition-case nil (require 'browse-url) (error nil)))

(defgroup info nil
  "The info package for Emacs."
  :group 'help
  :group 'docs)

(defgroup info-faces nil
  "The faces used by info browser."
  :group 'info
  :group 'faces)


(defcustom Info-inhibit-toolbar nil
  "*Non-nil means don't use the specialized Info toolbar."
  :type 'boolean
  :group 'info)

(defcustom Info-novice nil
  "*Non-nil means to ask for confirmation before switching Info files."
  :type 'boolean
  :group 'info)

(defvar Info-history nil
  "List of info nodes user has visited.
Each element of list is a list (\"(FILENAME)NODENAME\" BUFPOS WINSTART).")

(defvar Info-keeping-history t
  "Non-nil if Info-find-node should modify Info-history.
This is for use only by certain internal Info routines.")

(defvar Info-minibuffer-history nil
  "Minibuffer history for Info.")

(defcustom Info-enable-edit nil
  "*Non-nil means the \\<Info-mode-map>\\[Info-edit] command in Info
can edit the current node.
This is convenient if you want to write info files by hand.
However, we recommend that you not do this.
It is better to write a Texinfo file and generate the Info file from that,
because that gives you a printed manual as well."
  :type 'boolean
  :group 'info)

(defcustom Info-enable-active-nodes t
  "*Non-nil allows Info to execute Lisp code associated with nodes.
The Lisp code is executed when the node is selected."
  :type 'boolean
  :group 'info)

(defcustom Info-restoring-point t
  "*Non-nil means to restore the cursor position when re-entering a node."
  :type 'boolean
  :group 'info)

(defcustom Info-auto-advance 'twice
  "*Control what SPC and DEL do when they can't scroll any further.
If nil, they beep and remain in the current node.
If t, they move to the next node (like Info-global-next/prev).
If anything else, they must be pressed twice to move to the next node."
  :type '(choice (const :tag "off" nil)
                 (const :tag "advance" t)
                 (const :tag "confirm" twice))
  :group 'info)

(defcustom Info-fontify t
  "*Non-nil enables font features in XEmacs.
This variable is ignored unless running under XEmacs."
  :type 'boolean
  :group 'info)

(defcustom Info-additional-search-directory-list nil
  "*List of additional directories to search for Info documentation
files.  These directories are not searched for merging the `dir'
file. An example might be something like:
\"/usr/local/lib/xemacs/packages/lisp/calc/\""
  :type '(repeat directory)
  :group 'info)

(defcustom Info-auto-generate-directory 'if-outdated
  "*When to auto generate an info directory listing.
Possible values are:
nil or `never' never auto-generate a directory listing,
  use any existing `dir' or `localdir' file and ignore info
  directories containing none
`always' auto-generate a directory listing ignoring existing
  `dir' and `localdir' files
`if-missing', the default, auto-generates a directory listing
  if no `dir' or `localdir' file is present.  Otherwise the
  contents of any of these files is used instead.
`if-outdated' auto-generates a directory listing if the `dir'
  and `localdir' are either inexistent or outdated (touched
  less recently than an info file in the same directory)."
  :type '(choice (const :tag "never" never)
                 (const :tag "always" always)
                 (const :tag "if-missing" if-missing)
                 (const :tag "if-outdated" if-outdated))
  :group 'info)

(defcustom Info-save-auto-generated-dir 'never
  "*Whether an auto-generated info directory listing should be saved.
Possible values are:
nil or `never', the default, auto-generated info directory
  information will never be saved.
`always', auto-generated info directory information will be saved to
  a `dir' file in the same directory overwriting it if it exists
`conservative', auto-generated info directory information will be saved
  to a `dir' file in the same directory but the user is asked before
  overwriting any existing file."
  :type '(choice (const :tag "never" never)
                 (const :tag "always" always)
                 (const :tag "conservative" conservative))
  :group 'info)

(defconst Info-emacs-info-file-name "sxemacs.info"
  "The filename of the SXEmacs info for `Info-goto-emacs-command-node'
\(`\\<help-mode-map>\\[Info-goto-emacs-command-node]'\)")

;;;###autoload
(defvar Info-directory-list nil
  "List of directories to search for Info documentation files.

The first directory in this list, the \"dir\" file there will become
the (dir)Top node of the Info documentation tree.

Note: DO NOT use the `customize' interface to change the value of this
variable.  Its value is created dynamically on each startup, depending
on XEmacs packages installed on the system.  If you want to change the
search path, make the needed modifications on the variable's value
from .emacs.  For instance:

    (setq Info-directory-list (cons \"~/info\" Info-directory-list))")

;; This could as well be hard-coded since ${srcdir}/info/dir is in CVS --dv
(defconst Info-localdir-heading-regexp "^Local Packages:$"
  "The menu part of localdir files will be inserted below this topic
heading.")

(defface info-node '((t (:bold t :italic t)))
  "Face used for node links in info."
  :group 'info-faces)

(defface info-xref '((t (:bold t)))
  "Face used for cross-references in info."
  :group 'info-faces)

;; This list is based on Karl Berry-s advice about extensions `info' itself
;; might encounter. --dv
(defcustom Info-suffix-list '(("" . nil)
                              (".info" . nil)
                              (".gz" . "gzip -dc %s")
                              (".info.gz" . "gzip -dc %s")
                              (".z" . "gzip -dc %s")
                              (".info.z" . "gzip -dc %s")
                              (".bz2" . "bzip2 -dc %s")
                              (".info.bz2" . "bzip2 -dc %s")
                              (".Z" . "uncompress -c %s")
                              (".info.Z" . "uncompress -c %s")
                              (".zip" . "unzip -c %s")
                              (".info.zip" . "unzip -c %s")
                              (".y" . "cat %s | unyabba")
                              ("info.y" . "cat %s | unyabba")
                              ;; These ones are for MS-DOS filenames.
                              (".inf" . nil)
                              (".igz" . "gzip -dc %s")
                              (".inz" . "gzip -c %s"))
  "*List of file name suffixes and associated decoding commands.
Each entry should be (SUFFIX . STRING); if STRING contains %s, that is
changed to name of the file to decode, otherwise the file is given to
the command as standard input.  If STRING is nil, no decoding is done."
  :type '(repeat (cons (string :tag "suffix")
                       (choice :tag "command"
                               (const  :tag "none" :value nil)
                               (string :tag ""))))
  :group 'info)

(defcustom Info-footnote-tag "Note"
  "*Symbol that identifies a footnote or cross-reference.
All \"*Note\" references will be changed to use this word instead."
  :type 'string
  :group 'info)

(defvar Info-current-file nil
  "Info file that Info is now looking at, or nil.
This is the name that was specified in Info, not the actual file name.
It doesn't contain directory names or file name extensions added by Info.")

(defvar Info-current-subfile nil
  "Info subfile that is actually in the *info* buffer now,
or nil if current info file is not split into subfiles.")

(defvar Info-current-node nil
  "Name of node that Info is now looking at, or nil.")

(defvar Info-tag-table-marker nil
  "Marker pointing at beginning of current Info file's tag table.
Marker points nowhere if file has no tag table.")

(defvar Info-tag-table-buffer nil)

(defvar Info-current-file-completions nil
  "Cached completion list for current Info file.")

(defvar Info-current-annotation-completions nil
  "Cached completion list for current annotation files.")

(defvar Info-index-alternatives nil
  "List of possible matches for last Info-index command.")

(defvar Info-index-first-alternative nil)

(defcustom Info-annotations-path
  (list
   (paths-construct-path (list user-init-directory "info.notes"))
   (paths-construct-path '("~" ".infonotes"))
   (paths-construct-path '("usr" "lib" "info.notes")
                         (char-to-string directory-sep-char)))
  "*Names of files that contain annotations for different Info nodes.
By convention, the first one should reside in your personal directory.
The last should be a world-writable \"public\" annotations file."
  :type '(repeat file)
  :group 'info)

(defcustom Info-button1-follows-hyperlink nil
  "*Non-nil means mouse button1 click will follow hyperlink."
  :type 'boolean
  :group 'info)

(defvar Info-standalone nil
  "Non-nil if Emacs was started solely as an Info browser.")

(defvar Info-in-cross-reference nil)
(defvar Info-window-configuration nil)

(defvar Info-dir-prologue "-*- Text -*-
This is the file .../info/dir, which contains the topmost node of the
Info hierarchy.  The first time you invoke Info you start off
looking at that node, which is (dir)Top.
\1f
File: dir       Node: Top       This is the top of the INFO tree
  This (the Directory node) gives a menu of major topics.

* Menu: The list of major topics begins on the next line.

")

(defcustom Info-no-description-string "[No description available]"
  "*Description string for info files that have none"
  :type 'string
  :group 'info)

;;;###autoload
(defun info (&optional file)
  "Enter Info, the documentation browser.
Optional argument FILE specifies the file to examine;
the default is the top-level directory of Info.

In interactive use, a prefix argument directs this command
to read a file name from the minibuffer."
  (interactive (if current-prefix-arg
                   (list (read-file-name "Info file name: " nil nil t))))
  (let ((p command-line-args))
    (while p
      (and (string-match "^-[fe]" (car p))
           (equal (nth 1 p) "info")
           (not Info-standalone)
           (setq Info-standalone t)
           (= (length p) 3)
           (not (string-match "^-" (nth 2 p)))
           (setq file (nth 2 p))
           (setq command-line-args-left nil))
      (setq p (cdr p))))
;  (Info-setup-x) ??? What was this going to be?  Can anyone tell karlheg?
  (if file
      (unwind-protect
          (Info-goto-node (concat "(" file ")"))
        (and Info-standalone (info)))
    (if (get-buffer "*info*")
        (switch-to-buffer "*info*")
      (Info-directory))))

;;;###autoload
(defun Info-query (file)
  "Enter Info, the documentation browser.  Prompt for name of Info file."
  (interactive "sInfo topic (default = menu): ")
  (info)
  (if (equal file "")
      (Info-goto-node "(dir)")
    (Info-goto-node (concat "(" file ")"))))

(defun Info-setup-initial ()
  (let ((f Info-annotations-path))
    (while f
      (if (and (file-exists-p (car f)) (not (get-file-buffer (car f))))
          (bury-buffer (find-file-noselect (car f))))
      (setq f (cdr f)))))

;;;###autoload
(defun Info-find-node (filename &optional nodename no-going-back tryfile line)
  "Go to an info node specified as separate FILENAME and NODENAME.
Look for a plausible filename, or if not found then look for URL's and
dispatch to the appropriate fn.  NO-GOING-BACK is non-nil if
recovering from an error in this function; it says do not attempt
further (recursive) error recovery.  TRYFILE is ??"

  (Info-setup-initial)

  (cond
   ;; empty filename is simple case
   ((null filename)
    (Info-find-file-node nil nodename no-going-back tryfile line))
   ;; Convert filename to lower case if not found as specified.
   ;; Expand it, look harder...
   ((let ((fname (substitute-in-file-name filename))
          temp found)
      (let ((dirs (cond
                   ;; If specified name starts with `./', then just try
                   ;; current directory. No point in searching for an absolute
                   ;; file name
                   ((string-match "^\\./" fname)
                    (list default-directory))
                   ((file-name-absolute-p fname)
                    '(nil))
                   (Info-additional-search-directory-list
                    (append Info-directory-list
                            Info-additional-search-directory-list))
                   (t Info-directory-list))))
        ;; Search the directory list for file FNAME.
        (while (and dirs (not found))
          (setq temp (expand-file-name fname (car dirs)))
          (setq found (Info-suffixed-file temp))
          (setq dirs (cdr dirs)))
        (if found
            (progn (setq filename (expand-file-name found))
                   t))))
    (Info-find-file-node filename nodename no-going-back tryfile line))
   ;; Look for a URL.  This pattern is stolen from w3.el to prevent
   ;; loading it if we won't need it.
   ((string-match  (concat #r"^\(wais\|solo\|x-exec\|newspost\|www\|"
                           #r"mailto\|news\|tn3270\|ftp\|http\|file\|"
                           #r"telnet\|gopher\):")
                   filename)
    (if-fboundp 'browse-url
        (browse-url filename)
      (error "Cannot follow URLs in this SXEmacs")))
   (t
    (error "Info file %s does not exist" filename))))

(defun Info-find-file-node (filename nodename
                                     &optional no-going-back tryfile line)
  ;; This is the guts of what was Info-find-node. Whoever wrote this
  ;; should be locked up where they can't do any more harm.

  ;; Go into info buffer.
  (or (eq major-mode 'Info-mode)
      (switch-to-buffer "*info*"))
  (buffer-disable-undo (current-buffer))
  (run-hooks 'Info-startup-hook)
  (or (eq major-mode 'Info-mode)
      (Info-mode))
  (or (null filename)
      (equal Info-current-file filename)
      (not Info-novice)
      (string= "dir" (file-name-nondirectory Info-current-file))
      (if (y-or-n-p
           (format "Leave Info file `%s'? "
                   (file-name-nondirectory Info-current-file)))
          (message "")
        (keyboard-quit)))
  ;; Record the node we are leaving.
  (if (and Info-current-file (not no-going-back))
      (Info-history-add Info-current-file Info-current-node (point)))
  (widen)
  (setq Info-current-node nil
        Info-in-cross-reference nil)
  (unwind-protect
      (progn
        ;; Switch files if necessary
        (or (null filename)
            (equal Info-current-file filename)
            (let ((buffer-read-only nil))
              (setq Info-current-file nil
                    Info-current-subfile nil
                    Info-current-file-completions nil
                    Info-index-alternatives nil
                    buffer-file-name nil
                    buffer-file-truename nil)
              (erase-buffer)
              (if (string= "dir" (file-name-nondirectory filename))
                  (Info-insert-dir)
                (Info-insert-file-contents filename t)
                (setq default-directory (file-name-directory filename)))
              (set-buffer-modified-p nil)
              ;; See whether file has a tag table.  Record the location if yes.
              (set-marker Info-tag-table-marker nil)
              (goto-char (point-max))
              (forward-line -8)
              (or (equal nodename "*")
                  (not (search-forward "\^_\nEnd tag table\n" nil t))
                  (let (pos)
                    ;; We have a tag table.  Find its beginning.
                    ;; Is this an indirect file?
                    (search-backward "\nTag table:\n")
                    (setq pos (point))
                    (if (save-excursion
                          (forward-line 2)
                          (looking-at "(Indirect)\n"))
                        ;; It is indirect.  Copy it to another buffer
                        ;; and record that the tag table is in that buffer.
                          (let ((buf (current-buffer))
                                (m Info-tag-table-marker))
                            (or
                             Info-tag-table-buffer
                             (setq
                              Info-tag-table-buffer
                              (generate-new-buffer " *info tag table*")))
                            (save-excursion
                              (set-buffer Info-tag-table-buffer)
                              (buffer-disable-undo (current-buffer))
                              (setq case-fold-search t)
                              (erase-buffer)
                              (insert-buffer-substring buf)
                              (set-marker m (match-end 0))))
                     (set-marker Info-tag-table-marker pos))))
              (setq Info-current-file
                    (file-name-sans-versions buffer-file-name))))
        (if (equal nodename "*")
            (progn (setq Info-current-node nodename)
                   (Info-set-mode-line)
                   (goto-char (point-min)))
          ;; Search file for a suitable node.
          (let* ((qnode (regexp-quote nodename))
                 (regexp (concat "Node: *" qnode " *[,\t\n\177]"))
                 (guesspos (point-min))
                 (found t))
            ;; First get advice from tag table if file has one.
            ;; Also, if this is an indirect info file,
            ;; read the proper subfile into this buffer.
            (if (marker-position Info-tag-table-marker)
                (let (foun found-mode (m Info-tag-table-marker))
                  (save-excursion
                    (set-buffer (marker-buffer Info-tag-table-marker))
                    (goto-char m)
                    (setq foun (re-search-forward regexp nil t))
                    (if foun
                        (setq guesspos (read (current-buffer))))
                    (setq found-mode major-mode))
                  (if foun
                      ;; If this is an indirect file,
                      ;; determine which file really holds this node
                      ;; and read it in.
                      (if (not (eq major-mode found-mode))
                          (setq guesspos
                                (Info-read-subfile guesspos))))))
            (goto-char (max (point-min) (- guesspos 1000)))
            ;; Now search from our advised position (or from beg of buffer)
            ;; to find the actual node.
            (catch 'foo
              (while (search-forward "\n\^_" nil t)
                (forward-line 1)
                (let ((beg (point)))
                  (forward-line 1)
                  (if (re-search-backward regexp beg t)
                      (throw 'foo t))))
              (setq found nil)
              (let ((bufs (delq nil (mapcar 'get-file-buffer
                                            Info-annotations-path)))
                    (pattern (if (string-match #r"\`<<.*>>\'" qnode) qnode
                               (format "\"%s\"\\|<<%s>>" qnode qnode)))
                    (pat2 (concat #r"------ *File: *\([^ ].*[^ ]\) *Node: "
                                  #r"*\([^ ].*[^ ]\) *Line: *\([0-9]+\)"))
                    (afile nil) anode aline)
                (while (and bufs (not anode))
                  (save-excursion
                    (set-buffer (car bufs))
                    (goto-char (point-min))
                    (if (re-search-forward pattern nil t)
                        (if (re-search-backward pat2 nil t)
                            (setq afile (buffer-substring (match-beginning 1)
                                                          (match-end 1))
                                  anode (buffer-substring (match-beginning 2)
                                                          (match-end 2))
                                  aline (string-to-int
                                         (buffer-substring (match-beginning 3)
                                                           (match-end 3)))))))
                  (setq bufs (cdr bufs)))
                (if anode
                    (Info-find-node afile anode t nil aline)
                  (if tryfile
                      (condition-case nil
                          (Info-find-node nodename "Top" t)
                        (error nil)))))
              (or Info-current-node
                  (error "No such node: %s" nodename)))
            (if found
                (progn
                  (Info-select-node)
                  (goto-char (point-min))
                  (if line (forward-line line)))))))
    ;; If we did not finish finding the specified node,
    ;; go back to the previous one.
    (or Info-current-node no-going-back
        (let ((hist (car Info-history)))
          ;; The following is no longer safe with new Info-history system
          ;; (setq Info-history (cdr Info-history))
          (Info-goto-node (car hist) t)
          (goto-char (+ (point-min) (nth 1 hist)))))))

;; Cache the contents of the (virtual) dir file, once we have merged
;; it for the first time, so we can save time subsequently.
(defvar Info-dir-contents nil)

;; Cache for the directory we decided to use for the default-directory
;; of the merged dir text.
(defvar Info-dir-contents-directory nil)

;; Record the file attributes of all the files from which we
;; constructed Info-dir-contents.
(defvar Info-dir-file-attributes nil)

(defun Info-insert-dir ()
  "Construct the Info directory node by merging the files named
\"dir\" or \"localdir\" from the directories in `Info-directory-list'.
The \"dir\" files will take precedence in cases where both exist.  It
sets the *info* buffer's `default-directory' to the first directory we
actually get any text from."
  (if (and Info-dir-contents Info-dir-file-attributes
           ;; Verify that none of the files we used has changed
           ;; since we used it.
           (eval (cons 'and
                       (mapcar #'(lambda (elt)
                                   (let ((curr (file-attributes (car elt))))
                                     ;; Don't compare the access time.
                                     (if curr (setcar (nthcdr 4 curr) 0))
                                     (setcar (nthcdr 4 (cdr elt)) 0)
                                     (equal (cdr elt) curr)))
                               Info-dir-file-attributes))))
      (insert Info-dir-contents)
    (let ((dirs (reverse Info-directory-list))
          buffers lbuffers buffer others nodes dirs-done)

      (setq Info-dir-file-attributes nil)

      ;; Search the directory list for the directory file.
      (while dirs
        (let ((truename (file-truename (expand-file-name (car dirs)))))
          (or (member truename dirs-done)
              (member (directory-file-name truename) dirs-done)
              ;; Karl Berry recently added the ability all possibilities for
              ;; extension as for normal info files. This code however is
              ;; still unsatisfactory: if one day, we find a compressed dir
              ;; file (which looks possible), we should be able to handle it
              ;; (which means decompress and read it, update it, save and
              ;; recompress it). --dv
              (let ((trials '("dir" "DIR"
                              "dir.info" "DIR.INFO"
                              "dir.inf" "DIR.INF"
                              "localdir" "LOCALDIR"
                              "localdir.info" "LOCALDIR.INFO"
                              "localdir.inf" "LOCALDIR.INF"))
                    buf file attrs)
                (catch 'found
                  (while (setq file (pop trials))
                    (setq file (expand-file-name file truename))
                    (and (setq attrs (file-attributes file))
                         (throw 'found t))))
                (unless file
                  (setq file (expand-file-name "dir" truename)))
                (setq dirs-done
                      (cons truename
                            (cons (directory-file-name truename)
                                  dirs-done)))
                (Info-maybe-update-dir file)
                (setq attrs (file-attributes file))
                (if (or (setq buf (find-buffer-visiting file))
                        attrs)
                    (save-excursion
                      (or buffers
                          (message "Composing main Info directory..."))
                      (set-buffer (or buf
                                      (generate-new-buffer
                                       (if (string-match "localdir" file)
                                           "localdir"
                                         "info dir"))))
                      (if (not buf)
                          (insert-file-contents file))
                      (if (string-match "localdir" (buffer-name))
                          (setq lbuffers (cons (current-buffer) lbuffers))
                        (setq buffers (cons (current-buffer) buffers)))
                      (if attrs
                          (setq Info-dir-file-attributes
                                (cons (cons file attrs)
                                      Info-dir-file-attributes)))))))
          (or (cdr dirs) (setq Info-dir-contents-directory (car dirs)))
          (setq dirs (cdr dirs))))

      ;; ensure that the localdir files are inserted last, and reverse
      ;; the list of them so that when they get pushed in, they appear
      ;; in the same order they got specified in the path, from top to
      ;; bottom.
      (nconc buffers (reverse lbuffers))

      (or buffers
          (error "Can't find the Info directory node"))
      ;; Distinguish the dir file that comes with Emacs from all the
      ;; others.  Yes, that is really what this is supposed to do.
      ;; If it doesn't work, fix it.
      (setq buffer (car buffers)
            ;; reverse it since they are pushed down from the top. the
            ;; `Info-directory-list can be specified in natural order
            ;; this way.
            others (reverse (cdr buffers)))

      ;; Insert the entire original dir file as a start; note that we've
      ;; already saved its default directory to use as the default
      ;; directory for the whole concatenation.
      (insert-buffer buffer)

      ;; Look at each of the other buffers one by one.
      (while others
        (let ((other (car others))
              (info-buffer (current-buffer)))
          (if (string-match "localdir" (buffer-name other))
              (save-excursion
                (set-buffer info-buffer)
                (goto-char (point-max))
                (cond
                 ((re-search-backward "^ *\\* *Locals *: *$" nil t)
                  (delete-region (match-beginning 0) (match-end 0)))
                 ;; look for a line like |Local XEmacs packages:
                 ;; or mismatch on some text ...
                 ((re-search-backward Info-localdir-heading-regexp nil t)
                  ;; This is for people who underline topic headings with
                  ;; equal signs or dashes.
                  (when (save-excursion
                          (forward-line 1)
                          (beginning-of-line)
                          (looking-at "^[ \t]*[-=*]+"))
                    (forward-line 1))
                  (forward-line 1)
                  (beginning-of-line))
                 (t (search-backward "\^L" nil t)))
                ;; Insert menu part of the file
                (let* ((pt (point))
                       (len (length (buffer-string nil nil other))))
                  (insert (buffer-string nil nil other))
                  (goto-char (+ pt len))
                  (save-excursion
                    (goto-char pt)
                    (if (search-forward "* Menu:" (+ pt len) t)
                        (progn
                          (forward-line 1)
                          (delete-region pt (point)))))))
            ;; In each, find all the menus.
            (save-excursion
              (set-buffer other)
              (goto-char (point-min))
              ;; Find each menu, and add an elt to NODES for it.
              (while (re-search-forward "^\\* Menu:" nil t)
                (let (beg nodename end)
                  (forward-line 1)
                  (setq beg (point))
                  (search-backward "\n\^_")
                  (search-forward "Node: ")
                  (setq nodename (Info-following-node-name))
                  (search-forward "\n\^_" nil 'move)
                  (beginning-of-line)
                  (setq end (point))
                  (setq nodes (cons (list nodename other beg end) nodes))))))
          (setq others (cdr others))))

      ;; Add to the main menu a menu item for each other node.
      (re-search-forward "^\\* Menu:" nil t)
      (forward-line 1)
      (let ((menu-items '("top"))
            (nodes nodes)
            (case-fold-search t)
            (end (save-excursion (search-forward "\^_" nil t) (point))))
        (while nodes
          (let ((nodename (car (car nodes))))
            (save-excursion
              (or (member (downcase nodename) menu-items)
                  (re-search-forward (concat "^\\* "
                                             (regexp-quote nodename)
                                             "::")
                                     end t)
                  (progn
                    (insert "* " nodename "::" "\n")
                    (setq menu-items (cons nodename menu-items))))))
          (setq nodes (cdr nodes))))
      ;; Now take each node of each of the other buffers
      ;; and merge it into the main buffer.
      (while nodes
        (let ((nodename (car (car nodes))))
          (goto-char (point-min))
          ;; Find the like-named node in the main buffer.
          (if (re-search-forward (concat "\n\^_.*\n.*Node: "
                                         (regexp-quote nodename)
                                         "[,\n\t]")
                                 nil t)
              (progn
                (search-forward "\n\^_" nil 'move)
                (beginning-of-line)
                (insert "\n"))
            ;; If none exists, add one.
            (goto-char (point-max))
            (insert "\^_\nFile: dir\tNode: " nodename "\n\n* Menu:\n\n"))
          ;; Merge the text from the other buffer's menu
          ;; into the menu in the like-named node in the main buffer.
          (apply 'insert-buffer-substring (cdr (car nodes))))
        (setq nodes (cdr nodes)))
      ;; Kill all the buffers we just made.
      (while buffers
        (kill-buffer (car buffers))
        (setq buffers (cdr buffers)))
      (while lbuffers
        (kill-buffer (car lbuffers))
        (setq lbuffers (cdr lbuffers)))
      (message "Composing main Info directory...done"))
    (setq Info-dir-contents (buffer-string)))
  (setq default-directory (file-name-as-directory Info-dir-contents-directory))
  (setq buffer-file-name (caar Info-dir-file-attributes)
        buffer-file-truename (file-truename buffer-file-name)))

(defmacro Info-directory-files (dir-file &optional all full nosort files-only)
  "Return a list of Info files living in the same directory as DIR-FILE.
This list actually contains the files living in this directory, except for
the dir file itself and the secondary info files (foo-1 foo-2 etc).

If the optional argument ALL is non nil, the secondary info files are also
included in the list.

Please refer to the function `directory-files' for the meaning of the other
optional arguments."
  `(let* ((dir (file-name-directory ,dir-file))
          (all-files (remove ,dir-file (directory-files dir ',full nil ',nosort
                                                        ',files-only))))
     (setq all-files
           (if ,full
               (remove (concat dir ".")
                       (remove (concat dir "..") all-files))
             (remove "."
                     (remove ".." all-files))))
     (if ,all
         all-files
       (let ((suff-match
              (concat "-[0-9]+\\("
                      ;; Extract all known compression suffixes from
                      ;; Info-suffix-list. These suffixes can typically  be
                      ;; found in entries of the form `.info.something'.
                      (let ((suff-list Info-suffix-list)
                            suff regexp)
                        (while (setq suff (pop suff-list))
                          (and (string-match "^\\.info" (car suff))
                               (setq regexp (concat regexp
                                                    (regexp-quote
                                                     (substring
                                                      (car suff) 5))
                                                    (and suff-list "\\|")))))
                        regexp)
                      "\\)?$"))
             info-files file)
         (while (setq file (pop all-files))
           (or (string-match suff-match file)
               (push file info-files)))
         (reverse info-files)
         ))
     ))

(defun Info-maybe-update-dir (file)
  "Rebuild dir or localdir according to `Info-auto-generate-directory'."
  (unless (or (not (file-exists-p (file-name-directory file)))
              (null (Info-directory-files file 'all)))
    (if (not (find-buffer-visiting file))
        (if (not (file-exists-p file))
            (if (or (memq Info-auto-generate-directory
                          '(always if-missing if-outdated)))
                (Info-build-dir-anew (file-name-directory file)))
          (if (or (eq Info-auto-generate-directory 'always)
                  (and (eq Info-auto-generate-directory 'if-outdated)
                       (Info-dir-outdated-p file)))
              (Info-rebuild-dir file))))))

;; Record which *.info files are newer than the dir file
(defvar Info-dir-newer-info-files nil)

(defun Info-dir-outdated-p (file)
  "Return non-nil if dir or localdir is outdated.
dir or localdir are outdated when an info file in the same
directory has been modified more recently."
  (let ((dir-mod-time (nth 5 (file-attributes file)))
        f-mod-time newer)
    (setq Info-dir-newer-info-files nil)
    (mapcar
     #'(lambda (f)
         (prog2
             (setq f-mod-time (nth 5 (file-attributes f)))
             (setq newer (or (> (car f-mod-time) (car dir-mod-time))
                             (and (= (car f-mod-time) (car dir-mod-time))
                                  (> (car (cdr f-mod-time))
                                     (car (cdr dir-mod-time))))))
           (if (and (file-readable-p f) newer)
               (setq Info-dir-newer-info-files
                     (cons f Info-dir-newer-info-files)))))
     (Info-directory-files file nil 'fullname 'nosort t))
    Info-dir-newer-info-files))

(defun Info-extract-dir-entry-from (file)
  "Extract the dir entry from the info FILE.
The dir entry is delimited by the markers `START-INFO-DIR-ENTRY'
and `END-INFO-DIR-ENTRY'."
  (save-excursion
    (set-buffer (get-buffer-create " *Info-tmp*"))
    (when (file-readable-p file)
      (insert-file-contents file nil nil nil t)
      (goto-char (point-min))
      (let (beg)
        (unless (null (re-search-forward "^START-INFO-DIR-ENTRY" nil t))
          (forward-line 1)
          (setq beg (point))
          (unless (null (re-search-forward "^END-INFO-DIR-ENTRY" nil t))
            (goto-char (match-beginning 0))
            (car (Info-parse-dir-entries beg (point)))))))))

;; Parse dir entries contained between START and END into a list of the form
;; (filename topic node (description-line-1 description-line-2 ...))
(defun Info-parse-dir-entries (start end)
  (let (entry entries)
    (save-excursion
      (save-restriction
        (narrow-to-region start end)
        (goto-char start)
        (while (re-search-forward
                (concat #r"^\* \([^:]+\):\("
                        "[ \t]*"
                        #r"(\([^)]*\))\w*\.\|:\)")
                nil t)
          (setq entry (list (match-string 2)
                            (match-string 1)
                            (downcase (or (match-string 3)
                                          (match-string 1)))))
          (setq entry
                (cons (nreverse
                       (cdr
                        (nreverse
                         (split-string
                          (buffer-substring
                           (re-search-forward "[ \t]*" nil t)
                           (or (and (re-search-forward "^[^ \t]" nil t)
                                    (goto-char (match-beginning 0)))
                               (point-max)))
                          "[ \t]*\n[ \t]*"))))
                      entry))
          (setq entries (cons (nreverse entry) entries)))))
    (nreverse entries)))

(defun Info-dump-dir-entries (entries)
  (let ((tab-width 8)
        (description-col 0)
        len)
    (mapcar #'(lambda (e)
                (setq e (cdr e))        ; Drop filename
                (setq len (length (concat (car e)
                                          (car (cdr e)))))
                (if (> len description-col)
                    (setq description-col len)))
            entries)
    (setq description-col (+ 5 description-col))
    (mapcar #'(lambda (e)
                (setq e (cdr e))        ; Drop filename
                (insert "* " (car e) ":" (car (cdr e)))
                (setq e (car (cdr (cdr e))))
                (while e
                  (indent-to-column description-col)
                  (insert (car e) "\n")
                  (setq e (cdr e))))
            entries)
    (insert "\n")))


(defun Info-build-dir-anew (directory)
  "Build info directory information for DIRECTORY.
The generated directory listing may be saved to a `dir' according
to the value of `Info-save-auto-generated-dir'."
  (save-excursion
    (let* ((dirfile (expand-file-name "dir" directory))
           (to-temp (or (null Info-save-auto-generated-dir)
                        (eq Info-save-auto-generated-dir 'never)
                        (and (not (file-writable-p dirfile))
                             (message "File not writable %s. Using temporary."
                                      dirfile))))
           (info-files (Info-directory-files dirfile nil 'fullname nil t)))
      (if to-temp
          (message "Creating temporary dir in %s..." directory)
        (message "Creating %s..." dirfile))
      (set-buffer (find-file-noselect dirfile t))
      (setq buffer-read-only nil)
      (erase-buffer)
      (insert Info-dir-prologue "Info files in " directory ":\n\n")
      (Info-dump-dir-entries
       (mapcar
        #'(lambda (f)
            (or (Info-extract-dir-entry-from f)
                (list 'dummy
                      (progn (string-match #r"\([^.]*\)\(\..*\)?$"
                                           (file-name-nondirectory f))
                             (capitalize
                              (match-string 1 (file-name-nondirectory f))))
                      ":"
                      (list Info-no-description-string))))
        info-files))
      (if to-temp
          (set-buffer-modified-p nil)
        (save-buffer))
      (if to-temp
          (message "Creating temporary dir in %s...done" directory)
        (message "Creating %s...done" dirfile)))))


(defun Info-rebuild-dir (file)
  "Build info directory information in the directory of dir FILE.
Description of info files are merged from the info files in the
directory and the contents of FILE with the description in info files
taking precedence over descriptions in FILE.
The generated directory listing may be saved to a `dir' according to
the value of `Info-save-auto-generated-dir'."
  (save-excursion
    (save-restriction
      (let (dir-section-contents dir-full-contents
            dir-entry
            file-dir-entry
            mark next-section
            not-first-section
            (to-temp
             (or (null Info-save-auto-generated-dir)
                 (eq Info-save-auto-generated-dir 'never)
                 (and (eq Info-save-auto-generated-dir 'always)
                      (not (file-writable-p file))
                      (message "File not writable %s. Using temporary." file))
                 (and (eq Info-save-auto-generated-dir 'conservative)
                      (or (and (not (file-writable-p file))
                               (message
                                "File not writable %s. Using temporary." file))
                          (not (y-or-n-p
                                (message "%s is outdated. Overwrite ? "
                                         file))))))))
        (set-buffer (find-file-noselect file t))
        (setq buffer-read-only nil)
        (if to-temp
            (message "Rebuilding temporary %s..." file)
          (message "Rebuilding %s..." file))
        (catch 'done
          (setq buffer-read-only nil)
          (goto-char (point-min))
          (unless (and (search-forward "\^_")
                       (re-search-forward "^\\* Menu:.*$" nil t)
                       (setq mark (and (re-search-forward "^\\* " nil t)
                                       (match-beginning 0))))
            (throw 'done nil))
          (setq dir-full-contents (Info-parse-dir-entries mark (point-max)))
          (setq next-section (or (and (re-search-forward "^[^* \t].*:[ \t]*$"
                                                         nil t)
                                      (match-beginning 0))
                                 (point-max)))
          (while next-section
            (narrow-to-region mark next-section)
            (setq dir-section-contents (nreverse (Info-parse-dir-entries
                                                  (point-min) (point-max))))
            (mapcar
             #'(lambda (file)
                 (setq dir-entry (assoc (downcase
                                         (file-name-sans-extension
                                          (file-name-nondirectory file)))
                                        dir-section-contents)
                       file-dir-entry (Info-extract-dir-entry-from file))
                 (if dir-entry
                     (if file-dir-entry
                         ;; A dir entry in the info file takes precedence over
                         ;; an existing entry in the dir file
                         (setcdr dir-entry (cdr file-dir-entry)))
                   (unless (or not-first-section
                               (assoc (downcase
                                       (file-name-sans-extension
                                        (file-name-nondirectory file)))
                                      dir-full-contents))
                     (if file-dir-entry
                         (setq dir-section-contents
                               (cons file-dir-entry dir-section-contents))