fASCIIsm: For the Love of Text

Spellcheck Dictionaries

Mon, 18 May 2020 00:00:00 +0000

I first tackled spellchecking way back at the start of this blog, but I only configured the files and languages, not the dictionaries and environment. Three work laptops later, this has become a problem. First I'll install Hunspell on the MacBook:

% brew install hunspell
...
==> Caveats
Dictionary files (*.aff and *.dic) should be placed in
~/Library/Spelling/ or /Library/Spelling/.

Then I'll fetch the dictionaries and extract them where I want them to go, non-standard as that may be:

% mkdir ~/.hunspell

% file dict-en-20200501.oxt
dict-en-20200501.oxt: Zip archive data, at least v2.0 to extract

% unzip dict-en-20200501.oxt
Archive:  dict-en-20200501.oxt
  ...
  inflating: en_CA.aff
  inflating: en_CA.dic
  inflating: en_US.aff
  inflating: en_US.dic
  ...

Having to worry about different shells (Bash, Zsh, Eshell) using different startup files for setting environment variables annoyed me, so I decided I'm going to have a ~/.environment file that I make my shells all read from. While I could have used ~/.profile and then told Zsh to read from it, I'd rather a file no tool is going to get clever with and mangle.

% cat ~/.environment
# Required by Hunspell
export DICPATH="$HOME/.hunspell"

% cat ~/.profile
source ~/.environment

% cat ~/.zshenv
source ~/.environment

Deleting all but those four files, since those are the languages (dialects) in which I write, I make then need to test that they're active. First I ensure I have a fresh session and then:

% hunspell -D
SEARCH PATH:
.::/Users/mak/.hunspell:...

AVAILABLE DICTIONARIES (path is not mandatory for -d option):
/Users/mak/.hunspell/en_CA
/Users/mak/.hunspell/en_US

Next, I dogfood Hunspell by running it on its own README, and after ignoring the many false-positives I found an actual mistake:

Hunspell was still screaming about not being able to find dictionaries, so I need to be pulling things out of shell environment variables properly. There's a package for exactly that:

