Skip to content

basille/.emacs.d

Repository files navigation

Emacs literate configuration

Table of Contents

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 nameOperation
M-<arrows>Move between windows
M-x <arrows>Swap buffer between windows
C-~Next window (key above TAB)
C-TABCycle through buffers with IVY
C-x kKill THIS buffer
C-x +Balance the sizes of windows
C-x CCenter the text horizontally

Search and replace

Key nameOperation
C-sSearch using Swiper
C-S-sivy-resume: go back to state of last search
C-S-yYank from history
C-rReplace
C-M-rReplace using a RegExp
C-+Count words in region
C-=Expand region (more: =; less: -)

Regular Expressions

Key nameOperation
. (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
\cQuote characters otherwise having a special meaning in regular expressions
\wMatches word-syntax character
\WMatches non-word-syntax character
\<Matches at word beginning
\>Matches at word end
\bMatches at word break
\BMatches at non-word break
\(…\)Groups a series of pattern elements to a single element
…\|…\|…Matches one of the alternatives (“or”)
\NSame text as n-th group

Edit

C-zUndo
M-yList kill ring (counsel-yank-pop)
C-c C-uCycle between snake_case, lowerCamelCase and kebab-case
M-qFill paragraph (indentation and lines)
C-u M-qJustifies text (fixed width)
M-$Check spelling of word at the cursor

Operations

Key nameOperation
C-.Imenu (main sections/headers)
M-xSMEX
M-!Shell-command in the minibuffer
C-h mCheck modes in a buffer
C-x C-eEvaluate lisp expression
C-x C-yEvaluate lisp expression and replace with result
M-g M-gGo to a given line number

Keyboard macros

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

Bookmarks

Key nameOperation
C-x r mBookmark a file (works on directories and remote files too!)
C-x r bJump to a bookmark
C-x r lList bookmarks

Completion and Ivy

Key nameOperation
C-sSearch using Swiper
C-S-sivy-resume: go back to state of last search
M-rIn Ivy mode, toggle regexp mode
M-oIn 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-oivy-occur: save current search into a new buffer (then C-d to delete lines)
TABComplete anything
orFold/unfold functions/regions (if code indented)

Flycheck

Key nameOperation
C-c ! vVerify Flycheck setup for current buffer
C-c ! n / C-c ! pNext and previous error
C-c ! lList 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 nameOperation
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 nameOperation
//Go to the root directory
~Go to the home directory
ENTEREnter Dired in this directory

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

Key nameOperation
$Go to a bookmark
(Hide/show details
sSort by date or filename
SInteractively sort (by filename, date, reverse, etc.)
iInclude subdirectory
oOpen in other window
mMark a file/folder
* /Mark all folders
* sMark all files and folders
dMark for deletion
xExecute deletion of marked files
uUnmark a file/folder
UUnmark all
tToggle mark
/Dynamically filter files/folders (dired-narrow)
CCopy (marked) file(s)
DDelete (marked) file(s)
RRename (marked) file(s)
ASearch with regexp content of (marked) file(s)
QSearch and replace with regexp content of (marked) file(s)
eediff two marked files
=Launch ediff file at point, requesting for file to compare
wCopy file name in the kill ring
M-0 wCopy absolute path to the file

Magit

Key nameOperation
yShow information on branches and commits
C-fGitFlow from within Magit
Kgit ls-files from within Magit
eIn case of conflicts, open Ediff on file
kIn case of conclicts, ask to delete our/their file

Web browser

Key nameOperation
<backspace>Go to previous page
fOpen page with external browser

Polymode

Key nameOperation
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 nameOperation
C-c C-qAdd a Tag in Org mode
(use :TOC: for an automatic table of contents)
<s TABAdd a source code block

PDF tools

Key nameOperation
PFit to the page
HFit to the height
WFit to the width
grefreshes the PDF
hopens the help of PDF tools
C-c C-a hHighlight text and annotate (C-c C-c to commit)
C-c C-a tAnnotate anywhere (C-c C-c to commit)
C-c C-a oStrike through text
C-c C-a DDelete annotation
C-c C-a lList annotations

LaTeX

Key nameOperation
C-c C-lShows compilation logs in LaTeX
C-c C-vCalls 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 bLaunch `ivy-bibtex` (do not need to be in LaTeX mode)
C-c C-e C-aTemplate for new article
C-c C-e C-tTemplate for technical reports
C-c C-e C-bTemplate for books
C-jMoves to the next BibTeX field
C-c C-cChecks and cleans entry

ESS

Key nameOperation
M-x rLaunch R
C-c rLaunch R dired

Interactive buffer

Key nameOperation
C-c C-rMove cursor to previous command (only for commands typed in the interactive buffer)
C-c C-oDelete everything from last command to current prompt

Script

Key nameOperation
C-=Insert <-, %>%, -> (cycle)
C-M-\Indent region (using formatR)
C-returnEvaluate line or region (in R code)
C-returnAdd a fenced R code block (in RMarkdown file)
C-S-returnAdd inline R code (in RMarkdown file)
C-c C-xEvaluate chunk

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

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

SQL

Key nameOperation
C-returnSend 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 nameOperation
F1–F4Jump to registers
C-F1–C-F4Save registers
C-S-F1Show/hide menu
C-S-F3Bookmark a file (works on directories and remote files too!)
C-S-F4List bookmarks
Key nameOperation
F5NeoTree in left-side panel
C-F5TOC in right-side panel (Markdown files)
F6Dired in current directory
C-F6Activate write mode in Dired (C-c C-c to save and exit)
F7Run rmarkdown::render on current RMarkdown file
C-F7Run bookdown::render_book on index.Rmd file
S-C-F7Run knitr::pandoc (with custom options) on .md file
F8Magit
C-F8shell-xterm (Shell with clearing capabilities)
Key nameOperation
F9Highlight region (like a marker)
C-F9Move to the next highlighted text
C-S-F9Un-highlight everything
F10Toggle line wrapping
C-F10Toggle current line highlight mode
C-S-F10Toggle column highlight mode
F11Multiple cursors in all lines
C-F11Smart multiple cursors
C-S-F11Multiple 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-F12Toggle Flyspell
C-S-F12Change Ispell dictionary

Misc

Key nameOperation
M-x lunar-phasesDisplay moon phases.
M-x zoneScreen saver. Sort of…
C-S EscRedact 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-neotree-org-magit.png

  • 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.

    emacs-markdown-yaml-ess.png

About

Custom config for Emacs

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published