Outdated documentation

This documentation is out of scope. Emacs already has a user manual.

GNU Emacs 22.1.1

GNU Emacs, often referred as Emacs, is a advanced, self-documenting, customizable and extensible file editor. Written in 1986 by Richard Stallman. It is written in Emacs Lisp. If you ask Richard Stallman a question like this - " I want to learn a programming language, can you suggest one for me ?", his answer will be something like - "You must learn Lisp". Emacs is more than just an editor once you dig deep inside. Here are few things that you can do with Emacs - write programs, write articles/reports/documentation like this one, read text-info manuals and man pages, execute basic shell commands, browse tar/zip archives, listen to music, do email, browse the web in text mode. Sounds interesting ?. It is time for you to leverage one of the first programs released by the GNU project - GNU Emacs.

The focus of this page will be to get you acquainted with some of the features in Emacs. This should not be looked as a how-to page, rather as a page which will try to throw light on certain features of emacs and give pointers to places where you may find information about how to use emacs.

Basic Things

Firing Emacs

There are couple of ways to start Emacs. The most obvious way is to go to Applications --> Accessories --> Emacs 22 (GTK) . The other way is to start emacs from the Terminal, to do this, first open a Terminal window, type emacs and hit RET, an Emacs window should open. You have an option to run Emacs right inside the Terminal window, instead of using GTK. To run Emacs right inside the Terminal window, open the the Terminal, type emacs -nw and hit RET, emacs should open inside the Terminal. The option -nw stands for no window system - it just says Emacs not to use the GTK's interface. You can also run Emacs from the Virtual Terminal, to do this, first move to a Virtual Terminal by hitting Ctrl+Alt+F2, you will be prompted for the username and password, duly provide them, after this, type emacs and hit RET, you will be running emacs from the Virtual terminal.

Now you have learned how to kick off Emacs in different ways, next step is to learn some basic stuff. Read ahead.

Representation of Keys

To enhance readability of this page and to easily read the official Emacs documentation, here are certain things that you need to be familiar with.

Opening, Creating and Saving Files

Emacs is an editor and therefore opening/creating files is the first step when you open Emacs. You may open a file by rattling the

 C-x C-f

key binding from your keyboard. This should open a prompt in the bottom of the emacs window (this space is called the mini buffer) asking you for the path of the file and the file name. Duly type in the path for the file and hit RET. If the file already exists, then the file is read from the disk, if the file doesn't exists, emacs creates one for you and opens the created file in a new buffer.

Now you may edit the file ( either the one that already exists or the new created file) as you wish and save the file with the

 C-x C-s

key binding, it is only after you save the contents of the file will emacs write it to the respective file in the disk.

In case you want to undo changes that you have made to the file, use the

 C-x u

key binding to undo changes, you may undo changes as long as Emacs has the history of the changes you have made to the file.

Moving around in the Buffer

The blinking rectangle - the cursor, can be moved around using the arrow keys, but this is seen as being inefficient, since , your fingers has to move away from the typing position to access the arrow keys. In Emacs, there are key bindings to overcome this.

To move the cursor one place forward, use the

 C-f

key binding, C-f means you keeping pressing the Ctrl key while you hit the f key. The

 C-b

key binding is used to move the cursor back by one place. To move the cursor up by one place, use

 C-p

key binding and

 C-n

key binding to move the cursor down by one place.

If your reading a big file, the C-n and the C-p command might be cumbersome. To scroll one screen forward, use the

 C-v

key binding. To scroll back by one screen, use the

 M-v

key binding. Moving to the beginning and the end of the file can be achieved by

 M-< 
 M->

keys bindings respectively.

Killing and Yanking

Shuttling words from one place in the file to another, copying a chunk of text from a file and putting the chunk elsewhere, erasing irrelevant paragraphs from a file are certain regular things you do while editing a file or editing multiple files. Majority of the Applications call these routine tasks as cutting and pasting. In Emacs, these things are known as Killing and Yanking. To kill in Emacs means to remove the respective text from the buffer and put the text in the kill ring. The kill ring is similar to the clipboard that many Applications have. A clipboard as the capability to remember only the recently copied/cut text from the file, whereas the kill ring can remember more than two kills at a time and the memory of the kill ring is limited by the variable known as kill-ring-max.

