diff options
Diffstat (limited to 'emacs.html.markdown')
| -rw-r--r-- | emacs.html.markdown | 321 |
1 files changed, 321 insertions, 0 deletions
diff --git a/emacs.html.markdown b/emacs.html.markdown new file mode 100644 index 00000000..e690f7af --- /dev/null +++ b/emacs.html.markdown @@ -0,0 +1,321 @@ +--- +category: tool +tool: emacs +filename: emacs.txt +contributors: + - ["Joseph Riad", "https://github.com/Joseph-Riad"] +lang: en-en +--- + +Emacs started its life as ["the extensible, customizable display +editor"](https://www.gnu.org/software/emacs/emacs-paper.html) and grew +over the years into a full-blown ecosystem. Many tasks, usually +relegated to a diverse set of tools can be accomplished from within +Emacs in a consistent, familiar interface. Examples include directory +management, viewing PDF documents, editing files over SSH, managing git +repos,… (the list is quite long). In short, Emacs is yours to make of it +what you will: the spectrum of users varies from those who use it to +edit text files to extreme purists who use it to virtually replace their +operating system. + +Emacs is extensible via a specialized dialect of Lisp known as Emacs +Lisp (Elisp) which has a lot of macros geared towards editing text and +managing text buffers. Any key (combination) you use in Emacs is bound +to an Emacs Lisp function and may be remapped to any other function, +including ones you write +yourself. + +# Key Notation + +``` text +The Emacs manual and the community in general uses a convention to refer to different key combinations used within Emacs. Specifically, Emacs has the notion of a "modifier key" that is pressed along with another key to modify its action. + +An example of this notation is "C-c". In this key combination "C" is the modifier and stands for the "Ctrl" key and "c" is the key whose action is being modified (the literal character "c"). + +The modifier shorthand: +"C-" --> The "CTRL" key +"M-" --> The "Meta" key (usually, the "Alt" key) +"s-" --> The "Super" key (the "Cmd" key on Macs and the "Windows" key on PCs) + +There are other, less commonly used modifiers that I will not get into here. + +The key combination "C-x C-s" means you press "Ctrl+x" followed by "Ctrl+s" + +In addition to the above modifiers, the special keys "Esc", "Return (Enter)" and "Shift" are denoted by "ESC", "RET" and "S", respectively. +``` + +# Basic Emacs Concepts + +Here, I discuss some basic Emacs concepts and terminology that may be +confusing to newcomers (especially to people used to Vim terminology) + + - A bunch of text that Emacs is editing is known as a **buffer** + - A buffer does not necessarily correspond to an actual file on disk. + It may be just a bunch of text in memory. + - When a buffer corresponds to a file on disk, we say that the buffer + is **visiting** that file. + - Emacs typically has many buffers open at once. + - The display of Emacs may be split into different **windows** (not to + be confused with your operating system's windows: the operating + system window for Emacs can have multiple Emacs windows inside it). + - An operating system window for Emacs is called an Emacs **frame**. + Thus, when the Emacs manual talks about opening a new frame, this + essentially means opening a new OS *window* containing an(other) + instance of Emacs. + - The concepts conventionally known as cutting and pasting are + referred to as **killing** and **yanking**, respectively in Emacs + parlance. + - The current position of the cursor is called the **point** in Emacs. + Technically, **point** is defined as the position right before the + character where the cursor currently is. + - Finally, each buffer may have several **modes** associated with it: + a **major mode** and possibly several **minor modes**. + - The **major mode** defines the main behavior of Emacs in the + currently selected buffer. This can be roughly thought of as the + file type. For example, if you're editing a Python file, the major + mode is (by default) `python-mode` which causes Emacs to highlight + Python syntax and automatically indent and outdent your code blocks + as syntactically required by your Python code. + - **Minor modes** define subtle changes in behavior and several minor + modes may be active at once in the same buffer. An example minor + mode is `flyspell-mode` which automatically highlights spelling + errors in your +buffer. + +# Navigation Basics + +``` text +The GUI version of Emacs can be navigated with the mouse like you would expect from a conventional GUI text editor. + +The aim here is to focus on navigation solely using the keyboard as this enhances productivity immensely. + + +* Line movement + +C-n --> Next line +C-p --> Previous line + +* Character movement + +C-f --> Go forward one character +C-b --> Go backward one character + +* Word movement + +M-f --> Go forward one word +M-b --> Go backward one word + +* Sentence movement + +M-a --> Move to the beginning of the sentence +M-e --> Move to the end of the sentence + +* Beginning and end of line + +C-a --> Move to the beginning of the line +C-e --> Move to the end of the line + +* Beginning and end of buffer + +M-< ("Meta+Shift+,") --> Go to the beginning of the buffer +M-> ("Meta+Shift+.") --> Go to the end of the buffer + +* Screen movement + +C-v --> Scroll down by one screen-full (the last two lines of the previous screen are kept as overlap for a smoother transition) +M-v --> Scroll up by one screen-full (same as above but with the first two lines) + +* Centering the screen + +C-l --> Move current line to the screen's center + +The above key combination actually cycles through different states depending on how many times it's been pressed. + +C-l --> Move current line to the screen's center +C-l C-l --> Move current line to the top of the screen +C-l C-l C-l --> Restore the position of the current line to where it was before the first C-l was pressed + +If you press "C-l" a 4th time, it cycles back to centering the current line. + +* Repeating movement commands + +Most movement commands take a numerical prefix argument that says "repeat the following command that many times". + +Example: + +C-u 3 C-p --> Go up 3 lines +C-u 5 C-f --> Go forward 5 characters + +One notable exception are the screen scrolling commands: + +C-u 3 C-v --> Scroll downward 3 lines (maintaining the position of the cursor) +``` + +Bonus: many of the above navigation commands are the default navigation +commands in Bash (e.g. pressing "C-b" while entering a Bash command +takes you back one +character). + +# File editing basics + +``` text +* Quitting Emacs [ Now you can't say you don't know how to quit Emacs :-) ] + +C-x C-c --> Quit Emacs and get prompted to save any unsaved files (buffers not visiting a file will simply be discarded unless you're running in client-server mode) + +* Saving a buffer + +C-x C-s --> Save the current buffer. If not visiting a file, it will prompt you for a file name to use to save the buffer. + +* Searching within a buffer + +C-s --> Search forwards within the buffer. Search is incremental and case-insensitive by default. + Press C-s to move to the next match. + If you press "RET", point is moved to the currently highlighted word and the search ends. +C-r --> Same as C-s except it searches backward + +C-_ or C-/ --> Undo the last action. Keep pressing it to move up the undo tree. +C-? or M-_ --> Redo the previous change + +The "undo" and "redo" commands can take prefix numerical arguments to undo or redo that many actions: + +C-u 3 C-_ --> Undo the last 3 changes. +``` + +# Executing Elisp Functions + +``` text +You can execute any currently loaded Elisp functions (including ones you have written yourself) via "M-x" + +M-x RET --> Prompts you for name of function to execute (Tab completion is available). + +Example: + +M-x RET search-forward-regexp RET --> Prompts you for a regular expression and searches forward in the buffer for it +``` + +# Emacs Configuration + +Emacs is configured using Elisp. On startup, it looks for a +configuration file either in `~/.emacs` or `~/.emacs.d/init.el` where +`~` refers to your home directory. If you're on Windows, consult [this +article](https://www.gnu.org/software/emacs/manual/html_node/efaq-w32/Location-of-init-file.html) +for the appropriate location of your configuration file. + +# Vim inside Emacs + +If you are considering the transition from Vim to Emacs and you're put +off by the non-modal nature of Emacs editing, there is an Emacs +extension known as `evil-mode` which lets you have many Vim concepts +inside Emacs. Here are some things added to Emacs by `evil-mode`: + + - Modal editing: you get normal, insert, visual and block visual modes + like Vim. In addition, you get an "Emacs" mode where movement and + navigation follow the Emacs bindings. + - Same movement keys as Vim in normal mode + - Leader key combinations + - Pressing ":" in normal mode allows you to execute commands + (including system commands) + +In my own experience, `evil-mode` helps make the transition seamless and +allows you to blend the arguably more intuitive and ergonomic +keybindings of Vim with the unbridled power of Emacs for a truly +superior editing experience. + +# Discoverable Help + +Emacs features a pretty powerful help system that allows you to discover +new functionality all the +time. + +``` text +Obtaining help on specific topics. Tab completion is available for function and variable names. + +C-h f RET --> Prompts you for the name of an elisp function and + displays help text on it along with a clickable link + to its source code. +C-h v RET --> Same as above with variables + +C-h k RET --> Allows you to enter a key combination and displays the + name of the elisp function bound to it. + +Searching for help: + +C-h a --> Prompts you for a string to search for a command in the + help system. Similar to the 'apropos' or 'man -k' + commands in Unix systems. + +Starting a tutorial: + +C-h C-t --> Starts a tutorial designed to familiarize you with + basic Emacs functionality. +``` + +# Emacs "Killer Apps" + +As I hinted above, Emacs functionality goes way beyond being a mere text +editor. I will list here a couple of Emacs "apps" that are fairly +powerful and popular and may interest you in and of themselves. + +## Org + +Technnically, `org-mode`, a major mode for buffer editing that provides +organizational tools. It is very difficult to succinctly describe what +Org can do because it's a behemoth of a tool that has many diverse uses +to different people. I will attempt to describe the main features I use +briefly. + + - Divide your file into sections and sub-sections for easy outlining + and organizing of concepts. + - Different headings in the outline are foldable/expandable so that + you can focus on what you need to focus on and eliminate + distractions. + - You can maintain a TODO list within Org + - You can compile TODO lists from many files into an agenda + - Track the time you spend on each TODO task + - Manage tables in plain text (including spreadsheet-like + capabilities) + - Using the extension `org-babel`, write and execute code blocks in + your file. The results are captured and are re-usable within the + file itself. Think Jupyter notebook for any language. + - Display inline images and LaTeX formulas as images within your file + (makes for a great note-taking system and/or personal wiki) + - Export your file into many different formats (LaTeX, PDF, html,…) + +Org mode is a very powerful tool to add to your productivity arsenal +and, on a personal note, was the reason that caused me to start using +Emacs after years of using Vim. + +## Magit + +This is a frontend to `git` from within Emacs. It features a very +intuitive and discoverable interface, yet exposes very powerful +functionality that allows you to manage commits at the chunk level, +inspect diffs, rebase, cherry-pick, … all from within the comfort of +your own editor. + +# A Word of Advice + +If you are considering using Emacs, a common trap that beginning users +fall into is to copy someone else's configuration file and use it as is. +I highly recommend against doing this for several reasons: + + - It will discourage you from learning and finding things out for + yourself + - Someone else's configuration will probably contain many things + relevant to them that you won't need or ever use. + - It defeats the purpose of having a customizable text editor that can + fit your own needs. + +What I encourage you to do is to look at other people's configurations +and seek to understand them and adapt only what makes sense to you. You +can find out about new features of Emacs through many YouTube videos, +screencasts or blog posts and then learn for yourself how to add them to +your configuration and workflow. This way, you grow your configuration +incrementally while increasing your knowledge of Emacs along the way. + +# Additional Resources + + - [The GNU Emacs Manual](https://www.gnu.org/software/emacs/manual/emacs.html) + - [Emacs Stack Exchange](https://emacs.stackexchange.com/) + - [Emacs Wiki](https://www.emacswiki.org/emacs/EmacsWiki) |