@syncodeindex pg cp
@copying
-Copyright (c) 2004 Free Software Foundation, Inc.
+Copyright @copyright{} 2004-2005, 2007-2011 Free Software
+Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
+under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU
Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
license is included in the section entitled ``GNU Free Documentation
-License'' in the Emacs manual.
+License'' in the Gnus manual.
-(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-this GNU Manual, like GNU software. Copies published by the Free
-Software Foundation raise funds for GNU development.''
+(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
+modify this GNU manual. Buying copies from the FSF supports it in
+developing GNU and promoting software freedom.''
This document is part of a collection distributed under the GNU Free
Documentation License. If you want to distribute this document
@titlepage
-@title Gnus Coding Style and Maintainance Guide
+@title Gnus Coding Style and Maintenance Guide
-@c @author by Reiner Steib <Reiner.Steib@gmx.de>
+@author by Reiner Steib <Reiner.Steib@@gmx.de>
@insertcopying
@end titlepage
-@c Obviously this is only a very rudimentary draft. We put it in CVS
-@c anyway hoping that it might annoy someone enough to fix it. ;-)
-@c Fixing only a paragraph also is appreciated.
+@c Obviously this is only a very rudimentary draft. We put it in the
+@c repository anyway hoping that it might annoy someone enough to fix
+@c it. ;-) Fixing only a paragraph also is appreciated.
+@ifnottex
@node Top
+@top Gnus Coding Style and Maintainance Guide
+This manual describes @dots{}
+
+@insertcopying
+@end ifnottex
+
+@menu
+* Gnus Coding Style:: Gnus Coding Style
+* Gnus Maintainance Guide:: Gnus Maintainance Guide
+@end menu
+
+@c @ref{Gnus Reference Guide, ,Gnus Reference Guide, gnus, The Gnus Newsreader}
+
+@node Gnus Coding Style
+@chapter Gnus Coding Style
+@section Dependencies
+
+The Gnus distribution contains a lot of libraries that have been written
+for Gnus and used intensively for Gnus. But many of those libraries are
+useful on their own. E.g. other Emacs Lisp packages might use the
+@acronym{MIME} library @xref{Top, ,Top, emacs-mime, The Emacs MIME
+Manual}.
+
+@subsection General purpose libraries
+
+@table @file
+
+@item netrc.el
+@file{.netrc} parsing functionality.
+@c As of 2005-10-21...
+There are no Gnus dependencies in this file.
+
+@item format-spec.el
+Functions for formatting arbitrary formatting strings.
+@c As of 2005-10-21...
+There are no Gnus dependencies in this file.
+
+@item hex-util.el
+Functions to encode/decode hexadecimal string.
+@c As of 2007-08-25...
+There are no Gnus dependencies in these files.
+@end table
+
+@subsection Encryption and security
+
+@table @file
+@item encrypt.el
+File encryption routines
+@c As of 2005-10-25...
+There are no Gnus dependencies in this file.
+
+@item password.el
+Read passwords from user, possibly using a password cache.
+@c As of 2005-10-21...
+There are no Gnus dependencies in this file.
+
+@item tls.el
+TLS/SSL support via wrapper around GnuTLS
+@c As of 2005-10-21...
+There are no Gnus dependencies in this file.
+
+@item pgg*.el
+Glue for the various PGP implementations.
+@c As of 2005-10-21...
+There are no Gnus dependencies in these files.
+
+@item sha1.el
+SHA1 Secure Hash Algorithm.
+@c As of 2007-08-25...
+There are no Gnus dependencies in these files.
+@end table
+
+@subsection Networking
+
+@table @file
+@item dig.el
+Domain Name System dig interface.
+@c As of 2005-10-21...
+There are no serious Gnus dependencies in this file. Uses
+@code{gnus-run-mode-hooks} (a wrapper function).
+
+@item dns.el, dns-mode.el
+Domain Name Service lookups.
+@c As of 2005-10-21...
+There are no Gnus dependencies in these files.
+@end table
+
+@subsection Mail and News related RFCs
+
+@table @file
+@item pop3.el
+Post Office Protocol (RFC 1460) interface.
+@c As of 2005-10-21...
+There are no Gnus dependencies in this file.
+
+@item imap.el
+@acronym{IMAP} library.
+@c As of 2005-10-21...
+There are no Gnus dependencies in this file.
+
+@item ietf-drums.el
+Functions for parsing RFC822bis headers.
+@c As of 2005-10-21...
+There are no Gnus dependencies in this file.
+
+@item rfc1843.el
+HZ (rfc1843) decoding. HZ is a data format for exchanging files of
+arbitrarily mixed Chinese and @acronym{ASCII} characters.
+@c As of 2005-10-21...
+@code{rfc1843-gnus-setup} seem to be useful only for Gnus. Maybe this
+function should be relocated to remove dependencies on Gnus. Other
+minor dependencies: @code{gnus-newsgroup-name} could be eliminated by
+using an optional argument to @code{rfc1843-decode-article-body}.
+
+@item rfc2045.el
+Functions for decoding rfc2045 headers
+@c As of 2007-08-25...
+There are no Gnus dependencies in these files.
+
+@item rfc2047.el
+Functions for encoding and decoding rfc2047 messages
+@c As of 2007-08-25...
+There are no Gnus dependencies in these files.
+@c
+Only a couple of tests for gnusy symbols.
+
+@item rfc2104.el
+RFC2104 Hashed Message Authentication Codes
+@c As of 2007-08-25...
+There are no Gnus dependencies in these files.
+
+@item rfc2231.el
+Functions for decoding rfc2231 headers
+@c As of 2007-08-25...
+There are no Gnus dependencies in these files.
+
+@item flow-fill.el
+Interpret RFC2646 "flowed" text.
+@c As of 2005-10-27...
+There are no Gnus dependencies in this file.
+
+@item uudecode.el
+Elisp native uudecode.
+@c As of 2005-12-06...
+There are no Gnus dependencies in this file.
+@c ... but the custom group is gnus-extract.
+
+@item canlock.el
+Functions for Cancel-Lock feature
+@c Cf. draft-ietf-usefor-cancel-lock-01.txt
+@c Although this draft has expired, Canlock-Lock revived in 2007 when
+@c major news providers (e.g. news.individual.org) started to use it.
+@c As of 2007-08-25...
+There are no Gnus dependencies in these files.
+
+@end table
+
+@subsection message
+
+All message composition from Gnus (both mail and news) takes place in
+Message mode buffers. Message mode is intended to be a replacement for
+Emacs mail mode. There should be no Gnus dependencies in
+@file{message.el}. Alas it is not anymore. Patches and suggestions to
+remove the dependencies are welcome.
+
+@c message.el requires nnheader which requires gnus-util.
+
+@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. Patches and suggestions
+to remove the dependencies are welcome.
+
+@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 most widely used mail back ends).
+
+@c mm-uu requires nnheader which requires gnus-util. message.el also
+@c requires nnheader.
+
+
+@section Compatibility
+
+No Gnus and Gnus 5.10.10 and up should work on:
+@itemize @bullet
+@item
+Emacs 21.1 and up.
+@item
+XEmacs 21.4 and up.
+@end itemize
+
+Gnus 5.10.8 and below 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 development of Gnus normally is done on the Git repository trunk
+as of April 19, 2010 (formerly it was done in CVS; the repository is
+at http://git.gnus.org), 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.8, @dots{}). @ref{Gnus Development,
+,Gnus Development, gnus, The Gnus Newsreader}
+
+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
+became part of Emacs 22 as Gnus 5.11.
-@section Gnus Coding Style
-@subsection Dependencies
-
-@c message / gnus
-@c
-@c nn*
-@c
-@c mm*
-@c
-@c rfc*
-@c
-@c tla netrc pop3 dig dns ...
-@c format-spec.el
-
-@subsection Compatibility
-
-@c Compatibility with XEmacs and older Emacs versions in v5-10 and in the
-@c trunk.
-
-@c @table
-@c x
-@c @end table
-
-@section Gnus Maintainance Guide
-
-@subsection 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
-
-
-@subsection Syncing
+@section Syncing
@c Some MIDs related to this follow. Use http://thread.gmane.org/MID
@c (and click on the subject) to get the thread on Gmane.
@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.
+
+After Emacs moved to bzr and Gnus moved to git, Katsumi Yamaoka has
+taken over the chore of keeping Emacs and Gnus in sync. In general,
+changes made to one repository will usually be replicated in the other
+within a few days.
+
+Basically the idea is that the gateway will cause all common files in
+Emacs and Gnus v5-13 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-13 version string remains @samp{5.13.x}). Furthermore, all
+changes in these files in either Emacs or the v5-13 branch will be
+installed into the Gnus git 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 bzr access (or it's inconvenient), you can
+change such a file in the v5-10 branch, and it should propagate to Emacs
+bzr -- 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 bzr and the Gnus git 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 git 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 Git 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 ;-).
-@subsection Miscellanea
+@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}
Starting from No Gnus, the @file{GNUS-NEWS} is created from
@file{texi/gnus-news.texi}. Don't edit @file{GNUS-NEWS}. Edit
@file{texi} directory and commit @file{GNUS-NEWS} and
@file{texi/gnus-news.texi}.
+@heading Conventions for version information in defcustoms
+
+For new customizable variables introduced in Oort Gnus (including the
+v5-10 branch) use @code{:version "22.1" ;; Oort Gnus} (including the
+comment) or e.g. @code{:version "22.2" ;; Gnus 5.10.10} if the feature
+was added for Emacs 22.2 and Gnus 5.10.10.
+@c
+If the variable is new in No Gnus use @code{:version "23.1" ;; No Gnus}.
+
+The same applies for customizable variables when its default value was
+changed.
@c Local Variables:
@c mode: texinfo
@c coding: iso-8859-1
@c End:
-
-@ignore
- arch-tag: ab15234c-2c8a-4cbd-8111-1811bcc6f931
-@end ignore
projects / gnus / blobdiff