Add comments

1 files changed, 58 insertions, 5 deletions

diff --git a/init.el b/init.el
index 056447d..7b9c8f6 100644
--- a/init.el
+++ b/init.el
@@ -13,6 +13,9 @@
 
 (setq gc-cons-threshold (* 1024 1024 1024))
 
+;; Set some global key rebindings, mainly trying to use `*-dwim' functions
+;; whenever possible and making other common functions more convenient.  The
+;; main keybinding that conflicts with other modes is `C-.' or `C-,'.
 (global-set-key (kbd "M-u") #'upcase-dwim)
 (global-set-key (kbd "M-l") #'downcase-dwim)
 (global-set-key (kbd "M-c") #'capitalize-dwim)
@@ -29,6 +32,9 @@
 
 (define-key global-map (kbd "M-Q") #'ymh/unfill-paragraph)
 
+;; Create my own keymap for other, less important but still useful commands
+;; which I want to have quick access to.  This can be quite flexible, and it
+;; might change depending on what I need or how the configuration changes.
 (define-prefix-command 'ymh-map)
 (global-set-key (kbd "C-c y") 'ymh-map)
 (define-key ymh-map (kbd "o") #'ymh/reset-coq-windows)
@@ -37,6 +43,9 @@
 (define-key ymh-map (kbd "C-p") #'org-previous-link)
 (define-key ymh-map (kbd "C-n") #'org-next-link)
 
+;; Create variables which hold default locations for various things like my Org
+;; directory or the directory containing the bibliography.  This makes it much
+;; easier to migrate the configuration.
 (defvar ymh/org-base-dir "~/Dropbox/org"
   "Contains the base directory for Org files.")
 
@@ -48,6 +57,8 @@ Should be one of `:white-split', `:modified' or `:default'")
 (defvar ymh/bib-base-dir "~/Dropbox/bibliography"
   "Contains the base directory for the bibliography related files.")
 
+;; Define functions using the previous variables and `expand-file-name' to
+;; calculate the full path for any file correctly.
 (defun ymh/expand-org-file (file)
   "Expand file name relative to `ymh/org-base-dir'."
   (expand-file-name file ymh/org-base-dir))
@@ -56,6 +67,9 @@ Should be one of `:white-split', `:modified' or `:default'")
   "Expand file name relative to `ymh/bib-base-dir'."
   (expand-file-name file ymh/bib-base-dir))
 
+;; Set registers for commonly accessed files, especially org-mode files that
+;; will be edited a lot.  In general, I use `org-capture' to edit the Org files
+;; in particular though.
 (set-register ?l (cons 'file (expand-file-name "init.el" user-emacs-directory)))
 (set-register ?m (cons 'file (ymh/expand-org-file "meetings.org")))
 (set-register ?i (cons 'file (ymh/expand-org-file "inbox.org")))
@@ -63,49 +77,86 @@ Should be one of `:white-split', `:modified' or `:default'")
 (set-register ?c (cons 'file (ymh/expand-org-file
                               (format-time-string "%Y-%m.org"))))
 
+;; Emacs 29 contains some packages that otherwise need to be downloaded from
+;; Melpa, and in addition to that it also allows for the installation of
+;; packages using git.
 (defvar ymh/emacs-29-p (version<= "29" emacs-version)
   "Checks if the current emacs version is 29 or not.")
+
+;; There are also some changes that are means for MacOS only, so it's useful to
+;; have a flag for that as well.
 (defvar ymh/macos-p (eq system-type 'darwin)
   "Checks if the current operating system is MacOS.")
 
+;; Add linker arguments when compiling for macos.
 (when ymh/macos-p (customize-set-variable 'native-comp-driver-options '("-Wl,-w")))
 
+;; Load package for general package management.
 (require 'package)
 (add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
 (package-initialize)
 
-;; For emacs 28 and below install use-package
+;; For emacs 28 and below install use-package.  Use-package allows for neat
+;; organisation and loading of packages, allowing you to easily set variables
+;; before a package is loaded (in the `:init' section), and allowing you to
+;; customise the package after it has been loaded (in the `:config' section).
+;;
+;; There are many more benefits of using `use-package', but the separation of
+;; init and config is important to properly trigger any hooks on customisable
+;; variables.  If you set variables after the package has been loaded, they may
+;; not be properly set using the customisation interface, whereas if they were
+;; changed before the load it is as if they had been customised using the
+;; interface.
 (unless (package-installed-p 'use-package)
   (package-install 'use-package))
 
+;; Load my local library of common emacs functions.
 (use-package ymh-common
   :load-path "ymh-emacs")
 
+;; This is the main configuration block for vanilla emacs.
 (use-package emacs
   :init
+  ;; Remove any warnings from the async compilation.  This was bothersome
+  ;; because it would make the warning buffer appear whenever there were any.
   (setq native-comp-async-report-warnings-errors nil)
 
+  ;; Customise `isearch' so that it works accross new lines, which is especially
+  ;; useful for searching in documents with hard line breaks.  This fixes my one
+  ;; reason for not having hard line breaks as it becomes harder to edit.
   (setq isearch-lax-whitespace t)
   (setq isearch-regexp-lax-whitespace t)
   (setq search-whitespace-regexp "[ \t\r\n]+")
 
+  ;; Set the initial gnus file.
   (setq gnus-init-file (expand-file-name "gnus.el" user-emacs-directory))
 
+  ;; I currently use 80 as the default fill column width as it works on low-res
+  ;; displays as well.
   (setq-default fill-column 80)
 
   (setq completion-cycle-threshold 3)
   (setq tab-always-indent 'complete)
 
+  ;; Some simple configurations which make using the interface a bit nicer.
   (setq use-short-answers t)
   (setq inhibit-startup-message t)
   (setq confirm-nonexistent-file-or-buffer nil)
   (setq ring-bell-function 'ignore)
+
+  ;; I always end sentences in two spaces so that emacs can detect them easier.
   (setq sentence-end-double-space t)
 
+  ;; Follow symlinks when opening a file.
   (setq find-file-visit-truename t)
+  (setq vc-follow-symlinks t)
 
+  ;; When you have two dired buffers open, it will copy them from one to the
+  ;; other automatically.
   (setq dired-dwim-target t)
+  (setq wdired-allow-to-change-permissions t)
 
+  ;; Some performance improvements because I do not use right-to-left text.
   (setq truncate-partial-width-windows nil)
   (setq-default bidi-paragraph-direction 'left-to-right)
   (if (version<= "27.1" emacs-version)
@@ -116,6 +167,7 @@ Should be one of `:white-split', `:modified' or `:default'")
 
   (setq enable-recursive-minibuffers t)
 
+  ;; Clean up backup directories.
   (defvar --backup-directory)
   (setq --backup-directory (expand-file-name "backups" user-emacs-directory))
   (if (not (file-exists-p --backup-directory))
@@ -135,9 +187,8 @@ Should be one of `:white-split', `:modified' or `:default'")
   (setq auto-save-timeout 20)
   (setq auto-save-interval 200)
 
-  (setq vc-follow-symlinks t)
-
-  (setq add-log-full-name "Yann Herklotz")
+  ;; Setup some options to be able to use changelog mode.
+  (setq add-log-full-name user-full-name)
   (setq add-log-mailing-address "git@yannherklotz.com")
   (setq change-log-default-name "CHANGELOG")
   (add-hook 'change-log-mode-hook
@@ -147,6 +198,7 @@ Should be one of `:white-split', `:modified' or `:default'")
 	          (setq tab-width 2
 		            left-margin 2)))
 
+  ;; Set indentation settings for various languages.
   (setq-default indent-tabs-mode nil)
   (setq-default tab-width 4)
   (setq-default python-indent-offset 4)
@@ -154,14 +206,15 @@ Should be one of `:white-split', `:modified' or `:default'")
 
   (setq line-number-display-limit 2000000)
 
+  ;; Remove the emacs border when on Linux.
   (unless ymh/macos-p
     (setq default-frame-alist '((undecorated . t)
                                 (drag-internal-border . 1)
                                 (internal-border-width . 5))))
 
   (setq auth-sources '("~/.authinfo" "~/.authinfo.gpg" "~/.netrc"))
-  (setq wdired-allow-to-change-permissions t)
 
+  ;; Set visual new line indicators when using `visual-line-mode'.
   (setq visual-line-fringe-indicators '(left-curly-arrow nil))
   :config
   (unless ymh/macos-p