Merge branch 'master' into master

1 files changed, 320 insertions, 0 deletions

diff --git a/emacs.html.markdown b/emacs.html.markdown
new file mode 100644
index 00000000..ff4d3c03
--- /dev/null
+++ b/emacs.html.markdown
@@ -0,0 +1,320 @@
+---
+category: tool
+tool: emacs
+filename: emacs.txt
+contributors:
+    - ["Joseph Riad", "https://github.com/Joseph-Riad"]
+---
+
+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)