diff --git a/00.emacs-patches.el b/00.emacs-patches.el index 0e164af..522cc1d 100644 --- a/00.emacs-patches.el +++ b/00.emacs-patches.el @@ -1,9 +1,17 @@ -;;;; Patches for buggy/old emacs code -*- lexical-binding: t; -*- -;;;; -;;;; This allows me to use one init file across multiple versions of Emacs. -;;;; -;;;; Currently tested against: -;;;; * GNU Emacs 29.1 +;;; init/00.emacs-patches.el --- Patches for buggy/old emacs code -*- lexical-binding: t; -*- + +;;; Commentary: +;; +;; This file serves two purposes: +;; +;; 1. It contains bugfixes for core Emacs functions. +;; 2. It backports new Emacs functionality to earlier versions that +;; are not yet available on Debian stable. +;; +;; Currently tested against: +;; * GNU Emacs 29.1 + +;;; Code: ;; Disallow navigating to the minibuffer (unless (eq (plist-get minibuffer-prompt-properties 'cursor-intangible) t) diff --git a/00.required-libraries.el b/00.required-libraries.el index 125272b..cd28074 100644 --- a/00.required-libraries.el +++ b/00.required-libraries.el @@ -1,10 +1,16 @@ -;;;; Misc utilities that I like to use throughout my init file. -*- lexical-binding: t; -*- +;;; init/00.required-libraries.el --- Misc utilities useful for init files -*- lexical-binding: t; -*- + +;;; Code: (require 'cl-lib) (require 'package) ;;; A new and improved DEFMACRO. TODO(upstream) (defmacro defmacro+ (name args &rest body) - "Like `cl-defmacro', but also attempts to figure out the indenting." + "Like `cl-defmacro', but also attempts to figure out the indenting. + +NAME: Symbol to use as macro, as in `cl-defmacro'. +ARGS: List of parameters to the macro, as in `cl-defmacro'. +BODY: The body of the macro, as in `cl-defmacro'." (let ((body-index (cl-position-if (lambda (arg) (member arg '(&body &rest))) (remove '&optional args)))) `(progn @@ -28,14 +34,14 @@ This allows you to declaratively hook in minor modes on a major mode." collect (list expr 1) else if (listp expr) collect expr - else do (error "%s does not appear to name a minor mode." expr)))) + else do (error "%s does not appear to name a minor mode" expr)))) `(hook-mode-attach ',hook (lambda () "Auto-generated by `hook-mode'" ,@body)))) (defvar hook-mode-*hooks* (make-hash-table :test #'eq)) (defun hook-mode-attach (hook function) + "Attach FUNCTION to HOOK." (when (gethash hook hook-mode-*hooks*) (remove-hook hook (gethash hook hook-mode-*hooks*))) (add-hook hook function) (setf (gethash hook hook-mode-*hooks*) function)) - diff --git a/c.el b/c.el index 11f40c1..bcda12a 100644 --- a/c.el +++ b/c.el @@ -1,6 +1,6 @@ -;;;; C customizations. -*- lexical-binding: t; -*- -;;;; -;;;; Also applied to other C-like languages (really anything that uses CC-mode) +;;; init/c.el --- C based language customizations -*- lexical-binding: t; -*- + +;;; Code: (hook-mode c-mode-common-hook visual-line-mode (c-set-offset 'case-label '+) @@ -47,8 +47,12 @@ ;; Make CC-Mode's defun finding include any function comments that ;; immediately preceede it. (defun my-c-beginning-of-defun (&optional arg) - "Move backward to the beginning of a defun, and any function -comment right before it." + "Move backward to the beginning of a defun, including comments. + +Unlike `c-beginning-of-defun', this also includes the comment +block in front of it. + +ARG: Number of defuns to move, as in `c-beginning-of-defun'." (ignore-errors (c-beginning-of-defun arg) (while (c-backward-single-comment)) @@ -57,7 +61,10 @@ comment right before it." ;; Make CScope use next-error functionality, so "C-x `" works correctly (defun cscope-next-error (n &optional reset) "Advance to the next error message and visit the file where the error was. -This is the value of `next-error-function' in CScope buffers." +This is the value of `next-error-function' in CScope buffers. + +N: Number of errors to move forward. +RESET: If non-nil, start from the beginning." (let ((buffer (get-buffer cscope-output-buffer-name))) (when reset (with-current-buffer buffer diff --git a/compilation.el b/compilation.el index 227c790..c8bcc06 100644 --- a/compilation.el +++ b/compilation.el @@ -1,4 +1,6 @@ -;;;; Compilation mode customizations -*- lexical-binding: t; -*- +;;; init/compilation.el --- Compilation mode customizations -*- lexical-binding: t; -*- + +;;; Code: (hook-mode compilation-mode-hook next-error-follow-minor-mode) (hook-mode occur-mode-hook diff --git a/custom.el b/custom.el index 4dbfb65..97c5169 100644 --- a/custom.el +++ b/custom.el @@ -1,4 +1,6 @@ -;; -*- lexical-binding: t; -*- +;;; init/custom.el --- Location for changes from Custom. -*- lexical-binding: t; -*- + +;;; Code: (put 'downcase-region 'disabled nil) (put 'upcase-region 'disabled nil) (put 'narrow-to-region 'disabled nil) diff --git a/diff.el b/diff.el index 0b986ec..f029de8 100644 --- a/diff.el +++ b/diff.el @@ -1,17 +1,36 @@ -;;;; Diff mode customizations -*- lexical-binding: t; -*- +;;; init/diff.el --- Diff mode customizations -*- lexical-binding: t; -*- + +;;; Code: (defun hexl-find-file-noselect (file) - "Find a file and put it into hexl-mode." + "Find a file and put it into `hexl-mode'. + +FILE: Path to a file to find." (let ((buffer (find-file-noselect file nil t))) (with-current-buffer buffer (hexl-mode 1)) buffer)) (defun ediff-binary-files (file1 file2) + "Diff two binary files with `ediff'. + +The diff will be done on the binary contents with both buffers in +`hexl-mode'. + +FILE1: Path to the first file. +FILE2: Path to the second file." (interactive (list (read-file-name "File A to compare: ") (read-file-name "File B to compare: "))) (apply #'ediff-buffers (mapcar #'hexl-find-file-noselect (list file1 file2)))) (defun ediff-binary-files3 (file1 file2 file3) + "Diff three binary files with `ediff3'. + +The diff will be done on the binary contents with all buffers in +`hexl-mode'. + +FILE1: Path to the first file. +FILE2: Path to the second file. +FILE3: Path to the third file." (interactive (list (read-file-name "File A to compare: ") (read-file-name "File B to compare: ") (read-file-name "File C to compare: "))) diff --git a/dired.el b/dired.el index 18a1856..635c70a 100644 --- a/dired.el +++ b/dired.el @@ -1,5 +1,6 @@ -;;;; Dired mode customizations. -*- lexical-binding: t; -*- +;;; init/dired.el --- Dired mode customizations -*- lexical-binding: t; -*- +;;; Code: (hook-mode dired-mode-hook (when window-system (dired-icon-mode 1)) @@ -31,5 +32,5 @@ "Show VC status for the currently displayed directory." (interactive) (unless (eq major-mode 'dired-mode) - (error "`my-dired-vc-dir' only works in dired mode.")) + (error "`my-dired-vc-dir' only works in Dired mode")) (vc-dir (dired-current-directory))) diff --git a/early-init.el b/early-init.el index 3d36aae..7cd6d32 100644 --- a/early-init.el +++ b/early-init.el @@ -1,8 +1,14 @@ -;;;; Visual changes that affect the initial frame. -*- lexical-binding: t; -*- +;;; init/early-init.el --- Visual changes that affect the initial frame -*- lexical-binding: t; -*- +;;; Commentary: +;; ;; This file should only be loaded during the early init and not -;; during regular init. `early-init-file' is set after the early init -;; process, which serves as a clear flag. +;; during regular init. This is only for fundamental visual changes +;; that would otherwise cause Emacs to flicker during startup. + +;;; Code: +;; `early-init-file' is set after the early init process, which serves +;; as a clear flag. (unless early-init-file (setf modus-themes-headings '((1 . (variable-pitch (height 1.5))) diff --git a/elisp.el b/elisp.el index e70d5ce..a9f3540 100644 --- a/elisp.el +++ b/elisp.el @@ -1,4 +1,6 @@ -;;;; Emacs Lisp customizations -*- lexical-binding: t; -*- +;;; init/elisp.el --- Emacs Lisp customizations -*- lexical-binding: t; -*- + +;;; Code: (hook-mode emacs-lisp-mode-hook eldoc-mode (font-lock-add-keywords nil '(("^\\s *;;;.*\n?" (0 'section-comment-face t)) diff --git a/emacs.el b/emacs.el index b9725b8..efb9648 100644 --- a/emacs.el +++ b/emacs.el @@ -1,6 +1,6 @@ -;;;; Global Emacs customizations. -*- lexical-binding: t; -*- -;;;; -;;;; Put stuff here if you have nowhere else to put them +;;; init/emacs.el --- Global Emacs customizations -*- lexical-binding: t; -*- + +;;; Code: (unless (fboundp 'bar-cursor-mode) ;; If this triggers, make sure to install the `bar-cursor' package ;; from melpa unstable. @@ -144,11 +144,11 @@ ;;; stand out a bit more. (defface section-comment-face '((t (:height 1.3 :inherit (font-lock-comment-face variable-pitch)))) - "Face for section level comments" + "Face for section level comments." :group 'local) (defface file-comment-face '((t (:height 1.5 :weight bold :inherit (font-lock-comment-face variable-pitch)))) - "Face for file level comments" + "Face for file level comments." :group 'local) ;; Also make same adjustments for markdown. @@ -181,7 +181,7 @@ (interactive) (if (> (length (frame-list)) 1) (delete-frame) - (when (y-or-n-p "Last frame, kill emacs? ") + (when (y-or-n-p "Last frame, kill Emacs? ") (call-interactively #'save-buffers-kill-emacs))))))) ;; Account for differences in Win32 keycodes @@ -223,7 +223,9 @@ (beginning-of-line)))) (defun end-of-line-dwim (&optional n) - "Movie point to the last non-whitespace character or the end of line." + "Movie point to the last non-whitespace character or the end of line. + +N: Number of lines to go forward." (interactive "^p") (let ((point (point))) @@ -237,7 +239,10 @@ ;;; Recursive edits TODO(package) (defun push-or-pop-excursion (pop?) - "Pushes or pops an excursion, depending on the prefix arg." + "Pushes or pops an excursion, depending on the prefix arg. + +POP?: If nil (the default), then push an excursion. Otherwise, +pop an excursion." (interactive (list current-prefix-arg)) (if (not pop?) @@ -248,6 +253,12 @@ ;;; Sibling file navigation TODO(upstream) (defun my-find-sibling-file-other-window (file) + "Variant of `find-sibling-file', that opens in another window. + +When called interactively, find the sibling of the current +buffer's file. + +FILE: File to find the sibling file of." (interactive (progn (unless buffer-file-name (user-error "Not visiting a file")) @@ -258,6 +269,12 @@ (let ((this-command t)) (run-hooks 'post-command-hook)))) (defun my-find-sibling-file-other-frame (file) + "Variant of `find-sibling-file', that opens in another frame. + +When called interactively, find the sibling of the current +buffer's file. + +FILE: File to find the sibling file of." (interactive (progn (unless buffer-file-name (user-error "Not visiting a file")) @@ -285,7 +302,7 @@ (defun indent-dwim (arg) "Try to do what a human would mean when indenting. -The prefix argument, if given, indents to that column" +The prefix argument ARG, if given, indents to that column." (interactive (list current-prefix-arg)) (cond (mark-active diff --git a/hexl.el b/hexl.el index 2f08515..3c4ff20 100644 --- a/hexl.el +++ b/hexl.el @@ -1,4 +1,6 @@ -;;;; Hexl (hex editor) customizations. -*- lexical-binding: t; -*- +;;; init/hexl.el --- Hexl (hex editor) customizations -*- lexical-binding: t; -*- + +;;; Code: (with-eval-after-load 'hexl (hook-mode hexl-mode-hook (hexl-follow-line) @@ -28,7 +30,11 @@ ;; TODO(upstream) (defun hexl-insert-nybble (ch arg) - "Insert nybble for character ch arg times." + "Insert nybble for character CH, ARG times. + +CH: Character for a nybble to insert. This should be a + hexadecimal digit, ?0 - ?9 or ?A -?F. +ARG: Number of times to insert the above character." (when (not (or (<= ?0 ch ?9) (<= ?a ch ?f) (<= ?A ch ?F))) @@ -47,7 +53,9 @@ (goto-char (+ hex-position index 1))))) (defun hexl-my-self-insert-command (arg) - "Replacement for `hexl-self-insert-command'." + "Replacement for `hexl-self-insert-command'. + +ARG: Number of times to insert the character." (interactive "p") (if (< (current-column) (hexl-ascii-start-column)) (hexl-insert-nybble last-command-event arg) @@ -65,50 +73,73 @@ 1 0))))) (defun hexl-my-ascii-position (addr) + "Return the buffer position in the ascii column. + +ADDR: Address to get the position for, as returned from +`hexl-current-address'." (+ (* (/ addr 16) (hexl-line-displen)) (hexl-ascii-start-column) (point-min) (% addr 16))) (defun hexl-my-movement (f arg) + "Execute movement function F, staying in ASCII or bytes column. + +F: Function to execute. +ARG: Argument to pass to F, as (F ARG)." (let ((at-ascii-position (>= (current-column) (hexl-ascii-start-column)))) (funcall f arg) (when at-ascii-position (goto-char (hexl-my-ascii-position (hexl-current-address t)))))) (defun hexl-my-movement0 (f) + "Execute movement function F, staying in ASCII or bytes column. + +F: Function to execute." (let ((at-ascii-position (>= (current-column) (hexl-ascii-start-column)))) (funcall f) (when at-ascii-position (goto-char (hexl-my-ascii-position (hexl-current-address t)))))) (defun hexl-my-backward-char (arg) - "Replacement for `hexl-backward-char'." + "Replacement for `hexl-backward-char'. + +ARG: Number of characters to move." (interactive "p") (hexl-my-forward-char (- arg))) (defun hexl-my-forward-char (arg) - "Replacement for `hexl-forward-char'." + "Replacement for `hexl-forward-char'. + +ARG: Number of characters to move." (interactive "p") (hexl-my-movement 'hexl-my-forward-char-internal arg)) (defun hexl-my-previous-line (arg) - "Replacement for `hexl-previous-line'." + "Replacement for `hexl-previous-line'. + +ARG: Number of lines to move." (interactive "p") (hexl-my-movement 'hexl-previous-line arg)) (defun hexl-my-next-line (arg) - "Replacement for `hexl-next-line'." + "Replacement for `hexl-next-line'. + +ARG: Number of lines to move." (interactive "p") (hexl-my-movement 'hexl-next-line arg)) (defun hexl-my-beginning-of-buffer (arg) - "Replacement for `hexl-beginning-of-buffer'." + "Replacement for `hexl-beginning-of-buffer'. + +ARG: Passed to `hexl-beginning-of-buffer'." (interactive "p") (hexl-my-movement 'hexl-beginning-of-buffer arg)) (defun hexl-my-end-of-buffer (arg) - "Replcaement for `hexl-end-of-buffer'." + "Replcaement for `hexl-end-of-buffer'. + +ARG: Passed to `hexl-end-of-buffer'." (interactive "p") (hexl-my-movement 'hexl-end-of-buffer arg)) diff --git a/lisp.el b/lisp.el index c4422b7..9b0a363 100644 --- a/lisp.el +++ b/lisp.el @@ -1,4 +1,6 @@ -;;;; (Common) Lisp customizations -*- lexical-binding: t; -*- +;;; init/lisp.el --- (Common) Lisp customizations -*- lexical-binding: t; -*- + +;;; Code: (cl-pushnew '("\\.asd\\'" . lisp-mode) auto-mode-alist :test #'equal) (hook-mode lisp-mode-hook diff --git a/menu-bar.el b/menu-bar.el index b5fb423..2d44601 100644 --- a/menu-bar.el +++ b/menu-bar.el @@ -1,4 +1,8 @@ -;;;; Menu bar customizations -*- lexical-binding: t; -*- -;;;; -;;;; TODO: Make x-popup-menu on TTYs properly handle mouse input (it -;;;; treats a mouse-click as "select current entry") +;;; init/menu-bar.el --- Menu bar customizations -*- lexical-binding: t; -*- + +;;; Code: + +;; No more needed! Just bugs to fix. +;; +;; TODO: Make x-popup-menu on TTYs properly handle mouse input (it +;; treats a mouse-click as "select current entry") diff --git a/text.el b/text.el index 347d33c..ccd9420 100644 --- a/text.el +++ b/text.el @@ -1,6 +1,6 @@ -;;;; Text mode customizations. -*- lexical-binding: t; -*- -;;;; -;;;; Why not use Emacs for editting plain old text? +;;; init/text.el --- Text mode customizations -*- lexical-binding: t; -*- + +;;; Code: (hook-mode text-mode-hook (unless (member major-mode '(mail-mode org-mode)) visual-line-mode)) diff --git a/vc.el b/vc.el index f17625a..edd3e0f 100644 --- a/vc.el +++ b/vc.el @@ -1,4 +1,6 @@ -;;;; Customizing Version Control menus and such -*- lexical-binding: t; -*- +;;; init/vc.el --- Customizing Version Control menus and such -*- lexical-binding: t; -*- + +;;; Code: (with-eval-after-load 'vc-git (keymap-set vc-git-extra-menu-map "" '(menu-item "Git SVN Commit" vc-git-svn-dcommit)) @@ -6,14 +8,18 @@ '(menu-item "Git SVN Update" vc-git-svn-rebase))) (defun vc-git-svn-rebase () - "Get lastest changes from SVN to Git." + "Get latest commits from SVN to Git." (interactive) (let ((root (vc-git-root default-directory))) (assert root nil "Not in a Git repository") (vc-git-command "*vc-git*" 'async nil "svn" "rebase") (display-buffer "*vc-git*"))) + (defun vc-git-svn-dcommit (&optional rebase-also) - "Commit changes stored in a Git repository to SVN." + "Submit SVN commits for all commits in the Git repository. + +REBASE-ALSO: If non-nil, do not actually rebase so that you can +manually do the desired rebase." (interactive "P") (let ((root (vc-git-root default-directory))) (assert root nil "Not in a Git repository") diff --git a/window.el b/window.el index 5c9f1c4..9a0e9c4 100644 --- a/window.el +++ b/window.el @@ -1,7 +1,11 @@ -;;;; Control the window layout. -*- lexical-binding: t; -*- -;;;; -;;;; Generally this customizes display-buffer-alist and related -;;;; options. +;;; init/window.el --- Control the window layout -*- lexical-binding: t; -*- + +;;; Commentary: +;; +;; Using `display-buffer-alist' send small utility windows to side +;; windows. This also adjusts some related options. + +;;; Code: ;; Make more switching commands do what I want. (setf switch-to-buffer-obey-display-actions t diff --git a/xml.el b/xml.el index d82ff63..13023d1 100644 --- a/xml.el +++ b/xml.el @@ -1,5 +1,6 @@ -;;;; Configuration for XML files -*- lexical-binding: t; -*- +;;; init/xml.el --- Configuration for XML files -*- lexical-binding: t; -*- +;;; Code: (add-to-list 'major-mode-remap-alist '(xml-mode . nxml-mode)) (add-to-list 'major-mode-remap-alist '(mhtml-mode . nxml-mode))