From 1a00bf16a72b03c9d79ec3bd301d02efc94f9683 Mon Sep 17 00:00:00 2001 From: Jonas Bernoulli Date: Sun, 14 Mar 2021 20:24:07 +0100 Subject: [PATCH] Improve consistency of outline headings in dired libraries * lisp/dired-aux.el: Improve consistency of outline headings. * lisp/dired-x.el: Improve consistency of outline headings. * lisp/dired.el: Improve consistency of outline headings. - Use three semicolons at beginning of headings because that already is the dominant number of semicolons for headings in these files. - Prefix each heading with a ^L instead of randomly omitting it in front of some. - Always prefix the line with the ^L with a completely empty line. - Begin headings with a capital letter. - Do not update complete headings. - Do not end headings with a period. - Remove a handful of section end markers. - Address further inconsistencies. --- lisp/dired-aux.el | 59 +++++++++++++++++++++--------------- lisp/dired-x.el | 39 +++++++++++++----------- lisp/dired.el | 77 ++++++++++++++++++++++++++++++----------------- 3 files changed, 106 insertions(+), 69 deletions(-) diff --git a/lisp/dired-aux.el b/lisp/dired-aux.el index 73bceffbc2c..060f3a84111 100644 --- a/lisp/dired-aux.el +++ b/lisp/dired-aux.el @@ -33,6 +33,7 @@ ;; sorting by Sebastian Kremer . ;; Finished up by rms in 1992. + ;;; Code: (require 'cl-lib) @@ -45,9 +46,8 @@ Functions that operate recursively can store additional names into this list; they also should call `dired-log' to log the errors.") -;;; 15K -;;;###begin dired-cmd.el -;; Diffing and compressing + +;;; Diffing and compressing (defconst dired-star-subst-regexp "\\(^\\|[ \t]\\)\\*\\([ \t]\\|$\\)") (defconst dired-quark-subst-regexp "\\(^\\|[ \t]\\)\\?\\([ \t]\\|$\\)") @@ -418,6 +418,7 @@ List has a form of (file-name full-file-name (attribute-list))." full-file-name (file-attributes full-file-name)))) (directory-files dir))) + ;;; Change file attributes @@ -655,8 +656,9 @@ passed as the second arg to `completing-read'." 'completing-read (format prompt (dired-mark-prompt arg files)) collection nil nil initial nil default-value nil)) + -;;; Cleaning a directory: flagging some backups for deletion. +;;; Cleaning a directory: flagging some backups for deletion (defvar dired-file-version-alist) @@ -699,7 +701,8 @@ with a prefix argument." (dired-map-dired-file-lines #'dired-trample-file-versions) (message "Cleaning numerical backups...done"))) -;;; Subroutines of dired-clean-directory. + +;;; Subroutines of dired-clean-directory (defun dired-map-dired-file-lines (fun) ;; Perform FUN with point at the end of each non-directory line. @@ -750,6 +753,7 @@ with a prefix argument." (progn (beginning-of-line) (delete-char 1) (insert dired-del-marker))))) + ;;; Shell commands @@ -986,8 +990,8 @@ prompted for the shell command to use interactively." (shell-command command))) ;; Return nil for sake of nconc in dired-bunch-files. nil) - + (defun dired-check-process (msg program &rest arguments) "Display MSG while running PROGRAM, and check for output. Remaining arguments are strings passed as command arguments to PROGRAM. @@ -1032,8 +1036,9 @@ Return the result of `process-file' - zero for success." (unless (zerop res) (pop-to-buffer out-buffer)) res)))) + -;; Commands that delete or redisplay part of the dired buffer. +;;; Commands that delete or redisplay part of the dired buffer (defun dired-kill-line (&optional arg) "Kill the current line (not the files). @@ -1098,10 +1103,8 @@ present. A FMT of \"\" will suppress the messaging." (message (or fmt "Killed %d line%s.") count (dired-plural-s count))) count)))) -;;;###end dired-cmd.el -;;; 30K -;;;###begin dired-cp.el +;;; Compression (defun dired-compress () ;; Compress or uncompress the current file. @@ -1454,7 +1457,8 @@ uncompress and unpack all the files in the archive." (interactive "P") (dired-map-over-marks-check #'dired-compress arg 'compress t)) -;; Commands for Emacs Lisp files - load and byte compile + +;;; Commands for Emacs Lisp files - load and byte compile (defun dired-byte-compile () ;; Return nil for success, offending file name else. @@ -1546,6 +1550,7 @@ See Info node `(emacs)Subdir switches' for more details." (interactive) (setq dired-switches-alist nil) (revert-buffer)) + (defun dired-update-file-line (file) ;; Delete the current line, and insert an entry for FILE. @@ -1734,6 +1739,7 @@ See `dired-delete-file' in case you wish that." (line-beginning-position 2))) (setq file (directory-file-name file)) (dired-add-entry file (if (eq ?\s marker) nil marker))))) + ;;; Copy, move/rename, making hard and symbolic links @@ -1933,7 +1939,9 @@ unless OK-IF-ALREADY-EXISTS is non-nil." (defvar overwrite-query) (defvar overwrite-backup-query) -;; The basic function for half a dozen variations on cp/mv/ln/ln -s. + +;;; The basic function for half a dozen variations on cp/mv/ln/ln -s + (defun dired-create-files (file-creator operation fn-list name-constructor &optional marker-char) "Create one or more new files from a list of existing files FN-LIST. @@ -2067,6 +2075,7 @@ ESC or `q' to not overwrite any of the remaining files, success-count) operation success-count)))) (dired-move-to-filename)) + (defcustom dired-do-revert-buffer nil "Automatically revert Dired buffers after `dired-do' operations. @@ -2299,7 +2308,6 @@ Optional arg HOW-TO determines how to treat the target. dired-dirs))) - ;; We use this function in `dired-create-directory' and ;; `dired-create-empty-file'; the return value is the new entry ;; in the updated Dired buffer. @@ -2448,10 +2456,10 @@ of `dired-dwim-target', which see." (interactive "P") (dired-do-create-files 'move #'dired-rename-file "Move" arg dired-keep-marker-rename "Rename")) -;;;###end dired-cp.el + -;;; 5K -;;;###begin dired-re.el +;;; Operate on files matched by regexp + (defvar rename-regexp-query) (defun dired-do-create-files-regexp @@ -2572,6 +2580,9 @@ See function `dired-do-rename-regexp' for more info." #'make-symbolic-link "SymLink" arg regexp newname whole-name dired-keep-marker-symlink)) + +;;; Change case of file names + (defvar rename-non-directory-query) (defun dired-create-files-non-directory @@ -2617,10 +2628,8 @@ Type SPC or `y' to %s one file, DEL or `n' to skip to next, (interactive "P") (dired-rename-non-directory #'downcase "Rename downcase" arg)) -;;;###end dired-re.el -;;; 13K -;;;###begin dired-ins.el +;;; Insert subdirectory ;;;###autoload (defun dired-maybe-insert-subdir (dirname &optional @@ -2894,8 +2903,9 @@ is always equal to STRING." (setq result (cons (substring str end) result))) (nreverse result))) + -;;; moving by subdirectories +;;; Moving by subdirectories ;;;###autoload (defun dired-prev-subdir (arg &optional no-error-if-not-found no-skip) @@ -2998,8 +3008,9 @@ Lower levels are unaffected." (if pos (goto-char pos) (error "At the bottom")))) + -;;; hiding +;;; Hiding ;;;###autoload (defun dired-hide-subdir (arg) @@ -3043,10 +3054,8 @@ Use \\[dired-hide-subdir] to (un)hide a particular subdirectory." (dired--hide start end)) (setq pos (cdr subdir))))))) ; prev dir gets current dir -;;;###end dired-ins.el - -;; Search only in file names in the Dired buffer. +;;; Search only in file names in the Dired buffer (defcustom dired-isearch-filenames nil "Non-nil to Isearch in file names only. @@ -3116,7 +3125,7 @@ is part of a file name (i.e., has the text property `dired-filename')." (isearch-forward-regexp nil t)) -;; Functions for searching in tags style among marked files. +;;; Functions for searching in tags style among marked files ;;;###autoload (defun dired-do-isearch () diff --git a/lisp/dired-x.el b/lisp/dired-x.el index 38a624fa72b..8d99d1a21c6 100644 --- a/lisp/dired-x.el +++ b/lisp/dired-x.el @@ -44,7 +44,8 @@ ;; but maybe not if a dired-x function is being autoloaded. (require 'dired) -;;; User-defined variables. + +;;; User-defined variables (defgroup dired-x nil "Extended directory editing (dired-x)." @@ -217,7 +218,9 @@ to nil: a pipe using `zcat' or `gunzip -c' will be used." :type 'boolean :group 'dired-x) -;;; KEY BINDINGS. + +;;; Key bindings + (when (keymapp (lookup-key dired-mode-map "*")) (define-key dired-mode-map "*(" 'dired-mark-sexp) (define-key dired-mode-map "*O" 'dired-mark-omitted) @@ -234,7 +237,8 @@ to nil: a pipe using `zcat' or `gunzip -c' will be used." (define-key dired-mode-map "Y" 'dired-do-relsymlink) (define-key dired-mode-map "V" 'dired-do-run-mail) -;;; MENU BINDINGS + +;;; Menu bindings (when-let ((menu (lookup-key dired-mode-map [menu-bar]))) (easy-menu-add-item menu '("Operate") @@ -274,7 +278,7 @@ files"] "Refresh")) -;; Install into appropriate hooks. +;;; Install into appropriate hooks (add-hook 'dired-mode-hook 'dired-extra-startup) (add-hook 'dired-after-readin-hook 'dired-omit-expunge) @@ -303,7 +307,7 @@ See also the functions: (dired-omit-startup)) -;;; EXTENSION MARKING FUNCTIONS. +;;; Extension marking functions (defun dired--mark-suffix-interactive-spec () (let* ((default @@ -432,7 +436,7 @@ See variables `dired-texinfo-unclean-extensions', (list ".dvi")))) -;;; OMITTING. +;;; Omitting ;; Enhanced omitting of lines from directory listings. ;; Marked files are never omitted. @@ -570,7 +574,7 @@ files in the active region if `dired-mark-region' is non-nil." msg))) -;;; VIRTUAL DIRED MODE. +;;; Virtual dired mode ;; For browsing `ls -lR' listings in a dired-like fashion. @@ -693,7 +697,7 @@ Also useful for `auto-mode-alist' like this: (dired-virtual (dired-virtual-guess-dir))) -;;; SMART SHELL. +;;; Smart shell ;; An Emacs buffer can have but one working directory, stored in the ;; buffer-local variable `default-directory'. A Dired buffer may have @@ -720,7 +724,7 @@ Also useful for `auto-mode-alist' like this: (shell-command command output-buffer error-buffer))) -;;; GUESS SHELL COMMAND. +;;; Guess shell command ;; Brief Description: ;; @@ -1028,7 +1032,7 @@ See `dired-guess-shell-alist-user'." (if (equal val "") default val)))) -;;; RELATIVE SYMBOLIC LINKS. +;;; Relative symbolic links (declare-function make-symbolic-link "fileio.c") @@ -1117,7 +1121,7 @@ for more info." "RelSymLink" arg regexp newname whole-name dired-keep-marker-relsymlink)) -;;; VISIT ALL MARKED FILES SIMULTANEOUSLY. +;;; Visit all marked files simultaneously ;; Brief Description: ;; @@ -1186,7 +1190,7 @@ NOSELECT the files are merely found but not selected." (find-file file))))) -;;; MISCELLANEOUS COMMANDS. +;;; Miscellaneous commands ;; Run man on files. @@ -1254,7 +1258,7 @@ otherwise." (dired-rmail))))) -;;; MISCELLANEOUS INTERNAL FUNCTIONS. +;;; Miscellaneous internal functions ;; This should be a builtin (defun dired-buffer-more-recently-used-p (buffer1 buffer2) @@ -1264,7 +1268,6 @@ Considers buffers closer to the car of `buffer-list' to be more recent." (memq buffer1 (buffer-list)) (not (memq buffer1 (memq buffer2 (buffer-list)))))) - ;; Needed if ls -lh is supported and also for GNU ls -ls. (defun dired-x--string-to-number (str) "Like `string-to-number' but recognize a trailing unit prefix. @@ -1437,7 +1440,7 @@ only in the active region if `dired-mark-region' is non-nil." (format "'%s file" predicate)))) -;;; FIND FILE AT POINT. +;;; Find file at point (defcustom dired-x-hands-off-my-keys t "Non-nil means don't remap `find-file' to `dired-x-find-file'. @@ -1484,7 +1487,8 @@ a prefix argument, when it offers the filename near point as a default." (interactive (list (dired-x-read-filename-at-point "Find file: "))) (find-file-other-window filename)) -;;; Internal functions. + +;;; Internal functions ;; Fixme: This should probably use `thing-at-point'. -- fx (define-obsolete-function-alias 'dired-filename-at-point @@ -1532,8 +1536,9 @@ If `current-prefix-arg' is non-nil, uses name at point as guess." (define-obsolete-function-alias 'read-filename-at-point 'dired-x-read-filename-at-point "24.1") ; is this even needed? + -;;; BUG REPORTS +;;; Epilog (define-obsolete-function-alias 'dired-x-submit-report 'report-emacs-bug "24.1") diff --git a/lisp/dired.el b/lisp/dired.el index 1f9037180dc..9ddd2c542dc 100644 --- a/lisp/dired.el +++ b/lisp/dired.el @@ -41,6 +41,7 @@ (declare-function dired-buffer-more-recently-used-p "dired-x" (buffer1 buffer2)) + ;;; Customizable variables (defgroup dired nil @@ -254,8 +255,6 @@ This is similar to the \"-L\" option for the \"cp\" shell command." (define-obsolete-variable-alias 'dired-free-space-args 'directory-free-space-args "27.1") -;;; Hook variables - (defcustom dired-load-hook nil "Run after loading Dired. You can customize key bindings or load extensions with this." @@ -357,7 +356,8 @@ is anywhere on its Dired line, except the beginning of the line." :group 'dired :version "28.1") -;; Internal variables + +;;; Internal variables (defvar dired-marker-char ?* ; the answer is 42 ;; so that you can write things like @@ -457,6 +457,9 @@ The match starts at the beginning of the line and ends after the end of the line. Subexpression 2 must end right before the \\n.") + +;;; Faces + (defgroup dired-faces nil "Faces used by Dired." :group 'dired @@ -560,6 +563,9 @@ Subexpression 2 must end right before the \\n.") (defvar dired-ignored-face 'dired-ignored "Face name used for files suffixed with `completion-ignored-extensions'.") + +;;; Font-lock + (defvar dired-font-lock-keywords (list ;; @@ -687,8 +693,11 @@ Subexpression 2 must end right before the \\n.") "Additional expressions to highlight in Dired mode.") (defvar dnd-protocol-alist) + -;;; Macros must be defined before they are used, for the byte compiler. +;;; Macros + +;; Macros must be defined before they are used, for the byte compiler. (defmacro dired-mark-if (predicate msg) "Mark files for PREDICATE, according to `dired-marker-char'. @@ -883,7 +892,7 @@ ERROR can be a string with the error message." (point-max))) -;; The dired command +;;; The dired command (defun dired-read-dir-and-switches (str) ;; For use in interactive. @@ -1263,7 +1272,7 @@ The return value is the target column for the file names." found))) -;; Read in a new dired buffer +;;; Read in a new dired buffer (defun dired-readin () "Read in a new Dired buffer. @@ -1627,8 +1636,9 @@ see `dired-use-ls-dired' for more details.") (put-text-property (+ (point) 4) (line-end-position) 'invisible 'dired-hide-details-link)))) (forward-line 1)))) + -;; Reverting a dired buffer +;;; Reverting a dired buffer (defun dired-revert (&optional _arg _noconfirm) "Reread the Dired buffer. @@ -1815,8 +1825,9 @@ Do so according to the former subdir alist OLD-SUBDIR-ALIST." (let ((handler (find-file-name-handler dir 'dired-uncache))) (if handler (funcall handler 'dired-uncache dir)))) + -;; dired mode key bindings and initialization +;;; Dired mode key bindings and menus (defvar dired-mode-map ;; This looks ugly when substitute-command-keys uses C-d instead d: @@ -2177,6 +2188,8 @@ Do so according to the former subdir alist OLD-SUBDIR-ALIST." :help "Delete image tag from current or marked files"])) +;;; Dired mode + ;; Dired mode is suitable only for specially formatted data. (put 'dired-mode 'mode-class 'special) @@ -2274,8 +2287,9 @@ Keybindings: (add-hook 'file-name-at-point-functions #'dired-file-name-at-point nil t) (add-hook 'isearch-mode-hook #'dired-isearch-filenames-setup nil t) (run-mode-hooks 'dired-mode-hook)) + -;; Idiosyncratic dired commands that don't deal with marks. +;;; Idiosyncratic dired commands that don't deal with marks (defun dired-summary () "Summarize basic Dired commands and show recent Dired errors." @@ -2473,8 +2487,9 @@ Otherwise, display it in another buffer." (interactive) (display-buffer (find-file-noselect (dired-get-file-for-visit)) t)) + -;;; Functions for extracting and manipulating file names in Dired buffers. +;;; Functions for extracting and manipulating file names in Dired buffers (defun dired-unhide-subdir () (with-silent-modifications @@ -2619,7 +2634,10 @@ unchanged." (if (string-match (concat "^" (regexp-quote dir)) file) (substring file (match-end 0)) file)) + +;;; Mode to hide details + (define-minor-mode dired-hide-details-mode "Toggle visibility of detailed information in current Dired buffer. When this minor mode is enabled, details such as file ownership and @@ -2656,6 +2674,7 @@ See options: `dired-hide-details-hide-symlink-targets' and 'add-to-invisibility-spec 'remove-from-invisibility-spec) 'dired-hide-details-link)) + ;;; Functions to hide/unhide text @@ -2685,7 +2704,7 @@ See options: `dired-hide-details-hide-symlink-targets' and (progn (goto-char end) (line-end-position)) '(invisible)))) -;;; Functions for finding the file name in a dired buffer line. +;;; Functions for finding the file name in a dired buffer line (defvar dired-permission-flags-regexp "\\([^ ]\\)[-r][-w]\\([^ ]\\)[-r][-w]\\([^ ]\\)[-r][-w]\\([^ ]\\)" @@ -2784,7 +2803,7 @@ If EOL, it should be an position to use instead of (point))))) -;;; COPY NAMES OF MARKED FILES INTO KILL-RING. +;;; Copy names of marked files into kill-ring (defun dired-copy-filename-as-kill (&optional arg) "Copy names of marked (or next ARG) files into the kill ring. @@ -2818,7 +2837,7 @@ You can then feed the file name(s) to other commands with \\[yank]." (message "%s" string)))) -;; Keeping Dired buffers in sync with the filesystem and with each other +;;; Keeping Dired buffers in sync with the filesystem and with each other (defun dired-buffers-for-dir (dir &optional file subdirs) "Return a list of buffers for DIR (top level or in-situ subdir). @@ -2904,10 +2923,9 @@ dired-buffers." ;; Removing is also done as a side-effect in dired-buffer-for-dir. (setq dired-buffers (delq (assoc (expand-file-name dir) dired-buffers) dired-buffers))) - -;; Tree Dired -;;; utility functions + +;;; Utility functions (defun dired-in-this-tree-p (file dir) ;;"Is FILE part of the directory tree starting at DIR?" @@ -3167,7 +3185,7 @@ It runs the hook `dired-initial-position-hook'." (dired-goto-subdir dirname)) (if dired-trivial-filenames (dired-goto-next-nontrivial-file)) (run-hooks 'dired-initial-position-hook)) - + ;; These are hooks which make tree dired work. ;; They are in this file because other parts of dired need to call them. ;; But they don't call the rest of tree dired unless there are subdirs loaded. @@ -3206,8 +3224,9 @@ is the directory where the file on this line resides." (if (or (null (cdr dired-subdir-alist)) (not (dired-next-subdir 1 t t))) (point-max) (point)))) + -;; Deleting files +;;; Deleting files (defcustom dired-recursive-deletes 'top "Whether Dired deletes directories recursively. @@ -3448,7 +3467,7 @@ confirmation. To disable the confirmation, see (kill-buffer buf)))))) -;; Confirmation +;;; Confirmation (defun dired-marker-regexp () (concat "^" (regexp-quote (char-to-string dired-marker-char)))) @@ -3567,8 +3586,9 @@ argument or confirmation)." (let ((beg (point))) (completion--insert-strings files) (put-text-property beg (point) 'mouse-face nil))) + -;; Commands to mark or flag file(s) at or near current line. +;;; Commands to mark or flag file(s) at or near current line (defun dired-repeat-over-lines (arg function) ;; This version skips non-file lines. @@ -3756,8 +3776,9 @@ on the whole buffer." (list ?\s dired-marker-char) (list dired-marker-char ?\s)))) (forward-line 1))))) + -;;; Commands to mark or flag files based on their characteristics or names. +;;; Commands to mark or flag files based on their characteristics or names (defvar dired-regexp-history nil "History list of regular expressions used in Dired commands.") @@ -4033,8 +4054,9 @@ Type SPC or `y' to unmark one file, DEL or `n' to skip to next, (message (if (= count 1) "1 mark removed" "%d marks removed") count)))) + -;; Logging failures operating on files, and showing the results. +;;; Logging failures operating on files, and showing the results (defvar dired-log-buffer "*Dired log*") @@ -4099,6 +4121,7 @@ or nil if file names are not applicable." ;; Log a summary describing a bunch of errors. (dired-log (concat "\n" string "\n")) (dired-log t)) + ;;; Sorting @@ -4280,9 +4303,9 @@ To be called first in body of `dired-sort-other', etc." ;; No pre-R subdir alist, so revert to main directory ;; listing: (list (car (reverse dired-subdir-alist)))))))) - -;;;; Drag and drop support + +;;; Drag and drop support (defcustom dired-recursive-copies 'top "Whether Dired copies directories recursively. @@ -4384,9 +4407,9 @@ Ask means pop up a menu for the user to select one of copy, move or link." (let ((local-file (dnd-get-local-file-uri uri))) (if local-file (dired-dnd-handle-local-file local-file action) nil))) - -;;;; Desktop support + +;;; Desktop support (eval-when-compile (require 'desktop)) (declare-function desktop-file-name "desktop" (filename dirname)) @@ -4432,7 +4455,7 @@ Ask means pop up a menu for the user to select one of copy, move or link." '(dired-mode . dired-restore-desktop-buffer)) -;;;; Jump to Dired +;;; Jump to Dired (defvar archive-superior-buffer) (defvar tar-superior-buffer) -- 2.39.2