added some more annotations

This commit is contained in:
ndwarshuis 2018-12-12 00:59:34 -05:00
parent 334a208c52
commit c63315f2fd
1 changed files with 53 additions and 16 deletions

View File

@ -1,19 +1,40 @@
* overview * overview
This is my personal emacs config which currently runs on emacs 26.1 (currently the latest package from the Arch Linux official repos). ** purpose and usage
This is my personal emacs config.
I use this for a variety of purposes: I use this for a variety of purposes:
- maintaining my todo list/[[https://en.wikipedia.org/wiki/Getting_Things_Done][GTD]] workflow (org mode) - maintaining my todo list/[[https://en.wikipedia.org/wiki/Getting_Things_Done][GTD]] workflow (org mode)
- unified interface for system administration (dired, shell, git, ediff) - unified interface for system administration (dired, shell, git, ediff)
- email (mu4e, work in progress) - email (mu4e)
- editing some of my favorite languages (R, Lisp, Haskell, Lua, Python) - writing some of my favorite languages (R, Lisp, Haskell, Lua, Python)
- document preparation (latex)
** for new users
Feel free to take bits and pieces for your own configuration file. Like many things in emacs, the config file is quite self documenting; however, there are some useful ramblings that decribe why I made some design choices over others. As someone who learned from countless emacs configs of other experienced users, I thought it was extremely beneficial to see the thought process behind their workflow and code, and I hope my annotations pay that forward. Finally, please don't just blindly copy this config into your =~/.emacs.d=. I don't care if you do, but you will learn more if you build from scratch.
** config structure
The "config file" is actually several files.
The "root" is =init.el= which is the file explicitly loaded by emacs. The =init.el= is sometimes the only file people use, but my configuration became so huge I decided to split it in several files to maintain sanity. =init.el= currently has minimum functionality, including setting the repositories, configuring the package =use-package= (which installs all other packages and ensures they are available if I move this config elsewhere), and load paths for the other config files as explained below. Basically, it's a bootloader for bigger, better config files.
Once loaded, the =init.el= pulls in another file called =main.el= from the =conf= directory with the function =org-babel-load-file=. =main.el= is actually sourced from an [[https://en.wikipedia.org/wiki/Org-mode][org]] file, which allows markdown and annotations surrounding each block of lisp code. Since github is awesome and understands org files as a valid markdown format, all readme files (including this one) are actually org file.
After =main.el= is loaded, it may pull in a number of other files that I deemed big enough to separate (again using the =org-babel-load-file= function). Each .el/.org file that is included is stored in a separate directory under =conf=; navigate to these directories to see the file in readme format as you are reading this one.
* includes
These is general code that is used throughout the config file. Stored in another file for brevity.
#+BEGIN_SRC emacs-lisp
(org-babel-load-file (expand-file-name "lib/lib.org" nd/conf-dir))
#+END_SRC
* ui * ui
** theme ** theme
This theme has good functionality for many different modes without being over-the-top or overly complex. It also comes with an easy way to set custom colors.
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(use-package spacemacs-theme (use-package spacemacs-theme
:defer t :defer t
:config :config
(setq spacemacs-theme-custom-colors '((lnum . "#64707c")))) (setq spacemacs-theme-custom-colors '((lnum . "#64707c"))))
#+END_SRC
Since I run emacs in [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html][client/server]] mode, the loaded theme can change depending on if the client is a terminal or server (terminals have far fewer colors). This makes the theme reset when terminal is loaded before gui or vice versa.
#+BEGIN_SRC emacs-lisp
(defvar nd/theme 'spacemacs-dark) (defvar nd/theme 'spacemacs-dark)
(defvar nd/theme-window-loaded nil) (defvar nd/theme-window-loaded nil)
(defvar nd/theme-terminal-loaded nil) (defvar nd/theme-terminal-loaded nil)
@ -41,6 +62,7 @@ I use this for a variety of purposes:
(setq nd/theme-terminal-loaded t)))) (setq nd/theme-terminal-loaded t))))
#+END_SRC #+END_SRC
** modeline ** modeline
This modeline goes along with the =spacemacs-theme=. It also has nice integration with =evil-mode= (see keybindings below).
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(use-package spaceline (use-package spaceline
:ensure t :ensure t
@ -54,33 +76,32 @@ I use this for a variety of purposes:
(column-number-mode 1) (column-number-mode 1)
#+END_SRC #+END_SRC
*** delight *** delight
Used to hide minor modes on the modeline I like to keep the modeline clean and uncluttered. This package prevents certain mode names from showing in the modeline (it also has support for =use-package= through the =:delight= keyword)
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(use-package delight (use-package delight
:ensure t) :ensure t)
#+END_SRC #+END_SRC
** clean the interface ** clean the interface
No need for startup screen, tool/menu/scrollbars, or backups Emacs comes with some useless garbage by default. IMHO (in my haughty opinion), text editors should be boxes with text in them. No menu bars, scroll bars, or toolbars (and certainly no ribbons). Also, I don't need the startup screen; scratch buffer is fine.
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(setq inhibit-startup-screen t) (setq inhibit-startup-screen t)
(tool-bar-mode -1) (tool-bar-mode -1)
(menu-bar-mode -1) (menu-bar-mode -1)
(scroll-bar-mode -1) (scroll-bar-mode -1)
(setq make-backup-files nil)
(setq auto-save-default nil)
#+END_SRC #+END_SRC
** other enhancements ** other enhancements
*** popup windows *** popup windows
Some modes like to make popup windows (eg ediff). This prevents that.
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(setq pop-up-windows nil) ; no popups (eg ediff) (setq pop-up-windows nil)
#+END_SRC #+END_SRC
*** line wrap *** line wrap
I don't like line wrap
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(set-default 'truncate-lines t) (set-default 'truncate-lines t)
#+END_SRC #+END_SRC
*** smooth scrolling *** smooth scrolling
This makes scrolling smoother
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(setq scroll-conservatively 100) (setq scroll-conservatively 100)
#+END_SRC #+END_SRC
@ -90,11 +111,19 @@ No need for startup screen, tool/menu/scrollbars, or backups
(imagemagick-register-types)) (imagemagick-register-types))
#+END_SRC #+END_SRC
*** yes-no prompt *** yes-no prompt
Some prompts require literal "yes" or "no" to decide action. Life is short and I would rather not waste keystrokes typing whole words. This makes all "yes/no" prompts only require "y" or "n."
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(defalias 'yes-or-no-p 'y-or-n-p) ; eliminate yes or no prompt on killing procs (defalias 'yes-or-no-p 'y-or-n-p)
#+END_SRC
*** autosave
Saving files continuously is actually really annoying and clutters my disk. Turn it off.
#+BEGIN_SRC emacs-lisp
(setq make-backup-files nil)
(setq auto-save-default nil)
#+END_SRC #+END_SRC
* packages * packages
** beacon ** beacon
This makes a nice glowy effect on the cursor when switching window focus. Very elegant way of saving time in finding where you left off.
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(use-package beacon (use-package beacon
:ensure t :ensure t
@ -103,6 +132,7 @@ No need for startup screen, tool/menu/scrollbars, or backups
(beacon-mode 1)) (beacon-mode 1))
#+END_SRC #+END_SRC
** whichkey ** whichkey
Everyone forgets keybindings. When typing a key chord, this will display a window with all possible completions and their commands.
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(use-package which-key (use-package which-key
:ensure t :ensure t
@ -111,6 +141,7 @@ No need for startup screen, tool/menu/scrollbars, or backups
(which-key-mode)) (which-key-mode))
#+END_SRC #+END_SRC
** helm ** helm
One of the best packages for emacs. Helm is basically a search and completion engine (other exanples being =ido-mode= and =ivy-mode=) which is mainly used for finding files and selecting commands (which are obviously used often). It also integrates well with many other modes such as =evil-mode= and =org-mode=.
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(use-package helm (use-package helm
:ensure t :ensure t
@ -140,6 +171,7 @@ No need for startup screen, tool/menu/scrollbars, or backups
:ensure t) :ensure t)
#+END_SRC #+END_SRC
** rainbow-delimiters ** rainbow-delimiters
This color-codes matching parenthesis. Enable pretty much everywhere.
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(use-package rainbow-delimiters (use-package rainbow-delimiters
:ensure t :ensure t
@ -152,6 +184,7 @@ No need for startup screen, tool/menu/scrollbars, or backups
(Tex-latex-mode . rainbow-delimiters-mode))) (Tex-latex-mode . rainbow-delimiters-mode)))
#+END_SRC #+END_SRC
** ace-window ** ace-window
This is an elegant window selector. It displays a number in the corner when activated, and windows may be chosen by pressing the corresponding number. Note that spacemacs fails to make the numbers look nice so the theme code is a workaround to make them smaller and prettier.
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(use-package ace-window (use-package ace-window
:ensure t :ensure t
@ -164,6 +197,7 @@ No need for startup screen, tool/menu/scrollbars, or backups
:box nil)))))) :box nil))))))
#+END_SRC #+END_SRC
** avy ** avy
Allows jumping to any character in any window with a few keystrokes. Goodbye mouse :)
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(use-package avy (use-package avy
:ensure t :ensure t
@ -171,11 +205,13 @@ No need for startup screen, tool/menu/scrollbars, or backups
(setq avy-background t)) (setq avy-background t))
#+END_SRC #+END_SRC
** sudo edit ** sudo edit
Allows opening a file with sudo elevation.
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(use-package sudo-edit (use-package sudo-edit
:ensure t) :ensure t)
#+END_SRC #+END_SRC
** undo tree ** undo tree
Displays undo history in a nice tree. Also dislays diff information.
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(use-package undo-tree (use-package undo-tree
:ensure t :ensure t
@ -185,6 +221,7 @@ No need for startup screen, tool/menu/scrollbars, or backups
(global-undo-tree-mode)) (global-undo-tree-mode))
#+END_SRC #+END_SRC
** fill-column-indicator ** fill-column-indicator
Displays a line at 80 characters as a guide for column width.
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(use-package fill-column-indicator (use-package fill-column-indicator
:ensure t :ensure t
@ -194,11 +231,13 @@ No need for startup screen, tool/menu/scrollbars, or backups
(prog-mode . fci-mode)) (prog-mode . fci-mode))
#+END_SRC #+END_SRC
** rainbow ** rainbow
Overlays hex color codes with matching colors in certain modes like css and html.
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(use-package rainbow-mode (use-package rainbow-mode
:ensure t) :ensure t)
#+END_SRC #+END_SRC
** async ** async
Allows certain processes to run in multithreaded manner. For things like IO this makes sense.
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(use-package async (use-package async
:ensure t :ensure t
@ -207,17 +246,20 @@ No need for startup screen, tool/menu/scrollbars, or backups
(dired-async-mode 1)) (dired-async-mode 1))
#+END_SRC #+END_SRC
** csv-mode ** csv-mode
This adds support for csv files. Almost makes them editable like a spreadsheet. The lambda function enables alignment by default.
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(use-package csv-mode (use-package csv-mode
:ensure t :ensure t
:hook (csv-mode . (lambda () (csv-align-fields nil (point-min) (point-max))))) :hook (csv-mode . (lambda () (csv-align-fields nil (point-min) (point-max)))))
#+END_SRC #+END_SRC
** markdown-mode ** markdown-mode
Added support for standard markdown files.
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(use-package markdown-mode (use-package markdown-mode
:ensure t) :ensure t)
#+END_SRC #+END_SRC
** polymode ** polymode
This allows multiple modes in one buffer. This may sound totally crazy...but it actually is. Despite it's hackiness, it actually makes alot of sense for some situations such as R markdown which requires yaml, markdown, and R code in one buffer.
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(use-package polymode (use-package polymode
:ensure t :ensure t
@ -229,11 +271,6 @@ No need for startup screen, tool/menu/scrollbars, or backups
(require 'poly-R) (require 'poly-R)
(require 'poly-markdown)) (require 'poly-markdown))
#+END_SRC #+END_SRC
* library
These is general code that is used throughout the config file. Stored in another file for brevity.
#+BEGIN_SRC emacs-lisp
(org-babel-load-file (expand-file-name "lib/lib.org" nd/conf-dir))
#+END_SRC
* editing * editing
** tabs and alignment ** tabs and alignment
First things first, don't use spaces and force tabs to 4 chars by default (because...let's compromise on things that don't matter since I am using spaces anyways) First things first, don't use spaces and force tabs to 4 chars by default (because...let's compromise on things that don't matter since I am using spaces anyways)