Several miscellaneous doc changes.
[bpt/emacs.git] / lisp / ido.el
index 4086000..dcaa8f3 100644 (file)
@@ -1,6 +1,6 @@
 ;;; ido.el --- interactively do things with buffers and files
 
-;; Copyright (C) 1996-2011 Free Software Foundation, Inc.
+;; Copyright (C) 1996-2012 Free Software Foundation, Inc.
 
 ;; Author: Kim F. Storm <storm@cua.dk>
 ;; Based on: iswitchb by Stephen Eglen <stephen@cns.ed.ac.uk>
 ;; The highlighting of matching items is controlled via ido-use-faces.
 ;; The faces used are ido-first-match, ido-only-match and
 ;; ido-subdir.
-;; Colouring of the matching item was suggested by
+;; Coloring of the matching item was suggested by
 ;; Carsten Dominik (dominik@strw.leidenuniv.nl).
 
 ;; Replacement for read-buffer and read-file-name
 ;; ifindf package back into iswitchb.
 ;;
 ;; This is basically what ido (interactively do) is all about; but I
-;; found it ackward to merge my changes into the "iswitchb-" namespace,
+;; found it awkward to merge my changes into the "iswitchb-" namespace,
 ;; so I invented a common "ido-" namespace for the merged packages.
 ;;
 ;; This version is based on ido.el version 1.57 released on
@@ -461,12 +461,6 @@ See `ido-default-file-method' for details."
                   (const :tag "Show in other frame" other-frame)
                   (const :tag "Ask to show in other frame" maybe-frame)
                   (const :tag "Raise frame if already shown" raise-frame))
-    :type '(choice (const selected-window)
-                  (const other-window)
-                  (const display)
-                  (const other-frame)
-                  (const maybe-frame)
-                  (const raise-frame))
     :group 'ido)
 
 (defcustom ido-enable-flex-matching nil
@@ -776,7 +770,7 @@ can be completed using TAB,
 (defcustom ido-use-virtual-buffers nil
   "If non-nil, refer to past buffers as well as existing ones.
 Essentially it works as follows: Say you are visiting a file and
-the buffer gets cleaned up by mignight.el.  Later, you want to
+the buffer gets cleaned up by midnight.el.  Later, you want to
 switch to that buffer, but find it's no longer open.  With
 virtual buffers enabled, the buffer name stays in the buffer
 list (using the `ido-virtual' face, and always at the end), and if
@@ -1475,8 +1469,10 @@ Removes badly formatted data and ignored directories."
   (add-hook 'choose-completion-string-functions 'ido-choose-completion-string))
 
 (define-minor-mode ido-everywhere
-  "Toggle using ido-mode everywhere file and directory names are read.
-With ARG, turn ido-mode on if arg is positive, off otherwise."
+  "Toggle use of Ido for all buffer/file reading.
+With a prefix argument ARG, enable this feature if ARG is
+positive, and disable it otherwise.  If called from Lisp, enable
+the mode if ARG is omitted or nil."
   :global t
   :group 'ido
   (when (get 'ido-everywhere 'file)
@@ -1696,7 +1692,7 @@ This function also adds a hook to the minibuffer."
 (defun ido-nonreadable-directory-p (dir)
   ;; Return t if dir is a directory, but not readable
   ;; Do not check for non-readable directories via tramp, as this causes a premature
-  ;; connect on incomplete tramp paths (after entring just method:).
+  ;; connect on incomplete tramp paths (after entering just method:).
   (let ((ido-enable-tramp-completion nil))
     (and (ido-final-slash dir)
         (not (ido-is-unc-host dir))
@@ -1706,7 +1702,7 @@ This function also adds a hook to the minibuffer."
 (defun ido-directory-too-big-p (dir)
   ;; Return t if dir is a directory, but too big to show
   ;; Do not check for non-readable directories via tramp, as this causes a premature
-  ;; connect on incomplete tramp paths (after entring just method:).
+  ;; connect on incomplete tramp paths (after entering just method:).
   (let ((ido-enable-tramp-completion nil))
     (and (numberp ido-max-directory-size)
         (ido-final-slash dir)
@@ -1726,8 +1722,9 @@ This function also adds a hook to the minibuffer."
     (unless (and ido-enable-tramp-completion
                 (string-match "\\`/[^/]*@\\'" dir))
       (setq dir (ido-final-slash dir t))))
-  (if (get-buffer ido-completion-buffer)
-      (kill-buffer ido-completion-buffer))
+  (and ido-completion-buffer
+       (get-buffer ido-completion-buffer)
+       (kill-buffer ido-completion-buffer))
   (cond
    ((equal dir ido-current-directory)
     nil)
@@ -1740,8 +1737,9 @@ This function also adds a hook to the minibuffer."
    (t
     (ido-trace "cd" dir)
     (setq ido-current-directory dir)
-    (if (get-buffer ido-completion-buffer)
-       (kill-buffer ido-completion-buffer))
+    (and ido-completion-buffer
+        (get-buffer ido-completion-buffer)
+        (kill-buffer ido-completion-buffer))
     (setq ido-directory-nonreadable (ido-nonreadable-directory-p dir))
     (setq ido-directory-too-big (and (not ido-directory-nonreadable)
                                     (ido-directory-too-big-p dir)))
@@ -1826,7 +1824,7 @@ This function also adds a hook to the minibuffer."
 ;;       e.g. the file name may be ignored or joined with ido-current-directory, and
 ;;       the relevant function is called (find-file, write-file, etc).
 
-(defun ido-read-internal (item prompt history &optional default require-match initial)
+(defun ido-read-internal (item prompt hist &optional default require-match initial)
   "Perform the `ido-read-buffer' and `ido-read-file-name' functions.
 Return the name of a buffer or file selected.
 PROMPT is the prompt to give to the user.
@@ -1984,10 +1982,11 @@ If INITIAL is non-nil, it specifies the initial input string."
                (read-from-minibuffer (ido-make-prompt item prompt)
                                      (prog1 ido-text-init
                                        (setq ido-text-init nil))
-                                     ido-completion-map nil history))))
+                                     ido-completion-map nil hist))))
       (ido-trace "read-from-minibuffer" ido-final-text)
-      (if (get-buffer ido-completion-buffer)
-         (kill-buffer ido-completion-buffer))
+      (and ido-completion-buffer
+          (get-buffer ido-completion-buffer)
+          (kill-buffer ido-completion-buffer))
 
       (ido-trace "\n_EXIT_" ido-exit)
 
@@ -2155,7 +2154,12 @@ If INITIAL is non-nil, it specifies the initial input string."
 
         (t
          (setq done t))))))
