sachachua: 2018-10-15 Emacs news

Links from, /r/orgmode, /r/spacemacs, Hacker News,, YouTube, the changes to the Emacs NEWS file, and emacs-devel.

-1:-- 2018-10-15 Emacs news (Post Sacha Chua)--L0--C0--October 16, 2018 02:53 AM

Irreal: Ignoring Files Locally in Magit

I learned two things I didn’t know about Magit from a post by Marcin Borkowski (mbork). The first is that you can exclude files locally. That is, you can ignore files just as if they were in .gitignore but that information doesn’t get committed as it does with .gitignore. That’s handy when you’re working in a team and have some local files that are peculiar to you and that you don’t want committed.

The other information is how to add those files to the exclude list from within Magit. Head on over to mbork’s post to get all the details.

-1:-- Ignoring Files Locally in Magit (Post jcs)--L0--C0--October 15, 2018 04:56 PM

Marcin Borkowski: Magit and C-u i

Last time I mentioned that I use multiple backup copies of my .env file. One problem with that approach was they they cluttered my Git status (or the magit-status window). I could put the relevant pattern in my .gitignore file, but I didn’t want to bother other programmers in the team with peculiarities of my personal setup.
-1:-- Magit and C-u i (Post)--L0--C0--October 14, 2018 05:59 PM

Irreal: Configuring Org Mode to Look Like a Word Processor

Last month, I wrote about clean screen writing where all the extraneous information is removed from the screen and the writer is presented with a “blank page.” In the same vein, Abhinav Tushar has an interesting post on making Org mode itself look like a word processor. By that he means that Org looks like a word processor as you enter text.

Mostly it’s a matter of picking a nice font, a nice background, adjusting the spacing, and getting rid of everything but the text you’re editing. That include hiding all the Org markup and #+ commands. The result, I must admit, looks gorgeous. Still, as I said in the blank page post, it’s not for me. When I’m writing, I like to see the markup because, among other things, it makes it easier to edit the text.

Not everyone will agree, of course, so you should take a look at his results to see if they’re something you’d like. He has links to his configuration so it shouldn’t be hard to recreate his setup or use it as a jumping off place for your own. Even if you don’t want his setup, you might like using a proportional font in Org. He uses the ET Book, which looks very nice. I am impressed at what he was able to do and how nice it looks.

-1:-- Configuring Org Mode to Look Like a Word Processor (Post jcs)--L0--C0--October 14, 2018 04:15 PM

Raimon Grau: staging hunks without magit

So there's magit that allows you to stage hunks as if you were doing "git add -p".  And I love it, but sometimes magit feels like too much, and it's slower than using vc.

I've been using git-gutter for some time, and I think there's a nice potential for staging hunks with it.

(use-package git-gutter
:ensure t
:config (global-git-gutter-mode t)
:bind ("C-x v s" . git-gutter:stage-hunk)
("C-x v n" . git-gutter:next-hunk)
("C-x v p" . git-gutter:previous-hunk))

With these configs (I'm using use-package), you can navigate through hunks with c-x v n/p (I'm basing the keybinds on vc "c-x v" ones) and stage them with "c-x v s". 

I'm pretty happy with those, only missing the ability of staging several hunks at once within a region.

