Add arch tagline
[emacs.git] / etc / gnus-tut.txt
blob9a8dbfcc96156fc0715508ab66072bb0f86632d3
1 From lars Thu Feb 23 23:20:38 1995
2 From: larsi@ifi.uio.no (ding)
3 Date: Fri Feb 24 13:40:45 1995
4 Subject: So you want to use the new Gnus
5 Message-ID: <lars-doc1@eyesore.no>
7 Actually, since you are reading this, chances are you are already
8 using the new Gnus.  Congratulations.
10 This entire newsgroup you are reading is, in fact, no real newsgroup
11 at all, in the traditional sense.  It is an example of one of the
12 "foreign" select methods that Gnus may use.
14 The text you are now reading is stored in the "etc" directory with the
15 rest of the Emacs sources.  You are using the "nndoc" backend for
16 accessing it.  Scary, isn't it?
18 This isn't the real documentation.  `M-x info', `m gnus <RET>' to read
19 that.  This "newsgroup" is intended as a kinder, gentler way of getting
20 people started.
22 Gnus is a rewrite of GNUS 4.1, written by Masanobu Umeda.  The rewrite
23 was done by moi, yours truly, your humble servant, Lars Magne
24 Ingebrigtsen.  If you have a WWW browser, you can investigate to your
25 heart's delight at <URL:http://www.ifi.uio.no/~larsi/larsi.html>.
27 ;; Copyright (C) 1995, 2001, 2002, 2003, 2004, 2005,
28 ;;   2006, 2007, 2008  Free Software Foundation, Inc.
30 ;; Author: Lars Magne Ingebrigtsen <larsi@ifi.uio.no>
31 ;; Keywords: news
33 ;; This file is part of GNU Emacs.
35 ;; GNU Emacs is free software; you can redistribute it and/or modify
36 ;; it under the terms of the GNU General Public License as published by
37 ;; the Free Software Foundation; either version 3, or (at your option)
38 ;; any later version.
40 ;; GNU Emacs is distributed in the hope that it will be useful,
41 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
42 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
43 ;; GNU General Public License for more details.
45 ;; You should have received a copy of the GNU General Public License
46 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
47 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
48 ;; Boston, MA 02110-1301, USA.
50 From lars Thu Feb 23 23:20:38 1995
51 From: larsi@ifi.uio.no (ding)
52 Date: Fri Feb 24 13:40:45 1995
53 Subject: Starting up
54 Message-ID: <lars-doc2@eyesore.no>
56 If you are having problems with Gnus not finding your server, you have
57 to set `gnus-select-method'.  A "method" is a way of specifying *how*
58 the news is to be found, and from *where*.
60 Say you want to read news from you local, friendly nntp server
61 "news.my.local.server".
63 (setq gnus-select-method '(nntp "news.my.local.server"))
65 Quite easy, huh?
67 From the news spool:
69 (setq gnus-select-method '(nnspool ""))
71 From your mh-e spool:
73 (setq gnus-select-method '(nnmh ""))
75 There's a whole bunch of other methods for reading mail and news, see
76 the "Foreign groups" article for that.
79 From lars Thu Feb 23 23:20:38 1995
80 From: larsi@ifi.uio.no (ding)
81 Date: Fri Feb 24 13:40:45 1995
82 Subject: Where are all the groups, then?
83 Message-ID: <lars-doc3@eyesore.no>
85 If this is the first time you have used a newsreader, you won't have a
86 .newsrc file.  This means that Gnus will think that all the newsgroups
87 on the server are "new", and kill them all.
89 If you have a .newsrc file, the new groups will be processed with the
90 function in the `gnus-subscribe-newsgroup-method' variable, which is
91 `gnus-subscribe-zombies' by default.
93 This means that all the groups have been made into "zombies" - not
94 quite dead, but not exactly alive, either.
96 Jump back to the *Group* buffer, and type `A z' to list all the zombie
97 groups.  Look though the list, and subscribe to the groups you want to
98 read by pressing `u' on the one you think look interesting.
100 If all the groups have been killed, type `A k' to list all the killed
101 groups.  Subscribe to them the same way.
103 When you are satisfied, press `S z' to kill all the zombie groups.
105 Now you should have a nice list of all groups you are interested in.
107 (If you later want to subscribe to more groups, press `A k' to
108 list all the kill groups, and repeat.  You can also type `U' and be
109 prompted for groups to subscribe to.)
112 From lars Thu Feb 23 23:20:38 1995
113 From: larsi@ifi.uio.no (ding)
114 Date: Fri Feb 24 13:40:45 1995
115 Subject: I want to read my mail!
116 Message-ID: <lars-doc4@eyesore.no>
118 Yes, Virginia, you can read mail with Gnus.
120 First you have to decide which mail backend you want to use.  You have
121 nnml, which is a one-file-one-mail backend, which is quite nice, but
122 apt to make your systems administrator go crazy and come after you
123 with a shotgun.
125 nnmbox uses a Unix mail box to store mail.  Nice, but slow.
127 nnmh uses mh-e folders, which is also a one-file-one-mail thingie, but
128 slower than nnml.  (It doesn't support NOV files.)
130 So if you want to go with nnmbox, you can simply say:
132 (setq gnus-secondary-select-methods '((nnmbox "")))
134 (The same for the other methods, kind of.)
136 You should also set `nnmail-split-methods' to something sensible:
138 (setq nnmail-split-methods
139       '(("mail.junk" "From:.*Lars")
140         ("mail.misc "")))
142 This will put all mail from me in you junk mail group, and the rest in
143 "mail.misc".
145 These groups will be subscribe the same way as the normal groups, so
146 you will probably find them among the zombie groups after you set
147 these variables and re-start Gnus.
150 From lars Thu Feb 23 23:20:38 1995
151 From: larsi@ifi.uio.no (ding)
152 Date: Fri Feb 24 13:40:45 1995
153 Subject: Foreign newsgroups
154 Message-ID: <lars-doc5@eyesore.no>
156 These are groups that do not come from `gnus-select-method'.
158 Say you want to read "alt.furniture.couches" from "news.funet.fi".  You
159 can then either type `B news.funet.fi <RET>' to browse that server and
160 subscribe to that group, or you can type
161 `G m alt.furniture.couches<RET>nntp<RET>news.funet.fi<RET>', if you
162 like to type a lot.
164 If you want to read a directory as a newsgroup, you can create an
165 nndir group, much the same way.  There's a shorthand for that,
166 though.  If, for instance, you want to read the (ding) list archives,
167 you could type `G d /ftp <RET>'.
169 There's lots more to know about foreign groups, but you have to read
170 the info pages to find out more.
173 From lars Thu Feb 23 23:20:38 1995
174 From: larsi@ifi.uio.no (ding)
175 Date: Fri Feb 24 13:40:45 1995
176 Subject: Low level changes in GNUS, or, Wrong type argument: stringp, nil
177 Message-ID: <lars-doc6@eyesore.no>
179 Gnus really isn't GNUS, even though it looks like it.  If you scrape
180 the surface, you'll find that most things have changed.
182 This means that old code that relies on GNUS internals will fail.
184 In particular, `gnus-newsrc-hashtb', `gnus-newsrc-assoc',
185 `gnus-killed-list', the `nntp-header-' macros and the display formats
186 have all changed.  If you have some code lying around that depend on
187 these, or change these, you'll have to re-write your code.
189 Old hilit19 code does not work at all.  In fact, you should probably
190 remove all hilit code from all the Gnus hooks
191 (`gnus-group-prepare-hook', `gnus-summary-prepare-hook' and
192 `gnus-summary-article-hook').  (Well, at the very least the first
193 two.)  Gnus provides various integrated functions for highlighting,
194 which are both faster and more accurated.
196 There is absolutely no chance, whatsoever, of getting Gnus to work
197 with Emacs 18.  It won't even work on Emacsen older than Emacs
198 19.30/XEmacs 19.13.  Upgrade your Emacs or die.
201 From lars Thu Feb 23 23:20:38 1995
202 From: larsi@ifi.uio.no (ding)
203 Date: Fri Feb 24 13:40:45 1995
204 Subject: How do I re-scan my mail groups?
205 Message-ID: <lars-doc8@eyesore.no>
207 Reading the active file from the nntp server is a drag.
209 Just press `M-g' on the mail groups, and they will be re-scanned.
211 You can also re-scan all the mail groups by putting them on level 1
212 (`S l 1'), and saying `1 g' to re-scan all level 1 groups.
215 From lars Thu Feb 23 23:20:38 1995
216 From: larsi@ifi.uio.no (ding)
217 Date: Fri Feb 24 13:40:45 1995
218 Subject: How do I set up virtual newsgroups?
219 Message-ID: <lars-doc9@eyesore.no>
221 Virtual newsgroups are collections of other newsgroups.  Why people
222 want this is beyond me, but here goes:
224 Create the group by saying
226 `G m my.virtual.newsgroup<RET>nnvirtual<RET>^rec\.aquaria\.*<RET>'
228 This will create the group "nnvirtual:my.virtual.newsgroup", which
229 will collect all articles from all the groups in the "rec.aquaria"
230 hierarchy.
232 If you want to edit the regular expression, just type `M-e' on the
233 group line.
235 Note that all the groups that are part of the virtual group have to be
236 alive.  This means that the cannot, absolutely not, be zombie or
237 killed.  They can be unsubscribed; that's no problem.
239 You can combine groups from different servers in the same virtual
240 newsgroup, something that may actually be useful.  Say you have the
241 group "comp.headers" on the server "news.server.no" and the same group
242 on "news.server.edu".  If people have posted articles with Distribution
243 headers that stop propagation of their articles, combining these two
244 newsgroups into one virtual newsgroup should give you a better view of
245 what's going on.
247 One caveat, though: The virtual group article numbers from the first
248 source group (group A) will always be lower than the article numbers
249 from the second (group B).  This means that Gnus will believe that
250 articles from group A are older than articles from group B.  Threading
251 will lessen these problems, but it might be a good idea to sort the
252 threads over the date of the articles to get a correct feel for the
253 flow of the groups:
255 (setq gnus-thread-sort-functions '(gnus-thread-sort-by-date))
257 If you only want this in virtual groups, you could say something along
258 the lines of:
260 (setq gnus-select-group-hook
261       (lambda ()
262         (if (eq 'nnvirtual (car (gnus-find-method-for-group
263                                   gnus-newsgroup-name)))
264             (progn
265               (make-local-variable 'gnus-thread-sort-functions)
266               (setq gnus-thread-sort-functions '(gnus-thread-sort-by-date))))))
269 From lars Thu Feb 23 23:20:38 1995
270 From: larsi@ifi.uio.no (ding)
271 Date: Fri Feb 24 13:40:45 1995
272 Subject: Bugs & stuff
273 Message-ID: <lars-doc7@eyesore.no>
275 If you want to report a bug, please type `M-x gnus-bug'.  This will
276 give me a precise overview of your Gnus and Emacs version numbers,
277 along with a look at all Gnus variables you have changed.
279 Du not expect a reply back, but your bug should be fixed in the next
280 version.  If the bug persists, please re-submit your bug report.
282 When a bug occurs, I need a recipe for how to trigger the bug.  You
283 have to tell me exactly what you do to uncover the bug, and you should
284 (setq debug-on-error t) and send me the backtrace along with the bug
285 report.
287 If I am not able to reproduce the bug, I won't be able to fix it.
289 I would, of course, prefer that you locate the bug, fix it, and mail
290 me the patches, but one can't have everything.
292 If you have any questions on usage, the "ding@ifi.uio.no" mailing list
293 is where to post the questions.