Killing

Killing text is similar to cutting text from a buffer. There are couple of commands available in Emacs for killing text, but here, I will reveal to you only the significant ones for the sake of simplicity and to maintain the page as a basic document to get new users acquainted with Emacs.

To kill a line of text, all you got to do is, move to the beginning of the line and hit the

 C-k

key binding to kill that line. If you need to kill a bunch of lines, then the kill command can turn out to be inefficient. So how do we kill a bunch of lines ?. It is quite intuitive. First, you need to select the bunch and use the

 C-w

key binding to kill it. Your question now will be " How will I select my bunch of text ?". Okay, In Emacs we call the bunch of text which is select as the region. To select a region, first we specify the beginning of the region by the hitting

 C-<SPC>

key binding and then moving to the cursor to the end of region of text. After your region selection, go ahead and kill the region with the C-w key binding.

Both the above described kill functions remove the text from the buffer, this might not be always desired, you might want to just copy a section of text instead of removing it from the buffer. If this is what you desire to do, then use the

 M-w

key binding instead of C-w. The function (executed by the M-w key binding) instead of cutting the text from the buffer, makes a copy of the text and puts it in the kill ring. It is required that you specify, the region of text, the function executed by the M-w must copy and put in the kill ring

Yanking

With C-w and `M-w' we managed to put the text in the kill ring, now we will have to yank (move) it from the kill ring and put the text in the desired destination. To do this, first move your cursor to the destination where you need to yank the text, next use the

 C-y

key binding to yank the last killed text from the kill-ring to the place where the cursor is. If you want to yank the second most recently killed text, first do C-y and then hit M-y. This is should bring the second most recently killed text into the buffer. You may use the M-y as many times as there are text available in the kill ring.

Buffers

A Buffer is an container into which file is loaded when you open that respective file in Emacs. There can be more than one buffer in a single instance of Emacs, but it is possible to edit/manipulate only one buffer at a time.

To go to a particular buffer, type

 C-x b

To kill a particular buffer, type

 C-x k

To view the list of buffers in the current Emacs session, type

 C-x C-b

Quitting Emacs

So I how do we quit an Emacs session. The key binding to quit Emacs is inspired from the Bash's key binding to kill a presently running process - C-c. To quit Emacs, you have to hit the following key sequence :

C-x C-c

To elaborate, keep pressing the Ctrl key and hit the x key and c key in sequence. Emacs should close itself.

Intermediate Things

Searching and Replacing

Searching for text

Rummaging for a string of text is common when you're wading through reference text, or documentation. For instance, if you're skimming an anthropological document and desire to directly head to a section on Polymaths, then the search function in Emacs will be instrumental in getting you there to the Polymaths section. Prior to giving your search term, it is prerequisite to invoke the search function. To do this, use the

 C-s

key binding. The C-s key binding invokes an incremental search function, meaning, the function starts to search as soon as you start typing the individual letters of the respective search term ( in our case - Polymaths), i.e, when you press the first letter of the search term - P, the function rummages for the first P in the buffer in which you have invoked the search function, if it finds a P in the buffer, it duly moves the to the point the P and hightlights P. When you hit the second letter of your search term - o, function searches for the string Po in the buffer and if it finds the string it moves the cursor there and highlights Po, and then when you type the third letter of your search term - l, the function searches for Pol and if it finds the phrase, it goes there. When you finally typed the whole search term Polymath, it searches for the phrase, highlights and moves the cursor there. You must note that, one positive aspect of incremental search is that, there is always the possibility that you will reach the search string before you even type the full search term. The C-s key binding searches forward, if you want to search backward, use the

 C-r

key binding. C-r is also performs an incremental search but it performs a backward search, that is the major difference between the functions invoked by the C-r and the C-s key bindings.

Not comfortable with incremental search ?. No problem, Emacs gives an option to perform a non-incremental search. To perform a non-incremental search, do C-s or C-r and immediately hit RET, this brings up a prompt called Search forward: or Search backward: in the minibuffer (according to whether you hit the C-s or C-r key binding), give the the prompt your search term (in our case it is Polymath) and hit RET to perform the search. The non-incremental search allows you type the search term fully before the function performs the search.

Replacing text

Replacing text in a editable file is rare, but Emacs provides this very feature, perhaps, for the sake of completeness. I will take a hypothetical situation to explain this feature. Imagine a modern world kingdom known as the The Kingdom of Domenix where the king, Lord Domargivk, maintains all of his affairs and duties in his notebook computer and for the sake of simplicity, the king maintains all these things in simple files. Let us pick one of the files from Lord Domargivk's notebook computer and see how the Replace feature in Emacs will come of use. The file I have chosen is called the File of Relationship which contains the names of neighbouring kingdoms and the relationship that The Kingdom of Domenix has with the neighbouring kingdoms. The file looks like this.

                    Kingdom of Domenix.

        File of Relationship.

Neighbour       Status

City of Worlao  war
Amigoras        peace
Bitumenous      war
Zidale          war
Glirtir         peace
Paelebande      war
Loenradadnicx   war
City of Yile.   war

The king for his cynical deeds and for the benefit of his kingdom has a habit to change the status of relationship his kingdom has with its neighbours quite frequently. Being a saint in the Church of Emacs he uses GNU Emacs, for almost all tasks, on top of a free (free as in freedom) operating system like gNewSense. His fickle minded self desires to change the status of relationship with his neighbours. Lord Domargivk wishes to make peace with three of the nations which are presently in war with the Kingdom of Domenix, they are - City of Worlao, Zidale and City of Yile. To make the corresponding changes in the File of Relationship, he opens the File of Relationship file in an Emacs buffer and invokes the query replace feature by hitting

 M-%

key binding. Emacs opens the Query replace prompt where he gives the string that as to be replaced by a new string. He gives war as the string to the Query replace prompt and hits RET, immediately Emacs prompts him with the Query replace text with prompt. Since he wants to change the status of few neighbours from war to peace. He gives peace as the replacement string for this second prompt and hits RET. After this, Emacs searches for the string to be replaced ('war') after the point in the File of Relationship and highlights the first match in a pink shade (the color of the highlight is defined by the query-replace face) and other subsequent matches are highlighted in a blue shade (the color of this is defined by the lazy-highlight face). The buffer looks this now :

screenshot1.png

As you can see, the first match ('war') is the one beside the City of Worlao, since Lord Domargivk wishes to make peace with this nation, he certainly has to replace the status from war to peace, to do the replacement for this match, the king hits the

<SPC>

 (or)

'y'

key. This replaces the text highlighted in pink shade ('war') to peace and automatically moves to the next consecutive match and the buffer looks like this now :

screenshot2.png

Now the status of Bitumenous is highlighted, since, the Lord Domargivk wishes not to change the relationship status of the Bitumenous kingdom, he doesn't perform any replacement here and he just skips to the next match by hitting

<DEL>

or

'n'

key. The query-replace function now moves to next match. The status of the relationship of the Zidale kingdom is now highlighted. The kings desires to make peace with this kingdom, therefore, he does the replacement with the <SPC> or y key. The next two consecutive matches as can you see are the status of relationship with the Paelebande and the Loenradadnicx kingdoms and it is evident that Domargivk wants to remain in war with these kingdoms, therefore he skips these two consecutive matches by rattling the <DEL> or n key twice. This moves the cursor to the end of the last match - the status of relationship with the City of Yile kingdom. Domargivk wishes to bring in peace with this neighbour, therefore, hits the <SPC> or y key to make the replacement. After this, he saves the File of Relationship and closes the buffer.

If the fickle minded king of Domenix changes his mind to make peace with all the neighbouring kingdoms, there is another function at his call in Emacs. It is called replace-string function. To invoke this, we hit M-x and type replace-string and hit RET. Emacs will bring up the Replace string prompt in the minibuffer, you need to provide the text string that has to be replace and press RET. In the next prompt (Replace string with), provide the replacement string and hit RET. The replace-string function searches for a match and if it finds, replaces the match with the replacement string and keeps doing this until it finds no matches.

Split window

If you want to see two (or more) files at a time, you can split the main window of emacs.

To split vertically current window in two windows, type:

 C-x 2

To split horizontally current window in two windows, type:

 C-x 3

Switch between windows

To switch between windows, type:

 C-x o

Close windows

If you want to close current window, type:

 C-x 0

If you want to close all windows but current one, type:

 C-x 1

Bookmarks

Bookmarks helps you to keep tabs on files you often visit. The Bookmark feature in Emacs not only keeps a list of bookmarked files but also remembers the exact location where the point had been.

Creating Bookmarks

All most all buffers in Emacs can be bookmarked. A buffer can be bookmarked by giving

C-x r m

key binding in Emacs. Once you provide this command to emacs, it will start a prompt in the minibuffer asking for a name for the buffer which is being bookmarked, the buffer's name is the default name for the bookmark, if you're okay with default name for the bookmark, hit RET, otherwise provide a name for the bookmark and hit RET.

'Jumping' to the Bookmarked file

Of course you will want to visit the bookmarked file at a later Emacs session, you may jump to a bookmarked file by providing this key binding

 C-x r b

to Emacs. Emacs will start a prompt, asking you for the name of the bookmark to open, duly provide it the respective name of the bookmark and hit RET. Emacs should open the bookmarked file.

Browsing tar/zip archives

It is common to have tar and zip archives in your computer, in most of the cases, it is that you want to just browse the archive, i.e, you don't want to modify any files contained in the archive. In this scenario it is more appropriate to browse that archive without actually extracting the archive.

gNewSense comes with file-roller which helps you to browse/extract archives. But when you want to read a file, you will have to open a separate application like gedit. In Emacs, you won't need a separate application to open up a file for reading, because Emacs itself is an editor!. Therefore with Emacs, you have the ability to everything from Emacs itself. If you're running, Emacs using GTK, it is also possible to view images (contained in the archive) straight from Emacs.

So how do we do it ?

It is simpler than you think. To open the archive, all you got to do is hit the

 C-x C-f

key binding, you will be prompted for the file todisplay, give the prompt the respective archive name (If you have stored your archive (say , foo.tar) in ~/Documents folder, then the string that you have to give to the prompt will ~/Documents/foo.tar.) preceded by the pathname to the archive and hit RET, the contents of the archive will be displayed in a new buffer. In this new buffer, to read/view a particular file, move the cursor to the respective file and hit RET, the file will materialize itself in a new buffer and you may start reading the file.

Listening to Music

Emacs Multimedia System (emms) enables you to play music right from the Emacs interface, it is designed to be minimalistic and non-intrusive. Emms is not installed by default in the Emacs packaged by the gNewSense team. It is required that you manually install it using the APT system.

Installing emms

You need administrative privileges to install emms in the system. Perchance, if your not the administering your computer, please tell the computer administrator of the system to install emms for you.

To install emms, open the terminal (Applications --> Accessories --> Terminal), make sure you're connected to the Internet and then type the following sequence of commands.

          sudo apt-get update
          sudo apt-get install emms

That's it, you have installed emms. But before you can play music, there are certain non-trivial things to do. Read ahead.

Initial configuration

Emms requires the vorbis-tools package to function properly, therefore go ahead and install this package by rattling the following commands in the terminal.

        sudo apt-get update     
        sudo apt-get install vorbis-tools  

After this, you must add a few lines in the .emacs file which is located in your home directory. To do this, please open Emacs, hit C-x C-f for the Find file prompt, give this string - ~/.emacs, as the argument for the prompt and hit RET. The .emacs file should open. Move the cursor to the bottom of the buffer and add the following lines.

          ;; EMMS
          (require 'emms-setup)
          (emms-all)
          (emms-default-players)

Once you have added the above lines, save the .emacs file by hitting the C-x C-s command. Quit (C-x C-c) and restart Emacs. Now you're ready to play music from Emacs. Since we have install only vorbis-tools, emms will only be able to play ogg and flac files. If you have your music in the mp3 format, it is recommended that you convert your music to ogg and if that is not possible, install the mpg321 package to play music in mp3 format, though this is highly not recommended as mp3 is fraught with patents and having mp3s is against the conscience of the free software community.

Adding files/directories to playlist

In emms to play music, you must first add files to the *EMMS playlist* buffer (which is automatically created once you start adding music files). To add just one file to the playlist, type M-x (the x key while pressing the Alt/Meta key) then hit the following :

           emms-add-file

You must be prompted with the Play file prompt, give the path where the music file is located. If you have stored the musics file Swansong.ogg under the ~/Music/joshwoodward directory, then the argument for the Play file prompt will be ~/Music/joshwoodward/Swansong.ogg.

If you wish to add the whole ~/Music/joshwoodward directory, then you need to use this command :

           emms-add-directory

In the same way as for the emms-add-file command, you need hit M-x first and then rattle the above command and after you give the prompt the directory to play (~/Music/joshwoodward),hit RET. Now, of course you want to play those music files. Let's do it.

Playing music

The most simplest way to begin playing music is by hitting M-x and then typing the following command :

            emms-start

and hitting RET, the music should soon start playing. You may also go to the *EMMS Playlist* buffer to start playing music. Do M-x and type emms and hit RET to go to the emms buffer. Here you use the cursor to select the songs (use the C-n and C-p key bindings to move around the bufffer) and hit RET to play the song on which the cursor is on.

There are one-letter commands which you can use in the *EMMS playlist* buffer. Here is a list of few significant ones :

Key Binding

Function

n

play next song in the list.

p

play previous song in the list.

P

pause the song which in playing.

s

stop playing music.

Adjusting Volume

The next thing that you might want to know is How do I adjust the Volume ?. It is quite simple. First, go to your *EMMS playlist* buffer by doing M-x, typing emms as the argument for the prompt and hitting RET. Once you're in the *EMMS playlist* buffer, hit M-x again and type the following command :

           emms-volume-raise

This command will enable you to adjust the volume from the *EMMS playlist* buffer. You increase the volume by hitting the + key and you decrease the volume by hitting the - key.

You will find this volume adjustment feature very useful, if you choose to run emacs from the virtual terminal.

Want more on emms ?

The textinfo manual is the best destination to get more information. To get to the emms textinfo manual all you have to do is:

and you're there. If you're not quite acquainted with browsing the textinfo manual, hit h key to read some basic things on how to browse the textinfo manual.

Browsing the Web

The Internet has become major reason why we turn our computers ON. You are reading this because of the Internet. With a program by the name w3m-el you may browse the Internet in text mode right from Emacs.

Installing w3m

The w3m-el program is not installed by default and it is required that the user installs it manually. To install w3m-el, go to your administrative account and open the terminal window and provide the following commands to install w3m-el

          sudo apt-get update
          sudo apt-get install w3m-el

Now, you will be able to use w3m-el from Emacs.To do use w3m-el, first start an Emacs session, hit M-x and give w3m as the argument and press RET. This will start w3m (buffer) inside Emacs.

Searching the web

Once inside the w3m (buffer), use the S to do a Google search. As soon as you hit S, a prompt in the minibuffer will ask you for the search phrase, duly give it and hit RET to perform the search.

Going to specific locations

If all you want to do is go to a specific URL, say, www.gnu.org. Then use the G key. w3m will ask for the URL from the minibuffer. Type the URL duly - www.gnu.org and hit RET. w3m will directly take you to the desired destination.

Bookmarking

w3m supports bookmarking, web pages can be bookmarked with the a key. In w3m, the bookmarked web pages are organized into Sections, you can put the gNewSense's web pages in a Section called gns, if you're researching the web on how to build a laptop, you may put these pages in a Section called DIY Laptop. As soon as you hit the a key to bookmark a page, you will be prompted for the Section in which the page must go in, give the name of the section and next when you hit RET, the prompt will ask for the Title, w3m will generate a title for you, if that is okay, just press RET otherwise provide your own custom Title and hit RET.

More

The complete documentation of emacs is available on the GNU website.


CategoryOutdated

Documentation/Emacs (last edited 2013-09-05 19:06:30 by samgee2)