[Emacs] Add docstring and update some settings.

Hopefully this is the last time I 'batch commit' a large change that way.

1 files changed, 205 insertions, 148 deletions

diff --git a/emacs.d/init.el b/emacs.d/init.el
index 67ceecf..b9999e7 100644
--- a/emacs.d/init.el
+++ b/emacs.d/init.el
@@ -1,8 +1,13 @@
+;; when did we start this session ?
+(defconst emacs-start-time (current-time))
+
+;; setup packages
 (require 'package)
-(setq package-user-dir "~/.emacs.d/var/elpa"
+(setq package-user-dir (expand-file-name "var/elpa" user-emacs-directory)
       package-enable-at-startup nil
       package-archives (append package-archives
                                '(("melpa" . "https://melpa.milkbox.net/packages/"))))
+
 (package-initialize)
 
 (unless package-archive-contents
@@ -36,24 +41,45 @@
   (unless (server-running-p) (server-start)))
 
 (use-package  diminish
+  ;; remove clutter from the mode line
   :ensure t)
 
-;; other packages
 (use-package ag
+  ;; interface to the 'ag' tool
   :ensure t
+
+  :commands (counsel-ag
+	     ag)
   :init
   (setq ag-reuse-buffers t
         ag-reuse-window t))
 
+(use-package autorevert
+  ;; automatically revert the buffer if the content changed on disk
+  :diminish auto-revert-mode)
+
 (use-package counsel
+  ;; completion functions for ivy
   :ensure t
+
+  :bind*
+  (("M-x"     . counsel-M-x)
+   ("C-s"     . counsel-grep-or-swiper)
+   ("C-x C-f" . counsel-find-file)
+   ("C-x C-r" . counsel-recentf)
+   ("C-c f"   . counsel-git)
+   ("C-c s"   . counsel-git-grep)
+   ("C-c /"   . counsel-ag))
+
   :config
   (setq counsel-find-file-at-point t))
 
 (use-package dired
+  ;; configuration for dired
   :bind ("C-x C-d" . dired)
+
   :config
-  (let ((gls "/usr/local/bin/gls"))
+  (let ((gls "/opt/twitter/bin/gls"))
     (if (file-exists-p gls)
 	(setq insert-directory-program gls
               dired-listing-switches "-aBhl --group-directories-first")))
@@ -66,26 +92,44 @@
     (setq dired-omit-files
 	  (concat dired-omit-files "\\|^.DS_Store$\\|^.projectile$\\|^.git$"))))
 
+(use-package dockerfile-mode
+  ;; support for dockerfile mode
+  :ensure t)
+
 (use-package lisp-mode
+  ;; simple configuration for various lisp mode
   :config
   (add-hook 'emacs-lisp-mode-hook
             (lambda()
               (setq mode-name "λ"))))
 
-;; eshell configuration
+(use-package eldoc
+  ;; documentation with eldoc
+  :ensure t
+
+  :commands eldoc-mode
+
+  :diminish ""
+
+  :init
+  (add-hook 'emacs-lisp-mode-hook 'eldoc-mode)
+  (add-hook 'lisp-interaction-mode-hook 'eldoc-mode))
+
 (use-package eshell
+  ;; configuration for eshell
   :ensure t
+
   :bind ("C-x e" . eshell)
+
   :init
   (progn
+    (setq eshell-directory-name (expand-file-name "var/eshell/" user-emacs-directory))
     (add-hook 'eshell-mode-hook '(lambda ()(exec-path-from-shell-initialize)))
     (add-hook 'eshell-mode-hook (lambda ()
                                   (setenv "PAGER" "less")
                                   (setenv "EDITOR" "emacsclient"))))
-
   :config
   (progn
-    (setq eshell-aliases-file "~/.emacs.d/var/eshell/aliases")
     (use-package em-term
       :defer t
       :config
@@ -93,28 +137,31 @@
             eshell-visual-commands
             (append '("less" "tmux" "ssh" "htop" "top") eshell-visual-commands)))))
 
-;; environment fixup for macOS.
 (use-package exec-path-from-shell
+  ;; environment fixup for macOS.
   :ensure t
-  :commands (exec-path-from-shell-initialize
-             exec-path-from-shell-copy-env)
+
   :if (and (eq system-type 'darwin) (display-graphic-p))
+
   :init
   (setq exec-path-from-shell-check-startup-files nil)
+  (exec-path-from-shell-initialize)
+
   :config
-  (progn
-    (setq exec-path-from-shell-debug t)
-    (exec-path-from-shell-initialize)
-    (exec-path-from-shell-copy-envs '("PATH" "GOROOT" "GOPATH" "GEM_HOME" "GEM_PATH" "MY_RUBY_HOME"))))
+  (setq exec-path-from-shell-debug t))
 
 (use-package flycheck
+  ;; check syntax
   :ensure t
+
   :config
   (progn
     (use-package flycheck-pos-tip
       :ensure t
       :config
-      (setq flycheck-display-errors-function #'flycheck-pos-tip-error-messages))
+      (setq flycheck-display-errors-function #'flycheck-pos-tip-error-messages)
+      :init
+      (flycheck-pos-tip-mode))
 
     (add-hook 'prog-mode-hook 'flycheck-mode)
     (setq-default flycheck-disabled-checkers '(emacs-lisp-checkdoc))
@@ -126,106 +173,83 @@
            (buffer-file-name)
            (string-match "src/source/.*\.py$" (buffer-file-name))))
 
+    ;;; errors are reported like this:
+    ;;; E241:ERROR   <file name>:<line> <message>
     (flycheck-define-checker source-check
       "A syntax checker for python source code in Source, using `check.pex'"
       :command ("check.pex" source)
-    ;;; errors are reported like this:
-    ;;; E241:ERROR   <file name>:<line> <message>
       :error-patterns ((error line-start (id (1+ nonl)) ":ERROR" (1+ nonl) ":" line (message) line-end)
                        (warning line-start (id (1+ nonl)) ":WARNING" (1+ nonl) ":" line (message) line-end))
       :predicate check-source-predicate
       :modes (python-mode))
     (add-to-list 'flycheck-checkers 'source-check)
 
-    (defface fc/flycheck-error
-      '((t (:foreground "#f40000")))
-      "Face for flycheck error feedback in the modeline."
-      :group 'fc/flycheck)
-    (defface fc/flycheck-warning
-      '((t (:foreground "#724a09")))
-      "Face for flycheck warning feedback in the modeline."
-      :group 'fc/flycheck)
-    ;;; errors are reported like this:
-    ;;; E241:ERROR   <file name>:<line> <message>
-    (defface fc/flycheck-info
-      '((t (:foreground "#19baff")))
-      "Face for flycheck info feedback in the modeline."
-      :group 'fc/flycheck)
-    (defface fc/flycheck-success
-      '((t (:foreground "#2cb250")))
-      "Face for flycheck success feedback in the modeline."
-      :group 'fc/flycheck)
-
     (setq flycheck-mode-line
         '(:eval
           (pcase flycheck-last-status-change
-            (`running (propertize " ⟲ Running" 'face 'fc/flycheck-info))
-            (`errored (propertize " ⚠ Error" 'face 'fc/flycheck-error))
-            (`no-checker (propertize " ⚠ No Checker" 'face 'fc/flycheck-info))
-            (`suspicious (propertize " ⚠ Suspicious" 'face 'fc/flycheck-warning))
-            (`not-checked (propertize " ✖ Disabled" 'face 'fc/flycheck-info))
-            (`interrupted (propertize " ⚠ Interrupted" 'face 'fc/flycheck-warning))
+            (`running     " ⟲ Running")
+            (`errored     " ⚠ Error")
+            (`no-checker  " ⚠ No Checker")
+            (`suspicious  " ⚠ Suspicious")
+            (`not-checked " ✖ Disabled")
+            (`interrupted " ⚠ Interrupted")
             (`finished
              (let* ((error-counts (flycheck-count-errors flycheck-current-errors))
                     (no-errors (cdr (assq 'error error-counts)))
-                    (no-warnings (cdr (assq 'warning error-counts)))
-                    (face (cond (no-errors 'fc/flycheck-error)
-                                (no-warnings 'fc/flycheck-warning)
-                                (t 'fc/flycheck-success))))
-               (propertize (if (or no-errors no-warnings) (format " ✘ %s/%s Issues" (or no-errors 0) (or no-warnings 0)) " ✔ No Issues") 'face face))))))))
+                    (no-warnings (cdr (assq 'warning error-counts))))
+               (if (or no-errors no-warnings) (format " ✘ %s/%s Issues" (or no-errors 0) (or no-warnings 0)) " ✔ No Issues"))))))))
 
 (use-package flyspell
+  ;; check the spelling
   :ensure t
-  :diminish ""
+
   :init
   (progn
     (setq ispell-program-name "aspell"
           ispell-list-command "--list")
     (add-hook 'text-mode-hook 'flyspell-mode))
+
   :config
-  (use-package flyspell-correct-ivy
-      :ensure t
-      :bind ("C-:" . flyspell-correct-word-generic)))
+  (use-package flyspell-popup
+    :ensure t
+    :bind ("C-:" . flyspell-popup-correct)))
 
 (use-package geiser
+  ;; to work with various schemes
   :ensure t
+
   :config
   (progn
     (setq geiser-default-implementation 'racket
           geiser-racket-binary "~/src/devbox/racket/racket-repl.sh")))
 
 (use-package gist
+  ;; interface to gist.github.com
   :ensure t
   :bind ("C-c G" . gist-region-or-buffer))
 
 (use-package go-mode
+  ;; support for go
+  :mode (("\\.go\\'" . go-mode))
+
   :ensure t
-  :init
-  (progn
-    (use-package go-eldoc
-      :ensure t)
-    (use-package gotest
-      :ensure t)
-    (add-hook 'go-mode-hook
-              (lambda ()
-                (setenv "GO15VENDOREXPERIMENT" "1")
-                (go-eldoc-setup)
-                (add-hook 'before-save-hook 'gofmt-before-save)
-                (setq tab-width 4)))))
-
-(use-package helm
-  :ensure t
-  :bind (("C-c h l" . helm-resume))
-  :diminish " Ⓗ"
-  :init
-  (helm-mode 1)
-  (with-eval-after-load 'helm-config
-    (warn "`helm-config' loaded! Get rid of it ASAP!"))
+
   :config
-  ;; Split inside selected window with Helm
-  (setq helm-split-window-in-side-p t))
+   (when (memq window-system '(mac ns x))
+    (dolist (var '("GOPATH"))
+      (unless (getenv var)
+        (exec-path-from-shell-copy-env var))))
+   (use-package go-eldoc
+     :ensure t
+     :config
+     (add-hook 'go-mode-hook 'go-eldoc-setup))
+   (use-package gotest
+     :ensure t)
+   (add-hook 'before-save-hook 'gofmt-before-save)
+   (add-hook 'go-mode-hook (lambda () (setq-local tab-width 4))))
 
 (use-package ibuffer
+  ;; configuration for ibuffer
   :ensure t
   :defer t
   :bind ("C-x C-b" . ibuffer)
@@ -233,21 +257,20 @@
   (setq ibuffer-show-empty-filter-groups nil
         ibuffer-saved-filter-groups
         (quote (("default"
-                 ("repl"   (name . "repl"))
+                 ("dired"  (mode . dired-mode))
                  ("elisp"  (mode . emacs-lisp-mode))
-                 ("ruby"   (name . "^\\.rb$"))
+                 ("emacs"  (or (name . "^\\*.*\\*$") (mode . fundamental-mode)))
+                 ("go"     (mode . go-mode))
+                 ("java"   (mode . java-mode))
                  ("json"   (mode . json-mode))
-                 ("sh"     (mode . sh-mode))
                  ("lisp"   (mode . lisp-mode))
                  ("magit"  (mode . magit-mode))
+                 ("puppet" (mode . puppet-mode))
                  ("python" (mode . python-mode))
-                 ("java"   (mode . java-mode))
-                 ("go"     (mode . go-mode))
-                 ("text"   (mode . text-mode))
-                 ("dired"  (mode . dired-mode))
-                 ("emacs"  (or
-                            (name . "^\\*.*\\*$")
-                            (mode . fundamental-mode)))))))
+                 ("repl"   (name . "repl"))
+                 ("ruby"   (name . "^\\.rb$"))
+                 ("sh"     (mode . sh-mode))
+                 ("text"   (mode . text-mode))))))
 
   (add-hook 'ibuffer-mode-hook  ;; organise by filter-groups
             '(lambda ()
@@ -256,22 +279,22 @@
                (ibuffer-switch-to-saved-filter-groups "default"))))
 
 (use-package ivy
+  ;; completion system
+  :diminish (ivy-mode . "")
+
+  :bind ("C-c m" . ivy-switch-project)
+
   :config
   (ivy-mode 1)
-  (setq ivy-use-virtual-buffers t)
-  (setq ivy-height 10)
-  (setq ivy-count-format "(%d/%d) ")
-  (setq ivy-initial-inputs-alist nil)
-  ;; from https://github.com/company-mode/company-statistics
-  ;; ignore buffers in the ignore buffer list.
-  (setq ivy-use-ignore-default 'always)
-  (setq ivy-ignore-buffers '("company-statistics-cache.el" "company-statistics-autoload.el"))
-  ;; if ivy-flip is t, presents results on top of query.
-  (setq ivy-flip nil)
-  (setq ivy-re-builders-alist
-	'((swiper . ivy--regex-ignore-order)
-	  (t . ivy--regex-fuzzy)
-	  (t   . ivy--regex-ignore-order)))
+  (setq ivy-use-virtual-buffers t
+        ivy-height 10
+        ivy-count-format "(%d/%d) "
+        ivy-initial-inputs-alist nil
+        ivy-use-ignore-default 'always
+        ivy-ignore-buffers '("company-statistics-cache.el" "company-statistics-autoload.el")
+        ivy-re-builders-alist '((swiper . ivy--regex-ignore-order)
+                                (t      . ivy--regex-fuzzy)
+                                (t      . ivy--regex-ignore-order)))
 
   (defun ivy-switch-project ()
     (interactive)
@@ -283,8 +306,6 @@
        projectile-known-projects)
      :action #'projectile-switch-project-by-name))
 
-  (global-set-key (kbd "C-c m") 'ivy-switch-project)
-
   (ivy-set-actions
    'ivy-switch-project
    '(("d" dired "Open Dired in project's directory")
@@ -293,43 +314,69 @@
      ("r" projectile-remove-known-project "Remove project(s)"))))
 
 (use-package json-mode
+  ;; mode to support json files
   :ensure t
+
   :mode "\\.json\\'"
+
   :config
   (setq json-reformat:indent-width 2))
 
 (use-package magit
+  ;; interface to git
   :ensure t
-  :bind ("C-x g" . magit-status)
+
+  :bind (("C-x g s" . magit-status)
+         ("C-x g b" . magit-checkout))
+
+  :init
+  (progn
+    (setq magit-completing-read-function 'ivy-completing-read))
+
   :config
-  (add-hook 'magit-log-edit-mode-hook
-            #'(lambda ()
-                (set-fill-column 72)
-                (flyspell-mode))))
+  (progn
+    (global-git-commit-mode)
+    (use-package git-commit :ensure t :defer t)
+    (setq magit-display-buffer-function 'magit-display-buffer-fullframe-status-v1)
+    (add-hook 'magit-log-edit-mode-hook
+              #'(lambda ()
+                  (set-fill-column 72)
+                  (flyspell-mode)))))
 
 (use-package make-mode
+  ;; mode to support Makefile
   :config
   (add-hook 'makefile-mode-hook
             #'(lambda ()
-                (setq whitespace-style '(face trailing tabs))
-                (setq tab-width 2)
+                (setq whitespace-style '(face trailing tabs)
+                      tab-width 2)
                 (whitespace-mode))))
 
 (use-package markdown-mode
+  ;; mode to support files in the Markdown format
+  :ensure t
+
   :commands (markdown-mode gfm-mode)
-  :mode (("\\.md\\'"          . gfm-mode)
-         ("\\.markdown\\'"    . gfm-mode))
+
+  :mode (("\\.md\\'"       . gfm-mode)
+         ("\\.markdown\\'" . gfm-mode))
+
   :init (setq markdown-command "pandoc -f markdown_github -c https://goo.gl/OVmlwT --self-contained")
+
   :config
   (add-hook 'gfm-mode-hook 'visual-line-mode))
 
-(use-package midnight)
+(use-package midnight
+  ;; clean old buffers at midnight
+  :ensure t)
 
 (use-package pants
+  ;; interface to pants
   :load-path (lambda () (expand-file-name  "~/src/pants.el/"))
 
   :config
-  (setq pants-source-tree-root "/Users/fcuny/src/source"
+  (setq pants-completion-system 'ivy
+        pants-source-tree-root "/Users/fcuny/src/source"
         pants-bury-compilation-buffer t
         pants-extra-args "-q")
 
@@ -337,26 +384,50 @@
          ("C-c r" . pants-run-binary)
          ("C-c t" . pants-run-test)))
 
+(use-package phabricator
+  ;; interface to phabricator
+  :load-path (lambda () (expand-file-name  "~/src/phabricator.el/"))
+
+  :config
+  (setq diffusion-repo-prefix-list '(("source" "source"))))
+
 (use-package projectile
+  ;; library to interact with projects
   :ensure t
-  :diminish projectile-mode
+
+  :diminish ""
+
   :bind-keymap ("C-c p" . projectile-command-map)
 
+  :init
+  (add-hook 'after-init-hook #'projectile-global-mode)
+
   :config
-  (setq projectile-enable-caching t
+  (use-package counsel-projectile :ensure t)
+  (setq projectile-switch-project-action 'projectile-dired
+        projectile-enable-caching t
         projectile-completion-system 'ivy
         projectile-known-projects-file "~/.emacs.d/var/projectile-bookmarks.eld"
         projectile-cache-file "~/.emacs.d/var/projectile.cache")
-  (projectile-mode))
+  (add-to-list 'projectile-globally-ignored-files ".DS_Store"))
 
 (use-package puppet-mode
+  ;; mode to support puppet and work with puppet
   :ensure t
+
   :mode ("\\.pp\\'" . puppet-mode)
+
   :init (add-hook 'puppet-mode-hook 'flycheck-mode)
+
   :config
+  (when (memq window-system '(mac ns x))
+    (dolist (var '("GEM_HOME" "GEM_PATH" "MY_RUBY_HOME"))
+      (unless (getenv var)
+        (exec-path-from-shell-copy-env var))))
   (setq flycheck-puppet-lint-rc "/Users/fcuny/src/twitter-ops/utilities/puppet/.puppet-lint.rc"))
 
 (use-package python
+  ;; configuration for Python
   :mode(("\\.aurora$" . python-mode)
         ("BUILD$" . python-mode)
         ("\\.py$" . python-mode))
@@ -371,34 +442,30 @@
   (add-hook 'python-mode-hook 'color-identifiers-mode))
 
 (use-package recentf
+  ;; configuration for recentf, to interact with recent files
   :config
-  (setq recentf-save-file "~/.emacs.d/var/recentf"))
+  (setq recentf-save-file (expand-file-name "var/recentf" user-emacs-directory)))
 
 (use-package sh-script
+  ;; configuration to interact with shell scripts
   :mode ("bashrc" . sh-mode)
+
   :config
   (defun set-sh-mode-indent ()
     (setq sh-basic-offset 2
           sh-indentation 2))
-  (add-hook 'sh-mode-hook 'set-sh-mode-indent))
-
-(use-package shell-pop
-  :defer t
-  :ensure t
-  :bind ("C-:" . shell-pop)
-  :init
-  (progn
-    (setq-default shell-pop-shell-type '("eshell" "*eshell-pop*" (lambda nil (eshell))))
-    (setq-default shell-pop-window-height 30)
-    (setq-default shell-pop-full-span t)
-    (setq-default shell-pop-window-position "bottom")))
+  (add-hook 'sh-mode-hook 'set-sh-mode-indent)
+  (add-hook 'after-save-hook 'executable-make-buffer-file-executable-if-script-p))
 
 (use-package swiper
+  ;; install swiper
   :ensure t)
 
 (use-package term
+  ;; configuration to manage multiple terminals inside emacs
   :bind (("C-x t" . fc/open-term)
          ("C-x m" . fc/switch-to-term-buffer))
+
   :config
   (progn
     (defun fc/make-term (new-buffer-name cmd &rest switches)
@@ -433,37 +500,27 @@
                   :caller 'fc/find-term-buffers)))))
 
 (use-package thrift
+  ;; mode to work with thrift files
   :ensure t
+
   :mode ("\\.thrift\\'" . thrift-mode)
+
   :config
   (setq thrift-indent-level 2))
 
 (use-package tramp
+  ;; configuration for tramp
   :config
-  (setq tramp-default-method "ssh"))
+  (setq tramp-default-method "ssh"
+        tramp-persistency-file-name (expand-file-name "var/tramp" user-emacs-directory)))
 
 (use-package yaml-mode
+  ;; mode to work wity YAML files
   :ensure t
+
+  :init (add-hook 'yaml-mode-hook 'flycheck-mode)
+
   :mode ("\\.ya?ml\\'" . yaml-mode))
 
-;; some bindings
-(global-set-key (kbd "M-j") 'join-line)
-(global-set-key (kbd "<s-return>") 'toggle-frame-fullscreen)
-(define-key emacs-lisp-mode-map (kbd "C-c C-e") 'eval-buffer)
-(define-key emacs-lisp-mode-map (kbd "C-c C-r") 'eval-region)
-
-
-(custom-set-variables
- ;; custom-set-variables was added by Custom.
- ;; If you edit it by hand, you could mess it up, so be careful.
- ;; Your init file should contain only one such instance.
- ;; If there is more than one, they won't work right.
- '(package-selected-packages
-   (quote
-    (flycheck-pos-tip puppet-mode ag projectile magit multi-term shell-pop esh-opt em-term thrift json-mode helm gist flycheck exec-path-from-shell counsel use-package))))
-(custom-set-faces
- ;; custom-set-faces was added by Custom.
- ;; If you edit it by hand, you could mess it up, so be careful.
- ;; Your init file should contain only one such instance.
- ;; If there is more than one, they won't work right.
- )
+(fc/load-time emacs-start-time)
+(fc/emacs-is-ready)