dots

Personal dotfiles
git clone git://git.gormless.xyz/dots.git
Log | Files | Refs

config.org (33904B)


      1 #+TITLE: Emacs Config
      2 #+AUTHOR: Mitch Taylor
      3 #+Description: Mitch's custom emacs config
      4 
      5 * TABLE OF CONTENTS                                                     :TOC:
      6 - [[#package-management][PACKAGE MANAGEMENT]]
      7   - [[#setup-packageel-to-work-with-melpa][Setup package.el to work with MELPA.]]
      8   - [[#installing-use-package][Installing use-package]]
      9   - [[#evil-mode][Evil Mode]]
     10   - [[#general-keybindings][General Keybindings]]
     11 - [[#startup-performance][STARTUP PERFORMANCE]]
     12   - [[#garbage-collection][Garbage collection]]
     13   - [[#native-compil][Native Compil]]
     14 - [[#aesthetics][AESTHETICS]]
     15   - [[#all-the-icons][All the icons]]
     16   - [[#display-line-numbers-and-truncated-lines][Display Line Numbers and Truncated Lines]]
     17   - [[#fonts][Fonts]]
     18   - [[#gui-settings][GUI settings]]
     19   - [[#modeline][Modeline]]
     20   - [[#theme][Theme]]
     21 - [[#buffers-and-bookmarks][BUFFERS AND BOOKMARKS]]
     22 - [[#dashboard][DASHBOARD]]
     23   - [[#configuring-dashboard][Configuring Dashboard]]
     24   - [[#dashboard-in-emacsclient][Dashboard in Emacsclient]]
     25 - [[#default-browser][DEFAULT BROWSER]]
     26 - [[#delete-selection-mode][DELETE SELECTION MODE]]
     27 - [[#emojis][EMOJIS]]
     28 - [[#evaluate-elisp-expressions][EVALUATE ELISP EXPRESSIONS]]
     29 - [[#file-manager-dired][FILE MANAGER (DIRED)]]
     30   - [[#keybindings-to-open-dired][Keybindings To Open Dired]]
     31   - [[#keybindings-within-dired][Keybindings Within Dired]]
     32   - [[#keybindings-for-peep-dired-mode][Keybindings For Peep-Dired-Mode]]
     33 - [[#files][FILES]]
     34   - [[#file-related-keybindings][File-related Keybindings]]
     35   - [[#installing-some-useful-file-related-modules][Installing Some Useful File-related Modules]]
     36   - [[#useful-file-functions][Useful File Functions]]
     37   - [[#zooming-in-and-out][Zooming In and Out]]
     38 - [[#general-keybindings-1][GENERAL KEYBINDINGS]]
     39 - [[#ivy-counselswiper][IVY (COUNSEL/SWIPER)]]
     40   - [[#installing-ivy-and-basic-setup][Installing Ivy And Basic Setup]]
     41   - [[#making-m-x-great-again][Making M-x Great Again!]]
     42   - [[#ivy-posframe][Ivy-posframe]]
     43 - [[#language-support][LANGUAGE SUPPORT]]
     44 - [[#magit][MAGIT]]
     45 - [[#org-mode][ORG-MODE]]
     46   - [[#defining-a-few-things][Defining A Few Things]]
     47   - [[#enabling-org-bullets][Enabling Org Bullets]]
     48   - [[#org-link-abbreviations][Org Link Abbreviations]]
     49   - [[#org-todo-keywords][Org Todo Keywords]]
     50   - [[#source-code-block-tag-expansion][Source Code Block Tag Expansion]]
     51   - [[#source-code-block-syntax-highlighting][Source Code Block Syntax Highlighting]]
     52   - [[#automatically-create-table-of-contents][Automatically Create Table of Contents]]
     53   - [[#make-m-ret-not-add-blank-lines][Make M-RET Not Add Blank Lines]]
     54   - [[#org-export-to-manpage-format][Org Export To Manpage Format]]
     55   - [[#automatically-tangle][Automatically tangle]]
     56 - [[#perspective][PERSPECTIVE]]
     57 - [[#projectile][PROJECTILE]]
     58 - [[#registers][REGISTERS]]
     59 - [[#runtime-performance][RUNTIME PERFORMANCE]]
     60 - [[#scrolling][SCROLLING]]
     61 - [[#shells][SHELLS]]
     62   - [[#eshell][Eshell]]
     63   - [[#vterm][Vterm]]
     64 - [[#which-key][WHICH KEY]]
     65 - [[#writeroom-mode][WRITEROOM MODE]]
     66 
     67 * PACKAGE MANAGEMENT
     68 ** Setup package.el to work with MELPA.
     69 
     70   #+begin_src emacs-lisp
     71     (require 'package)
     72     (add-to-list 'package-archives
     73 		 '("melpa" . "https://melpa.org/packages/"))
     74     (package-refresh-contents)
     75     (package-initialize)
     76 
     77   #+end_src
     78   
     79 ** Installing use-package
     80 
     81    #+begin_src emacs-lisp
     82    ;; Bootstrap 'use-package'
     83    (eval-after-load 'gnutls
     84      '(add-to-list 'gnutls-trustfiles "/etc/ssl/cert.pem"))
     85    (unless (package-installed-p 'use-package)
     86      (package-refresh-contents)
     87      (package-install 'use-package))
     88    (eval-when-compile
     89      (require 'use-package))
     90    (require 'bind-key)
     91    (setq use-package-always-ensure t)
     92    #+end_src
     93 
     94 ** Evil Mode
     95 Evil is an extensible 'vi' layer for Emacs. It emulates the main features of Vim, and provides facilities for writing custom extensions.  Evil Collection is also installed since it adds 'evil' bindings to parts of Emacs that the standard Evil package does not cover, such as: calenda, help-mode adn ibuffer.
     96  
     97 #+begin_src emacs-lisp
     98 (use-package evil
     99   :init      ;; tweak evil's configuration before loading it
    100   (setq evil-want-integration t) ;; This is optional since it's already set to t by default.
    101   (setq evil-want-keybinding nil)
    102   (setq evil-vsplit-window-right t)
    103   (setq evil-split-window-below t)
    104   (evil-mode))
    105 (use-package evil-collection
    106   :after evil
    107   :config
    108   (setq evil-collection-mode-list '(dashboard dired ibuffer))
    109   (evil-collection-init))
    110 (use-package evil-tutor)
    111 #+end_src
    112 ** General Keybindings
    113 General.el allows us to set keybindings.  As a longtime Doom Emacs user, I have grown accustomed to using SPC as the prefix key.  General makes setting keybindings (especially with SPC) much easier.  All of the keybindings we set later in the config depend on general being loaded.
    114 
    115 #+begin_src emacs-lisp
    116 (use-package general
    117   :config
    118   (general-evil-setup t))
    119 #+end_src
    120 
    121 * STARTUP PERFORMANCE
    122   This section is where it make emacs faster to load.
    123 ** Garbage collection
    124 Makes startup faster by reducing the frequency of garbage collection
    125 #+begin_src emacs-lisp
    126 ;; Using garbage magic hack.
    127  (use-package gcmh
    128    :config
    129    (gcmh-mode 1))
    130 ;; Setting garbage collection threshold
    131 (setq gc-cons-threshold 402653184
    132       gc-cons-percentage 0.6)
    133 
    134 ;; Profile emacs startup
    135 (add-hook 'emacs-startup-hook
    136           (lambda ()
    137             (message "*** Emacs loaded in %s with %d garbage collections."
    138                      (format "%.2f seconds"
    139                              (float-time
    140                               (time-subtract after-init-time before-init-time)))
    141                      gcs-done)))
    142 
    143 ;; Silence compiler warnings as they can be pretty disruptive (setq comp-async-report-warnings-errors nil)
    144 #+end_src
    145 ** Native Compil
    146 #+begin_src emacs-lisp
    147 ;; Silence compiler warnings as they can be pretty disruptive
    148 (if (boundp 'comp-deferred-compilation)
    149     (setq comp-deferred-compilation nil)
    150     (setq native-comp-deferred-compilation nil))
    151 ;; In noninteractive sessions, prioritize non-byte-compiled source files to
    152 ;; prevent the use of stale byte-code. Otherwise, it saves us a little IO time
    153 ;; to skip the mtime checks on every *.elc file.
    154 (setq load-prefer-newer noninteractive)
    155 #+end_src
    156 
    157 * AESTHETICS
    158 
    159 ** All the icons
    160 This is an icon set that can be used with dashboard, dired, ibuffer and other Emacs programs.
    161   
    162 #+begin_src emacs-lisp
    163 (use-package all-the-icons)
    164 #+end_src
    165 
    166 ** Display Line Numbers and Truncated Lines
    167 #+begin_src emacs-lisp
    168 (global-display-line-numbers-mode 1)
    169 (global-visual-line-mode t)
    170 #+end_src
    171 
    172 ** Fonts
    173 
    174 #+begin_src emacs-lisp
    175 (set-face-attribute 'default nil :family "Spleen" :height 110)
    176 (set-face-attribute 'fixed-pitch nil :family "Spleen" :height 110)
    177 (set-face-attribute 'variable-pitch nil :family "IBM Plex Serif" :height 120)
    178 
    179 (add-to-list 'default-frame-alist '(font . "Spleen-11"))
    180 (set-face-attribute 'font-lock-comment-face nil
    181   :slant 'italic)
    182 (set-face-attribute 'font-lock-keyword-face nil
    183   :slant 'italic)
    184 (setq global-prettify-symbols-mode t)
    185 #+end_src
    186 
    187 ** GUI settings
    188 
    189 Disable menu, toolbar, and scrollbar
    190 #+begin_src emacs-lisp
    191   (menu-bar-mode -1)
    192   (tool-bar-mode -1)
    193   (scroll-bar-mode -1)
    194 #+end_src
    195 
    196 ** Modeline
    197 
    198 #+begin_src emacs-lisp
    199 (use-package spaceline)
    200 (spaceline-spacemacs-theme)
    201 #+end_src
    202 
    203 ** Theme
    204 
    205 #+begin_src emacs-lisp
    206 (use-package poet-theme)
    207 (add-hook 'text-mode-hook
    208            (lambda ()
    209             (variable-pitch-mode 1)))
    210 (load-theme 'poet-monochrome t)
    211 #+end_src
    212 
    213 * BUFFERS AND BOOKMARKS
    214 
    215 #+begin_src emacs-lisp
    216 (nvmap :prefix "SPC"
    217        "b b"   '(ibuffer :which-key "Ibuffer")
    218        "b c"   '(clone-indirect-buffer-other-window :which-key "Clone indirect buffer other window")
    219        "b k"   '(kill-current-buffer :which-key "Kill current buffer")
    220        "b n"   '(next-buffer :which-key "Next buffer")
    221        "b p"   '(previous-buffer :which-key "Previous buffer")
    222        "b B"   '(ibuffer-list-buffers :which-key "Ibuffer list buffers")
    223        "b K"   '(kill-buffer :which-key "Kill buffer"))
    224 (nvmap :prefix "SPC"
    225        "B a"   '(bookmark-set :whichkey "Add bookmark")
    226        "B l"   '(list-bookmarks :whichkey "List bookmarks"))
    227 #+end_src
    228 
    229 * DASHBOARD
    230 Emacs Dashboard is an extensible startup screen showing you recent files, bookmarks, agenda items and an Emacs banner.
    231 
    232 ** Configuring Dashboard
    233 
    234 #+begin_src emacs-lisp
    235 (use-package dashboard
    236   :init      ;; tweak dashboard config before loading it
    237   (setq dashboard-set-heading-icons t)
    238   (setq dashboard-set-file-icons t)
    239   (setq dashboard-banner-logo-title "For our blood and soil and youth!")
    240   ;;(setq dashboard-startup-banner 'logo) ;; use standard emacs logo as banner
    241   (setq dashboard-startup-banner "~/etc/emacs/emacs-banner.png")  ;; use custom image as banner
    242   (setq dashboard-center-content t) ;; set to 't' for centered content
    243   (setq dashboard-items '((recents . 5)
    244                           (agenda . 5 )
    245                           (bookmarks . 3)
    246                           (projects . 3)
    247                           (registers . 3)))
    248   :config
    249   (dashboard-setup-startup-hook)
    250   (dashboard-modify-heading-icons '((recents . "file-text")
    251 			      (bookmarks . "book"))))
    252 #+end_src
    253 
    254 ** Dashboard in Emacsclient
    255 This setting ensures that emacsclient always opens on *dashboard* rather than *scratch*.
    256 
    257 #+begin_src emacs-lisp
    258 (setq initial-buffer-choice (lambda () (get-buffer "*dashboard*")))
    259 #+end_src
    260 
    261 * DEFAULT BROWSER
    262 
    263 #+begin_src emacs-lisp
    264 (setq browse-url-browser-function 'browse-url-firefox)
    265 #+end_src
    266 
    267 * DELETE SELECTION MODE
    268 By default in Emacs, we don't have ability to select text, and then start typing and our new text replaces the selection.  Let's fix that!
    269 
    270 #+begin_src emacs-lisp
    271 (delete-selection-mode t)
    272 #+end_src
    273 
    274 * EMOJIS
    275 Emojify is an Emacs extension to display emojis. It can display github style emojis like :smile: or plain ascii ones like :). 
    276 
    277 #+begin_src emacs-lisp
    278 (use-package emojify
    279   :hook (after-init . global-emojify-mode))
    280 #+end_src
    281 
    282 * EVALUATE ELISP EXPRESSIONS
    283 I choose to use the format 'SPC e' plus 'key' for these (I also use 'SPC e' for 'eww' keybindings).
    284 
    285 | COMMAND         | DESCRIPTION                                    | KEYBINDING |
    286 |-----------------+------------------------------------------------+------------|
    287 | eval-buffer     | /Evaluate elisp in buffer/                       | SPC e b    |
    288 | eval-defun      | /Evaluate the defun containing or after point/   | SPC e d    |
    289 | eval-expression | /Evaluate an elisp expression/                   | SPC e e    |
    290 | eval-last-sexp  | /Evaluate elisp expression before point/         | SPC e l    |
    291 | eval-region     | /Evaluate elisp in region/                       | SPC e r    |
    292 
    293 #+begin_src emacs-lisp
    294 (nvmap :states '(normal visual) :keymaps 'override :prefix "SPC"
    295        "e b"   '(eval-buffer :which-key "Eval elisp in buffer")
    296        "e d"   '(eval-defun :which-key "Eval defun")
    297        "e e"   '(eval-expression :which-key "Eval elisp expression")
    298        "e l"   '(eval-last-sexp :which-key "Eval last sexression")
    299        "e r"   '(eval-region :which-key "Eval region"))
    300 #+end_src
    301   
    302 * FILE MANAGER (DIRED)
    303 Dired is the file manager within Emacs.  Below, I setup keybindings for image previews (peep-dired).  I've chosen the format of 'SPC d' plus 'key'.
    304 
    305 ** Keybindings To Open Dired
    306 | COMMAND    | DESCRIPTION                        | KEYBINDING |
    307 |------------+------------------------------------+------------|
    308 | dired      | /Open dired file manager/            | SPC d d    |
    309 | dired-jump | /Jump to current directory in dired/ | SPC d j    |
    310 
    311 ** Keybindings Within Dired
    312 | COMMAND            | DESCRIPTION                                 | KEYBINDING |
    313 |--------------------+---------------------------------------------+------------|
    314 | dired-view-file    | /View file in dired/                          | SPC d v    |
    315 | dired-up-directory | /Go up in directory tree/                     | h          |
    316 | dired-find-file    | /Go down in directory tree (or open if file)/ | l          |
    317 
    318 ** Keybindings For Peep-Dired-Mode
    319 | COMMAND              | DESCRIPTION                              | KEYBINDING |
    320 |----------------------+------------------------------------------+------------|
    321 | peep-dired           | /Toggle previews within dired/             | SPC d p    |
    322 | peep-dired-next-file | /Move to next file in peep-dired-mode/     | j          |
    323 | peep-dired-prev-file | /Move to previous file in peep-dired-mode/ | k          |
    324 
    325 #+begin_src emacs-lisp
    326 (use-package all-the-icons-dired)
    327 (use-package dired-open)
    328 (use-package peep-dired)
    329 
    330 (nvmap :states '(normal visual) :keymaps 'override :prefix "SPC"
    331                "d d" '(dired :which-key "Open dired")
    332                "d j" '(dired-jump :which-key "Dired jump to current")
    333                "d p" '(peep-dired :which-key "Peep-dired"))
    334 
    335 (with-eval-after-load 'dired
    336   ;;(define-key dired-mode-map (kbd "M-p") 'peep-dired)
    337   (evil-define-key 'normal dired-mode-map (kbd "h") 'dired-up-directory)
    338   (evil-define-key 'normal dired-mode-map (kbd "l") 'dired-open-file) ; use dired-find-file instead if not using dired-open package
    339   (evil-define-key 'normal peep-dired-mode-map (kbd "j") 'peep-dired-next-file)
    340   (evil-define-key 'normal peep-dired-mode-map (kbd "k") 'peep-dired-prev-file))
    341 
    342 (add-hook 'peep-dired-hook 'evil-normalize-keymaps)
    343 ;; Get file icons in dired
    344 (add-hook 'dired-mode-hook 'all-the-icons-dired-mode)
    345 ;; With dired-open plugin, you can launch external programs for certain extensions
    346 ;; For example, I set all .png files to open in 'sxiv' and all .mp4 files to open in 'mpv'
    347 (setq dired-open-extensions '(("gif" . "sxiv")
    348                               ("jpg" . "sxiv")
    349                               ("png" . "sxiv")
    350                               ("mkv" . "mpv")
    351                               ("mp4" . "mpv")))
    352 #+end_src
    353 
    354 * FILES
    355 ** File-related Keybindings
    356 
    357 #+begin_src emacs-lisp
    358 (nvmap :states '(normal visual) :keymaps 'override :prefix "SPC"
    359        "."     '(find-file :which-key "Find file")
    360        "f f"   '(find-file :which-key "Find file")
    361        "f r"   '(counsel-recentf :which-key "Recent files")
    362        "f s"   '(save-buffer :which-key "Save file")
    363        "f u"   '(sudo-edit-find-file :which-key "Sudo find file")
    364        "f y"   '(dt/show-and-copy-buffer-path :which-key "Yank file path")
    365        "f C"   '(copy-file :which-key "Copy file")
    366        "f D"   '(delete-file :which-key "Delete file")
    367        "f R"   '(rename-file :which-key "Rename file")
    368        "f S"   '(write-file :which-key "Save file as...")
    369        "f U"   '(sudo-edit :which-key "Sudo edit file"))
    370 #+end_src
    371 
    372 ** Installing Some Useful File-related Modules
    373 Though 'recentf' is one way to find recent files although I prefer using 'counsel-recentf'.
    374 
    375 #+begin_src emacs-lisp
    376 (use-package recentf
    377   :config
    378   (recentf-mode))
    379 (use-package sudo-edit) ;; Utilities for opening files with sudo
    380 
    381 #+end_src
    382 
    383 ** Useful File Functions
    384 #+begin_src emacs-lisp
    385 (defun dt/show-and-copy-buffer-path ()
    386   "Show and copy the full path to the current file in the minibuffer."
    387   (interactive)
    388   ;; list-buffers-directory is the variable set in dired buffers
    389   (let ((file-name (or (buffer-file-name) list-buffers-directory)))
    390     (if file-name
    391         (message (kill-new file-name))
    392       (error "Buffer not visiting a file"))))
    393 (defun dt/show-buffer-path-name ()
    394   "Show the full path to the current file in the minibuffer."
    395   (interactive)
    396   (let ((file-name (buffer-file-name)))
    397     (if file-name
    398         (progn
    399           (message file-name)
    400           (kill-new file-name))
    401       (error "Buffer not visiting a file"))))
    402 #+end_src
    403 
    404 ** Zooming In and Out
    405 You can use the bindings CTRL plus =/- for zooming in/out.  You can also use CTRL plus the mouse wheel for zooming in/out.
    406 
    407 #+begin_src emacs-lisp
    408 ;; zoom in/out like we do everywhere else.
    409 (global-set-key (kbd "C-=") 'text-scale-increase)
    410 (global-set-key (kbd "C--") 'text-scale-decrease)
    411 (global-set-key (kbd "<C-wheel-up>") 'text-scale-increase)
    412 (global-set-key (kbd "<C-wheel-down>") 'text-scale-decrease)
    413 #+end_src
    414 
    415 * GENERAL KEYBINDINGS
    416 General.el allows us to set keybindings.  As a longtime Doom Emacs user, I have grown accustomed to using SPC as the prefix key.  It certainly is easier on the hands than constantly using CTRL for a prefix.
    417 
    418 #+begin_src emacs-lisp
    419 (nvmap :keymaps 'override :prefix "SPC"
    420        "SPC"   '(counsel-M-x :which-key "M-x")
    421        "c c"   '(compile :which-key "Compile")
    422        "c C"   '(recompile :which-key "Recompile")
    423        "h r r" '((lambda () (interactive) (load-file "~/etc/emacs/init.el")) :which-key "Reload emacs config")
    424        "t t"   '(toggle-truncate-lines :which-key "Toggle truncate lines"))
    425 (nvmap :keymaps 'override :prefix "SPC"
    426        "m *"   '(org-ctrl-c-star :which-key "Org-ctrl-c-star")
    427        "m +"   '(org-ctrl-c-minus :which-key "Org-ctrl-c-minus")
    428        "m ."   '(counsel-org-goto :which-key "Counsel org goto")
    429        "m e"   '(org-export-dispatch :which-key "Org export dispatch")
    430        "m f"   '(org-footnote-new :which-key "Org footnote new")
    431        "m h"   '(org-toggle-heading :which-key "Org toggle heading")
    432        "m i"   '(org-toggle-item :which-key "Org toggle item")
    433        "m n"   '(org-store-link :which-key "Org store link")
    434        "m o"   '(org-set-property :which-key "Org set property")
    435        "m t"   '(org-todo :which-key "Org todo")
    436        "m x"   '(org-toggle-checkbox :which-key "Org toggle checkbox")
    437        "m B"   '(org-babel-tangle :which-key "Org babel tangle")
    438        "m I"   '(org-toggle-inline-images :which-key "Org toggle inline imager")
    439        "m T"   '(org-todo-list :which-key "Org todo list")
    440        "o a"   '(org-agenda :which-key "Org agenda")
    441        )
    442 #+end_src
    443 
    444 * IVY (COUNSEL/SWIPER)
    445 Ivy, counsel and swiper are a generic completion mechanism for Emacs.  Ivy-rich allows us to add descriptions alongside the commands in M-x.
    446 
    447 ** Installing Ivy And Basic Setup
    448 #+begin_src emacs-lisp
    449 (use-package counsel
    450   :after ivy
    451   :config (counsel-mode))
    452 (use-package ivy
    453   :defer 0.1
    454   :diminish
    455   :bind
    456   (("C-c C-r" . ivy-resume)
    457    ("C-x B" . ivy-switch-buffer-other-window))
    458   :custom
    459   (setq ivy-count-format "(%d/%d) ")
    460   (setq ivy-use-virtual-buffers t)
    461   (setq enable-recursive-minibuffers t)
    462   :config
    463   (ivy-mode))
    464 (use-package ivy-rich
    465   :after ivy
    466   :custom
    467   (ivy-virtual-abbreviate 'full
    468    ivy-rich-switch-buffer-align-virtual-buffer t
    469    ivy-rich-path-style 'abbrev)
    470   :config
    471   (ivy-set-display-transformer 'ivy-switch-buffer
    472                                'ivy-rich-switch-buffer-transformer)
    473   (ivy-rich-mode 1)) ;; this gets us descriptions in M-x.
    474 (use-package swiper
    475   :after ivy
    476   :bind (("C-s" . swiper)
    477          ("C-r" . swiper)))
    478 #+end_src
    479 
    480 ** Making M-x Great Again!
    481 The following line removes the annoying '^' in things like counsel-M-x and other ivy/counsel prompts.  The default '^' string means that if you type something immediately after this string only completion candidates that begin with what you typed are shown.  Most of the time, I'm searching for a command without knowing what it begins with though.
    482 
    483 #+begin_src emacs-lisp
    484 (setq ivy-initial-inputs-alist nil)
    485 #+end_src
    486 
    487 Smex is a package the makes M-x remember our history.  Now M-x will show our last used commands first.
    488 #+begin_src emacs-lisp
    489 (use-package smex)
    490 (smex-initialize)
    491 #+end_src
    492 
    493 ** Ivy-posframe
    494 Ivy-posframe is an ivy extension, which lets ivy use posframe to show its candidate menu.  Some of the settings below involve:
    495 + ivy-posframe-display-functions-alist -- sets the display position for specific programs
    496 + ivy-posframe-height-alist -- sets the height of the list displayed for specific programs
    497 
    498 Available functions (positions) for 'ivy-posframe-display-functions-alist'
    499 + ivy-posframe-display-at-frame-center
    500 + ivy-posframe-display-at-window-center
    501 + ivy-posframe-display-at-frame-bottom-left
    502 + ivy-posframe-display-at-window-bottom-left
    503 + ivy-posframe-display-at-frame-bottom-window-center
    504 + ivy-posframe-display-at-point
    505 + ivy-posframe-display-at-frame-top-center
    506 
    507 =NOTE:= If the setting for 'ivy-posframe-display' is set to 'nil' (false), anything that is set to 'ivy-display-function-fallback' will just default to their normal position in Doom Emacs (usually a bottom split).  However, if this is set to 't' (true), then the fallback position will be centered in the window.
    508 
    509 #+begin_src emacs-lisp
    510   (use-package ivy-posframe
    511     :init
    512     (setq ivy-posframe-display-functions-alist
    513       '((swiper                     . ivy-posframe-display-at-point)
    514         (complete-symbol            . ivy-posframe-display-at-point)
    515         (counsel-M-x                . ivy-display-function-fallback)
    516         (counsel-esh-history        . ivy-posframe-display-at-window-center)
    517         (counsel-describe-function  . ivy-display-function-fallback)
    518         (counsel-describe-variable  . ivy-display-function-fallback)
    519         (counsel-find-file          . ivy-display-function-fallback)
    520         (counsel-recentf            . ivy-display-function-fallback)
    521         (counsel-register           . ivy-posframe-display-at-frame-bottom-window-center)
    522         (dmenu                      . ivy-posframe-display-at-frame-top-center)
    523         (nil                        . ivy-posframe-display))
    524       ivy-posframe-height-alist
    525       '((swiper . 20)
    526         (dmenu . 20)
    527         (t . 10)))
    528     :config
    529     (ivy-posframe-mode 1)) ; 1 enables posframe-mode, 0 disables it.
    530 #+end_src
    531 
    532 * LANGUAGE SUPPORT
    533 Adding packages for programming langauges, so we can have nice things like syntax highlighting.
    534 
    535 #+begin_src emacs-lisp
    536 (use-package markdown-mode)
    537 #+end_src
    538 
    539 * MAGIT
    540 A git client for Emacs.  Often cited as a killer feature for Emacs.
    541 
    542 #+begin_src emacs-lisp
    543 (setq bare-git-dir (concat "--git-dir=" (expand-file-name "~/.dotfiles")))
    544 (setq bare-work-tree (concat "--work-tree=" (expand-file-name "~")))
    545 ;; use maggit on git bare repos like dotfiles repos, don't forget to change `bare-git-dir' and `bare-work-tree' to your needs
    546 (defun me/magit-status-bare ()
    547   "set --git-dir and --work-tree in `magit-git-global-arguments' to `bare-git-dir' and `bare-work-tree' and calls `magit-status'"
    548   (interactive)
    549   (require 'magit-git)
    550   (add-to-list 'magit-git-global-arguments bare-git-dir)
    551   (add-to-list 'magit-git-global-arguments bare-work-tree)
    552   (call-interactively 'magit-status))
    553 
    554 ;; if you use `me/magit-status-bare' you cant use `magit-status' on other other repos you have to unset `--git-dir' and `--work-tree'
    555 ;; use `me/magit-status' insted it unsets those before calling `magit-status'
    556 (defun me/magit-status ()
    557   "removes --git-dir and --work-tree in `magit-git-global-arguments' and calls `magit-status'"
    558   (interactive)
    559   (require 'magit-git)
    560   (setq magit-git-global-arguments (remove bare-git-dir magit-git-global-arguments))
    561   (setq magit-git-global-arguments (remove bare-work-tree magit-git-global-arguments))
    562   (call-interactively 'magit-status))
    563 
    564 (use-package magit)
    565  #+end_src
    566 
    567 * ORG-MODE
    568 
    569 ** Defining A Few Things
    570 #+begin_src emacs-lisp
    571 (add-hook 'org-mode-hook 'org-indent-mode)
    572 (setq org-directory "~/usr/doc/"
    573       org-agenda-files '("~/usr/doc/agenda.org")
    574       org-default-notes-file (expand-file-name "notes.org" org-directory)
    575       org-ellipsis " ▼ "
    576       org-log-done 'time
    577       org-journal-dir "~/usr/doc/journal/"
    578       org-journal-date-format "%B %d, %Y (%A) "
    579       org-journal-file-format "%Y-%m-%d.org"
    580       org-hide-emphasis-markers t)
    581 (setq org-src-preserve-indentation nil
    582       org-src-tab-acts-natively t
    583       org-edit-src-content-indentation 0)
    584 #+end_src
    585 
    586 ** Enabling Org Bullets
    587 Org-bullets gives us attractive bullets rather than asterisks.
    588 
    589 #+begin_src emacs-lisp
    590 (use-package org-bullets)
    591 (add-hook 'org-mode-hook (lambda () (org-bullets-mode 1)))
    592 #+end_src
    593 
    594 ** Org Link Abbreviations
    595 This allows for the use of abbreviations that will get expanded out into a lengthy URL.
    596    
    597 #+begin_src emacs-lisp
    598 ;; An example of how this works.
    599 ;; [[arch-wiki:Name_of_Page][Description]]
    600 ;; [[openports:x11/dwm][test]]
    601 (setq org-link-abbrev-alist
    602         '(("openports" . "https://openports.se/")
    603           ("ddg" . "https://duckduckgo.com/?q=")
    604           ("wiki" . "https://en.wikipedia.org/wiki/")))
    605 #+end_src
    606 
    607 ** Org Todo Keywords
    608 This lets us create the various TODO tags that we can use in Org.
    609    
    610 #+begin_src emacs-lisp
    611   (setq org-todo-keywords        ; This overwrites the default Doom org-todo-keywords
    612           '((sequence
    613              "TODO(t)"           ; A task that is ready to be tackled
    614              "BLOG(b)"           ; Blog writing assignments
    615              "GYM(g)"            ; Things to accomplish at the gym
    616              "PROJ(p)"           ; A project that contains other tasks
    617              "VIDEO(v)"          ; Video assignments
    618              "WAIT(w)"           ; Something is holding up this task
    619              "|"                 ; The pipe necessary to separate "active" states and "inactive" states
    620              "DONE(d)"           ; Task has been completed
    621              "CANCELLED(c)" )))  ; Task has been cancelled
    622 #+end_src
    623 
    624 ** Source Code Block Tag Expansion
    625 Org-tempo is a package that allows for '<s' followed by TAB to expand to a begin_src tag.  Other expansions available include:
    626 
    627 | Typing the below + TAB | Expands to ...                          |
    628 |------------------------+-----------------------------------------|
    629 | <a                     | '#+BEGIN_EXPORT ascii' … '#+END_EXPORT  |
    630 | <c                     | '#+BEGIN_CENTER' … '#+END_CENTER'       |
    631 | <C                     | '#+BEGIN_COMMENT' … '#+END_COMMENT'     |
    632 | <e                     | '#+BEGIN_EXAMPLE' … '#+END_EXAMPLE'     |
    633 | <E                     | '#+BEGIN_EXPORT' … '#+END_EXPORT'       |
    634 | <h                     | '#+BEGIN_EXPORT html' … '#+END_EXPORT'  |
    635 | <l                     | '#+BEGIN_EXPORT latex' … '#+END_EXPORT' |
    636 | <q                     | '#+BEGIN_QUOTE' … '#+END_QUOTE'         |
    637 | <s                     | '#+BEGIN_SRC' … '#+END_SRC'             |
    638 | <v                     | '#+BEGIN_VERSE' … '#+END_VERSE'         |
    639 
    640 #+begin_src emacs-lisp
    641 (use-package org-tempo
    642   :ensure nil) ;; tell use-package not to try to install org-tempo since it's already there.
    643 #+end_src
    644 
    645 ** Source Code Block Syntax Highlighting
    646 We want the same syntax highlighting in source blocks as in the native language files.
    647 
    648 #+begin_src emacs-lisp
    649 (setq org-src-fontify-natively t
    650     org-src-tab-acts-natively t
    651     org-confirm-babel-evaluate nil
    652     org-edit-src-content-indentation 0)
    653 #+end_src
    654 
    655 ** Automatically Create Table of Contents
    656 Toc-org helps you to have an up-to-date table of contents in org files without exporting (useful useful for README files on GitHub).  Use :TOC: to create the table.
    657 
    658 #+begin_src emacs-lisp
    659   (use-package toc-org
    660     :commands toc-org-enable
    661     :init (add-hook 'org-mode-hook 'toc-org-enable))
    662 #+end_src
    663 
    664 ** Make M-RET Not Add Blank Lines
    665 #+begin_src emacs-lisp
    666 (setq org-blank-before-new-entry (quote ((heading . nil)
    667                                          (plain-list-item . nil))))
    668 #+end_src
    669 
    670 ** Org Export To Manpage Format
    671 #+begin_src emacs-lisp
    672 (use-package ox-man
    673   :ensure nil)
    674 #+end_src
    675 
    676 ** Automatically tangle
    677 #+begin_src emacs-lisp
    678 (use-package org-auto-tangle
    679   :defer t
    680   :hook (org-mode . org-auto-tangle-mode))
    681 #+end_src
    682 
    683 * PERSPECTIVE
    684 The Perspective package provides multiple named workspaces (or "perspectives") in Emacs, similar to multiple desktops in window managers like Awesome and XMonad.  Each perspective has its own buffer list and its own window layout. This makes it easy to work on many separate projects without getting lost in all the buffers. Switching to a perspective activates its window configuration, and when in a perspective, only its buffers are available.
    685 
    686 #+begin_src emacs-lisp
    687 (use-package perspective
    688   :bind
    689   ("C-x C-b" . persp-list-buffers)   ; or use a nicer switcher, see below
    690   :config
    691   (persp-mode))
    692 #+end_src
    693 
    694 * PROJECTILE
    695 #+begin_src emacs-lisp
    696 (use-package projectile
    697   :config
    698   (projectile-global-mode 1))
    699 #+end_src
    700 
    701 * REGISTERS
    702 Emacs registers are compartments where you can save text, rectangles and positions for later use. Once you save text or a rectangle in a register, you can copy it into the buffer once or many times; once you save a position in a register, you can jump back to that position once or many times.  The default GNU Emacs keybindings for these commands (with the exception of counsel-register) involves 'C-x r' followed by one or more other keys.  I wanted to make this a little more user friendly, so I chose to replace the 'C-x r' part of the key chords with 'SPC r'.
    703 
    704 | COMMAND                          | DESCRIPTION                      | KEYBINDING |
    705 |----------------------------------+----------------------------------+------------|
    706 | copy-to-register                 | /Copy to register/                 | SPC r c    |
    707 | frameset-to-register             | /Frameset to register/             | SPC r f    |
    708 | insert-register                  | /Insert contents of register/      | SPC r i    |
    709 | jump-to-register                 | /Jump to register/                 | SPC r j    |
    710 | list-registers                   | /List registers/                   | SPC r l    |
    711 | number-to-register               | /Number to register/               | SPC r n    |
    712 | counsel-register                 | /Interactively choose a register/  | SPC r r    |
    713 | view-register                    | /View a register/                  | SPC r v    |
    714 | window-configuration-to-register | /Window configuration to register/ | SPC r w    |
    715 | increment-register               | /Increment register/               | SPC r +    |
    716 | point-to-register                | /Point to register/                | SPC r SPC  |
    717 
    718 #+begin_src emacs-lisp
    719 (nvmap :prefix "SPC"
    720        "r c"   '(copy-to-register :which-key "Copy to register")
    721        "r f"   '(frameset-to-register :which-key "Frameset to register")
    722        "r i"   '(insert-register :which-key "Insert register")
    723        "r j"   '(jump-to-register :which-key "Jump to register")
    724        "r l"   '(list-registers :which-key "List registers")
    725        "r n"   '(number-to-register :which-key "Number to register")
    726        "r r"   '(counsel-register :which-key "Choose a register")
    727        "r v"   '(view-register :which-key "View a register")
    728        "r w"   '(window-configuration-to-register :which-key "Window configuration to register")
    729        "r +"   '(increment-register :which-key "Increment register")
    730        "r SPC" '(point-to-register :which-key "Point to register"))
    731 #+end_src
    732 
    733 * RUNTIME PERFORMANCE
    734 Dial the GC threshold back down so that garbage collection happens more frequently but in less time.
    735 #+begin_src emacs-lisp
    736 ;; Make gc pauses faster by decreasing the threshold.
    737 (setq gc-cons-threshold (* 2 1000 1000))
    738 #+end_src
    739 
    740 * SCROLLING
    741 Emacs' default scrolling is annoying because of the sudden half-page jumps.  Also, I wanted to adjust the scrolling speed.
    742 
    743 #+begin_src emacs-lisp
    744 (setq scroll-conservatively 101) ;; value greater than 100 gets rid of half page jumping
    745 (setq mouse-wheel-scroll-amount '(3 ((shift) . 3))) ;; how many lines at a time
    746 (setq mouse-wheel-progressive-speed t) ;; accelerate scrolling
    747 (setq mouse-wheel-follow-mouse 't) ;; scroll window under mouse
    748 #+end_src
    749 
    750 * SHELLS
    751 In my configs, all of my shells (bash, fish, zsh and the ESHELL) require my shell-color-scripts-git package to be installed.  On Arch Linux, you can install it from the AUR.  Otherwise, go to my shell-color-scripts repository on GitLab to get it.
    752 
    753 ** Eshell
    754 Eshell is an Emacs 'shell' that is written in Elisp.
    755 
    756 #+begin_src emacs-lisp
    757 (nvmap :prefix "SPC"
    758        "e h"   '(counsel-esh-history :which-key "Eshell history")
    759        "e s"   '(eshell :which-key "Eshell"))
    760 #+end_src
    761 
    762 + 'eshell-rc-script' -- your profile for eshell; like a bashrc for eshell.
    763 + 'eshell-aliases-file' -- sets an aliases file for the eshell.
    764   
    765 #+begin_src emacs-lisp
    766 (use-package eshell-syntax-highlighting
    767   :after esh-mode)
    768 
    769 (setq eshell-rc-script (concat user-emacs-directory "eshell/profile")
    770       eshell-aliases-file (concat user-emacs-directory "eshell/aliases")
    771       eshell-history-size 5000
    772       eshell-buffer-maximum-lines 5000
    773       eshell-hist-ignoredups t
    774       eshell-scroll-to-bottom-on-input t
    775       eshell-destroy-buffer-when-process-dies t
    776       eshell-visual-commands'("ksh" "ssh" "top"))
    777 #+end_src
    778 
    779 ** Vterm
    780 Vterm is a terminal emulator within Emacs.  The 'shell-file-name' setting sets the shell to be used in M-x shell, M-x term, M-x ansi-term and M-x vterm.  By default, the shell is set to 'ksh but could change it to 'bash' or 'zsh' if you prefer.
    781 
    782 #+begin_src emacs-lisp
    783 (use-package vterm)
    784 (setq shell-file-name "/bin/ksh"
    785       vterm-max-scrollback 5000)
    786 #+end_src
    787 
    788 #+begin_src emacs-lisp
    789 (nvmap :prefix "SPC"
    790        "v"   '(vterm :which-key "Vterm"))
    791 #+end_src
    792 
    793 * WHICH KEY
    794 Which-key is a minor mode for Emacs that displays the key bindings following your currently entered incomplete command (a prefix) in a popup.
    795 
    796 =NOTE:= Which-key has an annoying bug that in some fonts and font sizes, the bottom row in which key gets covered up by the modeline.
    797 
    798 #+begin_src emacs-lisp
    799 (use-package which-key
    800   :init
    801   (setq which-key-side-window-location 'bottom
    802         which-key-sort-order #'which-key-key-order-alpha
    803         which-key-sort-uppercase-first nil
    804         which-key-add-column-padding 1
    805         which-key-max-display-columns nil
    806         which-key-min-display-lines 6
    807         which-key-side-window-slot -10
    808         which-key-side-window-max-height 0.25
    809         which-key-idle-delay 0.8
    810         which-key-max-description-length 25
    811         which-key-allow-imprecise-window-fit t
    812         which-key-separator " → " ))
    813 (which-key-mode)
    814 #+end_src
    815 
    816 * WRITEROOM MODE
    817 A minor mode for Emacs that implements a distraction-free writing mode similar to the famous Writeroom editor for OS X.
    818 
    819 #+begin_src emacs-lisp
    820 (use-package writeroom-mode)
    821 #+end_src