cheatsheets/emacs-ez.tex

% Created 2018-04-09 Mon 10:25
% Intended LaTeX compiler: pdflatex
\documentclass[11pt]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{graphicx}
\usepackage{grffile}
\usepackage{longtable}
\usepackage{wrapfig}
\usepackage{rotating}
\usepackage[normalem]{ulem}
\usepackage{amsmath}
\usepackage{textcomp}
\usepackage{amssymb}
\usepackage{capt-of}
\usepackage{hyperref}
\usepackage{lmodern}
\usepackage[QX]{fontenc}
\author{Joshua Branson}
\date{\today}
\title{Emacs Cheatsheat}
\hypersetup{
 pdfauthor={Joshua Branson},
 pdftitle={Emacs Cheatsheat},
 pdfkeywords={},
 pdfsubject={},
 pdfcreator={Emacs 25.3.1 (Org mode 9.1.9)},
 pdflang={English}}
\begin{document}

\maketitle

\section{Why use Emacs?}
\label{sec:orgd8d41e3}

For starters, Emacs is freedom respecting software.  This is often shortened to "free software", or "libre software".  This means that one has the right to:
\begin{itemize}
\item 0 run the program for any reason.
\item 1 the right to help yourself.
This is the right to study the source code and change it.
\item 2 The right to help your neighbor.
This is the right to distribute unmodified copies of Emacs to your neighbor.  You could also even sell this program to your neighbor!
\item 3 The right to help your community.
This is the right to distribute your modified version of Emacs.  You could also sell your modified version!

So Emacs grants you, the user, many freedoms that other programs lack.  Please notice that this is computing freedom.  Free software is liberty software, not necessarily gratis software.  However,  Emacs is Free software, and it can usually be obtained as gratis software.
\end{itemize}

There are also some practical reasons to use Emacs. Plenty of programmers these days use drastically simple programming editors like notepad, notepad++, nano.  These editors are "What you see is what you get" type editors, and they are frustratingly lacking in good features, and one cannot easily configure these editors.  Emacs gives you the ability to install hundreds, if not thousands of add-ons, and configure \textbf{everything} that your text editor does.

So what can Emacs do?  You can use emacs to use commands to manipulate and transpose regions of text, write in nearly every programming language imaginable, read your email, browse the internet, play games, browse local files, look at a photo gallery, stream internet music, watch online movies (coming soon), create text expandable abbreviations, clock your working hours, invoice clients, schedule your weekly agenda, syntax checking, browse documentation, commit your development changes to version control, emulate vim, all of which can be configured and tweaked emacs in numerous ways.  If that doesn't satisfy you, then you can programmatically change emacs' behavior to better suit your development workflow.

\section{Emacs Introduction}
\label{sec:org9a8e7e3}
Emacs is a incredibly old software.  It's been around since the late 80s and early 90s, and its amazing flexibility is probably what has kept it alive this long.  Learning Emacs can be a huge challenge of its own, but if you take the time to learn Emacs, the rewards are astonishing.




\begin{center}
\includegraphics[width=.9\linewidth]{/home/joshua/pictures/emacs_learning_curves.png}
\end{center}

