*** empty log message ***
[emacs.git] / etc / gnus-tut.txt
bloba76b591dbf18d9e01bba1aa5e35e1bb916310fcc
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 Free Software Foundation, Inc.
29 ;; Author: Lars Magne Ingebrigtsen <larsi@ifi.uio.no>
30 ;; Keywords: news
32 ;; This file is part of GNU Emacs.
34 ;; GNU Emacs is free software; you can redistribute it and/or modify
35 ;; it under the terms of the GNU General Public License as published by
36 ;; the Free Software Foundation; either version 2, or (at your option)
37 ;; any later version.
39 ;; GNU Emacs is distributed in the hope that it will be useful,
40 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
41 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
42 ;; GNU General Public License for more details.
44 ;; You should have received a copy of the GNU General Public License
45 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
46 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
47 ;; Boston, MA 02111-1307, USA.
49 From lars Thu Feb 23 23:20:38 1995
50 From: larsi@ifi.uio.no (ding)
51 Date: Fri Feb 24 13:40:45 1995
52 Subject: Starting up
53 Message-ID: <lars-doc2@eyesore.no>
55 If you are having problems with Gnus not finding your server, you have
56 to set `gnus-select-method'.  A "method" is a way of specifying *how*
57 the news is to be found, and from *where*.
59 Say you want to read news from you local, friendly nntp server
60 "news.my.local.server".
62 (setq gnus-select-method '(nntp "news.my.local.server"))
64 Quite easy, huh?
66 From the news spool:
68 (setq gnus-select-method '(nnspool ""))
70 From your mh-e spool:
72 (setq gnus-select-method '(nnmh ""))
74 There's a whole bunch of other methods for reading mail and news, see
75 the "Foreign groups" article for that.
78 From lars Thu Feb 23 23:20:38 1995
79 From: larsi@ifi.uio.no (ding)
80 Date: Fri Feb 24 13:40:45 1995
81 Subject: Where are all the groups, then?
82 Message-ID: <lars-doc3@eyesore.no>
84 If this is the first time you have used a newsreader, you won't have a
85 .newsrc file.  This means that Gnus will think that all the newsgroups
86 on the server are "new", and kill them all.
88 If you have a .newsrc file, the new groups will be processed with the
89 function in the `gnus-subscribe-newsgroup-method' variable, which is
90 `gnus-subscribe-zombies' by default.
92 This means that all the groups have been made into "zombies" - not
93 quite dead, but not exactly alive, either.
95 Jump back to the *Group* buffer, and type `A z' to list all the zombie
96 groups.  Look though the list, and subscribe to the groups you want to
97 read by pressing `u' on the one you think look interesting.
99 If all the groups have been killed, type `A k' to list all the killed
100 groups.  Subscribe to them the same way.
102 When you are satisfied, press `S z' to kill all the zombie groups.
104 Now you should have a nice list of all groups you are interested in.
106 (If you later want to subscribe to more groups, press `A k' to
107 list all the kill groups, and repeat.  You can also type `U' and be
108 prompted for groups to subscribe to.)
111 From lars Thu Feb 23 23:20:38 1995
112 From: larsi@ifi.uio.no (ding)
113 Date: Fri Feb 24 13:40:45 1995
114 Subject: I want to read my mail!
115 Message-ID: <lars-doc4@eyesore.no>
117 Yes, Virginia, you can read mail with Gnus.
119 First you have to decide which mail backend you want to use.  You have
120 nnml, which is a one-file-one-mail backend, which is quite nice, but
121 apt to make your systems administrator go crazy and come after you
122 with a shotgun.
124 nnmbox uses a Unix mail box to store mail.  Nice, but slow.
126 nnmh uses mh-e folders, which is also a one-file-one-mail thingie, but
127 slower than nnml.  (It doesn't support NOV files.)
129 So if you want to go with nnmbox, you can simply say:
131 (setq gnus-secondary-select-methods '((nnmbox "")))
133 (The same for the other methods, kind of.)
135 You should also set `nnmail-split-methods' to something sensible:
137 (setq nnmail-split-methods
138       '(("mail.junk" "From:.*Lars")
139         ("mail.misc "")))
141 This will put all mail from me in you junk mail group, and the rest in
142 "mail.misc".
144 These groups will be subscribe the same way as the normal groups, so
145 you will probably find them among the zombie groups after you set
146 these variables and re-start Gnus.
149 From lars Thu Feb 23 23:20:38 1995
150 From: larsi@ifi.uio.no (ding)
151 Date: Fri Feb 24 13:40:45 1995
152 Subject: Foreign newsgroups
153 Message-ID: <lars-doc5@eyesore.no>
155 These are groups that do not come from `gnus-select-method'.
157 Say you want to read "alt.furniture.couches" from "news.funet.fi".  You
158 can then either type `B news.funet.fi <RET>' to browse that server and
159 subscribe to that group, or you can type
160 `G m alt.furniture.couches<RET>nntp<RET>news.funet.fi<RET>', if you
161 like to type a lot.
163 If you want to read a directory as a newsgroup, you can create an
164 nndir group, much the same way.  There's a shorthand for that,
165 though.  If, for instance, you want to read the (ding) list archives,
166 you could type `G d /ftp <RET>'.
168 There's lots more to know about foreign groups, but you have to read
169 the info pages to find out more.
172 From lars Thu Feb 23 23:20:38 1995
173 From: larsi@ifi.uio.no (ding)
174 Date: Fri Feb 24 13:40:45 1995
175 Subject: Low level changes in GNUS, or, Wrong type argument: stringp, nil
176 Message-ID: <lars-doc6@eyesore.no>
178 Gnus really isn't GNUS, even though it looks like it.  If you scrape
179 the surface, you'll find that most things have changed.
181 This means that old code that relies on GNUS internals will fail.
183 In particular, `gnus-newsrc-hashtb', `gnus-newsrc-assoc',
184 `gnus-killed-list', the `nntp-header-' macros and the display formats
185 have all changed.  If you have some code lying around that depend on
186 these, or change these, you'll have to re-write your code.
188 Old hilit19 code does not work at all.  In fact, you should probably
189 remove all hilit code from all the Gnus hooks
190 (`gnus-group-prepare-hook', `gnus-summary-prepare-hook' and
191 `gnus-summary-article-hook').  (Well, at the very least the first
192 two.)  Gnus provides various integrated functions for highlighting,
193 which are both faster and more accurated.
195 There is absolutely no chance, whatsoever, of getting Gnus to work
196 with Emacs 18.  It won't even work on Emacsen older than Emacs
197 19.30/XEmacs 19.13.  Upgrade your Emacs or die.
200 From lars Thu Feb 23 23:20:38 1995
201 From: larsi@ifi.uio.no (ding)
202 Date: Fri Feb 24 13:40:45 1995
203 Subject: How do I re-scan my mail groups?
204 Message-ID: <lars-doc8@eyesore.no>
206 Reading the active file from the nntp server is a drag.
208 Just press `M-g' on the mail groups, and they will be re-scanned.
210 You can also re-scan all the mail groups by putting them on level 1
211 (`S l 1'), and saying `1 g' to re-scan all level 1 groups.
214 From lars Thu Feb 23 23:20:38 1995
215 From: larsi@ifi.uio.no (ding)
216 Date: Fri Feb 24 13:40:45 1995
217 Subject: How do I set up virtual newsgroups?
218 Message-ID: <lars-doc9@eyesore.no>
220 Virtual newsgroups are collections of other newsgroups.  Why people
221 want this is beyond me, but here goes:
223 Create the group by saying
225 `M-a my.virtual.newsgroup<RET>nnvirtual<RET>^rec\.aquaria\.*<RET>'
227 This will create the group "nnvirtual:my.virtual.newsgroup", which
228 will collect all articles from all the groups in the "rec.aquaria"
229 hierarchy.
231 If you want to edit the regular expression, just type `M-e' on the
232 group line.
234 Note that all the groups that are part of the virtual group have to be
235 alive.  This means that the cannot, absolutely not, be zombie or
236 killed.  They can be unsubscribed; that's no problem.
238 You can combine groups from different servers in the same virtual
239 newsgroup, something that may actually be useful.  Say you have the
240 group "comp.headers" on the server "news.server.no" and the same group
241 on "news.server.edu".  If people have posted articles with Distribution
242 headers that stop propagation of their articles, combining these two
243 newsgroups into one virtual newsgroup should give you a better view of
244 what's going on.
246 One caveat, though: The virtual group article numbers from the first
247 source group (group A) will always be lower than the article numbers
248 from the second (group B).  This means that Gnus will believe that
249 articles from group A are older than articles from group B.  Threading
250 will lessen these problems, but it might be a good idea to sort the
251 threads over the date of the articles to get a correct feel for the
252 flow of the groups:
254 (setq gnus-thread-sort-functions '(gnus-thread-sort-by-date))
256 If you only want this in virtual groups, you could say something along
257 the lines of:
259 (setq gnus-select-group-hook
260       (lambda ()
261         (if (eq 'nnvirtual (car (gnus-find-method-for-group
262                                   gnus-newsgroup-name)))
263             (progn
264               (make-local-variable 'gnus-thread-sort-functions)
265               (setq gnus-thread-sort-functions '(gnus-thread-sort-by-date))))))
268 From lars Thu Feb 23 23:20:38 1995
269 From: larsi@ifi.uio.no (ding)
270 Date: Fri Feb 24 13:40:45 1995
271 Subject: Bugs & stuff
272 Message-ID: <lars-doc7@eyesore.no>
274 If you want to report a bug, please type `M-x gnus-bug'.  This will
275 give me a precise overview of your Gnus and Emacs version numbers,
276 along with a look at all Gnus variables you have changed.
278 Du not expect a reply back, but your bug should be fixed in the next
279 version.  If the bug persists, please re-submit your bug report.
281 When a bug occurs, I need a recipe for how to trigger the bug.  You
282 have to tell me exactly what you do to uncover the bug, and you should
283 (setq debug-on-error t) and send me the backtrace along with the bug
284 report.
286 If I am not able to reproduce the bug, I won't be able to fix it.
288 I would, of course, prefer that you locate the bug, fix it, and mail
289 me the patches, but one can't have everything.
291 If you have any questions on usage, the "ding@ifi.uio.no" mailing list
292 is where to post the questions.