(use-package exec-path-from-shell
  :pin melpa
  :config
  (add-to-list 'exec-path-from-shell-variables "DICPATH")
  (exec-path-from-shell-initialize))

And now I'm save from spelling mistakes once again.

Org Blog Templates

Sun, 17 May 2020 00:00:00 +0000

I was considering what part of my workflow to improve next when I remembered that I've had to type #+begin_ and #+end_ a lot recently. I looked at org-structure-template-alist, but realized that if I wanted to start using templating in my workflows then it should be something universal, not something only useful within org-mode. Enter YASnippet:

(use-package yasnippet
  :ensure t
  :pin melpa
  :mode "/emacs.[dp]/snippets/[^/]*/"
  :config
  (setq yas-snippet-dirs '("~/.emacs.d/snippets" "~/.emacs.p/snippets"))
  (yas-global-mode t))

A great project exists called yasnippet-snippets, containing snippets for most programming languages. While that's a great reasource, I'd much rather import and customize the snippets I like and intend to use than import a massive collection of them. I've hardwired YASnippet to look in both my public (~/.emacs.d) and my private (~/.emacs.p) configurations for snippets. This allows me to keep, for example, templates for my emails and Git commits private.

Most snippets I have seen online begin with # -*- mode: snippet -*-, which tells Emacs to use the major mode snippet-mode for the file's buffer. I dislike using such things, and instead have used the :mode keyword to enable the major mode for all files within subdirectories of yas-snippet-dirs.

Now to make three templates that reduce the effort of writing these blog posts ever so slightly. First up is a source block, which is used for both executing code (as above) and displaying code without executing it (as below):

# name: src block
# key: <s
# --
#+begin_src ${1:emacs-lisp}
$0
#+end_src

# name: example block
# key: <e
# --
#+begin_example
$0
#+end_example

# name: verse block
# key: <v
# --
#+begin_verse
$0
#+end_verse

The relevant difference between example and verse blocks, for my purposes, is that example blocks don't wrap text, while verse blocks do.

Now typing <s[TAB] expands the src block template if I'm in an org-mode buffer.

Accumulate, Don't Poll

Wed, 13 May 2020 00:00:00 +0000

We're in the middle of the pandemic. This is my tenth year of working from home. My three kids and wife are all in the house with me, as all activities are cancelled and have been for two months. My brain has been melting, and refreshing the aggregators and social media sites I favour is more problematic than it used to be. The solution seems clear to me: accumulate, don't poll.

When I was keeping my programs separate, I had a dedicated tmux window for Newsbeuter, which is an amazing feed reader that is best described as "The Mutt of Feed Readers". It's good, but it's not Emacs.

Elfeed is almost exactly like Newsbeuter, except by virtue of being inside Emacs I can customize its behaviours more conveniently, and get integration into Org.

(use-package elfeed
  :ensure t
  :pin melpa)

I don't set a key for Elfeed because I'd rather invoke it with M-x elfeed. I try to save keybindings for things that I do constantly, and as part of a workflow. I should be checking Elfeed a couple times a day, ideally. I'll start by adding a few feeds that I want to make sure I get everything they publish.

(setq elfeed-feeds
      '("https://fasciism.com/feed.xml"
        "https://leahneukirchen.org/trivium/index.atom"
        "https://www.daemonology.net/blog/index.rss"
        "https://www.spinellis.gr/blog/dds-blog-rss.xml"
        "http://n-gate.com/index.atom"))

With that small bit of configuration done, we already have something that looks usable:

The normal navigation/search keys work as expected, Enter opens an entry into an *elfeed-entry* buffer with metadata at the top including a link to the post, images are displayed, hitting Enter on links opens them in Firefox, and q kills the buffer.

I was happy enough with the defaults that I lost an hour to reading my feeds while writing this post. I can almost feel my brain solidifying again. Now I just need to get Twitter and Reddit managed better.

Tangling Tolerantly

Tue, 12 May 2020 00:00:00 +0000

The posts on this blog/configuration, including this one, do not contain code that I want to be executed. Sometimes this is because the code belongs elsewhere (e.g., init.el), other times it's because I'm doing some sort of round-up or story. This entry is both.

The core of my init.el is (roughly) the following:

(defun mak::load-literate-config (dir &optional regex)
  (dolist (org (directory-files dir t (concat regex ".*\\.org$")))
    (org-babel-load-file org)))

org-babel-load-file throws an error if it tangles a file, but the result has no executable code in it, so it neglects to write the output file, and then tries to load the file. This is probably desirable behaviour for some users, but not for me. I've been getting around this by adding the following section to the bottom of the affected posts:

#+BEGIN_SRC emacs-lisp :exports none
  ;;; This block exists solely to prevent errors.
#+END_SRC

That's ugly. Let's fix it. The first way I thought to fix it was to create the output file unconditionally before invoking the tangler:

(defun mak::load-literate-config (dir &optional regex)
  (dolist (org (directory-files dir t (concat regex ".*\\.org$")))
    ;; Some posts don't contain any executable code, so no file is created. Make
    ;; an empty file with the expected name.
    (write-region "" nil (concat (file-name-sans-extension org) ".el"))
    (org-babel-load-file org)))

After deleting all my *.el files I restarted my Emacs to find a default installation. Having not seen such a thing in years, I immediately screamed in horror and took a few minutes to calm down. Default Emacs is ugly. After I'd relaxed, finished my lemon ginger tea, and spent some time focusing on my breathing I resumed my pursuit of slightly nicer blog post files. To figure out what went wrong, I ran C-h f org-babel-load-file and read:

org-babel-load-file is an autoloaded interactive compiled Lisp function in
‘org.el’.

(org-babel-load-file FILE &optional COMPILE)

Load Emacs Lisp source code blocks in the Org FILE.
This function exports the source code using ‘org-babel-tangle’
and then loads the resulting file using ‘load-file’. With
optional prefix argument COMPILE, the tangled Emacs Lisp file is
byte-compiled before it is loaded.

Following the link to org.el brought me to the function's definition, which is (roughly):

(defun org-babel-load-file (file &optional compile)
  (let* ((tangled-file (concat (file-name-sans-extension file) ".el")))
    (unless (org-file-newer-than-p
             tangled-file
             (file-attribute-modification-time (file-attributes file)))
      (org-babel-tangle-file file tangled-file "emacs-lisp"))
    (if compile
        (byte-compile-file tangled-file 'load))
    (load-file tangled-file)))

org-babel-load-file doesn't tangle a file if the .org file is older than the .el file, so making a blank .el file before calling the tangler was never going to work. The straightforward fix that I could see for this was to reimplement org-babel-load-file inside mak::load-literate-config. So this is what I ended up with:

(defun mak::load-literate-config (dir &optional regex)
  (dolist (org-file (directory-files dir t (concat regex ".*\\.org$")))
    ;; This is a customized implementation of org-babel-load-file.
    (let* ((el-file (concat (file-name-sans-extension org-file) ".el")))
      (unless (org-file-newer-than-p
               el-file
               (file-attribute-modification-time (file-attributes org-file)))
        (org-babel-tangle-file org-file el-file "emacs-lisp"))
      ;; Some blog posts don't have any runnable code, and so do not produce a
      ;; file when tangled.
      (if (file-exists-p el-file)
          (load-file el-file)))))

Complexity has to live somewhere, and I'd rather it live in my init.el with comments surrounding it than be scattered throughout my blog posts waiting for me to trip over the problem again.

Org Export Jekyll Backend

Sun, 10 May 2020 00:00:00 +0000

Since I started this blog I've been using a sketchy method to add the necessary YAML headers to exported Org-mode files for Jekyll. It's a pain, and I screwed it up yesterday and discovered that the titles for previous blog posts weren't always proper. The reason for that is the titles were based on the file names, and those don't contain all the proper capitalization and punctuation. Poka-yoke dictates that I must now create either guardrails or automation to prevent me from screwing this up in future, and also use this as an opportunity to learn something.

Org-mode has many backends that export to different formats, but it also allows backends to derive from other backends. This blog had been using the HTML backend. What I'd like to have is an exporter that allows me to have custom export options translated into a YAML header for use by Jekyll, with defaults. For example:

#+TITLE: Org Export Jekyll Backend

And the output written to the fASCIIsm Jekyll repository would be:

---
title:  "Org Export Jekyll Backend"
layout: post
---

Reading through the documentation, I discovered the following variable that does exactly what I want:

org-export-options-alist is a variable defined in ‘ox.el’.
…
Alist between export properties and ways to set them.

The key of the alist is the property name, and the value is a list
like (KEYWORD OPTION DEFAULT BEHAVIOR) where:

KEYWORD is a string representing a buffer keyword, or nil. Each
  property defined this way can also be set, during subtree
  export, through a headline property named after the keyword
  with the "EXPORT_" prefix (i.e. DATE keyword and EXPORT_DATE
  property).
OPTION is a string that could be found in an #+OPTIONS: line.
DEFAULT is the default value for the property.
BEHAVIOR determines how Org should handle multiple keywords for
  the same property. It is a symbol among:
  nil Keep old value and discard the new one.
  t Replace old value with the new one.

The documentation for this variable also notes that #+TITLE is already defined for all exporters, meaning we only need to define #+LAYOUT and give it our desired default.

The template hook in the translate-alist defined the final output function of an exporter. By redefining this, while leaving all other hooks alone, we cause the exporter to fall back to using the HTML backend for everything except the final output.

(require 'org)
(require 'ox-publish)

(org-export-define-derived-backend 'jekyll 'html
  :options-alist
  '((nil "LAYOUT" "post" t))
  :translate-alist
  '((template . org-jekyll-template)))

Next, I ~~stole~~ ~~liberated~~ ~~borrowed~~ ~~blindly copied~~ took inspiration from the template functions in org-mode/lisp/ox-beamer.el and org-mode/contrib/lisp/ox-confluence.el to produce a function that outputs the HTMLified content with a YAML header in front:

(defun org-jekyll-template (contents info)
  (let ((title (org-export-data (plist-get info :title) info))
        (layout (org-export-data (plist-get info :layout) info)))
    (concat "---\n"
            (format "title:  \"%s\"\n" title)
            (format "layout: post\n" layout)
            "---\n\n"
            contents)))

Since testing is good I took another function from org-mode/contrib/lisp/ox-confluence.el:

(defun org-jekyll-export-as-jekyll (&optional async subtreep visible-only body-only ext-plist)
  "Export current buffer to a text buffer.

For information on arguments, see `org-export-to-buffer'."
  (interactive)
  (org-export-to-buffer 'jekyll "*org JEKYLL Export*"
    async subtreep visible-only body-only ext-plist (lambda () (text-mode))))

Running this function via M-x org-export-jekyll-as-jekyll, this blog post/config file renders:

---
title:  "Org Export Jekyll Backend"
layout: post
---

<p>
Since I started this blog I've been using a...

Exporting to buffers is good for testing, but exporting to files is necessary for the project interface.

(defun org-jekyll-publish-to-jekyll (plist filename pub-dir)
  "Publish an org file to Jekyll.

For information on arguments, see `org-publish-org-to'."
  (org-publish-org-to 'jekyll filename ".html" plist pub-dir))

Finally, I need to get the Org-mode project reconfigured to use our new exporter. Going back to our previous setup and copying and editing the project's declaration is easier than altering the existing declaration. We can also fix a long-standing goof about the location of images.

(provide 'ox-jekyll)

;; Set up blog for export as an Org-mode project.
(setq org-publish-project-alist
      '(("fasciism-posts"
         :base-directory "~/.emacs.d/"
         :base-extension "org"
         :publishing-directory "~/src/fasciism/_posts/"
         :publishing-function org-jekyll-publish-to-jekyll)
        ("fasciism-images"
         :base-directory "~/.emacs.d/images/"
         :base-extension "gif\\|jpg\\|png\\|svg"
         :publishing-directory "~/src/fasciism/img/"
         :publishing-function org-publish-attachment)
        ("fasciism"
         :components ("fasciism-posts" "fasciism-images"))))

Now I can use C-c C-e to access the Org Export Dispatcher to export either this post or this whole blog.

MacBook

Sat, 09 May 2020 00:00:00 +0000

I have just realized tonight that I've been sitting on all kinds of posts that I thought I'd already published. Expect updates, finally!

When I have to be away from my beloved Kinesis Advantage 2, with its glorious blank keycaps and Dvorak keymap, I find myself on one of two MacBooks for work. As many others have noted, the Caps Lock key is a pox upon keyboard everywhere, and I universally rebind it to Control:

My muscle memory on normal, lame keyboard also expects to find Alt (Meta) just to the left of the space bar, to I take care of that with a bit of Elisp:

(setq mac-command-key-is-meta t)
(setq mac-command-modifier 'meta)

(setq mac-option-key-is-meta nil)
(setq mac-option-modifier nil)

Git Over Here

Wed, 19 Jul 2017 00:00:00 +0000

Before we begin, I'm going to be using a lot of snippets from Git's configuration file(s). I originally used BEGIN_EXAMPLE to render these as preformatted blocks, but after some research I discovered that the following code will create a new 'source language' with which we can view those snippets.

(add-to-list 'org-src-lang-modes '("gitconfig" . "conf-unix"))

I found that mode's name by opening ~/.gitconfig and typing C-h v major-mode to view the value.

With my new job using GitHub for its development workflow, suddenly maintaining a separate work identity in Git matters. Since we have dozens of repositories, setting my identify in each one was getting very tedious and error-prone. Git now has a feature that permits including files into its configuration based on the directory of the repository. This by having the following within my ~/.gitconfig:

[includeIf "gitdir/i:~/go/"]
      path = ~/.gitconfig.work

Note the use of gitdir/i, since I am on a Macbook which I just discovered treats path components in a case-insensitive manner, so we use this instead of gitdir just in case. The contents of ~/.gitconfig.work are:

[user]
      email = <my-work-email>

Additionally, there are some files that I create locally (e.g., TAGS) that I do not want to be considered by Git. Adding these to each repo sucks, so I'm now taking advantage of the following in ~/.gitconfig, which does just what it says on the tin:

[core]
      excludesfile = ~/.gitignore.global

Finally, some of the setup scripts I've been running into try to clone private repositories from GitHub over HTTPS, requiring usernames and passwords. Since I'm a firm believer in the user of SSH keys whenever possible, but don't want to (or don't have the power to) fix all these scripts, I have found another handy Git feature that forces specified transports for certain hosts:

[url "git@github.com:"]
      insteadOf = https://github.com/

Filesystem Hierarchy Standard

Tue, 18 Jul 2017 00:00:00 +0000

As I dedicate myself to Eshell more, especially on this Macbook which violates all my muscle memory in Terminal.app, a few tweaks are needed to be able to find all my commands:

(defun mak::flatten-list (l)
  (apply #'append l))

(defun mak::locally-installed-programs ()
  (mak::flatten-list
   (mapcar
    (lambda (d) (list (concat d "/bin")
                      (concat d "/sbin")))
    (directory-files "~/local" t directory-files-no-dot-files-regexp))))

(defun mak::generate-path-env-var ()
  (interactive)
  ;; The order of this list is critical:
  ;; 1) Scripts I wrote myself
  ;; 2) Programs installed privately (source)
  ;; 3) Programs installed privately (golang)
  ;; 4) Programs installed system-wide
  ;; 5) Stock OS commands
  (mapcar #'expand-file-name
         (mak::flatten-list
          `(("~/bin")
            ,(mak::locally-installed-programs)
            ("~/go/bin")
            ("/usr/local/bin" "/usr/local/sbin")
            ("/usr/bin" "/usr/sbin" "/bin" "/sbin")))))

Let's use IELM to test those functions, since we've not used it before and it's neat to see.

ELISP> (mak::flatten-list '((a) (b c) (d e f) (g (h) i)))
(a b c d e f g
   (h)
   i)

ELISP> (mak::locally-installed-programs)
("/Users/mak/local/emacs/bin" "/Users/mak/local/emacs/sbin")

ELISP> (mak::generate-path-env-var)
("/Users/mak/bin" "/Users/mak/local/emacs/bin" "/Users/mak/local/emacs/sbin" ...)

You'll notice that flatten only goes one level deep. I'm okay with that for now, but I anticipate Future Me hating Present Me for this.

(defun mak::set-path-env-var ()
  (interactive)
  (setenv "PATH"
          (string-join (mak::generate-path-env-var) ":")))

(add-hook 'eshell-mode-hook 'mak::set-path-env-var)

And there we have it! Eshell will now generate and set the appropriate $PATH variable when it starts.

Go Big Or Go Home

Mon, 17 Jul 2017 00:00:00 +0000

As part of using a Macbook for my new job, I've come to dislike the behaviour of apps not taking up the full screen on startup. Coming from the land of tiling window managers, I've finally had to break down and force Emacs to be fullscreen on start. The below code ensures that the first frame created by Emacs will be maximized, while other frames will have the size the OS decides.

(add-to-list 'initial-frame-alist '(fullscreen . maximized))

Epileptic Trees

Fri, 07 Apr 2017 00:00:00 +0000

While I don't always have threading enabled in my email, when I do it's nice to have something pretty. So let's start by defining a seasonal symbol for the root of the tree.

(defun mak::seasonal-tree ()
  (interactive)
  (let* ((month (format-time-string "%b"))
         (tree (cond ((equal month "Jan") ?🌲)
                     ((equal month "Feb") ?🌲)
                     ((equal month "Mar") ?🌱)
                     ((equal month "Apr") ?🌱)
                     ((equal month "May") ?🌱)
                     ((equal month "Jun") ?🌳)
                     ((equal month "Jul") ?🌳)
                     ((equal month "Aug") ?🌳)
                     ((equal month "Sep") ?🌳)
                     ((equal month "Oct") ?🌲)
                     ((equal month "Nov") ?🌲)
                     ((equal month "Dec") ?🎄))))
    (set-fontset-font t tree "Noto Emoji" nil 'prepend)
    tree))

We've used the same trick here as for the Eshell prompt. While this has worked so far, at some point we'll have to declare that the entire range of emoji should be rendered using the Noto Emoji font.

Now we declare the symbols used to create the tree.

(setq-default gnus-sum-thread-tree-false-root (format "%c " (mak::seasonal-tree))
              gnus-sum-thread-tree-root       (format "%c " (mak::seasonal-tree))
              gnus-sum-thread-tree-indent          " "
              gnus-sum-thread-tree-vertical        "│"
              gnus-sum-thread-tree-leaf-with-other "├► "
              gnus-sum-thread-tree-single-leaf     "╰► ")

One thing that I hadn't given much thought to before now is that the threading in Gnus always seemed wrong to me. It turns out that's because it was performing threading by subject, not by reference. This means that when I received automated emails with the same subject, they would be grouped into a thread. We can fix this easily:

(setq-default gnus-summary-thread-gathering-function 'gnus-gather-threads-by-references)

This allows my email to look much more sane to me, only threading messages that are actually related, to look similar to the following, except it's more spread out in reality:

January 10   [REDACTED]  🌱 BSidesWpg 2017
January 10   [REDACTED]  ╰►
January 10   [REDACTED]   ├►
January 15   [REDACTED]   │╰►
January 23   [REDACTED]   │ ╰►
January 23   [REDACTED]   │  ╰►
January 24   [REDACTED]   │   ├►
January 24   [REDACTED]   │   │├►
January 24   [REDACTED]   │   ││├►
January 25   [REDACTED]   │   │││╰►
January 24   [REDACTED]   │   ││╰►
January 24   [REDACTED]   │   │╰►
January 24   [REDACTED]   │   ╰►
January 10   [REDACTED]   ╰►
...          ...          ...
February 05  Audible.com  Thank you for shopping at Audible
February 20  Audible.com  Thank you for shopping at Audible

Finally, I want to force Summary buffers to be sorted by date. Specifically, any time you enter a buffer Gnus will start you at the top, so the most recent articles should be there. Additionally, if there is a thread full of older messages, and one relatively new message, I want the entire thread to be placed into the Summary buffer according to the date of the newest message.

(setq-default gnus-thread-sort-functions '(gnus-thread-sort-by-most-recent-date))

This results in the following sort, in which the thread is sorted according to its newest article (January 25), not the root of the thread (January 10):

January 25   [REDACTED]  [SkullSpace-Announce] ...
January 10   [REDACTED]  🌱 BSidesWpg 2017
January 10   [REDACTED]  ╰►
January 10   [REDACTED]   ├►
January 15   [REDACTED]   │╰►
January 23   [REDACTED]   │ ╰►
January 23   [REDACTED]   │  ╰►
January 24   [REDACTED]   │   ├►
January 24   [REDACTED]   │   │├►
January 24   [REDACTED]   │   ││├►
January 25   [REDACTED]   │   │││╰►
January 24   [REDACTED]   │   ││╰►
January 24   [REDACTED]   │   │╰►
January 24   [REDACTED]   │   ╰►
January 10   [REDACTED]   ╰►
January 24   [REDACTED]  [SkullSpace-Announce] ...

That's enough for today!

Flipping Tables

Thu, 06 Apr 2017 00:00:00 +0000

The default style of the Gnus summary buffers has been bugging me, so I've changed it to something more palatable.

(setq gnus-user-date-format-alist
      '(((gnus-seconds-today)           . "Today")
        ((+ 86400 (gnus-seconds-today)) . "Yesterday")
        (604800                         . "%A")
        ((gnus-seconds-month)           . "%A %d")
        ((gnus-seconds-year)            . "%B %d")
        (t                              . "%Y-%m-%d")))

;; U: Unread indicator
;; R: Mark
;; z: Indicates +/- for above/below default score
;; f: Sender
;; B: Tree display
;; s: Subject if root of thread or different from root
(setq gnus-summary-line-format "%U%R%z  %-17,17&user-date;  %-40,40f %B%s\n")

Back In The Saddle

Wed, 05 Apr 2017 00:00:00 +0000

Sorry for the lull. The last month has been particularly distracting. One thing that has been bugging me over the last month, during which I lived in email a lot, is the inconsistency in presentation between my personal mail and my Gmail caused by not having them both declared in gnus-secondary-select-methods. So let's fix this without re-declaring the configuration of my personal mail.

(setq gnus-secondary-select-methods
      (cons gnus-select-method
            gnus-secondary-select-methods))

A minor change, but now all of my mail folders are properly prefixed with the nnimap+<name> specifier, instead of only the Gmail folders appearing that way. We also need to unset the primary select method, otherwise having the same server specified twice could get confusing. We do this using the nnnil backend which acts as a dummy.

(setq gnus-select-method '(nnnil ""))

Implausibility Of Gnus

Sat, 04 Mar 2017 00:00:00 +0000

I tend to ignore my Gmail account since I only use it for Google/Android-related things. I should probably pay more attention to it, and so I've decided to add it to my Gnus setup. Whether this is a good idea, or whether it would be preferable to instead forward all email from Gmail to my personal mail server is a problem for Future Me. That guy can handle anything.

(add-to-list 'gnus-secondary-select-methods
             '(nnimap "gmail"
                      (nnimap-address "imap.gmail.com")
                      (nnimap-server-port "imaps")
                      (nnimap-stream ssl)
                      (nnmail-expiry-target "nnimap+gmail:[Gmail]/Trash")
                      (nnmail-expiry-wait immediate)))

This configuration didn't work for me at first, constantly giving me an authentication error, despite copying-and-pasting my password from my password manager. It turns out that due to my use of two-factor authentication, I needed to create an application-specific password for Gnus to access Gmail. Slightly annoying, but I still highly recommend password managers and two-factor authentication.

I don't have a need to send anything from Gmail, yet, so we'll stick with IMAP for now.

Also, collective nouns amuse me.

Misery Loves Company

Fri, 03 Mar 2017 00:00:00 +0000

Now that I've been using Gnus for all my personal email, I've been using Message mode a lot. One thing I need to do very frequently is CC or BCC people or groups. For example, I run a few non-profits and frequently have to CC the organizers@ list for our group with any email representing the non-profit to keep the other directors informed. While Message mode is awesome because I can simply type in the names of new headers, I would find it slightly more convenient of the headers I commonly use were already there. And if there's one thing Emacs is about, it's making things slightly more convenient:

(setq message-default-mail-headers "Cc: \nBcc: \n")

I also run my own mail server for my extended family since I've gotten kolybabi.com for us. This means that if anything goes wrong with the server, I need to hear about it. So I'll enable debugging on sending mail.

(setq smtpmail-debug-info t)

Colour Eshell Prompt

Thu, 02 Mar 2017 00:00:00 +0000

I had never considered before today how to change the colour of some text. I had messed with applying faces to fonts before when making major modes, but I had never looked into styling a specific string. It turns out to be easy:

(propertize STRING &rest PROPERTIES)

Return a copy of STRING with text properties added.
First argument is the string to copy.
Remaining arguments form a sequence of PROPERTY VALUE pairs for text properties to add to the result.

We could leave mak::last-command-status alone, and then advise the function to manipulate its output, but that will inevitably confuse me some day when I am debugging something. So we'll just add a simple propertize call to make the exit code of a command even more visible:

(defun mak::last-command-status ()
  (interactive)
  (let ((c eshell-last-command-status))
    (when (and c (not (eq 0 c)))
      (propertize (format "?%d " c) 'face '(:foreground "red")))))

Gnus Kill Files

Wed, 01 Mar 2017 00:00:00 +0000

Gnus uses newsgroups as its central metaphor. As an individual that never really experienced newsgroups, for which I am sad, some concepts are a little foreign to me. One concept is that of a kill file.

Newsgroups were in some sense a shared mailbox, or an RSS feed of emails, arranged in a hierarchy. Individuals could 'subscribe' to a group by telling their newsreader to pull down the current 'feed' and storing the new posts to the local computer. There was a lot more to this, including only downloading headers, propagation between servers, and varying retention periods between servers. The aspect of these oldschool newsgroups that I care about today are kill files.

A newsreader's kill file instructed it to kill (delete/ignore) certain messages in newsgroups. This was done to filter out topics of which the user had no interest, and to mute users considered abusive or annoying. Gnus supports kill files, but they are deprecated. In my case, my mail server adds X-Spam-Status as a header to all incoming email. Deleting email that my mail server has determined is spam is a classic use of a kill file:

(require 'gnus-kill)
(gnus-kill "X-Spam-Status" "Yes")
(gnus-expunge "X")

This example doesn't make much sense without reading the documentation of the two commands:

(gnus-kill FIELD REGEXP &optional EXE-COMMAND ALL SILENT)

If FIELD of an article matches REGEXP, execute COMMAND.

Optional 1st argument COMMAND is default (gnus-summary-mark-as-read nil "X").

So this means that since we did not pass an EXE-COMMAND argument, the messages were set as read and marked with an X.

(gnus-expunge MARKS)

Remove lines marked with MARKS.

And this means that the X-marked messages are deleted.

Now that we understand kill files, it's time for the punchline: We're not going to use them. The reason is that Gnus has a more modern facility that is recommended by the manual:

In short, kill processing is a lot slower (and I do mean a lot) than score processing, so it might be a good idea to rewrite your kill files into score files.

So I'm working on getting my Gnus to work with score files. But I'm saving that for another day.

New Business

Tue, 28 Feb 2017 00:00:00 +0000

Let's finish off February with something I'm trying to make a part of my life: workflows. You can call them checklists, but I'm going to stick with the more generic term of workflow since I don't want to narrow how I think about their usage. The majority of tasks in my life are repetitive. What I want is a simple way of writing an Org-mode file, dropping it a specific directory, and being able to create an instance of that template that Org will operate on.

Let's start by creating the workflow template instantiation function, and binding it to my Org-mode keymap:

(defvar org-workflow-dir
  (concat org-directory "/workflows")
  "Directory in which my workflows are stored.")

(defun mak::org-new-workflow (template)
  (interactive
   ;; Choose a workflow template.
   (list (read-file-name "Workflow: " (concat org-workflow-dir "/templates/"))))
  ;; Generate the template's file name.
  (let* ((datetime (format-time-string "%F::%T"))
         (filename (file-name-nondirectory template))
         (workflow (format "%s/active/%s::%s" org-workflow-dir datetime filename)))
    (copy-file template workflow)
    (find-file workflow)))

(define-key mak::org-mode-map (kbd "w") 'mak::org-new-workflow)

Now when I chord C-c o w, I will be able to choose a workflow template with Helm, and a new file matching the current date and time, suffixed with the template's file name, will be created, 'activated', and opened in a buffer. By activated, I mean that the template will exposed to Org-mode's Agenda. An example file name is 2017-02-28::01:06:33::month-end.org.

We need to make Agenda aware of where the Org-mode files I want it to use are kept. For now I will include all files in my ~/org directory, since there is no reason to do otherwise. I suspect that I will eventually reach a point where the number of files Org is processing will require me to archive some files, but I'm not there yet. And when I do reach that point, creating a way to archive a file to ~/org/workflows/archive should be easy.

(setq org-agenda-files
      (list org-directory
            (concat org-workflow-dir "/active")))

Finally, I want to create two Agenda views: calendar and tasks.

(defun mak::org-agenda-calendar (&optional arg)
  (interactive "P")
  (org-agenda arg "a"))

(defun mak::org-agenda-tasks (&optional arg)
  (interactive "P")
  (org-agenda arg "t"))

(define-key mak::org-mode-map (kbd "a") 'mak::org-agenda-calendar)
(define-key mak::org-mode-map (kbd "t") 'mak::org-agenda-tasks)

As usual, there's more to do here, but the perfect is the enemy of the good. This is usable, and does what I need for now.

Failure To Launch

Mon, 27 Feb 2017 00:00:00 +0000

I have recently come across a useful addition for my Eshell prompt. I have a love of a simple prompt, but one thing I think it is worthwhile to add is a warning when the previous command exited with a non-zero exit status.

This will be the first time we replace the definition of a function. Thanks to Lisp being great, this is effortless.

;;(require 'esh-io)
(defun mak::last-command-status ()
  (interactive)
  (let ((c eshell-last-command-status))
    (when (and c (not (eq 0 c)))
      (format "?%d " c))))

(defun mak::eshell-prompt ()
  (interactive)
  (concat (if (not (eq 0 (current-column)))
              "\n"
            "")
          (mak::last-command-status)
          (mak::ghost-or-percent)
          " "))

Then we update the prompt regex to match our new prompt format:

(setq eshell-prompt-regexp (format "^\(?[0-9]+ \)\?%s " (mak::ghost-or-percent)))

And take the new prompt for a spin.

👻 false
?1 👻 false
?1 👻 true
👻 true
👻 false
?1 👻 true
👻

There we go. I don't need the current directory in the prompt, because I can find that in a heartbeat. I don't need the current Git branch in the prompt, because I do everything with Magit. This will be useful in that while I can find the information if I need, checking the exit status is something I never think to do.

One glitch that testing revealed is that if I run a command that exits with a non-zero status, kill the Eshell buffer, and create a new Eshell buffer, the prompt will be ?1 👻. This indicates that Eshell does not clear the eshell-last-command-status variable on initialization. I'm not going to fix this in my code, because I feel like it should be fixed in Eshell. Maybe I'll submit a bug report for it when I have some free time.

Bird By Bird

Sun, 26 Feb 2017 00:00:00 +0000

Continuing with my plan to make 2017 the Year of Structure, I need to start using Org-mode beyond this blog. I've been chasing the perfect Org-mode setup, putting off using it until I've designed my system fully. That's dumb, I'm dumb, time to get started. As Anne Lamot teaches, I need to embrace "Shitty First Drafts".

I'm going to make ~/org the base directory for all my Org-mode usage. I realize that this is the default value, but I find comfort in being explicit at this point.

(setq org-directory "~/org")

The next thing I want to do is make a keymap. Many people seem to give Org-mode features top level keybindings such as C-c c for capturing. I don't feel the need to do that (yet?), so I've decided to use a keymap bound to C-c o. I could bind things globally without using a keymap, but the keymap feels like the right choice.

(setq mak::org-mode-map (make-sparse-keymap))
(global-set-key (kbd "C-c o") mak::org-mode-map)

I feel like the obvious first feature to set up is Capture. Org-mode's capture facility pops up a buffer in which I can choose a (user-defined) template, and then fill in whatever I want captured. I can then chord C-c C-c, the general "do what I mean" command in Org-mode, and the information I've input will be whisked away and saved safely, returning me to whatever I was doing.

(define-key mak::org-mode-map (kbd "c") 'org-capture)

I currently have a system that I've been using for a year or two where I send myself emails such as mak+capture@kolybabi.com and then manage my captures/todos as a series of email messages. While I don't have a system to properly manage those emails in my current configuration, I plan to keep that capture method and integrate Gnus and Org-mode to make it work.

For the saving of these captures, I'd like the file to be named less generically than the default of notes.org:

(setq org-default-notes-file (concat org-directory "/capture.org"))

When chording C-c o c from this blog post, I now see a buffer with the following:

Select a capture template
=========================

[t]     Task
---------------------------------------
[C]     Customize org-capture templates
[q]     Abort

And after hitting t to create a generic task, I get the following in a temporary buffer:

** TODO
   [2017-02-26 Sun]
   [[file:~/.emacs.d/2017-02-26-bird-by-bird.org]]

Now I have a way to effortlessly capture when I'm in Emacs, but not elsewhere. So there we go, I've started using Org-mode in earnest. Time to figure out what doesn't work for me, and fix that. How long could that process possibly take…?

Company Capital

Sat, 25 Feb 2017 00:00:00 +0000

One day into using Company and I admit that I'm enjoying it a great deal. One issue that hit me in the first day was that configuration files had completion suggestions, but capitalization of keywords was not being maintained. It turns out that Company maintains a list of modes in which it should preserve capitalization. So if you spend your days fiddling with configuration files, like I do, the following tweak is required:

(require 'company-dabbrev-code)
(add-to-list 'company-dabbrev-code-modes 'conf-mode)

I suspect I'll find more modes to add to company-dabbrev-code-modes over time.

Had Me At Hello

Fri, 24 Feb 2017 00:00:00 +0000

I've wanted to try Company-Mode for a while, so I enabled it today. It's one of the rare packages available in ELPA as opposed to MELPA. Company is a completion framework that offers a popup list after a delay (or immediately when called) in the current buffer.

(use-package company
  :ensure t
  :pin elpa
  :diminish company-mode
  :config
  (add-hook 'after-init-hook 'global-company-mode))

That's all the configuration it needs to start. From this point on I'll have popups whenever there are several options for a prefix that I've typed, or a dim suffix inline.

Lead Bullets

Thu, 23 Feb 2017 00:00:00 +0000

I'm punting it today due to time constraints. Here's a short bit of Org-mode configuration that I've seen other places and have adopted.

(use-package org-bullets
  :ensure t
  :pin melpa-stable
  :config
  (add-hook 'org-mode-hook (lambda ()
                             (org-bullets-mode 1))))

This package changes the bullets used by Org-mode to make them visibly different at different levels. I've kept the default set of bullets provided by the package for the moment, but that may change as I start to use Org-mode more heavily.

Another important change is telling Org-mode to hide leading bullets in headers so that you don't see five bullets prefixing a fifth-level header:

(setq org-hide-leading-stars t)

It's important to note that even with these changes, the actual text representation of the heading doesn't change: the file still has the same asterisks as always underneath it all. This is especially important for me, since I frequently write parts of emails in Org-mode, and then copy-and-paste them into O365. For now, at least. In the end, these configuration changes result in the following styling:

Gnusfeeds

Wed, 22 Feb 2017 00:00:00 +0000

I have used Newsbeuter happily for many years, since it is the Mutt of feed readers, and I love Mutt. However, in moving my life to Emacs I looked at some Emacs feed readers. I discovered Elfeed, and enjoyed it for a while. I've also attempted to use the RSS feed reader built into Gnus (via G R), but I really didn't like that. So I'm currently using Gwene as an NNTP source for Gnus. Gwene translates RSS and Atom feeds on the Internet into Newsgroups. This lowers the burden on individual sites, and has the benefit of not disclosing your IP to the sites.

Setting up Gwene was really easy:

(require 'gnus)
(add-to-list 'gnus-secondary-select-methods '(nntp "news.gwene.org"))

Once that configuration is in place, I reloaded Gnus by quitting it and re-entering it for good measure. Then I hit ^ (gnus-group-enter-server-mode) which brought up the server buffer:

{nnfolder:archive} (opened)
{nndraft:} (opened)
{nntp:news.gwene.org} (opened)
{nnimap:kolybabi} (opened)

By hitting <enter> on nntp:news.gwene.org I can browse the list of newsgroups available on the server, and to toggle subscribing I can hit u (gnus-group-unsubscribe-group):

(gnus-group-unsubscribe-group GROUP &optional LEVEL SILENT)

Toggle subscription to GROUP.
Killed newsgroups are subscribed. If SILENT, don’t try to update the group line.

These are the newsgroups to which I am currently subscribed:

nntp+news.gwene.org:gmane.comp.security.langsec
nntp+news.gwene.org:gmane.comp.security.nmap.devel
nntp+news.gwene.org:gmane.comp.security.nmap.general
nntp+news.gwene.org:gmane.org.hackerspaces.skullspace.announce
nntp+news.gwene.org:gmane.org.hackerspaces.skullspace.general
nntp+news.gwene.org:gwene.com.blogspot.lcamtuf
nntp+news.gwene.org:gwene.com.cryptography.engineering.blog
nntp+news.gwene.org:gwene.com.devttys0
nntp+news.gwene.org:gwene.com.fasciism
nntp+news.gwene.org:gwene.electronics.bunniestudios.blog
nntp+news.gwene.org:gwene.net.boingboing
nntp+news.gwene.org:gwene.net.might.matt.articles
nntp+news.gwene.org:gwene.net.music4program
nntp+news.gwene.org:gwene.org.chneukirchen.blog
nntp+news.gwene.org:gwene.org.chneukirchen.trivium.index
nntp+news.gwene.org:gwene.org.emacsen.planet
nntp+news.gwene.org:gwene.org.jwz.blog

Gnus Scale

Tue, 21 Feb 2017 00:00:00 +0000

One thing that started bugging me immediately upon using Gnus was the prompt for how many messages I wanted to load from my inbox when it had more than 200 messages in it. It turns out that this behaviour is controlled by gnus-large-newsgroup, described as:

The number of articles which indicates a large newsgroup.

If the number of articles in a newsgroup is greater than this value, confirmation is required for selecting the newsgroup.

If it is nil, no confirmation is required.

So let's stop this right now:

(setq gnus-large-newsgroup nil)

Now I feel less like Gnus is judging me for the size of my inbox.

Gnus Sounds Like News

Mon, 20 Feb 2017 00:00:00 +0000

I literally just got the joke of the name while writing this entry. Sometimes I'm a little late to the party.

Anyways, Gnus is one of the many email and news readers available in Emacs. While others are reputed to be much more sane, straightforward, and easy to configure, I've been planning to switch from Mutt to Gnus for many years now. Some of the people whose opinions I respect espouse Gnus, so I'm going to try to live with it. Fingers crossed!

The first and most obvious thing that we want to do with a newsreader is define my identity. While I have a few identities I'd like to use with Gnus, my primary one is:

(setq user-mail-address "mak@kolybabi.com"
      user-full-name "Mak Kolybabi")

And with that, I realize that this is the first time I've named myself. Hi, I'm Mak! I like long walks and configurable systems. Next we need to tell the system how to send email.

(setq send-mail-function 'smtpmail-send-it
      smtpmail-smtp-server "mail.kolybabi.com"
      smtpmail-stream-type 'starttls
      smtpmail-smtp-service 587)

Now that we can send email, it is critical for me to not be able to easily send mail accidentally. I'm the kind of person that has his IRSSI (IRC client) configured to require I hold M-Enter to send, for safety. Let's require a confirmation before sending an email:

(setq message-confirm-send t)

We can test sending an email with C-x m, which opens a buffer populated with the fields of an email. Once that test has confirmed that I can send email, I'll configure the reading of email.

(setq gnus-select-method
      '(nnimap "kolybabi"
               (nnimap-address "mail.kolybabi.com")
               (nnimap-server-port "imaps")
               (nnimap-stream ssl)
               (nnmail-expiry-target "nnimap+kolybabi:trash")
               (nnmail-expiry-wait immediate)))

The credentials to log into SMTP and IMAP are stored in a separate file, ~/.authinfo, and look like this:

machine mail.kolybabi.com login mak.kolybabi password hunter2 port imaps
machine mail.kolybabi.com login mak.kolybabi password hunter2 port 587

Don't fret, my password isn't really hunter2.

In retrospect, that wasn't much to configure at all. I'm sure there will be much more tweaking later, especially since I'd like to add certificate pinning for my mail server for additional protection, and move my credentials into ~/.authinfo.gpg. But for now, this setup is functional, even if it's not yet comfortable.

Jump Around

Sun, 19 Feb 2017 00:00:00 +0000

Another package that I've installed in the past but rarely used was Ace-Jump-Mode. The problem is that I never found a good keybinding for it, and so I rarely remembered to use it. Since Avy has carried on where Ace-Jump-Mode left off, I'm using it instead:

(use-package avy
  :ensure t
  :pin melpa-stable
  :bind
  ("M-`" . avy-goto-char-2)
  :config
  (avy-setup-default)
  (setq avy-keys '(?e ?t ?u ?h ?o ?n ?i ?d)))

Emacs Rocks has a great introduction to the idea of Avy, although it talks about Ace-Jump-Mode specifically. One important thing about Avy is that it defaults to Qwerty home row shortcuts for the candidates, but I prefer Dvorak home row shortcuts. This is easily remedied by altering avy-keys.

I spent some time using avy-goto-char at first, but quickly changed to avy-goto-char-2. The problem is that if you only use one character, then there are many, many choices. You then have to look at what Avy has named the candidate your were intending, then read and type two letters. I found it much better to start by reading two characters and then typing them, then (usually) only having to read and type another character to indicate the selection. YMMV.

Dired Subdirs

Sat, 18 Feb 2017 00:00:00 +0000

I've found that the presence of certain files and directories in Dired buffers is annoying. I spent some time considering adding the ability for certain directories to use my Dired limiting, but found dired-omit-mode instead:

(require 'dired-x)
(setq mak::dired-omit-files
      '("^\\.$"
        "^\\.\\.$"
        "^\\.git$"))
(setq dired-omit-files
      (mapconcat #'identity mak::dired-omit-files "\\|"))
(add-hook 'dired-mode-hook (lambda () (dired-omit-mode)))

Dired omit mode prevents a number of files and directories from being shown by default in Dired. These include revision control directories (e.g., CVS, .git, .svn) and derived files (e.g., .elc, .o). The mode can be disabled in cases where viewing the omitted entries is desirable.

I have also been finding useful the ability to include a subdirectory in the view of its parent. What I've been frustrated by is the inconvenience of its default keybinding: $. I've bound this to <tab> to make it feel more like Org-mode.

(define-key dired-mode-map (kbd "<tab>") 'dired-hide-subdir)

Bull And Bear

Fri, 17 Feb 2017 00:00:00 +0000

It's amazing how choosing the right keybinding for a feature can change your opinion of that feature. I've thought Expand-Region was neat for a long time, and it has been in my configuration at various points, but I've never used it on a regular basis, until now.

(use-package expand-region
  :ensure t
  :pin melpa-stable
  :bind
  ("C-<prior>" . er/expand-region)
  ("C-<next>" . er/contract-region))

On both my laptop keyboard and my Kinesis Advantage, the Page Up and Page Down keys are very accessible. At the time of me writing this, I have used er/expand-region over 400 times in the last two weeks, which I'd estimate is an order of magnitude more than the entire time before that.

Here's the great Emacs Rocks video demonstrating Expand-Region.

Quantified Self

Thu, 16 Feb 2017 00:00:00 +0000

One thing I've always liked about the Windows Add/Remove Programs interface is that it provides you a date that the installed program was last used. When paring down the number of programs on a Windows computer, that date is helpful to gauge whether a program is useful enough to keep around. Since the number of Emacs packages tends to sprawl over time, I have installed the Keyfreq package to track the commands I use:

(use-package keyfreq
  :ensure t
  :pin melpa-stable
  :init
  (setq keyfreq-file "~/.emacs.p/keyfreq/statistics"
        keyfreq-file-lock "~/.emacs.p/keyfreq/lockfile")
  :config
  (keyfreq-mode 1)
  (keyfreq-autosave-mode 1))

When I first installed this package, I didn't honestly think it would be that useful. But since installing it, I have used its output to appreciate how much my usage of certain commands is changing.

Dired Limiting

Wed, 15 Feb 2017 00:00:00 +0000

For me, a great feature of Emacs is narrowing, and a indispensable feature of Gnus is limiting. I'd like to have the same feature, or a close approximation with similar bindings, in Dired. I've waited this long to implement it because I wanted to have a stack just like Gnus.

First, we need to create a buffer-local variable to represent the stack of limits that have been applied.

(add-hook 'dired-mode-hook
          (lambda ()
            (defvar-local mak::dired-limit-stack nil)))

Next, we create a macro. I've never made a macro before, but it seems to work. The reason I have made it is that Undo-Tree provides two useful functions: undo-tree-save-to-register and undo-tree-restore-state-from-register. Registers are extremely useful, and are global, so I don't want my code to clobber any of their values. So I have made the with-register macro that permits me to borrow a register for the duration of the sexp.

(defmacro with-register (register &rest body)
  "Execute the forms in body without allowing contents of register to change."
  (let ((original (gensym))
        (result (gensym)))
    `(let ((,result nil))
       (setq ,original (get-register ,register))
       (setq ,result (progn ,@body))
       (set-register ,register ,original)
       ,result)))

Since this is the first register I've ever made, there are a few things I'd like to discuss. Macros generate code, and so it is bad form to use static variable names anywhere in the generated code. The solution for this is gensym:

(gensym &optional PREFIX)

Generate a new uninterned symbol.
The name is made by appending a number to PREFIX, default "G".

If you're a Lisp enthusiast, I recommend you go read about gensym alternatives like fexpr and hygienic macros, which are much fancier than what we're doing here. Another odd thing we're doing here is saving the result of evaluating the body, this is because this macro could conceivably used in some way that depends on its value, so to avoid surprises we have made that possible. Finally, we used the backquote syntax, and its children comma and splice. When generating code, especially with gensym, you need to have control over evaluation to allow you to determine how many levels of dereferencing you're using. This is done by using the backquote, preventing evaluation of the sexp to which it is applied. You'll notice that after the initial let establishing our dynamically-generated symbol names, we never again use original or result without a comma to give it a dereference. This ensures that the code we're generating doesn't contain the name result or original, but instead the G-prefixed symbol name. Last of all, the =,@= splice notation unpacks the list, promoting all its elements to the level at which the =,@= was called.

That was a lot of words, so here's an example:

(macroexpand
  '(with-register ?a
     (set-register ?a "Monkeys")
     (message (get-register ?a))))

Executing the macroexpand above generates the following code, which has been reformatted for readability:

(let ((G177 nil))
  (setq G176 (get-register 97))
  (setq G177 (progn
               (set-register 97 "Monkeys")
               (message ...)))
  (set-register 97 G176)
  G177)

Looks good! Next, we need to create the function that applies a new limit. This function must save the current buffer state to the stack, and then execute the limiting action. Unfortunately, marks are not preserved across limiting actions, but are restored when the limit is popped.

(require 'undo-tree)
(defun mak::dired-push-limit (dired-mark-function)
  "Limit the buffer to display a subset of files and directories."
  (interactive)
  ;; Save buffer state prior to applying limit.
  (with-register ?q
    (undo-tree-save-state-to-register ?q)
    (add-to-list 'mak::dired-limit-stack (get-register ?q)))
  ;; Clear all marks.
  (dired-unmark-all-marks)
  ;; Mark files we wish to view.
  (call-interactively dired-mark-function)
  ;; Invert which files are marked.
  (dired-toggle-marks)
  ;; Remove all marked files.
  (dired-do-kill-lines))

Now we perform the pop, which is pretty easy. We just need to have a guard against the stack being empty, and the rest is restoring state.

(defun mak::dired-pop-limit ()
  "Pop the most recent limit from the dired-limit-ring."
  (interactive)
  (unless mak::dired-limit-stack
    (user-error "No limit currently is in effect."))
  ;; Restore buffer state to before we applied the limit.
  (with-register ?q
    (set-register ?q (pop mak::dired-limit-stack))
    (undo-tree-restore-state-from-register ?q)))

We finish things off by binding to keys that seem sensible.

(require 'dired-x)

;; These bindings correspond to the default "*" bindings in Dired.
(define-key dired-mode-map (kbd "/ .")
  (lambda ()
    (interactive)
    (mak::dired-push-limit 'dired-mark-extension)))
(define-key dired-mode-map (kbd "/ /")
  (lambda ()
    (interactive)
    (mak::dired-push-limit 'dired-mark-directories)))
(define-key dired-mode-map (kbd "/ *")
  (lambda ()
    (interactive)
    (mak::dired-push-limit 'dired-mark-executables)))
(define-key dired-mode-map (kbd "/ %")
  (lambda ()
    (interactive)
    (mak::dired-push-limit 'dired-mark-files-regexp)))
(define-key dired-mode-map (kbd "/ g")
  (lambda ()
    (interactive)
    (mak::dired-push-limit 'dired-mark-files-containing-regexp)))
(define-key dired-mode-map (kbd "/ s")
  (lambda ()
    (interactive)
    (mak::dired-push-limit 'dired-mark-files-containing-regexp)))

;; This binding is straight out of Gnus.
(define-key dired-mode-map (kbd "/ w") 'mak::dired-pop-limit)

It's not perfect, and the inability to preserve marks when applying more limits is unfortunate, but I'm quite happy with this for now. After writing this, I discovered Dired-Hacks which implements a very similar feature called dired-filter. As I use Dired more, I may add that to my configuration, but for now my cheap hack works for me.

Reader Appreciation

Tue, 14 Feb 2017 00:00:00 +0000

Some things can only get done if you stop worrying about whether the results will matter or have actual benefits. This blog and my Master's degree are two such things. For this blog at least, I have had five different readers contact me about various posts in its seven week lifetime. I'm calling that a rousing success!

Today's post is dedicated to the thing that I have received the most comments about: use-package. The excellent Use-Package library, featured heavily this month, has a number of features that I have retroactively edited into my blog.

First, Use-Package offers a :mode keyword that allows you to bind a mode to a file extension:

(use-package lua-mode
  :mode "\\.nse$")

This is much more convenient than the alternative:

(use-package lua-mode
  :config
  (add-to-list 'auto-mode-alist '("\\.nse$" . lua-mode)))

Use-Package offers an :interpreter keyword which is similar, but applies to the shebang line as opposed to the file extension. It also uses a macro for both the :init and :config keywords to allow multiple forms without the use of progn. Given that I've already used progn in those sections four times this month, that's a great feature, and I've changed earlier posts to take advantage of it.

Another change of note is that I have also gone back and removed the <tab> completion binding from Helm. It turns out that using the right arrow key is a better experience for me. I'm still working out whether the actions offered by Helm under the <tab> menu are particularly useful for me.

Finally, I just want to say that everyone who has contacted me has been wonderful and helpful. I honestly look forward to future emails/tweets pointing out errors and simplifications in my posts.

Copenhagen Interpretation

Mon, 13 Feb 2017 00:00:00 +0000

Emacs has an excellent undo system, once you get the hang of it. But as with all things Emacs, it could be better!

(use-package undo-tree
  :ensure t
  :pin elpa
  :diminish undo-tree-mode
  :bind
  ("C-z" . undo)
  ("M-z" . undo-tree-redo)
  ("C-M-z" . undo-tree-visualize)
  :config
  (global-undo-tree-mode)
  (setq undo-tree-visualizer-diff t))

Let's see how the undo tree looks for this buffer:

As you can see, I've performed several undo and redo operations at this point, and can navigate through them. If I choose any node in the undo tree, I will be presented with an explanatory diff telling me what that node's change represents in a small window.

Dired Here

Sun, 12 Feb 2017 00:00:00 +0000

One thing that occurs frequently in my Emacs usage is opening a Dired buffer based on the current context of the file I am in. For example, when editing this file I would like C-x d to a Dired buffer representing ~/.emacs.d, and ensure that the buffer represents the current state of the filesystem. The default is for C-x d to require confirmation of the location, and to not refresh the Dired buffer if it already exists.

(defun mak::dired-here ()
  "Make an up-to-date Dired buffer for the current location."
  (interactive)
  (dired ".")
  (revert-buffer))

(global-set-key (kbd "C-x d") 'mak::dired-here)

While this is a minor change, it is satisfying.

Kill Ring

Sat, 11 Feb 2017 00:00:00 +0000

I've been using the fabulous browse-kill-ring package for years, but I just discovered that Helm has a similar feature. I now prefer Helm's show-kill-ring, since it is based on filtering candidates from the kill ring using matching, just like the rest of Helm. It's also nice to pare down the number of packages in use occasionally, since the tendency is for one's configuration to grow not shrink.

(global-set-key (kbd "M-y") 'helm-show-kill-ring)

I've bound M-y to this feature, which is normally yank-pop, since if I'm looking for a different item from the kill ring than I already have, it's probably not going to be the first alternate. Creating keyboard macros using registers instead of the kill ring has taught me this.

Magit Is Magic

Fri, 10 Feb 2017 00:00:00 +0000

I stopped doing development for a living three years ago, having moved into security consulting and penetration testing since. Now that I'm setting up Emacs again, I can't believe how much I have missed Magit. While Org-mode and Gnus are the main killer apps for Emacs, they are sprawling. Magit is extremely fast, tight, focused, and beautiful. As mentioned yesterday, I have been doing some open source development recently, and one thing I believe in when making contributions to the code of others is tight diffs. Magit makes it so that the use of a git add -p equivalent is very accessible.

(use-package magit
  :ensure t
  :pin melpa-stable
  :bind
  ("C-c C-g" . magit-status))

Magit's maintainer is very active, new releases are frequent. I love Magit so much that I contribute to the maintainer's Patreon. It's really that good.

Cue Ball

Thu, 09 Feb 2017 00:00:00 +0000

An unscheduled dive into the world of Nmap Scripting last night has caused me to need Emacs to be configured to handle Lua code. As usual, packages are there to make life better:

(use-package lua-mode
  :ensure t
  :pin melpa-stable
  :mode
  "\\.nse$"
  :config
  (add-hook 'lua-mode-hook
            (lambda ()
              (setq lua-indent-level 2
                    lua-documentation-url "http://www.lua.org/manual/5.3/manual.html"
                    lua-default-application "lua5.3"))))

The default indentation in Lua mode is 3 spaces, which seems insane to me, and needs to be 2 spaces to match every bit of Lua I've ever seen. The default documentation is for version 5.1, and the default interpreter on my system is version 5.2, but Nmap embeds version 5.3. The documentation URL allows me to use C-c C-f on a function or keyword to open its documentation in the browser. Finally, Nmap uses a non-standard file extension, .nse for Nmap Scripting Engine, which we need to make Emacs aware of.

The results of last night's Nmap programming can be found here, if you're interested.

At The Helm

Wed, 08 Feb 2017 00:00:00 +0000

No, I couldn't just call this post "Helm". The terrible title I chose called to me, and so I acquiesced. Helm is the most invasive package I've installed thus far. It replaces the majority of commands where user input is expected (e.g., C-x b, C-x C-f, C-x k, M-x) with its own version. Helms commands offer lists of candidates, shown in a pop-up window, which can be filtered, navigated, and selected. This is far more powerful than the default commands, and I find it useful.

An instance of C-x C-f (helm-find-files) appears as follows:

Now let's get that package in the system.

(use-package helm
  :ensure t
  :pin melpa-stable
  :diminish helm-mode
  :bind
  ("M-x" . helm-M-x)
  ("C-x C-f" . helm-find-files)
  :init
  (setq helm-mode-fuzzy-match t)
  :config
  (helm-mode 1))

Fuzzy matching has been enabled, which requires more processing of a list of candidates, but I have used this feature in the past and appreciated it. To explain be example, I can type C-h v hmfm looking for helm-mode-fuzzy-match and the list of candidates will include every variable that matches the regex .*h.*m.*f.*m.*, which is a lot of candidates. As always, if this annoys me later I can disable it effortlessly.

When I initially installed Helm, I limited its use to M-x, but found that I enjoyed it a great deal. I have used Interactive Do (Ido) in earlier times, but I like Helm better. There's also Ivy which is the new kid on the block, but until Helm pisses me off someday it has my (fickle) loyalty.

Switching Windows

Tue, 07 Feb 2017 00:00:00 +0000

Emacs frequently has more than one window open, and C-x o can be used to switch between them. C-x o is far less useful when you have three or more windows open, since you need to use it multiple times to reach the desired window. The Ace-Window package improves this situation by allowing you to navigate directly to a window.

(use-package ace-window
  :ensure t
  :pin elpa
  :diminish
  :bind
  ("M-o" . ace-window)
  :config
  (setq aw-keys '(?e ?t ?u ?h ?o ?n ?i ?d)))

I've bound the keys for different windows based on the Dvorak keyboard layout that I use with my Kinesis Advantage keyboard, prioritizing the strongest fingers. The effect of this package can be seen below:

Jiminy Cricket

Mon, 06 Feb 2017 00:00:00 +0000

Emacs keybindings are not simple. But they are discoverable and memorable, once you get past the initial shock at least. The Guide-Key package helps with that by popping up a new window displaying a list of keys available at the current moment.

(use-package guide-key
  :ensure t
  :pin melpa-stable
  :diminish guide-key-mode
  :init
  (setq guide-key/guide-key-sequence
        '("C-c" "C-x r" "C-x 4" "C-x 5" "C-x 8"))
  :config
  (guide-key-mode 1))

For instance, while writing this blog I can press C-x r and receive a list of possibilities shown below:

You'll notice that we used the :diminish option above, with the name of the minor mode as its value. That indicates that Diminish should omit the minor mode from the mode line entirely. Alternatively, I could have offered an abbreviation such as GK.

Diminishing Returns

Sun, 05 Feb 2017 00:00:00 +0000

For all of the minor modes that I use, I enable them globally. This may change in the future, as can anything, but for now I have no need to know which minor modes are enabled, because the answer is "All the ones I like." Diminish is a package that allows the replacement or omission of mode names in the mode line.

(use-package diminish
  :ensure t
  :pin melpa-stable
  :config
  ;; Diminish built-in modes we've already enabled.
  (diminish 'flyspell-mode)
  (diminish 'visual-line-mode)
  (diminish 'whitespace-mode))

Since we have not yet installed any new minor modes, we will diminish only those which are part of the base system. In future entries we will use :diminish in use-package to include packages in the list that Diminish affects.

Solarized

Sat, 04 Feb 2017 00:00:00 +0000

I have been in love with the Solarized colour scheme(s) since I first laid eyes on them. Before I found Solarized, I would always opt for harsh, high-contrast colour schemes consisting solely of bright colours on black backgrounds. What I like about Solarized is that it claims to be non-arbitrary. Most colour schemes have the feel that everything was picked because the author just liked the look of it. Solarized appears to have some method, though not one which I can understand. So, in summary, SCIENCE!

(use-package solarized-theme
  :ensure t
  :pin melpa-stable
  :init
  (setq solarized-distinct-fringe-background t
        solarized-use-variable-pitch nil
        solarized-high-contrast-mode-line t
        x-underline-at-descent-line t)
  :config
  (load-theme 'solarized-light)
  (load-theme 'solarized-dark))

First, an explanation of the reason I load the light and then the dark version of Solarized. I do this so that both themes are 'approved' by Emacs, meaning that in ~/.emacs.p/custom.el – where I store my Customization settings, see Day 2 – the hashes for the themes are stored as follows:

(custom-set-variables
 '(custom-safe-themes
   (quote
    ("<hash-for-solarized-light>" "<hash-for-solarized-dark>" default))))

This means that whenever I choose to switch between the two versions of the theme, due to the lighting in the environment or the content of a buffer, I needn't worry about warning dialogs. The rest of the settings ensure that Solarized doesn't visually affect other aspects of the Emacs instance.

Htmlize

Fri, 03 Feb 2017 00:00:00 +0000

For a couple of weeks now I've actually had Htmlize installed in my Emacs. The reason for this is that it automatically enables Org-mode's export functions to add syntax highlighting to code blocks. You may have noticed that the blog got slightly less ugly in the recent past, this is why.

(use-package htmlize
  :ensure t
  :pin melpa-stable)

The above call to use-package installs the Htmlize package if it's missing, and forces the use of MELPA Stable as its repository. As mentioned earlier, I try to stick to stable packages whenever possible. Emacs is 'mission critical' to my life, so I can't afford the time and frustration caused by unstable packages. use-package has many more, interesting options that we will use in the coming days.

Ouroboros

Thu, 02 Feb 2017 00:00:00 +0000

As you might have guessed, writing my Emacs configuration in this style leads me to need to reload the system often to ensure that things are in the correct order as I make new drafts and go back to fix mistakes. So far I have been handling this by manually calling M-x kill-emacs and running the program anew. Now that we have packages available, restart-emacs gives us a better way:

(defun mak::restart-emacs-or-release-file ()
  (interactive)
  (if server-buffer-clients
      (server-edit)
    (when (y-or-n-p "Restart Emacs? ")
      (restart-emacs '("--debug-init")))))

(use-package restart-emacs
  :ensure t
  :pin melpa-stable
  :bind
  ("C-x C-c" . mak::restart-emacs-or-release-file))

On Day 3 we changed confirmations to y-or-n-p, and on Day 4 we removed the keybinding that exited Emacs. Now we change our setup to ensure that if we hit C-x C-c Emacs will restart itself, unless it is within a buffer (and frame for my configuration) created by emacsclient, in which case it will return from emacsclient.

Package Fever

Wed, 01 Feb 2017 00:00:00 +0000

I've been holding off on adding packages to my configuration until I had been at this for a month. So it's finally time to celebrate a month of daily blogging by adding every major package repository to my configuration:

(require 'package)
(setq package-archives
      '(("melpa-stable" . "https://stable.melpa.org/packages/")
        ("marmalade" . "https://marmalade-repo.org/packages/")
        ("melpa" . "https://melpa.org/packages/")
        ("elpa" . "https://elpa.gnu.org/packages/")))
(setq package-enable-at-startup nil)
(package-initialize)

Note that instead of using add-to-list I have used setq. This is because for no functional reason, I just like seeing elpa instead of gnu as the name of the core Emacs repo. Whenever possible, I will try and use packages from the elpa repository first, then melpa-stable, then melpa, then marmalade. I have nothing against Marmalade, and placing it last is not a statement about its quality or trustworthiness, I just like MELPA's idea of having a stable repository.

There are many, many packages to choose from, and it's been hard living without them for the first month of this blog. So let's start slow, by installing the package use-package that will enable us to easily use and configure other packages.

(unless (package-installed-p 'use-package)
  (package-refresh-contents)
  (package-install 'use-package))

(eval-when-compile
  (require 'use-package))

This tells Emacs to download use-package if it's not already installed. For most of this week we will revel in silly little cosmetic changes that make me happy.

Automated Blog Posting

Tue, 31 Jan 2017 00:00:00 +0000

To celebrate one full month of blogging, I have written a function that will post the HTML and Org files that comprise each day's blog entry automatically with Midnight, as seen earlier this month.

(defun mak::fasciism-post-daily-blog ()
  "Posts daily blog in HTML and Org format to respective GitHub repos."
  ;; Publish the project to ensure the HTML file is on disk.
  (org-publish-project "fasciism" t)
  ;; Set up the common one-liner to publish a file.
  (let ((cmd (string-join
              '("cd %s"
                "git add %s-*.%s"
                "git commit -m 'Daily blog post.'"
                "git push")
              " && "))
        (date (format-time-string "%F")))
    ;; Publish the HTML file.
    (let ((file (format "_posts/%s" date)))
      (shell-command
       (format cmd "~/src/fasciism" file "html")
       "*fasciism-blog-post::html*"))
    ;; Publish the Org file.
    (shell-command
     (format cmd "~/.emacs.d" date "org")
     "*fasciism-blog-post::org*")))

(add-hook 'midnight-mode 'mak::fasciism-post-daily-blog)

And with that, we've made it! An entire month sticking to the built-in features of Emacs and using it every day. Tomorrow I will lift that self-imposed restriction and dive into the wide world of packages.

Tabs Vs Spaces

Mon, 30 Jan 2017 00:00:00 +0000

I love a good holy war, one in which neither side can ever be right so it gives us something to argue about forever. I find that delightful. Today I'm going to fix something that has been driving me bonkers all month as I write lots of Elisp code: tabs as indentation.

In the tabs vs. spaces war, I'm strictly a fence-sitter. I use both for different languages, but the use of tabs for a language with complex indentation like Elisp is madness. Let's start by disabling tabs as indentation globally.

(setq-default indent-tabs-mode nil)

We need to use setq-default because indent-tabs-mode's help notes that its value becomes buffer-local once set.

For a few programming languages that have relatively simple formatting (C, C++, and Java), I prefer tabs. But I haven't programmed in any of those languages recently, so we can deal with them another day.

Hobo Code

Sun, 29 Jan 2017 00:00:00 +0000

Continuing my love of semi-nonsensical blog entry titles only tangentially related to the topic in any way…

I have some boxes at work that I need to log into frequently. Now that I'm trying to use Eshell instead of xterm, I need to set up Tramp properly. Tramp is an Emacs mode that abstracts the connection to another machine in such a way that editing files, running remote commands, and navigating remote directories with Dired all work.

The first thing I needed to do to make Tramp work was to add the following line to the top of my ~/.zshrc. This line checks for terminals that are 'dumb', meaning they lack advanced features or are likely not normal terminal emulators, and if so: disables Zsh's line-editing facilities, sets the prompt to a traditional style, and stops processing the remainder of the configuration file.

#######################################################
# Emacs Tramp
#######################################################
[[ $TERM == "dumb" ]] && unsetopt zle && PS1='$ ' && return

Once the above line is in place, Eshell immediately works:

👻 cd /ssh:stormy:
👻 pwd
/ssh:stormy:/home/fasciism
👻 cat ../../etc/motd
 _____ _
/  ___| |
\ `--.| |_ ___  _ __ _ __ ___  _   _
 `--. | __/ _ \| '__| '_ ` _ \| | | |
/\__/ | || (_) | |  | | | | | | |_| |
\____/ \__\___/|_|  |_| |_| |_|\__, |
                                __/ |
Stormageddon: Dark Lord of All |___/
https://www.youtube.com/watch?v=bWK61bkQ-ME

Eshell and Tramp ignore all the login banners and message-of-the-day (MOTD) information from the remote system. From this point on, you can execute commands on the remote system since you are effectively SSH'd into it:

👻 hostname
stormy
👻 cat /etc/hostname
aboyne

It's important to know that absolute paths still refer to the system on which Emacs resides, while relative paths refer to the current working directory of Eshell (i.e., the remote host). If I attempt to run find-file on the remote machine to edit the MOTD, the buffer will be marked as read-only

👻 find-file ../../etc/motd
#<buffer motd>
👻 (with-current-buffer "motd" buffer-read-only)
t

Thankfully, Tramp also supports elevating our privilege via sudo on local and remote hosts. The downside is that this operation requires a horrific syntax. Using sudo ffap isn't an option either, since sudo opens a new shell on the remote machine through which Emacs has no special relationship.

👻 sudo find-file ../../etc/motd
[sudo] password for fasciism: [redacted]
sudo: find-file: command not found

However, using Tramp's sudo syntax and multi-hop capabilities, we can use C-x C-f /ssh:stormy|sudo:stormy:/etc/motd, type in the password, and start editing the MOTD in Emacs, resulting in:

👻 cat ../../etc/motd
 _____ _
/  ___| |
\ `--.| |_ ___  _ __ _ __ ___  _   _
 `--. | __/ _ \| '__| '_ ` _ \| | | |
/\__/ | || (_) | |  | | | | | | |_| |
\____/ \__\___/|_|  |_| |_| |_|\__, |
                                __/ |
SUDO VIA TRAMP APPEARS TO WORK |___/
https://www.youtube.com/watch?v=bWK61bkQ-ME

Since this syntax is so ungainly, I've decided to make two emacs functions f (an alias for find-file) and f! which tries to edit the file using sudo (locally or remote).

(defun mak::get-buffer-path (&optional name)
  "Finds the current path, including for Eshell buffers where it is the working directory."
  (interactive "b")
  (with-current-buffer name
    (if (eq major-mode 'eshell-mode)
        (substring-no-properties default-directory)
      (buffer-file-name))))

(defun mak::get-buffer-tramp-context (&optional name)
  "Finds a buffer's Tramp context based on its file name."
  (interactive "b")
  (let ((path (mak::get-buffer-path name)))
    ;; Match single and chained contexts.
    (if (string-match "^\\(/\\(ssh\\|sudo\\):[^:|]+\\(|\\(ssh\\|sudo\\):[^:|]+\\)*:\\)" path)
        (match-string 1 path)
      (user-error "Failed to find Tramp context in path %s." path))))

(defun mak::get-last-hop-from-tramp-context (ctx)
  "Finds the last host or user@host hop in a Tramp context."
  (if (string-match "[/:]\\(?:ssh\\|sudo\\):\\([^:]+\\):$" ctx)
      (match-string 1 ctx)
      (user-error "Failed to find last hop in context %s." ctx)))

(defun mak::tramp-remote-find-file-with-sudo (file)
  "Attempts to open a file using Tramp and Sudo."
  ;; We need to currently be within a Tramp 'context'.
  (let* ((ctx (mak::get-buffer-tramp-context (current-buffer)))
         (hop (mak::get-last-hop-from-tramp-context ctx)))
    (find-file (format "%s|sudo:%s:%s"
                       (substring ctx 0 -1)
                       hop
                       file))))

(defun eshell/f (file)
  "An alias for find-file."
  (find-file file))

(defun eshell/f! (file)
  "An alias for find-file-with-sudo."
  (if (equal "/" (substring file 0 1))
      (find-file (concat "/sudo::" file))
    (mak::tramp-remote-find-file-with-sudo file)))

And with this we now have an easy way to edit either local (absolute) or remote (relative) files with much less typing.

👻 f! /etc/motd
#<buffer motd::>
👻 f! ../../etc/motd
#<buffer motd::/ssh:stormy:>

While the determination of whether to access the local or remote file isn't ideal, it's not bad for a couple hours of work. I can always touch up the logic in a future entry.

Web Browser

Sat, 28 Jan 2017 00:00:00 +0000

Just a minor configuration change today. I've noticed that when I trigger URLs in Emacs in various modes my web browser doesn't pop up properly. I've looked at a few options for fixing this, and the most straightforward one is this:

(setq browse-url-browser-function 'browse-url-generic
      browse-url-generic-program "firefox")

That is all. Good day to you.

Eshell Kill Previous Output

Fri, 27 Jan 2017 00:00:00 +0000

One thing that I do frequently is run a command that produces a lot of output, often curl or nmap, which I would rather not run again. This means that instead or re-running the command and redirecting the output to the kill ring or clipboard, I have to carefully select the output from the buffer and then M-w (kill-ring-save) it. That's more effort than I'd like, so I made a function to select the previous command's output and add it to the kill ring:

(defun eshell/kill-previous-output (&optional nth)
  "Copies the output of the previous command to the kill ring.
When nth is set, it will copy the nth previous command."
  (save-excursion
    ;; Move to the end of the eshell buffer.
    (goto-char (point-max))
    ;; Move to the start of the last prompt.
    (search-backward-regexp eshell-prompt-regexp nil nil nth)
    ;; Move to the start of the line, before the prompt.
    (beginning-of-line)
    ;; Remember this position as the end of the region.
    (let ((end (point)))
      ;; Move to the start of the last prompt.
      (search-backward-regexp eshell-prompt-regexp)
      ;; Move one line below the prompt, where the output begins.
      (next-line)
      ;; Find first line that's not blank.
      (while (looking-at "^[[:space:]]*$")
        (beginning-of-line)
        (next-line))
      ;; Copy region to kill ring.
      (copy-region-as-kill (point) end)
      ;; Output stats on what was copied as a sanity check.
      (format "Copied %s words to kill ring." (count-words-region (point) end)))))

This function doesn't use Eshell's builtin functions, because they break in the common case of the previous command containing a newline. Here's why:

(defun eshell-next-prompt (n)
  "Move to end of Nth next prompt in the buffer."
  (interactive "p")
  (forward-paragraph n)
  (eshell-skip-prompt))

As you can see, the call to forward-paragraph messes things up for my use case.

Eshell Customizations

Thu, 26 Jan 2017 00:00:00 +0000

After trying to use Eshell for the month, I've been fine-tuning its behaviour so that I can tolerate it. There's more work to do, but the first step is to create a command that gets the *eshell* buffer out of the way, taking me back to whatever I was just doing. In mosts modes q is bound to bury-buffer, which sends the current buffer to the back of the list of buffers.

(defun eshell/q ()
  "Send the *eshell* buffer to the back of buffer list."
  (bury-buffer))

I've also found that I'd much rather use Dired instead of Eshell for many tasks. At the same time, it's convenient to be able to quickly switch between the two, so here we add a binding to the e key in Dired and add the d command in Eshell.

(defun eshell/d ()
  "Open a dired instance of the current working directory."
  (dired "."))

(require 'dired)
(define-key dired-mode-map "e"
  ;; Force the creation of a new Eshell instance at this path.
  (lambda ()
    (interactive)
    (eshell t)))

Forcing a creation of a new Eshell ensures it has the same directory as Dired.

Finally, now that I have started using the ~/.emacs.p directory for all of my private files I want Eshell's files to be stored there. I also increased eshell-history-size to a ridiculous number. If that gets ungainly in the future, I'll reduce it.

(setq eshell-history-size 100000
      eshell-directory-name "~/.emacs.p/eshell")

Batch Jekyll Publishing

Wed, 25 Jan 2017 00:00:00 +0000

Every time I export the blog from Org-mode to HTML, I need to go through new entries and add the YAML header that Jekyll (this blog's site generator) uses. I'm tired of doing that, so it's time to automate it.

First we add the symbol for our not-yet-defined function to the property list that defines this Org project. A property list is a flat list of the form (:param1 value1 ... :paramN valueN).

;; List contains (("fasciism" ...)) before proper plist begins.
;; cdar = (cdr (car ...)), removing first element of list.
(plist-put (cdar org-publish-project-alist)
           :completion-function
           'mak::fasciism-project-export-completion)

This method for accessing org-publish-project-alist depends on the blog being the first project. While a terrible way to do things, it'll work since Emacs loads these blog entries in sequence so that later additions to my Org projects won't cause this to fail.

(defun mak::fasciism-project-export-completion (&rest project)
  "Ensure the YAML header exists on blog entries."
  ;; In Org v8, we check a dynamically-scoped variable.
  ;; In Org v9, we get a parameter passed to us.
  (unless project
    (setq project project-plist))
  (let* ((dir (plist-get project :publishing-directory))
         (files (directory-files dir t "\\.html$")))
    ;; For each HTML file.
    (dolist (file files)
      ;; Create a temporary buffer tied to the HTML file.
      (with-temp-file file
       (insert-file-contents file)
         ;; Check for YAML header, inserting if absent.
         (unless (equal (buffer-substring 1 5) "---\n")
           (insert "---\n"
                   "layout: post\n"
                   "---\n"
                   "\n"))))))

While most of the functions used above will be recognizable to your average programmer, I want to take a moment to discuss let*. We've used let before when we needed to create temporary variables, so why do I use let* here? It's because let* allows me to create a variable that references the value assigned to a previous variable in the same assignment list. Specifically, we define dir, and then we use dir in the definition of files. We could have made the definition of files longer, but I prefer this method of breaking it up into smaller assignments that accrete.

X509 Mode

Tue, 24 Jan 2017 00:00:00 +0000

As part of my job, I often have to look at X.509 (SSL/TLS) certificates. I almost never want to see them in their raw state, a blob of unintelligible Base64 or binary. When opening an image in Emacs, the image is displayed in the window by default, and C-c C-c toggles between the image and its representation on disk. I want to have the same thing for X.509 certificates.

First we create the most important thing for any mode, the hook that facilitates customization.

(defvar x509-certificate-mode-hook nil)

Then we build a function that can take a buffer and pipe it through the openssl x509 command. This function needs to be smart enough to detect errors and undo any damage it causes on error.

(defun x509-certificate-parse-command (encoding)
  "Parse the buffer using OpenSSL's x509 command and the specified encoding."
  (let ((errbuf (generate-new-buffer-name "*x509-parse-error*")))
    ;; Try to parse buffer using specified encoding.
    (shell-command-on-region
     (point-min)
     (point-max)
     (format "openssl x509 -text -noout -inform %s" encoding)
     (buffer-name)
     t
     errbuf)
    ;; Check for failure, represented by the existence of errbuf.
    (if (get-buffer errbuf)
        ;; Restore buffer to original state.
        (progn
          (kill-buffer errbuf)
          (insert x509-certificate-mode-text)
          nil)
      t)))

Next we need a pair of functions that can transform the buffer between parsed and raw states. Two variables will be needed, which should be local to the buffer: one to hold the raw buffer contents, and another to track the current state of the buffer.

(defun x509-certificate-parse ()
  "Parse the buffer as a certificate, trying multiple encodings."
  (interactive)
  (if (not (eq x509-certificate-mode-display :raw))
      (error "The buffer is not in :raw mode, it's in %s mode."
             x509-certificate-mode-display)
    (let ((modified (buffer-modified-p)))
      ;; Save the contents of the buffer.
      (setq x509-certificate-mode-text (buffer-string))
      (read-only-mode -1)
      ;; Try to convert the buffer through different formats.
      (if (not (x509-certificate-parse-command "pem"))
          (if (not (x509-certificate-parse-command "der"))
              (error "Failed to parse buffer as X.509 certificate.")))
      (read-only-mode 1)
      ;; Restore previous modification state.
      (set-buffer-modified-p modified)
      (setq x509-certificate-mode-display :parsed))))

(defun x509-certificate-raw ()
  "Revert buffer to unparsed contents."
  (interactive)
  (if (not (eq x509-certificate-mode-display :parsed))
      (error "The buffer is not in :parsed mode, it's in %s mode."
             x509-certificate-mode-display)
    (let ((modified (buffer-modified-p)))
      ;; Delete the buffer, which currently contains the parsed format.
      (read-only-mode -1)
      (erase-buffer)
      ;; Convert the buffer into its raw format.
      (insert x509-certificate-mode-text)
      (read-only-mode 1)
      ;; Restore previous modification state.
      (set-buffer-modified-p modified)
      (setq x509-certificate-mode-display :raw))))

With the transformation functions in place, we would like a keybinding to easily toggle between them. This is done by making a function that dispatches based on the state variable. We also create a keybinding for this mode, instead of tainting the global key map with our function.

(defun x509-certificate-toggle-display ()
  "Toggle between raw and parsed displays of the buffer."
  (interactive)
  (cond ((eq x509-certificate-mode-display :parsed)
         (x509-certificate-raw))
        ((eq x509-certificate-mode-display :raw)
         (x509-certificate-parse))
        (t
         (error "Variable x509-certificate-mode-display is in an unknown state: %s"
                x509-certificate-mode-display))))

(defvar x509-certificate-mode-map
  (let ((map (make-keymap)))
    (define-key map (kbd "C-c C-c") 'x509-certificate-toggle-display)
    map)
  "Keymap for X.509 Certificate major mode")

Calling modes manually via M-x is a pain, so we add likely extensions to a list that maps them to our new major mode. Certificates often have wacky extensions, though, so we also provide a regular expression to match text at the beginning of the buffer.

(add-to-list 'auto-mode-alist '("\\.\\(der\\|crt\\|pem\\)$" . x509-certificate-mode))
(add-to-list 'magic-mode-alist '("-----BEGIN CERTIFICATE-----" . x509-certificate-mode))

Finally, we create our major mode and register it in the Emacs environment. Overly verbose comments are inline.

(defun x509-certificate-mode ()
  "Major mode for viewing X.509 certificates"
  ;; Ensure this function is callable by M-x.
  (interactive)
  ;; Clear the slate.
  (kill-all-local-variables)
  ;; Use our key map just for this buffer
  (use-local-map x509-certificate-mode-map)
  ;; Set the symbol (computer-recognizable) and name (human-visible).
  (setq major-mode 'x509-certificate-mode
        mode-name "X.509")
  ;; Create the two buffer-local variables on which our functions depend.
  (defvar-local x509-certificate-mode-display :raw
    "Current display mode of the data")
  (defvar-local x509-certificate-mode-text nil
    "Original text of the buffer")
  ;; Run the customization hooks.
  (run-hooks 'x509-certificate-mode-hook)
  ;; Perform the initial parse of the buffer
  (x509-certificate-parse))

(provide 'x509-certificate-mode)

And that's it, not much to it. From this point forward I will look at parsed certificates in Emacs by default. This makes me ridiculously happy.

I Am Your Everywhere

Mon, 23 Jan 2017 00:00:00 +0000

I've been using Mutt for my email, but turning off the exit key for Emacs has made using Mutt inconvenient. The reason is that Mutt, like all decent programs, allows you to compose emails in the editor of your choice. For me, this ends up being Emacs in a terminal. Unfortunately when I am done composing an email, I need to exit Emacs to return control to Mutt… which is something I've made harder for myself.

The obvious solution for this made me think of a line from JourneyQuest, "I'm your everywhere!" Emacs offers server-mode, which allows emacsclient to use an existing Emacs instance for editing. All we have to do is enable server mode:

(server-mode)

Now I can change my normal declaration of $EDITOR from emacs -nw to: emacsclient --alternate-editor=vi --create-frame. This allows me to use vi if something goes wrong. I have no problem with vi, it's great, but Emacs is my preference. This also creates a new frame, which is what most people would call a window. Creating a new frame, which appears in my current view, is superior to making me change my virtual desktop from the Mutt terminal over to the dedicated Emacs virtual desktop.

Of course I hope to stop using Mutt, moving my full email workflow into Emacs, but we're going slow and steady.

Removing Safeties

Sun, 22 Jan 2017 00:00:00 +0000

This blog is not focused on the specifics of Emacs lisp, but as we use new concepts I'll try and talk about them briefly. In elisp, symbols are not tied to a single meaning. They are nuanced, and may have variables, functions, or properties attached to them. We previously used this when we ran (fset 'yes-or-no-p 'y-or-n-p) to change the function associated with a symbol. All of the times we've run setq we have been setting the value associated with a symbol. Today we'll be setting the property associated with a symbol.

Let's fool around with this a bit. First we make a function, and disable it.

(defun mak::test-disabling ()
  "XXX-MAK: DEMO FUNCTION"
  (interactive)
  (message "Disabled: %s"
           (get 'mak::test-disabling 'disabled)))

(put 'mak::test-disabling 'disabled "This function has been disabled as a demonstration.")

Now let's run the function non-interactively, by calling it from elisp as opposed to a M-x or a keybinding, and see what happens.

(mak::test-disabling)

This prints the message Disabled: This function has been disabled as a demonstration. as expected. Next we'll bind it to a key, only inside the current buffer for safety, and then trigger the key to see what happens.

(local-set-key (kbd "C-M-D") 'mak::test-disabling)

This results in the following buffer being displayed:

Once I enter y, the function executes and displays Disabled: nil. Now that we have a good handle on this, let's clean up the mess we just made:

(fmakunbound 'mak::test-disabling)
(local-unset-key (kbd "C-M-D"))

We could have used functions we already knew to bind things to nil, but the functions above are more appropriate and have the potential to be more thorough.

Now, let's take the safeties off. We'll start with the region-based case adjustments. We've not discussed the region, so just think of it as the highlighted selection. These commands are constantly useful to me when I'm tidying up text from other sources.

(put 'downcase-region  'disabled nil)
(put 'upcase-region    'disabled nil)

The narrowing functions allow a buffer to alter its display to only include the desired text. This is useful both for blocking out distracting elements of a buffer, such as everything except a single function or paragraph, and for making and running keyboard macros without risking damage to unrelated sections of the buffer.

(put 'narrow-to-region 'disabled nil)

Finally, the ability to set a goal column is useful when dealing with column-based data, and for keyboard macros. Setting a goal column means that when the point (cursor) enters a new line, it will attempt (if the line is long enough) to place itself at the specified column.

(put 'set-goal-column  'disabled nil)

Waiting For Tonight

Sat, 21 Jan 2017 00:00:00 +0000

Midnight mode clears out the list of buffers to trim Emacs down. It does this daily, to buffers that have not been accessed recently, to buffers that are likely to be temporary.

The first thing I need to do is protect certain critical buffers from Midnight's selection. I'd be livid if any tramp or eshell buffers got nuked:

(require 'midnight)
(add-to-list 'clean-buffer-list-kill-never-regexps "\\`\\*tramp::.*\\*\\`")
(add-to-list 'clean-buffer-list-kill-never-regexps "\\`\\*eshell::.*\\*\\`")

I don't think that keeping buffers around for the default three days is necessary:

(setq clean-buffer-list-delay-general 1)

Set the culling to occur when I'm least likely to be awake:

(midnight-delay-set 'midnight-delay "4:30am")
(midnight-mode t)

Now that I've got midnight-mode to clean up after me, I might just stop closing buffers. We'll see.

Midnight mode will be especially useful when I automate the posting of this blog, and the creation of checklists.

Cycling Home

Fri, 20 Jan 2017 00:00:00 +0000

I have noticed the configurations of many others use a function similar to the one below to add some intelligence to moving to the start of a line. It seems like a good idea.

(defun mak::cycle-bol-boi ()
  "Cycle between beginning of line and beginning of indentation."
  (interactive)
  (let ((orig (point)))
    (back-to-indentation)
    (when (= orig (point))
      (move-beginning-of-line 1))))

(global-set-key (kbd "C-a") 'mak::cycle-bol-boi)
(global-set-key (kbd "<home>") 'mak::cycle-bol-boi)

One Coding System To Rule Them All

Thu, 19 Jan 2017 00:00:00 +0000

Since the year 2010, I've felt like I live in the future. Strangely, 2000 and 2001 didn't have quite the same effect. Regardless, we do live in the future so it's time to accept that ASCII has been superseded. This originally came from this blog post.

(setq locale-coding-system 'utf-8)
(set-terminal-coding-system 'utf-8)
(set-keyboard-coding-system 'utf-8)
(set-selection-coding-system 'utf-8)
(prefer-coding-system 'utf-8)
(when (display-graphic-p)
  (setq x-select-request-type '(UTF8_STRING COMPOUND_TEXT TEXT STRING)))

With that done, it's time to use C-x 8 RET 0950 to test our settings with a Unicode code point that looks similar to the Emacs logo: ॐ.

Visualizing Tabs

Wed, 18 Jan 2017 00:00:00 +0000

Normally <backspace> is bound to backward-delete-char-untabify, meaning that if you have the cursor to the right of a tab, and then backspace, it will convert the tab into 8 spaces and remove one. I don't find that intuitive. I'd prefer that backspace delete a single character, whatever it may be.

(global-set-key (kbd "<backspace>") 'backward-delete-char)

I'd also like to be able to tell if a file is indented with tabs or spaces. I like tabs for indentation, and spaces for alignment, personally. Let's enable whitespace-mode, allowing us to see a variety of whitespace-related issues:

(setq whitespace-style '(face trailing tabs empty space-after-tab tab-mark))
(add-hook 'text-mode-hook 'whitespace-mode)
(add-hook 'prog-mode-hook 'whitespace-mode)

Now we will see tabs as », and trailing spaces and lines in the file will appear red.

By default, M-SPC turns a run of whitespace into a single space, and M-\ turns a run of whitespace into nothing. It's more useful to have a single key binding for this that cycles through those options, and back to nothing.

(global-set-key (kbd "M-SPC") 'cycle-spacing)

There Can Be Only One

Tue, 17 Jan 2017 00:00:00 +0000

Once thing you start running into when you have many buffers is colliding names. For instance, if I open up two files ~/foo/test and ~/bar/test I would have two buffers named test<1> and test<2>. This depends on the version of Emacs, but is not very attractive.

(require 'uniquify)
(setq uniquify-buffer-name-style 'post-forward
      uniquify-separator "::")

Now those two buffers would be named test::foo and test::bar, which I find more palatable.

Spellchecking

Mon, 16 Jan 2017 00:00:00 +0000

We're over two weeks into this whole blogging debacle, I guess it's time to start actually spellchecking my blog posts. I'm adapting this from What's the best spell check setup in emacs, which was updated within the last month. Looking into Hunspell versus Aspell, it turns out that the latter is unmaintained while the former had a release in the last month.

The first thing I need to ensure is that both American and Canadian spellings work, because I have to write in both styles, constantly.

👻 echo color colour | hunspell -a -d en_CA,en_US
@(#) International Ispell Version 3.2.06 (but really Hunspell 1.3.3)
*
*

Seems like Hunspell does what I need.

(setq ispell-program-name "hunspell"
      ispell-local-dictionary "en_CA"
      ispell-local-dictionary-alist
      '(("en_CA" "[[:alpha:]]" "[^[:alpha:]]" "[']" nil ("-d" "en_CA,en_US") nil utf-8)))

(add-hook 'text-mode-hook 'flyspell-mode)
(add-hook 'prog-mode-hook 'flyspell-prog-mode)

Picking Up Where We Left Off

Sun, 15 Jan 2017 00:00:00 +0000

One nice feature I've experienced in some Vim installations is the editor remembering where my cursor was the last time I viewed a file. Emacs can do that, too:

(setq save-place-file "~/.emacs.d/saved-point-places"
      save-place-forget-unreadable-files nil)
(save-place-mode t)

Backups And Autosave

Sat, 14 Jan 2017 00:00:00 +0000

Since clearing my configuration, my filesystem has started to drown in *~ files and the occasional #*# file. This is a result of Emacs's default safety net, which I do not appreciate.

(setq auto-save-default nil  ; Prevent *~  files
      make-backup-files nil) ; Prevent #*# files

I'm sure I'll live to regret this. You'll notice that I used the more compact form of setting multiple variables this time. I'm going to stick with that from now on.

Remembering History

Fri, 13 Jan 2017 00:00:00 +0000

I don't exit Emacs often, but when I do it is bothersome to lose recently used commands and filenames. As usual, others have felt this way and mitigated the issue with the creation of savehist-mode:

(savehist-mode &optional ARG)

Toggle saving of minibuffer history (Savehist mode). With a prefix argument ARG, enable Savehist mode if ARG is positive, and disable it otherwise. If called from Lisp, enable the mode if ARG is omitted or nil.

When Savehist mode is enabled, minibuffer history is saved periodically and when exiting Emacs. When Savehist mode is enabled for the first time in an Emacs session, it loads the previous minibuffer history from ‘savehist-file’.

While saving the text in the minibuffer is a good start, there are a number of other aspects of a session that I would like to be saved. Surprising nobody, the variable savehist-additional-variables addresses this:

List of additional variables to save.

Each element is a symbol whose value will be persisted across Emacs sessions that use Savehist. The contents of variables should be printable with the Lisp printer. You don’t need to add minibuffer history variables to this list, all minibuffer histories will be saved automatically as long as ‘savehist-save-minibuffer-history’ is non-nil.

So let's add every history-related variable that I can find. This will even maintain the clipboard and its history (kill-ring).

(setq savehist-file "~/.emacs.p/savehist")
(setq savehist-additional-variables
      '(buffer-name-history
        compile-command
        extended-command-history
        file-name-history
        kill-ring
        regexp-search-ring
        search-ring))

Now that we've configured the mode, we activate it:

(savehist-mode 1)

Henceforth I don't need to worry about losing previously-entered commands/parameters on my rare exits from Emacs. I'll probably have to add more variables later.

Unfill Paragraph

Thu, 12 Jan 2017 00:00:00 +0000

I've been into plain text for fifteen years now, and for much of that time I adhered to the rule of maintaining an eighty-character column width. While I usually continue to adhere to that for comments in source code, I've recently softened my stance when it comes to other text. This change occurred during the writing of the thesis proposal for my Master's degree (currently in progress). It turns out that viewing diffs (even word diffs) is difficult when text changes reflow the paragraph onto different lines. So as a result of my newly-found love for text that is easily diffed, I sought out a way to turn paragraphs containing line breaks into a single, unbroken line.

In Emacs, the process of reflowing text to fit between the left margin and a chosen column is called 'filling'. Emacs maintains a variable, fill-column, which defaults to 70. This variable is used by fill-paragraph (bound to M-q) and together they are used to reflow text into a given column size. Frequently, both in fixing my thesis proposal and copying snippets of text into this blog, I need to reflow text as though it had an infinite column width, and the below does just that:

;;; Originally by Stefan Monnier <foo@acm.org>
(defun mak::unfill-paragraph (&optional region)
  "Takes a multi-line paragraph and makes it into a single line of text."
  (interactive (progn (barf-if-buffer-read-only) '(t)))
  (let ((fill-column (point-max)))
    (fill-paragraph nil region)))

Since fill-paragraph is bound to M-q, binding its complement to M-Q seems appropriate:

(global-set-key (kbd "M-Q") 'mak::unfill-paragraph)

I don't want text to scroll horizontally in a window, nor do I wish for it to wrap in the middle of a word. visual-line-mode takes care of that. Here we add a hook to all modes that inherit from text-mode, which is most writing/programming modes, that enables visual-line-mode in their buffers:

(add-hook 'text-mode-hook 'turn-on-visual-line-mode)

I still use fill-paragraph on occasion, so we will give it a more modern value:

(setq-default fill-column 80)

I use setq-default here instead of setq because some variables are global, and some are local to the buffer in which they are set. setq-default provides a default value for buffer-local values, like fill-column.

Whitespace After Periods

Wed, 11 Jan 2017 00:00:00 +0000

Emacs uses a number of heuristics to induce structure on buffer text. One of these heuristics is that, by default, a single space is not the end of a sentence, but is an abbreviation. This interpretation of periods prevents Emacs from wrapping text after periods with only a single space.

I don't put two spaces after my periods, and I like using word-wrapping.

(setq sentence-end-double-space nil)

Reading through the variables documentation using the describe-variable help facility (C-h v sentence-end-double-space), we find other variables of interest:

Non-nil means a single space does not end a sentence.

This is relevant for filling.

Filling will be discussed tomorrow, and is known elsewhere as reflowing.

Cursor Craving Attention

Tue, 10 Jan 2017 00:00:00 +0000

The blinking cursor is in some ways a useful feedback mechanism: it draws your attention to it and indicates that the terminal hasn't stalled. Personally, I don't want it drawing my attention, since attention is a precious, limited, and fleeting resource. I also use the GUI almost exclusively, so terminal stalls aren't as frequent.

(blink-cursor-mode -1)

Ghost In The Eshell

Mon, 09 Jan 2017 00:00:00 +0000

A problem with fonts and unicode is that many of the characters have no glyphs in a given font. This is going to bite us immediately unless we address it somehow. Our solution, inspired by Ergo Emacs, is to switch to a different font when rendering emoji. I've chosen to use Google Noto as my font for this, since it is dedicated to full Unicode coverage:

(defun mak::ghost-or-percent ()
  (interactive)                                                   ; Allow call via M-x or binding
  (let ((ghost "👻")                                              ; My desired prompt
        (percent "%"))                                            ; My fallback prompt
    (if (and (display-graphic-p)                                  ; Are we in the GUI?
             (member "Noto Emoji" (font-family-list)))            ; Do we have the emoji font?
        (progn (set-fontset-font t ?👻 "Noto Emoji" nil 'prepend) ; Use the emoji font for the ghost
               ghost)                                             ; Return desired prompt
      percent)))                                                  ; Return fallback prompt

I like my prompts simple. Prior to this, my prompt has been a lone percent sign for the last decade. I'm keeping the percent sign as a fallback in case I'm on a terminal, or a host missing the Noto Emoji font.

The set-fontset-font call is the heart of the above function, so let's look at its description:

(set-fontset-font NAME TARGET FONT-SPEC &optional FRAME ADD)

Modify fontset NAME to use FONT-SPEC for TARGET characters.

NAME is … t for the default fontset.

TARGET may be a single character to use FONT-SPEC for.

FONT-SPEC may one of these:
* A font name string.

Optional 4th argument FRAME is a frame or nil for the selected frame that is concerned in the case that NAME is nil.

Optional 5th argument ADD, if non-nil, specifies how to add FONT-SPEC to the font specifications for TARGET previously set. If it is ‘prepend’, FONT-SPEC is prepended. If it is ‘append’, FONT-SPEC is appended. By default, FONT-SPEC overrides the previous settings.

The end result of this is that we've configured Emacs to always display the ghost emoji in the Noto Emoji font.

(defun mak::eshell-prompt ()
  (interactive)
  (concat (if (not (eq 0 (current-column)))
            "\n"
            "")
          (mak::ghost-or-percent)
          " "))

(setq eshell-prompt-function 'mak::eshell-prompt)

Eshell has special behaviour when you have the point after the prompt, honouring input as commands, so we need to explain to it how to recognize our newly-customized prompt.

(setq eshell-prompt-regexp (format "^%s " (mak::ghost-or-percent)))

Finally, we'll expand my war on welcome messages into Eshell:

(setq eshell-banner-message "")

From here I can run M-x eshell and have a functional shell inside Emacs.

War On Mice

Sun, 08 Jan 2017 00:00:00 +0000

Continuing our war on mice (or in my case a Logitech M570 Trackball which I love dearly) inside Emacs, we will unbind most mouse events. We'll still allow scrolling, just in case we have a use for it.

(defun mak::silent (&rest ignored)
  (interactive)
  nil)

(defun mak::mouse-disable (&rest ignored)
  (dolist (event '("" "down-" "drag-" "double-" "triple-"))
    (dotimes (button 3)
      (let ((key (format "<%smouse-%d>" event (1+ button))))
        ;; Bind to a function that returns nil.
        ;; Binding to nil would unbind the key, resulting in errors when used.
        ;; Alternatively, we could bind to individual lambdas, but we don't.
        (global-set-key (kbd key) 'mak::silent)))))

Emacs Lisp, like most Lisp dialects, allows almost any character in a function name. Since this is a personal function, I have prefixed it with my first name and used C++'s namespace notation, despite that notation having no semantic meaning to Emacs Lisp. Since each Emacs frame requires mouse events to be disabled separately, we need to advise the Emacs function responsible for creating frames.

;; Run for first frame.
(mak::mouse-disable)

;; Run in the context of subsequently created frames.
(advice-add 'make-frame-command :before #'mak::mouse-disable)

Advising is a Lisp concept that allows hooking a function before, after, or around (before and after) its execution. It is extremely useful for customizing behaviour.

Decluttering

Sat, 07 Jan 2017 00:00:00 +0000

Until somewhat recently I exclusively used Emacs in a terminal emulator, but now I understand the benefits the GUI offers: more colours, inline graphics, different fonts, and the fringe. We'll get to all of those in due time. The parts of the GUI that I'm not interested in are those which are intended to be used via the mouse.

(when (display-graphic-p)
  (menu-bar-mode -1)
  (tool-bar-mode -1)
  (scroll-bar-mode -1))

Since I'll still occasionally use Emacs in a terminal emulator, these interface elements are only disabled when Emacs is running in a GUI. Trying to disable them in the terminal, where they don't exist, will cause the startup customization process to error out. To learn about display-graphic-p, we'll use a different help facility designed specifically for retrieving the docstrings of functions: describe-function (C-h f display-graphic-p):

(display-graphic-p &optional DISPLAY)

Return non-nil if DISPLAY is a graphic display.

Graphical displays are those which are capable of displaying several frames and several different fonts at once. This is true for displays that use a window system such as X, and false for text-only terminals. DISPLAY can be a display name, a frame, or nil (meaning the selected frame's display).

By this point Emacs is looking appropriately svelte, especially compared to where we started:

Welcome Wagon

Fri, 06 Jan 2017 00:00:00 +0000

Even though I rarely close Emacs, when it starts up a splash buffer named GNU Emacs is displayed:

This is unnecessary for me, so I'll disable it:

(setq inhibit-startup-screen t
      inhibit-startup-message t)

In addition to the splash screen, I feel no need to be told what the *scratch* buffer is for with it saying this each time:

;; This buffer is for text that is not saved, and for Lisp evaluation.
;; To create a file, visit it with C-x C-f and enter text in its buffer.

We can force the *scratch* buffer to start blank with:

(setq initial-scratch-message nil)

Self Publishing

Thu, 05 Jan 2017 00:00:00 +0000

I previously mentioned that the sources for these blog entries are actually my configuration files. This means I'm actually living through this slow configuration process day by day. In truth, I have to live a couple days ahead of the blog to stay sane, but that will get better as things progress. One item that has been in place since day one is the export configuration for my Org-mode files. While on the first day I published the code that turns Org-mode files into live Elisp files, below is the setting that turns Org-mode files into Web pages.

(require 'org)
(require 'ox-publish)
(require 'ox-html)

;; Set up blog for export as an Org-mode project.
(setq org-publish-project-alist
      '(("fasciism"
        :base-directory "~/.emacs.d/"
        :publishing-directory "~/src/fasciism/_posts/"
        :base-extension "org"
        :sub-superscript ""
        :toc nil
        :publishing-function org-html-publish-to-html
        :html-extension "html"
        :body-only t)))

First, the require lines import the libraries necessary for the export process. I have not configured this process as much as I'd like, causing the blog to be ugly right now. We'll revisit this configuration at a later date by simply over-writing the value of org-publish-project-alist in a later blog entry.

To perform the publishing, I run M-x org-publish-current-file:

(org-publish-current-file &optional FORCE ASYNC)

Publish the current file.

With prefix argument FORCE, force publish the file. When optional argument ASYNC is non-nil, publishing will be done asynchronously, in another process.

We'll talk about prefix arguments at a later date. For now, running this command populates the _posts directory of the Jekyll project that produces this blog.

As of today, this blog has a Twitter account, @fasciism.

No Escape

Wed, 04 Jan 2017 00:00:00 +0000

As part of my dedication to staying in Emacs, I feel that I should endeavour to keep it open all of the time. While I can normally manage this, my mind occasionally wanders and reflexes take over and I find myself unintentionally chording the exit sequence. First, let's use the describe-key help facility (C-h k) to discover what is bound to the exit sequence (C-h k C-x C-c):

C-x C-c runs the command save-buffers-kill-terminal (found in global-map), which is an interactive compiled Lisp function in ‘files.el’.

It is bound to C-x C-c, <menu-bar> <file> <exit-emacs>.

(save-buffers-kill-terminal &optional ARG)

Offer to save each buffer, then kill the current connection.
If the current frame has no client, kill Emacs itself.

We can unbind the key using global-unset-key:

(global-unset-key (kbd "C-x C-c"))

Now when we chord C-x C-c we will receive a message in the minibuffer stating "C-x C-c is undefined". Now since my goal is only to prevent myself from unintentionally exiting Emacs, I should mention that I can still trigger the function that closes emacs (exit-emacs) by calling it directly with M-x save-buffers-kill-emacs. Let's look at the help for M-x, which is used to execute any command that is configured as being interactively callable:

(execute-extended-command PREFIXARG &optional COMMAND-NAME TYPED)

This function is for interactive use only; in Lisp code use ‘command-execute’ instead.

Read a command name, then read the arguments and call the command.
To pass a prefix argument to the command you are invoking, give a prefix argument to ‘execute-extended-command’.

Simplified Confirmations

Tue, 03 Jan 2017 00:00:00 +0000

There are many great choices for the first real customization to make to a stock Emacs configuration, but I've chosen one that to me most represents taking the safety off: simplifying confirmations via yes-or-no-p. Lisp has a tradition of using the p-suffix to denote predicates, statements which can be either true or false. Emacs offers excellent built-in help facilities, one of which searches the documentation of symbols (i.e., docstrings) for a pattern. Using this help facility, called apropos-documentation (C-h d yes-or-no-p), describes the function of interest as:

(yes-or-no-p PROMPT)

Ask user a yes-or-no question. Return t if answer is yes, and nil if the answer is no. PROMPT is the string to display to ask the question. It should end in a space; `yes-or-no-p' adds "(yes or no) " to it.

The user must confirm the answer with RET, and can edit it until it has been confirmed.

Typing yes and no quickly becomes tiresome. Thankfully there's y-or-n-p, described as:

(y-or-n-p PROMPT)

Ask user a "y or n" question. Return t if answer is "y". PROMPT is the string to display to ask the question. It should end in a space; `y-or-n-p' adds "(y or n) " to it.

No confirmation of the answer is requested; a single character is enough. SPC also means yes, and DEL means no.

This feels dangerous, but Emacs has great undo capabilities and the convenience is appreciable, so let's pull the trigger.

(fset 'yes-or-no-p 'y-or-n-p)

The reason that I've used fset above is that symbols have separate function and value cells, similar to how Lisp uses address (car) and data (cdr) cells.

Literate Configuration

Mon, 02 Jan 2017 00:00:00 +0000

The first file that Emacs runs when it loads is ~/.emacs.d/init.el. This file is written using Emacs Lisp (elisp). It is important to get one thing clear in your head: Emacs is just a Lisp runtime. This means that while Emacs is primarily considered a text editor, that's just its user interface, not its application.

The init file that I'm using right now takes every various files with the .org extension and converts them to the correspondingly named .el file, and then evaluates the files altering the Emacs active session. Comments are prefixed with varying numbers of semicolons. In classic Unix fashion, you are not expected to understand this.

;;; init.el --- Where all the magic begins
;;
;; Originally from:
;;     http://orgmode.org/worg/org-contrib/babel/intro.html#literate-emacs-init
;;
;; This file loads Org-mode and then loads the rest of our Emacs initialization
;; from Emacs lisp embedded in literate Org-mode files.

;; Load up Org Mode and (now included) Org Babel for elisp embedded in Org Mode
;; files.

(defun mak::load-literate-config (dir &optional regex)
  "Load and evaluate the files in dir matching regex, except blacklisted files."
  (unless regex
    (setq regex ""))
  (dolist (org (directory-files dir t (concat regex ".*\\.org$")))
    (org-babel-load-file org)))

(setq dotfiles-dir (file-name-directory (or (buffer-file-name) load-file-name)))

(let* ((org-dir (expand-file-name "lisp"
        (expand-file-name "org"
         (expand-file-name "src"
          dotfiles-dir))))
       (org-contrib-dir (expand-file-name "lisp"
        (expand-file-name "contrib"
         (expand-file-name ".."
          org-dir))))
       (load-path (append (list org-dir org-contrib-dir)
                          (or load-path nil))))
  ;; Load up Org-mode and Org-babel.
  (require 'org-install)
  (require 'ob-tangle))

;; Load the customization variables from another file.
(setq custom-file "~/.emacs.p/custom.el")
(load custom-file 'noerror)

;; Load up all literate org-mode files matching the regex in each directory.
(mak::load-literate-config "~/.emacs.d" "\[0-9\]\\{4\\}-\[0-9\]\\{2\\}-\[0-9\]\\{2\\}-")
(mak::load-literate-config "~/.emacs.d/drafts" "YYYY-MM-DD-")
(mak::load-literate-config "~/.emacs.p")

I have edited the bottom of the file to only import my blog posts, both published and unscheduled drafts, and my private configuration files.

Emacs Bankruptcy

Sun, 01 Jan 2017 00:00:00 +0000

I have decided to claim Emacs bankruptcy, not because Emacs is groaning under the weight of all my customizations, but because I feel there is something instructive to be gained from watching someone build up their configuration slowly. I have personally declared 2017 to be "The Year of Structure" in my life, and part of that will be loading my life entirely into Emacs, and writing about it.

Over time, I will likely have to go back and fix earlier entries as I realize mistakes that I've made, so none of these blog entries are immutable. You have been warned. The reason for this is that the primary source material for most posts exists as Org-mode files inside my ~/.emacs.d directory. I am also making the source files for this blog publicly available.

Tomorrow's post will contain the core of the Org-to-HTML+Elisp process.