# Written in 2013 by Christopher Allan Webber
#
# To the extent possible under law, the author(s) have dedicated all
# copyright and related and neighboring rights to this
# documentation/README file to the public domain worldwide. This
# software is distributed without any warranty.
# 
# You should have received a copy of the CC0 Public Domain
# Dedication along with this software. If not, see
# <http://creativecommons.org/publicdomain/zero/1.0/>.

#+TITLE: Intro to GNU Emacs

* What is emacs?
** Emacs is an editor

 - Emacs is an editor, but not just any editor.
 - Emacs is also a lisp machine, and this has powerful implications
 - "GNU/Linux is a nice bootloader for the emacs operating system"
   joke... not too untrue
 - Emacs is almost infinitely extensible
 - But who cares?
 - You should care!
 - Do you spend all day writing?  Are you a programmer?
 - A programmer spends all day in her editor.  It makes sense that she
   should be able to fit it to her needs.  It makes sense that she
   should want something powerful.
 - Not just for programmers!  Documentation people too... I'm looking
   at you, Jim!

** Some demonstrations

 - Just simple editing (of course, this is what we do more than
   anything!)
 - Opening a shell inside emacs and running pdb
 - nyan-mode

   #+BEGIN_SRC emacs-lisp
     (load-file "~/elisp/nyan-mode/nyan-mode.el")
     (nyan-mode)
   #+END_SRC

 - My orgmode agenda
 - changing my mode line:

   #+BEGIN_SRC emacs-lisp
     (load-file "~/.config/emacs/mode-line.el")
   #+END_SRC

 - Mail!
 - [[http://xkcd.com/378/][M-x butterfly]]
 - Tetris??!

** Killer features

 - Modes for almost any language you would want.
 - Useful debugging tools
 - Easy ability to add customizations and even write entirely new tools
 - OrgMode!  Oh my god... OrgMode!
 - Learning emacs lisp is a great way to learn to program!
 - Magit and vc-mode
 - Tetris??!

** Is emacs for you?

 - Learning emacs does take patience, but the payoff is big
 - The "emacs patriarchy"?
   - There was a case where I suggested orgmode to jewelfox
   - Kind of a [[http://jewelfox.dreamwidth.org/33061.html][backlash]]...

#+BEGIN_QUOTE
  Earlier on Identi.ca, I lamented the lack of a decent Free Software
  notetaking app that would sync between all my devices. In response,
  one of my friends suggested using emacs and orgmode, and waxed
  enthusiastic about how "Since it's plaintext, [it's] easy to sync
  between laptops via git!" In short order, he revealed a number of
  assumptions that I feel are common in the Free Software community:
  
      "Syncing" is something that happens between laptops, not between
      desktop and tablet computers and smartphones.
  
      Recommending the use of emacs and git to solve a particular
      problem is a reasonable solution.
  
      Recommending the use of emacs and git to solve a problem that most
      people would use a dedicated, well-maintained,
      thoughtfully-designed application for is also a reasonable
      solution.
  
  I feel that the vast majority of potential contributors are
  discouraged from participating by assumptions like these. Which insist
  on a high degree of technical knowledge and a high tolerance for
  frustration in order to contribute to or enjoy Free Software ... on
  the desktop. Which is one reason why the hackers and idealists inside
  much larger and healthier Free Software communities, like Mozilla's
  and WordPress', largely use Macs.
#+END_QUOTE

   - fwiw, I sent a reply saying I agree-ish... we need reasonable
     solutions that don't require such dive-in
   - But what about those of us who *enjoy* using things like emacs?
     Is it also bad to share our enthusiasm?
   - My friend Aeva and I had a conversation where we semi-seriously
     and semi-jokingly talked about the "emacs patriarchy"
   - By that, don't just mean gender issues (though I think there is a
     gender gap)
   - How do we make emacs accessible in the way other areas of free
     software are doing outreach?
   - That's mostly a question without answers
   - I do want to point to RMS's essay
     [[http://www.gnu.org/gnu/rms-lisp.html][My Lisp Experiences and the Development of GNU Emacs]]
     
#+BEGIN_QUOTE
It was Bernie Greenberg, who discovered that it was. He wrote a
version of Emacs in Multics MacLisp, and he wrote his commands in
MacLisp in a straightforward fashion. The editor itself was written
entirely in Lisp. Multics Emacs proved to be a great success
programming new editing commands was so convenient that even the
secretaries in his office started learning how to use it. They used a
manual someone had written which showed how to extend Emacs, but
didn't say it was a programming. So the secretaries, who believed they
couldn't do programming, weren't scared off. They read the manual,
discovered they could do useful things and they learned to program.
#+END_QUOTE

   - So maybe we should be careful to make sure we have easier, more
     cushioned software than as something as overwhelming as emacs for
     newcomers, or we'll scare people away from free software
   - But I think there's something interesting there, that there's a
     lot you can do if you don't already know you're supposed to be
     scared by it!
   - How to kill the emacs patriarchy?  Use emacs, and help others use
     emacs!  And that's true for other technical tools also.

I'll give some more encouragement on why I think emacs is really great
in a few, but now one more warning.

** A word of warning about RSI

 - You should know about RSI
 - My own story with Libreplanet
 - [[http://gmarceau.qc.ca/articles/your-wrists-hurt-you-must-be-a-programmer.html][Your wrists hurt, you must be a programmer]]
 - Keyboard chording may increase risk
 - Not using emacs won't save you though!
 - I know users who use notepad and vim and have serious RSI, worse
   than I do
 - [[http://dustycloud.org/tmp/messydesk/20111023_005.jpg][I have my own foot pedal related solution]]
 - Yeah that's pretty dorky
 - At the very least, you should remap caps lock to control.  This is
   critical to avoiding "the emacs claw"
 - Demo of how to do so in GNOME!

** Still here?  Emacs is probably for you!

 - Emacs is fun.  Every day I enjoy working in it.
 - I told myself I'd never become "one of those people"
 - I did anyway, because it was too much fun... and too
   efficient!... not to.

** Don't panic!

:               _------_
:             .'        '.  \|||
:            /            \-_  )
:      \\\| ,              ,__\\
:       (  /(  ,'-_____'-, )---'
:        ||//\ \ uuuuuuu //
:        ',/  '.'----.'\\,
:               '-____\,/
: 
:             _  _ , , ___
:            |O)(_)|\|' |
:           _             _
:          |_) /\ |\ | | /  |
:          |  /''\| \| | \_ o

 - Easy to get intimidated by watching someone experienced with emacs
   doing crazy things
 - That's just because they've been using it for a long time.  My 2004
   self might be overwhelmed by my use of emacs.
 - You can do a lot with emacs fairly quickly!
 - Start slow, but keep learning as you go
 - Have fun!

* Some history

 - Emacs was a project at the MIT AI lab, originally written with
   terrible things called "teco macros"
 - At the time, a full screen editor of its type was revolutionary
 - Lisp machines swoop in, change computing in the AI lab.  RMS works
   in the battle between some lisp companies to take revenge on what
   he sees as the AI lab destruction.  Lisp lisp lisp, entire
   operating machines written in lisp!
 - Jump to 1984: RMS starts the GNU project.  The first GNU project: a
   complete emacs rewrite!
 - As quoted earlier, was inspired by Multics MacLisp 
 - Emacs rewritten to be an integrated editor and lisp machine
 - You can tell how similar the UIs are too:
   http://image.absoluteastronomy.com/images/encyclopediaimages/x/x-/x-document.gif

* Diving into emacs
** How do I learn emacs?

 - Start with simple use
 - Read the tutorials
 - Read the manual
 - Force yourself to do projects in it!

   (When I was in college I decided to start learning Emacs and LaTeX
   simultaneously in the same night when I had a term paper due the
   next morning... I just barely survived, but I forced myself
   through!)

 - Read the [[http://emacswiki.org][emacs wiki]] and search the web if you need help
 - There's also a channel on freenode called #emacs... warning, it's a
   bit overwhelming sometimes, but I hang out in there :)
 - Keep trying and be patient.  Like all "fighter jet" software,
   there's a high learning curve, but a high reward for sticking with
   it.

** Opening for the first time

Pretty straightforward, let's do it via gnome

Okay, let's do it without my customizations on via a terminal :)

** Opening files via the menu bar
** Opening files via a keyboard command

Don't panic! :)

Or do it the keybinding way:
: C-x C-f

** Two helpful tutorials

 - [[http://www.gnu.org/software/emacs/tour/][A Guided Tour of Emacs]]
 - The builtin emacs tutorial: Help->Emacs tutorial

** Keyboard shortcuts (or: playing Mortal Kombat with your keyboard)

Escape-Meta-Alt-Control-Shift... emacs! ;)

 - Commands like "C-x C-f" to open a file might seem ridiculous and even
   impossible to learn
 - Like playing video games or even typing, if you keep doing it, it
   becomes second nature
 - You don't need to force yourself to learn commands, but try to pick
   up useful ones slowly
 - It pays to use keyboard commands!  It's so much faster, and if you
   ever see someone doing "editing wizardry" it's probably because
   they have super keyboard command skills

If you see something like "C-x C-M-f" that means "hit Control + x at
the same time, then Control, alt and f at the same time".  Don't
worry, most emacs shortcuts don't require hitting multiple things at
once.

 - C-x means "hit Control and x at the same time"
 - M-z means "hit Alt and z at the same time" (M stands for "Meta")...
   meta is effectively the same as alt ;)

C-g is a special command, says quit, gets you outta there!

** Understanding some goofy terms

Emacs was one of the first free software projects ever, and the first
GNU project ever.  It's got a lot of history, and had some terminology
that existed before we came up with more modern terms..

 - frames and windows: swapped from what you expect!
 - killing, yanking, and the kill ring
   (translation: cutting, pasting, and paste history)
 - meta: this just means the alt key
 - point, mark, and the region: basically, the cursor, the start of
   the selection, and the selection area itself
 - modes: major and minor modes both... well, easier to explain out loud
 - buffer: basically emacs' representation of a file you have
   open... or some other representation of text (for example, a magit
   buffer)
 - the mode line: that line that says what file you have open and stuff
 - the minibuffer: the area at the bottom where sometimes messages pop
   up and you are prompted for things

** Using the manual

Emacs comes with a manual!

Help->"Read the emacs manual" (or: C-h r)

It's a bit intimidating... but most things you'd want to know are in
there.

Reading that will show it to you in the "info browser" which is cool
but might be intimidating if you're new to emacs.  There are also HTML
versions online.

** Emacs is a self-documenting editor

What the hell does that mean?  Let's find out!

Let's say we wonder... what does C-t do?  Emacs knows, and can tell you!

In the "Help" menu you'll see there's a "Help->Describe->Describe key"
function.  Press that, then actually hit the key you want to learn about.

Now we can try that with a keybinding first!  "C-h k"

We can also find out:
 - what a function means: "C-h f"
 - find some functions that have a word in their name or description:
   "C-h a" for apropos
 - "C-h w" find out where that command is

Remember: emacs is just binding lisp functions to keys.  That's all!

** Interactive commands

Many commands can be run interactively via M-x

For example, all keybindings can be run this way.

Try:
 - M-x find-file
 - M-x make-directory

* Down the rabbit hole: customization and lisp
** Falling gently down the rabbit hole

Again: Don't panic!

** The customize interface

Options->Customize emacs

I used to use this a lot, but I don't anymore.

Nonetheless you can do quite a bit of tweaking from this.

** Your .emacs file

Basically, this is where we put customizations.

I'll show you mine :)

#+BEGIN_SRC emacs-lisp
(find-file "~/.emacs")
#+END_SRC

Let's also look at my general file

#+BEGIN_SRC emacs-lisp
(find-file "~/.config/emacs/general.el")
#+END_SRC

** Dipping your toe into lisp

Lisp:

:  (message "hello world!")

You can survive fairly far with barely any lisp knowledge.  But
there's a couple of things you should at least know.

Lisp is all about the parentheses.

A list (note the quote):

:  '("dog" "cat" "rat")

Without the quote, the first argument is a function (or macro call..)

:  (+ 1 2 3)

:  (+ (* 2 4) (/ 6 3))

** Going for a lisp swim

You will probably want to turn on show-paren-mode.  (It might be on by default?)

#+BEGIN_SRC emacs-lisp
  (defun add-three (some-number)
    "Take SOME-NUMBER and return that number plus three."
    (+ some-number 3))
#+END_SRC

I'm willing to write something on the fly... :)

#+BEGIN_SRC emacs-lisp
  (defun tell-me-if-its-broken (is-it-broken)
    (if is-it-broken
        (message "Yeah that's totally broken.")
      (message "It looks fine, stop stressing!")))
#+END_SRC

Oh yeah, about nil, t, and lisp functions..

 - car, cdr and friends
 - it's all about the linked lists!
 - Anyway, parenthesis matching makes it a bit easier

** Drowning in lisp

We're not going to talk about macros today, with the exception that
I'll tell you what they are.

** Learning from other lisp

Let's try:
: C-h f "find-file" <RET>

We can read about the lisp stuff right here

** Learning more

I highly recommend reading through the "Emacs Lisp Intro"... it's how
I learned much of my first programming skills!

** Lisp is beautiful

Lisp is a bit overwhelming because of its minimal syntax.  But its
minimal syntax also makes it super powerful: you can write new
language features quickly, and the code you have is readable but also
looks like the actual structure of the language.

http://xkcd.com/224/
http://xkcd.com/297/

** How little can you get away with?

Well.... you don't really need to know

The most important thing to know is setq, which is how you set a
variable.  So, for example:

#+BEGIN_SRC emacs-lisp
  (setq some-variable "monkeys")
#+END_SRC

sets some variable to monkeys.

#+BEGIN_SRC emacs-lisp
  ;; Make sure that pressing middle mouse button pastes right at point,
  ;; not where the mouse cursor is.
  (setq mouse-yank-at-point t)
#+END_SRC

* Wrap up

I showed a lot of cool things here, but also some intimidating things.

The key to emacs is: don't be intimidated!  Work with what you know,
and keep coming back and learning more.