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
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)
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)
.
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 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 |
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: - ) |
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 |
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 |
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 |
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 ) |
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 |
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) |
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 |
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 |
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 |
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 |
Key name | Operation |
---|---|
<backspace> | Go to previous page |
f | Open page with external browser |
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 |
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 |
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 |
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 |
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)
Key name | Operation |
---|---|
C-return | Send paragraph or region if active |
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
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 |
Key name | Operation |
---|---|
M-x lunar-phases | Display moon phases. |
M-x zone | Screen saver. Sort of… |
C-S Esc | Redact the buffer |
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.