[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master 1a00bf1 2/4: Improve consistency of outline headings in dired lib
|
From: |
Jonas Bernoulli |
|
Subject: |
master 1a00bf1 2/4: Improve consistency of outline headings in dired libraries |
|
Date: |
Wed, 30 Jun 2021 16:25:54 -0400 (EDT) |
branch: master
commit 1a00bf16a72b03c9d79ec3bd301d02efc94f9683
Author: Jonas Bernoulli <jonas@bernoul.li>
Commit: Jonas Bernoulli <jonas@bernoul.li>
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 73bceff..060f3a8 100644
--- a/lisp/dired-aux.el
+++ b/lisp/dired-aux.el
@@ -33,6 +33,7 @@
;; sorting by Sebastian Kremer <sk@thp.uni-koeln.de>.
;; 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 38a624f..8d99d1a 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 1f90371..9ddd2c5 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)