Emacs literate configuration

Table of Contents

• Getting started
  • Pre-requisites
  • Configuring Emacs
    • Associate Org files to Emacs
  • A note on the use of org-mode for literate configuration
• Key bindings
  • General
    • Windows and buffers
    • Search and replace
    • Regular Expressions
    • Edit
    • Operations
    • Keyboard macros
    • Bookmarks
    • Completion and Ivy
    • Flycheck
    • Rectangles
  • File manager
  • Magit
  • Web browser
  • Polymode
  • Org mode
  • PDF tools
  • LaTeX
  • ESS
  • SQL
  • Screen
  • Function keys (F1–F12)
  • Misc
• Screenshots (outdated)

Getting started

Pre-requisites

This is a configuration for Emacs on Ubuntu Groovy (20.10). While most of it should work pretty much on any platform, installing Emacs (Emacs 26.3 at the time of writing) is Debian specific:

sudo apt install emacs

In addition, a few changes need to be made for PDF Tools and LaTeX. First, we need a additional library for PDF Tools:

sudo apt install elpa-pdf-tools-server libpoppler-glib-dev

Second, we define a central bibliographic folder at the level of the LaTeX distribution. We first check the actual BibTeX folder:

kpsewhich -show-path=.bib

This should contain: /home/<user>/.texlive2016/texmf-var/bibtex/bib//. We thus link the bibliographic folder (here ~/Work/Biblio/) to this folder:

mkdir -p ~/.texlive2016/texmf-var/bibtex/bib
ln -s ~/Work/Biblio/ ~/.texlive2016/texmf-var/bibtex/bib

Finally, we also add Ditaa for ASCII-based diagrams and PIP to install Python libraries; then format-sql for SQL formatting:

sudo apt install ditaa pip
sudo pip install format-sql

Configuring Emacs

To configure Emacs, the easiest is simply to clone this repository in the home directory :

git clone https://github.com/basille/.emacs.d ~

And that’s it! Opening Emacs will then do the magic! (several openings may be necessary for the magic to fully operate)

Associate Org files to Emacs

For Org users, there is a way to associate Org files to Emacs without associating all text files. First copy org.xml to the relevant folder in /usr/:

sudo cp org.xml /usr/share/mime/packages/org.xml

Then run:

sudo update-mime-database /usr/share/mime

If you are using Nautilus, restart it:

killall nautilus
nautilus -n &

Open nautilus, navigate to your file location, right click on it, select Open with, and search for Emacs (GUI).

A note on the use of org-mode for literate configuration

The original idea is to embed configuration bits into an Org file (init.org), which contains both code and explanations, making it a lot easier to navigate and configure. Emacs, with the use of org-babel is able to extract all configuration bits and assemble them in a standard init.el file, and its compiled version init.elc. The trick to make it work is that there is already an initial init.el file provided with this repository, which does the job the first time Emacs is loaded.

The initial init.el file also adjusts Xresources for Emacs (start without toolbars and scrollbars), and create the folder structure necessary for the rest of the configuration.

This file looks like that:

;; This file replaces itself with the actual configuration at first run.

