Update copyright year to 2016
[gnus] / etc / gnus-tut.txt
1 From lars Thu Feb 23 23:20:38 1995
2 From: larsi@gnus.org (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>
6
7 Actually, since you are reading this, chances are you are already
8 using the new Gnus.  Congratulations.
9
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.
13
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?
17
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.
21
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.gnus.org/> and
26 <URL:http://quimby.gnus.org/lmi/>.
27
28 ;; Copyright (C) 1995, 2001-2016 Free Software Foundation, Inc.
29
30 ;; Author: Lars Magne Ingebrigtsen <larsi@ifi.uio.no>
31 ;; Keywords: news
32
33 ;; This file is part of GNU Emacs.
34
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.
39
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.
44
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/>.
47
48 From lars Thu Feb 23 23:20:38 1995
49 From: larsi@gnus.org (ding)
50 Date: Fri Feb 24 13:40:45 1995
51 Subject: Starting up
52 Message-ID: <lars-doc2@eyesore.no>
53
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*.
57
58 Say you want to read news from you local, friendly nntp server
59 "news.my.local.server".
60
61 (setq gnus-select-method '(nntp "news.my.local.server"))
62
63 Quite easy, huh?
64
65 From the news spool:
66
67 (setq gnus-select-method '(nnspool ""))
68
69 From your mh-e spool:
70
71 (setq gnus-select-method '(nnmh ""))
72
73 There's a whole bunch of other methods for reading mail and news, see
74 the "Foreign groups" article for that.
75
76
77 From lars Thu Feb 23 23:20:38 1995
78 From: larsi@gnus.org (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>
82
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.
86
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.
90
91 This means that all the groups have been made into "zombies" - not
92 quite dead, but not exactly alive, either.
93
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.
97
98 If all the groups have been killed, type `A k' to list all the killed
99 groups.  Subscribe to them the same way.
100
101 When you are satisfied, press `S z' to kill all the zombie groups.
102
103 Now you should have a nice list of all groups you are interested in.
104
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.)
108
109
110 From lars Thu Feb 23 23:20:38 1995
111 From: larsi@gnus.org (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>
115
116 Yes, Virginia, you can read mail with Gnus.
117
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.
122
123 nnmbox uses a Unix mail box to store mail.  Nice, but slow.
124
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.)
127
128 So if you want to go with nnmbox, you can simply say:
129
130 (setq gnus-secondary-select-methods '((nnmbox "")))
131
132 (The same for the other methods, kind of.)
133
134 You should also set `nnmail-split-methods' to something sensible:
135
136 (setq nnmail-split-methods
137       '(("mail.junk" "From:.*Lars")
138         ("mail.misc "")))
139
140 This will put all mail from me in you junk mail group, and the rest in
141 "mail.misc".
142
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.
146
147
148 From lars Thu Feb 23 23:20:38 1995
149 From: larsi@gnus.org (ding)
150 Date: Fri Feb 24 13:40:45 1995
151 Subject: Foreign newsgroups
152 Message-ID: <lars-doc5@eyesore.no>
153
154 These are groups that do not come from `gnus-select-method'.
155
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.
161
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>'.
166
167 There's lots more to know about foreign groups, but you have to read
168 the info pages to find out more.
169
170
171 From lars Thu Feb 23 23:20:38 1995
172 From: larsi@gnus.org (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>
176
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.
179
180 This means that old code that relies on GNUS internals will fail.
181
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.
186
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 accurate.
193
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 20.7/XEmacs 21.1.  Upgrade your Emacs or die.
197
198
199 From lars Thu Feb 23 23:20:38 1995
200 From: larsi@gnus.org (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>
204
205 Reading the active file from the nntp server is a drag.
206
207 Just press `M-g' on the mail groups, and they will be re-scanned.
208
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.
211
212
213 From lars Thu Feb 23 23:20:38 1995
214 From: larsi@gnus.org (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>
218
219 Virtual newsgroups are collections of other newsgroups.  Why people
220 want this is beyond me, but here goes:
221
222 Create the group by saying
223
224 `G m my.virtual.newsgroup<RET>nnvirtual<RET>^rec\.aquaria\.*<RET>'
225
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.
229
230 If you want to edit the regular expression, just type `M-e' on the
231 group line.
232
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.
236
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.
244
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:
252
253 (setq gnus-thread-sort-functions '(gnus-thread-sort-by-date))
254
255 If you only want this in virtual groups, you could say something along
256 the lines of:
257
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))))))
265
266
267 From lars Thu Feb 23 23:20:38 1995
268 From: larsi@gnus.org (ding)
269 Date: Fri Feb 24 13:40:45 1995
270 Subject: Bugs & stuff
271 Message-ID: <lars-doc7@eyesore.no>
272
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.
276
277 Do 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.
279
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.
284
285 If I am not able to reproduce the bug, I won't be able to fix it.
286
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.
289
290 If you have any questions on usage, the "ding@gnus.org" mailing list
291 is where to post the questions.
292
293
294 From fschmitt Sat Mar 22 18:13:00 2003
295 From: faq@my.gnus.org (Gnus FAQ team)
296 Date: Sat Mar 22 18:13:00 2003
297 Subject: Gnus FAQ (Frequently Asked Questions)
298 Message-ID: <lars-doc9@eyesore.no>
299
300 The Gnus FAQ is distributed within the Gnus manual.  The home page of
301 the Gnus FAQ is <URL:http://my.gnus.org/FAQ/>, where you can find the
302 most recent version in HTML various other formats.
303
304 To browse the FAQ now, put the cursor at the end of the following line
305 and press `C-x C-e':
306
307   (info "(gnus)Frequently Asked Questions")
308
309 On older XEmacs version, use:
310
311   (Info-goto-node "(gnus)Frequently Asked Questions")
312
313 Or simply use RET or the middle mouse button, if the above is displayed
314 as a clickable button.