merge trunk
[emacs.git] / etc / gnus-tut.txt
blobca8dd11d8aa129500d3cab593a012d14cb5475e7
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, 2006, 2007,
28 ;;   2008, 2009, 2010  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 of the License, or
38 ;; (at your option) 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.  If not, see <http://www.gnu.org/licenses/>.
48 From lars Thu Feb 23 23:20:38 1995
49 From: larsi@ifi.uio.no (ding)
50 Date: Fri Feb 24 13:40:45 1995
51 Subject: Starting up
52 Message-ID: <lars-doc2@eyesore.no>
54 If you are having problems with Gnus not finding your server, you have
55 to set `gnus-select-method'.  A "method" is a way of specifying *how*
56 the news is to be found, and from *where*.
58 Say you want to read news from you local, friendly nntp server
59 "news.my.local.server".
61 (setq gnus-select-method '(nntp "news.my.local.server"))
63 Quite easy, huh?
65 From the news spool:
67 (setq gnus-select-method '(nnspool ""))
69 From your mh-e spool:
71 (setq gnus-select-method '(nnmh ""))
73 There's a whole bunch of other methods for reading mail and news, see
74 the "Foreign groups" article for that.
77 From lars Thu Feb 23 23:20:38 1995
78 From: larsi@ifi.uio.no (ding)
79 Date: Fri Feb 24 13:40:45 1995
80 Subject: Where are all the groups, then?
81 Message-ID: <lars-doc3@eyesore.no>
83 If this is the first time you have used a newsreader, you won't have a
84 .newsrc file.  This means that Gnus will think that all the newsgroups
85 on the server are "new", and kill them all.
87 If you have a .newsrc file, the new groups will be processed with the
88 function in the `gnus-subscribe-newsgroup-method' variable, which is
89 `gnus-subscribe-zombies' by default.
91 This means that all the groups have been made into "zombies" - not
92 quite dead, but not exactly alive, either.
94 Jump back to the *Group* buffer, and type `A z' to list all the zombie
95 groups.  Look though the list, and subscribe to the groups you want to
96 read by pressing `u' on the one you think look interesting.
98 If all the groups have been killed, type `A k' to list all the killed
99 groups.  Subscribe to them the same way.
101 When you are satisfied, press `S z' to kill all the zombie groups.
103 Now you should have a nice list of all groups you are interested in.
105 (If you later want to subscribe to more groups, press `A k' to
106 list all the kill groups, and repeat.  You can also type `U' and be
107 prompted for groups to subscribe to.)
110 From lars Thu Feb 23 23:20:38 1995
111 From: larsi@ifi.uio.no (ding)
112 Date: Fri Feb 24 13:40:45 1995
113 Subject: I want to read my mail!
114 Message-ID: <lars-doc4@eyesore.no>
116 Yes, Virginia, you can read mail with Gnus.
118 First you have to decide which mail backend you want to use.  You have
119 nnml, which is a one-file-one-mail backend, which is quite nice, but
120 apt to make your systems administrator go crazy and come after you
121 with a shotgun.
123 nnmbox uses a Unix mail box to store mail.  Nice, but slow.
125 nnmh uses mh-e folders, which is also a one-file-one-mail thingie, but
126 slower than nnml.  (It doesn't support NOV files.)
128 So if you want to go with nnmbox, you can simply say:
130 (setq gnus-secondary-select-methods '((nnmbox "")))
132 (The same for the other methods, kind of.)
134 You should also set `nnmail-split-methods' to something sensible:
136 (setq nnmail-split-methods
137       '(("mail.junk" "From:.*Lars")
138         ("mail.misc "")))
140 This will put all mail from me in you junk mail group, and the rest in
141 "mail.misc".
143 These groups will be subscribe the same way as the normal groups, so
144 you will probably find them among the zombie groups after you set
145 these variables and re-start Gnus.
148 From lars Thu Feb 23 23:20:38 1995
149 From: larsi@ifi.uio.no (ding)
150 Date: Fri Feb 24 13:40:45 1995
151 Subject: Foreign newsgroups
152 Message-ID: <lars-doc5@eyesore.no>
154 These are groups that do not come from `gnus-select-method'.
156 Say you want to read "alt.furniture.couches" from "news.funet.fi".  You
157 can then either type `B news.funet.fi <RET>' to browse that server and
158 subscribe to that group, or you can type
159 `G m alt.furniture.couches<RET>nntp<RET>news.funet.fi<RET>', if you
160 like to type a lot.
162 If you want to read a directory as a newsgroup, you can create an
163 nndir group, much the same way.  There's a shorthand for that,
164 though.  If, for instance, you want to read the (ding) list archives,
165 you could type `G d /ftp <RET>'.
167 There's lots more to know about foreign groups, but you have to read
168 the info pages to find out more.
171 From lars Thu Feb 23 23:20:38 1995
172 From: larsi@ifi.uio.no (ding)
173 Date: Fri Feb 24 13:40:45 1995
174 Subject: Low level changes in GNUS, or, Wrong type argument: stringp, nil
175 Message-ID: <lars-doc6@eyesore.no>
177 Gnus really isn't GNUS, even though it looks like it.  If you scrape
178 the surface, you'll find that most things have changed.
180 This means that old code that relies on GNUS internals will fail.
182 In particular, `gnus-newsrc-hashtb', `gnus-newsrc-assoc',
183 `gnus-killed-list', the `nntp-header-' macros and the display formats
184 have all changed.  If you have some code lying around that depend on
185 these, or change these, you'll have to re-write your code.
187 Old hilit19 code does not work at all.  In fact, you should probably
188 remove all hilit code from all the Gnus hooks
189 (`gnus-group-prepare-hook', `gnus-summary-prepare-hook' and
190 `gnus-summary-article-hook').  (Well, at the very least the first
191 two.)  Gnus provides various integrated functions for highlighting,
192 which are both faster and more accurated.
194 There is absolutely no chance, whatsoever, of getting Gnus to work
195 with Emacs 18.  It won't even work on Emacsen older than Emacs
196 19.30/XEmacs 19.13.  Upgrade your Emacs or die.
199 From lars Thu Feb 23 23:20:38 1995
200 From: larsi@ifi.uio.no (ding)
201 Date: Fri Feb 24 13:40:45 1995
202 Subject: How do I re-scan my mail groups?
203 Message-ID: <lars-doc8@eyesore.no>
205 Reading the active file from the nntp server is a drag.
207 Just press `M-g' on the mail groups, and they will be re-scanned.
209 You can also re-scan all the mail groups by putting them on level 1
210 (`S l 1'), and saying `1 g' to re-scan all level 1 groups.
213 From lars Thu Feb 23 23:20:38 1995
214 From: larsi@ifi.uio.no (ding)
215 Date: Fri Feb 24 13:40:45 1995
216 Subject: How do I set up virtual newsgroups?
217 Message-ID: <lars-doc9@eyesore.no>
219 Virtual newsgroups are collections of other newsgroups.  Why people
220 want this is beyond me, but here goes:
222 Create the group by saying
224 `G m my.virtual.newsgroup<RET>nnvirtual<RET>^rec\.aquaria\.*<RET>'
226 This will create the group "nnvirtual:my.virtual.newsgroup", which
227 will collect all articles from all the groups in the "rec.aquaria"
228 hierarchy.
230 If you want to edit the regular expression, just type `M-e' on the
231 group line.
233 Note that all the groups that are part of the virtual group have to be
234 alive.  This means that the cannot, absolutely not, be zombie or
235 killed.  They can be unsubscribed; that's no problem.
237 You can combine groups from different servers in the same virtual
238 newsgroup, something that may actually be useful.  Say you have the
239 group "comp.headers" on the server "news.server.no" and the same group
240 on "news.server.edu".  If people have posted articles with Distribution
241 headers that stop propagation of their articles, combining these two
242 newsgroups into one virtual newsgroup should give you a better view of
243 what's going on.
245 One caveat, though: The virtual group article numbers from the first
246 source group (group A) will always be lower than the article numbers
247 from the second (group B).  This means that Gnus will believe that
248 articles from group A are older than articles from group B.  Threading
249 will lessen these problems, but it might be a good idea to sort the
250 threads over the date of the articles to get a correct feel for the
251 flow of the groups:
253 (setq gnus-thread-sort-functions '(gnus-thread-sort-by-date))
255 If you only want this in virtual groups, you could say something along
256 the lines of:
258 (setq gnus-select-group-hook
259       (lambda ()
260         (if (eq 'nnvirtual (car (gnus-find-method-for-group
261                                   gnus-newsgroup-name)))
262             (progn
263               (make-local-variable 'gnus-thread-sort-functions)
264               (setq gnus-thread-sort-functions '(gnus-thread-sort-by-date))))))
267 From lars Thu Feb 23 23:20:38 1995
268 From: larsi@ifi.uio.no (ding)
269 Date: Fri Feb 24 13:40:45 1995
270 Subject: Bugs & stuff
271 Message-ID: <lars-doc7@eyesore.no>
273 If you want to report a bug, please type `M-x gnus-bug'.  This will
274 give me a precise overview of your Gnus and Emacs version numbers,
275 along with a look at all Gnus variables you have changed.
277 Du not expect a reply back, but your bug should be fixed in the next
278 version.  If the bug persists, please re-submit your bug report.
280 When a bug occurs, I need a recipe for how to trigger the bug.  You
281 have to tell me exactly what you do to uncover the bug, and you should
282 (setq debug-on-error t) and send me the backtrace along with the bug
283 report.
285 If I am not able to reproduce the bug, I won't be able to fix it.
287 I would, of course, prefer that you locate the bug, fix it, and mail
288 me the patches, but one can't have everything.
290 If you have any questions on usage, the "ding@ifi.uio.no" mailing list
291 is where to post the questions.