;; Add X options to ~/.Xresources and initialize them
(write-region "
! Emacs geometry
!
emacs.menuBar: off
emacs.toolBar: off
emacs.verticalScrollBars: off
emacs.horizontalScrollbars: off

" nil "~/.Xresources" 'append)
(shell-command "xrdb -merge ~/.Xresources")

;; Create necessary directories and save abbrev silently
(mkdir (concat user-emacs-directory "cache") t)
(mkdir (concat user-emacs-directory "functions") t)
(mkdir (concat user-emacs-directory "save") t)
(mkdir "~/.emacs.d/save/" 1)
(setq abbrev-file-name "~/.emacs.d/cache/abbrev_defs")
(setq save-abbrevs 'silently)

;; We can't tangle without org!
(require 'org)
;; Open the configuration
(find-file (concat user-emacs-directory "init.org"))
;; tangle it
(org-babel-tangle)
;; load it
(load-file (concat user-emacs-directory "init.el"))
;; finally byte-compile it
(byte-compile-file (concat user-emacs-directory "init.el"))  

Note that this file is “locked” by Git, so that it is not modified after the complete init.el file is prepared, with the command:

git update-index --assume-unchanged init.el

To “unlock” it and make changes to the initial init.el file, use:

git update-index --no-assume-unchanged init.el

After this initial load, a function (tangle-init) ensures that a new init.el is generated at every modification of init.org (precisely every time init.org is saved).

(note for Magit: to show untracked files within subdirectories, switch the --untracked-files option with git config status.showUntrackedFiles all; switch back with git config status.showUntrackedFiles normal)

Key bindings

General

Windows and buffers

Key name	Operation
M-<arrows>	Move between windows
M-x <arrows>	Swap buffer between windows
C-~	Next window (key above TAB)
C-TAB	Cycle through buffers with IVY
C-x k	Kill THIS buffer
C-x +	Balance the sizes of windows
C-x C	Center the text horizontally

Search and replace

Key name	Operation
C-s	Search using Swiper
C-S-s	ivy-resume: go back to state of last search
C-S-y	Yank from history
C-r	Replace
C-M-r	Replace using a RegExp
C-+	Count words in region
C-=	Expand region (more: =; less: -)

Regular Expressions

Key name	Operation
. (dot)	Any single character except a newline
*	Zero or more repeats
+	One or more repeats
?	Zero or one repeat
^	Matches at line beginning
$	Matches at line end
[…]	Denotes a class of character to match
[^…]	Negates the class
\c	Quote characters otherwise having a special meaning in regular expressions
\w	Matches word-syntax character
\W	Matches non-word-syntax character
\<	Matches at word beginning
\>	Matches at word end
\b	Matches at word break
\B	Matches at non-word break
\(…\)	Groups a series of pattern elements to a single element
…\|…\|…	Matches one of the alternatives (“or”)
\N	Same text as n-th group

Edit

C-z	Undo
M-y	List kill ring (counsel-yank-pop)
C-c C-u	Cycle between snake_case, lowerCamelCase and kebab-case
M-q	Fill paragraph (indentation and lines)
C-u M-q	Justifies text (fixed width)
M-$	Check spelling of word at the cursor

Operations

Key name	Operation
C-.	Imenu (main sections/headers)
M-x	SMEX
M-!	Shell-command in the minibuffer
C-h m	Check modes in a buffer
C-x C-e	Evaluate lisp expression
C-x C-y	Evaluate lisp expression and replace with result
M-g M-g	Go to a given line number

Keyboard macros

Key name	Operation
C-x (	Start the macro
C-x )	Stop the macro
C-x e	Execute the macro once
C-u <n> C-x e	Execute the macro n times (0 for infinite; can be negative like - 5)

Bookmarks

Key name	Operation
C-x r m	Bookmark a file (works on directories and remote files too!)
C-x r b	Jump to a bookmark
C-x r l	List bookmarks

Completion and Ivy

Key name	Operation
C-s	Search using Swiper
C-S-s	ivy-resume: go back to state of last search
M-r	In Ivy mode, toggle regexp mode
M-o	In Ivy mode, presents valid actions from which to choose
↑	Uses current input instead of current candidate (e.g. useful to create files)
C-c C-o	ivy-occur: save current search into a new buffer (then C-d to delete lines)
TAB	Complete anything
or	Fold/unfold functions/regions (if code indented)

Flycheck

Key name	Operation
C-c ! v	Verify Flycheck setup for current buffer
C-c ! n / C-c ! p	Next and previous error
C-c ! l	List all errors in a buffer

Rectangles

Need to mark the upper left corner first (C-Space) then move to the other end of the rectangle.

Key name	Operation
C-S-<return>	Start rectangle mode
<return>	Moves cursor to next corner
M-<arrows>	Moves the entire rectangle selection

File manager

When opening a file with Ivy (C-x C-f):

Key name	Operation
//	Go to the root directory
~	Go to the home directory
ENTER	Enter Dired in this directory

In Dired (see mark here, and operations on file here) or ibuffer:

Key name	Operation
$	Go to a bookmark
(	Hide/show details
s	Sort by date or filename
S	Interactively sort (by filename, date, reverse, etc.)
i	Include subdirectory
o	Open in other window
m	Mark a file/folder
* /	Mark all folders
* s	Mark all files and folders
d	Mark for deletion
x	Execute deletion of marked files
u	Unmark a file/folder
U	Unmark all
t	Toggle mark
/	Dynamically filter files/folders (dired-narrow)
C	Copy (marked) file(s)
D	Delete (marked) file(s)
R	Rename (marked) file(s)
A	Search with regexp content of (marked) file(s)
Q	Search and replace with regexp content of (marked) file(s)
e	ediff two marked files
=	Launch ediff file at point, requesting for file to compare
w	Copy file name in the kill ring
M-0 w	Copy absolute path to the file

Magit

Key name	Operation
y	Show information on branches and commits
C-f	GitFlow from within Magit
K	git ls-files from within Magit
e	In case of conflicts, open Ediff on file
k	In case of conclicts, ask to delete our/their file

Web browser

Key name	Operation
<backspace>	Go to previous page
f	Open page with external browser

Polymode

Key name	Operation
C-<page down>	Move to previous chunk
C-<page up>	Move to next chunk
C-S-<page down>	Move to previous chunk of the same type
C-S-<page up>	Move to next chunk of the same type

Org mode

Key name	Operation
C-c C-q	Add a Tag in Org mode
	(use :TOC: for an automatic table of contents)
<s TAB	Add a source code block

PDF tools

Key name	Operation
P	Fit to the page
H	Fit to the height
W	Fit to the width
g	refreshes the PDF
h	opens the help of PDF tools
C-c C-a h	Highlight text and annotate (C-c C-c to commit)
C-c C-a t	Annotate anywhere (C-c C-c to commit)
C-c C-a o	Strike through text
C-c C-a D	Delete annotation
C-c C-a l	List annotations

LaTeX

Key name	Operation
C-c C-l	Shows compilation logs in LaTeX
C-c C-v	Calls viewer with forward search from LaTeX document
C-<left click>	Inverse search in PDF document
C-c =	Displays a dynamic table of contents
C-c (	RefTeX inserts label
C-c )	RefTeX references label
C-c [	RefTeX inserts citation (from BibTeX)
C-c b	Launch `ivy-bibtex` (do not need to be in LaTeX mode)
C-c C-e C-a	Template for new article
C-c C-e C-t	Template for technical reports
C-c C-e C-b	Template for books
C-j	Moves to the next BibTeX field
C-c C-c	Checks and cleans entry

ESS

Key name	Operation
M-x r	Launch R
C-c r	Launch R dired

Interactive buffer

Key name	Operation
C-c C-r	Move cursor to previous command (only for commands typed in the interactive buffer)
C-c C-o	Delete everything from last command to current prompt

Script

Key name	Operation
C-=	Insert <-, %>%, -> (cycle)
C-M-\	Indent region (using formatR)
C-return	Evaluate line or region (in R code)
C-return	Add a fenced R code block (in RMarkdown file)
C-S-return	Add inline R code (in RMarkdown file)
C-c C-x	Evaluate chunk

Special: Ask for password in R and hide it while typing:

cat("Password: "); pwd <- readLines(file("stdin"), 1)

SQL

Key name	Operation
C-return	Send paragraph or region if active

Screen

screen key bindings collide with Emacs own key bindings in the Shell. To prevent this, every screen key needs to be prefixed by C-l. For instance, to detach a screen session (normally C-a C-d), use C-l C-a C-l C-d.

screen operations:

• List existing sessions:

  screen -ls
      

• Open a session (note that sessions must be open in a regular terminal first to prevent printing issues in Emacs):

  screen -S <session_name>
      

• Detach a session:

  screen -d <number/name>
      

  or interactively in the session: C-a C-d

• Attach a session:

  screen -r <number/name>
      

  If need be, detach the session at the same time:

  screen -d -r <number/name>
      

  If really necessary:

  screen -D -RR <number/name>
      

  (“Attach here and now. Whatever that means, just do it.”)

• Kill a session

  screen -X -S <number/name> quit
      

  or interactively in the session: C-a :quit

Function keys (F1–F12)

Use position registers (a sort of bookmark) with F1—F4: C-F1 to C-F4 to save a register, F1 to F4 to jump to a saved register:

Key name	Operation
F1–F4	Jump to registers
C-F1–C-F4	Save registers
C-S-F1	Show/hide menu
C-S-F3	Bookmark a file (works on directories and remote files too!)
C-S-F4	List bookmarks

Key name	Operation
F5	NeoTree in left-side panel
C-F5	TOC in right-side panel (Markdown files)
F6	Dired in current directory
C-F6	Activate write mode in Dired (C-c C-c to save and exit)
F7	Run rmarkdown::render on current RMarkdown file
C-F7	Run bookdown::render_book on index.Rmd file
S-C-F7	Run knitr::pandoc (with custom options) on .md file
F8	Magit
C-F8	shell-xterm (Shell with clearing capabilities)
Key name	Operation
F9	Highlight region (like a marker)
C-F9	Move to the next highlighted text
C-S-F9	Un-highlight everything
F10	Toggle line wrapping
C-F10	Toggle current line highlight mode
C-S-F10	Toggle column highlight mode
F11	Multiple cursors in all lines
C-F11	Smart multiple cursors
C-S-F11	Multiple cursors: next like selected
C-S-<left click>	Multiple cursors on mouse click
C-'	In multiple cursor mode, narrow to lines with cursors
F12 / <middle click>	Flyspell correction suggestions
C-F12	Toggle Flyspell
C-S-F12	Change Ispell dictionary

Misc

Key name	Operation
M-x lunar-phases	Display moon phases.
M-x zone	Screen saver. Sort of…
C-S Esc	Redact the buffer

Screenshots (outdated)

A good demonstration could not be complete without screenshots, so here is Emacs in action:

• Emacs on the init.org config file, in Org mode, with Neotree in the left window, and Magit in the right window with its main commands at the bottom.

  

• Emacs opened with a RMarkdown file (.Rmd), including YAML headers and R code chunks, with the help page of a function in the right window together with the R buffer at the bottom.