-    (add-to-history (or history 'minibuffer-history) ido-selected)
+    (add-to-history (cond
+                    ((consp hist)
+                     (or (car hist) 'minibuffer-history))
+                    (hist hist)
+                    (t 'minibuffer-history))
+                   ido-selected)
     ido-selected))
 
 (defun ido-edit-input ()
@@ -3151,7 +3155,7 @@ for first matching file."
 ;;; CREATE LIST OF ALL CURRENT FILES
 
 (defun ido-all-completions ()
-  ;; Return unsorted list of all competions.
+  ;; Return unsorted list of all completions.
   (let ((ido-process-ignore-lists nil)
        (ido-directory-too-big nil))
     (cond
@@ -3456,8 +3460,6 @@ This is to make them appear as if they were \"virtual buffers\"."
       (nconc ido-temp-list items)
     (setq ido-temp-list items)))
 
-(declare-function tramp-tramp-file-p "tramp" (name))
-
 (defun ido-file-name-all-completions-1 (dir)
   (cond
    ((ido-nonreadable-directory-p dir) '())
@@ -3465,8 +3467,6 @@ This is to make them appear as if they were \"virtual buffers\"."
    ;; Caller must have done that if necessary.
 
    ((and ido-enable-tramp-completion
-        (or (fboundp 'tramp-completion-mode-p)
-            (require 'tramp nil t))
         (string-match "\\`/[^/]+[:@]\\'" dir))
     ;; Strip method:user@host: part of tramp completions.
     ;; Tramp completions do not include leading slash.
@@ -3479,7 +3479,9 @@ This is to make them appear as if they were \"virtual buffers\"."
                ;; /ftp:user@host:./ => ok
                (and
                 (not (string= "/ftp:" dir))
-                (tramp-tramp-file-p dir)
+                (file-remote-p dir)
+                ;; tramp-ftp-file-name-p is available only when tramp
+                ;; has been loaded.
                 (fboundp 'tramp-ftp-file-name-p)
                 (funcall 'tramp-ftp-file-name-p dir)
                 (string-match ":\\'" dir)
@@ -3838,8 +3840,9 @@ This is to make them appear as if they were \"virtual buffers\"."
 (defun ido-choose-completion-string (choice &rest ignored)
   (when (ido-active)
     ;; Insert the completion into the buffer where completion was requested.
-    (if (get-buffer ido-completion-buffer)
-       (kill-buffer ido-completion-buffer))
+    (and ido-completion-buffer
+        (get-buffer ido-completion-buffer)
+        (kill-buffer ido-completion-buffer))
     (cond
      ((ido-active t) ;; ido-use-merged-list
       (setq ido-current-directory ""
@@ -3858,7 +3861,8 @@ This is to make them appear as if they were \"virtual buffers\"."
   "Show possible completions in a *File Completions* buffer."
   (interactive)
   (setq ido-rescan nil)
-  (let ((temp-buf (get-buffer ido-completion-buffer))
+  (let ((temp-buf (and ido-completion-buffer
+                      (get-buffer ido-completion-buffer)))
        display-it full-list)
     (if (and (eq last-command this-command) temp-buf)
        ;; scroll buffer
@@ -3877,7 +3881,7 @@ This is to make them appear as if they were \"virtual buffers\"."
            (scroll-other-window))
          (set-buffer buf))
       (setq display-it t))
-    (if display-it
+    (if (and ido-completion-buffer display-it)
        (with-output-to-temp-buffer ido-completion-buffer
          (let ((completion-list (sort
                                  (cond
@@ -4149,7 +4153,6 @@ in a separate window.
 \\[ido-toggle-regexp] Toggle regexp searching.
 \\[ido-toggle-prefix] Toggle between substring and prefix matching.
 \\[ido-toggle-case] Toggle case-sensitive searching of file names.
-\\[ido-toggle-vc] Toggle version control for this file.
 \\[ido-toggle-literal] Toggle literal reading of this file.
 \\[ido-completion-help] Show list of matching files in separate window.
 \\[ido-toggle-ignore] Toggle ignoring files listed in `ido-ignore-files'."