-1:-- staging hunks without magit (Post Raimon Grau ( 11, 2018 12:20 PM

sachachua: 2018-10-08 Emacs news

Links from, /r/orgmode, /r/spacemacs, Hacker News,, YouTube, the changes to the Emacs NEWS file, and emacs-devel.

-1:-- 2018-10-08 Emacs news (Post Sacha Chua)--L0--C0--October 08, 2018 07:55 PM

Marcin Borkowski: The version-control variable

As many of us know, Emacs has a habit (annoying for most people, I guess) of making backup copies of files it saves. Happily, it doesn’t kick in in version-controlled files (and most of my files fall into this category nowadays). But there are situations when I actually do want the backup copies.
-1:-- The version-control variable (Post)--L0--C0--October 06, 2018 06:24 AM

Raimon Grau: kill-ring-max is a thing

So I recently discovered the variable `kill-ring-max', that dictates the size of the kill-ring, meaning when items on the kill-ring will be discarded.  Its original value is 60, and for some reason I still had it set to the default.

It's strange that I hadn't seen it mentioned before (at least, enough times to pay attention to it,) so let's try to increase the awareness of this very useful variable.

If you use helm-show-kill-ring, or something that allows you to search through kill-ring, having a bigger kill-ring might allow you to recover s"lost" work.
-1:-- kill-ring-max is a thing (Post Raimon Grau ( 05, 2018 01:10 PM

Emacs Redux: super-save 0.3

After a long period of no development activity (mostly because it was perfect from the start), super-save gets an update today!

The latest 0.3 version of your favourite auto-saving library makes it easier to customize the hook triggers (see super-save-hook-triggers) and adds an option to ignore remote (TRAMP) files (see super-save-remote-files).

As a refresher - super-save will save modified files automatically on certain command (e.g. switch-to-buffer) and hook triggers (e.g. focus-out-hook).

Both of those are configurable via super-save-triggers and (starting with 0.3) super-save-hook-triggers. Here are a couple of examples:

;; add integration with ace-window
(add-to-list 'super-save-triggers 'ace-window)

;; save on find-file
(add-to-list 'super-save-hook-triggers 'find-file-hook)

You can now turn off super-save for remote files like this:

(setq super-save-remote-files nil)

It seems that now super-save is beyond perfect, so don’t expect the next release any time soon! ;-)

P.S. super-save was extracted from Prelude, but for some reason I actually forgot to add it to Prelude. Today that changes as well! :-)

-1:-- super-save 0.3 (Post)--L0--C0--September 29, 2018 05:22 PM

Emacs Redux: Projectile goes Turbo

For a while one of the biggest complaints people had about Projectile was that the alien indexing wasn’t fast enough (especially on big projects). The reason for the (relatively) bad performance was pretty simple - even though Projectile would normally obtain the list of project files pretty fast (e.g. by using git ls-files) it always did some post-processing of the results (e.g. filtering, sorting, etc), which is a very slow operation in Elisp on a big dataset.

Today I’ve added a new indexing method that simply dispenses with all of the post-processing and gives you the raw power you always craved for. It’s called turbo-alien (yeah, yeah - naming is hard!) and it’s going to be the default indexing method going forward (starting with Projectile 1.1 which should be released pretty soon).

You can read a bit more about it in Projectile’s manual.

If you find yourself missing Projectile’s old behaviour just add the following to your config:

(setq projectile-indexing-method 'alien)

The old tried and true alien method is still around, it’s just no longer the default.

P.S. I encourage all of you to help out with some of the open tickets marked with “Help Wanted” or “Good First Issue” here. I’m trying to clean-up shop after a long period of stagnation and I can certainly use some help! :-)

P.P.S. The recent 1.0 release was just a precursor to some bigger changes I had planned to do for quite a while. Stay tuned for more updates!

-1:-- Projectile goes Turbo (Post)--L0--C0--September 29, 2018 05:14 PM

Chen Bin (redguardtoo): Wucuo, a Emacs spell checker that works with camel case code

Now it's possible to spell check camel case code in Emacs using wucuo.

Setup is easy. Add (wucuo-start) into ~/.emacs, then use flyspell as usual.

Flyspell could use either aspell or hunspell. No extra setup for aspell or hunspell is required.

Wucuo starts an independent process to check camel case words. So your original flyspell setup is still valid.

For example, you could still use Spanish and English dictionaries in your existing flyspell setup.

Two flag wucuo-aspell-language-to-use and wucuo-hunspell-dictionary-base-name are used and only used to check camel case word through independent process.

Wucuo is generic enough to handle any programming language if its major mode inherits from prog-mode.

Even if the major mode does not inherit from prog-mode, it's still simple to use wucuo.

You only need find font face the camel case word is used by running M-x wucuo-current-font-face. Say the font face is js2-function-call.

Then we need setup wucuo-personal-font-faces-to-check,

(setq wucuo-personal-font-faces-to-check '(js2-function-call))

That's all.

Some optional tools to help you manage personal dictionaries:

  • M-x wucuo-create-aspell-personal-dictionary creates plain word dictionary ~/.aspell.en.pws for aspell
  • M-x wucuo-create-hunspell-personal-dictionary creates plain word dictionary ~/.hunspell_en_US for hunspell

BTW, please don't start flyspell-prog-mode when using wucuo.

Any suggestion is welcomed. For example, currently wucuo only check English camel case word. Ping me if you want to use other languages.

-1:-- Wucuo, a Emacs spell checker that works with camel case code (Post Chen Bin)--L0--C0--September 07, 2018 12:39 PM

emacsninja: Fixing My #1 Annoyance With Emacs Lisp

Ah, Emacs Lisp. There are many reasons for loving and hating it. I disagree with most people name when they argue why the language sucks[1], for me it’s mostly two things that end up mattering in practice:

  1. The APIs are terrible. Font-locking is an enigma. It’s common for packages to use synchronous APIs because it’s far easier to do than The Right Thing™. Moving through buffers and editing them makes for incomprehensible and stateful code. I could go on, but most of these can be mitigated by writing your own APIs as you figure things out. This is not what this blog post is about.
  2. There is no namespace or module system. This means that every global identifier could end up clashing with another one unless you emulate namespacing by adding a unique prefix. While this could be fixed, it’s unlikely to happen[2]. Interestingly enough this situation is similar to C, but worse as there’s no visibility control, only the convention of using a double dash for global identifiers not considered public. This annoys me as I have to type out a potentially long prefix every time. This is what this blog post is about.

I initially considered one of the namespace packages. It would make for as little typing as possible, however this would require an additional dependency and break my existing workflows. Therefore I went for the alternative route, writing a command that inserts the package prefix of the current buffer at point. Bind that command to an easily reachable key binding and you’d save nearly as much effort with typing.

(defvar-local my-current-package-prefix nil)

(defun my-ensure-trailing-dash (string)
  (if (and (not (zerop (length string)))
           (not (= (aref string (1- (length string))) ?-)))
      (concat string "-")

(defun my-guess-current-package-prefix (arg)
    (goto-char (point-min))
    (if (and (not arg)
             (re-search-forward "^(defgroup \\(\\w+\\)" nil t))
        (setq my-current-package-prefix
              (my-ensure-trailing-dash (match-string 1)))
      (setq my-current-package-prefix
             (read-string "Package prefix: "

(defun my-insert-current-package-prefix (arg)
  (interactive "P")
  (when (or (not my-current-package-prefix) arg)
    (my-guess-current-package-prefix arg))
  (insert my-current-package-prefix))

(with-eval-after-load 'elisp-mode
  (define-key emacs-lisp-mode-map (kbd "C-.")

Guessing the prefix is done by looking for a (defgroup ...) form which is a good enough indicator for a prefix[3]. In case it’s not given, the above code prompts for a prefix and allows resetting it with a prefix argument. The trickiest part is ensuring the prefix ends with a dash. You could optimize this even further by looking whether a prefix has already been inserted, but honestly, undoing the change is simple enough.

Let’s see whether this reignites my drive to write more Emacs packages…

[1]Who cares if it’s slow? Who cares about the lack of regex literals? Yes, it’s not <insert your favorite language>. Despite all of this people wrote lots of it, far more than any of the haters would. Feel free to dream about an Emacs rewritten in something else, but it’s going to stay a pipe dream if that’s all you do. The topic deserves a separate blog post because it’s a common phenomenon in the Emacs community to place irrational hopes in a re-implementation to succeed the status quo.
[2]The topic came up on emacs-devel before, the main problem is that the tooling would need to be updated. Simple workflows the core team is used to (such as grepping the qualified name) would completely break apart.
[3]An even better indicator would be the :prefix option inside (defgroup ...), but let’s not go overboard.
-1:-- Fixing My #1 Annoyance With Emacs Lisp (Post Vasilij Schneidermann)--L0--C0--August 26, 2018 06:12 PM

Flickr tag 'emacs': Move

Lil' Mersereau posted a photo:


-1:-- Move (Post Lil' Mersereau ( 17, 2018 03:16 PM

Flickr tag 'emacs': You&Me

Lil' Mersereau posted a photo:


-1:-- You&amp;Me (Post Lil' Mersereau ( 14, 2018 07:48 PM

Emacs café: The new Indium

Now that Indium 2.0 is around the corner, it’s about time to write this post!

You can see this article as the third part of my series of articles describing how to make Emacs a JavaScript development environment. If you haven’t read it yet, you should jump to the first and second post first to get started.

About Indium 2.0

Indium 2.0 is not out yet, but if you’re installing Indium from MELPA, you’re already using it.

Indium is a JavaScript development environment for Emacs. It connects to a runtime (Browser or Node), and provides things like a REPL, inspector, live evaluation, and of course a stepping source debugger.

Indium debugger in action

New project configuration

The upcoming release of Indium will feature much better project configuration with sourcemap support for most, if not all JavaScript projects, including React, VueJS, Meteor, Angular, and basically any project that uses Webpack or other bundlers that produce sourcemaps.

New client/server architecture

The new Indium will also be based on a client/server architecture, and will require the installation of the indium server like the following:

npm install -g indium

There are several reasons for this change, the most important one being the ability to reuse existing JavaScript libraries for handling WebSockets, source-maps and the Chrome Debug Protocol.

You can read the documentation of the new TCP protocol here.

As a result, Indium will be much more responsive.

Setting up Indium

Let’s start with the creation of a React project built with the CLI tool create-react-app.

sudo npm install -g create-react-app
create-react-app my-app
cd my-app
npm install
npm start

We need to tell Indium how to connect to our new project my-app. To do that, let’s create a .indium.json file at the root of the project:

  "configurations": [
	  "name": "Web Browser",
	  "type": "chrome",
	  "url": "http://localhost:3000"

We only need one configuration, but Indium supports any number of configurations per project, including mixing NodeJS and Chrome.

Firing up Indium

To start Indium, you can either do M-x indium-connect to connect to a running JavaScript process (Chrome tab the example above), or do M-x indium-launch to start a new process and automatically connect to it.

For more information about setting up and starting Indium, read the Getting up and running section of the documentation.

Closing words

The new architecture of Indium is brand new, and I expect issues to be discovered. You can open issues on the GitHub issue tracker (please do!).

If you are unsure how to best report an issue for Indium, there’s a section in the manual for that!

-1:-- The new Indium (Post Nicolas Petton)--L0--C0--August 14, 2018 10:00 AM

Trey Jackson: I'm so out of it

I didn't even realize that Emacs 26.1 was released 3 months ago!
-1:-- I'm so out of it (Post Trey Jackson ( 08, 2018 02:56 PM

emacspeak: Using Emacs Threads To Execute Commands Asynchronously

Using Emacs Threads To Execute Commands Asynchronously

1 Executive Summary

Emacs 26 has threads for executing functions asynchronously. Emacs
commands that call an external process and wait for that process to
finish make a good candidate for asynchronous execution — e.g.,
smtpmail-send-it for sending mail. The arrival of threads provides
an interesting option for running such commands asynchronously.

2 First Attempt — Custom Async gnus Command

I initially wrote a custom command for launching gnus asynchronously
— it was a one-line function that ran the following:

(make-thread #'gnus)

The above worked well — except when command gnus needed user input
— so I just had to be thoughtful about when I called it. But a few
weeks later, I wanted the equivalent for function smtpmail-send-it
for sending mail. I almost wrote myself one more command before
stepping back to create a more generic solution.

3 One Command To Thread Them All

I have now defined command emacspeak-wizards-execute-asynchronously
bound to C-' a.
Note that this command, though part of module emacspeak-wizards, has
no emacspeak dependencies.

(defun emacspeak-wizards-execute-asynchronously (key)
  "Read key-sequence, then execute its command on a new thread."
  (interactive (list (read-key-sequence "Key Sequence: ")))
      (let ((l  (local-key-binding key))
             (g (global-key-binding key)))
     ( (commandp l)
       (make-thread l)
      (message "Running %s on a new thread." l))
     ((commandp g)
      (make-thread g)
      (message "Running %s on a new thread." g))
     (t (error "%s is not bound to a command." key)))))

(global-set-key (kbd "C-' a") 'emacspeak-wizards-execute-asynchronously)

With this command bound to C-' a, I can now get rid of my custom
gnus-async command and its associated key-binding. I already have
command gnus bound to C-; g, so I can just press C-' a C-; g to
fetch news/mail asynchronously.

Similarly, when sending mail using smtpmail I can press C-' a C-c
in the *mail* buffer to send mail without Emacs blocking.

4 Final Caveats

Like other asynchronous solutions (see package async for instance)
one needs to make sure that the command being executed asynchronously
will not require user input. In the case of package async, the
asynchronous Emacs will block waiting for input; in the case of
make-thread, Emacs enters a blocking loop with the minibuffer
continuously displaying

No catch for ...

The only way to come out is to kill Emacs — so make sure to use
command emacspeak-wizards-execute-asynchronously only when you're
sure that the command being run asynchronously will not require user

Date: 2018-07-03 Tue 00:00

Author: T.V Raman

Created: 2018-07-03 Tue 14:37


-1:-- Using Emacs Threads To Execute Commands Asynchronously (Post T. V. Raman ( 03, 2018 09:57 PM

emacspeak: Effective Suggest And Complete In An Eyes-Free Environment

Effective Suggest And Complete In An Eyes-Free Environment

1 Executive Summary

Emacs has always provided a wealth of techniques for rapid keyboard
input (abbrev, dabbrev, hippie-expandand completion come to mind)
alongside a rich collection of tools for navigating among open
buffers. And these affordances have significantly increased over the
last few years with the arrival of packages like ido, company,
helm etc., each replete with different strategies for rapid task
completion such as flex and fuzzy matching. This article investigates
these tools in an eyes-free environment, specifically in the context
of Emacspeak and rapid task completion. I've not investigated every
possible package in this space — instead, I've picked a collection
of packages and techniques that have worked well in an eyes-free
context. Finally, the ultimate metric I use in each case is the time
to successful task completion — since at the end of the day, that's
the only metric that counts when it comes to user productivity.

2 Terminology

For this article, I will use terms suggestion and completion to
mean subtly different concepts. I'll also use terms explore and
filter in describing various phases in user interaction.

Offer the user some suggestions that help explore the space of choices. (metaphor: avoid the blank sheet of paper syndrome).
Filter the available choices based on user input with the goal of reaching the target as rapidly as possible.
User does not necessarily know what he is looking for, but expects to be able to recognize what he wants from the displayed choices.
User knows exactly what he wants, e.g., filename, or function-name, but would still like to get there with the fewest possible number of keystrokes, along with the needed memory aids to guide the decision.

Note that in practice, suggestions and completions work
hand-in-hand, with the visual display playing a central role in
guiding the user through the pace of available choices. In a typical
user interaction session, the space of suggestions gets filtered by
user input to produce the available completions (choices) for the next
round of user input — think of this as a
Suggest/Input/Filter/Target (SIFT) interaction loop. Similarly, explore and
target type activities typically go hand-in-hand, with explore
serving as a memory-aid for locating the target.

3 Tasks Where Suggestions And Completions Help Speed Up Task Completion

Here are exemplars of tasks that I perform often and where I require
all the help that Emacs can provide in completing the task as rapidly
as possible:

File Navigation
Navigating to and opening a file — either code or prose.
Content Navigation
Jump to a specific location (section, function, class/method, or pattern-match) in that file.
Buffer Navigation
Jump to an already open buffer in a long-running Emacs.

If that buffer existed — but has since been killed (by
midnight for example), then re-open that buffer.
I do everything in Emacs, so open buffers include a large
number of ORG and LaTeX documents, Web Pages opened in EWW
(news sites, documentation, blog articles), IM Chats (I use
jabber), Mail Buffers — both open folders and previously
sent messages, and much, much more.

Easily launch media streams including local and streaming media.
Open (or jump to an already open) EBook to continue reading.
Code Completion
Complete function/method-name as I type, with an easy affordance to move among the available choices. The Suggest/Input/Filter/Target interaction loop applies here as well.

Notice that as one performs all of these tasks, every target is an
Emacs buffer or Emacs buffer location. In the case of completion, the
target is a string that gets inserted at the current location.

4 Features Of Eyes-Free Interaction

Using spoken output — as opposed to a rich visual display — has
the following special features and/or drawbacks:

  1. A large visual display can offer the user many choices at a time,
    and the eye's ability to rapidly scan these choices makes for an
    extremely fast Suggest/Input/Filter/Target loop. As an example, an
    interface like helm can display a large number of initial
    choices, with the user filtering these down with a few strategic key-presses.
  2. Spoken output takes time — and there is simply no way around
    this — speeding up speech-rate helps to a point, but speaking
    50 choices very fast does not help the user in the explore
    phase. This means that effective filtering and ranking of the available
    choices takes on added importance.
  3. More importantly, picking a Suggest/Input/Filter/Target (SIFT)
    interaction loop that depends on a large display is sub-optimal
    for eyes-free interaction.
  4. Given (2,3), smart filtering, flex/fuzzy matching, and ranking
    based on past user behavior take on added importance in an
    eyes-free environment. As an aside, I have high hopes in this
    area for package prescient — though in my few days of usage,
    it has yet to make a difference in my productivity.
  5. For many of the tasks enumerated in the previous section, (2, 3
    and 4) make ido with flex and fuzzy matching extremely
    effective. In contrast, helm with similar flex and fuzzy
    matching (via packages helm-flx and helm-fuzzier) adds little
    extra benefit — and the fractional extra time to compute and
    display the choices can even lead to a minor productivity hit.
  6. When it comes to writing code with completion, package company
    has proven extremely effective. Notice that when writing code,
    one rarely if ever resorts to fuzzy matching — this may well
    be subjective. Speaking for myself, I cannot think of function
    or method names in the context of fuzzy matching — said
    differently, it's hard to think xl for function-name
    next-line — even though in a given filtering context, xl
    might define the shortest path through the available choices to
    the target next-line. Given this, emacspeak implements a
    company front-end that allows the user to navigate through the
    available choices with succinct spoken feedback, and I use those
    choices only after I have typed sufficiently many characters to
    have a manageable number of choices — said differently, though
    package company is set up to trigger after 3 characters have
    been typed, I usually end up typing more — and often resort to
    dabbrev or hippee-expand to input this longer prefix.
  7. Some of the shortcomings with eyes-free interaction enumerated
    above lead to my looking for effective work-arounds that might
    well work well outside the eyes-free context, e.g. when the
    available choices are too large to fit on a typical visual
    display. Interestingly, most of these have also been solved by
    mainstream Emacs developers in their never-ending/unerring quest for increased
    productivity — package ido and company are excellent exemplars.

  • Mapping Solutions To Tasks

This section maps the various solutions I use to speed up the tasks
enumerated earlier in this article.

4.1 File And Buffer Navigation

I use package ido with add-ons flx-ido and ido-completing-read+
(formerly ido-ubiquitous) as my primary/only solution for this
task. I've dabbled with package helm — primarily via command
helm-mini but have found almost no use-cases where I did better with
helm. I also use command org-switchb to quickly jump to any of my
open org buffers – since that automatically filters the choices
down for me — I can then get to the org-mode buffer I want with
one or two keystrokes. Notice that in all of these cases, I'm relying
on the fact that I mostly know what I want, i.e., the explore phase
does not start with an entirely blank sheet of paper.

4.2 Content Navigation

Incremental search is your biggest and most effective friend in
effective eyes-free interaction — this simply cannot be stressed
enough. That everything in Emacs is searchable via
incremental-search is a big win for eyes-free interaction. When you
have a large visual display, the human eye is the search interface of
first resort – you typically use a search-command only if the
target is below the fold or far away from the cursor. Because spoken
output takes time, I use isearch even when the target is one or two
lines away.

Structured navigation comes next in my toolbox for navigating content
imenu for code, and section navigation for documents (org,
LaTeX). I also use command occur to advantage since that provides a
quick way of finding all the desired targets in a document. Given that
program source-code uses indentation for displaying structure,
hbuilt-in command selective-display remains one of Emacs' hidden
treasures with respect to expanding/collapsing source-code.

Finally, I
use a combination of isearch and structured navigation in
org-mode buffres by collapsing the document, and then using
isearch to reveal the desired content fragment.
In the case of LaTeX documents, I use package reftex to
generate a navigation buffer that functions as an interactive table
of contents.

4.3 Locating And Playing Media

  1. I keep all my music content organized under ~/mp3.
  2. I keep playlist files that contain stream-links to my favorite
    Internet streams under emacspeak/media.
  3. The afore-mentioned techniques using ido enables me to launch
    local and streaming media with a small number of keystrokes. Once
    selected, the content is played via package emacspeak-m-player
    which provides Emacs bindings to all mplayer functionality
    via that program's slave-mode. In addition, Emacspeak also
    implements a smart emacspeak-m-player-locate-media which uses
    Emacs' integration with command locate to turn the located
    files matching a given pattern into an interactive play-list.

4.4 EBooks

Jumping to already open ebooks is no different than buffer
navigation. I organize all my ebooks under a single directory
tree, and module emacspeak-epub implements a bookshelf that
allows me to organize and browse my collection along various
axies. Finally, Emacspeak implements a light-weight bookmark
facility that works with eww so that I can save my place in an
ebook across Emacs sessions.

4.5 Code Completion

As covered earlier, I use company along with dabbrev and
hippee-expand while writing code. I also use yasnippet to
generate skeleton code. I use auto-correct-mode to
automatically correct repeated errors, and add abbrevs for
commonly occurring typos.

5 Summary

  1. Emacs' Suggest/Input/Filter/Target (SIFT) interaction loop is just as
    effective in eyes-free interaction — in fact more so .
  2. Fuzzy matching when filtering is a big win when working with spoken
    output — it leads to faster task completion.
  3. Navigating ones computing environment based on the underlying
    structure and semantics of electronic content is a major win —
    both when working with a visual or spoken display. The advantages
    just become evident far sooner in the eyes-free context due to the
    inherently temporal nature of spoken interaction.

Date: 2018-06-22 Fri 00:00

Author: T.V Raman

Created: 2018-06-23 Sat 17:22


-1:-- Effective Suggest And Complete In An Eyes-Free Environment (Post T. V. Raman ( 25, 2018 03:55 PM

Wilfred Hughes: Helpful: One Year On

It’s been a year since the first release of Helpful! It’s gained a ton of new features, and I’d love to share the highlights with you.

Tool Integration

Emacs has some excellent built-in debugging tools that I wanted to expose within Helpful. These tools missed the first release, but I’ve now had the chance to build them.

From a Helpful buffer, you can now toggle edebug on a function. This allows you to easily step through code.

You can also toggle tracing. Tracing is an underrated built-in feature of Emacs. You can use it to confirm functions have the inputs and outputs you’re expecting. It’s really useful when exploring unfamiliar code.

In this example, I’ve enabled tracing on projectile-project-root to see when it’s called, and what values it’s returning.


After some great user feedback, Helpful buffers now start with a summary of what you’re looking at.

Users often want a direct link to the source code, so this is included in the summary. Helpful also mentions if a function is interactive or autoloaded, just like describe-function. If a user doesn’t know what that means, those words now link to the relevant part of the Emacs manual!


Helpful tries to show all relevant information for the current thing. I’ve overhauled aliases with this in mind.

For example, if you view make-hash-table, you can now see that there is another alias of this function, but it’s now deprecated.

Modifying Variables

It’s now possible to set variables directly from Helpful buffers. This was inspired by counsel-set-variable, which has an excellent similar feature.

If a variable is a defcustom, then Helpful also includes a link to the relevant part of Customize.

Even Better Docstrings

Helpful now handles all Emacs docstring syntax. It handles references to keybindings, keymaps, and even supports the obscure features like \<foo-map> and \='.

fortran-mode is a great example of a docstring that uses a lot of Emacs docstring features.

Recent versions of Helpful try even harder to save you keystrokes. URLs are now automatically converted to links.

Finally, my favourite new feature is Info manual links. If a docstring mentions a section of the manual, Helpful converts it to a link.

Even better, if a symbol is documented in the Emacs manual, Helpful automatically adds a link at the bottom of the docstring! This hugely helps discoverability.

Installing It

Helpful is available on MELPA and MELPA stable. It’s become an indispensable part of my Emacs workflow, and I’m sure it will benefit you too.

-1:-- Helpful: One Year On (Post Wilfred Hughes ( 22, 2018 12:00 AM

emacshorrors: Determining if the server is started, or the wonders of server-running-p

Update: Bug report thread with a workaround.

(This is a contributed post by thblt )

Trivia: How can you determine if the current Emacs instance has the Emacs server running?

A quick search gives us three potential candidates: server-mode, (daemonp) and (server-running-p). That’s way too much, but surely one of them is the right one, isn’t it? Well, no. Because the real answer to this trivial question is: you can’t.

  • server-mode is t if, and only if, the server was started using the function with the same name. But there are other ways to run the server, like M-x server-start or emacs --daemon.
  • (daemonp) returns t if, and only if, Emacs was started in daemon mode.

What about (server-running-p), then? Well, it may look friendly, but here be monsters.

It starts by looking promising: after M-x server-start, (server-running-p) now returns t! Do we have a winner? Not yet! Let’s pop a new Emacs instance and eval (server-running-p) without starting the server. t again!

What’s happening? The truth is that (server-running-p) is not what it seems to be. Here’s its complete source code:

(defun server-running-p (&optional name)
  "Test whether server NAME is running.

Return values:
  nil              the server is definitely not running.
  t                the server seems to be running.
  something else   we cannot determine whether it's running without using
                   commands which may have to wait for a long time."
  (unless name (setq name server-name))
  (condition-case nil
      (if server-use-tcp
            (insert-file-contents-literally (expand-file-name name server-auth-dir))
            (or (and (looking-at "127\\.0\\.0\\.1:[0-9]+ \\([0-9]+\\)")
                     (assq 'comm
                            (string-to-number (match-string 1))))
          :name "server-client-test" :family 'local :server nil :noquery t
          :service (expand-file-name name server-socket-dir)))
    (file-error nil)))

The horror starts as soon as the docstring. The -p suffix in the name promises a predicate, that is, a boolean function. But in server-running-p, non-nil is not a loud and clear “Yes!”, it’s a mumbled “well, maybe, who knows?”. Ternary logic, because Emacs is above the law of excluded middle.

But what does this function do? It tries to determine if a server called NAME is running, by assuming that this server would be configured exactly the same as the running instance. It may end up looking at the socket file of the current server, or it may try to initiate a TCP connection, which is extremely expensive. server-running-p is the kind of function you may be tempted to call while building the mode line: try it, and get an instant and unrecoverable Emacs freeze. What it’s supposed to be useful for is extremely unclear. It’s unable to determine if the running instance has a server — but it uses this server’s config to search for a potentially completely different server.

-1:-- Determining if the server is started, or the wonders of server-running-p (Post Vasilij Schneidermann)--L0--C0--June 20, 2018 07:51 AM

Chen Bin (redguardtoo): How to spell check function/variable in Emacs

CREATED: <2018-06-17 Sun>

UPDATED: <2018-09-06 Thu>

This article explains how to spell check name of function and variable while programming in Emacs.

It uses options --run-together from GNU Aspell to check camel cased word.

But this solution is not perfect. It wrongly identifies two character interior word as typo. For example, "onChange" is identified as typo because the interior word "on". Another issue is namespace of function name. For example, "MS" from "MSToggleButton" is alias of "Microsoft". If "MS" is identified as typo, every word containing namespace "MS" is regarded as typo.

In this article,

  • I will explain how Emacs spell checker works
  • Then we study the algorithm of aspell (We can learn nothing from hunspell because hunspell can NOT check camel case word at all)
  • Finally, I will show you a complete solution which works with either aspell or hunspell

In Emacs, a built in plugin Fly Spell is in charge of spell check. It passes the options and plain text to command line tool aspell. Aspell sends back the typos of text into Fly Spell. Fly Spell then select certain typos to display. For example, when flyspell-prog-mode is on, only typos in comments and strings are visible.

So aspell doesn't understand syntax of any programming language. It scans plain text and report all typos to Fly Spell.

In aspell, there are two extra "run-together" word options:

  • --run-together-limit is "Maximum number of words can be strung together"
  • --run-together-min is "Minimal length of interior words"

Let's study the code of aspell to understand these two options. The "run-together" algorithm in implemented in function Working::check_word of file "modules/speller/default/suggest.cpp".

In order to help you understand this function, I documented the code line by line,

class Working : public Score {
  unsigned check_word(char * word, char * word_end, CheckInfo * ci, unsigned pos = 1);
unsigned Working::check_word(char * word, char * word_end,  CheckInfo * ci,
                             /* it WILL modify word */
                             unsigned pos)
  // check the whole word before go into run-together mode
  unsigned res = check_word_s(word, ci);
  // if `res` is true, it's a valid word, don't bother run-together
  if (res) return pos + 1;
  // it's typo because number of interior words is greater than "--run-together-limit"
  if (pos + 1 >= sp->run_together_limit_) return 0;

  // `i` is the `end` of interior word, the poition AFTER last character of interior word
  for (char * i = word + sp->run_together_min_; 
       // already checked the whole word; besides, any interior word whose size is less 
       // than "--run-together-min" is regarded as invalid
       i <= word_end - sp->run_together_min_;
    char t = *i;

    // read the interior word by set the character at `end` position to '\0'
    *i = '\0';
    res = check_word_s(word, ci);
    // restore original character at `end` position
    *i = t;

    // Current interior word is invalid, we need append the character at current
    //  `end` position to creata new interior word.
    //  Inncrement `i` because `i` always points to the `end` of interior word
    if (!res) continue;

    // Current interior word is valid, strip it from the whole word to create a totally
    // new word for `check_word`, `check_word` is a recursive function
    res = check_word(i, word_end, ci + 1, pos + 1);
    if (res) return res;
  memset(ci, 0, sizeof(CheckInfo));
  return 0;

Let's use "hisHelle" as demo how check_word runs:

  • "word" points to string "hisHelle" (in C/C++, string is character array. The last character of array is character '\0')
  • "sp->run_together_min_" is 3, so "i" initially points to the character "H", at the end of interior word "his"
  • "check_word_s" return "true" for interior word "his"
  • So we strip "his" from "hisHelle" and recursively call "check_word" to check new word "Helle"
  • In the new context of "check_word", we extract "Hel" from "Helle" initially
  • "Hel" is invalid. So we extract "Hell" from "Helle" and get new word "e" and recursively apply "check_word" on "e"
  • "e" is not valid and at the end of recursion. So "hisHelle" is a typo

Here is our conclusion after studying the code:

  • --run-together-limit could not be bigger if your computer got enough memory. It's default value is 8. I prefer 16.
  • --run-together-min can't be 2 because too many typos are combination of "correct" two character interior words ("hehe", "isme", …)
  • --run-together-min can't be greater than 3, or else, too many "correct" three character interior words are regarded as invalid ("his", "her", "one", "two")
  • --run-together-min should always be 3 which is its default value. Actually, it should never be tweak-able by user at the beginning

Since --run-together-min is 3. the word "onChange" is always regarded as typo because of two character interior word "on". Since there is nothing we can do at aspell side, we have to turn to Emacs to fix this problem.

When Emacs got potential typo on Emacs side, we can strip out all the two character interior word from original word and spell check new word again.

Please note hunspell can't check camel case word at all while aspell can check camel case word but with a little noise. So there is nothing we can study in hunspell.

We will use Emacs Lisp to solve this problem completely, using either aspell or hunspell.

We can attach a predicate into specific major-mode. The predicate return t if current word at cursor is typo,

(defun js-flyspell-verify ()
  (let* ((font-face (get-text-property (- (point) 1) 'face))
         (word (thing-at-point 'word)))
    (message "font-face=%s word=%s" font-face word)
(put 'js2-mode 'flyspell-mode-predicate 'js-flyspell-verify)

As you can see from above code, we have full control on what typos should be displayed in js-flyspell-verify. So predicate is actually the last chance to fix wrongly identified typos.

Here is complete setup you can paste into .emacs (I setup for js2-mode and rjsx-mode but code is generic enough).

Please note function split-camel-case split a camel case word into a list of sub-words. I just assume any sub-word whose length is less than three is not a typo.

(defun split-camel-case (word)
  "Split camel case WORD into a list of strings.
Ported from ''."
  (let* ((case-fold-search nil)
         (len (length word))
         ;; ten sub-words is enough
         (runes [nil nil nil nil nil nil nil nil nil nil])
         (runes-length 0)
         (i 0)
         (last-class 0)
         (class 0)

    ;; split into fields based on class of character
    (while (< i len)
      (setq ch (elt word i))
       ;; lower case
       ((and (>= ch ?a) (<= ch ?z))
        (setq class 1))
       ;; upper case
       ((and (>= ch ?A) (<= ch ?Z))
        (setq class 2))
       ((and (>= ch ?0) (<= ch ?9))
        (setq class 3))
        (setq class 4)))

       ((= class last-class)
        (aset runes
              (1- runes-length)
              (concat (aref runes (1- runes-length)) (char-to-string ch))))
        (aset runes runes-length (char-to-string ch))
        (setq runes-length (1+ runes-length))))
      (setq last-class class)
      ;; end of while
      (setq i (1+ i)))

    ;; handle upper case -> lower case sequences, e.g.
    ;;     "PDFL", "oader" -> "PDF", "Loader"
    (setq i 0)
    (while (< i (1- runes-length))
      (let* ((ch-first (aref (aref runes i) 0))
             (ch-second (aref (aref runes (1+ i)) 0)))
        (when (and (and (>= ch-first ?A) (<= ch-first ?Z))
                   (and (>= ch-second ?a) (<= ch-second ?z)))
          (aset runes (1+ i) (concat (substring (aref runes i) -1) (aref runes (1+ i))))
          (aset runes i (substring (aref runes i) 0 -1))))
      (setq i (1+ i)))

    ;; construct final result
    (setq i 0)
    (while (< i runes-length)
      (when (> (length (aref runes i)) 0)
        (setq rlt (add-to-list 'rlt (aref runes i) t)))
      (setq i (1+ i)))

(defun flyspell-detect-ispell-args (&optional run-together)
  "If RUN-TOGETHER is true, spell check the CamelCase words.
Please note RUN-TOGETHER will make aspell less capable. So it should only be used in prog-mode-hook."
  ;; force the English dictionary, support Camel Case spelling check (tested with aspell 0.6)
  (let* ((args (list "--sug-mode=ultra" "--lang=en_US"))args)
    (if run-together
        (setq args (append args '("--run-together" "--run-together-limit=16"))))

;; {{ for aspell only, hunspell does not need setup `ispell-extra-args'
(setq ispell-program-name "aspell")
(setq-default ispell-extra-args (flyspell-detect-ispell-args t))
;; }}

