├── .gitignore ├── images ├── do.png ├── mouse.png ├── window.png ├── echoarea.png ├── filemenu.png ├── modeline.png └── titlebar.png ├── .gitmodules ├── bin ├── layout ├── updated ├── title ├── toc ├── footnotes ├── next ├── tables ├── toc.awk └── glossarylinks ├── toc ├── LICENSE ├── layout.haml ├── howtolearn.haml ├── makefile ├── contribute_guide.haml ├── README ├── install.haml ├── ergonomics.haml ├── info.haml ├── tutorial.haml ├── howtolearn.html ├── osx.haml ├── contribute_guide.html ├── glossary.haml ├── install.html ├── info.html ├── osx.html ├── why.haml ├── customize_general.haml ├── ergonomics.html ├── emacs.css ├── contribute_emacs.haml ├── glossary.html ├── tutorial.html ├── why.html ├── customize_general.html ├── contribute_emacs.html ├── customize_colors.haml ├── customize_colors.html └── customize_c.haml /.gitignore: -------------------------------------------------------------------------------- 1 | layout.html 2 | .DS_Store 3 | -------------------------------------------------------------------------------- /images/do.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drothlis/how-to-learn-emacs/HEAD/images/do.png -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "haml"] 2 | path = haml 3 | url = git://github.com/drothlis/haml.git 4 | -------------------------------------------------------------------------------- /images/mouse.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drothlis/how-to-learn-emacs/HEAD/images/mouse.png -------------------------------------------------------------------------------- /images/window.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drothlis/how-to-learn-emacs/HEAD/images/window.png -------------------------------------------------------------------------------- /images/echoarea.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drothlis/how-to-learn-emacs/HEAD/images/echoarea.png -------------------------------------------------------------------------------- /images/filemenu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drothlis/how-to-learn-emacs/HEAD/images/filemenu.png -------------------------------------------------------------------------------- /images/modeline.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drothlis/how-to-learn-emacs/HEAD/images/modeline.png -------------------------------------------------------------------------------- /images/titlebar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/drothlis/how-to-learn-emacs/HEAD/images/titlebar.png -------------------------------------------------------------------------------- /bin/layout: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | # Prints a complete html page to stdout from the layout filename in $1 and the 4 | # content on stdin. 5 | 6 | sed -e '/-- Contents --/ q' $1 7 | cat 8 | sed -n -e '/-- Contents --/,$ p' $1 9 | -------------------------------------------------------------------------------- /bin/updated: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | # Replaces "" on stdin with the date of the latest commit. 4 | 5 | updated=$(git log -n1 --format=format:%cD "$@" | awk '{print $2, $3, $4 "."}') 6 | sed -e "s,,$updated," 7 | -------------------------------------------------------------------------------- /bin/title: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | # Replaces "" on stdin with the actual title on stdout; 4 | # takes the actual title from the

...

contents of the filename in $1. 5 | 6 | title=$(sed -n 's,%h1 \(.*\),\1,p' $1) 7 | sed -e "s,,How to learn Emacs :: $title," 8 | -------------------------------------------------------------------------------- /bin/toc: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | # Replaces "" on stdin with html, generated by 4 | # toc.awk, on stdout. 5 | 6 | plain_toc=$1 7 | chapter=$2 # toc.awk highlights this chapter. 8 | 9 | html_toc=/tmp/toc.html.$$ 10 | trap "rm -f $html_toc" EXIT 11 | 12 | $(dirname $0)/toc.awk current=$chapter < $plain_toc > $html_toc 13 | sed -e "/-- Table of Contents --/ r $html_toc" 14 | -------------------------------------------------------------------------------- /toc: -------------------------------------------------------------------------------- 1 | 1. howtolearn 2 | 2. why 3 | 4 | —Basic usage— 5 | 3. install 6 | 4. tutorial 7 | 5. basic_c +subsections 8 | 9 | —Basic customisation— 10 | 6. customize_c +subsections 11 | 7. customize_colors +subsections 12 | 8. customize_general +subsections 13 | 14 | —Miscellaneous— 15 | 9. info +subsections 16 | 10. contribute_emacs 17 | 18 | —Appendices— 19 | A. ergonomics 20 | B. osx 21 | C. contribute_guide 22 | D. glossary 23 | -------------------------------------------------------------------------------- /bin/footnotes: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | # Replaces "[1]" on stdin with an html link to #fn1 on stdout; 4 | # similarly, replaces "[1]:" with an html anchor for #fn1. 5 | 6 | # GNU sed uses "-r" for extended regexps; BSD sed uses "-E". 7 | if $(echo test | sed -r >/dev/null 2>&1); then 8 | sed="sed -r" 9 | else 10 | sed="sed -E" 11 | fi 12 | 13 | fn='\[\[([0-9]+)\]\]' 14 | $sed -e "/$fn/ s,$fn([^:]|\$),[\1]\2,g" \ 15 | -e "s,$fn:,[\1]:," 16 | -------------------------------------------------------------------------------- /bin/next: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | # Inserts, at the appropriate position on stdout, an html link to the next 4 | # chapter. 5 | 6 | plain_toc=$1 7 | chapter=$2 8 | next_chapter=$(awk "\$2 == \"$chapter\" { PRINT=1; next; } 9 | /^[0-9A-Z]+\. / && PRINT==1 { print \$2; exit; }" \ 10 | < $plain_toc) 11 | 12 | if [ -n "$next_chapter" ]; then 13 | next_title=$(sed -n 's,%h1 \(.*\),\1,p' $next_chapter.haml) 14 | next_link="" 15 | sed -e "s,,

$next_link

