+2005-11-10 Reiner Steib <Reiner.Steib@gmx.de>
+
+ * gnus-coding.texi (Gnus Coding Style): Add MIME subsection.
+ (Gnus Maintainance Guide): Improvements.
+
+ * gnus.texi (Sorting the Summary Buffer): Replace 2005-10-29
+ change by a reference to `Group Parameters'. Use `(not ...)' in
+ example instead of `lambda' expression.
+ (Group Parameters): Add simplified sorting example based on
+ example for `Sorting the Summary Buffer' from Jari Aalto
+ <jari.aalto@cante.net>.
+ (Example Methods): Add example for an indirect connection.
+
2005-11-10 Katsumi Yamaoka <yamaoka@jpl.org>
* gnus.texi (XVarious): Fix description of gnus-use-toolbar; add
Emacs mail mode. There should be no Gnus dependencies in
@file{message.el}.
+@subsection Emacs @acronym{MIME}
+
+The files @file{mml*.el} and @file{mm-*.el} provide @acronym{MIME}
+functionality for Emacs.
+
+@acronym{MML} (@acronym{MIME} Meta Language) is supposed to be
+independent from Gnus. Alas it is not anymore.
+
+
@subsection Gnus backends
The files @file{nn*.el} provide functionality for accessing NNTP
(@file{nntp.el}), IMAP (@file{nnimap.el}) and several other Mail back
ends (probably @file{nnml.el}, @file{nnfolder.el} and
-@file{nnmaildir.el} are the ones most widely used mail back ends).
+@file{nnmaildir.el} are the most widely used mail back ends).
@c message / gnus
@section Compatibility
-@c Compatibility with XEmacs and older Emacs versions in v5-10 and in the
-@c trunk.
-
-@c @table
-@c x
-@c @end table
+@c Compatibility with XEmacs and older Emacs versions in v5-10 and in
+@c the trunk.
+
+No Gnus should work on:
+@itemize @bullet
+@item
+Emacs 21.1 and up.
+@item
+XEmacs 21.4 and up.
+@end itemize
+
+Gnus 5.10 should work on:
+@itemize @bullet
+@item
+Emacs 20.7 and up.
+@item
+XEmacs 21.1 and up.
+@end itemize
@node Gnus Maintainance Guide
@chapter Gnus Maintainance Guide
@section Stable and development versions
-The CVS trunk is developed quite actively.
-
-@c Most of the time Gnus is developed on the trunk.
-
-@c Exeption: several month of feature freeze after a release,
-@c e.g. 5.10.1
+The development of Gnus normally is done on the CVS trunk, i.e. there
+are no separate branches to develop and test new features. Most of the
+time, the trunk is developed quite actively with more or less daily
+changes. Only after a new major release, e.g. 5.10.1, there's usually a
+feature period of several months. After the release of Gnus 5.10.6 the
+development of new features started again on the trunk while the 5.10
+series is continued on the stable branch (v5-10) from which more stable
+releases will be done when needed (5.10.7, @dots{}).
+Stable releases of Gnus finally become part of Emacs. E.g. Gnus 5.8
+became a part of Emacs 21 (relabeled to Gnus 5.9). The 5.10 series will
+become part of Emacs 22 (as Gnus 5.11).
@section Syncing
@c <v9eklyke6b.fsf@marauder.physik.uni-ulm.de>
@c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp>
-I do Emacs->Gnus less often (than Gnus->Emacs) because it tends to
-require more manual work.
-
-By default I sync about once a week. I also try to follow any Gnus
-threads on the mailing lists and make sure any changes being discussed
-are kept more up-to-date (so say 1-2 days delay for "topical" changes).
-
-
-@c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp>
-
-BTW, just to add even more verbose explanation about the syncing thing:
-
-Basically my idea is that the Emacs-Gnus gateway will cause all common
-files in Emacs and Gnus v5-10 to be identical except when there's a very
-good reason (e.g., the Gnus version string in Emacs says "5.11", but the
-v5-10 version string remains "5.10.whatever"). Furthermore, all changes
-in these files in either Emacs or the v5-10 branch will be installed
-into the Gnus CVS trunk, again except where there's a good reason
-(typically so far the only exception has been that the changes already
-exist in the trunk in modified form). Because of this, when the next
-Emacs Gnus upgrade comes, it should be very easy -- just plonk in the
-files from the Gnus trunk without worrying about lost changes from the
-Emacs tree.
+In the past, the inclusion of Gnus into Emacs was quite cumbersome. For
+each change made to Gnus in Emacs repository, it had to be checked that
+it was applied to the new Gnus version, too. Else, bug fixes done in
+Emacs repository might have been lost.
+
+With the inclusion of Gnus 5.10, Miles Bader has set up an Emacs-Gnus
+gateway to ensure the bug fixes from Emacs CVS are propagated to Gnus
+CVS semi-automatically. These bug fixes are installed on the stable
+branch and on the trunk. Basically the idea is that the gateway will
+cause all common files in Emacs and Gnus v5-10 to be identical except
+when there's a very good reason (e.g., the Gnus version string in Emacs
+says @samp{5.11}, but the v5-10 version string remains @samp{5.10.x}).
+Furthermore, all changes in these files in either Emacs or the v5-10
+branch will be installed into the Gnus CVS trunk, again except where
+there's a good reason.
+@c (typically so far the only exception has been that the changes
+@c already exist in the trunk in modified form).
+Because of this, when the next major version of Gnus will be included in
+Emacs, it should be very easy -- just plonk in the files from the Gnus
+trunk without worrying about lost changes from the Emacs tree.
The effect of this is that as hacker, you should generally only have to
make changes in one place:
- 1) If it's a file which is thought of as being outside of Gnus (e.g.,
- the new "encrypt.el"), you should probably make the change in the
- Emacs tree, and it will show up in the Gnus tree a few days later.
-
- If you don't have Emacs CVS access (or it's inconvenient), you can
- change such a file in the v5-10 branch, and it should propagate to
- Emacs CVS -- however, it will get some extra scrutiny (by me) to see
- if the changes are possibly controversial and need discussion on the
- mailing list. [Many changes are obvious bug-fixes however, so often
- there won't be any problem.]
-
- 2) If it's to a Gnus file, and it's important enough that it should be
- part of Emacs/v5-10, then you can make the change on the v5-10
- branch, and it will go into Emacs CVS and the Gnus CVS trunk (a few
- days later).
-
- If you know that there will be conflicts (perhaps because the
- affected source code is different in v5-10 and the Gnus CVS trunk),
- then you can install your change in both places, and when I try to
- sync them, there will be a conflict -- however, since in most such
- cases there would be a conflict _anyway_, it's often easier for me
- to resolve it simply if I see two "identical" changes, and can just
- choose the proper one, rather than having to actually fix the code.
-
- 3) For general Gnus development changes, of course you just make the
- change on the Gnus CVS trunk and it goes into Emacs a few years
- later... :-)
+@itemize
+@item
+If it's a file which is thought of as being outside of Gnus (e.g., the
+new @file{encrypt.el}), you should probably make the change in the Emacs
+tree, and it will show up in the Gnus tree a few days later.
+
+If you don't have Emacs CVS access (or it's inconvenient), you can
+change such a file in the v5-10 branch, and it should propagate to Emacs
+CVS -- however, it will get some extra scrutiny (by Miles) to see if the
+changes are possibly controversial and need discussion on the mailing
+list. Many changes are obvious bug-fixes however, so often there won't
+be any problem.
+
+@item
+If it's to a Gnus file, and it's important enough that it should be part
+of Emacs and the v5-10 branch, then you can make the change on the v5-10
+branch, and it will go into Emacs CVS and the Gnus CVS trunk (a few days
+later). The most prominent examples for such changes are bug-fixed
+including improvements on the documentation.
+
+If you know that there will be conflicts (perhaps because the affected
+source code is different in v5-10 and the Gnus CVS trunk), then you can
+install your change in both places, and when I try to sync them, there
+will be a conflict -- however, since in most such cases there would be a
+conflict @emph{anyway}, it's often easier for me to resolve it simply if
+I see two @samp{identical} changes, and can just choose the proper one,
+rather than having to actually fix the code.
+
+@item
+For general Gnus development changes, of course you just make the
+change on the Gnus CVS trunk and it goes into Emacs a few years
+later... :-)
+@end itemize
Of course in any case, if you just can't wait for me to sync your
change, you can commit it in more than one place and probably there will
such multiple commits, like whitespace differences, and unify those ;-).
+@c I do Emacs->Gnus less often (than Gnus->Emacs) because it tends to
+@c require more manual work.
+
+@c By default I sync about once a week. I also try to follow any Gnus
+@c threads on the mailing lists and make sure any changes being discussed
+@c are kept more up-to-date (so say 1-2 days delay for "topical" changes).
+
+@c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp>
+
+@c BTW, just to add even more verbose explanation about the syncing thing:
+
@section Miscellanea
@heading @file{GNUS-NEWS}
\e$B$r\e(B @code{nil} \e$B$K@_Dj$7$F2<$5$$!#$"$k$$$O!"$=$l$i$,>o$KBgJ8;z$H>.J8;z$r6h\e(B
\e$BJL$7$J$$$h$&$K$7$?$$$J$i!"$=$l$r\e(B @code{t} \e$B$K@_Dj$7$F2<$5$$!#\e(B
+@code{gnus-parameters} \e$B$r2p$9$k$3$H$K$h$C$F!"%0%k!<%W$K$h$C$F0[$J$kJB$Y\e(B
+\e$BBX$($rDj5A$9$k$3$H$,$G$-$^$9!#$3$l$O!"\e(B@acronym{NNTP} \e$B$G$OI=Bj$G!"\e(B
+@acronym{RSS} \e$B%0%k!<%W$G$O:G?7$N%K%e!<%9$,@hF,$K$J$k$h$&$KF|IU$G!"$=$l$>\e(B
+\e$B$lJB$YBX$($r9T$J$&Nc$G$9!#$3$NNc$N:G=i$N%0%k!<%W$O!"\e(Bnews.gmane.org \e$B$+$i\e(B
+\e$B<hF@$9$k\e(B Debian \e$B$N%G%$%j!<%K%e!<%9$G$9!#\e(B@acronym{RSS} \e$B%0%k!<%W$O!"\e(BRSS
+\e$B%U%#!<%I$GG[?.$5$l$F$$$k\e(B Debian \e$B$N%&%#!<%/%j!<%K%e!<\e(B
+\e$B%9\e(B @url{http://packages.debian.org/unstable/newpkg_main.en.rdf} \e$B$KBP1~$7\e(B
+\e$B$^$9!#\e(B@xref{RSS}.
+
+@lisp
+(setq
+ gnus-parameters
+ '(("nntp.*gmane\\.debian\\.user\\.news"
+ (gnus-show-threads nil)
+ (gnus-article-sort-functions '((not gnus-article-sort-by-date)))
+ (gnus-use-adaptive-scoring nil)
+ (gnus-use-scoring nil))
+ ("nnrss.*debian"
+ (gnus-show-threads nil)
+ (gnus-article-sort-functions 'gnus-article-sort-by-subject)
+ (gnus-use-adaptive-scoring nil)
+ (gnus-use-scoring t)
+ (gnus-score-find-score-files-function 'gnus-score-find-single)
+ (gnus-summary-line-format "%U%R%z%d %I%(%[ %s %]%)\n"))))
+@end lisp
+
@node Listing Groups
@section \e$B%0%k!<%W$N0lMwI=<(\e(B
@cindex group listing
@lisp
(setq gnus-thread-sort-functions
- '((lambda (t1 t2)
- (not (gnus-thread-sort-by-number t1 t2)))
+ '((not gnus-thread-sort-by-number)
gnus-thread-sort-by-score))
@end lisp
-\e$B$5$i$KJL$NNc!#%0%k!<%W$K$h$C$F0[$J$kJB$SBX$($rDj5A$9$k$3$H$,$G$-$^$9!#$3\e(B
-\e$B$3$K$"$kNc$O!"0l$D$N\e(B @acronym{NNTP} \e$B$G$OI=Bj$K$h$C$FJB$SBX$($r9T$$!"\e(B
-@acronym{RSS} \e$B%0%k!<%W$G$O!"@hF,$G:G?7$N%K%e!<%9$r8+$k$?$a$K!"F|IU$GJB$Y\e(B
-\e$BBX$($^$9!#\e(B(\e$BLuCm\e(B: \e$B$3$NNc$O\e(B @code{cl} \e$B$r>o;~FI$_9~$_$^$9!#FC$K\e(B Emacs \e$B$G$3\e(B
-\e$B$N$h$&$J@_Dj$r;H$&I,MW$,@8$8$?$H$-$O!"\e(B@code{cl} \e$B$rI,MW$H$7$J$$%3!<%I$K=q\e(B
-\e$B$-49$($k$3$H$r9MN8$7$F2<$5$$!#Fq$7$/$O$"$j$^$;$s!#\e(B)
-
-@lisp
-(require 'cl)
-
-(defun my-gnus-summary-mode-hook-group-select ()
- (flet ((lsetq (x val) ;; Local setq
- (set (make-local-variable x) val)))
- (cond
- ;; In Group buffer to make Debian daily news group press: G m
- ;; and point it to nntp server news.gmane.org and
- ;; group gmane.linux.debian.user.news
- ((string-match "nntp.*debian.user.news" gnus-newsgroup-name)
- (lsetq 'gnus-show-threads nil)
- (lsetq 'gnus-article-sort-functions 'gnus-article-sort-by-date-reverse)
- (lsetq 'gnus-use-adaptive-scoring nil)
- (lsetq 'gnus-use-scoring nil))
- ;; In Group buffer to read Debian weekly news RSS feed press: G R
- ;; and point it to url:
- ;; http://packages.debian.org/unstable/newpkg_main.en.rdf
- ((string-match "nnrss.*debian" gnus-newsgroup-name)
- (lsetq 'gnus-show-threads nil)
- (lsetq 'gnus-article-sort-functions 'gnus-article-sort-by-subject)
- (lsetq 'gnus-use-adaptive-scoring nil)
- (lsetq 'gnus-use-scoring t)
- (lsetq 'gnus-score-find-score-files-function 'gnus-score-find-single)
- (lsetq 'gnus-summary-line-format "%U%R%z%d %I%(%[ %s %]%)\n")))))
-
-(defun my-gnus-summary-mode-hook ()
- (my-gnus-summary-mode-hook-group-select))
-@end lisp
-
@vindex gnus-thread-score-function
\e$BJQ?t\e(B @code{gnus-thread-score-function} (\e$B%G%#%U%)%k%H$O\e(B @code{+}) \e$B$K@_Dj\e(B
\e$B$5$l$F$$$k4X?t$O!"%9%l%C%I$NAm%9%3%"$r7W;;$9$k$?$a$KMQ$$$i$l$^$9!#LrN)$D\e(B
gnus-article-sort-by-subject))
@end lisp
+@code{gnus-parameters} \e$B$r2p$9$k$3$H$K$h$C$F!"%0%k!<%W$K$h$C$F0[$J$kJB$Y\e(B
+\e$BBX$($rDj5A$9$k$3$H$,$G$-$^$9!#\e(B@xref{Group Parameters}.
+
@node Asynchronous Fetching
@section \e$BHsF14|5-;v<hF@\e(B
@cindex asynchronous article fetching
(nntp-via-rlogin-command "ssh")
@end lisp
-@code{nntp-via-rlogin-command-switches} \e$B$b;2>H$7$F2<$5$$!#\e(B
+@code{nntp-via-rlogin-command-switches} \e$B$b;2>H$7$F2<$5$$!#4V@\E*$K@\B3$9\e(B
+\e$B$k>l9g$NNc$G$9\e(B:
+
+@lisp
+(setq gnus-select-method
+ '(nntp "indirect"
+ (nntp-address "news.server.example")
+ (nntp-via-user-name "intermediate_user_name")
+ (nntp-via-address "intermediate.host.example")
+ (nntp-via-rlogin-command "ssh")
+ (nntp-end-of-line "\n")
+ (nntp-via-rlogin-command-switches ("-C" "-t" "-e" "none"))
+ (nntp-open-connection-function nntp-open-via-rlogin-and-telnet)))
+@end lisp
\e$BKIJI$NCf$K$$$?$H$7$F$b\e(B "runsocks" \e$B$N$h$&$J%i%C%Q!<%3%^%s%I$rDL$7$F30$N@$\e(B
\e$B3&$KD>@\%"%/%;%9$G$-$k$N$J$i$P!"0J2<$N$h$&$K\e(B socks \e$B2=$5$l$?\e(B telnet \e$B$G%K%e!<\e(B
T-gnus \e$B$O0J2<$N$b$N$GF0:n$7$^$9\e(B:
@itemize @bullet
-
@item
Emacs 21.1 \e$B$H$=$l0J>e!#\e(B
@code{nil}. Otherwise, set it to @code{t} if you want to compare them
always in a case-insensitive manner.
+You can define different sorting to different groups via
+@code{gnus-parameters}. Here is an example to sort an @acronym{NNTP}
+group by subject and an @acronym{RSS} group by reverse date to see the
+latest news at the top. In this example, the first group is the Debian
+daily news group @code{gmane.linux.debian.user.news} from
+news.gmane.org. The @acronym{RSS} group corresponds to the Debian
+weekly news RSS feed
+@url{http://packages.debian.org/unstable/newpkg_main.en.rdf},
+@xref{RSS}.
+
+@lisp
+(setq
+ gnus-parameters
+ '(("nntp.*gmane\\.debian\\.user\\.news"
+ (gnus-show-threads nil)
+ (gnus-article-sort-functions '((not gnus-article-sort-by-date)))
+ (gnus-use-adaptive-scoring nil)
+ (gnus-use-scoring nil))
+ ("nnrss.*debian"
+ (gnus-show-threads nil)
+ (gnus-article-sort-functions 'gnus-article-sort-by-subject)
+ (gnus-use-adaptive-scoring nil)
+ (gnus-use-scoring t)
+ (gnus-score-find-score-files-function 'gnus-score-find-single)
+ (gnus-summary-line-format "%U%R%z%d %I%(%[ %s %]%)\n"))))
+@end lisp
+
@node Listing Groups
@section Listing Groups
@lisp
(setq gnus-thread-sort-functions
- '((lambda (t1 t2)
- (not (gnus-thread-sort-by-number t1 t2)))
+ '((not gnus-thread-sort-by-number)
gnus-thread-sort-by-score))
@end lisp
-Yet more examples. You can define different sorting to different
-groups. Here is an example for where one @acronym{NNTP} group is
-sorted by subject and the @acronym{RSS} group is sorted by date to see
-the latest news at the top.
-
-@lisp
-(require 'cl)
-
-(defun my-gnus-summary-mode-hook-group-select ()
- (flet ((lsetq (x val) ;; Local setq
- (set (make-local-variable x) val)))
- (cond
- ;; In Group buffer to make Debian daily news group press: G m
- ;; and point it to nntp server news.gmane.org and
- ;; group gmane.linux.debian.user.news
- ((string-match "nntp.*debian.user.news" gnus-newsgroup-name)
- (lsetq 'gnus-show-threads nil)
- (lsetq 'gnus-article-sort-functions 'gnus-article-sort-by-date-reverse)
- (lsetq 'gnus-use-adaptive-scoring nil)
- (lsetq 'gnus-use-scoring nil))
- ;; In Group buffer to read Debian weekly news RSS feed press: G R
- ;; and point it to url:
- ;; http://packages.debian.org/unstable/newpkg_main.en.rdf
- ((string-match "nnrss.*debian" gnus-newsgroup-name)
- (lsetq 'gnus-show-threads nil)
- (lsetq 'gnus-article-sort-functions 'gnus-article-sort-by-subject)
- (lsetq 'gnus-use-adaptive-scoring nil)
- (lsetq 'gnus-use-scoring t)
- (lsetq 'gnus-score-find-score-files-function 'gnus-score-find-single)
- (lsetq 'gnus-summary-line-format "%U%R%z%d %I%(%[ %s %]%)\n")))))
-
-(defun my-gnus-summary-mode-hook ()
- (my-gnus-summary-mode-hook-group-select))
-@end lisp
-
@vindex gnus-thread-score-function
The function in the @code{gnus-thread-score-function} variable (default
@code{+}) is used for calculating the total score of a thread. Useful
gnus-article-sort-by-subject))
@end lisp
+You can define group specific sorting via @code{gnus-parameters},
+@xref{Group Parameters}.
@node Asynchronous Fetching
(nntp-via-rlogin-command "ssh")
@end lisp
-See also @code{nntp-via-rlogin-command-switches}.
+See also @code{nntp-via-rlogin-command-switches}. Here's an example for
+an indirect connection:
+@lisp
+(setq gnus-select-method
+ '(nntp "indirect"
+ (nntp-address "news.server.example")
+ (nntp-via-user-name "intermediate_user_name")
+ (nntp-via-address "intermediate.host.example")
+ (nntp-via-rlogin-command "ssh")
+ (nntp-end-of-line "\n")
+ (nntp-via-rlogin-command-switches ("-C" "-t" "-e" "none"))
+ (nntp-open-connection-function nntp-open-via-rlogin-and-telnet)))
+@end lisp
If you're behind a firewall, but have direct access to the outside world
through a wrapper command like "runsocks", you could open a socksified
projects / elisp / gnus.git- / commitdiff