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