Gnus tutorial

Table of contents:


This document is my attempt to summarize what is needed to get up and running with Gnus, the news reader built-in to Emacs. I myself searched in vain for a long time to find a decent news reader, before discovering Gnus. It's a bit rough around the edges (in particular, no on-screen key-binding reminders) but if you're at all comfortable in Emacs it will quickly be your favorite news reader.

I assume you're more or less familiar with newsgroups. If not, here's the 5-second overview: there are about 6000 newsgroups, each dedicated to some topic of discussion. People can post articles to a group; the article is a bunch of text (like an email) that gets distributed worldwide. People can also read others' posts. This description is very brief, so if you're still lost, try doing a web search for "newsgroup".

Get connected

The first step is to connect to a news server. My method of choice is to edit my .emacs file to contain something like:

  (setq gnus-select-method
    '(nntp "my.newsserver.machine"    ; fill in your server!  (see below)
           (nntp-port-number 119)))
Then, either restart emacs, or just put the cursor on the 'setq' and type M-C-x (aka Alt-Ctrl-x).

(I like to keep the port number explicitly specified (119 in the above example). While 119 is the default if you don't specify anything, I access servers on nonstandard ports often enough that I want to immediately know the syntax when I need it. I recommend you do the same.)

Now, attempt to connect to the news server: M-x gnus. You should briefly see an ascii-art gnu (some kind of animal), then be presented with a short list of groups. gnu.emacs.gnus is usually one, and news.announce.newusers may be there too.

It's not always easy to know which news server to use. Often, simply "news" will work. If not, ask your system administrator. On campus at UC Berkeley, "" is the correct server. You can test your newsserver outside emacs:

  % telnet 119
  Connected to
  Escape character is '^]'.
  200 InterNetNews NNRP server INN 2.2.2 13-Dec-1999 ready (posting ok).
  telnet> close
  Connection closed.
If you see "connection refused" or similar, instead of the NNTP banner like above, then your server or port number is wrong.

The newsgroup list

When you're looking at the list of newsgroups, there are several things you can do:

Like all the key-binding lists in this tutorial, this list is not complete, and you can change the bindings if you like. To see the current list of bindings, type C-h b.

The group summary list

Once you go into a group, you see the list of unread articles in that group. There's a bunch of things you can do here:

I still don't know how to toggle whether read articles are displayed. If you catchup, then re-enter the group, it shows all the (now read) messages...

Reading an article

When you select an article to read, the Emacs window will split horizontally, with the article on the bottom and the list of messages at the top.

The main keys when reading an article are:

Article composition

When you decide to compose an article, either a new one or a followup to someone else's article, you'll be in the article composition mode. Here, you edit the text that will be posted.

Note: There's an excellent chance the default colors will look absolutely dreadful. See tweaks, below, to see how to fix this.

When you're editing an article to post, normal editing key-bindings are in effect. If you want to add a new header line, or modify an existing one, just do it -- they're ordinary text.

When you're ready to post the article, use C-c C-c. Unless there's a problem, this will post the article immediately (but see tweaks).

If you change your mind, and don't want to post after all, you just kill the composition buffer: C-x k.

Since this is a newsgroup tutorial, I'm obligated to make a few comments about article style:


As Gnus is an Emacs app written in elisp (Emacs lisp), it is possible to customize its behavior to a large degree. I've collected a few common ones here.

The "customize" interface

Like many elements of Emacs, Gnus' behavior can be modified via the "customize" interface. You can access it as M-x customize. Then choose Applications, then News, and finally Gnus.

"customize" has a poor user interface, and isn't all that well organized, so it can be hard to use. But it points the way when you're wondering if something can be done easily.

Changing the colors

The default colors range from tolerable to utterly unreadable, depending on the background color you've set Emacs to use.

The easiest way to change them is to use M-x customize-face. This presents you with a list of all the "faces" (fonts/colors) used anywhere in Emacs. Find the ones that pertain to Gnus (or sometimes Mail or Message, since these packages share faces) and change them to suit your taste. (The "customize" interface is quite awkward... it will take a bit of getting used to.)

The process of changing faces is fairly tedious, owing to the very large number of faces Gnus uses. I dislike this aspect of Gnus (3 or 4 would have been plenty) but do not know a better solution.

Confirm before post

When you hit C-c C-c to post a composed article, Gnus fills in some headers for you. Sometimes (me: always) you want to look over the headers before they actually get sent around the world. (Example: spammers harvest posters' email addresses, so if I'm posting to a public group I want to make sure it's not using my real email address.)

Gnus will ask for confirmation if it detects an error in the article, but otherwise it just goes out without asking. Since I always want it to ask, I've added this to my .emacs:

  ; load `message' now so I can override functions
  (require 'message)
  (defun message-check-news-syntax ()
    "Check the syntax of the message."
           ;; We narrow to the headers and check them first.
           ;; Check the body.
      ; sm: this last line is my addition
      (y-or-n-p "Post the message? ")

This is a re-definition of the message-check-news-syntax function. I wish I could find a less hacky way to do this, but there does not appear the be a hook in the proper place.

Getting the right From address

The user-mail-address variable specifies the "From" address in emails and newsgroup posts. However, for reasons that aren't clear to me, if you have it set to e.g. "Foo <foo@bar>", Gnus just uses the "foo@bar" part.

To make Gnus use the full user-mail-address, I added to my .emacs:

  (require 'message)
  ; allow comments (real name) in my addr
  (defun message-make-address ()
    "Make the address of the user."
    (or user-mail-address
        (concat (user-login-name) "@" (message-make-domain))))
Like above, this overrides a function in Gnus, which is more of a hack than I'd like, but I could not find a better solution.

More Information

The only other source I know of is the Emacs docs: