Skip to content

Latest commit

 

History

History
417 lines (343 loc) · 20.8 KB

emacs.org

File metadata and controls

417 lines (343 loc) · 20.8 KB
Raw

My Emacs Notes

Overview

Introduction

This is my collection of GNU/Emacs related notes which I wrote for my own use as well as to share with my friends and colleagues. This may be a bit chaotic, because much of it was lifted from a much larger document which I have been carrying around for many years.

Warning: many links are not properly rendered by github. Please see README.org on how best to read this document.

This document is written in org-mode. It is best viewed using emacs in org format, but you can also view the HTML version via a web browser.

Why another document on emacs when there are so many online resources already? Although there are many online resources, almost none of them cross link to the official manuals which I think is quite unfortunate, because in my opinion one of the best things about emacs is its excellent documentation which can be accessed from within emacs in many ways.

The Official Guided Tour is just about the only online resource that I could find that has more than a few links to the official manuals. Unfortunately this document does not seem to refer to any unofficial resources outside of gnu.org, e.g., there is no mention of packages such as magit, evil, and many many other excellent packages some of which are mentioned in this document. My goals with this document is to help my friends and colleagues not only learn many features of emacs, but also to get them well versed in emacs documentation system so that they can learn all that emacs has to offer on their own.

This document cross links heavily with the official manuals such as the Emacs Manual and the Emacs-Lisp Manual. If you are reading this document within emacs as org files, then clicking on these links bring up GNU info browser. If you are reading the html version (e.g., https://github.com/emacs18/notes), then most emacs related links will take you to documents located under http://www.gnu.org/software/emacs/manual/html_mono.

How to learn or lookup features

The chapter of emacs manual details many ways to get help. Also info manual is a good way to learn the GNU info browser. A few of the topics discussed in these manuals are listed below.

  • Hitting C-h or ? following any incomplete key sequence will list all possible key bindings, e.g., try typing C-x 4 C-h. Also which-key add-on package shows all possible key bindings as you type.
  • Type C-h C-h to see what commands follow C-h and learn as many of these as possible.
  • helm is another great way. Just type M-x and start typing space separate regexp of the command that you want to locate, e.g., typing “back color” shows that set-background-color is the only match.

Some of the commands that start with C-h are:

KeyFunctionComment
C-h iinfolaunch GNU/info browser
C-h kdescribe-keydescribe specified key sequence
C-h fdescribe-functiondescribe specified function
C-h vdescribe-variabledescribe specified variable
C-h Sinfo-lookup-symbollocate manual section on specified symbol
C-h mdescribe-modesummary of current major mode
C-h aapropos-commandfind symbols by name

Document Format

This document is authored in org-mode format within GNU/Emacs, then converted to HTML via emacs. I prefer to use the bigblow HTML theme provided by org-html-themes add-on package.

I started writing this document in texinfo format, but then switched over to using org-mode.

Although most folks probably read HTML version of this document, I read and edit this document in org format. One key advantage of org mode is that links to Emacs and Elisp manuals pop up instantaneously without any delay.

Most links to the info documents are presented using info node name notation, e.g., (emacs)Help. See GNU info documentation system below for more info.

GNU info documentation system

If you hit C-h i or M-x info within emacs, it brings up the info document browser which allows you to browse many info documents. Hitting d within the info browser displays all the info files that are currently known to emacs. From there you can browse emacs, elisp, or any other document currently available.

Resources

This chapter lists some of the online emacs resources available that I came across over the years.

General Resources

There are just too many resources, but here is my collection of few links.

New User Resources

Emacs News/RSS/Blog Sites

There are many blog and other site. These are just a few that I came across.

Startup Files

These links discuss emacs startup files. There are many others I’m sure.

Org Mode

Some links on org mode:

Package

Package Overview

For an overview see Packages section of Emacs manual, and Packaging section of Emacs-Lisp manual. Also you should be familiar with the following concepts explained in Elisp Basics section to understand this section: loading, autoload, load-path, byte-compiling, etc.

A package is a collection of files. Most often the files are elisp files, but it could also include info manuals and other files. Installing a package usually means

  • Creating a new sub-directory under the directory specifiied by package-user-dir variable
  • Unpacking files (usually from a tarball) to the new directory
  • Byte-compiling all elisp files.
  • Generating the autoload file, i.e., a file that contains autoload forms.
  • Generating info manuals from texinfo source files if any

Once installed, a package needs to be activated to make it available for use. This includes three things

  • add installed package directory to load-path
  • Load the autoload file, i.e., <package>-autoloads.el file found in the package install directory if any
  • add package directory to info-directory-list if the package comes with GNU info manual

All installed packages are activated on emacs startup, i.e., emacs searches all sub-directories of package-user-dir and activates them.

Following are few variables which control package installation as well activation:

  • package-archives determines package sources, i.e., location from which to find packages
  • package-user-dir determines where packages get installed
  • package-load-list determines which packages are initialized on startup among all the installed package. Default is to initialize all.

Following are some of the functions related with packaging:

  • list-packages pops up “GUI” buffer so that you can browes, install, and delete packages interactively.
  • package-initialize is implicitly called by default after evaluating ~/.emacs. However you can also call this explicitly in your ~/.emacs early on to activate installed packages.

Emacs-Lisp

Elisp Basics

This chapter points out a few basic emacs-lisp concepts to help you understand how to install and use add-on packages. More comprehensive resources on learning elisp are listed at New User Resources

Topics covered include

  • elisp files define functions, variables, and other objects
  • emacs loads (i.e., evaluates) files to pick up new functions, and also possibly modify built-in features
  • load-path tells emacs where to find elisp files
  • autoload allows easy access to functions without using too much memory
  • elisp files are byte-compiled mainly for faster execution

The core emacs code is written in C. However much of built-in features of emacs is written in emacs-lisp which is a lisp dialect customized for use within emacs. The core of emacs is the elisp interpreter (or a virtual machine). When you use emacs you are interacting with the interpreter which is in infinite REPL, i.e., Read-Eval-Print-Loop. It just sits there and waits for you to use input devices such as keyboards and mice to request actions.

When you type anything on the keyboard or use mouse, you are executing elisp function bound to the key or mouse event that you just invoked. For example if you type m, then you are asking the interpreter to call self-insert-command elisp function which just inserts the letter just typed into the current buffer. However m is bound to dired-mark elisp function instead of self-insert-command within buffers in dired-mode so that typing m results not in inserting letter m, but marking the current item in dired buffer. See Keys, Commands.

You can use C-h k to ask emacs to describe what any given key sequence would do rather than calling the function bound to that key sequence. For example typing C-h k followed by m in most buffers would say that the m key sequence is bound to self-insert-command. Similarly typing C-h k followed by C-x C-f brings up *Help* buffer describing find-file function. *Help* buffer should show files.el link at the top.elfiles Clicking your mouse button on this files.el link should bring up files.el file showing emacs-lisp code that implements find-file function, i.e., you can browse the source code that make up emacs. This is one key reason why I almost always use my own build of emacs rather than /usr/bin/emacs or other emacs builds provided someone else.

Emacs function are written via defun (among other ways) like this

(defun f (arg1 arg2 ...) ...)

The side effect of evaluation this expression is that the lisp interpreter has added f function to its internal database of known functions. Similarly variables are set via setq, custom-set-variables, among other ways:

(setq make-backup-files nil)

Evaluating this make the variable known to emacs.

Functions and variables are put in emacs-lisp files such as files.el mentioned above. Files are then loaded into emacs, i.e., the content of the file is evaluated by the elisp interpreter whose side effect is to tuck away the function and variable definitions so that they can be called or accessed. In most cases new emacs-lisp code is made known to the interpreter by loading elisp files via one of these ways:

  • load-file evaluates the specified file whose side effect is to define new functions and variables, and also possibly modify existing ones
  • load-library first searches the directories listed in load-path (much like how linux shells search PATH) for the specified file name, then calls load-file on the located file
  • require first search features variable to see if the requested module is already loaded or not. If is is already loaded, then nothing is done. If it is not, then load-library is called.

However you can also evaluate specific elisp expressions within buffers interactively via eval-last-sexp (bound to C-x C-e), eval-print-last-sexp, eval-region, eval-current-buffer, eval-expression, etc.

elfiles If you don’t see a link to an elisp file within *Help* buffer, it probably means that you don’t have the elisp source files installed. On Debian derived GNU/Linux systems, you can fix this via something like sudo apt-get install emacs24-el.

Elisp Expressions

Resources:

  • Use the *scratch* buffer to experiment and learn. Use C-j to call eval-print-last-sexp.
  • info:emacs-lisp-intro#Top
  • info:elisp#Eval
  • info:elisp#Loading

Lisp expressions can be evaluated in many ways:

  • C-x C-e bound to eval-last-sexp evaluates one expression at a time and prints the result in the mini-buffer
  • eval-print-last-sexp evaluates one expression and prints the result in current buffer. This is bound to C-j within buffers in lisp-interaction-mode mode such as *scratch* buffer.
  • eval-region evaluates a region of elisp code
  • eval-buffer evaluates the whole buffer
  • load evaluates elisp code in a file
  • load-library evaluates elisp code in a file but uses LOAD-PATH to locate the requested file
  • require looks up features and if not found, then uses load-libary to locate and load the file

Symbols

buffer-local dynamic lexical

Resources:

  • info:elisp#Symbols
  • info:elisp#Variables
  • info:elisp#Functions
  • info:elisp#Eval

Things to note:

  • a symbol is an object that has for components: name, value, function and plist
  • Basic functions are symbolp, symbol-name, symbol-value, make-symbol, intern, unintern.
  • Property list functions are: get, put, symbol-plist, set-plist
  • info:elisp#Standard Properties lists properties that have predefined meaning, e.g., disabled and variable-documentation.
  • obarray is the container with all interned symbols.
  • mapatoms calls a function on all symbols.

Bindings:

  • info:elisp#Dynamic Binding
  • info:elisp#Lexical Binding
  • info:elisp#Closures
  • lexical-binding variable
  • special-variable-p

Advising

Official documentation include:

  • Advising Functions which discuss the new (as of emacs 24.x) way to advise functions.
  • Porting old advices shows you how you can convert old style advices which used defadvice macro.

Advising a functions means modifying the behavior of even built-in emacs functions to suit your needs. This is one of the neatest features of lisp which I haven’t yet seen in other languages that I used. Advising was first added to emacs in late 1980’s or early 1990’s in emacs version 18.