summaryrefslogtreecommitdiffhomepage
path: root/emacs.html.markdown
diff options
context:
space:
mode:
authorJoseph-Riad <joseph.samy.albert@gmail.com>2019-08-03 03:54:47 -0500
committerDivay Prakash <divayprakash@users.noreply.github.com>2019-08-03 14:24:46 +0530
commita9c3d41253d0157b6a7076accc3526175eaa822f (patch)
treef4364aec01c2470ea42bda386310a370f4636b29 /emacs.html.markdown
parent1391c0194a12e82d59a68458202d8859c23c6fca (diff)
[emacs/en] Basic Emacs tutorial (#3562)
* Basic Emacs tutorial * Added a "category" line to the metadata * Fixed a mistake
Diffstat (limited to 'emacs.html.markdown')
-rw-r--r--emacs.html.markdown321
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)