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