," 16 | else 17 | cat 18 | fi 19 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright © 2012 David Röthlisberger. 2 | Permission is granted to copy, distribute and/or modify this document 3 | under the terms of the GNU Free Documentation License, Version 1.3 4 | or any later version published by the Free Software Foundation; 5 | with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. 6 | A copy of the license is available at http://www.gnu.org/copyleft/fdl.html 7 | 8 | The scripts in the bin/ directory, and the makefile in the same directory as 9 | this LICENSE file, are released to the public domain. If you live somewhere 10 | with totally braindead Copyright laws, you can use them (the scripts and the 11 | makefile) under the ISC or CC0 licenses, both of which are as close to the 12 | public domain as possible. 13 | -------------------------------------------------------------------------------- /bin/tables: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env perl 2 | 3 | while (<>) { 4 | if (s,^( *)\| *,,) { 5 | $indentation = $1; 6 | print $indentation; 7 | if (! $intable) { 8 | $intable = 1; 9 | print "\n$indentation"; 10 | } 11 | if (! $inrow) { 12 | $inrow = 1; 13 | print ",; 19 | } 20 | markdown(); 21 | } 22 | elsif ($intable) { 23 | $intable = 0; 24 | print "$indentation
" 14 | } 15 | s, \| ,,g; 16 | if (/\|$/) { 17 | $inrow = 0; 18 | s,\|$,
\n"; 25 | } 26 | s,^( *)\\\|,$1|,; 27 | 28 | print; 29 | } 30 | 31 | # My own limited markdown implementation, because the markdown invoked by my 32 | # toolchain ("haml --autofilter markdown" ...) doesn't touch content inside 33 | # .... 34 | sub markdown { 35 | s,`([^`]+)`,$1,g; 36 | s, $,
,; 37 | } 38 | -------------------------------------------------------------------------------- /bin/toc.awk: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env awk -f 2 | 3 | BEGIN { printf "\n

" $0 "

\n\n" } 7 | 8 | function li(number, file, subs) { 9 | if (file == current) printf "
  • " 10 | else printf "
  • " 11 | printf number " " 12 | system("sed -n 's,%h1 ,,p' " file ".haml | tr -d '\n'") 13 | if (file != current) printf "" 14 | if (file == current && subs == "+subsections") { 15 | printf "\n \n " 18 | } 19 | printf "
    • \n" 20 | } 21 | function subsections(file) { 22 | system("sed -En 's,%h2#([a-z0-9-]*) (.*)" \ 23 | ",
  • \\2
    • " \ 24 | ",p' " file ".haml") 25 | } 26 | -------------------------------------------------------------------------------- /layout.haml: -------------------------------------------------------------------------------- 1 | !!! 5 2 | %html(lang="en") 3 | %head 4 | %meta(charset="utf-8") 5 | %title 6 | / Title 7 | %link(rel="stylesheet" href="emacs.css" media="all") 8 | 9 | %body 10 | 11 | #sidebar 12 | #info 13 | %h1 How to learn Emacs 14 | 15 | By [David Röthlisberger](http://david.rothlis.net). 16 | Comments welcome at david@rothlis.net. 17 | Last updated 18 | 19 | #toc 20 | / Table of Contents 21 | 22 | Copyright © 2012 [David Röthlisberger](http://david.rothlis.net). 23 | This guide is released under the 24 | GNU 25 | Free Documentation License. 26 | 27 | #content2 28 | / Contents 29 | 30 | / Next chapter link 31 | -------------------------------------------------------------------------------- /howtolearn.haml: -------------------------------------------------------------------------------- 1 | -# This file will go inside a
    so feel free to use h1 etc. 2 | 3 | %h1 About this guide to Emacs 4 | 5 | This guide is aimed at computer programmers who want to master the GNU Emacs 6 | text editor. 7 | 8 | It has been said that the Emacs learning curve is not so much steep as *long*. 9 | While the initial learning curve is indeed much steeper than other editors, 10 | that is a hump you'll get over fairly soon. This guide does start from the 11 | basics, but its real aim is to help you reach the next level —programming the 12 | behavior of Emacs itself— in months rather than years. The focus is on 13 | self-driven discovery by leveraging the Emacs built-in help, debugging 14 | facilities, and source code. 15 | 16 | What I need from you is commitment (a couple of dedicated hours of study per 17 | week, and to use Emacs as your day-to-day editor) and patience (be willing to 18 | give up your favourite IDE's features, at least for a month or two). 19 | 20 | If you're not sure it's worth the trouble, please read the next section—and 21 | *then* by all means sniff in contempt. 22 | -------------------------------------------------------------------------------- /makefile: -------------------------------------------------------------------------------- 1 | chapters := $(shell awk '/^[0-9A-Z]+\. / {print $$2}' toc) 2 | 3 | chapters_haml := $(chapters:%=%.haml) 4 | chapters_html := $(chapters:%=%.html) 5 | 6 | all: $(chapters_html) 7 | 8 | haml := haml/bin/haml --format html5 --autofilter markdown 9 | 10 | $(chapters_html): %.html: %.haml toc layout.html 11 | @echo $@: $^ 12 | @set -o pipefail; \ 13 | cat $< |\ 14 | bin/footnotes |\ 15 | bin/tables |\ 16 | $(haml) |\ 17 | bin/layout layout.html |\ 18 | bin/title $< |\ 19 | bin/updated $(chapters_haml) |\ 20 | bin/toc toc $(<:%.haml=%) |\ 21 | bin/glossarylinks $(filter glossary.haml,$<) |\ 22 | bin/next toc $(<:%.haml=%) \ 23 | > $@ 24 | 25 | layout.html: layout.haml 26 | @echo $@: $^ 27 | @$(haml) $< > $@ 28 | 29 | clean: 30 | rm -f *.html 31 | .PHONY: clean 32 | 33 | wc: $(chapters_haml) 34 | @for f in $^; do \ 35 | printf "%25s" $$f; \ 36 | sed -Ee '/^ *(\.figure|\.window|\.modeline|\.echoarea)/,/^$$/ d' \ 37 | $$f | wc; \ 38 | done; \ 39 | printf "%25s" ""; \ 40 | sed -Ee '/^ *(\.figure|\.window|\.modeline|\.echoarea)/,/^$$/ d' \ 41 | $^ | wc 42 | .PHONY: wc 43 | 44 | .DELETE_ON_ERROR: 45 | -------------------------------------------------------------------------------- /bin/glossarylinks: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env perl 2 | 3 | # Replaces words on stdin with html links to their entry in the glossary. 4 | # Presence of any command-line argument inhibits all replacements (we don't want to 5 | # add links on the glossary html page itself, for example). 6 | 7 | while () { 8 | if (!@ARGV[0] && !/frame 1|tcpip-parser|Notepad|Making Buffer Names Unique/) { 9 | s,((C-M-|C-|M-|s-)([a-zA-Z0-9 /|-])+),$1,g; 10 | s,(?-])\b(frame)\b(?![/<]),$&,gi; 11 | s,(?-])\b(windows?)\b(?![/<]),$&,g; 12 | s,(?-])\b(buffers?)\b(?![/<-]),$&,gi; 13 | s,(?-])\b(modeline)\b(?![/<]),$&,gi; 14 | s,(?-])\b(echo area)\b(?![/<]),$&,gi; 15 | s,(?-])\b(minibuffer)\b(?![/<]),$&,gi; 16 | s,(?-])\b(the (point|mark|region))\b,$&,gi; 17 | s,(?-])\b(kill|yank)(ing)?\b,$&,gi; 18 | s,(?-])\b(editing modes?|major modes?)\b,$&,gi; 19 | s,(?-])\b(minor modes?)\b,$&,gi; 20 | } 21 | print; 22 | } 23 | -------------------------------------------------------------------------------- /contribute_guide.haml: -------------------------------------------------------------------------------- 1 | %h1 Contributing to this guide 2 | 3 | This guide is released under the [GNU Free Documentation License]( 4 | http://www.gnu.org/copyleft/fdl.html). The source documents are available on 5 | [github]( https://github.com/drothlis/how-to-learn-emacs). Please contribute 6 | patches, no matter how small, to correct errors or omissions. It's very easy! 7 | 8 | I initially intended to write multiple variants of the introductory chapter 9 | ["Basic Unix/C workflow"]( basic_c.html): One targeting Ruby/Rails developers, 10 | etc. I gave up due to a lack of time, but if you'd like to contribute such a 11 | chapter, please do. It could be tricky because I introduce concepts in a 12 | particular order, and an introductory chapter for (say) Rails development would 13 | require installing third-party packages, something I don't touch on until much 14 | later. 15 | 16 | 17 | %h2 Super-easy way to contribute small patches 18 | 19 | If you have a small correction to wording or spelling, you can browse to the 20 | source file on [github](https://github.com/drothlis/how-to-learn-emacs), click 21 | the button that says "Fork and edit this file", make your change, and submit a 22 | "pull request". This will require you to create a (free) account on github, but 23 | you don't even need to checkout the source files onto your computer. 24 | 25 | Or just [email me]( mailto:david@rothlis.net?subject=How%20to%20learn%20Emacs) 26 | the correction. Unless you ask me otherwise, I will use your name and email 27 | address in the change logs, which will be visible to anyone who downloads the 28 | source repository from github. 29 | 30 | 31 | %h2 More complex changes 32 | 33 | See the [README]( 34 | https://github.com/drothlis/how-to-learn-emacs/blob/master/README) for 35 | instructions on generating the html from the source haml files. 36 | -------------------------------------------------------------------------------- /README: -------------------------------------------------------------------------------- 1 | "How to learn Emacs" 2 | is a guide aimed at computer programmers who want to master the GNU Emacs 3 | text editor. 4 | 5 | 6 | Generating HTML from the source HAML files 7 | ========================================== 8 | 9 | The document source is in Haml + Markdown format: Haml for HTML block 10 | structure, and Markdown for paragraphs and formatting. 11 | 12 | Haml uses significant indentation: 13 | 14 | HAML HTML 15 | #about
    16 | *Hello* there *Hello* there 17 |
    18 | 19 | See for details. 20 | 21 | I use a custom fork† of Haml that automatically formats plain-text content 22 | through Markdown‡, so the above Haml example actually converts to: 23 | 24 |
    25 |

    26 | Hello there 27 |

    28 |
    29 | 30 | † 31 | ‡ 32 | 33 | To install all the necessary tools: (on a Unixy system: Linux, OS X, etc.) 34 | 35 | 1. Install ruby and rubygems (the ruby package manager) with your system's 36 | package manager (macports or homebrew on OS X, apt-get or yum on some Linux 37 | distributions, etc.). You may already have these installed (try `ruby` and 38 | `gem` at the terminal). On some systems the `rubygems` package is called 39 | `rb-rubygems`. 40 | 41 | 2. Use `gem` to install the rdiscount package (a Markdown implementation): 42 | `gem install rdiscount` 43 | 44 | 3. Clone this repository: 45 | `git clone git://github.com/drothlis/how-to-learn-emacs.git` 46 | 47 | 4. Fetch the haml submodule of this repository: 48 | `cd how-to-learn-emacs` 49 | `git submodule init` 50 | `git submodule update` 51 | 52 | 5. Build the HTML from the Haml sources: 53 | `make` 54 | 55 | 56 | Why are the generated HTML files tracked in the git repository? 57 | =============================================================== 58 | 59 | So that I can easily see the effects of changes to the scripts that generate 60 | the HTML. 61 | -------------------------------------------------------------------------------- /install.haml: -------------------------------------------------------------------------------- 1 | %h1 Install the right Emacs 2 | 3 | Install the latest release of [GNU Emacs]( http://www.gnu.org/s/emacs/) (24.1 4 | as of this writing). Not XEmacs, not EmacsW32, not AquaMacs, not Carbon Emacs. 5 | 6 | %h2 Linux 7 | 8 | Emacs is probably already installed; if not, use your distro's package manager 9 | (yum, apt-get, etc). 10 | 11 | If your distro only has older Emacs packages, you could try finding a 12 | third-party package repository, or [building the latest version from source]( 13 | http://www.gnu.org/software/emacs/emacs-faq.html#Compiling-and-installing-Emacs) 14 | if you are comfortable doing so. 15 | 16 | %h2 OS X 17 | 18 | If you use [macports]( http://www.macports.org/), install the `emacs-app` port, 19 | which gives you a native OS X application. By default macports will install 20 | Emacs.app into /Applications/MacPorts. If you use a laptop I recommend the 21 | `fullscreen` variant (i.e. `port install emacs-app +fullscreen`) which adds the 22 | command `ns-toggle-fullscreen` to Emacs. 23 | 24 | If you use [homebrew]( http://mxcl.github.com/homebrew/): 25 | `brew install emacs --cocoa`. 26 | 27 | Otherwise, you can use a [pre-built emacs]( http://emacsformacosx.com/), but do 28 | consider installing macports or homebrew so that you can easily install other 29 | Unixy tools as you need them. 30 | 31 | %h2 Windows 32 | 33 | You are mostly on your own as I am not a Windows user; I apologize in advance 34 | if some of the examples in this guide don't work on your system, as I haven't 35 | tested on Windows. 36 | 37 | You'll want to download the latest `emacs-xx.x-bin-i386.zip` from 38 | and unzip it into a directory of 39 | your choice. Then run `addpm.exe` from the `bin` subdirectory, as an 40 | administrator (this adds a start menu shortcut and various registry entries). 41 | 42 | Some Emacs functionality requires Unixy tools like `find` and `grep`, which you 43 | can get by installing a posix emulation environment such as [Cygwin]( 44 | http://www.gnu.org/software/emacs/windows/Other-useful-ports.html). You will 45 | have to ensure that the posix utilities are on the system PATH so that Emacs 46 | can find them. 47 | 48 | For further help refer to the [GNU Emacs FAQ for MS Windows]( 49 | http://www.gnu.org/software/emacs/windows/) and the (often outdated) 50 | [EmacsWiki]( http://www.emacswiki.org/emacs/MsWindowsInstallation). 51 | 52 | %h2 Remove any existing .emacs configuration 53 | 54 | If you have existing Emacs customizations in a `.emacs` file or `.emacs.d` 55 | directory, you should move it out of the way if you want your Emacs behavior to 56 | exactly mirror the examples in this guide. 57 | -------------------------------------------------------------------------------- /ergonomics.haml: -------------------------------------------------------------------------------- 1 | %h1 Ergonomics 2 | 3 | Most of the following advice relies heavily on the Control key, so bind your 4 | Caps Lock to Control. This is easy to do on [OS X](osx.html) and Linux, and on 5 | Windows involves [changing a registry entry]( 6 | http://sites.google.com/site/steveyegge2/effective-emacs#item1). 7 | 8 | You may choose to swap the left Control key with Caps Lock, or just to make 9 | them both Control keys — in Emacs and bash you can uppercase a word with `M-u` 10 | (upcase-word) and the region with `C-x C-u` (upcase-region). 11 | 12 | Now you will find the navigation keys like `C-f`, `C-b`, `C-n` and `C-p` much 13 | closer to your home row position than the arrow keys. Learn to navigate in 14 | larger jumps with `C-a` and `C-e` (beggining and end of line), `M-f` and `M-b` 15 | (forward and back by one word), `C-M-f` and `C-M-b` (forward and back by one 16 | block of parentheses or braces), and `M-a` and `M-e` (beginning and end of a 17 | sentence or expression). 18 | 19 | If you need to move to a far-away position it is often faster to get there by 20 | searching with `C-s`. 21 | 22 | For fixing typos, `C-t` (transpose-chars) comes in handy. 23 | 24 | Instead of reaching for the backspace key, consider rebinding `C-h` to 25 | backspace (as in most shells), and `C-w` to backward-kill-word (also as in most 26 | shells; in Emacs it is normally bound to `C-backspace`). `C-d` deletes the 27 | *next* character, and you don't even need to bind it yourself. 28 | 29 | Rebinding `C-h` is a bit tricky, because after making your binding you might 30 | activate some major or minor mode that binds a new sequence beginning with 31 | `C-h`, undoing your own binding. You can use `key-translation-map` to make 32 | `C-h` appear to Emacs as the backspace key, ignoring all other `C-h` bindings 33 | now or in future: 34 | 35 | .window< 36 | :preserve 37 | (define-key key-translation-map (kbd "C-h") (kbd "<DEL>")) 38 | 39 | You will still be able to access the help commands with `F1 f`, `F1 v`, `F1 S`, 40 | etc. 41 | 42 | As for `C-w`, you could define your own function that keeps the default 43 | behavior when the region is active, and does `backward-kill-word` when not: 44 | 45 | .window< 46 | :preserve 47 | (defun kill-region-or-backward-kill-word (&optional arg region) 48 | "`kill-region' if the region is active, otherwise `backward-kill-word'" 49 | (interactive 50 | (list (prefix-numeric-value current-prefix-arg) (use-region-p))) 51 | (if region 52 | (kill-region (region-beginning) (region-end)) 53 | (backward-kill-word arg))) 54 | (global-set-key (kbd "C-w") 'kill-region-or-backward-kill-word) 55 | 56 | Some of these tips were inspired by Steve Yegge's [Effective Emacs]( 57 | http://sites.google.com/site/steveyegge2/effective-emacs) article. Read it. 58 | -------------------------------------------------------------------------------- /info.haml: -------------------------------------------------------------------------------- 1 | %h1 Info documentation 2 | 3 | %h2#path Info file search path 4 | 5 | The [Info manual]( 6 | http://www.gnu.org/software/texinfo/manual/info/html_node/Emacs-Info-Variables.html) 7 | tells us about variable `Info-default-directory-list`: 8 | 9 | .do 10 | .window< 11 | :preserve 12 | (eval-after-load 'info 13 | '(progn 14 | (push "/opt/local/share/info" Info-default-directory-list) 15 | (push "~/.emacs.d/info" Info-default-directory-list))) 16 | 17 | The first is the directory for info files installed by my package manager 18 | (macports); modify the path according to your own system. The second directory 19 | is where we'll install info files manually. 20 | 21 | 22 | %h2#glibc glibc 23 | 24 | [`glibc`]( http://www.gnu.org/software/libc/) ("gee lib cee") is the GNU 25 | implementation of `libc`, the Unix standard C library. Don't confuse it with 26 | `glib`, which is a library from the GNOME desktop project. 27 | 28 | If you're not developing for a GNU/Linux system, but you don't find 29 | `info`-format documentation for your system's own `libc`, you might still find 30 | the GNU docs useful. `glibc` follows the ISO C 99 and POSIX standards, and its 31 | documentation is always careful to point out where a feature is non-standard. 32 | Common Unix variations are covered (e.g. the BSD and SysV styles of signal 33 | handling). 34 | 35 | .do 36 | Download "Info document (gzipped tar file)" from [the GNU website]( 37 | http://www.gnu.org/software/libc/manual/). 38 | 39 | Untar into `~/.emacs.d/info/` 40 | 41 | `cd ~/.emacs.d/info` 42 | `install-info libc.info dir` 43 | 44 | `install-info` is provided by the texinfo package, which you can install with 45 | your system's package manager. 46 | 47 | The generated `dir` file contains an entry for every function and constant in 48 | libc. These entries are added to your top-level Info menu. It is easy to remove 49 | these from the top-level menu (you will still be able to find them via Info's 50 | `i`ndex command or by searching): The `dir` file is plain text, so you can edit 51 | it and remove those entries. Leave the single libc entry under "Libraries". 52 | 53 | Now visit a C file and use `info-lookup-symbol` to look up, say, `socket`. Go 54 | `u`p to the main sockets node for introductory material. 55 | 56 | 57 | %h2#python Python 58 | 59 | Install [pydoc-info.el]( 60 | https://bitbucket.org/jonwaltman/pydoc-info/src/default/pydoc-info.el) (we 61 | covered elisp package installation in a [previous chapter]( 62 | customize_colors.html#packages)) and follow the instructions under "Setup and 63 | Install" in [pydoc-info's README]( 64 | https://bitbucket.org/jonwaltman/pydoc-info). 65 | 66 | 67 | %h2#perl Perl 68 | 69 | I've found [info docs for perl 5.6]( 70 | http://www.cpan.org/doc/manual/texinfo/perl5/) (over a decade old now). If you 71 | know of a more recent version, or know how to build info files from the latest 72 | perl docs, please send me detailed instructions. 73 | 74 | And spread the word! It's a shame that such a well-integrated documentation 75 | system hasn't received more support from popular software distributions. 76 | -------------------------------------------------------------------------------- /tutorial.haml: -------------------------------------------------------------------------------- 1 | %h1 The very basics 2 | 3 | .do#first-key-sequence 4 | Work through the Emacs tutorial: Start Emacs and press `C-h t`. 5 | 6 | If the tutorial seems a bit tedious, soldier on. It will only take you 30 7 | minutes, at most; and the material is essential for understanding Emacs. Most 8 | of the cursor movement and text manipulation keybindings you'll learn will also 9 | work in the bash shell (or any program that uses the readline library) and, if 10 | you use OS X, even in the text fields of any native GUI application. 11 | 12 | Do not proceed to the next chapter of this guide until you have read the entire 13 | tutorial, and you are comfortable with: 14 | 15 | | Visiting (opening) and saving files: | `C-x C-f` and `C-x C-s` | 16 | | Switching between buffers: | `C-x b` and `C-x C-b` | 17 | | Using the mark and the point 18 | | to set the region: | `C-SPC` | 19 | | Killing (cutting) and 20 | | yanking (pasting): | `C-w`, `C-k`, `C-y`, `M-y` | 21 | | Searching forwards and backwards: | `C-s`, `C-r` | 22 | | Invoking commands by name: | `M-x` | 23 | | Undo: | `C-/` | 24 | | Cancelling half-entered commands: | `C-g` | 25 | | Getting help on editing modes, 26 | | keybindings and commands: | 27 | | `C-h m`, `C-h k`, `C-h f`, `C-h a` 28 | | (just remember `C-h` and read 29 | | the prompt in the minibuffer) | 30 | | Quitting Emacs: | `C-x C-c` | 31 | 32 | .figure.first 33 | %img(src="images/filemenu.png" width="319" height="172") 34 | 35 | Don't worry if you don't remember *every­thing* from the tutorial. For now 36 | there's no need to remember all the cursor move­ment keybindings; the arrow 37 | keys will do. If you forget the keys for visiting (opening) or saving a file, 38 | the File menu will remind you. Instead of remembering `C-x 1` to remove other 39 | windows from the frame, you can use the mouse (hover over the right-hand side 40 | of the window's modeline and read the help text in the echo area). I will ask 41 | you to re-read the entire tutorial in a month or so, to fill in the gaps; in 42 | the meantime, try to learn the keybindings instead of relying on the menus and 43 | the mouse. 44 | 45 | .window< 46 |   47 | .modeline< 48 | :preserve 49 | -U:--- *scratch* All L1 (Lisp Interaction)----------------------------------------------- 50 | %img.mouse(src="images/mouse.png") 51 | .echoarea< 52 | mouse-1: Select (drag to resize), mouse-2: Make current window occupy the whole frame, mouse-3: Remove current window from display 53 | 54 | If you're on a Mac running OS X, you're in luck: Since you have separate Meta 55 | (alt/option), Control, and Command (⌘) keys on your keyboard, the latter is 56 | reserved for the standard OS keybindings. You can save with ⌘-s, copy with ⌘-c, 57 | paste with ⌘-v, and search with ⌘-f. Still, you should eventually learn the 58 | Emacs alternatives for all of the above, as they are much more powerful. In 59 | Emacs-speak the ⌘ key is called "super", abbreviated to a lower-case "s", as in 60 | `s-f`. 61 | -------------------------------------------------------------------------------- /howtolearn.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | How to learn Emacs :: About this guide to Emacs 7 | 8 | 9 | 10 | 11 | 54 |
    55 | 56 |

    About this guide to Emacs

    57 |

    This guide is aimed at computer programmers who want to master the GNU Emacs 58 | text editor.

    59 | 60 |

    It has been said that the Emacs learning curve is not so much steep as long. 61 | While the initial learning curve is indeed much steeper than other editors, 62 | that is a hump you’ll get over fairly soon. This guide does start from the 63 | basics, but its real aim is to help you reach the next level —programming the 64 | behavior of Emacs itself— in months rather than years. The focus is on 65 | self-driven discovery by leveraging the Emacs built-in help, debugging 66 | facilities, and source code.

    67 | 68 |

    What I need from you is commitment (a couple of dedicated hours of study per 69 | week, and to use Emacs as your day-to-day editor) and patience (be willing to 70 | give up your favourite IDE’s features, at least for a month or two).

    71 | 72 |

    If you’re not sure it’s worth the trouble, please read the next section—and 73 | then by all means sniff in contempt.

    74 | 75 |

    76 |
    77 | 78 | 79 | -------------------------------------------------------------------------------- /osx.haml: -------------------------------------------------------------------------------- 1 | %h1 OS X 2 | 3 | %h2 Control and Command keys 4 | 5 | Mac keyboards conveniently have separate Control, Meta (a.k.a. Option or Alt) 6 | and Command (⌘) keys. You have the traditional Emacs bindings on Control and 7 | Meta, and the OS X bindings on Command. 8 | 9 | As recommended previously, you should strongly consider re-binding Caps Lock 10 | to Control, system-wide. Go to System Preferences > Keyboard > Modifier Keys. 11 | 12 | On a laptop's smaller keyboard there is no Control key for the right hand. Good 13 | ergonomic practice is to use a right-hand Control key with a left-hand normal 14 | key, instead of stretching your left hand. You can use the open-source 15 | [KeyRemap4MacBook]( http://pqrs.org/macosx/keyremap4macbook/index.html) to bind 16 | your Return key to an additional Control—but only when held down; hitting it 17 | once still registers as Return. Try it! It's not as crazy as it sounds. 18 | KeyRemap4MacBook, despite its name, works on any recent Mac. 19 | 20 | After you have passed the initial learning curve and are used to the Emacs 21 | bindings for opening, saving, copying, cutting, pasting, and undo, you may want 22 | to re-bind the Command keys to be additional Meta keys, simply to offer a 23 | larger target for your fingers: 24 | 25 | .titlebar< 26 | init.el 27 | .window< 28 | :preserve 29 | (setq mac-command-modifier 'meta) 30 | (global-set-key (kbd "M-`") 'other-frame) 31 | 32 | (The second line keeps the very useful ⌘-\` behavior.) 33 | -# 34 | Rebinding Command in this way won't work when running Emacs inside a terminal, 35 | as the terminal program will intercept the Command keybindings. 36 | 37 | If you choose to leave the Command modifier alone, you might want to rebind 38 | `⌘-q` because it is so close to the frequently-used `M-q`. Or at least make 39 | Emacs prompt before quitting: 40 | 41 | .window< 42 | :preserve 43 | (setq confirm-kill-emacs 'y-or-n-p) 44 | 45 | %h2 System-wide PATH 46 | 47 | When you start Emacs.app from the Finder (or the Dock, or Spotlight) the 48 | environment doesn't contain customizations from your `.bash_profile` or 49 | `.bashrc` files. If you run a shell inside Emacs (`M-x shell`) that shell 50 | *will* load your `.bashrc`, but other Emacs commands like `shell-command`, 51 | `grep` and `compile` won't. 52 | 53 | You can modify Emacs's environment directly in your init file: 54 | 55 | .window< 56 | :preserve 57 | (setenv "PATH" (concat (getenv "HOME") "/bin:" 58 | "/opt/local/bin:" 59 | (getenv "PATH"))) 60 | 61 | You can also set environment variables to apply to any OS X application in your 62 | login session, by creating the file `~/.MacOSX/environment.plist`: 63 | 64 | .titlebar< 65 | \~/.MacOSX/environment.plist 66 | .window< 67 | :preserve 68 | <?xml version="1.0" encoding="UTF-8"?> 69 | <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" 70 | "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> 71 | <plist version="1.0"> 72 | <dict> 73 | <key>PATH</key> 74 | <string>/usr/bin:/bin:/usr/sbin:/sbin</string> 75 | </dict> 76 | </plist> 77 | 78 | 79 | %h2 Running Emacs from the command line 80 | 81 | If you're using Emacs.app installed by macports, you can find the command-line 82 | version in `/Applications/MacPorts/Emacs.app/Contents/MacOS/Emacs`. (Useful 83 | when you need to run Emacs with certain command-line switches, like `-Q`). 84 | -------------------------------------------------------------------------------- /contribute_guide.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | How to learn Emacs :: Contributing to this guide 7 | 8 | 9 | 10 | 11 | 54 |
    55 | 56 |

    Contributing to this guide

    57 |

    This guide is released under the GNU Free Documentation License. The source documents are available on 58 | github. Please contribute 59 | patches, no matter how small, to correct errors or omissions. It’s very easy!

    60 | 61 |

    I initially intended to write multiple variants of the introductory chapter 62 | “Basic Unix/C workflow”: One targeting Ruby/Rails developers, 63 | etc. I gave up due to a lack of time, but if you’d like to contribute such a 64 | chapter, please do. It could be tricky because I introduce concepts in a 65 | particular order, and an introductory chapter for (say) Rails development would 66 | require installing third-party packages, something I don’t touch on until much 67 | later.

    68 |

    Super-easy way to contribute small patches

    69 |

    If you have a small correction to wording or spelling, you can browse to the 70 | source file on github, click 71 | the button that says “Fork and edit this file”, make your change, and submit a 72 | “pull request”. This will require you to create a (free) account on github, but 73 | you don’t even need to checkout the source files onto your computer.

    74 | 75 |

    Or just email me 76 | the correction. Unless you ask me otherwise, I will use your name and email 77 | address in the change logs, which will be visible to anyone who downloads the 78 | source repository from github.

    79 |

    More complex changes

    80 |

    See the README for 81 | instructions on generating the html from the source haml files.

    82 | 83 |

    84 |
    85 | 86 | 87 | -------------------------------------------------------------------------------- /glossary.haml: -------------------------------------------------------------------------------- 1 | %h1 Glossary 2 | 3 | %dl 4 | %dt#keys Emacs key names: 5 | %dd 6 | | `C-x` | means Control-x. | 7 | | `C-x C-s` | means Control-x, then Control-s. | 8 | | `C-x k` | means Control-x, then k on its own (without Control). | 9 | | `M-x` | means Alt-x (Alt is called Option on some Mac keyboards). 10 | | The `M` stands for “Meta” which is presumably what the Alt 11 | | key was called in the 70s. | 12 | | `M-x help` | means press Alt-x, then type `help`, then press return. | 13 | | `C-M-x` | means Control-Alt-x | 14 | | `S-x` | means Shift-x | 15 | | `s-x` | means Command-x (the ⌘ Command key on Mac keyboards). 16 | | The `s` stands for “Super”, from the days when keyboards 17 | | had Meta, Super, and Hyper keys. | 18 | | `<RET>` | means the Return or Enter key. | 19 | | `<SPC>` | means the Space bar. | 20 | | `<DEL>` | means Backspace 21 | | (not to be confused with the delete-forward key) | 22 | 23 | %dt#frames Frames: 24 | %dd 25 | .figure#glossary-frames 26 | .titlebar< 27 | rl.c 28 | .window.default< 29 | :preserve 30 | int 31 | main (argc, argv) 32 | int argc; 33 | char **argv; 34 | {  35 | .modeline< 36 | :preserve 37 | --:--- rl.c 59% L83 Git-master (C/l Abbrev)----------------------------------- 38 | .window.default< 39 | :preserve 40 | make -k 41 | rm -f rl.o 42 | gcc -DHAVE_CONFIG_H -DREADLINE_LIBRARY -DRL_LIBRARY_VERSION='"6.2"' -I. -I.. -I.. -g -O -c rl.c 43 | rl.c: In function ‘main’: 44 | .modeline< 45 | :preserve 46 | -U:%*- *compilation* Top L1 (Compilation:exit [2])----------------------------------- 47 | .echoarea< 48 | Compilation exited abnormally with code 2 49 | %p One frame, two windows
    (each with its own modeline) 50 | 51 | 52 | What Emacs calls your window-manager's windows. [[Emacs manual]]( 53 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Frames.html) 54 | 55 | %dt#windows Windows: 56 | %dd 57 | Subdivisions inside a Frame. [[Emacs manual]]( 58 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Windows.html) 59 | 60 | %dt#buffers Buffers: 61 | %dd 62 | The text you are editing. The difference between a buffer and a file is 63 | that their contents may differ until you save your changes; and some 64 | buffers aren't backed by files at all (e.g. a `*compilation*` or `*Help*` 65 | buffer). [[Emacs manual]]( 66 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Buffers.html) 67 | 68 | %dt#modeline Mode line: 69 | %dd 70 | Describes the buffer in the window above the modeline. Hover your mouse 71 | over each indicator in the modeline for a description. [[Emacs manual]]( 72 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Mode-Line.html) 73 | 74 | %dt#echoarea Echo area: 75 | %dd 76 | The line at the very bottom of the frame, used to display small informative 77 | messages. [[Emacs manual]]( 78 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Echo-Area.html) 79 | 80 | %dt#minibuffer Minibuffer: 81 | %dd 82 | The echo area when it is prompting for user input. [[Emacs manual]]( 83 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Minibuffer.html) 84 | 85 | %dt#region The point, the mark and the region: 86 | %dd 87 | The point is where the cursor is. Set the mark with `C-`, move the 88 | point, and now the region is the area between point and mark. [[Emacs 89 | manual]]( 90 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Mark.html) 91 | 92 | %dt#killing Killing and yanking: 93 | %dd 94 | Killing = cutting. Yanking = pasting (sorry vi users!). [[Emacs manual]]( 95 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Killing.html) 96 | 97 | %dt#majormode Major mode or Editing mode: 98 | %dd 99 | A major mode is a customization of Emacs for editing text of a particular 100 | sort (e.g. a particular programming language). A buffer can only have one 101 | major mode active at a time. [[Emacs manual]]( 102 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Major-Modes.html) 103 | 104 | %dt#minormode Minor mode: 105 | %dd 106 | Multiple minor modes can be enabled at once; they add functionality ranging 107 | from syntax highlighting to automatic spell-checking to modifying the 108 | behavior of common Emacs commands. [[Emacs manual]]( 109 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Minor-Modes.html) 110 | -------------------------------------------------------------------------------- /install.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | How to learn Emacs :: Install the right Emacs 7 | 8 | 9 | 10 | 11 | 54 |
    55 | 56 |

    Install the right Emacs

    57 |

    Install the latest release of GNU Emacs (24.1 58 | as of this writing). Not XEmacs, not EmacsW32, not AquaMacs, not Carbon Emacs.

    59 |

    Linux

    60 |

    Emacs is probably already installed; if not, use your distro’s package manager 61 | (yum, apt-get, etc).

    62 | 63 |

    If your distro only has older Emacs packages, you could try finding a 64 | third-party package repository, or building the latest version from source 65 | if you are comfortable doing so.

    66 |

    OS X

    67 |

    If you use macports, install the emacs-app port, 68 | which gives you a native OS X application. By default macports will install 69 | Emacs.app into /Applications/MacPorts. If you use a laptop I recommend the 70 | fullscreen variant (i.e. port install emacs-app +fullscreen) which adds the 71 | command ns-toggle-fullscreen to Emacs.

    72 | 73 |

    If you use homebrew: 74 | brew install emacs --cocoa.

    75 | 76 |

    Otherwise, you can use a pre-built emacs, but do 77 | consider installing macports or homebrew so that you can easily install other 78 | Unixy tools as you need them.

    79 |

    Windows

    80 |

    You are mostly on your own as I am not a Windows user; I apologize in advance 81 | if some of the examples in this guide don’t work on your system, as I haven’t 82 | tested on Windows.

    83 | 84 |

    You’ll want to download the latest emacs-xx.x-bin-i386.zip from 85 | http://ftp.gnu.org/pub/gnu/emacs/windows/ and unzip it into a directory of 86 | your choice. Then run addpm.exe from the bin subdirectory, as an 87 | administrator (this adds a start menu shortcut and various registry entries).

    88 | 89 |

    Some Emacs functionality requires Unixy tools like find and grep, which you 90 | can get by installing a posix emulation environment such as Cygwin. You will 91 | have to ensure that the posix utilities are on the system PATH so that Emacs 92 | can find them.

    93 | 94 |

    For further help refer to the GNU Emacs FAQ for MS Windows and the (often outdated) 95 | EmacsWiki.

    96 |

    Remove any existing .emacs configuration

    97 |

    If you have existing Emacs customizations in a .emacs file or .emacs.d 98 | directory, you should move it out of the way if you want your Emacs behavior to 99 | exactly mirror the examples in this guide.

    100 | 101 |

    102 |
    103 | 104 | 105 | -------------------------------------------------------------------------------- /info.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | How to learn Emacs :: Info documentation 7 | 8 | 9 | 10 | 11 | 61 |
    62 | 63 |

    Info documentation

    64 |

    Info file search path

    65 |

    The Info manual 66 | tells us about variable Info-default-directory-list:

    67 |
    68 |
    (eval-after-load 'info '(progn (push "/opt/local/share/info" Info-default-directory-list) (push "~/.emacs.d/info" Info-default-directory-list)))
    69 |
    70 |

    The first is the directory for info files installed by my package manager 71 | (macports); modify the path according to your own system. The second directory 72 | is where we’ll install info files manually.

    73 |

    glibc

    74 |

    glibc (“gee lib cee”) is the GNU 75 | implementation of libc, the Unix standard C library. Don’t confuse it with 76 | glib, which is a library from the GNOME desktop project.

    77 | 78 |

    If you’re not developing for a GNU/Linux system, but you don’t find 79 | info-format documentation for your system’s own libc, you might still find 80 | the GNU docs useful. glibc follows the ISO C 99 and POSIX standards, and its 81 | documentation is always careful to point out where a feature is non-standard. 82 | Common Unix variations are covered (e.g. the BSD and SysV styles of signal 83 | handling).

    84 |
    85 |

    Download “Info document (gzipped tar file)” from the GNU website.

    86 | 87 |

    Untar into ~/.emacs.d/info/

    88 | 89 |

    cd ~/.emacs.d/info
    90 | install-info libc.info dir

    91 |
    92 |

    install-info is provided by the texinfo package, which you can install with 93 | your system’s package manager.

    94 | 95 |

    The generated dir file contains an entry for every function and constant in 96 | libc. These entries are added to your top-level Info menu. It is easy to remove 97 | these from the top-level menu (you will still be able to find them via Info’s 98 | index command or by searching): The dir file is plain text, so you can edit 99 | it and remove those entries. Leave the single libc entry under “Libraries”.

    100 | 101 |

    Now visit a C file and use info-lookup-symbol to look up, say, socket. Go 102 | up to the main sockets node for introductory material.

    103 |

    Python

    104 |

    Install pydoc-info.el (we 105 | covered elisp package installation in a previous chapter) and follow the instructions under “Setup and 106 | Install” in pydoc-info’s README.

    107 |

    Perl

    108 |

    I’ve found info docs for perl 5.6 (over a decade old now). If you 109 | know of a more recent version, or know how to build info files from the latest 110 | perl docs, please send me detailed instructions.

    111 | 112 |

    And spread the word! It’s a shame that such a well-integrated documentation 113 | system hasn’t received more support from popular software distributions.

    114 | 115 |

    116 |
    117 | 118 | 119 | -------------------------------------------------------------------------------- /osx.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | How to learn Emacs :: OS X 7 | 8 | 9 | 10 | 11 | 54 |
    55 | 56 |

    OS X

    57 |

    Control and Command keys

    58 |

    Mac keyboards conveniently have separate Control, Meta (a.k.a. Option or Alt) 59 | and Command (⌘) keys. You have the traditional Emacs bindings on Control and 60 | Meta, and the OS X bindings on Command.

    61 | 62 |

    As recommended previously, you should strongly consider re-binding Caps Lock 63 | to Control, system-wide. Go to System Preferences > Keyboard > Modifier Keys.

    64 | 65 |

    On a laptop’s smaller keyboard there is no Control key for the right hand. Good 66 | ergonomic practice is to use a right-hand Control key with a left-hand normal 67 | key, instead of stretching your left hand. You can use the open-source 68 | KeyRemap4MacBook to bind 69 | your Return key to an additional Control—but only when held down; hitting it 70 | once still registers as Return. Try it! It’s not as crazy as it sounds. 71 | KeyRemap4MacBook, despite its name, works on any recent Mac.

    72 | 73 |

    After you have passed the initial learning curve and are used to the Emacs 74 | bindings for opening, saving, copying, cutting, pasting, and undo, you may want 75 | to re-bind the Command keys to be additional Meta keys, simply to offer a 76 | larger target for your fingers:

    77 |

    init.el

    78 |
    (setq mac-command-modifier 'meta) (global-set-key (kbd "M-`") 'other-frame)
    79 |

    (The second line keeps the very useful ⌘-` behavior.)

    80 |

    Rebinding Command in this way won’t work when running Emacs inside a terminal, 81 | as the terminal program will intercept the Command keybindings.

    82 | 83 |

    If you choose to leave the Command modifier alone, you might want to rebind 84 | ⌘-q because it is so close to the frequently-used M-q. Or at least make 85 | Emacs prompt before quitting:

    86 |
    (setq confirm-kill-emacs 'y-or-n-p)
    87 |

    System-wide PATH

    88 |

    When you start Emacs.app from the Finder (or the Dock, or Spotlight) the 89 | environment doesn’t contain customizations from your .bash_profile or 90 | .bashrc files. If you run a shell inside Emacs (M-x shell) that shell 91 | will load your .bashrc, but other Emacs commands like shell-command, 92 | grep and compile won’t.

    93 | 94 |

    You can modify Emacs’s environment directly in your init file:

    95 |
    (setenv "PATH" (concat (getenv "HOME") "/bin:" "/opt/local/bin:" (getenv "PATH")))
    96 |

    You can also set environment variables to apply to any OS X application in your 97 | login session, by creating the file ~/.MacOSX/environment.plist:

    98 |

    ~/.MacOSX/environment.plist

    99 |
    <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>PATH</key> <string>/usr/bin:/bin:/usr/sbin:/sbin</string> </dict> </plist>
    100 |

    Running Emacs from the command line

    101 |

    If you’re using Emacs.app installed by macports, you can find the command-line 102 | version in /Applications/MacPorts/Emacs.app/Contents/MacOS/Emacs. (Useful 103 | when you need to run Emacs with certain command-line switches, like -Q).

    104 | 105 |

    106 |
    107 | 108 | 109 | -------------------------------------------------------------------------------- /why.haml: -------------------------------------------------------------------------------- 1 | %h1 Why Emacs 2 | 3 | I believe that the future of software development, if we are to survive 4 | ever-increasing complexity, lies in domain-specific languages that can express 5 | solutions measured in hundreds of lines of code, not the tens or hundreds of 6 | *thousands* of lines common in today's software systems. 7 | 8 | #vri-examples 9 | #nile< 10 | :preserve 11 | CompositeSoftLight : Compositor 12 | ∀ (A, B) 13 | C = (1 - B / B.a) × (2 × A - A.a) 14 | D = B × (A.a - C) + (A ⊕ B) 15 | E = B × (A.a - C × (3 - 8 × B / B.a)) + (A ⊕ B) 16 | F = B × A.a + (√(B / B.a) × B.a - B) × (2 × A - A.a) + (A ⊕ B) 17 | >> {D if 2 × A < A.a, E if B × 8 ≤ B.a, F} 18 | %p VRI's Nile language for rendering and compositing 19 | #tcpip-parser< 20 | :preserve 21 | { structure-diagram } 22 | +-------------+----------+----------+-------------------+-------------------------------------------------+ 23 | \| 00 01 02 03 | 04 05 06 | 07 08 09 | 10 11 12 13 14 15 | 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | 24 | +-------------+----------+----------+-------------------+-------------------------------------------------+ 25 | \| sourcePort | destinationPort | 26 | +-------------------------------------------------------+-------------------------------------------------+ 27 | \| sequenceNumber | 28 | +---------------------------------------------------------------------------------------------------------+ 29 | \| acknowledgementNumber | 30 | +-------------+----------+----------+-------------------+-------------------------------------------------+ 31 | \| offset | reserved | ecn | controlBits | window | 32 | +-------------+----------+----------+-------------------+-------------------------------------------------+ 33 | \| checksum | urgentPointer | 34 | +-------------------------------------------------------+-------------------------------------------------+ 35 | tcp -- Transmission Control Protocol packet header [RFC 793] 36 | %p VRI's language for defining bit field accessors 37 | 38 | On the right are two examples from Alan Kay's Viewpoints Research Institute. 39 | The top one is a snippet of code in the Nile language for rendering and 40 | compositing. Below it, what looks like documentation is a valid program for 41 | encoding and decoding TCP headers: it defines accessors called tcp-sourcePort, 42 | tcp-destinationPort and so on. (The complete parser for this, and other 43 | ascii-art programs, is 77 lines of code.[[1]]) This second example may seem a 44 | bit gimmicky but I've included it to stimulate your imagination and to show 45 | just how different, and data-driven, these languages can be. 46 | 47 | What does this have to do with Emacs? Well, if you are frequently using dozens 48 | of different languages, perhaps even creating your own, you want an editor that 49 | is easily extensible. Programmable. At the core of Emacs is an interpreter for 50 | Emacs Lisp, a full-fledged programming language;[[2]] plus *excellent* integrated 51 | help, code navigation, and a debugger. Because the interpreter is embedded in 52 | Emacs itself, you can write your tools and customizations interactively; your 53 | changes take effect immediately. (If you are familiar with other interpreted 54 | languages you will already know and love the convenience of a Read-Eval-Print 55 | Loop.) The many Emacs libraries and APIs can be overwhelming, but Emacs Lisp 56 | itself is quite simple. 57 | 58 | %h2 Emacs vs. _____ 59 | 60 | “Writing an Eclipse or IntelliJ (or God help you, Visual Studio) plugin is a 61 | monumental effort, so almost nobody does it. This means there's no community of 62 | building and customizing your own tools [...]. Moreover, the effort to create a 63 | plugin is high enough that people only do it for really significant 64 | applications, whereas in Emacs a “plugin” can be any size at all, from a single 65 | line of code up through enormous systems and frameworks.”[[3]] 66 | 67 | Of course, there are many valid, reasonable reasons *not* to learn Emacs. If 68 | you program entirely or mostly in Java, Windows/.NET, or OS X/iOS, there are 69 | compelling reasons to use Eclipse/IntelliJ, Visual Studio, or XCode, 70 | respectively; you will certainly get a better out-of-the-box experience, with 71 | IntelliSense and other IDE features that just work, at the expense of 72 | extensibility. 73 | 74 | Or maybe you just abhor complexity in your tools: One of my early 75 | mentors, who to this day is one of the programmers I most respect, used nothing 76 | but dozens of Notepad and terminal windows open at once and an extra-wide 77 | taskbar along the left edge of the screen to tell them apart. True story. 78 | 79 | %h2 Some thoughts on longevity 80 | 81 | **...of your language:** Even if you don't buy the "dozens of domain-specific 82 | languages" idea, think about where you see yourself in 10 years. Will you still 83 | be writing programs exclusively in Java? In C++? 84 | 85 | **...of your editor:** GNU Emacs has been around for almost 30 years, and 86 | earlier versions for 10 years before that. It is open source (and [free]( 87 | http://www.gnu.org/philosophy/free-sw.html)) software, still under active 88 | development, with a large, talented community writing extensions for every new 89 | language imaginable. Can you expect the same longevity from TextMate or Sublime 90 | Text or whatever the web crowd is using these days? 91 | 92 | 93 | #footnotes 94 | [[1]]: 95 | The Nile code snippet was taken from [Gezira]( 96 | https://github.com/damelang/gezira/blob/master/nl/compositor.nl), a 2D 97 | vector graphics renderer. Nile and Gezira are described in the [Viewpoints 98 | Research Institute 2009 report]( 99 | http://www.vpri.org/pdf/tr2009016_steps09.pdf). 100 | The TCP/IP implementation is described in the [2007 report]( 101 | http://www.vpri.org/pdf/tr2007008_steps.pdf). The source code for [TCP frames 102 | is here]( 103 | http://piumarta.com/svn2/idst/trunk/function/examples/tcp/net-tcp.k) and the 104 | [ascii-art parser is here]( 105 | http://piumarta.com/svn2/idst/trunk/function/examples/tcp/structure.k). 106 | 107 | [[2]]: 108 | For some Lisp evangelism, read [Paul Graham]( 109 | http://www.paulgraham.com/avg.html). 110 | 111 | [[3]]: 112 | Steve Yegge, [*XEmacs is dead. Long live XEmacs!*]( 113 | http://steve-yegge.blogspot.com/2008/04/xemacs-is-dead-long-live-xemacs.html). 114 | Read all of Steve's Emacs articles for some equally conflicted (but much 115 | funnier) Emacs advocacy. 116 | -------------------------------------------------------------------------------- /customize_general.haml: -------------------------------------------------------------------------------- 1 | %h1 General customization 2 | 3 | %h2#ido ido-mode 4 | 5 | Other editors and IDEs have nice tree views of directories and files, as well 6 | as tabs for switching between buffers. Emacs does have a rather ugly tree 7 | view—`M-x speedbar` if you want to see *how* ugly—but the real Emacs answer 8 | to navigating large projects is `ido-mode`. 9 | 10 | .figure 11 | .titlebar< 12 | init.el 13 | .window< 14 | :preserve 15 | (ido-mode 1) 16 |   17 | .modeline< 18 | :preserve 19 | -U:--- init.el All L17 (Emacs-Lisp)---------------------------------------- 20 | .echoarea< 21 | Find file: \.../readline/ex{examples/ | histexpand.c | text.c} 22 | 23 | `ido-mode` remaps the keybindings for `find-file` and `switch-to-buffer` to 24 | more powerful versions of the same. You'll only need to type a few letters of 25 | the file or buffer name (not necessarily matching the beginning of the name, 26 | and not necessarily adjacent letters). A list of matches, in most-recently-used 27 | order, is displayed in the minibuffer; `` and `` (or `C-s` and 28 | `C-r`) navigate amongst the matches. If nothing matches, after a brief 29 | (and configurable) pause `ido` can search previously-used directories. 30 | 31 | Because `RET` opens the first matching file, to open a directory you'll have to 32 | use `C-d`. Or you could use `C-f` (at the `ido-find-file` prompt) to drop into 33 | normal `find-file`. 34 | 35 | `ido` ships with Emacs but isn't present at all in the manual; read the online 36 | help for the `ido-find-file` command. For more details and configuration 37 | instructions, use `C-h f ido-mode` to find its elisp implementation, and read 38 | the long comment at the top of the elisp file. 39 | 40 | Emacs users tend to leave buffers open when they have finished with them, and 41 | after a while have hundreds of buffers open so `ido-switch-buffer` effectively 42 | becomes "find file in project". 43 | 44 | To save your list of open files between invocations of Emacs, or to manage 45 | separate sets of open files (if you're working on several projects in 46 | parallel), see ["Saving Emacs Sessions"]( 47 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Saving-Emacs-Sessions.html) 48 | in the Emacs manual. 49 | 50 | 51 | %h2#minimalism Minimalism 52 | 53 | To make the most of your screen space, consider disabling the toolbar and 54 | scrollbars: 55 | 56 | .titlebar< 57 | init.el 58 | .window< 59 | :preserve 60 | (tool-bar-mode -1) 61 | (scroll-bar-mode -1) 62 | 63 | Similarly, you can disable the menu bar with `(menu-bar-mode -1)`, though I 64 | find the menu bar useful for discovering Emacs features; major and minor modes 65 | often add their own menu to the menu bar. As previously noted, you certainly 66 | shouldn't disable the menu bar on OS X; if you'd like to share your Emacs init 67 | file among several environments you could conditionally disable `menu-bar-mode` 68 | based on the value of variables `system-type` and `window-system`. 69 | 70 | Some commands like `revert-buffer` force you to confirm by typing `yes`; it 71 | would be nice to just type `y`. If you look at the definition of 72 | `revert-buffer` you'll find it calls `yes-or-no-p`, which we can redefine to 73 | call `y-or-n-p` instead: 74 | 75 | .window< 76 | :preserve 77 | (defun yes-or-no-p (prompt) 78 | (y-or-n-p prompt)) 79 | 80 | Or more simply: 81 | 82 | .window< 83 | :preserve 84 | (defalias 'yes-or-no-p 'y-or-n-p) 85 | 86 | Another thing everyone does the second they install Emacs is to prevent the 87 | creation of a "`~`"-suffixed backup file on every save: 88 | 89 | .window< 90 | :preserve 91 | (setq make-backup-files nil) 92 | 93 | Rely on your version control system for backups instead. 94 | 95 | 96 | %h2#elisp Navigating Emacs Lisp 97 | 98 | In the last couple of chapters I have encouraged you to discover Emacs 99 | functionality by studying the elisp code directly. To make the job easier we 100 | already saw `show-paren-mode` and `eldoc-mode`; let's enable them globally 101 | because they're useful in other programming languages too. 102 | 103 | .window< 104 | :preserve 105 | (show-paren-mode 1) 106 | (eldoc-mode 1) 107 | 108 | We'll also re-bind `M-.` from its default `find-tag` to 109 | `find-function-at-point`, but only for elisp files, for which you don't need a 110 | tags table because Emacs already knows all about every elisp function it has 111 | loaded. 112 | 113 | .window< 114 | :preserve 115 | (define-key emacs-lisp-mode-map 116 | (kbd "M-.") 'find-function-at-point) 117 | 118 | If you plan on *writing* a lot of Lisp, `paredit-mode` is great for always 119 | keeping your parentheses balanced, and for moving whole forms around when 120 | refactoring—but it does take some getting used to. 121 | 122 | 123 | %h2#shell shell 124 | 125 | If you ever tried to run a program like git under `M-x shell`, you will have 126 | come across the warning "terminal is not fully functional" followed by unusable 127 | behavior. This is because git sends its output through a pager (probably 128 | `less`), which requires a real terminal emulator. 129 | 130 | Setting the `PAGER` environment variable to `/bin/cat` (but only inside Emacs) 131 | solves this problem: 132 | 133 | .titlebar< 134 | init.el 135 | .window< 136 | :preserve 137 | (setenv "PAGER" "/bin/cat") 138 | 139 | This also allows you to use `git grep` from `M-x grep`. 140 | -# 141 | Make sure you don't override `PAGER` in your `~/.gitconfig` file or the 142 | `GIT_PAGER` environment variable (and `MANPAGER` for the `man` program, etc). 143 | 144 | If you need to make customizations in your `~/.bashrc` file (or the 145 | corresponding file for your shell of choice) you can test for the environment 146 | variable `INSIDE_EMACS`. To configure which shell Emacs uses, see [the manual]( 147 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Interactive-Shell.html). 148 | 149 | 150 | %h2#other Other ideas 151 | 152 | Other customizations you might like to make are covered by the Emacs manual: 153 | 154 | * [Minor Modes]( 155 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Minor-Modes.html). 156 | * [Making Buffer Names Unique]( 157 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Uniquify.html). 158 | * [Displaying The Cursor]( 159 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Cursor-Display.html) 160 | (in particular `global-hl-line-mode`). 161 | 162 | For further inspiration you might want to look at other people's init files, 163 | widely available on the [Emacs wiki]( 164 | http://www.emacswiki.org/emacs/CategoryDotEmacs) and on the [internet at 165 | large]( http://sites.google.com/site/steveyegge2/my-dot-emacs-file). Some of 166 | the customizations I have presented here came from the [Emacs Starter Kit]( 167 | http://github.com/technomancy/emacs-starter-kit), a collection of elisp files 168 | to provide "a more pleasant set of defaults than you get normally with Emacs". 169 | -------------------------------------------------------------------------------- /ergonomics.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | How to learn Emacs :: Ergonomics 7 | 8 | 9 | 10 | 11 | 54 |
    55 | 56 |

    Ergonomics

    57 |

    Most of the following advice relies heavily on the Control key, so bind your 58 | Caps Lock to Control. This is easy to do on OS X and Linux, and on 59 | Windows involves changing a registry entry.

    60 | 61 |

    You may choose to swap the left Control key with Caps Lock, or just to make 62 | them both Control keys — in Emacs and bash you can uppercase a word with M-u 63 | (upcase-word) and the region with C-x C-u (upcase-region).

    64 | 65 |

    Now you will find the navigation keys like C-f, C-b, C-n and C-p much 66 | closer to your home row position than the arrow keys. Learn to navigate in 67 | larger jumps with C-a and C-e (beggining and end of line), M-f and M-b 68 | (forward and back by one word), C-M-f and C-M-b (forward and back by one 69 | block of parentheses or braces), and M-a and M-e (beginning and end of a 70 | sentence or expression).

    71 | 72 |

    If you need to move to a far-away position it is often faster to get there by 73 | searching with C-s.

    74 | 75 |

    For fixing typos, C-t (transpose-chars) comes in handy.

    76 | 77 |

    Instead of reaching for the backspace key, consider rebinding C-h to 78 | backspace (as in most shells), and C-w to backward-kill-word (also as in most 79 | shells; in Emacs it is normally bound to C-backspace). C-d deletes the 80 | next character, and you don’t even need to bind it yourself.

    81 | 82 |

    Rebinding C-h is a bit tricky, because after making your binding you might 83 | activate some major or minor mode that binds a new sequence beginning with 84 | C-h, undoing your own binding. You can use key-translation-map to make 85 | C-h appear to Emacs as the backspace key, ignoring all other C-h bindings 86 | now or in future:

    87 |
    (define-key key-translation-map (kbd "C-h") (kbd "<DEL>"))
    88 |

    You will still be able to access the help commands with F1 f, F1 v, F1 S, 89 | etc.

    90 | 91 |

    As for C-w, you could define your own function that keeps the default 92 | behavior when the region is active, and does backward-kill-word when not:

    93 |
    (defun kill-region-or-backward-kill-word (&optional arg region) "`kill-region' if the region is active, otherwise `backward-kill-word'" (interactive (list (prefix-numeric-value current-prefix-arg) (use-region-p))) (if region (kill-region (region-beginning) (region-end)) (backward-kill-word arg))) (global-set-key (kbd "C-w") 'kill-region-or-backward-kill-word)
    94 |

    Some of these tips were inspired by Steve Yegge’s Effective Emacs article. Read it.

    95 | 96 |

    97 |
    98 | 99 | 100 | -------------------------------------------------------------------------------- /emacs.css: -------------------------------------------------------------------------------- 1 | /* Start with a blank slate */ 2 | html, body, div, p, ul, ol, h1, h2, h3 { margin: 0; padding: 0; border: 0; } 3 | 4 | /* === Layout === */ 5 | 6 | #content2 { max-width: 700px; margin: 50px 0 0 400px; } 7 | #sidebar { position: absolute; left: 50px; top: 50px; width: 300px; } 8 | .figure { float: right; clear: both; margin: 6px 0 18px 10px; } 9 | .figure.center { float: none; text-align: center; } 10 | .figure.first { margin-top: 18pt; } 11 | #footnotes { margin-top: 3em; } 12 | 13 | /* === Smartphones === */ 14 | /* (only tested on iPhone) */ 15 | @media only screen 16 | and (max-device-width: 480px) { 17 | #content2 { max-width: 100%; margin: 1em; } 18 | #sidebar { position: static; width: 100%; } 19 | #toc li ul { display: none; } 20 | } 21 | 22 | /* === Typography === */ 23 | 24 | body { font-family: verdana, helvetica, sans-serif; 25 | font-size: 12pt; line-height: 1.5; } 26 | 27 | h1, h2, h3 { font-family: georgia, "times new roman", serif; clear: both; } 28 | h1 { font-size: 18pt; line-height: 1; margin-bottom: 1em; } 29 | h2 { font-size: 14pt; line-height: 1.28; margin: 1.28em 0; } 30 | h3 { font-size: 12pt; line-height: 1.5; margin: 1.5em 0; } 31 | 32 | #sidebar, 33 | #sidebar a { color: #888; } 34 | #sidebar { font-size: 10pt; line-height: 1.8; } 35 | #info h1 { font-size: 12pt; line-height: 1.5; } 36 | #info p { margin: 0; } 37 | #toc { margin-top: 1.5em; } 38 | #toc ul { list-style: none; } 39 | #toc p { margin: .5em 0 0 0; font-style: italic; } 40 | #toc li.current { font-weight: bold; } 41 | #toc li.current ul { list-style: disc; font-weight: normal; margin-left: 3em; } 42 | 43 | p { margin: 1.5em 0; } 44 | 45 | a { color: #00007f; text-decoration: none; } 46 | a:hover { text-decoration: underline; } 47 | a.glossary { color: inherit; text-decoration: none; } 48 | a.glossary:hover, 49 | #first-key-sequence a.glossary { border-bottom: 1px dashed #888; } 50 | 51 | li { margin-left: 1.2em; } 52 | #toc li { margin: 0; } 53 | 54 | .figure p { font-size: 8pt; line-height: 1; font-weight: bold; 55 | margin: 0; text-align: center; } 56 | 57 | .footnote { font-size: 10pt; vertical-align: super; line-height: 1; 58 | font-family: verdana, helvetica, sans-serif; font-weight: normal; } 59 | #footnotes { font-size: 10pt; } 60 | #footnotes .footnote { vertical-align: baseline; } 61 | 62 | .next { text-align: right; clear: both; } 63 | .next a { color: #888; } 64 | 65 | /* === Instructions for the reader === */ 66 | .do { margin: 1.5em 0; padding: 0 1ex 0 35px; 67 | background: url("images/do.png") no-repeat 0 8px; } 68 | .do p { margin: .5em 0; } 69 | 70 | /* === Draw an emacs frame === */ 71 | .titlebar, 72 | .window, 73 | .modeline, 74 | .echoarea { position: relative; width: 559px; margin: 0 auto; 75 | background-repeat: no-repeat; overflow: hidden; 76 | font-family: Menlo, "DejaVu Sans Mono", "Bitstream Vera Sans Mono", monospace; 77 | font-size: 12px; line-height: 1.25; white-space: pre; } 78 | .titlebar { height: 23px; margin-top: 18pt; 79 | background-image: url("images/titlebar.png"); 80 | text-align: center; } 81 | .window { width: 535px; padding: 0 12px; 82 | background-image: url("images/window.png"); 83 | background-repeat: repeat-y; } 84 | .modeline { width: 554px; padding-left: 5px; height: 15px; 85 | background-image: url("images/modeline.png"); } 86 | .echoarea { height: 18px; margin-bottom: 18pt; 87 | background-image: url("images/echoarea.png"); } 88 | .titlebar p { margin: 5px 0 0 0; } 89 | .window p { text-align: left; /* Over-rides text-align:center when inside .figure */ 90 | margin: 0; } /* margin is provided by .window's padding, to 91 | support non-

    content generated by haml's 92 | :preserve filter. */ 93 | .modeline { text-align: left; } 94 | .echoarea p { text-align: left; margin: 1px 12px 0; } 95 | 96 | /* === Half-width emacs frame when shown as a floated figure === */ 97 | .figure .window, 98 | .figure .modeline, 99 | .figure .echoarea { text-align: left; } 100 | .figure .titlebar, 101 | .figure .echoarea { width: 260px; } 102 | .figure .window { width: 236px; } 103 | .figure .modeline { width: 255px; } 104 | .figure .titlebar { margin-top: 0; } 105 | .figure .echoarea { margin-bottom: 4pt; } 106 | .figure .titlebar p, 107 | .figure .window p, 108 | .figure .echoarea p { font-weight: normal; line-height: 1.25; } 109 | .figure .titlebar p { margin-left: 150px; } 110 | 111 | /* === Full-width emacs frame when shown as a floated figure === */ 112 | .figure.wide .titlebar, 113 | .figure.wide .echoarea { width: 320px; } 114 | .figure.wide .window { width: 296px; } 115 | .figure.wide .modeline { width: 315px; } 116 | 117 | /* === Font-lock colours === */ 118 | .window.default .comment { color: #b22; } 119 | .window.default .builtin { color: #738; } 120 | .window.default .keyword { color: #707; } 121 | .window.default .type { color: #282; } 122 | .window.default .variable-name { color: #952; } 123 | .window.default .function-name { color: #00f; } 124 | .window.default .string { color: #825; } 125 | .window.default .doc { color: #825; } 126 | .window .comment, 127 | .window.new-comment-face .comment { color: #3f7f5f; } 128 | .window .builtin { color: #004; } 129 | .window .keyword { color: #004; } 130 | .window .type { color: #000; } 131 | .window .variable-name { color: #000; font-weight: bold; } 132 | .window .function-name { color: #000; font-weight: bold; } 133 | .window .string { color: #505; } 134 | .window .doc { color: #505; } 135 | .window .region { background-color: #ed9; } 136 | .window .hl-line { background-color: #beb; } 137 | .window .cursor, 138 | .echoarea .cursor { background-color: #ccc; } 139 | .modeline .error { color: #f00; font-weight: bold; } 140 | .echoarea .prompt { color: #24d; } 141 | .echoarea .ido-first-match { font-weight: bold; } 142 | .window .bold { font-weight: bold; } 143 | .window .button { text-decoration: underline; } 144 | .window .underline { text-decoration: underline; } 145 | .window .comint-highlight-prompt { color: #008; } 146 | .window .compilation-error { color: #f00; font-weight: bold; } 147 | .window .compilation-line-number { color: #952; } 148 | .window .diff-header, 149 | .window .diff-hunk-header, 150 | .window .diff-function { background-color: #ccc; } 151 | .window .diff-file-header { background-color: #bbb; font-weight: bold; } 152 | .window .diff-context { color: #777; } 153 | .window .vc-annotate-face-3f3fff { color: #44f; background-color: #000; } 154 | .window .vc-annotate-face-56ff3f { color: #5f4; background-color: #000; } 155 | 156 | /* === why.html === */ 157 | #vri-examples { float: right; width: 300px; margin: 3pt 0 1em 2em; } 158 | #nile, 159 | #tcpip-parser { white-space: pre; 160 | overflow-x: auto; overflow-y: hidden; 161 | font-family: Menlo, "Bitstream Vera Sans Mono", monospace; 162 | font-size: 10pt; line-height: 1; } 163 | #tcpip-parser { font-size: 9pt; letter-spacing: -1pt; text-align: center; } 164 | #vri-examples p { white-space: normal; font-family: verdana, helvetica, sans-serif; 165 | font-size: 9pt; line-height: 1; font-weight: bold; 166 | text-align: center; margin-top: 0; } 167 | 168 | /* === tutorial.html === */ 169 | .modeline img.mouse { position: absolute; left: 400px; top: 0px; } 170 | td { vertical-align: bottom; padding-right: 1ex; } 171 | td:first-child { vertical-align: top; text-align: right; } 172 | td code { outline: 1px dotted #ccc; } 173 | 174 | /* === basic_c.html === */ 175 | .figure#minibuffer .echoarea, 176 | .notethis { border: #a00 2px solid; } 177 | .modeline .notethis { font-size: 80%; } /* so that top & bottom borders are visible */ 178 | 179 | /* === glossary.html === */ 180 | dt { margin-top: 1.5em; font-weight: bold; } 181 | dd { margin-left: 0; } 182 | dd p { margin-top: 0; } 183 | dl a { color: #888; font-size: 10pt; line-height: 1.8; } 184 | dl td { vertical-align: top; } 185 | dl td:first-child { white-space: nowrap; } 186 | #glossary-frames { margin-top: -18pt; } 187 | -------------------------------------------------------------------------------- /contribute_emacs.haml: -------------------------------------------------------------------------------- 1 | %h1 Contributing to Emacs 2 | 3 | Please consider contributing patches to Emacs, even if you're an Emacs novice. 4 | *Especially* if you're an Emacs novice--no-one is better qualified to judge the 5 | introductory documentation. Contribute *now*, before Stockholm syndrome sets 6 | in! 7 | 8 | 9 | %h2 Reporting a bug 10 | 11 | `M-x report-emacs-bug` will open a mail buffer with a template ready for you to 12 | fill with information. You probably haven't configured Emacs to be able to send 13 | email, but you can copy from this buffer and paste into your favorite email 14 | client. 15 | 16 | Do follow the instructions in that buffer. In particular, make sure you can 17 | reproduce the bug having run Emacs with `emacs -Q` (to confirm that it is a bug 18 | in Emacs itself and not in your customizations or in a third-party package). 19 | 20 | 21 | %h2 A simple documentation change 22 | 23 | The documentation for `ido-find-file` says: 24 | 25 | .titlebar< 26 | \\*Help* 27 | .window< 28 | :preserve 29 | C-j Select the current prompt as the buffer or file. 30 | If no buffer or file is found, prompt for a new one. 31 |   32 | .modeline< 33 | :preserve 34 | -U:%%- *Help* 32% L22 (Help View)----------------------------------------------- 35 | .echoarea< 36 |   37 | 38 | After reading that I still didn't know what `C-j` (at the `ido-find-file` 39 | prompt) actually does. It turns out to mean "use whatever you've typed 40 | verbatim" instead of using `ido`'s fuzzy matching. I'll submit a patch to the 41 | documentation string. 42 | 43 | 44 | %h2 Making a patch, the 1980s way 45 | 46 | .do 47 | `M-x find-function ido-find-file`. 48 | 49 | .do 50 | Save a copy of this buffer (with `C-x C-w`) to `~/.emacs.d/ido.el` and 51 | another copy to `~/.emacs.d/ido.el.orig`. 52 | 53 | .do 54 | Modify `~/.emacs.d/ido.el`. To test the change, evaluate (`C-M-x`) the 55 | `defun` form you changed. 56 | 57 | .do 58 | Generate a patch with `diff -cp ido.el.orig ido.el`.[[1]] 59 | 60 | .titlebar< 61 | ido.el.patch 62 | .window< 63 | :preserve 64 | *** ido.el.orig 2012-04-07 10:20:31.000000000 +0100 65 | --- ido.el 2012-04-07 10:28:59.000000000 +0100 66 | *************** (defun ido-switch-buffer () 67 | *** 4041,4048 **** 68 | RET Select the buffer at the front of the list of matches. If the 69 | list is empty, possibly prompt to create new buffer. 70 | 71 | ! \\[ido-select-text] Select the current prompt as the buffer. 72 | ! If no buffer is found, prompt for a new one. 73 | 74 | \\[ido-next-match] Put the first element at the end of the list. 75 | \\[ido-prev-match] Put the last element at the start of the list. 76 | --- 4041,4047 ---- 77 | RET Select the buffer at the front of the list of matches. If the 78 | list is empty, possibly prompt to create new buffer. 79 | 80 | ! \\[ido-select-text] Use the current input string verbatim. 81 | 82 | \\[ido-next-match] Put the first element at the end of the list. 83 | \\[ido-prev-match] Put the last element at the start of the list. 84 | *************** (defun ido-find-file () 85 | *** 4128,4135 **** 86 | RET Select the file at the front of the list of matches. If the 87 | list is empty, possibly prompt to create new file. 88 | 89 | ! \\[ido-select-text] Select the current prompt as the buffer or file. 90 | ! If no buffer or file is found, prompt for a new one. 91 | 92 | \\[ido-next-match] Put the first element at the end of the list. 93 | \\[ido-prev-match] Put the last element at the start of the list. 94 | --- 4127,4133 ---- 95 | RET Select the file at the front of the list of matches. If the 96 | list is empty, possibly prompt to create new file. 97 | 98 | ! \\[ido-select-text] Use the current input string verbatim. 99 | 100 | \\[ido-next-match] Put the first element at the end of the list. 101 | \\[ido-prev-match] Put the last element at the start of the list. 102 | 103 | .modeline< 104 | :preserve 105 | -U:--- ido.el.patch Top L1 (Diff)----------------------------------------------- 106 | .echoarea< 107 |   108 | 109 | 110 | %h2 Making a patch in the 21st century[[2]] 111 | 112 | Ideally you'd make the patch against the latest (unreleased) version of the 113 | Emacs source code, instead of version 24.1. Someone else might even have fixed 114 | your problem already! The Emacs source code is hosted at [savannah.gnu.org]( 115 | http://savannah.gnu.org/projects/emacs) and you can grab the source code from 116 | the official Bazaar repository: 117 | 118 | .do 119 | `bzr branch bzr://bzr.savannah.gnu.org/emacs/trunk` 120 | 121 | Or, if you prefer git, from the git mirror (which can [allegedly]( 122 | http://emacswiki.org/emacs/EmacsFromGit) be up to one day behind the Bazaar 123 | repo): 124 | 125 | .do 126 | `git clone git://git.savannah.gnu.org/emacs.git` 127 | 128 | Note that either one of the above commands will take quite a while, but you'll 129 | only do it once. I'll use git in the following instructions. 130 | 131 | .do 132 | Create a private (local) branch for your changes: 133 | `git checkout -b ido-el-documentation --track master` 134 | 135 | .do 136 | Make the change on the source files directly. Test. 137 | 138 | .do 139 | `git commit -am "* ido.el: Documentation for C-j in ido-find-file and ido-switch-buffer."` 140 | 141 | .do 142 | `git format-patch master` 143 | 144 | In future, before starting on another change you'll want to pull the latest 145 | changes from upstream: 146 | 147 | .do 148 | `git checkout master` 149 | `git pull --rebase`[[3]] 150 | 151 | 152 | %h2 Send the patch 153 | 154 | Send the patch to the same email address as `M-x report-emacs-bug`. But first 155 | read the [instructions for contributing to Emacs]( 156 | http://git.savannah.gnu.org/cgit/emacs.git/plain/etc/CONTRIBUTE) and the [Emacs 157 | Lisp tips and conventions]( 158 | http://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html). 159 | 160 | 161 | %h2 Contributing to third-party packages 162 | 163 | Try to find contribution guidelines on the package's website: Where to email 164 | your patch, the preferred formatting of the patch and its changelog message, 165 | etc. 166 | 167 | If the package is hosted on github, the package maintainers may be open to pull 168 | requests via github's interface. 169 | 170 | 171 | #footnotes 172 | [[1]]: 173 | Don't ask me why the Emacs maintainers don't like unified diffs (`diff -u`). 174 | They [specifically ask]( 175 | http://git.savannah.gnu.org/cgit/emacs.git/tree/etc/CONTRIBUTE?id=9771cd41#n103) 176 | for `diff -c`. 177 | 178 | [[2]]: 179 | The 21st century requires half a gig of disk space and a 30-minute download. 180 | 181 | [[3]]: 182 | The `--rebase` is to avoid complicated merges in the history if you have 183 | local un-pushed commits on the master branch. Though if you've followed these 184 | instructions, your local changes should only ever be on private branches, not 185 | on master. 186 | -------------------------------------------------------------------------------- /glossary.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | How to learn Emacs :: Glossary 7 | 8 | 9 | 10 | 11 |

    54 |
    55 | 56 |

    Glossary

    57 |
    58 |
    Emacs key names:
    59 |
    60 | 61 | 62 | 63 | 64 | 67 | 68 | 69 | 70 | 73 | 74 | 75 | 77 |
    C-x means Control-x.
    C-x C-s means Control-x, then Control-s.
    C-x k means Control-x, then k on its own (without Control).
    M-x means Alt-x (Alt is called Option on some Mac keyboards).
    65 | The M stands for “Meta” which is presumably what the Alt 66 | key was called in the 70s.
    M-x helpmeans press Alt-x, then type help, then press return.
    C-M-x means Control-Alt-x
    S-x means Shift-x
    s-x means Command-x (the ⌘ Command key on Mac keyboards).
    71 | The s stands for “Super”, from the days when keyboards 72 | had Meta, Super, and Hyper keys.
    <RET>means the Return or Enter key.
    <SPC>means the Space bar.
    <DEL>means Backspace
    76 | (not to be confused with the delete-forward key)
    78 |
    79 |
    Frames:
    80 |
    81 |
    82 |

    rl.c

    83 |
    int main (argc, argv) int argc; char **argv; { 
    84 |
    --:--- rl.c 59% L83 Git-master (C/l Abbrev)-----------------------------------
    85 |
    make -k rm -f rl.o gcc -DHAVE_CONFIG_H -DREADLINE_LIBRARY -DRL_LIBRARY_VERSION='"6.2"' -I. -I.. -I.. -g -O -c rl.c rl.c: In function ‘main’:
    86 |
    -U:%*- *compilation* Top L1 (Compilation:exit [2])-----------------------------------
    87 |

    Compilation exited abnormally with code 2

    88 |

    One frame, two windows
    (each with its own modeline)

    89 | 90 |
    91 |

    What Emacs calls your window-manager’s windows. [Emacs manual]

    92 |
    93 |
    Windows:
    94 |
    95 |

    Subdivisions inside a Frame. [Emacs manual]

    96 |
    97 |
    Buffers:
    98 |
    99 |

    The text you are editing. The difference between a buffer and a file is 100 | that their contents may differ until you save your changes; and some 101 | buffers aren’t backed by files at all (e.g. a *compilation* or *Help* 102 | buffer). [Emacs manual]

    103 |
    104 |
    Mode line:
    105 |
    106 |

    Describes the buffer in the window above the modeline. Hover your mouse 107 | over each indicator in the modeline for a description. [Emacs manual]

    108 |
    109 |
    Echo area:
    110 |
    111 |

    The line at the very bottom of the frame, used to display small informative 112 | messages. [Emacs manual]

    113 |
    114 |
    Minibuffer:
    115 |
    116 |

    The echo area when it is prompting for user input. [Emacs manual]

    117 |
    118 |
    The point, the mark and the region:
    119 |
    120 |

    The point is where the cursor is. Set the mark with C-<SPC>, move the 121 | point, and now the region is the area between point and mark. [Emacs 122 | manual]

    123 |
    124 |
    Killing and yanking:
    125 |
    126 |

    Killing = cutting. Yanking = pasting (sorry vi users!). [Emacs manual]

    127 |
    128 |
    Major mode or Editing mode:
    129 |
    130 |

    A major mode is a customization of Emacs for editing text of a particular 131 | sort (e.g. a particular programming language). A buffer can only have one 132 | major mode active at a time. [Emacs manual]

    133 |
    134 |
    Minor mode:
    135 |
    136 |

    Multiple minor modes can be enabled at once; they add functionality ranging 137 | from syntax highlighting to automatic spell-checking to modifying the 138 | behavior of common Emacs commands. [Emacs manual]

    139 |
    140 |
    141 | 142 | 143 |
    144 | 145 | 146 | -------------------------------------------------------------------------------- /tutorial.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | How to learn Emacs :: The very basics 7 | 8 | 9 | 10 | 11 | 54 |
    55 | 56 |

    The very basics

    57 |
    58 |

    Work through the Emacs tutorial: Start Emacs and press C-h t.

    59 |
    60 |

    If the tutorial seems a bit tedious, soldier on. It will only take you 30 61 | minutes, at most; and the material is essential for understanding Emacs. Most 62 | of the cursor movement and text manipulation keybindings you’ll learn will also 63 | work in the bash shell (or any program that uses the readline library) and, if 64 | you use OS X, even in the text fields of any native GUI application.

    65 | 66 |

    Do not proceed to the next chapter of this guide until you have read the entire 67 | tutorial, and you are comfortable with:

    68 | 69 | 70 | 71 | 72 | 74 | 76 | 77 | 78 | 79 | 80 | 85 | 86 |
    Visiting (opening) and saving files:C-x C-f and C-x C-s
    Switching between buffers: C-x b and C-x C-b
    Using the mark and the point
    73 | to set the region:     		C-SPC
    Killing (cutting) and 75 | yanking (pasting): C-w, C-k, C-y, M-y
    Searching forwards and backwards: C-s, C-r
    Invoking commands by name: M-x
    Undo: C-/
    Cancelling half-entered commands: C-g
    Getting help on editing modes,
    81 | keybindings and commands:
    82 | C-h m, C-h k, C-h f, C-h a
    83 | (just remember C-h and read
    84 | the prompt in the minibuffer)
    Quitting Emacs: C-x C-c
    87 |
    88 | 89 |
    90 |

    Don’t worry if you don’t remember every­thing from the tutorial. For now 91 | there’s no need to remember all the cursor move­ment keybindings; the arrow 92 | keys will do. If you forget the keys for visiting (opening) or saving a file, 93 | the File menu will remind you. Instead of remembering C-x 1 to remove other 94 | windows from the frame, you can use the mouse (hover over the right-hand side 95 | of the window’s modeline and read the help text in the echo area). I will ask 96 | you to re-read the entire tutorial in a month or so, to fill in the gaps; in 97 | the meantime, try to learn the keybindings instead of relying on the menus and 98 | the mouse.

    99 |

     

    100 |
    -U:--- *scratch* All L1 (Lisp Interaction)----------------------------------------------- 101 |
    102 |

    mouse-1: Select (drag to resize), mouse-2: Make current window occupy the whole frame, mouse-3: Remove current window from display

    103 |

    If you’re on a Mac running OS X, you’re in luck: Since you have separate Meta 104 | (alt/option), Control, and Command (⌘) keys on your keyboard, the latter is 105 | reserved for the standard OS keybindings. You can save with ⌘-s, copy with ⌘-c, 106 | paste with ⌘-v, and search with ⌘-f. Still, you should eventually learn the 107 | Emacs alternatives for all of the above, as they are much more powerful. In 108 | Emacs-speak the ⌘ key is called “super”, abbreviated to a lower-case “s”, as in 109 | s-f.

    110 | 111 |

    If you’re not on a Mac, resist the temptation to enable cua-mode. cua-mode 112 | rebinds keys like C-z, C-x, C-c, and C-v to their standard Windows 113 | meanings. cua-mode also changes the behavior of the region, so that using 114 | shift-arrow keys highlights text, and typing text replaces the active 115 | selection, as you’d expect in most other text editors. Get used to the Emacs 116 | way of doing these things.

    117 | 118 |

    119 |
    120 | 121 | 122 | -------------------------------------------------------------------------------- /why.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | How to learn Emacs :: Why Emacs 7 | 8 | 9 | 10 | 11 | 54 |
    55 | 56 |

    Why Emacs

    57 |

    I believe that the future of software development, if we are to survive 58 | ever-increasing complexity, lies in domain-specific languages that can express 59 | solutions measured in hundreds of lines of code, not the tens or hundreds of 60 | thousands of lines common in today’s software systems.

    61 |
    62 |
    CompositeSoftLight : Compositor ∀ (A, B) C = (1 - B / B.a) × (2 × A - A.a) D = B × (A.a - C) + (A ⊕ B) E = B × (A.a - C × (3 - 8 × B / B.a)) + (A ⊕ B) F = B × A.a + (√(B / B.a) × B.a - B) × (2 × A - A.a) + (A ⊕ B) >> {D if 2 × A < A.a, E if B × 8 ≤ B.a, F}
    63 |

    VRI's Nile language for rendering and compositing

    64 |
    { structure-diagram } +-------------+----------+----------+-------------------+-------------------------------------------------+ | 00 01 02 03 | 04 05 06 | 07 08 09 | 10 11 12 13 14 15 | 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | +-------------+----------+----------+-------------------+-------------------------------------------------+ | sourcePort | destinationPort | +-------------------------------------------------------+-------------------------------------------------+ | sequenceNumber | +---------------------------------------------------------------------------------------------------------+ | acknowledgementNumber | +-------------+----------+----------+-------------------+-------------------------------------------------+ | offset | reserved | ecn | controlBits | window | +-------------+----------+----------+-------------------+-------------------------------------------------+ | checksum | urgentPointer | +-------------------------------------------------------+-------------------------------------------------+ tcp -- Transmission Control Protocol packet header [RFC 793]
    65 |

    VRI's language for defining bit field accessors

    66 |
    67 |

    On the right are two examples from Alan Kay’s Viewpoints Research Institute. 68 | The top one is a snippet of code in the Nile language for rendering and 69 | compositing. Below it, what looks like documentation is a valid program for 70 | encoding and decoding TCP headers: it defines accessors called tcp-sourcePort, 71 | tcp-destinationPort and so on. (The complete parser for this, and other 72 | ascii-art programs, is 77 lines of code.[1]) This second example may seem a 73 | bit gimmicky but I’ve included it to stimulate your imagination and to show 74 | just how different, and data-driven, these languages can be.

    75 | 76 |

    What does this have to do with Emacs? Well, if you are frequently using dozens 77 | of different languages, perhaps even creating your own, you want an editor that 78 | is easily extensible. Programmable. At the core of Emacs is an interpreter for 79 | Emacs Lisp, a full-fledged programming language;[2] plus excellent integrated 80 | help, code navigation, and a debugger. Because the interpreter is embedded in 81 | Emacs itself, you can write your tools and customizations interactively; your 82 | changes take effect immediately. (If you are familiar with other interpreted 83 | languages you will already know and love the convenience of a Read-Eval-Print 84 | Loop.) The many Emacs libraries and APIs can be overwhelming, but Emacs Lisp 85 | itself is quite simple.

    86 |

    Emacs vs. _____

    87 |

    “Writing an Eclipse or IntelliJ (or God help you, Visual Studio) plugin is a 88 | monumental effort, so almost nobody does it. This means there’s no community of 89 | building and customizing your own tools […]. Moreover, the effort to create a 90 | plugin is high enough that people only do it for really significant 91 | applications, whereas in Emacs a “plugin” can be any size at all, from a single 92 | line of code up through enormous systems and frameworks.”[3]

    93 | 94 |

    Of course, there are many valid, reasonable reasons not to learn Emacs. If 95 | you program entirely or mostly in Java, Windows/.NET, or OS X/iOS, there are 96 | compelling reasons to use Eclipse/IntelliJ, Visual Studio, or XCode, 97 | respectively; you will certainly get a better out-of-the-box experience, with 98 | IntelliSense and other IDE features that just work, at the expense of 99 | extensibility.

    100 | 101 |

    Or maybe you just abhor complexity in your tools: One of my early 102 | mentors, who to this day is one of the programmers I most respect, used nothing 103 | but dozens of Notepad and terminal windows open at once and an extra-wide 104 | taskbar along the left edge of the screen to tell them apart. True story.

    105 |

    Some thoughts on longevity

    106 |

    …of your language: Even if you don’t buy the “dozens of domain-specific 107 | languages” idea, think about where you see yourself in 10 years. Will you still 108 | be writing programs exclusively in Java? In C++?

    109 | 110 |

    …of your editor: GNU Emacs has been around for almost 30 years, and 111 | earlier versions for 10 years before that. It is open source (and free) software, still under active 112 | development, with a large, talented community writing extensions for every new 113 | language imaginable. Can you expect the same longevity from TextMate or Sublime 114 | Text or whatever the web crowd is using these days?

    115 |
    116 |

    [1]: 117 | The Nile code snippet was taken from Gezira, a 2D 118 | vector graphics renderer. Nile and Gezira are described in the Viewpoints 119 | Research Institute 2009 report.
    120 | The TCP/IP implementation is described in the 2007 report. The source code for TCP frames 121 | is here and the 122 | ascii-art parser is here.

    123 | 124 |

    [2]: 125 | For some Lisp evangelism, read Paul Graham.

    126 | 127 |

    [3]: 128 | Steve Yegge, XEmacs is dead. Long live XEmacs!. 129 | Read all of Steve’s Emacs articles for some equally conflicted (but much 130 | funnier) Emacs advocacy.

    131 |
    132 | 133 |

    134 |
    135 | 136 | 137 | -------------------------------------------------------------------------------- /customize_general.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | How to learn Emacs :: General customization 7 | 8 | 9 | 10 | 11 | 62 |
    63 | 64 |

    General customization

    65 |

    ido-mode

    66 |

    Other editors and IDEs have nice tree views of directories and files, as well 67 | as tabs for switching between buffers. Emacs does have a rather ugly tree 68 | view—M-x speedbar if you want to see how ugly—but the real Emacs answer 69 | to navigating large projects is ido-mode.

    70 |
    71 |

    init.el

    72 |
    (ido-mode 1)  
    73 |
    -U:--- init.el All L17 (Emacs-Lisp)----------------------------------------
    74 |

    Find file: .../readline/ex{examples/ | histexpand.c | text.c}

    75 |
    76 |

    ido-mode remaps the keybindings for find-file and switch-to-buffer to 77 | more powerful versions of the same. You’ll only need to type a few letters of 78 | the file or buffer name (not necessarily matching the beginning of the name, 79 | and not necessarily adjacent letters). A list of matches, in most-recently-used 80 | order, is displayed in the minibuffer; <right> and <left> (or C-s and 81 | C-r) navigate amongst the matches. If nothing matches, after a brief 82 | (and configurable) pause ido can search previously-used directories.

    83 | 84 |

    Because RET opens the first matching file, to open a directory you’ll have to 85 | use C-d. Or you could use C-f (at the ido-find-file prompt) to drop into 86 | normal find-file.

    87 | 88 |

    ido ships with Emacs but isn’t present at all in the manual; read the online 89 | help for the ido-find-file command. For more details and configuration 90 | instructions, use C-h f ido-mode to find its elisp implementation, and read 91 | the long comment at the top of the elisp file.

    92 | 93 |

    Emacs users tend to leave buffers open when they have finished with them, and 94 | after a while have hundreds of buffers open so ido-switch-buffer effectively 95 | becomes “find file in project”.

    96 | 97 |

    To save your list of open files between invocations of Emacs, or to manage 98 | separate sets of open files (if you’re working on several projects in 99 | parallel), see “Saving Emacs Sessions” 100 | in the Emacs manual.

    101 |

    Minimalism

    102 |

    To make the most of your screen space, consider disabling the toolbar and 103 | scrollbars:

    104 |

    init.el

    105 |
    (tool-bar-mode -1) (scroll-bar-mode -1)
    106 |

    Similarly, you can disable the menu bar with (menu-bar-mode -1), though I 107 | find the menu bar useful for discovering Emacs features; major and minor modes 108 | often add their own menu to the menu bar. As previously noted, you certainly 109 | shouldn’t disable the menu bar on OS X; if you’d like to share your Emacs init 110 | file among several environments you could conditionally disable menu-bar-mode 111 | based on the value of variables system-type and window-system.

    112 | 113 |

    Some commands like revert-buffer force you to confirm by typing yes; it 114 | would be nice to just type y. If you look at the definition of 115 | revert-buffer you’ll find it calls yes-or-no-p, which we can redefine to 116 | call y-or-n-p instead:

    117 |
    (defun yes-or-no-p (prompt) (y-or-n-p prompt))
    118 |

    Or more simply:

    119 |
    (defalias 'yes-or-no-p 'y-or-n-p)
    120 |

    Another thing everyone does the second they install Emacs is to prevent the 121 | creation of a “~”-suffixed backup file on every save:

    122 |
    (setq make-backup-files nil)
    123 |

    Rely on your version control system for backups instead.

    124 |

    Navigating Emacs Lisp

    125 |

    In the last couple of chapters I have encouraged you to discover Emacs 126 | functionality by studying the elisp code directly. To make the job easier we 127 | already saw show-paren-mode and eldoc-mode; let’s enable them globally 128 | because they’re useful in other programming languages too.

    129 |
    (show-paren-mode 1) (eldoc-mode 1)
    130 |

    We’ll also re-bind M-. from its default find-tag to 131 | find-function-at-point, but only for elisp files, for which you don’t need a 132 | tags table because Emacs already knows all about every elisp function it has 133 | loaded.

    134 |
    (define-key emacs-lisp-mode-map (kbd "M-.") 'find-function-at-point)
    135 |

    If you plan on writing a lot of Lisp, paredit-mode is great for always 136 | keeping your parentheses balanced, and for moving whole forms around when 137 | refactoring—but it does take some getting used to.

    138 |

    shell

    139 |

    If you ever tried to run a program like git under M-x shell, you will have 140 | come across the warning “terminal is not fully functional” followed by unusable 141 | behavior. This is because git sends its output through a pager (probably 142 | less), which requires a real terminal emulator.

    143 | 144 |

    Setting the PAGER environment variable to /bin/cat (but only inside Emacs) 145 | solves this problem:

    146 |

    init.el

    147 |
    (setenv "PAGER" "/bin/cat")
    148 |

    This also allows you to use git grep from M-x grep.

    149 |

    Make sure you don’t override PAGER in your ~/.gitconfig file or the 150 | GIT_PAGER environment variable (and MANPAGER for the man program, etc).

    151 | 152 |

    If you need to make customizations in your ~/.bashrc file (or the 153 | corresponding file for your shell of choice) you can test for the environment 154 | variable INSIDE_EMACS. To configure which shell Emacs uses, see the manual.

    155 |

    Other ideas

    156 |

    Other customizations you might like to make are covered by the Emacs manual:

    157 | 158 | 164 | 165 | 166 |

    For further inspiration you might want to look at other people’s init files, 167 | widely available on the Emacs wiki and on the internet at 168 | large. Some of 169 | the customizations I have presented here came from the Emacs Starter Kit, a collection of elisp files 170 | to provide “a more pleasant set of defaults than you get normally with Emacs”.

    171 | 172 |

    173 |
    174 | 175 | 176 | -------------------------------------------------------------------------------- /contribute_emacs.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | How to learn Emacs :: Contributing to Emacs 7 | 8 | 9 | 10 | 11 | 54 |
    55 | 56 |

    Contributing to Emacs

    57 |

    Please consider contributing patches to Emacs, even if you’re an Emacs novice. 58 | Especially if you’re an Emacs novice—no-one is better qualified to judge the 59 | introductory documentation. Contribute now, before Stockholm syndrome sets 60 | in!

    61 |

    Reporting a bug

    62 |

    M-x report-emacs-bug will open a mail buffer with a template ready for you to 63 | fill with information. You probably haven’t configured Emacs to be able to send 64 | email, but you can copy from this buffer and paste into your favorite email 65 | client.

    66 | 67 |

    Do follow the instructions in that buffer. In particular, make sure you can 68 | reproduce the bug having run Emacs with emacs -Q (to confirm that it is a bug 69 | in Emacs itself and not in your customizations or in a third-party package).

    70 |

    A simple documentation change

    71 |

    The documentation for ido-find-file says:

    72 |

    *Help*

    73 |
    C-j Select the current prompt as the buffer or file. If no buffer or file is found, prompt for a new one.  
    74 |
    -U:%%- *Help* 32% L22 (Help View)-----------------------------------------------
    75 |

     

    76 |

    After reading that I still didn’t know what C-j (at the ido-find-file 77 | prompt) actually does. It turns out to mean “use whatever you’ve typed 78 | verbatim” instead of using ido’s fuzzy matching. I’ll submit a patch to the 79 | documentation string.

    80 |

    Making a patch, the 1980s way

    81 | 82 |
    83 |

    M-x find-function ido-find-file.

    84 |
    85 |
    86 |

    Save a copy of this buffer (with C-x C-w) to ~/.emacs.d/ido.el and 87 | another copy to ~/.emacs.d/ido.el.orig.

    88 |
    89 |
    90 |

    Modify ~/.emacs.d/ido.el. To test the change, evaluate (C-M-x) the 91 | defun form you changed.

    92 |
    93 |
    94 |

    Generate a patch with diff -cp ido.el.orig ido.el.[1]

    95 |
    96 |

    ido.el.patch

    97 |
    *** ido.el.orig 2012-04-07 10:20:31.000000000 +0100 --- ido.el 2012-04-07 10:28:59.000000000 +0100 *************** (defun ido-switch-buffer () *** 4041,4048 **** RET Select the buffer at the front of the list of matches. If the list is empty, possibly prompt to create new buffer. ! \\[ido-select-text] Select the current prompt as the buffer. ! If no buffer is found, prompt for a new one. \\[ido-next-match] Put the first element at the end of the list. \\[ido-prev-match] Put the last element at the start of the list. --- 4041,4047 ---- RET Select the buffer at the front of the list of matches. If the list is empty, possibly prompt to create new buffer. ! \\[ido-select-text] Use the current input string verbatim. \\[ido-next-match] Put the first element at the end of the list. \\[ido-prev-match] Put the last element at the start of the list. *************** (defun ido-find-file () *** 4128,4135 **** RET Select the file at the front of the list of matches. If the list is empty, possibly prompt to create new file. ! \\[ido-select-text] Select the current prompt as the buffer or file. ! If no buffer or file is found, prompt for a new one. \\[ido-next-match] Put the first element at the end of the list. \\[ido-prev-match] Put the last element at the start of the list. --- 4127,4133 ---- RET Select the file at the front of the list of matches. If the list is empty, possibly prompt to create new file. ! \\[ido-select-text] Use the current input string verbatim. \\[ido-next-match] Put the first element at the end of the list. \\[ido-prev-match] Put the last element at the start of the list.
    98 |
    -U:--- ido.el.patch Top L1 (Diff)-----------------------------------------------
    99 |

     

    100 |

    Making a patch in the 21st century[2]

    101 |

    Ideally you’d make the patch against the latest (unreleased) version of the 102 | Emacs source code, instead of version 24.1. Someone else might even have fixed 103 | your problem already! The Emacs source code is hosted at savannah.gnu.org and you can grab the source code from 104 | the official Bazaar repository:

    105 |
    106 |

    bzr branch bzr://bzr.savannah.gnu.org/emacs/trunk

    107 |
    108 |

    Or, if you prefer git, from the git mirror (which can allegedly be up to one day behind the Bazaar 109 | repo):

    110 |
    111 |

    git clone git://git.savannah.gnu.org/emacs.git

    112 |
    113 |

    Note that either one of the above commands will take quite a while, but you’ll 114 | only do it once. I’ll use git in the following instructions.

    115 |
    116 |

    Create a private (local) branch for your changes:
    117 | git checkout -b ido-el-documentation --track master

    118 |
    119 |
    120 |

    Make the change on the source files directly. Test.

    121 |
    122 |
    123 |

    git commit -am "* ido.el: Documentation for C-j in ido-find-file and ido-switch-buffer."

    124 |
    125 |
    126 |

    git format-patch master

    127 |
    128 |

    In future, before starting on another change you’ll want to pull the latest 129 | changes from upstream:

    130 |
    131 |

    git checkout master
    132 | git pull --rebase[3]

    133 |
    134 |

    Send the patch

    135 |

    Send the patch to the same email address as M-x report-emacs-bug. But first 136 | read the instructions for contributing to Emacs and the Emacs 137 | Lisp tips and conventions.

    138 |

    Contributing to third-party packages

    139 |

    Try to find contribution guidelines on the package’s website: Where to email 140 | your patch, the preferred formatting of the patch and its changelog message, 141 | etc.

    142 | 143 |

    If the package is hosted on github, the package maintainers may be open to pull 144 | requests via github’s interface.

    145 |
    146 |

    [1]: 147 | Don’t ask me why the Emacs maintainers don’t like unified diffs (diff -u). 148 | They specifically ask 149 | for diff -c.

    150 | 151 |

    [2]: 152 | The 21st century requires half a gig of disk space and a 30-minute download.

    153 | 154 |

    [3]: 155 | The --rebase is to avoid complicated merges in the history if you have 156 | local un-pushed commits on the master branch. Though if you’ve followed these 157 | instructions, your local changes should only ever be on private branches, not 158 | on master.

    159 |
    160 | 161 |

    162 |
    163 | 164 | 165 | -------------------------------------------------------------------------------- /customize_colors.haml: -------------------------------------------------------------------------------- 1 | %h1 Fix that awful color scheme 2 | 3 | The default Emacs color scheme is affectionately known as "angry fruit salad". 4 | 5 | %h2#default Default font 6 | 7 | ["Fonts" in the Emacs manual]( 8 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Fonts.html)[[1]] says: 9 | 10 | .do 11 | Click on 'Set Default Font' in the 'Options' menu. To save this for future 12 | sessions, click on 'Save Options' in the 'Options' menu.[[2]] 13 | 14 | "DejaVu Sans Mono" is a good choice (also known as "Bitstream Vera Sans Mono", 15 | or "Menlo" on OS X 10.6+). Do choose a fixed-width font, even if you like 16 | proportional fonts for programming. We'll cover Emacs's handling of 17 | proportional fonts later. 18 | 19 | The "Save Options" menu command automatically modified your init file with the 20 | new settings (and told you so in the echo area, now in the `*Messages*` buffer 21 | if you missed it). 22 | 23 | There is a [known bug]( http://debbugs.gnu.org/cgi/bugreport.cgi?bug=2845) on 24 | OS X that prevents "Save Options" from saving changes to the default font. OS X 25 | users will have to use the `customize-face` mechanism I explain below, 26 | specifying `default` as the face name. 27 | 28 | 29 | %h2#colors Syntax highlighting colors 30 | 31 | [Font Lock mode]( 32 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Font-Lock.html) is the 33 | minor mode responsible for syntax highlighting. You can read up on font-lock 34 | mode if you want to figure out how Emacs decides what is a comment or a keyword 35 | or a variable, or how to add your own keywords. 36 | 37 | But to merely change the colors: 38 | 39 | .do 40 | Figure out the name of the face you want to change: `describe-face` (defaults 41 | to the face at point) or `list-faces-display`. 42 | 43 | .do 44 | `modify-face` will prompt you for a face and for each attribute to change. 45 | Leave attributes as "unspecified" (the default) to inherit from the default 46 | face. When it comes to the foreground and background colors, you can use the 47 | predefined colors shown by tab-completion, or you can specify RGB hex values 48 | like `#3f7f5f`. 49 | 50 | .do 51 | `customize-face` brings up the "easy customization" interface I warned you 52 | against in the previous chapter. Click the `State` button and select `Save 53 | for Future Sessions`. (You can make changes here too, but I prefer 54 | `modify-face` because it gives you tab-completion on the possible values for 55 | each attribute.) 56 | 57 | Apart from `describe-face`, which I found in the Help menu, I found all these 58 | in the Emacs manual under ["Faces"]( 59 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Faces.html), 60 | ["Standard Faces"]( 61 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Standard-Faces.html) 62 | and ["Customizing Faces"]( 63 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Face-Customization.html). 64 | 65 | Now let's figure out how to bypass the "easy customization" interface: 66 | 67 | .do 68 | Visit your init file to see what "easy customization" added. If you already 69 | had the file open, you may need `revert-buffer` to see the latest changes. 70 | 71 | .titlebar< 72 | init.el 73 | .window.default.new-comment-face< 74 | :preserve 75 | (custom-set-variables 76 | ;; custom-set-variables was added by Custom. 77 | ;; If you edit it by hand, you could mess it up, so be careful. 78 | ;; Your init file should contain only one such instance. 79 | ;; If there is more than one, they won't work right. 80 | ) 81 | (custom-set-faces 82 | ;; custom-set-faces was added by Custom. 83 | ;; If you edit it by hand, you could mess it up, so be careful. 84 | ;; Your init file should contain only one such instance. 85 | ;; If there is more than one, they won't work right. 86 | '(default ((t (:height 120 :family "Menlo")))) 87 | '(font-lock-comment-face ((t (:foreground "#3f7f5f"))))) 88 | 89 | 90 | You could configure the remaining font-lock faces by adding arguments to the 91 | `custom-set-faces` form, but they might be overwritten if you use the easy 92 | customization framework in future. Inspired by the name `custom-set-faces`, I 93 | searched for functions beginning with `set-face` and found 94 | `set-face-attribute`: 95 | 96 | .window< 97 | :preserve 98 | (set-face-attribute 'default nil :family "Menlo" :height 120) 99 | (set-face-attribute 'font-lock-comment-face nil :foreground "#3f7f5f") 100 | (set-face-attribute 'font-lock-string-face nil :foreground "#4f004f") 101 | (set-face-attribute 'font-lock-constant-face nil :foreground "#4f004f") 102 | (set-face-attribute 'font-lock-keyword-face nil :foreground "#00003f") 103 | (set-face-attribute 'font-lock-builtin-face nil :foreground "#00003f") 104 | (set-face-attribute 'font-lock-type-face nil :foreground "#000000") 105 | (set-face-attribute 'font-lock-function-name-face nil 106 | :foreground "#000000" :weight 'bold) 107 | (set-face-attribute 'font-lock-variable-name-face nil 108 | :foreground "#000000" :weight 'bold) 109 | 110 | The above settings produce a very conservative dark-on-white color scheme. I 111 | like it because in many languages it highlights variable and function 112 | *definitions* but not their uses. 113 | 114 | For all the face attribute names see ["Face Attributes"]( 115 | http://www.gnu.org/software/emacs/manual/html_node/elisp/Face-Attributes.html) 116 | in the Emacs Lisp manual. As to elisp syntax, [keyword symbols]( 117 | http://www.gnu.org/software/emacs/manual/html_node/elisp/Symbol-Type.html) like 118 | `:foreground` and `:weight` are constants (that evaluate to themselves so you 119 | don't have to quote them). 120 | 121 | 122 | %h2#diff diff-mode 123 | 124 | While we're on colors, let's add some helpful coloring to `diff-mode` (which 125 | we came across earlier, in the section on the `vc` version control 126 | interface).[[4]] 127 | 128 | .do 129 | .titlebar< 130 | init.el 131 | .window< 132 | :preserve 133 | (eval-after-load 'diff-mode 134 | '(progn 135 | (set-face-foreground 'diff-added "green4") 136 | (set-face-foreground 'diff-removed "red3"))) 137 | 138 | `eval-after-load` does what it says: The first time `diff-mode` is loaded, 139 | evaluate the following form. Emacs tends not to load every elisp package on 140 | startup, but waits until you actually *use* `diff-mode` to load it. 141 | 142 | If you used `(set-face-foreground 'diff-added ...)` directly in your init file, 143 | you would get the error "invalid face diff-added". You could explicitly load 144 | `diff-mode` (using `require`) in your init file, but that would increase 145 | Emacs's startup time—ever so slightly—every time you run Emacs in the 146 | terminal for a quick job that won't even use `diff-mode`. 147 | 148 | `eval-after-load` takes a single form to evaluate, but we want to make two 149 | function calls, so we wrap them in `progn` which merely evaluates a bunch of 150 | forms sequentially. We quote it so that it doesn't get evaluated right now, 151 | before even being passed to `eval-after-load`. 152 | 153 | .figure 154 | .titlebar< 155 | diff-mode.el.gz 156 | .window< 157 | :preserve 158 |   159 | ;; provide the package 160 | (provide 'diff-mode) 161 | 162 | The first argument to `eval-after-load` has to match the name that the package 163 | `provide`s (this usually matches the name of the command to enable the mode, 164 | but to double-check: `C-h f diff-mode`, follow the link to `diff-mode.el.gz`, 165 | and find the `provide` form near the bottom). 166 | 167 | 168 | %h2#themes Color themes 169 | 170 | *Note: This section and the next, which deal with the `color-theme` package, 171 | were written for Emacs 23. `color-theme` is obsolete in Emacs 24, so I need 172 | to find a better example for installing third-party packages.* 173 | 174 | Maybe you already have a favourite color theme, like [Zenburn]( 175 | http://slinky.imukuppi.org/zenburnpage/) or [Solarized]( 176 | http://ethanschoonover.com/solarized). There are Emacs implementations 177 | ([Zenburn]( https://github.com/bbatsov/zenburn-emacs), [Solarized]( 178 | https://github.com/sellout/emacs-color-theme-solarized)) built on top of the 179 | [`color-theme`]( http://www.nongnu.org/color-theme/) minor mode. `color-theme` 180 | is a third-party package; it doesn't come with Emacs. 181 | 182 | Note that Emacs 24 provides a built-in mechanism for defining multiple color 183 | themes. Nevertheless, I'll walk you through the process of installing 184 | third-party packages using `color-theme` and the Solarized theme as examples. 185 | 186 | Emacs 24 also comes with a package management system, so--as long as the 187 | package's author has taken advantage of the new mechanism--the manual 188 | installation procedure described below will not be necessary either. 189 | 190 | 191 | %h2#packages Installing third-party elisp packages 192 | 193 | I'll assume that you are keeping your `~/.emacs.d` under version control using 194 | git.[[3]] 195 | 196 | `color-theme`'s [installation instructions]( 197 | http://www.nongnu.org/color-theme/#sec5) recommend using your package manager 198 | (`apt-get install emacs-goodies-el` or `port install color-theme-mode.el`, 199 | etc.) but I prefer to manage all my Emacs extensions in a single place. That 200 | place is my `~/.emacs.d` directory, because I will eventually want an extension 201 | that isn't provided by my system's package manager. 202 | 203 | .do 204 | Download the [color-theme.6.6.0.tar.gz]( 205 | http://download.savannah.nongnu.org/releases/color-theme/) and extract into 206 | `~/.emacs.d`. 207 | 208 | `git add color-theme.6.6.0;` 209 | `git commit -m "color-theme 6.6.0 from http://www.nongnu.org/color-theme/";` 210 | 211 | .do 212 | Add the color-theme directory to your Emacs `load-path`: 213 | -# 214 | .titlebar< 215 | init.el 216 | .window< 217 | :preserve 218 | (add-to-list 'load-path "~/.emacs.d/color-theme-6.6.0") 219 | 220 | .do 221 | And actually load it: 222 | -# 223 | .window< 224 | :preserve 225 | (require 'color-theme) 226 | 227 | Now you can select a theme with `color-theme-select`. 228 | 229 | 230 | %h2#github Installing packages from github 231 | 232 | The Solarized color theme for Emacs is [available on github]( 233 | https://github.com/sellout/emacs-color-theme-solarized). If you are keeping 234 | your `~/.emacs.d` under version control using git, you can use git submodules 235 | to simplify the management of such third-party packages. 236 | 237 | .do 238 | `cd ~/.emacs.d;` 239 | `git submodule add https://github.com/sellout/emacs-color-theme-solarized.git;` 240 | 241 | In future you can use `git pull` from `~/.emacs.d/emacs-color-theme-solarized/` 242 | to get the latest changes. 243 | 244 | .do 245 | Add `~/.emacs.d/emacs-color-theme-solarized/` to your Emacs `load-path`, and 246 | require `'color-theme-solarized`, as you did for the `color-theme` package. 247 | 248 | Now you can activate the theme with `color-theme-solarized-light` (or `-dark`). 249 | 250 | 251 | %h2#size Increasing the font size 252 | 253 | `C-x C-+`, `C-x C--`, and `C-x C-0`. See ["Temporary Face Changes"]( 254 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Temporary-Face-Changes.html). 255 | 256 | 257 | %h2#variable-pitch variable-pitch-mode 258 | 259 | You can toggle between fixed- and variable-width fonts in a particular buffer 260 | with `variable-pitch-mode`. The face to customize is `variable-pitch`. 261 | 262 | To automatically enable `variable-pitch-mode`, add it to the hooks for all the 263 | major modes where you want it to take effect. For example, to `text-mode-hook` 264 | for editing plain text. 265 | 266 | If you really want it *everywhere*, I suppose there's no harm in setting the 267 | `default` face to a proportional font. The great advantage of 268 | `variable-pitch-mode`, though, is that it is so easy to switch between 269 | proportional- and fixed-width fonts when you come across some ascii art or an 270 | ascii table in a comment. 271 | 272 | 273 | #footnotes 274 | [[1]]: 275 | I found this—after some dead ends—with Info's `i`ndex command, typing 276 | "font", tab-completing, and trying whatever looked promising. I could just 277 | have explored the Options menu instead, but—silly me—I had disabled the 278 | menus because people on the internet said "real Emacs power users disable the 279 | menus." That might make sense on a text terminal, where you can't click the 280 | menu anyway, but on OS X, where there's only one menu bar at the top of the 281 | screen, it's just silly. See the next footnote. 282 | 283 | [[2]]: 284 | If you have disabled the menu, perhaps because you're using an init file 285 | copied from someone else or something like the [Emacs starter kit]( 286 | http://github.com/technomancy/emacs-starter-kit), you can re-enable it just 287 | for this session with `M-x menu-bar-mode`. 288 | 289 | [[3]]: 290 | `cd ~/.emacs.d; git init .; git add init.el; git status; git diff --cached;` 291 | `git commit -m "My emacs init file."` 292 | 293 | [[4]]: 294 | This customization—with several others—is borrowed from the [Emacs 295 | Starter Kit]( https://github.com/technomancy/emacs-starter-kit). 296 | -------------------------------------------------------------------------------- /customize_colors.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | How to learn Emacs :: Fix that awful color scheme 7 | 8 | 9 | 10 | 11 | 65 |
    66 | 67 |

    Fix that awful color scheme

    68 |

    The default Emacs color scheme is affectionately known as “angry fruit salad”.

    69 |

    Default font

    70 |

    “Fonts” in the Emacs manual[1] says:

    71 |
    72 |

    Click on ‘Set Default Font’ in the ‘Options’ menu. To save this for future 73 | sessions, click on ‘Save Options’ in the ‘Options’ menu.[2]

    74 |
    75 |

    “DejaVu Sans Mono” is a good choice (also known as “Bitstream Vera Sans Mono”, 76 | or “Menlo” on OS X 10.6+). Do choose a fixed-width font, even if you like 77 | proportional fonts for programming. We’ll cover Emacs’s handling of 78 | proportional fonts later.

    79 | 80 |

    The “Save Options” menu command automatically modified your init file with the 81 | new settings (and told you so in the echo area, now in the *Messages* buffer 82 | if you missed it).

    83 | 84 |

    There is a known bug on 85 | OS X that prevents “Save Options” from saving changes to the default font. OS X 86 | users will have to use the customize-face mechanism I explain below, 87 | specifying default as the face name.

    88 |

    Syntax highlighting colors

    89 |

    Font Lock mode is the 90 | minor mode responsible for syntax highlighting. You can read up on font-lock 91 | mode if you want to figure out how Emacs decides what is a comment or a keyword 92 | or a variable, or how to add your own keywords.

    93 | 94 |

    But to merely change the colors:

    95 |
    96 |

    Figure out the name of the face you want to change: describe-face (defaults 97 | to the face at point) or list-faces-display.

    98 |
    99 |
    100 |

    modify-face will prompt you for a face and for each attribute to change. 101 | Leave attributes as “unspecified” (the default) to inherit from the default 102 | face. When it comes to the foreground and background colors, you can use the 103 | predefined colors shown by tab-completion, or you can specify RGB hex values 104 | like #3f7f5f.

    105 |
    106 |
    107 |

    customize-face brings up the “easy customization” interface I warned you 108 | against in the previous chapter. Click the State button and select Save for Future Sessions. (You can make changes here too, but I prefer 109 | modify-face because it gives you tab-completion on the possible values for 110 | each attribute.)

    111 |
    112 |

    Apart from describe-face, which I found in the Help menu, I found all these 113 | in the Emacs manual under “Faces”, 114 | “Standard Faces” 115 | and “Customizing Faces”.

    116 | 117 |

    Now let’s figure out how to bypass the “easy customization” interface:

    118 |
    119 |

    Visit your init file to see what “easy customization” added. If you already 120 | had the file open, you may need revert-buffer to see the latest changes.

    121 |
    122 |

    init.el

    123 |
    (custom-set-variables ;; custom-set-variables was added by Custom. ;; If you edit it by hand, you could mess it up, so be careful. ;; Your init file should contain only one such instance. ;; If there is more than one, they won't work right. ) (custom-set-faces ;; custom-set-faces was added by Custom. ;; If you edit it by hand, you could mess it up, so be careful. ;; Your init file should contain only one such instance. ;; If there is more than one, they won't work right. '(default ((t (:height 120 :family "Menlo")))) '(font-lock-comment-face ((t (:foreground "#3f7f5f")))))
    124 |

    You could configure the remaining font-lock faces by adding arguments to the 125 | custom-set-faces form, but they might be overwritten if you use the easy 126 | customization framework in future. Inspired by the name custom-set-faces, I 127 | searched for functions beginning with set-face and found 128 | set-face-attribute:

    129 |
    (set-face-attribute 'default nil :family "Menlo" :height 120) (set-face-attribute 'font-lock-comment-face nil :foreground "#3f7f5f") (set-face-attribute 'font-lock-string-face nil :foreground "#4f004f") (set-face-attribute 'font-lock-constant-face nil :foreground "#4f004f") (set-face-attribute 'font-lock-keyword-face nil :foreground "#00003f") (set-face-attribute 'font-lock-builtin-face nil :foreground "#00003f") (set-face-attribute 'font-lock-type-face nil :foreground "#000000") (set-face-attribute 'font-lock-function-name-face nil :foreground "#000000" :weight 'bold) (set-face-attribute 'font-lock-variable-name-face nil :foreground "#000000" :weight 'bold)
    130 |

    The above settings produce a very conservative dark-on-white color scheme. I 131 | like it because in many languages it highlights variable and function 132 | definitions but not their uses.

    133 | 134 |

    For all the face attribute names see “Face Attributes” 135 | in the Emacs Lisp manual. As to elisp syntax, keyword symbols like 136 | :foreground and :weight are constants (that evaluate to themselves so you 137 | don’t have to quote them).

    138 |

    diff-mode

    139 |

    While we’re on colors, let’s add some helpful coloring to diff-mode (which 140 | we came across earlier, in the section on the vc version control 141 | interface).[4]

    142 |
    143 |

    init.el

    144 |
    (eval-after-load 'diff-mode '(progn (set-face-foreground 'diff-added "green4") (set-face-foreground 'diff-removed "red3")))
    145 |
    146 |

    eval-after-load does what it says: The first time diff-mode is loaded, 147 | evaluate the following form. Emacs tends not to load every elisp package on 148 | startup, but waits until you actually use diff-mode to load it.

    149 | 150 |

    If you used (set-face-foreground 'diff-added ...) directly in your init file, 151 | you would get the error “invalid face diff-added”. You could explicitly load 152 | diff-mode (using require) in your init file, but that would increase 153 | Emacs’s startup time—ever so slightly—every time you run Emacs in the 154 | terminal for a quick job that won’t even use diff-mode.

    155 | 156 |

    eval-after-load takes a single form to evaluate, but we want to make two 157 | function calls, so we wrap them in progn which merely evaluates a bunch of 158 | forms sequentially. We quote it so that it doesn’t get evaluated right now, 159 | before even being passed to eval-after-load.

    160 |
    161 |

    diff-mode.el.gz

    162 |
      ;; provide the package (provide 'diff-mode)
    163 |
    164 |

    The first argument to eval-after-load has to match the name that the package 165 | provides (this usually matches the name of the command to enable the mode, 166 | but to double-check: C-h f diff-mode, follow the link to diff-mode.el.gz, 167 | and find the provide form near the bottom).

    168 |

    Color themes

    169 |

    Note: This section and the next, which deal with the color-theme package, 170 | were written for Emacs 23. color-theme is obsolete in Emacs 24, so I need 171 | to find a better example for installing third-party packages.

    172 | 173 |

    Maybe you already have a favourite color theme, like Zenburn or Solarized. There are Emacs implementations 174 | (Zenburn, Solarized) built on top of the 175 | color-theme minor mode. color-theme 176 | is a third-party package; it doesn’t come with Emacs.

    177 | 178 |

    Note that Emacs 24 provides a built-in mechanism for defining multiple color 179 | themes. Nevertheless, I’ll walk you through the process of installing 180 | third-party packages using color-theme and the Solarized theme as examples.

    181 | 182 |

    Emacs 24 also comes with a package management system, so—as long as the 183 | package’s author has taken advantage of the new mechanism—the manual 184 | installation procedure described below will not be necessary either.

    185 |

    Installing third-party elisp packages

    186 |

    I’ll assume that you are keeping your ~/.emacs.d under version control using 187 | git.[3]

    188 | 189 |

    color-theme’s installation instructions recommend using your package manager 190 | (apt-get install emacs-goodies-el or port install color-theme-mode.el, 191 | etc.) but I prefer to manage all my Emacs extensions in a single place. That 192 | place is my ~/.emacs.d directory, because I will eventually want an extension 193 | that isn’t provided by my system’s package manager.

    194 |
    195 |

    Download the color-theme.6.6.0.tar.gz and extract into 196 | ~/.emacs.d.

    197 | 198 |

    git add color-theme.6.6.0;
    199 | git commit -m "color-theme 6.6.0 from http://www.nongnu.org/color-theme/";

    200 |
    201 |
    202 |

    Add the color-theme directory to your Emacs load-path:

    203 |

    init.el

    204 |
    (add-to-list 'load-path "~/.emacs.d/color-theme-6.6.0")
    205 |
    206 |
    207 |

    And actually load it:

    208 |
    (require 'color-theme)
    209 |
    210 |

    Now you can select a theme with color-theme-select.

    211 |

    Installing packages from github

    212 |

    The Solarized color theme for Emacs is available on github. If you are keeping 213 | your ~/.emacs.d under version control using git, you can use git submodules 214 | to simplify the management of such third-party packages.

    215 |
    216 |

    cd ~/.emacs.d;
    217 | git submodule add https://github.com/sellout/emacs-color-theme-solarized.git;

    218 |
    219 |

    In future you can use git pull from ~/.emacs.d/emacs-color-theme-solarized/ 220 | to get the latest changes.

    221 |
    222 |

    Add ~/.emacs.d/emacs-color-theme-solarized/ to your Emacs load-path, and 223 | require 'color-theme-solarized, as you did for the color-theme package.

    224 |
    225 |

    Now you can activate the theme with color-theme-solarized-light (or -dark).

    226 |

    Increasing the font size

    227 |

    C-x C-+, C-x C--, and C-x C-0. See “Temporary Face Changes”.

    228 |

    variable-pitch-mode

    229 |

    You can toggle between fixed- and variable-width fonts in a particular buffer 230 | with variable-pitch-mode. The face to customize is variable-pitch.

    231 | 232 |

    To automatically enable variable-pitch-mode, add it to the hooks for all the 233 | major modes where you want it to take effect. For example, to text-mode-hook 234 | for editing plain text.

    235 | 236 |

    If you really want it everywhere, I suppose there’s no harm in setting the 237 | default face to a proportional font. The great advantage of 238 | variable-pitch-mode, though, is that it is so easy to switch between 239 | proportional- and fixed-width fonts when you come across some ascii art or an 240 | ascii table in a comment.

    241 |
    242 |

    [1]: 243 | I found this—after some dead ends—with Info’s index command, typing 244 | “font”, tab-completing, and trying whatever looked promising. I could just 245 | have explored the Options menu instead, but—silly me—I had disabled the 246 | menus because people on the internet said “real Emacs power users disable the 247 | menus.” That might make sense on a text terminal, where you can’t click the 248 | menu anyway, but on OS X, where there’s only one menu bar at the top of the 249 | screen, it’s just silly. See the next footnote.

    250 | 251 |

    [2]: 252 | If you have disabled the menu, perhaps because you’re using an init file 253 | copied from someone else or something like the Emacs starter kit, you can re-enable it just 254 | for this session with M-x menu-bar-mode.

    255 | 256 |

    [3]: 257 | cd ~/.emacs.d; git init .; git add init.el; git status; git diff --cached;
    258 | git commit -m "My emacs init file."

    259 | 260 |

    [4]: 261 | This customization—with several others—is borrowed from the Emacs 262 | Starter Kit.

    263 |
    264 | 265 |

    266 |
    267 | 268 | 269 | -------------------------------------------------------------------------------- /customize_c.haml: -------------------------------------------------------------------------------- 1 | %h1 cc-mode customization 2 | 3 | I should probably lead you through the relevant parts of the [Emacs]( 4 | http://www.gnu.org/software/emacs/manual/html_node/emacs/index.html), [Emacs 5 | Lisp]( http://www.gnu.org/software/emacs/manual/html_node/elisp/index.html), 6 | and [CC Mode]( 7 | http://www.gnu.org/software/emacs/manual/html_node/ccmode/index.html) manuals, 8 | but they're just. so. *long*! The mere table of contents for the Emacs manual 9 | is longer than our previous "Unix/C workflow" chapter.[[1]] 10 | 11 | Instead I'll show you how I try to find the information I need from the Emacs 12 | source code (most of which, thankfully, is in Lisp rather than C). The manuals 13 | I dissed a moment ago *are* incredibly useful. It is cause for wonder that an 14 | open-source project has produced such comprehensive documentation! But it is 15 | *impossible* to read those manuals cover-to-cover; you must learn how to 16 | efficiently find the right information. We've already covered the basic tools 17 | for that, and now we will exercise them a lot more. 18 | 19 | By the way, `c-mode`, `c++-mode`, `objc-mode`, `java-mode`, and a few others 20 | are all aliases for `cc-mode`, but with slight configuration changes to support 21 | the respective languages. From here on I'll use the name `cc-mode`. 22 | 23 | 24 | %h2#style House coding style 25 | 26 | Are you supposed to indent with 2, 3, 4 or 8 spaces, or with tabs? How big is 27 | a tab? Whatever you want, I'm going to assume it's *not* the indentation that 28 | cc-mode provides by default, so that we can walk through the procedure for 29 | changing it. 30 | 31 | .do 32 | Visit (open) a C or C++ file (you can use `readline/examples/rl.c` from the 33 | previous chapter). 34 | 35 | Pressing `TAB` anywhere on a line indents it to the appropriate position 36 | according to the current indentation rules (to insert a literal tab, use 37 | `C-q`, a.k.a. `quoted-insert`). 38 | 39 | Let's find out what Emacs does behind the scenes when we press `TAB`: 40 | 41 | .do 42 | `C-h k TAB` 43 | 44 | .window< 45 | :preserve 46 | TAB runs the command c-indent-line-or-region, 47 | which is an interactive compiled Lisp function in `cc-cmds.el'. 48 |   49 | .modeline< 50 | :preserve 51 | -U:%%- *Help* Top L1 (Help View)----------------------------------------------- 52 | .echoarea< 53 | Type C-x 1 to delete the help window. 54 | 55 | If you don't see the link to `cc-cmds.el`, then you don't have the elisp 56 | sources installed. Use your system's package manager to install the `emacs-el` 57 | package and try again. 58 | 59 | .do 60 | Follow the link to `cc-cmds.el`. This will position you right where 61 | `c-indent-line-or-region` is defined. Bring the whole definition into view 62 | (`C-M-l`) if necessary. 63 | 64 | .window.default< 65 | :preserve 66 | (defun c-indent-line-or-region (&optional arg region) 67 | "Indent active region, current line, or block starting on this line. 68 | In Transient Mark mode, when the region is active, reindent the region. 69 | Otherwise, with a prefix argument, rigidly reindent the expression 70 | starting on the current line. 71 | Otherwise reindent just the current line." 72 | (interactive 73 | (list current-prefix-arg (use-region-p))) 74 | (if region 75 | (c-indent-region (region-beginning) (region-end)) 76 | (c-indent-command arg))) 77 | 78 | 79 | %h2#elisp Emergency elisp 80 | 81 | A brief parenthesis is needed to explain the above code. Let's start with the 82 | `if` statement at the end: 83 | 84 | .window.default< 85 | :preserve 86 | (if region 87 | (c-indent-region (region-beginning) (region-end)) 88 | (c-indent-command arg))) 89 | 90 | For clarity, let's simplify it to: 91 | 92 | .window.default< 93 | :preserve 94 | (if region 95 | a 96 | b) 97 | 98 | If you still don't understand what that means, pretend that `if` is actually a 99 | function, and that it looks like this: 100 | 101 | .window.default< 102 | :preserve 103 | if(region, a, b) 104 | 105 | (Moving that parenthesis to the *left* of the function is probably the largest 106 | single barrier to Lisp's adoption by the rest of the world.)[[2]] 107 | 108 | .do 109 | What do the three arguments `region`, `a` and `b` mean? Make a guess, and 110 | then check the answer at `C-h f if`. 111 | 112 | The definitions of *`COND`*, *`THEN`* and *`ELSE`* should be pretty clear. But 113 | what does it mean by "`if` is a special form"? 114 | 115 | It turns out that `if` isn't a regular function. The elisp rule for evaluation 116 | of "normal" forms—where "form" means a parenthesized "shape" like `(a b c)` or 117 | `(a b (c d))`—is to evaluate each argument, and then pass the resulting values 118 | to the function. 119 | 120 | Let's consider the function `+` (elisp doesn't have special infix operators, so 121 | `+` is just a function). If `x` is a variable containing the value `5`, and `y` 122 | is a variable containing the value `2`, then the following two expressions are 123 | identical: 124 | 125 | .window.default< 126 | :preserve 127 | (+ x y) 128 | (+ 5 2) 129 | 130 | The function `+` never sees `x`; it only sees `5`. 131 | 132 | .do 133 | Evaluate the form `(+ 5 2)`: Switch to the `*scratch*` buffer, type `(+ 5 2)` 134 | on a line of its own, and press `C-M-x` to evaluate the form and display the 135 | result in the echo area. 136 | 137 | The very first element in the form (`+`, in this case) gets evaluated too. `+` 138 | is actually a variable[[3]] whose value is the function that adds numbers. 139 | 140 | Anyway, back to `if`. `if` is a "special" form, which means that the elisp 141 | interpreter treats `if` as a special case. Upon reflection, it is obvious that 142 | the normal function evaluation rules are not suitable for `if`: We wouldn't 143 | want to evaluate *`ELSE`*, with its possible side-effects, when *`COND`* is 144 | "true" (non-nil). 145 | 146 | All this is explained in the Emacs Lisp manual: 147 | 148 | .do 149 | `C-h S if` 150 | -# 151 | In the `*info*` buffer press `i` (for `i`ndex) and enter `special forms`. 152 | 153 | .do 154 | Go back to the `cc-cmds.el.gz` buffer. 155 | -# 156 | Enable the `eldoc` minor mode (`M-x eldoc-mode`). Now positioning the point 157 | over the `if` statement will show some brief documentation in the echo area. 158 | -# 159 | Enable `show-paren-mode` too. This should help clarify where the *`THEN`* and 160 | *`ELSE`* clauses begin and end. 161 | 162 | Now, back up to the `defun`: 163 | 164 | .window.default< 165 | :preserve 166 | (defun c-indent-line-or-region (&optional arg region) 167 | "Indent active region, current line, or block starting on this line. 168 | In Transient Mark mode, when the region is active, reindent the region. 169 | Otherwise, with a prefix argument, rigidly reindent the expression 170 | starting on the current line. 171 | Otherwise reindent just the current line." 172 | (interactive 173 | (list current-prefix-arg (use-region-p))) 174 | (if region 175 | (c-indent-region (region-beginning) (region-end)) 176 | (c-indent-command arg))) 177 | 178 | .do 179 | You now have three ways to get help on `defun`: `eldoc`'s summary in the echo 180 | area, the reference provided by `C-h f`, and the more comprehensive Info 181 | manual at `C-h S`. Take your pick. 182 | 183 | If you run across the word "lambda", it's the same as the "function" keyword 184 | in javascript for an anonymous function. 185 | 186 | To reiterate: 187 | 188 | * `defun` defines a function named *`NAME`*. 189 | * *`ARGLIST`* is a list of arguments for the function. In elisp, a list is 190 | enclosed in parens: `(a b c)`. In this case it isn't evaluated as a function 191 | call, because `defun` is a special form that treats this particular list in a 192 | special way. When `defun`ing a function that takes no arguments, *`ARGLIST`* 193 | would be the empty list `()`. 194 | * The optional *`DOCSTRING`* is used by the `C-h f` help system (yes, even for 195 | functions you define yourself!). 196 | * *`BODY`* is one or more lists that are evaluated when you *call* the 197 | function. 198 | * ...except for the `(interactive ...)` form. 199 | 200 | .do 201 | `C-h S interactive` 202 | 203 | Don't get too bogged-down by the explanation; reading the first two paragrahs 204 | is enough. Learn to find *just* the information you need, or you will be easily 205 | overwhelmed. Right now we don't need to know how to *use* `interactive`, only 206 | what it *means*. 207 | 208 | 209 | %h2#indentation Configuring indentation 210 | 211 | So. `c-indent-line-or-region` is a function that optionally takes arguments 212 | `arg` and `region`, which, when the function is called interactively (for 213 | example by pressing `TAB`), are set to the prefix argument (if specified with 214 | `C-u` or similar) and "true" if the region is active. 215 | 216 | Right now we care about indentation when operating not on the region but on a 217 | single line (i.e. `region` is `nil`), so let's look at the *`ELSE`* clause: 218 | 219 | .window.default< 220 | :preserve 221 | (if region 222 | (c-indent-region (region-beginning) (region-end)) 223 | (c-indent-command arg)) 224 | 225 | .do 226 | Use `find-function` to jump to the definition of `c-indent-command`. 227 | 228 | This is a long and scary function, but luckily it has a good documentation 229 | string. Now that we know the name of this function, we can view the same 230 | documentation in a help buffer, with `C-h f c-indent-command`. 231 | 232 | The documentation mentions a couple of interesting variables: `c-basic-offset` 233 | and `indent-tabs-mode`. 234 | 235 | .do 236 | `C-h v c-basic-offset` 237 | 238 | That talks about "buffer-local" and "file local" variables. What? 239 | 240 | .do 241 | `C-h S buffer-local` 242 | 243 | .do 244 | From the elisp Info node for Buffer-Local Variables, search for "file local" 245 | (you can use `C-s` or the index `i`). 246 | 247 | As you can see you sometimes have to try different searches to find the right 248 | information. "Buffer-local" happened to be in the index, so the symbol search 249 | (`C-h S`) found it; "File local" has a space, but the symbol search doesn't 250 | allow spaces, so you had to search from within the Info buffer itself. You 251 | could also have gone up (`u`) from the "Buffer-Local Variables" Info node and 252 | scanned the "Variables" table of contents. 253 | 254 | Let's check the current value of `c-basic-offset`: 255 | 256 | .do 257 | Switch to buffer `rl.c` (`c-basic-offset` is buffer-local, so it matters 258 | which buffer we're in). 259 | 260 | `M-x eval-expression RET c-basic-offset RET` 261 | 262 | Now change it to 4: 263 | 264 | .do 265 | `M-x set-variable c-basic-offset 4` 266 | -# 267 | Find a line to re-indent and press `TAB`. 268 | 269 | .do 270 | Repeat the same investigation with variable `indent-tabs-mode`. 271 | 272 | 273 | %h2#setq Setting variables from elisp code 274 | 275 | .do 276 | Switch to the `*scratch*` buffer. 277 | 278 | Anything starting with a `;` is a comment. 279 | 280 | .do 281 | Type in this form and evaluate it with `C-M-x`: 282 | -# 283 | `(set indent-tabs-mode nil)` 284 | 285 | You triggered an error, and Emacs brings up the backtrace in an elisp debugger. 286 | You tried to set a constant to `nil`, which is clearly an error. 287 | 288 | .do 289 | Explain why this happened, with your knowledge of the previous value of 290 | `indent-tabs-mode` and of the elisp rules for evaluating functions. 291 | 292 | We can *quote* the name of the variable so that it doesn't get evaluated: 293 | 294 | .do 295 | `(set 'indent-tabs-mode nil)` 296 | 297 | Read more about quoting: 298 | 299 | .do 300 | `C-h S quote` 301 | -# 302 | `C-h S setq` 303 | 304 | The following forms do exactly the same; the preferred form is `setq`. 305 | -# 306 | .window.default< 307 | :preserve 308 | (set 'indent-tabs-mode nil) 309 | (set (quote indent-tabs-mode) nil) 310 | (setq indent-tabs-mode nil) 311 | 312 | One last thing: `indent-tabs-mode` is buffer-local, so setting it here only 313 | affects the `*scratch*` buffer. To make the change global, you must use 314 | `setq-default`. 315 | 316 | 317 | %h2#init Init file 318 | 319 | Your changes to these variables will be lost when you restart Emacs. You need 320 | to put your settings into an initialization file that Emacs will load each time 321 | it starts. 322 | 323 | .do 324 | In the Emacs manual (`C-h r`) table of contents, search for "init file" and 325 | read the first paragraph. 326 | 327 | There are several places you can put your init file; I suggest the one that 328 | goes inside the `~/.emacs.d` directory, so you can organize your customizations 329 | by keeping multiple elisp files in the same directory, and loading them from 330 | the main init file. Put this directory under version control. 331 | 332 | .do 333 | Visit (open) the init file you've chosen (if the file doesn't exist, Emacs 334 | will create it when you save the buffer). 335 | 336 | .do 337 | Add the following lines: 338 | -# 339 | `(setq-default c-basic-offset 4)` 340 | `(setq-default indent-tabs-mode nil)` 341 | 342 | (or whatever values you have chosen). 343 | 344 | .do 345 | Restart Emacs, visit `rl.c`, and verify that your settings are in effect. 346 | 347 | 348 | %h2#hooks Hooks 349 | 350 | By default, `cc-mode` automatically re-indents the line whenever you type a 351 | character like `;` or `}`. These are called ["electric characters"]( 352 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Electric-C.html) and 353 | you can disable this behavior in a particular buffer with 354 | `c-toggle-electric-state` (`C-c C-l`). 355 | 356 | To always disable electric characters we can have Emacs call 357 | `c-toggle-electric-state` each time it loads `cc-mode`. 358 | 359 | .do 360 | `C-h m` (from the `rl.c` buffer, or any other `cc-mode` buffer) to find out 361 | the names of the hooks provided by `cc-mode`. 362 | 363 | A [hook]( http://www.gnu.org/software/emacs/manual/html_node/emacs/Hooks.html) 364 | is a variable containing a list of functions to be run, usually upon entry to a 365 | particular editing mode. For C code we have two hooks: One for all of 366 | `cc-mode`'s supported languages, and one just for C. We'll use the first one, 367 | `c-mode-common-hook`. 368 | 369 | .do 370 | Add the following to your init file: 371 | -# 372 | .window.default< 373 | :preserve 374 | (defun my-disable-electric-indentation () 375 | "Stop ';', '}', etc. from re-indenting the current line." 376 | (c-toggle-electric-state -1)) 377 | (add-hook 'c-mode-common-hook 'my-disable-electric-indentation) 378 | 379 | First we defined a function that takes no arguments and calls 380 | `(c-toggle-electric-state -1)`. Then we added the function to the 381 | `c-mode-common-hook`. 382 | 383 | The `-1` argument tells `c-toggle-electric-state` to disable, rather than 384 | toggle, the electric behavior (I learned this from `C-h f 385 | c-toggle-electric-state`; some functions might want `nil`, but this one wanted 386 | a negative number). 387 | 388 | You could add an anonymous function to a hook directly: 389 | 390 | .window.default< 391 | :preserve 392 | (add-hook 'c-mode-common-hook 393 | (lambda () (c-toggle-electric-state -1))) 394 | 395 | but then you have no way of referring to the function by name, so you can't 396 | remove it from the hook with `remove-hook`. 397 | 398 | 399 | %h2#style-system The cc-mode style system 400 | 401 | There is more to coding style than the size of indentation. Where should 402 | opening braces go? Should they be indented too? 403 | 404 | The `C-h v` documentation for `c-basic-offset` mentioned a "style system", and 405 | referred us to `c-default-style`. 406 | 407 | .do 408 | `C-h v c-default-style` 409 | 410 | .window.default< 411 | :preserve 412 | c-default-style is a variable defined in `cc-vars.el'. 413 | Its value is ((java-mode . "java") 414 | (awk-mode . "awk") 415 | (other . "gnu")) 416 | 417 | Elisp syntax for a list is `(a b c)`, and for a pair is `(a . b)`. Pairs are 418 | called "cons cells" in lisp terminology, and you access the first element with 419 | the function `car`, the second with the function `cdr` (pronounced 420 | "could-er"). 421 | 422 | So the value of `c-default-style` is a list containing 3 pairs; it's used as a 423 | lookup dictionary where `java-mode`, `awk-mode` and `other` are the keys, and 424 | `"java"`, `"awk"` and `"gnu"` are the values (in this case, names of styles to 425 | use for each of the editing modes represented by the keys). These lookup 426 | dictionaries are called "alists". 427 | 428 | .do 429 | `C-h S alist` 430 | 431 | In your init file you could set `c-default-style` so that the default style for 432 | `other`[[4]] is something other than `"gnu"`. 433 | 434 | If you need to customize anything (including `c-basic-offset` and 435 | `indent-tabs-mode`) to something different than any of the built-in styles, I 436 | recommend you define your own style: Thus if you work on different projects 437 | with different styles, you will be able to switch easily (with `c-set-style`). 438 | The way we set `c-basic-offset` earlier will [automatically create a style 439 | called "user"]( 440 | http://www.gnu.org/software/emacs/manual/html_node/ccmode/Built_002din-Styles.html#index-User-style-294). 441 | 442 | For help see ["Configuration basics"]( 443 | http://www.gnu.org/software/emacs/manual/html_node/ccmode/Config-Basics.html), 444 | ["Customizing indentation"]( 445 | http://www.gnu.org/software/emacs/manual/html_node/ccmode/Customizing-Indentation.html), 446 | and ["Sample .emacs file"]( 447 | http://www.gnu.org/software/emacs/manual/html_node/ccmode/Sample-_002eemacs-File.html) 448 | in the CC Mode Manual. 449 | 450 | 451 | %h2#keys Binding keys 452 | 453 | I often come across source code where one file expects tabs to equal 8 spaces, 454 | and another file in the same directory—or even other lines within the same 455 | file—want a tab to be 4 spaces. Let's create a function that cycles 456 | `tab-width` between 2, 4 and 8 spaces. 457 | 458 | (I found the variable `tab-width` by using `apropos-variable` to search for 459 | "tab".) 460 | 461 | .do 462 | .window.default< 463 | :preserve 464 | (defun my-tab-width () 465 | "Cycle tab-width between values 2, 4, and 8." 466 | (interactive) 467 | (setq tab-width 468 | (cond ((eq tab-width 8) 2) 469 | ((eq tab-width 2) 4) 470 | (t 8))) 471 | (redraw-display)) 472 | 473 | The `cond` expression evaluates to 2 if `tab-width` equals 8; to 4 if 474 | `tab-width` equals 2; and to 8 otherwise. Look up `cond` and `eq` in the Info 475 | manuals if you like. 476 | 477 | I've been naming all my functions "*my*-something" because elisp doesn't have 478 | separate namespaces for each mode or package; this way I can be sure my 479 | functions won't accidentally re-define an existing function that some editing 480 | mode relies on. 481 | 482 | Now let's bind our new function to a key sequence, so we can invoke it 483 | conveniently. `C-c` followed by a letter is [reserved for users to define]( 484 | http://www.gnu.org/software/emacs/manual/html_node/elisp/Key-Binding-Conventions.html), 485 | so we'll use `C-c t`: 486 | 487 | .do 488 | .window.default< 489 | :preserve 490 | (global-set-key (kbd "C-c t") 'my-tab-width) 491 | 492 | 493 | The meaning of "global" in `global-set-key` should be obvious. If you'd like a 494 | keybinding just for `cc-mode`, use `define-key` to add the binding to the 495 | mode's keymap: 496 | 497 | .window.default< 498 | :preserve 499 | (define-key c-mode-base-map (kbd "C-c t") 'my-tab-width) 500 | 501 | I discovered `c-mode-base-map` with `C-h v c-mode- TAB TAB`. There is also a 502 | `c-mode-map` which is just for the C language, rather than all languages 503 | supported by `cc-mode`. 504 | 505 | 506 | %h2#auto-mode Associating file extensions with an editing mode 507 | 508 | Say you want `.h` files to open in `c++-mode` rather than `c-mode`: 509 | 510 | .do 511 | `C-h v auto-mode-alist` 512 | -# 513 | `C-h f add-to-list` 514 | 515 | .figure 516 | .window.default< 517 | :preserve 518 | (add-to-list 'auto-mode-alist 519 | '("\\.h$" . c++-mode)) 520 | .modeline< 521 | :preserve 522 | -U:--- *scratch* All L6 (Lisp Interaction)---------------------------------------- 523 | .echoarea< 524 | Regexp I-search: \\.h$ 525 | 526 | The trickiest part will be getting the regular expression right—elisp doesn't 527 | have syntax for a regexp literal, so you have to put it inside a string, and 528 | then the string backslash-escaping makes the regexp rather awful. See 529 | ["Regexps"]( 530 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Regexps.html) in the 531 | Emacs manual. 532 | 533 | 534 | %h2#homework Homework 535 | 536 | If you have a spare 30 minutes read Steve Yegge's [Emergency Elisp]( 537 | http://steve-yegge.blogspot.com/2008/01/emergency-elisp.html). 538 | 539 | If you have a spare 6 months work through [Structure and Interpretation of 540 | Computer Programs]( http://mitpress.mit.edu/sicp/), a famous textbook from MIT 541 | that teaches important (and some quite advanced) programming concepts and 542 | techniques using a simple dialect of Lisp called Scheme. If you like "mathy" 543 | things like the [Sieve of Eratosthenes]( 544 | http://en.wikipedia.org/wiki/Sieve_of_Eratosthenes) for finding prime numbers, 545 | [Heron's method]( 546 | http://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Babylonian_method) 547 | for calculating square roots, or estimating the value of pi using [Monte Carlo 548 | simulation]( http://en.wikipedia.org/wiki/Monte_Carlo_method), then you'll love 549 | this book. 550 | 551 | If you had a collection of `.emacs` customizations collected from the web 552 | before you started this guide to Emacs, go over them now and try to understand 553 | them thoroughly. 554 | 555 | In future, when you need a particular customization try to find the solution 556 | from the manuals or the elisp sources before reaching for Google. 557 | 558 | Don't try to modify the elisp files that are part of the Emacs distribution. 559 | For one, it won't be easy to merge your changes when you update Emacs to a 560 | newer version. Second, the files are byte-compiled so you'd have to recompile 561 | them. Third, even if you did it still wouldn't help because the core elisp 562 | functions are [built into the Emacs image]( 563 | http://www.gnu.org/software/emacs/manual/html_node/elisp/Building-Emacs.html), 564 | so you'd have to recompile the whole program. Instead, use the variables and 565 | hooks provided for customization. 566 | 567 | Don't pay attention to the Emacs manual whenever it tells you to use the ["Easy 568 | customization"]( 569 | http://www.gnu.org/software/emacs/manual/html_node/emacs/Easy-Customization.html) 570 | facility (in some help buffers it will say "you can customize this variable"). 571 | It's referring to a really awkward semi-graphical interface for setting Emacs 572 | variables. Best to keep all your customizations in your own init file. 573 | 574 | 575 | #footnotes 576 | [[1]]: 577 | Try this: 578 | `lynx --dump http://www.gnu.org/software/emacs/manual/html_node/emacs/index.html |` 579 | `sed '/^References/,$ d' | wc -w` 580 | 581 | [[2]]: 582 | I *am* joking. Lisp does have plenty of real problems. 583 | 584 | [[3]]: 585 | Actually a "symbol". Curiously, elisp functions and variables live in 586 | separate namespaces, so you can define the variable `+`, set it to `2`, and 587 | still use `+` as a function in nonsensical statements like `(+ 1 +)`. Try it: 588 | `(setq + 2)` 589 | `(+ 1 +)` 590 | 591 | [[4]]: 592 | "Other" here only refers to languages supported by `cc-mode`, not *any* other 593 | language. 594 | --------------------------------------------------------------------------------