[Emacs-diffs] Changes to doc/misc/gnus-coding.texi

[Miles Bader]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Miles Bader <miles>     07/10/28 09:18:40

Index: doc/misc/gnus-coding.texi
===================================================================
RCS file: doc/misc/gnus-coding.texi
diff -N doc/misc/gnus-coding.texi
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ doc/misc/gnus-coding.texi   28 Oct 2007 09:18:37 -0000      1.1
@@ -0,0 +1,381 @@
+\input texinfo
+
address@hidden gnus-coding
address@hidden Gnus Coding Style and Maintainance Guide
address@hidden fn cp
address@hidden vr cp
address@hidden pg cp
+
address@hidden
+Copyright (c) 2004, 2005, 2007  Free Software Foundation, Inc.
+
address@hidden
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 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.
+
+(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.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License.  If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
address@hidden quotation
address@hidden copying
+
+
address@hidden
address@hidden Gnus Coding Style and Maintainance Guide
+
address@hidden by Reiner Steib  <Reiner.Steib@@gmx.de>
+
address@hidden
address@hidden titlepage
+
address@hidden Obviously this is only a very rudimentary draft.  We put it in 
CVS
address@hidden anyway hoping that it might annoy someone enough to fix it.  ;-)
address@hidden Fixing only a paragraph also is appreciated.
+
address@hidden Top
address@hidden Gnus Coding Style and Maintainance Guide
+This manual describes @dots{}
address@hidden
+* Gnus Coding Style:: Gnus Coding Style
+* Gnus Maintainance Guide:: Gnus Maintainance Guide
address@hidden menu
+
address@hidden @ref{Gnus Reference Guide, ,Gnus Reference Guide, gnus, The Gnus 
Newsreader}
+
address@hidden Gnus Coding Style
address@hidden Gnus Coding Style
address@hidden 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
address@hidden library @xref{Top, ,Top, emacs-mime, The Emacs MIME
+Manual}.
+
address@hidden General purpose libraries
+
address@hidden @file
+
address@hidden netrc.el
address@hidden parsing functionality.
address@hidden As of 2005-10-21...
+There are no Gnus dependencies in this file.
+
address@hidden format-spec.el
+Functions for formatting arbitrary formatting strings.
address@hidden As of 2005-10-21...
+There are no Gnus dependencies in this file.
+
address@hidden hex-util.el
+Functions to encode/decode hexadecimal string.
address@hidden As of 2007-08-25...
+There are no Gnus dependencies in these files.
address@hidden table
+
address@hidden Encryption and security
+
address@hidden @file
address@hidden encrypt.el
+File encryption routines
address@hidden As of 2005-10-25...
+There are no Gnus dependencies in this file.
+
address@hidden password.el
+Read passwords from user, possibly using a password cache.
address@hidden As of 2005-10-21...
+There are no Gnus dependencies in this file.
+
address@hidden tls.el
+TLS/SSL support via wrapper around GnuTLS
address@hidden As of 2005-10-21...
+There are no Gnus dependencies in this file.
+
address@hidden pgg*.el
+Glue for the various PGP implementations.
address@hidden As of 2005-10-21...
+There are no Gnus dependencies in these files.
+
address@hidden sha1.el
+SHA1 Secure Hash Algorithm.
address@hidden As of 2007-08-25...
+There are no Gnus dependencies in these files.
address@hidden table
+
address@hidden Networking
+
address@hidden @file
address@hidden dig.el
+Domain Name System dig interface.
address@hidden As of 2005-10-21...
+There are no serious Gnus dependencies in this file.  Uses
address@hidden (a wrapper function).
+
address@hidden dns.el, dns-mode.el
+Domain Name Service lookups.
address@hidden As of 2005-10-21...
+There are no Gnus dependencies in these files.
address@hidden table
+
address@hidden Mail and News related RFCs
+
address@hidden @file
address@hidden pop3.el
+Post Office Protocol (RFC 1460) interface.
address@hidden As of 2005-10-21...
+There are no Gnus dependencies in this file.
+
address@hidden imap.el
address@hidden library.
address@hidden As of 2005-10-21...
+There are no Gnus dependencies in this file.
+
address@hidden ietf-drums.el
+Functions for parsing RFC822bis headers.
address@hidden As of 2005-10-21...
+There are no Gnus dependencies in this file.
+
address@hidden rfc1843.el
+HZ (rfc1843) decoding.  HZ is a data format for exchanging files of
+arbitrarily mixed Chinese and @acronym{ASCII} characters.
address@hidden As of 2005-10-21...
address@hidden 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}.
+
address@hidden rfc2045.el
+Functions for decoding rfc2045 headers
address@hidden As of 2007-08-25...
+There are no Gnus dependencies in these files.
+
address@hidden rfc2047.el
+Functions for encoding and decoding rfc2047 messages
address@hidden As of 2007-08-25...
+There are no Gnus dependencies in these files.
address@hidden
+Only a couple of tests for gnusy symbols.
+
address@hidden rfc2104.el
+RFC2104 Hashed Message Authentication Codes
address@hidden As of 2007-08-25...
+There are no Gnus dependencies in these files.
+
address@hidden rfc2231.el
+Functions for decoding rfc2231 headers
address@hidden As of 2007-08-25...
+There are no Gnus dependencies in these files.
+
address@hidden flow-fill.el
+Interpret RFC2646 "flowed" text.
address@hidden As of 2005-10-27...
+There are no Gnus dependencies in this file.
+
address@hidden uudecode.el
+Elisp native uudecode.
address@hidden As of 2005-12-06...
+There are no Gnus dependencies in this file.
address@hidden ... but the custom group is gnus-extract.
+
address@hidden canlock.el
+Functions for Cancel-Lock feature
address@hidden Cf. draft-ietf-usefor-cancel-lock-01.txt
address@hidden Although this draft has expired, Canlock-Lock revived in 2007 
when
address@hidden major news providers (e.g. news.individual.org) started to use 
it.
address@hidden As of 2007-08-25...
+There are no Gnus dependencies in these files.
+
address@hidden table
+
address@hidden 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
address@hidden  Alas it is not anymore.  Patches and suggestions to
+remove the dependencies are welcome.
+
address@hidden message.el requires nnheader which requires gnus-util.
+
address@hidden Emacs @acronym{MIME}
+
+The files @file{mml*.el} and @file{mm-*.el} provide @acronym{MIME}
+functionality for Emacs.
+
address@hidden (@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.
+
address@hidden 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
address@hidden are the most widely used mail back ends).
+
address@hidden mm-uu requires nnheader which requires gnus-util.  message.el 
also
address@hidden requires nnheader.
+
+
address@hidden Compatibility
+
+No Gnus and Gnus 5.10.10 and up should work on:
address@hidden @bullet
address@hidden
+Emacs 21.1 and up.
address@hidden
+XEmacs 21.4 and up.
address@hidden itemize
+
+Gnus 5.10.8 and below should work on:
address@hidden @bullet
address@hidden
+Emacs 20.7 and up.
address@hidden
+XEmacs 21.1 and up.
address@hidden itemize
+
address@hidden Gnus Maintainance Guide
address@hidden Gnus Maintainance Guide
+
address@hidden Stable and development versions
+
+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{}).
address@hidden 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.
+
address@hidden Syncing
+
address@hidden Some MIDs related to this follow.  Use 
http://thread.gmane.org/MID
address@hidden (and click on the subject) to get the thread on Gmane.
+
address@hidden Some quotes from Miles Bader follow...
+
address@hidden <address@hidden>
address@hidden <address@hidden>
+
+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.
address@hidden (typically so far the only exception has been that the changes
address@hidden 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:
+
address@hidden
address@hidden
+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.
+
address@hidden
+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.
+
address@hidden
+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... :-)
address@hidden 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
+be no problem; usually the changes are textually identical anyway, so
+can be easily resolved automatically (sometimes I notice silly things in
+such multiple commits, like whitespace differences, and unify those ;-).
+
+
address@hidden I do Emacs->Gnus less often (than Gnus->Emacs) because it tends 
to
address@hidden require more manual work.
+
address@hidden By default I sync about once a week.  I also try to follow any 
Gnus
address@hidden threads on the mailing lists and make sure any changes being 
discussed
address@hidden are kept more up-to-date (so say 1-2 days delay for "topical" 
changes).
+
address@hidden <address@hidden>
+
address@hidden BTW, just to add even more verbose explanation about the syncing 
thing:
+
address@hidden Miscellanea
+
address@hidden @file{GNUS-NEWS}
+
+Starting from No Gnus, the @file{GNUS-NEWS} is created from
address@hidden/gnus-news.texi}.  Don't edit @file{GNUS-NEWS}.  Edit
address@hidden/gnus-news.texi}, type @command{make GNUS-NEWS} in the
address@hidden directory and commit @file{GNUS-NEWS} and
address@hidden/gnus-news.texi}.
+
address@hidden 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.
address@hidden
+If the variable is new in No Gnus use @code{:version "23.0" ;; No Gnus}.
+
+The same applies for customizable variables when its default value was
+changed.
+
address@hidden Local Variables:
address@hidden mode: texinfo
address@hidden coding: iso-8859-1
address@hidden End:
+
address@hidden
+   arch-tag: ab15234c-2c8a-4cbd-8111-1811bcc6f931
address@hidden ignore