[emacs] add naming conventions
[~bandali/configs] / emacs / init.org
index 1801baf..5aa530e 100644 (file)
@@ -5,9 +5,18 @@
 
 TODO: description
 
 
 TODO: description
 
-TODO: toc
+* Contents                                                   :toc_1:noexport:
+
+- [[#intro][Intro]]
+- [[#header][Header]]
+- [[#initial-setup][Initial setup]]
+- [[#config][Config]]
+- [[#footer][Footer]]
 
 * Header
 
 * Header
+:PROPERTIES:
+:CUSTOM_ID: header
+:END:
 
 ** First line
 
 
 ** First line
 
@@ -41,7 +50,7 @@ file.
 
 ** Commentary
 
 
 ** Commentary
 
-#+begin_src emacs-lisp
+#+begin_src emacs-lisp :comments none
 ;;; Commentary:
 
 ;; Emacs configuration of Amin Bandali, computer scientist and functional
 ;;; Commentary:
 
 ;; Emacs configuration of Amin Bandali, computer scientist and functional
@@ -50,17 +59,195 @@ file.
 ;; THIS FILE IS AUTO-GENERATED FROM `init.org'.
 #+end_src
 
 ;; THIS FILE IS AUTO-GENERATED FROM `init.org'.
 #+end_src
 
-* Config
+** Naming conventions
 
 
-#+begin_src emacs-lisp
+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
+;;   ab!...   a macro
+#+end_src
+
+* Initial setup
+:PROPERTIES:
+:CUSTOM_ID: initial-setup
+:END:
+
+#+begin_src emacs-lisp :comments none
 ;;; Code:
 #+end_src
 
 ;;; Code:
 #+end_src
 
-TODO
+** Startup time
+
+Measure and display startup time. Also, temporarily increase
+~gc-cons-threshhold~ during startup to reduce reduce garbage
+collection frequency. Taken from [[https://github.com/dieggsy/dotfiles/tree/3d95bc08033920e077855caf545a975eba52d28d/emacs.d#startup-time][here]].
+
+#+begin_src emacs-lisp
+(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
+      ;; sidesteps a bug when profiling with esup
+      esup-child-profile-require-level 0)
+#+end_src
+
+Reset the variables back to default after init.
+
+#+begin_src emacs-lisp
+(add-hook
+ 'after-init-hook
+ `(lambda ()
+    (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)
+                                             ab--emacs-start-time))))
+      (message "Loading %s...done (%.3fs) [after-init]"
+              ,load-file-name elapsed))))
+#+end_src
+
+** Package management
+
+*** =straight.el=
+
+#+begin_quote
+Next-generation, purely functional package manager for the Emacs
+hacker.
+#+end_quote
+
+=straight.el= allows me to have a fully reproducible Emacs setup.
+
+**** Bootstrap
+
+#+begin_src emacs-lisp
+(let ((bootstrap-file (concat user-emacs-directory "straight/repos/straight.el/bootstrap.el"))
+      (bootstrap-version 3))
+  (unless (file-exists-p bootstrap-file)
+    (with-current-buffer
+        (url-retrieve-synchronously
+         "https://raw.githubusercontent.com/raxod502/straight.el/develop/install.el"
+         'silent 'inhibit-cookies)
+      (goto-char (point-max))
+      (eval-print-last-sexp)))
+  (load bootstrap-file nil 'nomessage))
+#+end_src
+
+**** Useful helpers
+
+#+begin_src emacs-lisp
+(defun straight-reload-init ()
+  "Reload init.el."
+  (interactive)
+  (straight-transaction
+    (straight-mark-transaction-as-init)
+    (message "Reloading init.el...")
+    (load user-init-file nil 'nomessage)
+    (message "Reloading init.el... done.")))
+
+(defun straight-eval-buffer ()
+  "Evaluate the current buffer as Elisp code."
+  (interactive)
+  (message "Evaluating %s..." (buffer-name))
+  (straight-transaction
+    (if (null buffer-file-name)
+        (eval-buffer)
+      (when (string= buffer-file-name user-init-file)
+        (straight-mark-transaction-as-init))
+      (load-file buffer-file-name)))
+  (message "Evaluating %s... done." (buffer-name)))
+#+end_src
+
+*** =use-package=
+
+#+begin_quote
+A use-package declaration for simplifying your .emacs
+#+end_quote
+
+=use-package= is an awesome utility for managing and configuring
+packages in a neatly organized way and without compromising on
+performance. So let's install it using =striaght.el= and have it use
+=straight.el= for installing packages.
+
+#+begin_src emacs-lisp
+(straight-use-package 'use-package)
+(setq straight-use-package-by-default t)
+#+end_src
+
+** No littering in =~/.emacs.d=
+
+#+begin_quote
+Help keeping ~/.emacs.d clean
+#+end_quote
+
+By default, even for Emacs' built-in packages, the configuration files
+and persistent data are all over the place. Use =no-littering= to help
+contain the mess.
+
+#+begin_src emacs-lisp
+(use-package no-littering
+  :demand t
+  :config
+  (savehist-mode 1)
+  (add-to-list 'savehist-additional-variables 'kill-ring)
+  (save-place-mode 1)
+  (setq auto-save-file-name-transforms
+        `((".*" ,(no-littering-expand-var-file-name "auto-save/") t))))
+#+end_src
+
+** Custom file (=custom.el=)
+
+I'm not planning on using the custom file much, but even so, I
+definitely don't want it mixing with =init.el=. So, here, let's give
+it it's own file.
+
+#+begin_src emacs-lisp
+(setq custom-file (no-littering-expand-etc-file-name "custom.el"))
+(when (file-exists-p custom-file)
+  (load custom-file))
+#+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
+
+* Config
+:PROPERTIES:
+:CUSTOM_ID: config
+:END:
+
+** Org
+
+#+begin_src emacs-lisp
+(setq org-src-tab-acts-natively t
+      org-src-preserve-indentation nil
+      org-edit-src-content-indentation 0)
+#+end_src
 
 * Footer
 
 * Footer
+:PROPERTIES:
+:CUSTOM_ID: footer
+:END:
 
 #+begin_src emacs-lisp :comments none
 
 #+begin_src emacs-lisp :comments none
-
 ;;; init.el ends here
 #+end_src
 ;;; init.el ends here
 #+end_src