cgit.sxemacs.org Git - packages/blob - xemacs-packages/dired/dired-help.el

   1 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
   2 ;;
   3 ;; File:          dired-help.el
   4 ;; Dired Version: 7.17
   5 ;; RCS:
   6 ;; Description:   Obtaining help for dired
   7 ;; Modified:      Sun Nov 20 21:10:47 1994 by sandy on gandalf
   8 ;;
   9 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  10
  11 ;;; Requirements and provisions
  12 (provide 'dired-help)
  13 (require 'dired)
  14 (autoload 'reporter-submit-bug-report "reporter")
  15 (defvar reporter-version) ; For the byte-compiler.
  16
  17 ;;; Constants
  18
  19 (defconst dired-bug-address "elisp-code-dired@nongnu.org")
  20
  21 (defvar dired-documentation nil)
  22
  23 ;;; Functions
  24
  25 (defun dired-documentation ()
  26   (or dired-documentation
  27       (let ((18-p (string-equal "18." (substring emacs-version 0 3)))
  28             (var-help-key (substitute-command-keys
  29                            (if (featurep 'ehelp)
  30                                "\\[electric-describe-variable]"
  31                              "\\[describe-variable]")))
  32             (standard-output (get-buffer-create " dired-help-temp")))
  33         (save-excursion
  34           (set-buffer standard-output)
  35           (unwind-protect
  36               (setq dired-documentation
  37                     (substitute-command-keys
  38                      (format "\\<dired-mode-map>The Directory Editor:
  39
  40 For more detailed help, type \\[universal-argument] \\[dired-describe-mode] to start the info
  41 documentation browser.
  42
  43 In dired, you can edit a list of the files in a directory \(and optionally
  44 its subdirectories in the `ls -lR' format\).
  45
  46 Editing a directory means that you can visit, rename, copy, compress,
  47 load, byte-compile  files.  You can change files' attributes, run shell
  48 commands on files, or insert subdirectories into the edit buffer.  You can
  49 \"flag\" files for deletion or \"mark\" files for later commands, either one
  50 file at a time or by all files matching certain criteria \(e.g., files that
  51 match a certain regexp\).
  52
  53 You move throughout the buffer using the usual cursor motion commands.
  54 Letters no longer insert themselves, but execute commands instead.  The
  55 digits (0-9) are prefix arguments.
  56
  57 Most commands operate either on all marked files or on the current file if
  58 no files are marked.  Use a numeric prefix argument to operate on the next
  59 ARG files (or previous ARG if ARG < 0).  Use the prefix argument `1' to
  60 operate on the current file only.  Prefix arguments override marks. Commands
  61 which run a sub-process on a group of files will display a list of files
  62 for which the sub-process failed.  Typing \\[dired-why] will try to tell
  63 you what went wrong.
  64
  65 When editing several directories in one buffer, each directory acts as a
  66 page, so \\[backward-page] and \\[forward-page] can be used to move between directories.
  67
  68 Summary of commands:
  69
  70 Motion Commands
  71       move up to previous line                             \\[dired-previous-line]
  72       move down to next line                               \\[dired-next-line]
  73       move up to previous directory line                   \\[dired-prev-dirline]
  74       move down to next directory line                     \\[dired-next-dirline]
  75       move up to previous subdirectory                     \\[dired-advertised-prev-subdir]
  76       move down to next subdirectory                       \\[dired-advertised-next-subdir]
  77       move to parent directory                             \\[dired-up-directory]
  78       move to first child subdirectory                     \\[dired-down-directory]
  79
  80 Immediate Actions on Files
  81       visit current file                                   \\[dired-advertised-find-file]
  82       visit current file in other window                   \\[dired-find-file-other-window]
  83       visit current file in other frame               %s
  84       display current file                                 \\[universal-argument] \\[dired-find-file-other-window]
  85       create a new subdirectory                            \\[dired-create-directory]
  86       recover file from auto-save                          \\[dired-recover-file]
  87
  88 Marking & Unmarking Files
  89       mark a file or subdirectory for later commands       \\[dired-mark]
  90       unmark a file or all files of a subdirectory         \\[dired-unmark]
  91       unmark all marked files in a buffer                  \\[dired-unmark-all-files]
  92       count marks in buffer                                0 \\[dired-unmark-all-files]
  93       mark all directories                                 \\[dired-mark-directories]
  94       mark all executable files                            \\[dired-mark-executables]
  95       mark file names matching a regular expression        \\[dired-mark-files-regexp]
  96
  97 Commands on Files Marked or Specified by the Prefix
  98       rename a file or move files to another directory     \\[dired-do-rename]
  99       copy files                                           \\[dired-do-copy]
 100       delete marked (as opposed to flagged) files          \\[dired-do-delete]
 101       compress or uncompress files                         \\[dired-do-compress]
 102       uuencode or uudecode files                           \\[dired-do-uucode]
 103       grep files                                           \\[dired-do-grep]
 104       search for regular expression                        \\[dired-do-tags-search]
 105       query replace by regular expression                  \\[dired-do-tags-query-replace]
 106       byte-compile files                                   \\[dired-do-byte-compile]
 107       load files                                           \\[dired-do-load]
 108       shell command on files                               \\[dired-do-shell-command]
 109       operate shell command separately on each file        \\[universal-argument] \\[dired-do-shell-command]
 110       do as above, but in each file's directory            \\[universal-argument] \\[universal-argument] \\[dired-do-shell-command]
 111
 112 Flagging Files for Deletion (unmark commands remove delete flags)
 113       flag file for deletion                               \\[dired-flag-file-deletion]
 114       backup and remove deletion flag                      \\[dired-backup-unflag]
 115       flag all backup files (file names ending in ~)       \\[dired-flag-backup-files]
 116       flag all auto-save files                             \\[dired-flag-auto-save-files]
 117       clean directory of numeric backups                   \\[dired-clean-directory]
 118       execute the deletions requested (flagged files)      \\[dired-expunge-deletions]
 119
 120 Modifying the Dired Buffer
 121       insert a subdirectory in this buffer                 \\[dired-maybe-insert-subdir]
 122       removing a subdir listing                            \\[dired-kill-subdir]
 123       relist single file, marked files, or subdir          \\[dired-do-redisplay]
 124       re-read all directories (retains all marks)          \\[revert-buffer]
 125       toggle sorting of current subdir by name/date        \\[dired-sort-toggle-or-edit]
 126       report on current ls switches                        0 \\[dired-sort-toggle-or-edit]
 127       edit ls switches for current subdir                  1 \\[dired-sort-toggle-or-edit]
 128       edit default ls switches for new subdirs             2 \\[dired-sort-toggle-or-edit]
 129       sort all subdirs by name/date                        \\[universal-argument] \\[dired-sort-toggle-or-edit]
 130       edit the ls switches for all subdirs                 \\[universal-argument] \\[universal-argument] \\[dired-sort-toggle-or-edit]
 131
 132 Hiding File Lines
 133       toggle file omission in current subdir               \\[dired-omit-toggle]
 134       kill marked file lines                               \\[dired-do-kill-file-lines]
 135
 136 Help on Dired
 137       dired help (what you're reading)                     \\[dired-describe-mode]
 138       dired summary (short help)                           \\[dired-summary]
 139       dired info (full dired info manual)                  \\[universal-argument] \\[dired-describe-mode]
 140       apropos for dired commands                           \\[dired-apropos]
 141       apropos for dired variables                          \\[universal-argument] \\[dired-apropos]
 142
 143 Regular Expression Commands
 144       mark files with a regular expression                 \\[dired-mark-files-regexp]
 145       copy marked files by regexp                          \\[dired-do-copy-regexp]
 146       rename marked files by regexp                        \\[dired-do-rename-regexp]
 147       omit files by regexp                                 \\[dired-omit-expunge]
 148       downcase file names (rename to lowercase)            \\[dired-downcase]
 149       upcase files names (rename to uppercase)             \\[dired-upcase]
 150
 151 Comparing Files
 152       diff file at point with file at mark                 \\[dired-diff]
 153       diff file with its backup                            \\[dired-backup-diff]
 154       merge file at point with file at mark                \\[dired-emerge]
 155       same as above but use a common ancestor              \\[dired-emerge-with-ancestor]
 156       ediff file at point with file at mark                \\[dired-ediff]
 157       patch file at point                                  \\[dired-epatch]
 158
 159 Mouse Commands
 160 %s
 161
 162 Miscellaneous
 163       quit dired                                           \\[dired-quit]
 164       insert current directory in minibuffer               \\[dired-get-target-directory]
 165
 166 If the dired buffer gets confused, you can either type \\[revert-buffer] to read all
 167 directories again, type \\[dired-do-redisplay] to relist a single file, the marked
 168 files, or a subdirectory, or type \\[dired-build-subdir-alist] to parse
 169 the directory tree in the buffer again.
 170
 171 Customization Variables:
 172 Use %s to obtain more information.
 173
 174 %s
 175
 176 Hook Variables:
 177 Use %s to obtain more information.
 178
 179 %s
 180
 181 Keybindings:
 182 \\{dired-mode-map}"
 183
 184                              ;; arguments to format
 185                              (if 18-p
 186                                  "Unavailable in Emacs 18"
 187                                "     \\[dired-find-file-other-frame]")
 188                              (if 18-p
 189                                  "      Unavailable in Emacs 18"
 190                                "\
 191       find file with mouse                                 \\[dired-mouse-find-file]
 192       mark file at mouse                                   \\[dired-mouse-mark]
 193       flag for deletion file at mouse                      \\[dired-mouse-flag]
 194       menu of commands to visit a file                     \\[dired-visit-popup-menu]
 195       menu of operations to do on a file                   \\[dired-do-popup-menu]
 196       insert directory of mouse in minibuffer              \\[dired-mouse-get-target]
 197 ")
 198                              var-help-key
 199                              (progn
 200                                (erase-buffer)
 201                                (dired-format-columns-of-files
 202                                 (sort
 203                                  (all-completions
 204                                   "dired-" obarray
 205                                   (function
 206                                    (lambda (sym)
 207                                      (and (user-variable-p sym)
 208                                           (not (dired-hook-variable-p
 209                                                 sym))))))
 210                                  'string<) t)
 211                                (buffer-string))
 212                              var-help-key
 213                              (progn
 214                                (erase-buffer)
 215                                (dired-format-columns-of-files
 216                                 (sort
 217                                  (all-completions
 218                                   "dired-" obarray
 219                                   (function
 220                                    (lambda (sym)
 221                                      (dired-hook-variable-p sym))))
 222                                  'string<) t)
 223                                (buffer-string)))))
 224             (kill-buffer " dired-help-temp"))))))
 225
 226 ;;; Commands
 227
 228 ;;;###autoload
 229 (defun dired-describe-mode (&optional info)
 230   "Detailed description of dired mode.
 231 With a prefix, runs the info documentation browser for dired."
 232   (interactive "P")
 233   ;; Getting dired documentation can be a bit slow.
 234   (if info
 235       (info "dired")
 236     (message "Building dired help...")
 237     (let* ((buff (get-buffer-create "*Help*"))
 238            (standard-output buff)
 239            (mess (dired-documentation)))
 240       (message "Building dired help... done")
 241       (if (featurep 'ehelp)
 242           (with-electric-help
 243            (function
 244             (lambda ()
 245               (princ mess)
 246               nil))) ; return nil so ehelp puts us at the top of the buffer.
 247         (with-output-to-temp-buffer (buffer-name buff)
 248           (princ mess)
 249           (print-help-return-message))))))
 250
 251 ;;;###autoload
 252 (defun dired-apropos (string &optional var-p)
 253   "Does command apropos for dired commands.
 254 With prefix does apropos for dired variables."
 255   (interactive
 256    (list
 257     (if current-prefix-arg
 258         (read-string "Dired variable apropos (regexp): ")
 259       (read-string "Dired command apropos (regexp): "))
 260     current-prefix-arg))
 261   (message "Doing dired %s apropos..." (if var-p "variable" "command"))
 262   (if (featurep 'ehelp)
 263       (with-electric-help
 264        (function
 265         (lambda ()
 266           (dired-apropos-internal string var-p)
 267           nil)))
 268     (with-output-to-temp-buffer "*Help*"
 269       (dired-apropos-internal string var-p)
 270       (or (print-help-return-message)
 271           (message "Doing dired %s apropos...done"
 272                    (if var-p "variable" "command"))))))
 273
 274 (defun dired-apropos-internal (string &optional var-p)
 275   (let ((case-fold-search t)
 276         (names (sort (all-completions "dired-" obarray
 277                                       (if var-p
 278                                           'user-variable-p
 279                                         'commandp))
 280                      'string<))
 281         doc)
 282     (mapcar
 283      (function
 284       (lambda (x)
 285         (and (if var-p (user-variable-p (intern x)) (commandp (intern x)))
 286              (progn
 287                (setq doc (if var-p
 288                              (get (intern x) 'variable-documentation)
 289                            (documentation (intern x))))
 290                (and doc (setq doc (substring doc 0 (string-match "\n" doc))))
 291                (or (string-match string x)
 292                    (and doc (string-match string doc))))
 293              (progn
 294                (princ x)
 295                (if var-p (princ " <V>:")
 296                  (princ " <F>:")
 297                  (princ (make-string (max 2 (- 30 (length x))) ?\ ))
 298                  (princ (dired-help-key-description (intern x))))
 299                (princ "\n ")
 300                (princ doc)
 301                (princ "\n")))))
 302      names)))
 303
 304 (defun dired-help-key-description (fun)
 305   ;; Returns a help string of keys for fun.
 306   (let ((res (mapconcat 'key-description
 307                         (where-is-internal fun dired-mode-map) ", ")))
 308     (if (string-equal res "")
 309         "\(not on any keys\)"
 310       res)))
 311
 312 ;;;###autoload
 313 (defun dired-summary ()
 314   "Display summary of basic dired commands in the minibuffer."
 315   (interactive)
 316   (message
 317    (mapconcat
 318     #'(lambda (list)
 319         (let* ((cmd (nth 0 list))
 320                (letter (nth 1 list))
 321                (name (nth 2 list))
 322                (name-with-letter (nth 3 list))
 323                (where-is (where-is-internal cmd dired-mode-map)))
 324           (if (or (member letter where-is)
 325                   (member (vector (intern letter)) where-is))
 326               name-with-letter
 327             (substitute-command-keys
 328              (format "\\<dired-mode-map>\\[%s] %s" cmd name)))))
 329     '((dired-flag-file-deletion     "d" "delete"       "d-elete")
 330       (dired-unmark                 "u" "undelete"     "u-ndelete")
 331       (dired-expunge-deletions      "x" "expunge"      "x-punge")
 332       (dired-advertised-find-file   "f" "find"         "f-ind")
 333       (dired-find-file-other-window "o" "other window" "o-ther window")
 334       (dired-do-rename              "R" "rename"       "R-ename")
 335       (dired-do-copy                "C" "copy"         "C-opy")
 336       (dired-describe-mode          "h" "help"         "h-elp"))
 337     ", ")))
 338
 339 (defun dired-hook-variable-p (sym)
 340   ;; Returns t if SYM is a hook variable.  Just looks at its name.
 341   (let ((name (symbol-name sym)))
 342     (and (>= (length name) 6)
 343          (or (string-equal (substring name -5) "-hook")
 344              (string-equal (substring name -6) "-hooks")))))
 345
 346 ;;; Submitting bug reports.
 347
 348 ;;;###autoload
 349 (defun dired-report-bug ()
 350   "Submit a bug report for dired."
 351   (interactive)
 352   (let ((reporter-prompt-for-summary-p t))
 353     (or (boundp 'reporter-version)
 354         (setq reporter-version
 355               "Your version of reporter is obsolete.  Please upgrade."))
 356     (reporter-submit-bug-report
 357      dired-bug-address "Dired"
 358      (cons
 359       'dired-version
 360       (nconc
 361        (mapcar
 362         'intern
 363         (sort
 364          (let (completion-ignore-case)
 365            (all-completions "dired-" obarray 'user-variable-p))
 366          'string-lessp))
 367        (list 'reporter-version)))
 368      (function
 369       (lambda ()
 370         (save-excursion
 371           (mail-position-on-field "subject")
 372           (beginning-of-line)
 373           (skip-chars-forward "^:\n")
 374           (if (looking-at ": Dired;")
 375               (progn
 376                 (goto-char (match-end 0))
 377                 (delete-char -1)
 378                 (insert " " dired-version " bug:")))))))))
 379
 380 ;;; end of dired-help.el