;; ;; {{ hunspell setup, please note we use dictionary "en_US" here
;; (setq ispell-program-name "hunspell")
;; (setq ispell-local-dictionary "en_US")
;; (setq ispell-local-dictionary-alist
;;       '(("en_US" "[[:alpha:]]" "[^[:alpha:]]" "[']" nil ("-d" "en_US") nil utf-8)))
;; ;; }}

(defvar extra-flyspell-predicate '(lambda (word) t)
  "A callback to check WORD.  Return t if WORD is typo.")

(defun my-flyspell-predicate (word)
  "Use aspell to check WORD.  If it's typo return t."
  (let* ((cmd (cond
               ;; aspell: `echo "helle world" | aspell pipe`
               ((string-match-p "aspell$" ispell-program-name)
                (format "echo \"%s\" | %s pipe"
               ;; hunspell: `echo "helle world" | hunspell -a -d en_US`
                (format "echo \"%s\" | %s -a -d en_US"
         (cmd-output (shell-command-to-string cmd))
    ;; (message "word=%s cmd=%s" word cmd)
    ;; (message "cmd-output=%s" cmd-output)
     ((string-match-p "^&" cmd-output)
      ;; it's a typo because at least one sub-word is typo
      (setq rlt t))
      ;; not a typo
      (setq rlt nil)))

(defun js-flyspell-verify ()
  (let* ((case-fold-search nil)
         (font-matched (memq (get-text-property (- (point) 1) 'face)
         (rlt t))
     ((not font-matched)
      (setq rlt nil))
     ;; ignore two character word
     ((< (length (setq word (thing-at-point 'word))) 2)
      (setq rlt nil))
     ;; handle camel case word
     ((and (setq subwords (split-camel-case word)) (> (length subwords) 1))
      (let* ((s (mapconcat (lambda (w)
                              ;; sub-word wholse length is less than three
                              ((< (length w) 3)
                               ;; special characters
                              ((not (string-match-p "^[a-zA-Z]*$" w))
                               w))) subwords " ")))
        (setq rlt (my-flyspell-predicate s))))
      (setq rlt (funcall extra-flyspell-predicate word))))

(put 'js2-mode 'flyspell-mode-predicate 'js-flyspell-verify)
(put 'rjsx-mode 'flyspell-mode-predicate 'js-flyspell-verify)

Optionally, you could see for my real world setup.

UPDATE: Now you can use wucuo which is complete and out of box solution to spell check code.

-1:-- How to spell check function/variable in Emacs (Post Chen Bin)--L0--C0--June 17, 2018 03:16 AM | Emacs: Org Table Spreadsheet

My notes on Org Table Spreadsheet feature.


Table 1: Org table Normalizing
Normalized col $1 Normalized col $3 Ratio of col $2 / $4
Col $1 Col $2 Col $3 Col $4 Col $5
79922.1 6.85 0.146993824 4.27 1.60
79185.9 6.78 0.146976008 4.27 1.59
64041.0 5.48 0.147067031 4.27 1.28
15452.5 1.32 0.034456713 1.00 1.32
11675.7 1.00 0.034460162 1.00 1.00

Equations Breakdown

Equation: #+tblfm: $2=$1/@7$1;%0.2f::$4=$3/@7$3;%0.2f::$5=$2/$4;%0.2f

  • $2=$1/@7$1 – Assign the value of a field in column 2 ($2) to the value of the field in column 1 in the same row ($1) divided by the value of the field in row 7, column 1 (@7$1).
    • @ is row, $ is column.
    • Row and column numbers start with 1 (not 0).
  • $4=$3/@7$3 – Similar to above, but with different row/column numbers.
  • $5=$2/$4 – Assign the value of a field in column 5 ($5) to the value of the field in column 2 in the same row ($2) divided by the value of the field in column 4 in the same row as well ($4).
  • ; is used to separate the equation from the formatting.
  • For all the 3 equations, formatting is applied using %0.2f i.e. the numbers will be formatted with 2 decimal places. See Field Formatters in Org table for more info.
  • Each of those equations are applied to the same table by concatenating them with ::.

Evaluate the whole table

Do C-u C-c C-c with point anywhere in the table, or do C-c C-c with point on the #+tblfm line.


-1:-- Org Table Spreadsheet (Post Kaushal Modi)--L0--C0--June 13, 2018 02:24 PM

Emacs café: Using Ledger for YNAB-like envelope budgeting

Bye bye Elbank

I have to start this post with this: I will not be actively maintaining Elbank anymore, simply because I switched back to Ledger. If someone wants to take over, please contact me!

The main reason for switching is budgeting. While Elbank was a cool experiment, it is not an accounting software, and inherently lacks support for powerful budgeting.

When I started working on Elbank as a replacement for Ledger, I was looking for a reporting tool within Emacs that would fetch bank transactions automatically, so I wouldn’t have to enter transactions by hand (this is a seriously tedious task, and I grew tired of doing it after roughly two years, and finally gave up).

Since then, I learned about ledger-autosync and boobank, which I use to sync my bank statements with Ledger (more about that in another post).

YNAB’s way of budgeting

I only came across YNAB recently. While I won’t use their software (being a non-free web application, and, you know… there’s no M-x ynab), I think that the principles behind it are really appealing for personal budgeting. I encourage you to read more about it (or grab a copy of the book, it’s great), but here’s the idea.

  1. Budget every euro: Quite simple once you get it. Every single Euro you have should be in a budget envelope. You should assign a job to every Euro you earn (that’s called zero-based, envelope system).

  2. Embrace your true expenses: Plan for larger and less frequent expenses, so when a yearly bill arrives, or your car breaks down, you’ll be covered.

  3. Roll with the punches: Address overspending as it happens by taking money overspent from another envelope. As long as you keep budgeting, you’re succeeding.

  4. Age your money: Spend less than you earn, so your money stays in the bank account longer. As you do that, the age of your money will grow, and once you reach the goal of spending money that is at least one month old, you won’t worry about that next bill.

Implementation in Ledger

I assume that you are familiar with Ledger, but if not I recommend reading its great introduction and tutorial.

The implementation in Ledger uses plain double-entry accounting. I took most of it from Sacha, with some minor differences.

Budgeting new money

After each income transaction, I budget the new money:

2018-06-12 Employer
    Assets:Bank:Checking                        1600.00 EUR
    Income:Salary                              -1600.00 EUR

2018-06-12 Budget
    [Assets:Budget:Food]                         400.00 EUR
    [Assets:Budget:Rent]                         600.00 EUR
    [Assets:Budget:Utilities]                    600.00 EUR
    [Equity:Budget]                            -1600.00 EUR

Did you notice the square brackets around the accounts of the budget transaction? It’s a feature Ledger calls virtual postings. These postings are not considered real, and won’t be present in any report that uses the --real flag. This is exactly what we want, since it’s a budget allocation and not a “real” transaction. Therefore we’ll use the --real flag for all reports except for our budget report.

Automatically crediting budget accounts when spending money

Next, we need to credit the budget accounts each time we spend money. Ledger has another neat feature called automated transactions for this:

= /Expenses/
    [Assets:Budget:Unbudgeted]                    -1.0
    [Equity:Budget]                                1.0

= /Expenses:Food/
    [Assets:Budget:Food]                          -1.0
    [Assets:Budget:Unbudgeted]                     1.0
= /Expenses:Rent/
    [Assets:Budget:Rent]                          -1.0
    [Assets:Budget:Unbudgeted]                     1.0
= /Expenses:Utilities/
    [Assets:Budget:Utilities]                     -1.0
    [Assets:Budget:Unbudgeted]                     1.0

Every expense is taken out of the Assets:Budget:Unbudgeted account by default.

This forces me to budget properly, as Assets:Budget:Unbudgeted should always be 0 (if it is not the case I immediately know that there is something wrong going on).

All other automatic transactions take money out of the Assets:Budget:Unbudgeted account instead of Equity:Budget account.

A Budget report

This is the final piece of the puzzle. Here’s the budget report command:

ledger --empty -S -T -f ledger.dat bal ^assets:budget

If we have the following transactions:

2018/06/12 Groceries store
    Expenses:Food                                123.00 EUR

2018/06/12 Landlord
    Expenses:Rent                                600.00 EUR

2018/06/12 Internet provider
    Expenses:Utilities:Internet                   40.00 EUR

Here’s what the report looks like:

          837.00 EUR  Assets:Budget
          560.00 EUR    Utilities
          277.00 EUR    Food
                   0    Rent
                   0    Unbudgeted
          837.00 EUR


Ledger is amazingly powerful, and provides a great framework for YNAB-like budgeting. In a future post I’ll explain how I automatically import my bank transactions using a mix of ledger-autosync and weboob.

-1:-- Using Ledger for YNAB-like envelope budgeting (Post Nicolas Petton)--L0--C0--June 12, 2018 07:20 PM

Sanel Zukan: declutter - read online content without clutter

Last two days I've been hacking on a small Emacs mode called declutter and this will be the first version announcement.

What is declutter and why?

I often use Emacs to read long, online articles, which gives me plenty of options - I can save text for offline reading, I can read content with my favorite color and terminal setup, I have my shortcuts for fast navigation and so on.

However, modern sites are using more and more client-side rendering which doesn't play well with EWW. Also, there is a recent trend I'm not really fan of, and that is putting paywall on anything worth of reading.

So, someone smart I'm not affiliated with, created service, which is able to solve above problems. At least most of it, which is perfectly fine with me. And that service is free to use, of course.

declutter, in short, will use to get readable html content, including paywall protected sites straight from Emacs. Then it will render it in readable form in separate buffer.

So, I'm inviting you to try it, test it and let me know for your comments. And please report if something breaks.


-1:-- declutter - read online content without clutter (Post)--L0--C0--June 11, 2018 10:00 PM

emacsair: Magit 2.13 released

I am excited to announce the release of Magit version 2.13, consisting of 166 commits since the last feature release two months ago.
-1:-- Magit 2.13 released (Post)--L0--C0--June 02, 2018 05:00 AM

Alex Bennée: dired-rsync 0.4 released

I started hacking on this a while back but I’ve finally done the house-keeping tasks required to make it a proper grown up package.

dired-rsync is a simple command which you can use to trigger an rsync copy from within dired. This is especially useful when you want to copy across large files from a remote server without locking up Emacs/Tramp. The rsync just runs as an inferior process in the background.

Today was mainly a process of cleaning up the CI and fixing any issues with it. I’d still like to add some proper tests but the whole thing is interactive and that seems to be tricky for Emacs to test. Anyway I’ve now tagged 0.4 so it will be available from MELPA Stable once it rebuilds. You can of course grab the building edge from MELPA any time 😉

-1:-- dired-rsync 0.4 released (Post Alex)--L0--C0--June 01, 2018 05:12 PM

Alexander Gromnitsky: Emacs & gpg files: use the minibuffer for password prompts

In the past Emacs was communicating w/ gnupg directly & hence was responsible for reading/sending/catching passwords. In contrast, Emacs 26.1, by default, fully delegates the password handling to gpg2.

The code for the interoperation w/ gpg1 is still present in the Emacs core, but it's no longer advertised in favour of gpg2 + elpa pinentry.

If you don't want an additional overhead or a special gpg-agent setup, it's still possible to use gpg1 for (en|de)crypting ops.

Say we have a text file we want to encrypt & then transparently edit in Emacs afterwards. The editor should remember the correct pw for the file & not bother us w/ the pw during the file saving op.

$ rpm -qf `which gpg gpg2`

$ echo rain raine goe away, little Johnny wants to play | gpg -c > nr.gpg
$ file nr.gpg
nr.gpg: GPG symmetrically encrypted data (AES cipher)

If you have both gpg1 & gpg2 installed, Emacs ignores gpg1 completely. E.g., run 'emacs -Q' & open nr.gpg file–gpg2 promptly contacts gpg-agent, which, in turn, runs the pinentry app:

Although, it may look as if everything is alright, try to edit the decrypted file & then save it. The pinentry window will reappear & you'll be forced to enter the pw twice.

The Emacs mode that handles the gnupg dispatch is called EasyPG Assistant. To check its current state, use epg-find-configuration fn:

ELISP> (car (epg-find-configuration 'OpenPGP))
(program . "/usr/bin/gpg2")

We can force EasyPG to use gpg1, despite that it's not documented anywhere.

The actual config data is located in epg-config--program-alist var:

ELISP> epg-config--program-alist
((OpenPGP epg-gpg-program
("gpg2" . "2.1.6")
("gpg" . "1.4.3"))
(CMS epg-gpgsm-program
("gpgsm" . "2.0.4")))

Here, if we shadow the gpg2 entry in the alist, EasyPG would regenerate a new config for all the (en|de)crypting ops on the fly:

(require 'epg-config)
(add-to-list 'epg-config--program-alist `(OpenPGP epg-gpg-program ("gpg" . ,epg-gpg-minimum-version)))
(setq epa-file-cache-passphrase-for-symmetric-encryption t)
(setq epg--configurations nil)

Now, if you open nr.gpg afresh, Emacs neither should use the gpg-agent any more:

Nor should it ask for the pw when you'll do edit+save later on.

To clear the internal pw cache, type

ELISP> (setq epa-file-passphrase-alist nil)
-1:-- Emacs &amp; gpg files: use the minibuffer for password prompts (Post ag ( 01, 2018 07:28 AM

Chris Wellons: Emacs 26 Brings Generators and Threads

Emacs 26.1 was recently released. As you would expect from a major release, it comes with lots of new goodies. Being a bit of an Emacs Lisp enthusiast, the two most interesting new features are generators (iter) and native threads (thread).

Correction: Generators were actually introduced in Emacs 25.1 (Sept. 2016), not Emacs 26.1. Doh!


Generators are one of those cool language features that provide a lot of power at a small implementation cost. They’re like a constrained form of coroutines, but, unlike coroutines, they’re typically built entirely on top of first-class functions (e.g. closures). This means no additional run-time support is needed in order to add generators to a language. The only complication is the changes the compiler. Generators are not compiled the same way as normal functions despite looking so similar.

What’s perhaps coolest of all about lisp-family generators, including Emacs Lisp, is that the compiler component can be implemented entirely with macros. The compiler need not be modified at all, making generators no more than a library, and not actually part of the language. That’s exactly how they’ve been implemented in Emacs Lisp (emacs-lisp/generator.el).

So what’s a generator? It’s a function that returns an iterator object. When an iterator object is invoked (e.g. iter-next) it evaluates the body of the generator. Each iterator is independent. What makes them unusual (and useful) is that the evaluation is paused in the middle of the body to return a value, saving all the internal state in the iterator. Normally pausing in the middle of functions isn’t possible, which is what requires the special compiler support.

Emacs Lisp generators appear to be most closely modeled after Python generators, though it also shares some similarities to JavaScript generators. What makes it most like Python is the use of signals for flow control — something I’m not personally enthused about (though see also). When a Python generator completes, it throws a StopItertion exception. In Emacs Lisp, it’s an iter-end-of-sequence signal. A signal is out-of-band and avoids the issue relying on some special in-band value to communicate the end of iteration.

In contrast, JavaScript’s solution is to return a “rich” object wrapping the actual yield value. This object has a done field that communicates whether iteration has completed. This avoids the use of exceptions for flow control, but the caller has to unpack the rich object.

Fortunately the flow control issue isn’t normally exposed to Emacs Lisp code. Most of the time you’ll use the iter-do macro or (my preference) the new cl-loop keyword iter-by.

To illustrate how a generator works, here’s a really simple iterator that iterates over a list:

(iter-defun walk (list)
  (while list
    (iter-yield (pop list))))

Here’s how it might be used:

(setf i (walk '(:a :b :c)))

(iter-next i)  ; => :a
(iter-next i)  ; => :b
(iter-next i)  ; => :c
(iter-next i)  ; error: iter-end-of-sequence

The iterator object itself is opaque and you shouldn’t rely on any part of its structure. That being said, I’m a firm believer that we should understand how things work underneath the hood so that we can make the most effective use of at them. No program should rely on the particulars of the iterator object internals for correctness, but a well-written program should employ them in a way that best exploits their expected implementation.

Currently iterator objects are closures, and iter-next invokes the closure with its own internal protocol. It asks the closure to return the next value (:next operation), and iter-close asks it to clean itself up (:close operation).

Since they’re just closures, another really cool thing about Emacs Lisp generators is that iterator objects are generally readable. That is, you can serialize them out with print and bring them back to life with read, even in another instance of Emacs. They exist independently of the original generator function. This will not work if one of the values captured in the iterator object is not readable (e.g. buffers).

How does pausing work? Well, one of other exciting new features of Emacs 26 is the introduction of a jump table opcode, switch. I’d lamented in the past that large cond and cl-case expressions could be a lot more efficient if Emacs’ byte code supported jump tables. It turns an O(n) sequence of comparisons into an O(1) lookup and jump. It’s essentially the perfect foundation for a generator since it can be used to jump straight back to the position where evaluation was paused.

Buuut, generators do not currently use jump tables. The generator library predates the new switch opcode, and, being independent of it, its author, Daniel Colascione, went with the best option at the time. Chunks of code between yields are packaged as individual closures. These closures are linked together a bit like nodes in a graph, creating a sort of state machine. To get the next value, the iterator object invokes the closure representing the next state.

I’ve manually macro expanded the walk generator above into a form that roughly resembles the expansion of iter-defun:

(defun walk (list)
  (let (state)
    (cl-flet* ((state-2 ()
                 (signal 'iter-end-of-sequence nil))
               (state-1 ()
                 (prog1 (pop list)
                   (when (null list)
                     (setf state #'state-2))))
               (state-0 ()
                 (if (null list)
                   (setf state #'state-1)
      (setf state #'state-0)
      (lambda ()
        (funcall state)))))

This omits the protocol I mentioned, and it doesn’t have yield results (values passed to the iterator). The actual expansion is a whole lot messier and less optimal than this, but hopefully my hand-rolled generator is illustrative enough. Without the protocol, this iterator is stepped using funcall rather than iter-next.

The state variable keeps track of where in the body of the generator this iterator is currently “paused.” Continuing the iterator is therefore just a matter of invoking the closure that represents this state. Each state closure may update state to point to a new part of the generator body. The terminal state is obviously state-2. Notice how state transitions occur around branches.

I had said generators can be implemented as a library in Emacs Lisp. Unfortunately theres a hole in this: unwind-protect. It’s not valid to yield inside an unwind-protect form. Unlike, say, a throw-catch, there’s no mechanism to trap an unwinding stack so that it can be restarted later. The state closure needs to return and fall through the unwind-protect.

A jump table version of the generator might look like the following. I’ve used cl-labels since it allows for recursion.

(defun walk (list)
  (let ((state 0))
        ((closure ()
           (cl-case state
             (0 (if (null list)
                    (setf state 2)
                  (setf state 1))
             (1 (prog1 (pop list)
                  (when (null list)
                    (setf state 2))))
             (2 (signal 'iter-end-of-sequence nil)))))

When byte compiled on Emacs 26, that cl-case is turned into a jump table. This “switch” form is closer to how generators are implemented in other languages.

Iterator objects can share state between themselves if they close over a common environment (or, of course, use the same global variables).

(setf foo
      (let ((list '(:a :b :c)))
          (iter-lambda ()
            (while list
              (iter-yield (pop list)))))
          (iter-lambda ()
            (while list
              (iter-yield (pop list))))))))

(iter-next (nth 0 foo))  ; => :a
(iter-next (nth 1 foo))  ; => :b
(iter-next (nth 0 foo))  ; => :c

For years there has been a very crude way to “pause” a function and allow other functions to run: accept-process-output. It only works in the context of processes, but five years ago this was sufficient for me to build primitives on top of it. Unlike this old process function, generators do not block threads, including the user interface, which is really important.


Emacs 26 also bring us threads, which have been attached in a very bolted on fashion. It’s not much more than a subset of pthreads: shared memory threads, recursive mutexes, and condition variables. The interfaces look just like they do in pthreads, and there hasn’t been much done to integrate more naturally into the Emacs Lisp ecosystem.

This is also only the first step in bringing threading to Emacs Lisp. Right now there’s effectively a global interpreter lock (GIL), and threads only run one at a time cooperatively. Like with generators, the Python influence is obvious. In theory, sometime in the future this interpreter lock will be removed, making way for actual concurrency.

This is, again, where I think it’s useful to contrast with JavaScript, which was also initially designed to be single-threaded. Low-level threading primitives weren’t exposed — though mostly because JavaScript typically runs sandboxed and there’s no safe way to expose those primitives. Instead it got a web worker API that exposes concurrency at a much higher level, along with an efficient interface for thread coordination.

For Emacs Lisp, I’d prefer something safer, more like the JavaScript approach. Low-level pthreads are now a great way to wreck Emacs with deadlocks (with no C-g escape). Playing around with the new threading API for just a few days, I’ve already had to restart Emacs a bunch of times. Bugs in Emacs Lisp are normally a lot more forgiving.

One important detail that has been designed well is that dynamic bindings are thread-local. This is really essential for correct behavior. This is also an easy way to create thread-local storage (TLS): dynamically bind variables in the thread’s entrance function.

;;; -*- lexical-binding: t; -*-

(defvar foo-counter-tls)
(defvar foo-path-tls)

(defun foo-make-thread (path)
   (lambda ()
     (let ((foo-counter-tls 0)
           (foo-name-tls path))

However, cl-letf “bindings” are not thread-local, which makes this otherwise incredibly useful macro quite dangerous in the presence of threads. This is one way that the new threading API feels bolted on.

Building generators on threads

In my stack clashing article I showed a few different ways to add coroutine support to C. One method spawned per-coroutine threads, and coordinated using semaphores. With the new threads API in Emacs, it’s possible to do exactly the same thing.

Since generators are just a limited form of coroutines, this means threads offer another, very different way to implement them. The threads API doesn’t provide semaphores, but condition variables can fill in for them. To “pause” in the middle of the generator, just wait on a condition variable.

So, naturally, I just had to see if I could make it work. I call it a “thread iterator” or “thriter.” The API is very similar to iter:

This is merely a proof of concept so don’t actually use this library for anything. These thread-based generators are about 5x slower than iter generators, and they’re a lot more heavy-weight, needing an entire thread per iterator object. This makes thriter-close all the more important. On the other hand, these generators have no problem yielding inside unwind-protect.

Originally this article was going to dive into the details of how these thread-iterators worked, but thriter turned out to be quite a bit more complicated than I anticipated, especially as I worked towards feature matching iter.

The gist of it is that each side of a next/yield transaction gets its own condition variable, but share a common mutex. Values are passed between the threads using slots on the iterator object. The side that isn’t currently running waits on a condition variable until the other side frees it, after which the releaser waits on its own condition variable for the result. This is similar to asynchronous requests in Emacs dynamic modules.

Rather than use signals to indicate completion, I modeled it after JavaScript generators. Iterators return a cons cell. The car indicates continuation and the cdr holds the yield result. To terminate an iterator early (thriter-close or garbage collection), thread-signal is used to essentially “cancel” the thread and knock it off the condition variable.

Since threads aren’t (and shouldn’t be) garbage collected, failing to run a thread-iterator to completion would normally cause a memory leak, as the thread sits there forever waiting on a “next” that will never come. To deal with this, there’s a finalizer is attached to the iterator object in such a way that it’s not visible to the thread. A lost iterator is eventually cleaned up by the garbage collector, but, as usual with finalizers, this is only a last resort.

The future of threads

This thread-iterator project was my initial, little experiment with Emacs Lisp threads, similar to why I connected a joystick to Emacs using a dynamic module. While I don’t expect the current thread API to go away, it’s not really suitable for general use in its raw form. Bugs in Emacs Lisp programs should virtually never bring down Emacs and require a restart. Outside of threads, the few situations that break this rule are very easy to avoid (and very obvious that something dangerous is happening). Dynamic modules are dangerous by necessity, but concurrency doesn’t have to be.

There really needs to be a safe, high-level API with clean thread isolation. Perhaps this higher-level API will eventually build on top of the low-level threading API.

-1:-- Emacs 26 Brings Generators and Threads (Post)--L0--C0--May 31, 2018 05:45 PM

Timo Geusch: Emacs 26.1 has been released (and it’s already on Homebrew)

Saw the announcement on on the GNU Emacs mailing list this morning. Much to my surprise, it’s also already available on homebrew. So my Mac is now sporting a new fetching version of Emacs as well :). I’ve been running Read More

The post Emacs 26.1 has been released (and it’s already on Homebrew) appeared first on The Lone C++ Coder's Blog.

-1:-- Emacs 26.1 has been released (and it’s already on Homebrew) (Post Timo Geusch)--L0--C0--May 28, 2018 05:32 PM | Emacs: How do I write "Org mode"?

You write it just like that in the title — “Org” with capital “O”, and then lower-case “mode” separated by a space.

A super-quick intro to Org mode

Org mode is a fantastic major mode for Emacs, and people use it for all sorts of things like keeping notes, maintaining TODO lists, writing documentation, or even blogging—like I am doing here.


Every now and then, I would see “Org mode” and related phrases written in the “wild” (like blogs, Reddit posts, tweets) as Org-mode, org-manual, org file, etc., with a mix-and-match of cases and hyphens.

So here is an attempt to familiarize more people with the documentation standard for referring to “Org” stuff. Below I am quoting the text from the official Org Documentation Standards:

  • Prefer “Org mode” to “Org-mode” or “org-mode”. This is simply because it reflects an existing convention in The Emacs Manual which consistently documents mode names in this form - “Text mode”, “Outline mode”, “Mail mode”, etc.
  • Likewise refer, if at all possible, to “Org file or “Org buffer” meaning with, great generality, any file or buffer which requires use of some part of Org to edit it properly.
  • Org uses “org-…” to ring fence a name space for itself in the Emacs code base. This is obviously retained in code snippets.

The right way

Org mode, Org manual, Org file

Only in the Elisp code, is it called org-mode, because it is a major mode, and has to be named so in code by convention, and for its separate org-* name space.

But for blogging, documentation, etc. –

    Org foo it is.


-1:-- How do I write "Org mode"? (Post Kaushal Modi)--L0--C0--May 21, 2018 08:35 PM