[emacs] add naming conventions

[~bandali/configs] / emacs / init.org

#+title: =aminb='s Emacs Init file
#+property: header-args :results silent :comments link :tangle ~/dotfiles/emacs/init.el

* Intro

TODO: description

* Contents                                                   :toc_1:noexport:

- [[#intro][Intro]]
- [[#header][Header]]
- [[#initial-setup][Initial setup]]
- [[#config][Config]]
- [[#footer][Footer]]

* Header
:PROPERTIES:
:CUSTOM_ID: header
:END:

** First line

#+begin_src emacs-lisp :comments none
;;; init.el --- Amin Bandali's Emacs config -*- lexical-binding: t ; eval: (view-mode 1)-*-
#+end_src

Enable =view-mode=, which both makes the file read-only (as a reminder
that =init.el= is an auto-generated file, not supposed to be edited),
and provides some convenient key bindings for browsing through the
file.

** License

#+begin_src emacs-lisp :comments none
;; Copyright (C) 2018  Amin Bandali <amin@aminb.org>

;; This program is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.

;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
#+end_src

** Commentary

#+begin_src emacs-lisp :comments none
;;; Commentary:

;; Emacs configuration of Amin Bandali, computer scientist and functional
;; programmer.

;; 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
;;   ab!...   a macro
#+end_src

* Initial setup
:PROPERTIES:
:CUSTOM_ID: initial-setup
:END:

#+begin_src emacs-lisp :comments none
;;; Code:
#+end_src

** 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
:PROPERTIES:
:CUSTOM_ID: footer
:END:

#+begin_src emacs-lisp :comments none
;;; init.el ends here
#+end_src