* gnus.el: Fixed all the doc strings to match the FSF convetions.
[gnus] / lisp / gnus.el
1 ;;; gnus.el --- a newsreader for GNU Emacs
2 ;; Copyright (C) 1987-1990,1993-1999 Free Software Foundation, Inc.
3
4 ;; Author: Masanobu UMEDA <umerin@flab.flab.fujitsu.junet>
5 ;;      Lars Magne Ingebrigtsen <larsi@gnus.org>
6 ;; Keywords: news, mail
7
8 ;; This file is part of GNU Emacs.
9
10 ;; GNU Emacs is free software; you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation; either version 2, or (at your option)
13 ;; any later version.
14
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18 ;; GNU General Public License for more details.
19
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
22 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
23 ;; Boston, MA 02111-1307, USA.
24
25 ;;; Commentary:
26
27 ;;; Code:
28
29 (eval '(run-hooks 'gnus-load-hook))
30
31 (eval-when-compile (require 'cl))
32 (require 'mm-util)
33
34 (require 'custom)
35 (eval-and-compile
36   (if (< emacs-major-version 20)
37       (require 'gnus-load)))
38 (require 'message)
39
40 (defgroup gnus nil
41   "The coffee-brewing, all singing, all dancing, kitchen sink newsreader."
42   :group 'news
43   :group 'mail)
44
45 (defgroup gnus-charset nil
46   "Group character set issues."
47   :link '(custom-manual "(gnus)Charsets")
48   :group 'gnus)
49
50 (defgroup gnus-cache nil
51   "Cache interface."
52   :group 'gnus)
53
54 (defgroup gnus-start nil
55   "Starting your favorite newsreader."
56   :group 'gnus)
57
58 (defgroup gnus-start-server nil
59   "Server options at startup."
60   :group 'gnus-start)
61
62 ;; These belong to gnus-group.el.
63 (defgroup gnus-group nil
64   "Group buffers."
65   :link '(custom-manual "(gnus)The Group Buffer")
66   :group 'gnus)
67
68 (defgroup gnus-group-foreign nil
69   "Foreign groups."
70   :link '(custom-manual "(gnus)Foreign Groups")
71   :group 'gnus-group)
72
73 (defgroup gnus-group-new nil
74   "Automatic subscription of new groups."
75   :group 'gnus-group)
76
77 (defgroup gnus-group-levels nil
78   "Group levels."
79   :link '(custom-manual "(gnus)Group Levels")
80   :group 'gnus-group)
81
82 (defgroup gnus-group-select nil
83   "Selecting a Group."
84   :link '(custom-manual "(gnus)Selecting a Group")
85   :group 'gnus-group)
86
87 (defgroup gnus-group-listing nil
88   "Showing slices of the group list."
89   :link '(custom-manual "(gnus)Listing Groups")
90   :group 'gnus-group)
91
92 (defgroup gnus-group-visual nil
93   "Sorting the group buffer."
94   :link '(custom-manual "(gnus)Group Buffer Format")
95   :group 'gnus-group
96   :group 'gnus-visual)
97
98 (defgroup gnus-group-various nil
99   "Various group options."
100   :link '(custom-manual "(gnus)Scanning New Messages")
101   :group 'gnus-group)
102
103 ;; These belong to gnus-sum.el.
104 (defgroup gnus-summary nil
105   "Summary buffers."
106   :link '(custom-manual "(gnus)The Summary Buffer")
107   :group 'gnus)
108
109 (defgroup gnus-summary-exit nil
110   "Leaving summary buffers."
111   :link '(custom-manual "(gnus)Exiting the Summary Buffer")
112   :group 'gnus-summary)
113
114 (defgroup gnus-summary-marks nil
115   "Marks used in summary buffers."
116   :link '(custom-manual "(gnus)Marking Articles")
117   :group 'gnus-summary)
118
119 (defgroup gnus-thread nil
120   "Ordering articles according to replies."
121   :link '(custom-manual "(gnus)Threading")
122   :group 'gnus-summary)
123
124 (defgroup gnus-summary-format nil
125   "Formatting of the summary buffer."
126   :link '(custom-manual "(gnus)Summary Buffer Format")
127   :group 'gnus-summary)
128
129 (defgroup gnus-summary-choose nil
130   "Choosing Articles."
131   :link '(custom-manual "(gnus)Choosing Articles")
132   :group 'gnus-summary)
133
134 (defgroup gnus-summary-maneuvering nil
135   "Summary movement commands."
136   :link '(custom-manual "(gnus)Summary Maneuvering")
137   :group 'gnus-summary)
138
139 (defgroup gnus-summary-mail nil
140   "Mail group commands."
141   :link '(custom-manual "(gnus)Mail Group Commands")
142   :group 'gnus-summary)
143
144 (defgroup gnus-summary-sort nil
145   "Sorting the summary buffer."
146   :link '(custom-manual "(gnus)Sorting")
147   :group 'gnus-summary)
148
149 (defgroup gnus-summary-visual nil
150   "Highlighting and menus in the summary buffer."
151   :link '(custom-manual "(gnus)Summary Highlighting")
152   :group 'gnus-visual
153   :group 'gnus-summary)
154
155 (defgroup gnus-summary-various nil
156   "Various summary buffer options."
157   :link '(custom-manual "(gnus)Various Summary Stuff")
158   :group 'gnus-summary)
159
160 (defgroup gnus-summary-pick nil
161   "Pick mode in the summary buffer."
162   :link '(custom-manual "(gnus)Pick and Read")
163   :prefix "gnus-pick-"
164   :group 'gnus-summary)
165
166 (defgroup gnus-summary-tree nil
167   "Tree display of threads in the summary buffer."
168   :link '(custom-manual "(gnus)Tree Display")
169   :prefix "gnus-tree-"
170   :group 'gnus-summary)
171
172 ;; Belongs to gnus-uu.el
173 (defgroup gnus-extract-view nil
174   "Viewing extracted files."
175   :link '(custom-manual "(gnus)Viewing Files")
176   :group 'gnus-extract)
177
178 ;; Belongs to gnus-score.el
179 (defgroup gnus-score nil
180   "Score and kill file handling."
181   :group 'gnus)
182
183 (defgroup gnus-score-kill nil
184   "Kill files."
185   :group 'gnus-score)
186
187 (defgroup gnus-score-adapt nil
188   "Adaptive score files."
189   :group 'gnus-score)
190
191 (defgroup gnus-score-default nil
192   "Default values for score files."
193   :group 'gnus-score)
194
195 (defgroup gnus-score-expire nil
196   "Expiring score rules."
197   :group 'gnus-score)
198
199 (defgroup gnus-score-decay nil
200   "Decaying score rules."
201   :group 'gnus-score)
202
203 (defgroup gnus-score-files nil
204   "Score and kill file names."
205   :group 'gnus-score
206   :group 'gnus-files)
207
208 (defgroup gnus-score-various nil
209   "Various scoring and killing options."
210   :group 'gnus-score)
211
212 ;; Other
213 (defgroup gnus-visual nil
214   "Options controling the visual fluff."
215   :group 'gnus
216   :group 'faces)
217
218 (defgroup gnus-agent nil
219   "Offline support for Gnus."
220   :group 'gnus)
221
222 (defgroup gnus-files nil
223   "Files used by Gnus."
224   :group 'gnus)
225
226 (defgroup gnus-dribble-file nil
227   "Auto save file."
228   :link '(custom-manual "(gnus)Auto Save")
229   :group 'gnus-files)
230
231 (defgroup gnus-newsrc nil
232   "Storing Gnus state."
233   :group 'gnus-files)
234
235 (defgroup gnus-server nil
236   "Options related to newsservers and other servers used by Gnus."
237   :group 'gnus)
238
239 (defgroup gnus-message '((message custom-group))
240   "Composing replies and followups in Gnus."
241   :group 'gnus)
242
243 (defgroup gnus-meta nil
244   "Meta variables controling major portions of Gnus.
245 In general, modifying these variables does not take affect until Gnus
246 is restarted, and sometimes reloaded."
247   :group 'gnus)
248
249 (defgroup gnus-various nil
250   "Other Gnus options."
251   :link '(custom-manual "(gnus)Various Various")
252   :group 'gnus)
253
254 (defgroup gnus-mime nil
255   "Variables for controlling the Gnus MIME interface."
256   :group 'gnus)
257
258 (defgroup gnus-exit nil
259   "Exiting gnus."
260   :link '(custom-manual "(gnus)Exiting Gnus")
261   :group 'gnus)
262
263 (defconst gnus-version-number "5.8.3"
264   "Version number for this version of Gnus.")
265
266 (defconst gnus-version (format "Gnus v%s" gnus-version-number)
267   "Version string for this version of Gnus.")
268
269 (defcustom gnus-inhibit-startup-message nil
270   "If non-nil, the startup message will not be displayed.
271 This variable is used before `.gnus.el' is loaded, so it should
272 be set in `.emacs' instead."
273   :group 'gnus-start
274   :type 'boolean)
275
276 (defcustom gnus-play-startup-jingle nil
277   "If non-nil, play the Gnus jingle at startup."
278   :group 'gnus-start
279   :type 'boolean)
280
281 (unless (featurep 'gnus-xmas)
282   (defalias 'gnus-make-overlay 'make-overlay)
283   (defalias 'gnus-delete-overlay 'delete-overlay)
284   (defalias 'gnus-overlay-put 'overlay-put)
285   (defalias 'gnus-move-overlay 'move-overlay)
286   (defalias 'gnus-overlay-end 'overlay-end)
287   (defalias 'gnus-extent-detached-p 'ignore)
288   (defalias 'gnus-extent-start-open 'ignore)
289   (defalias 'gnus-set-text-properties 'set-text-properties)
290   (defalias 'gnus-group-remove-excess-properties 'ignore)
291   (defalias 'gnus-appt-select-lowest-window 'appt-select-lowest-window)
292   (defalias 'gnus-mail-strip-quoted-names 'mail-strip-quoted-names)
293   (defalias 'gnus-character-to-event 'identity)
294   (defalias 'gnus-add-text-properties 'add-text-properties)
295   (defalias 'gnus-put-text-property 'put-text-property)
296   (defalias 'gnus-mode-line-buffer-identification 'identity)
297   (defalias 'gnus-characterp 'numberp)
298   (defalias 'gnus-deactivate-mark 'deactivate-mark)
299   (defalias 'gnus-window-edges 'window-edges)
300   (defalias 'gnus-key-press-event-p 'numberp)
301   (defalias 'gnus-decode-rfc1522 'ignore))
302
303 ;; We define these group faces here to avoid the display
304 ;; update forced when creating new faces.
305
306 (defface gnus-group-news-1-face
307   '((((class color)
308       (background dark))
309      (:foreground "PaleTurquoise" :bold t))
310     (((class color)
311       (background light))
312      (:foreground "ForestGreen" :bold t))
313     (t
314      ()))
315   "Level 1 newsgroup face.")
316
317 (defface gnus-group-news-1-empty-face
318   '((((class color)
319       (background dark))
320      (:foreground "PaleTurquoise"))
321     (((class color)
322       (background light))
323      (:foreground "ForestGreen"))
324     (t
325      ()))
326   "Level 1 empty newsgroup face.")
327
328 (defface gnus-group-news-2-face
329   '((((class color)
330       (background dark))
331      (:foreground "turquoise" :bold t))
332     (((class color)
333       (background light))
334      (:foreground "CadetBlue4" :bold t))
335     (t
336      ()))
337   "Level 2 newsgroup face.")
338
339 (defface gnus-group-news-2-empty-face
340   '((((class color)
341       (background dark))
342      (:foreground "turquoise"))
343     (((class color)
344       (background light))
345      (:foreground "CadetBlue4"))
346     (t
347      ()))
348   "Level 2 empty newsgroup face.")
349
350 (defface gnus-group-news-3-face
351   '((((class color)
352       (background dark))
353      (:bold t))
354     (((class color)
355       (background light))
356      (:bold t))
357     (t
358      ()))
359   "Level 3 newsgroup face.")
360
361 (defface gnus-group-news-3-empty-face
362   '((((class color)
363       (background dark))
364      ())
365     (((class color)
366       (background light))
367      ())
368     (t
369      ()))
370   "Level 3 empty newsgroup face.")
371
372 (defface gnus-group-news-4-face
373   '((((class color)
374       (background dark))
375      (:bold t))
376     (((class color)
377       (background light))
378      (:bold t))
379     (t
380      ()))
381   "Level 4 newsgroup face.")
382
383 (defface gnus-group-news-4-empty-face
384   '((((class color)
385       (background dark))
386      ())
387     (((class color)
388       (background light))
389      ())
390     (t
391      ()))
392   "Level 4 empty newsgroup face.")
393
394 (defface gnus-group-news-5-face
395   '((((class color)
396       (background dark))
397      (:bold t))
398     (((class color)
399       (background light))
400      (:bold t))
401     (t
402      ()))
403   "Level 5 newsgroup face.")
404
405 (defface gnus-group-news-5-empty-face
406   '((((class color)
407       (background dark))
408      ())
409     (((class color)
410       (background light))
411      ())
412     (t
413      ()))
414   "Level 5 empty newsgroup face.")
415
416 (defface gnus-group-news-6-face
417   '((((class color)
418       (background dark))
419      (:bold t))
420     (((class color)
421       (background light))
422      (:bold t))
423     (t
424      ()))
425   "Level 6 newsgroup face.")
426
427 (defface gnus-group-news-6-empty-face
428   '((((class color)
429       (background dark))
430      ())
431     (((class color)
432       (background light))
433      ())
434     (t
435      ()))
436   "Level 6 empty newsgroup face.")
437
438 (defface gnus-group-news-low-face
439   '((((class color)
440       (background dark))
441      (:foreground "DarkTurquoise" :bold t))
442     (((class color)
443       (background light))
444      (:foreground "DarkGreen" :bold t))
445     (t
446      ()))
447   "Low level newsgroup face.")
448
449 (defface gnus-group-news-low-empty-face
450   '((((class color)
451       (background dark))
452      (:foreground "DarkTurquoise"))
453     (((class color)
454       (background light))
455      (:foreground "DarkGreen"))
456     (t
457      ()))
458   "Low level empty newsgroup face.")
459
460 (defface gnus-group-mail-1-face
461   '((((class color)
462       (background dark))
463      (:foreground "aquamarine1" :bold t))
464     (((class color)
465       (background light))
466      (:foreground "DeepPink3" :bold t))
467     (t
468      (:bold t)))
469   "Level 1 mailgroup face.")
470
471 (defface gnus-group-mail-1-empty-face
472   '((((class color)
473       (background dark))
474      (:foreground "aquamarine1"))
475     (((class color)
476       (background light))
477      (:foreground "DeepPink3"))
478     (t
479      (:italic t :bold t)))
480   "Level 1 empty mailgroup face.")
481
482 (defface gnus-group-mail-2-face
483   '((((class color)
484       (background dark))
485      (:foreground "aquamarine2" :bold t))
486     (((class color)
487       (background light))
488      (:foreground "HotPink3" :bold t))
489     (t
490      (:bold t)))
491   "Level 2 mailgroup face.")
492
493 (defface gnus-group-mail-2-empty-face
494   '((((class color)
495       (background dark))
496      (:foreground "aquamarine2"))
497     (((class color)
498       (background light))
499      (:foreground "HotPink3"))
500     (t
501      (:bold t)))
502   "Level 2 empty mailgroup face.")
503
504 (defface gnus-group-mail-3-face
505   '((((class color)
506       (background dark))
507      (:foreground "aquamarine3" :bold t))
508     (((class color)
509       (background light))
510      (:foreground "magenta4" :bold t))
511     (t
512      (:bold t)))
513   "Level 3 mailgroup face.")
514
515 (defface gnus-group-mail-3-empty-face
516   '((((class color)
517       (background dark))
518      (:foreground "aquamarine3"))
519     (((class color)
520       (background light))
521      (:foreground "magenta4"))
522     (t
523      ()))
524   "Level 3 empty mailgroup face.")
525
526 (defface gnus-group-mail-low-face
527   '((((class color)
528       (background dark))
529      (:foreground "aquamarine4" :bold t))
530     (((class color)
531       (background light))
532      (:foreground "DeepPink4" :bold t))
533     (t
534      (:bold t)))
535   "Low level mailgroup face.")
536
537 (defface gnus-group-mail-low-empty-face
538   '((((class color)
539       (background dark))
540      (:foreground "aquamarine4"))
541     (((class color)
542       (background light))
543      (:foreground "DeepPink4"))
544     (t
545      (:bold t)))
546   "Low level empty mailgroup face.")
547
548 ;; Summary mode faces.
549
550 (defface gnus-summary-selected-face '((t
551                                        (:underline t)))
552   "Face used for selected articles.")
553
554 (defface gnus-summary-cancelled-face
555   '((((class color))
556      (:foreground "yellow" :background "black")))
557   "Face used for cancelled articles.")
558
559 (defface gnus-summary-high-ticked-face
560   '((((class color)
561       (background dark))
562      (:foreground "pink" :bold t))
563     (((class color)
564       (background light))
565      (:foreground "firebrick" :bold t))
566     (t
567      (:bold t)))
568   "Face used for high interest ticked articles.")
569
570 (defface gnus-summary-low-ticked-face
571   '((((class color)
572       (background dark))
573      (:foreground "pink" :italic t))
574     (((class color)
575       (background light))
576      (:foreground "firebrick" :italic t))
577     (t
578      (:italic t)))
579   "Face used for low interest ticked articles.")
580
581 (defface gnus-summary-normal-ticked-face
582   '((((class color)
583       (background dark))
584      (:foreground "pink"))
585     (((class color)
586       (background light))
587      (:foreground "firebrick"))
588     (t
589      ()))
590   "Face used for normal interest ticked articles.")
591
592 (defface gnus-summary-high-ancient-face
593   '((((class color)
594       (background dark))
595      (:foreground "SkyBlue" :bold t))
596     (((class color)
597       (background light))
598      (:foreground "RoyalBlue" :bold t))
599     (t
600      (:bold t)))
601   "Face used for high interest ancient articles.")
602
603 (defface gnus-summary-low-ancient-face
604   '((((class color)
605       (background dark))
606      (:foreground "SkyBlue" :italic t))
607     (((class color)
608       (background light))
609      (:foreground "RoyalBlue" :italic t))
610     (t
611      (:italic t)))
612   "Face used for low interest ancient articles.")
613
614 (defface gnus-summary-normal-ancient-face
615   '((((class color)
616       (background dark))
617      (:foreground "SkyBlue"))
618     (((class color)
619       (background light))
620      (:foreground "RoyalBlue"))
621     (t
622      ()))
623   "Face used for normal interest ancient articles.")
624
625 (defface gnus-summary-high-unread-face
626   '((t
627      (:bold t)))
628   "Face used for high interest unread articles.")
629
630 (defface gnus-summary-low-unread-face
631   '((t
632      (:italic t)))
633   "Face used for low interest unread articles.")
634
635 (defface gnus-summary-normal-unread-face
636   '((t
637      ()))
638   "Face used for normal interest unread articles.")
639
640 (defface gnus-summary-high-read-face
641   '((((class color)
642       (background dark))
643      (:foreground "PaleGreen"
644                   :bold t))
645     (((class color)
646       (background light))
647      (:foreground "DarkGreen"
648                   :bold t))
649     (t
650      (:bold t)))
651   "Face used for high interest read articles.")
652
653 (defface gnus-summary-low-read-face
654   '((((class color)
655       (background dark))
656      (:foreground "PaleGreen"
657                   :italic t))
658     (((class color)
659       (background light))
660      (:foreground "DarkGreen"
661                   :italic t))
662     (t
663      (:italic t)))
664   "Face used for low interest read articles.")
665
666 (defface gnus-summary-normal-read-face
667   '((((class color)
668       (background dark))
669      (:foreground "PaleGreen"))
670     (((class color)
671       (background light))
672      (:foreground "DarkGreen"))
673     (t
674      ()))
675   "Face used for normal interest read articles.")
676
677
678 ;;;
679 ;;; Gnus buffers
680 ;;;
681
682 (defvar gnus-buffers nil)
683
684 (defun gnus-get-buffer-create (name)
685   "Do the same as `get-buffer-create', but store the created buffer."
686   (or (get-buffer name)
687       (car (push (get-buffer-create name) gnus-buffers))))
688
689 (defun gnus-add-buffer ()
690   "Add the current buffer to the list of Gnus buffers."
691   (push (current-buffer) gnus-buffers))
692
693 (defun gnus-buffers ()
694   "Return a list of live Gnus buffers."
695   (while (and gnus-buffers
696               (not (buffer-name (car gnus-buffers))))
697     (pop gnus-buffers))
698   (let ((buffers gnus-buffers))
699     (while (cdr buffers)
700       (if (buffer-name (cadr buffers))
701           (pop buffers)
702         (setcdr buffers (cddr buffers)))))
703   gnus-buffers)
704
705 ;;; Splash screen.
706
707 (defvar gnus-group-buffer "*Group*")
708
709 (eval-and-compile
710   (autoload 'gnus-play-jingle "gnus-audio"))
711
712 (defface gnus-splash-face
713   '((((class color)
714       (background dark))
715      (:foreground "Brown"))
716     (((class color)
717       (background light))
718      (:foreground "Brown"))
719     (t
720      ()))
721   "Face of the splash screen.")
722
723 (defun gnus-splash ()
724   (save-excursion
725     (switch-to-buffer (gnus-get-buffer-create gnus-group-buffer))
726     (let ((buffer-read-only nil))
727       (erase-buffer)
728       (unless gnus-inhibit-startup-message
729         (gnus-group-startup-message)
730         (sit-for 0)
731         (when gnus-play-startup-jingle
732           (gnus-play-jingle))))))
733
734 (defun gnus-indent-rigidly (start end arg)
735   "Indent rigidly using only spaces and no tabs."
736   (save-excursion
737     (save-restriction
738       (narrow-to-region start end)
739       (let ((tab-width 8))
740         (indent-rigidly start end arg)
741         ;; We translate tabs into spaces -- not everybody uses
742         ;; an 8-character tab.
743         (goto-char (point-min))
744         (while (search-forward "\t" nil t)
745           (replace-match "        " t t))))))
746
747 (defvar gnus-simple-splash nil)
748
749 (defun gnus-group-startup-message (&optional x y)
750   "Insert startup message in current buffer."
751   ;; Insert the message.
752   (erase-buffer)
753   (insert
754    (format "              %s
755           _    ___ _             _
756           _ ___ __ ___  __    _ ___
757           __   _     ___    __  ___
758               _           ___     _
759              _  _ __             _
760              ___   __            _
761                    __           _
762                     _      _   _
763                    _      _    _
764                       _  _    _
765                   __  ___
766                  _   _ _     _
767                 _   _
768               _    _
769              _    _
770             _
771           __
772
773 "
774            ""))
775   ;;&nbs