(Original source appears to be Steve Rowe's blog. “A friend of mine put this together” \href{https://blogs.msdn.microsoft.com/steverowe/2004/11/17/code-editor-learning-curves/}{Source}).


Since Emacs is so old, it created some terminology that modern text editors do not use.  For example Emacs has "Frames" and "Windows", "yanking" and "killing" and no other text editor uses those terms, but the best way to learn Emacs, is to dive into the terminology.  So put on your big programming pants, and follow me down the Emacs golden brick road of confusion!

So go ahead and launch Emacs. When you do, you should see a blinking rectangle.  When you start to type this rectangle moves and letters appear.  That blinking rectangle is called \emph{point}.  When \emph{point} moves around the text, we say that point moves in the \emph{buffer}.  The \emph{buffer} then is a region in Emacs that contains text.  Since you've just started Emacs, the whole Emacs graphical display is one \emph{frame}.  You can also launch Emacs from the terminal and that is still just one frame of Emacs.  If you open a second instance of Emacs, you now have two frames.  Emacs also has windows.  An Emacs \emph{window} is the portion of Emacs that contains the buffer, or the text.  It's also possible to for a frame to have multiple windows.  You can read more about creating and deleting windows and frames in \hyperref[sec:orgcd0af05]{Frame and Window Commands}.

\section{Built in Emacs Features}
\label{sec:org0ecb61a}
\subsection{Movement}
\label{sec:orgc25e6fb}
One can always use the arrow keys to move point, but Emacs provides some nifty ways of moving point as well.  Pressing and holding the control key whilst hitting "f" will move point forward one character.  In Emacs lingo we call that a keychord, and it is denoted like this "C-f".  Similarly, holding and pressing the control key, then hitting "b" will move point backward one character.  That keychord is denoted as "C-b".  "C-p" will move point back to the up previous line, and "C-n" will move point down to the next line.  So the basic movement keys look like this:

\begin{verbatim}
                  "C-p"
                    /\
                    ||
                    ||
                    ||
                    ||
"C-b" <-------------||--------------> "C-f"
                    ||
                    ||
                    ||
                    ||
                    ||
                    ||
                    \/
                  "C-n"

\end{verbatim}

\subsection{Yanking and Killing}
\label{sec:orge6ac8d8}
Most text editors use the words "cutting", "pasting", and "coping" for the commands \texttt{C-x}, \texttt{C-v}, and \texttt{C-c}.  Emacs used different words and different commands.  What is normally called cutting is \emph{killing} in Emacs.  In this way, one kills to the kill region, a section where Emacs stores killed text.  Pasting is called \emph{yanking}.  One yanks from the kill region to past into the buffer.  Copying in Emacs is also called copying.

To kill or copy a region of text, you must first \emph{mark} that region or highlight it.  To begin marking a region of text one presses \texttt{C-<space>} or \texttt{C-SPC}.  \texttt{<space>} and \texttt{SPC} means hitting the spacebar key.    Then you can move around point until you have marked the entire region.  To kill the region type \texttt{C-w}.  To copy the region type \texttt{M-w}.  M stands for the meta key, which on today's keyboard usually means the alt key.  So \texttt{M-w} means to press and hold the alt key, then hit the w key.  Alternatively hitting the ESC key is the same as pressing and holding the alt key.  So \texttt{M-w} is the same thing as \texttt{ESC-w}.

To yank the killed or copied text back into the buffer press the \texttt{C-y} keychord.

\subsection{Opening, Closing, and Saving Files}
\label{sec:orga52ca85}
When one opens and edits a file in Emacs, Emacs opens the file and puts the contents in an editable buffer.  As you edit the buffer, you only change the a region in memory.  When you type \texttt{C-x s} to save the current buffer, the buffer's content are saved in the file.

Since I am constantly changing multiple files, I've modified my save function to save every open file.  If you would like to do the same, you can put the following in your init file:

\begin{verbatim}
(add-hook 'after-save-hook #'(lambda ()
                               (interactive)
                               (save-some-buffers 1)))
\end{verbatim}

Emacs' default method of opening a files is ido mode, which is pronounced like "I do mode".  \texttt{C-x C-f} or (find-file) opens a file in Emacs.  One can press the tab key to complete a partially completed file name.  Typing "\textasciitilde{}/" means to make ido search in the user's home directory.  I personally do not enjoy using ido-mode. Instead I prefer \hyperref[sec:org2d2c82c]{helm-mode}.
\subsection{Frame and Window Commands}
\label{sec:orgcd0af05}
Emacs has windows and frames, and they are probably not what you think they are.  A Frame is probably what you would think a window is.  So when you follow a link in your browser in a new window, that is a window in browser terminology.  In Emacs you can do the same thing, but it is called opening a new frame.  Go ahead and open a new frame now by typing \texttt{C-x 5 2}.  To get back to one Emacs frame, you can either close the additional frame normally, or you can press \texttt{C-x 5 0}.

An Emacs window then is the buffer portion of the frame that displays text.  One frame can have multiple windows.  If you type \texttt{C-x 1}, then Emacs is only displaying one window.  Then, if you type \texttt{C-x 2} or \texttt{C-x 3}, then Emacs is displaying 2 windows.  So a window then is a section of the Emacs Frame that contains text from a buffer.  To make the current frame only display one buffer, you can press \texttt{C-x 1}.

In emacs the entire emacs program takes up a \textbf{frame}.  But emacs allows you to view two different files in the same frame, by splitting the frame in half, or in two \textbf{windows}.
\begin{itemize}
\item \texttt{C-x o} Delete the selected window
\item \texttt{C-x 1} Delete all the windows except the one that currently has point
\item \texttt{C-x \textasciicircum{}} make the selected window taller
\item \texttt{C-x \{} make the selected window narrower
\item \texttt{C-x \}} make the selected window wider
\end{itemize}
\subsection{Bookmarks}
\label{sec:org43ddfcc}
Emacs bookmarks are nifty ways of saving your place in a file.  If you wish to return to some obscure local or remote file, you can easily save point's current position, and return to it later.

\begin{itemize}
\item \texttt{C-x r m}  sets a bookmark for you at point and it prompts you to name it
\item \texttt{C-x r b}  jumps you to a bookmark
\end{itemize}
\subsection{Learning About Emacs}
\label{sec:org4c3ad76}
Emacs comes with some amazing documentation.  \texttt{M-x info} will show you a list of the available documentation that comes with Emacs.  This documentation is contained in info files, which can be easily navigated via Emacs.

Emacs also has a pretty powerful help command:  \texttt{C-h}.  \texttt{C-h v} will let you learn some documentation about a particular Emacs variable, while \texttt{C-h f} will show you documentation for an Emacs elisp function.  Every time that you hit a keychord, an equivalent Emacs function is called.  In fact \texttt{C-h k KEYCHORD}, will tell you the documentation for the a function based on its keychord.  For example, \texttt{C-h k C-n} will display documentation for the function "next-line".

\subsection{Configuring Emacs with Lisp}
\label{sec:orga27941d}
Emacs' flexibility stems from the ability to program-matically change it via Emacs lisp.  If you dislike a particular aspect of Emacs, then you can easily change it by putting in some Emacs lisp code into your init file.  This is the file that Emacs loads every time on startup.  Any Emacs lisp functionality that you code in your init file, will be available every time you start emacs. You can find your init file by checking out the variable \texttt{user-init-file}.  To do this press the keychord \texttt{C-h v RET user-init-file RET}.
\subsection{Dired}
\label{sec:org25797aa}
Dired is the emacs file manager.  It opens a buffer displaying all your files in the specified directory.  With it you can perform numerous commands on marked files, like deleting, copying, moving, or even creating your own command.
\subsubsection{Commands}
\label{sec:org4fee3b2}
\begin{itemize}
\item \texttt{n} next line
\item \texttt{p} previous line
\item \texttt{m} mark the current file under point
\item \texttt{\% m REGEXP <RET>}  mark files based on a regular expression
\end{itemize}
\subsubsection{Image Dired}
\label{sec:org8ebe122}
You can also view images inside dired!  Mark the images you wish to view, then press C-t d (image-dired-display-thumbs). Alternatively, you could also just run the command M-x image-dired.
\subsection{Macros}
\label{sec:orgbcfe604}
A Macro is a remembered sequence of Emacs keychords that can be repeated.  This is useful to easily repeat complicated commands.  For example, I can write out the numbers 1 through a 1000 by typing a few keys.

\begin{itemize}
\item \texttt{C-x (} begin recording a keyboard macro
\item \texttt{C-x )} end recording a keyboard macro
\item \texttt{C-x e}  performs the last created keyboard macro
\end{itemize}
\subsection{Narrowing}
\label{sec:org7ce16de}
Narrowing commands make Emacs only display portions of the buffer, whilst hidding all other regions.  While Emacs is narrowed, all entered commands only affected the displayed regions.  This means any hidden area cannot be modified while Emacs is narrowed.  This is useful if you only want a macro to execute within a specific function.  Here are the relevant narrowing commands:

\texttt{C-x n <letter>}
\begin{itemize}
\item \texttt{d} narrow to defun
\item \texttt{r} widen to region
\item \texttt{s} narrow to a org subtree
\item \texttt{w} widden to the whole buffer
\end{itemize}

A much better way to use the narrowing commands is just to make emacs guess what you want whenever you press "C-x n", and that's what the following snippet does.   I recommend that you put it in your .emacs file.  The code works by figuring out which narrowing command you want to use.  If point is currently in a definition, then the buffer will be narrowed to that definition.  If point is in an org-subtree, then the buffer will be narrowed to that subtree.

You can see the blog post where I found this code snippet \href{http://endlessparentheses.com/emacs-narrow-or-widen-dwim.html}{here.}

\begin{verbatim}
;; Also set up narrow dwin
(defun narrow-or-widen-dwim (p)
  "Widen if buffer is narrowed, narrow-dwim otherwise.
Dwim means: region, org-src-block, org-subtree, or defun,
whichever applies first. Narrowing to org-src-block actually
calls `org-edit-src-code'.

With prefix P, don't widen, just narrow even if buffer is
already narrowed."
  (interactive "P")
  (declare (interactive-only))
  (cond ((and (buffer-narrowed-p) (not p)) (widen))
        ((region-active-p)
         (narrow-to-region (region-beginning) (region-end)))
        ((derived-mode-p 'org-mode)
         ;; `org-edit-src-code' is not a real narrowing
         ;; command. Remove this first conditional if you
         ;; don't want it.
         (cond ((ignore-errors (org-edit-src-code))
                (delete-other-windows))
               ((ignore-errors (org-narrow-to-block) t))
               (t (org-narrow-to-subtree))))
        ((derived-mode-p 'latex-mode)
         (LaTeX-narrow-to-environment))
        (t (narrow-to-defun))))

;; This line actually replaces Emacs' entire narrowing
;; keymap, that's how much I like this command. Only copy it
;; if that's what you want.
(define-key ctl-x-map "n" #'narrow-or-widen-dwim)
\end{verbatim}
\subsection{org-mode}
\label{sec:orgd079476}
Emacs org-mode really deserves its own cheatsheat, so I won't go into much detail here, but I'll start you off with the basics.  Org-mode is Emacs' organizational mode, and it's pure gold!  With Org-mode I organize my daily agenda, todo lists. Parts of my emacs init files are written in it.  I use it to keep track of my working hours, with which I then invoice clients.  I use its markup to write MIME emails.  I wrote all of my documentation in it, and I keep track of my finances with it!  It truly is a remarkable emacs mode!
\subsubsection{Org-mode's hierarchical structure}
\label{sec:org137506d}
Org-mode lets you easily insert headings and sub headings with "C-RET".  If you press it many times, you'll have something like this:

\begin{verbatim}
*
*
*
*
\end{verbatim}

A line with just one "\textbf{" is a top level heading.  If it has a two "*}" below it, then it now has a sub-heading.  Just like the following:
\begin{verbatim}
* I am a top level heading
** I am a sub-heading.
\end{verbatim}

You can use the tab key to show/hide any sub level headings.


Org-mode is also great for todo lists.  Hitting \texttt{C-c C-t} lets you mark an item as TODO or DONE.
\paragraph{Todo lists}
\label{sec:org1209f0c}
One can easily create simple todo lists with org-mode.  In any org file \texttt{C-RET} inserts a "*" into the buffer.  Pressing "C-c C-t" will add the words "TODO".  It'll look like:

\begin{verbatim}
* TODO
\end{verbatim}

Pressing \texttt{C-c C-t} again, will change the status to DONE.  You will end up with something looking like:

\begin{verbatim}
* DONE
\end{verbatim}

\subsubsection{org-babel}
\label{sec:org0265631}
Org babel is a the best approach towards literate programming ever attempted, and it works!  Almost all programming languages treat code as the first order citizen and hides comments behind a simple syntax.  I will eventually move org babel into its own cheatsheet, but I will describe the basics for you here.  For example here is some javascript:

\begin{verbatim}
console.log("hello world")
\end{verbatim}

Let's write a trivial js function the literate way

\begin{verbatim}
#+BEGIN_SRC js :exports code
  var i = 5;
  if (i < 6) {
    i++;
  }
  console.log (i);
#+END_SRC
\end{verbatim}

Literate programming might not be the best method of coding large projects, but it incredibly useful for writing your Emacs config files.  You can see an example of my org more custom-izations \href{https://github.com/jbranso/.emacs.d/blob/master/lisp/init-org.org}{here}.
\paragraph{Specific header arguments}
\label{sec:org631391f}

\url{http://orgmode.org/manual/Specific-header-arguments.html} \\
\href{org\#Specific\%20header\%20arguments}{info:org\#Specific header arguments} \\

\begin{itemize}
\item :results \\
syntax: \\
:results [raw | silent | value | output ] \\
value is function mode.  It means that org-mode will use the last executed command as the value of the output. ie:

\begin{verbatim}
import time
print("Hello, today's date is %s" % time.ctime())
print('Two plus two is')
return 2 + 2
\end{verbatim}

\begin{verbatim}
echo "hello world"
echo "big cat"
ls -lh | grep emacs.org
\end{verbatim}
\item :exports [code | results | node | both]
\item :dir
Specify a default directory that the code is to be run in
:dir dir

\begin{verbatim}
ls
\end{verbatim}
\end{itemize}

:dir can also specify remote directories to run code!
\begin{verbatim}
ls
\end{verbatim}

\section{Helpful Emacs modes}
\label{sec:org406102e}
\subsection{Bug Hunter}
\label{sec:org0ea84be}
If you fairly regularly change your init file, then you will at some point open your init file with a broken emacs.  Bug hunter helps you quickly narrow down the cause of the error.  You want to make sure that bug-hunter is loaded early in your init, but then anytime that you find another issue, just run.
  \texttt{M-x bug-hunter-init-file e RET}

\url{https://github.com/Malabarba/elisp-bug-hunter}
\subsection{Helm Mode}
\label{sec:org2d2c82c}
Helm mode is an interactive completetion framework that is much better than ido mode.
  C-c C-f helm-find-files

In this mode typing "\textasciitilde{}/ manage js\$"
will display a list of files in my home directory that contain the word "manage" and end with "js"

Typing C-l will display the files is the parent directory.

Typing C-z when point is on a directory, will show the files in that directory.

Helm has nth commands. Instead of typing tab to get to the action menu
just press C-e for the 2nd action
and C-j for the 3rd action.
You can also bind a key to an action menu
(define-key helm-map (kbd "<C-tab>") 'helm-select-4th-action)

\subsubsection{commands}
\label{sec:orga94123e}
You can learn how to write your own helm commands here: \href{http://wikemacs.org/wiki/How\_to\_write\_helm\_extensions}{write your own helm extentions}
  \texttt{C-c h m}  open helm-man-woman
  \texttt{C-c h h g} open helm info gnus
  \texttt{C-c h h r} open the helm-emacs-info
  \texttt{C-c h b} is helm-resume which opens up the last helm instance.
  \texttt{M-<space>} mark candidate
  \texttt{C-h m} inside a helm window will show you all of helm's keybindings
\subsection{El-doc}
\label{sec:org98d6ece}
El-doc shows you a function's documentation in the mini-bar as you write it.  By default it works for emacs lisp extremely well.  functions.  You can add this to your init file if you'd like to try it for emacs lisp.
\begin{verbatim}
(add-hook 'emacs-lisp-mode-hook 'eldoc-mode)
\end{verbatim}

\subsection{Yasnippet}
\label{sec:org8d0d875}
Yasnippet is Emacs non-official but pretty much most commonly used snippet system.  You can define an abbreviation, then when expanded does what the snippet file says to do.
\url{http://ergoemacs.org/emacs/yasnippet\_templates\_howto.html}

\subsubsection{Important Characters}
\label{sec:org7fe9ab0}
\begin{itemize}
\item \texttt{\$\&} indents the line according to the major mode
\item \texttt{`(some-lisp-code)`} embods lisp code
\item \texttt{\$0} where point will be when the snippet ends
\item \texttt{\$n} where n is a number ie: \texttt{\$1}, \texttt{\$2}, etc.  If you have multiple \$3, then typing some text in one \$3 will also be put in
the other \$3.
\item =\$\{n:<placeholder text>\}
\end{itemize}
\subsection{Undo Tree}
\label{sec:org74fa4be}
Undo tree is a mode that lets you visually step through the changes that you have done to the buffer.  You can step backwards and forwards through time.  In normal creation of a documentent, a user typically creates several changes that the emacs undo command is not sufficient to solve.  A document's historical content is not always linear.  Instead, during normal editing, a user can write content that the normal emacs undo command forgets about.  This is where undo tree is helpful.  Invoking \texttt{M-x undo-tree} shows the user a visual representation of the buffer in time.  Using the arrow keys (or conventional emacs replacements), one can step through a documentent's progression.
\subsection{Ediff}
\label{sec:org053654a}
Ediff is emacs's cool way of comparing two files and merging them into one.  \texttt{M-x ediff} starts the process.  Emacs will prompt you to ediff two files, and then you can begin merging the files together.
\subsubsection{Commands}
\label{sec:orgd027687}
\begin{itemize}
\item \texttt{a} copies buffer a diff to buffer b
\item \texttt{b} copies buffer b diff to buffer a
\item \texttt{A} toggles readonly mode of buffer a
\item \texttt{B} toggles readonly mode of buffer b
\item \texttt{wa} save buffer a
\item \texttt{wb} save buffer b
\item \texttt{!} update the differance regions.  If you press \texttt{a} and \texttt{b} multiple times, you should probably do a \texttt{!}
\item \texttt{*} highlights the words in the diff region that differ
\item \texttt{ra} restore the diff region in buffer a
\item \texttt{rb} restore the diff region in buffer b
\item \texttt{z} suspend the ediff session
\item \texttt{s} make the merge buffer as small as possible
\end{itemize}

When you specify files, you can edit the files as root using tramp's syntax like this.

/su::/path/to/file
\subsection{Tramp}
\label{sec:orgd2d54a3}
Tramp is an emacs extension that lets you edit remote files. To use tramp, just begin by opening a file via \texttt{C-x C-f} (find-file) then typing one of the following special syntaxes:

/HOST:FILENAME
/USER@HOST:FILENAME
/USER@HOST\#PORT:FILENAME
/METHOD:USER@HOST:FILENAME
/METHOD:USER@HOST\#PORT:FILENAME
\section{Regexp}
\label{sec:orga50996f}
Regular expressions are nifty ways of searching/replacing regions of text.

Consider this example

\begin{verbatim}
if (isadmin() || ismanager ()) {
    //some code here
}
\end{verbatim}

Suppose that you want to add a space between both "is" in the functions.  The following would do this:

\texttt{M-x dired-do-query-replace-regexp is\textbackslash{}(admin\textbackslash{}|manager\textbackslash{}) RET is \textbackslash{}1 RET}

But let's get a basic understanding of regexps.

\section{Useful Elisp Libraries}
\label{sec:orgf1745b5}
\begin{itemize}
\item ctable \url{https://github.com/kiwanami/emacs-ctable}
\item s \url{https://github.com/magnars/s.el}
\item f \url{https://github.com/rejeep/f.el}
\item dash \url{https://github.com/magnars/dash.el}
\end{itemize}
\end{document}