Merge pull request #53 from dysmento/master

use dysmento's updatees

.gitignore

@@ -9,5 +9,11 @@ projectile.cache
 auto-save-list
 backups
 melpa-stable
+elpa
+custom.el
 archive-contents
 *.elc
+.cache
+recentf
+transient
+network-security.data

README.md

@@ -1,15 +1,3 @@
-# WARNING this does not work currently
-
-A lot has changed since I last put significant effort into this repo, and as a result this emacs
-config is broken. I hope to get it working again soon (as of 2022-04-02).
-
-If you're completely new to Clojure and emacs, I recommend using [Calva](https://calva.io/), a plugin
-for VSCode, rather than trying to learn both Clojure and Emacs at the same time. Other options:
-
-- [Practicalli Spacemacs](https://practical.li/spacemacs/)
-- [Cursive](https://cursive-ide.com/)
-- [Vim fireplace](https://github.com/tpope/vim-fireplace)
-
 # this is a Clojure-friendly emacs config
 
 If you're new to emacs, check out
@@ -30,33 +18,82 @@ If you're new to emacs, check out
    `emacs-for-clojure-book1`. Run `mv path/to/emacs-for-clojure-book1
    ~/.emacs.d`.
 
-Then open Emacs.
+Then open Emacs. The first time you start, it will take a few minutes,
+because it needs to download and install around fifty packages. You
+will see some warnings pop up, but they are only style suggestions for
+the packages being loaded.
+
+## Prerequisites
+Since you're working in Clojure, we assume you have it and its prerequisites 
+installed (see [this guide](https://clojure.org/guides/install_clojure) for 
+those instructions). Additionally, you're likely to want to have 
+[Leiningen](https://leiningen.org/) installed, since many many projects use 
+it for running builds, tests, and tasks.
+
+To support specific features of this emacs configuration, there are three more 
+prerequisites:
+
+1. [git](https://git-scm.com/) is the dominant system for source code
+   version control. There's a good chance it came installed with your operating
+   system of choice, but in case it didn't, you'll want it!
+2. [clojure-lsp](https://clojure-lsp.io/installation/) enables Find References,
+   live linting, and many more features.
+3. To get nice icons in your modeline, you need the fonts installed. After
+   startup the first time, run `M-x all-the-icons-install-fonts`. You will only 
+   need to do this once.
+
+### A Word About Project-Wide Search
+One of the capabilities that comes in very handy is searching for some text 
+across all the files within your project. You can use git for that with the following
+command: `M-x counsel-git-grep`. This works just fine, with the caveat that it 
+_must_ be in a directory version-controlled with git. There are quite a few
+alternative search utilities, but you'll have to install them separately. In 
+practice, you'll probably settle on one you like and use it exclusively. Here 
+are the links, along with the emacs command to invoke each:
+
+* [ack](https://beyondgrep.com/) `M-x counsel-ack`
+* [The Silver Searcher](https://github.com/ggreer/the_silver_searcher) `M-x
+  counsel-ag`
+* [The Platinum
+  Searcher](https://github.com/monochromegane/the_platinum_searcher) `M-x
+  counsel-pt`
+* [ripgrep](https://github.com/BurntSushi/ripgrep) `M-x counsel-rg`
+
+## Features
+This will allow you to edit Clojure files with syntax-aware
+highlighting and [structural
+editing](https://clojure.org/guides/structural_editing) 
+via paredit, which means it will keep all your delimiters for nested forms 
+balanced (think parens, square brackets, and curly braces). Check out [this animated
+guide](http://danmidwood.com/content/2014/11/21/animated-paredit.html)
+to paredit. It's one of those things that seems strange at first, but
+once you get used to it, you won't want to edit Clojure without it!
+
+Other excellent capabilities you'll want to know about include:
+
+* [CIDER](https://cider.mx/), a fully interactive Clojure environent
+* [clojure-lsp](https://clojure-lsp.io/), provides static analysis
+  features for Clojure, such as live style and syntax warnings
+* [Projectile](https://projectile.mx/), navigate and manage project
+  files
+* [Magit](https://magit.vc/), a complete interface to git
+* [Treemacs](https://github.com/Alexander-Miller/treemacs), a tree
+  layout file explorer
 
 ## Upgrading
+Each package we use gets updated by its authors, at whatever cadence works for
+them. It's a good idea to stay up-to-date, to get improvements and bug
+fixes. It's analogous to keeping the software up-to-date in your operating
+system.
 
-Before upgrading, ensure that your `.emacs.d` directory is under
-version control so that you can always revert to a known good state.
-
-To upgrade:
-
-1. Edit `.emacs.d/init.el`, adding these lines after line 12:
-
-   ```elisp
-   (add-to-list 'package-archives
-                '("melpa-stable" . "http://stable.melpa.org/packages/") t)
-   
-   (add-to-list 'package-pinned-packages '(cider . "melpa-stable") t)
-   ```
-
-2. Close Emacs.
-3. Run `rm -Rf .emacs.d/elpa/cider-*`
-4. Open Emacs. You'll probably see some errors and your theme won't
-   load. That's ok.
-5. In Emacs, run `M-x package-refresh-contents`.
-6. In Emacs, run `M-x package-install cider`.
-7. Close and re-open Emacs.
+When you run `M-x list-packages` it refreshes the cache of all the package
+repositories, and then tells you in the status line whether there are any
+updates to install. Press `U` to mark all upgradeable packages for installation,
+and then press `x` to execute the installation. You will be prompted to confirm,
+and when you press `y` the package updates will be installed. Press `q` to exit
+the package list when it's finished.
 
-That should install the latest version. Enjoy!
+If you ever get curious to look, you can find all the installed packages in `~/.emacs.d/elpa`.
 
 ## Organization
 
@@ -68,16 +105,24 @@ what's going on.
 
 ## Supporting CSS, HTML, JS, etc.
 
-Emacs has decent support for CSS, HTML, JS, and many other file types out of the box, but if you want better support, then have a look at [my personal emacs config's init.el](https://github.com/flyingmachine/emacs.d/blob/master/init.el). It's meant to read as a table of contents. The emacs.d as a whole adds the following:
+Emacs has decent support for CSS, HTML, JS, and many other file types
+out of the box, but if you want better support, then have a look at 
+[my personal emacs config's
+init.el](https://github.com/flyingmachine/emacs.d/blob/master/init.el). 
+It's meant to read as a table of contents. The emacs.d as a whole adds the following:
 
 * [Customizes js-mode and html editing](https://github.com/flyingmachine/emacs.d/blob/master/customizations/setup-js.el)
     * Sets indentation level to 2 spaces for JS
     * enables subword-mode so that M-f and M-b break on capitalization changes
     * Uses `tagedit` to give you paredit-like functionality when editing html
     * adds support for coffee mode
-* [Uses enh-ruby-mode for ruby editing](https://github.com/flyingmachine/emacs.d/blob/master/customizations/setup-ruby.el). enh-ruby-mode is a little nicer than the built-in ruby-mode, in my opinion.
+* [Uses enh-ruby-mode for ruby
+editing](https://github.com/flyingmachine/emacs.d/blob/master/customizations/setup-ruby.el). 
+enh-ruby-mode is a little nicer than the built-in ruby-mode, in my opinion.
     * Associates many filenames and extensions with enh-ruby-mode (.rb, .rake, Rakefile, etc)
     * Adds keybindings for running specs
 * Adds support for YAML and SCSS using the yaml-mode and scss-mode packages
 
-In general, if you want to add support for a language then you should be able to find good instructions for it through Google. Most of the time, you'll just need to install the "x-lang-mode" package for it.
+In general, if you want to add support for a language then you should
+be able to find good instructions for it through Google. Most of the
+time, you'll just need to install the "x-lang-mode" package for it.

customizations/editing.el

@@ -18,21 +18,27 @@
 ;; Highlight current line
 (global-hl-line-mode 1)
 
-;; Interactive search key bindings. By default, C-s runs
-;; isearch-forward, so this swaps the bindings.
-(global-set-key (kbd "C-s") 'isearch-forward-regexp)
-(global-set-key (kbd "C-r") 'isearch-backward-regexp)
-(global-set-key (kbd "C-M-s") 'isearch-forward)
-(global-set-key (kbd "C-M-r") 'isearch-backward)
+;; line numbers
+(global-display-line-numbers-mode 1)
+;; but not everywhere
+(dolist (mode '(org-mode-hook
+                term-mode-hook
+                shell-mode-hook
+                treemacs-mode-hook
+                eshell-mode-hook))
+  (add-hook mode (lambda () (display-line-numbers-mode 0))))
 
 ;; Don't use hard tabs
 (setq-default indent-tabs-mode nil)
 
+;; shell scripts
+(setq-default sh-basic-offset 2
+              sh-indentation 2)
+
 ;; When you visit a file, point goes to the last place where it
 ;; was when you previously visited the same file.
 ;; http://www.emacswiki.org/emacs/SavePlace
-(require 'saveplace)
-(setq-default save-place t)
+(save-place-mode 1)
 ;; keep track of saved places in ~/.emacs.d/places
 (setq save-place-file (concat user-emacs-directory "places"))
 
@@ -43,7 +49,6 @@
                                                "backups"))))
 (setq auto-save-default nil)
 
-
 ;; comments
 (defun toggle-comment-on-line ()
   "comment or uncomment current line"

customizations/elisp-editing.el

@@ -1,15 +1,22 @@
-;; Automatically load paredit when editing a lisp file
-;; More at http://www.emacswiki.org/emacs/ParEdit
-(autoload 'enable-paredit-mode "paredit" "Turn on pseudo-structural editing of Lisp code." t)
-(add-hook 'emacs-lisp-mode-hook       #'enable-paredit-mode)
-(add-hook 'eval-expression-minibuffer-setup-hook #'enable-paredit-mode)
-(add-hook 'ielm-mode-hook             #'enable-paredit-mode)
-(add-hook 'lisp-mode-hook             #'enable-paredit-mode)
-(add-hook 'lisp-interaction-mode-hook #'enable-paredit-mode)
-(add-hook 'scheme-mode-hook           #'enable-paredit-mode)
+;; paredit enables structural editing of just about any lisp
+;; https://www.emacswiki.org/emacs/ParEdit
+(setup (:package paredit)
+  (:hook-into emacs-lisp-mode
+	      eval-expression-minibuffer-setup
+	      ielm-mode
+	      lisp-mode
+	      lisp-interaction-mode
+	      scheme-mode))
 
-;; eldoc-mode shows documentation in the minibuffer when writing code
-;; http://www.emacswiki.org/emacs/ElDoc
-(add-hook 'emacs-lisp-mode-hook 'turn-on-eldoc-mode)
-(add-hook 'lisp-interaction-mode-hook 'turn-on-eldoc-mode)
-(add-hook 'ielm-mode-hook 'turn-on-eldoc-mode)
+(setup turn-on-eldoc-mode
+  (:hook-into emacs-lisp-mode
+	 lisp-interaction-mode
+	 iel-mode))
+
+;; rainbow-delimiters makes nested parentheses easier to
+;; follow by showing each pair in its own color.
+;; Depending on your theme, the colors might be very subtle,
+;; and not very rainbow!
+;; https://github.com/Fanael/rainbow-delimiters
+(setup (:package rainbow-delimiters)
+  (:hook-into prog-mode))

customizations/filetree.el

@@ -0,0 +1,6 @@
+;; treemacs is a tree layout file explorer
+;; https://github.com/Alexander-Miller/treemacs
+(setup (:package treemacs treemacs-projectile treemacs-magit)
+  (:global "M-0" treemacs-select-window
+           "M-o" ace-window ;; treemacs brings ace-window as a dependency
+           "s-b" treemacs))

customizations/git.el

@@ -0,0 +1,5 @@
+;; magit is a full-fledged interface for git
+;; https://magit.vc/manual/magit/
+(add-to-list 'package-pinned-packages '(magit . "melpa-stable") t)
+(setup (:package magit)
+  (:global "C-M-;" magit-status))

customizations/navigation.el

@@ -1,62 +1,33 @@
 ;; These customizations make it easier for you to navigate files,
 ;; switch buffers, and choose options from the minibuffer.
 
-
-;; "When several buffers visit identically-named files,
-;; Emacs must give the buffers distinct names. The usual method
-;; for making buffer names unique adds ‘<2>’, ‘<3>’, etc. to the end
-;; of the buffer names (all but one of them).
-;; The forward naming method includes part of the file's directory
-;; name at the beginning of the buffer name
-;; https://www.gnu.org/software/emacs/manual/html_node/emacs/Uniquify.html
-(require 'uniquify)
-(setq uniquify-buffer-name-style 'forward)
-
-;; Turn on recent file mode so that you can more easily switch to
-;; recently edited files when you first start emacs
-(setq recentf-save-file (concat user-emacs-directory ".recentf"))
-(require 'recentf)
-(recentf-mode 1)
-(setq recentf-max-menu-items 40)
-
-
-;; ido-mode allows you to more easily navigate choices. For example,
-;; when you want to switch buffers, ido presents you with a list
-;; of buffers in the the mini-buffer. As you start to type a buffer's
-;; name, ido will narrow down the list of buffers to match the text
-;; you've typed in
-;; http://www.emacswiki.org/emacs/InteractivelyDoThings
-(ido-mode t)
-
-;; This allows partial matches, e.g. "tl" will match "Tyrion Lannister"
-(setq ido-enable-flex-matching t)
-
-;; Turn this behavior off because it's annoying
-(setq ido-use-filename-at-point nil)
-
-;; Don't try to match file across all "work" directories; only match files
-;; in the current directory displayed in the minibuffer
-(setq ido-auto-merge-work-directories-length -1)
-
-;; Includes buffer names of recently open files, even if they're not
-;; open now
-(setq ido-use-virtual-buffers t)
-
-;; This enables ido in all contexts where it could be useful, not just
-;; for selecting buffer and file names
-(ido-ubiquitous-mode t)
-(ido-everywhere t)
-
-;; Shows a list of buffers
-(global-set-key (kbd "C-x C-b") 'ibuffer)
-
-
-;; Enhances M-x to allow easier execution of commands. Provides
-;; a filterable list of possible commands in the minibuffer
-;; http://www.emacswiki.org/emacs/Smex
-(setq smex-save-file (concat user-emacs-directory ".smex-items"))
-(smex-initialize)
-(global-set-key (kbd "M-x") 'smex)
-
-;; projectile everywhere!
-(projectile-global-mode)
+;; which-key is the best feature for the discoverability and
+;; usability of Emacs. When you start a key sequence, e.g. C-x,
+;; a menu opens up that shows you what all your next options
+;; are. It's a great way to find out what's in Emacs, and it
+;; helps transfer commands from your short-term memory to
+;; your long-term memory and (finally) your muscle memory.
+(setup (:package which-key)
+  (which-key-mode)
+  (:option which-key-idle-delay 0.3))
+
+;; ivy is the completion framework. This makes M-x much more usable.
+;; Installing counsel brings ivy and swiper as dependencies
+;; swiper is a powerful search-within-a-buffer capability.
+;; https://github.com/abo-abo/swiper
+(setup (:package counsel)
+  (ivy-mode)
+  (:option ivy-use-virtual-buffers t
+           ivy-re-builders-alist '((t . ivy--regex-ignore-order))
+           ivy-count-format "%d/%d ")
+  (:global "C-s" swiper
+           "s-f" swiper
+           "C-x C-f" counsel-find-file
+           "C-x C-b" counsel-switch-buffer
+           "M-x" counsel-M-x))
+
+;; ivy-rich-mode adds docstrings and additional metadata
+;; in the ivy picker minibuffer
+;; see screenshots: https://github.com/Yevgnen/ivy-rich/blob/master/screenshots.org
+(setup (:package ivy-rich)
+  (ivy-rich-mode))

customizations/projects.el

@@ -0,0 +1,12 @@
+;; projectile is another amazing package from the
+;; creator of CIDER. It's got lots of commands
+;; for searching and managing files in a project.
+;; https://projectile.mx/
+(setup (:package projectile)
+  (projectile-mode +1)
+  (:bind "s-p" projectile-command-map
+         "C-c p" projectile-command-map))
+
+;; counsel-projectile integrates projectile with
+;; counsel's browse-and-select UI
+(setup (:package counsel-projectile))