[emacs] prepare for Borg-ification
[~bandali/configs] / emacs / init.org
index db79586..4d57bf4 100644 (file)
@@ -3,11 +3,23 @@
 
 * Intro
 
 
 * Intro
 
-TODO: description
+This org file is tangled to [[./init.el][init.el]] and constitutes my Emacs
+configuration. =straight.el=, =use-package=, =general.el=, =exwm=,
+=org-mode=, and =magit= are some of the awesome packages powering my
+Emacs setup.
 
 
-TODO: toc
+* Contents                                                   :toc_1:noexport:
+
+- [[#intro][Intro]]
+- [[#header][Header]]
+- [[#initial-setup][Initial setup]]
+- [[#core][Core]]
+- [[#footer][Footer]]
 
 * Header
 
 * Header
+:PROPERTIES:
+:CUSTOM_ID: header
+:END:
 
 ** First line
 
 
 ** First line
 
@@ -50,7 +62,28 @@ file.
 ;; THIS FILE IS AUTO-GENERATED FROM `init.org'.
 #+end_src
 
 ;; THIS FILE IS AUTO-GENERATED FROM `init.org'.
 #+end_src
 
+** Naming conventions
+
+The conventions below were inspired by [[https://github.com/hlissner/doom-emacs][Doom]]'s conventions, found
+[[https://github.com/hlissner/doom-emacs/blob/5dacbb7cb1c6ac246a9ccd15e6c4290def67757c/core/core.el#L3-L17][here]]. Naturally, I use my initials, =ab=, instead of =doom=.
+
+#+begin_src emacs-lisp :comments none
+;; Naming conventions:
+;;
+;;   ab-...   public variables or non-interactive functions
+;;   ab--...  private anything (non-interactive), not safe for direct use
+;;   ab/...   an interactive function; safe for M-x or keybinding
+;;   ab:...   an evil operator, motion, or command
+;;   ab|...   a hook function
+;;   ab*...   an advising function
+;;   ab@...   a hydra command
+;;   ...!     a macro
+#+end_src
+
 * Initial setup
 * Initial setup
+:PROPERTIES:
+:CUSTOM_ID: initial-setup
+:END:
 
 #+begin_src emacs-lisp :comments none
 ;;; Code:
 
 #+begin_src emacs-lisp :comments none
 ;;; Code:
@@ -63,10 +96,10 @@ Measure and display startup time. Also, temporarily increase
 collection frequency. Taken from [[https://github.com/dieggsy/dotfiles/tree/3d95bc08033920e077855caf545a975eba52d28d/emacs.d#startup-time][here]].
 
 #+begin_src emacs-lisp
 collection frequency. Taken from [[https://github.com/dieggsy/dotfiles/tree/3d95bc08033920e077855caf545a975eba52d28d/emacs.d#startup-time][here]].
 
 #+begin_src emacs-lisp
-(defconst aminb/emacs-start-time (current-time))
-(defconst aminb/gc-cons-threshold gc-cons-threshold)
-(defconst aminb/gc-cons-percentage gc-cons-percentage)
-(defvar aminb/file-name-handler-alist file-name-handler-alist)
+(defconst ab--emacs-start-time (current-time))
+(defconst ab--gc-cons-threshold gc-cons-threshold)
+(defconst ab--gc-cons-percentage gc-cons-percentage)
+(defvar ab--file-name-handler-alist file-name-handler-alist)
 (setq gc-cons-threshold 400000000
       gc-cons-percentage 0.6
       file-name-handler-alist nil
 (setq gc-cons-threshold 400000000
       gc-cons-percentage 0.6
       file-name-handler-alist nil
@@ -80,18 +113,18 @@ Reset the variables back to default after init.
 (add-hook
  'after-init-hook
  `(lambda ()
 (add-hook
  'after-init-hook
  `(lambda ()
-    (setq gc-cons-threshold aminb/gc-cons-threshold
-         gc-cons-percentage aminb/gc-cons-percentage
-         file-name-handler-alist aminb/file-name-handler-alist)
+    (setq gc-cons-threshold ab--gc-cons-threshold
+         gc-cons-percentage ab--gc-cons-percentage
+         file-name-handler-alist ab--file-name-handler-alist)
     (let ((elapsed (float-time (time-subtract (current-time)
     (let ((elapsed (float-time (time-subtract (current-time)
-                                             aminb/emacs-start-time))))
+                                             ab--emacs-start-time))))
       (message "Loading %s...done (%.3fs) [after-init]"
               ,load-file-name elapsed))))
 #+end_src
 
 ** Package management
 
       (message "Loading %s...done (%.3fs) [after-init]"
               ,load-file-name elapsed))))
 #+end_src
 
 ** Package management
 
-*** [[https://github.com/raxod502/straight.el][=straight.el=]]
+*** =straight.el=
 
 #+begin_quote
 Next-generation, purely functional package manager for the Emacs
 
 #+begin_quote
 Next-generation, purely functional package manager for the Emacs
@@ -118,7 +151,7 @@ hacker.
 **** Useful helpers
 
 #+begin_src emacs-lisp
 **** Useful helpers
 
 #+begin_src emacs-lisp
-(defun straight-reload-init ()
+(defun ab/reload-init ()
   "Reload init.el."
   (interactive)
   (straight-transaction
   "Reload init.el."
   (interactive)
   (straight-transaction
@@ -127,7 +160,7 @@ hacker.
     (load user-init-file nil 'nomessage)
     (message "Reloading init.el... done.")))
 
     (load user-init-file nil 'nomessage)
     (message "Reloading init.el... done.")))
 
-(defun straight-eval-buffer ()
+(defun ab/eval-buffer ()
   "Evaluate the current buffer as Elisp code."
   (interactive)
   (message "Evaluating %s..." (buffer-name))
   "Evaluate the current buffer as Elisp code."
   (interactive)
   (message "Evaluating %s..." (buffer-name))
@@ -143,7 +176,7 @@ hacker.
 *** =use-package=
 
 #+begin_quote
 *** =use-package=
 
 #+begin_quote
-A use-package declaration for simplifying your .emacs.
+A use-package declaration for simplifying your .emacs
 #+end_quote
 
 =use-package= is an awesome utility for managing and configuring
 #+end_quote
 
 =use-package= is an awesome utility for managing and configuring
@@ -159,7 +192,7 @@ performance. So let's install it using =striaght.el= and have it use
 ** No littering in =~/.emacs.d=
 
 #+begin_quote
 ** No littering in =~/.emacs.d=
 
 #+begin_quote
-Help keeping ~/.emacs.d clean.
+Help keeping ~/.emacs.d clean
 #+end_quote
 
 By default, even for Emacs' built-in packages, the configuration files
 #+end_quote
 
 By default, even for Emacs' built-in packages, the configuration files
@@ -189,7 +222,171 @@ it it's own file.
   (load custom-file))
 #+end_src
 
   (load custom-file))
 #+end_src
 
-** Org
+** Better =$PATH= handling
+
+Let's use [[https://github.com/purcell/exec-path-from-shell][exec-path-from-shell]] to make Emacs use the =$PATH= as set up
+in my shell.
+
+#+begin_src emacs-lisp
+(use-package exec-path-from-shell
+  :defer 1
+  :init
+  (setq exec-path-from-shell-check-startup-files nil)
+  :config
+  (exec-path-from-shell-initialize)
+  ;; while we're at it, let's fix access to our running ssh-agent
+  (exec-path-from-shell-copy-env "SSH_AGENT_PID")
+  (exec-path-from-shell-copy-env "SSH_AUTH_SOCK"))
+#+end_src
+
+** Server
+
+Start server if not already running. Alternatively, can be done by
+issuing =emacs --daemon= in the terminal, which can be automated with
+a systemd service or using =brew services start emacs= on macOS. I use
+Emacs as my window manager (via =exwm=), so I always start Emacs on
+login; so starting the server from inside Emacs is good enough for me.
+
+See [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html#Emacs-Server][Using Emacs as a Server]].
+
+#+begin_src emacs-lisp
+(require 'server)
+(unless (server-running-p)
+  (server-start))
+#+end_src
+
+* Core
+:PROPERTIES:
+:CUSTOM_ID: core
+:END:
+
+** Defaults
+
+*** Disable disabled commands
+
+Emacs disables some commands by default that could persumably be
+confusing for novice users. Let's disable that.
+
+#+begin_src emacs-lisp
+(setq disabled-command-function nil)
+#+end_src
+
+*** Kill-ring
+
+Save what I copy into clipboard from other applications into Emacs'
+kill-ring, which would allow me to still be able to easily access it
+in case I kill (cut or copy) something else inside Emacs before
+yanking (pasting) what I'd originally intended to.
+
+#+begin_src emacs-lisp
+(setq save-interprogram-paste-before-kill t)
+#+end_src
+
+*** Keep more =*Messages*=
+
+#+begin_src emacs-lisp
+(setq message-log-max 10000)
+#+end_src
+
+*** Minibuffer
+
+#+begin_src emacs-lisp
+(setq enable-recursive-minibuffers t
+      resize-mini-windows t)
+#+end_src
+
+*** Lazy-person-friendly yes/no prompts
+
+Lazy people would prefer to type fewer keystrokes, especially for yes
+or no questions. I'm lazy.
+
+#+begin_src emacs-lisp
+(defalias 'yes-or-no-p #'y-or-n-p)
+#+end_src
+
+*** =*scratch*=
+
+Let's customize the =*scratch*= buffer a bit. First off, I don't need
+the default hint.
+
+#+begin_src emacs-lisp
+(setq initial-scratch-message "")
+#+end_src
+
+Also, let's use Text mode as the major mode, in case I want to
+customize it (=*scratch*='s default major mode, Fundamental mode,
+can't really be customized).
+
+#+begin_src emacs-lisp
+(setq initial-major-mode 'text-mode)
+#+end_src
+
+*** More useful frame titles
+
+Show either the file name or the buffer name (in case the buffer isn't
+visiting a file). Borrowed from Emacs Prelude.
+
+#+begin_src emacs-lisp
+(setq frame-title-format
+      '("" invocation-name " - "
+        (:eval (if (buffer-file-name)
+                   (abbreviate-file-name (buffer-file-name))
+                 "%b"))))
+#+end_src
+
+*** Backups
+
+Emacs' default backup settings aren't that great. Let's use more
+sensible options. See documentation for the ~make-backup-file~
+variable.
+
+#+begin_src emacs-lisp
+(setq backup-by-copying t
+      version-control t)
+#+end_src
+
+** Packages
+
+The packages in this section are absolutely essential to my everyday
+workflow, and they play key roles in how I do my computing. They
+immensely enhance the Emacs experience for me; both using Emacs, and
+customizing it.
+
+*** [[https://github.com/noctuid/general.el][general.el]]
+
+#+begin_quote
+More convenient key definitions in emacs
+#+end_quote
+
+More like /the most/ convenient key definitions in Emacs.
+
+#+begin_src emacs-lisp
+(use-package general
+  :demand t)
+#+end_src
+
+*** [[https://github.com/ch11ng/exwm][exwm]] (window manager)
+
+#+begin_src emacs-lisp
+(use-package exwm
+  :config
+  (require 'exwm-config)
+  (exwm-config-default)
+  (require 'exwm-systemtray)
+  (exwm-systemtray-enable)
+  (require 'exwm-randr)
+  (exwm-randr-enable))
+#+end_src
+
+*** [[https://orgmode.org/][Org mode]]
+
+#+begin_quote
+Org mode is for keeping notes, maintaining TODO lists, planning
+projects, and authoring documents with a fast and effective plain-text
+system.
+#+end_quote
+
+In short, my favourite way of life.
 
 #+begin_src emacs-lisp
 (setq org-src-tab-acts-natively t
 
 #+begin_src emacs-lisp
 (setq org-src-tab-acts-natively t
@@ -197,7 +394,71 @@ it it's own file.
       org-edit-src-content-indentation 0)
 #+end_src
 
       org-edit-src-content-indentation 0)
 #+end_src
 
+*** [[https://magit.vc/][Magit]]
+
+#+begin_quote
+It's Magit! A Git porcelain inside Emacs.
+#+end_quote
+
+Not just how I do git, but /the/ way to do git.
+
+#+begin_src emacs-lisp
+(use-package magit
+  :general
+  ("s-g" 'magit-status))
+#+end_src
+
+*** [[https://github.com/abo-abo/swiper][Ivy]] (and friends)
+
+#+begin_quote
+Ivy - a generic completion frontend for Emacs, Swiper - isearch with
+an overview, and more. Oh, man!
+#+end_quote
+
+There's no way I could top that, so I won't attempt to.
+
+**** Ivy
+
+#+begin_src emacs-lisp
+(use-package ivy
+  :general
+  (ivy-minibuffer-map
+   [escape] 'keyboard-escape-quit
+   "C-j" 'ivy-next-line
+   "C-k" 'ivy-previous-line
+   [S-up] 'ivy-previous-history-element
+   [S-down] 'ivy-next-history-element
+   "DEL" 'ivy-backward-delete-char)
+  :config
+  (ivy-mode 1))
+#+end_src
+
+**** Swiper
+
+#+begin_src emacs-lisp
+(use-package swiper
+  :general ("C-s" 'swiper))
+#+end_src
+
+**** Counsel
+
+#+begin_src emacs-lisp
+(use-package counsel
+  :general
+  ("M-x" 'counsel-M-x
+   "C-x C-f" 'counsel-find-file
+   "s-r" 'counsel-recentf)
+  (imap minibuffer-local-map
+    "C-r" 'counsel-minibuffer-history)
+  :config
+  (counsel-mode 1)
+  (defalias 'locate #'counsel-locate))
+#+end_src
+
 * Footer
 * Footer
+:PROPERTIES:
+:CUSTOM_ID: footer
+:END:
 
 #+begin_src emacs-lisp :comments none
 ;;; init.el ends here
 
 #+begin_src emacs-lisp :comments none
 ;;; init.el ends here