3 @setfilename gnus-coding
4 @settitle Gnus Coding Style and Maintainance Guide
10 Copyright (c) 2004, 2005 Free Software Foundation, Inc.
13 Permission is granted to copy, distribute and/or modify this document
14 under the terms of the GNU Free Documentation License, Version 1.1 or
15 any later version published by the Free Software Foundation; with no
16 Invariant Sections, with the Front-Cover texts being ``A GNU
17 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
18 license is included in the section entitled ``GNU Free Documentation
19 License'' in the Emacs manual.
21 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
22 this GNU Manual, like GNU software. Copies published by the Free
23 Software Foundation raise funds for GNU development.''
25 This document is part of a collection distributed under the GNU Free
26 Documentation License. If you want to distribute this document
27 separately from the collection, you can do so by adding a copy of the
28 license to the document, as described in section 6 of the license.
34 @title Gnus Coding Style and Maintainance Guide
36 @author by Reiner Steib <Reiner.Steib@@gmx.de>
41 @c Obviously this is only a very rudimentary draft. We put it in CVS
42 @c anyway hoping that it might annoy someone enough to fix it. ;-)
43 @c Fixing only a paragraph also is appreciated.
47 @chapter Gnus Coding Style
50 The Gnus distribution contains a lot of libraries that have been written
51 for Gnus and used intensively for Gnus. But many of those libraries are
52 useful on their own. E.g. other Emacs Lisp packages might use the
53 @acronym{MIME} library @xref{Top, ,Top, emacs-mime, The Emacs MIME
56 @subsection General purpose libraries
61 @file{.netrc} parsing functionality.
62 @c As of 2005-10-21...
63 There are no Gnus dependencies in this file.
66 Functions for formatting arbitrary formatting strings.
67 @c As of 2005-10-21...
68 There are no Gnus dependencies in this file.
72 @subsection Encryption and security
76 File encryption routines
77 @c As of 2005-10-21...
78 There are no Gnus serious dependencies in this file. It uses
79 @code{gnus-message} which can easily be replaced with @code{message}.
82 Read passwords from user, possibly using a password cache.
83 @c As of 2005-10-21...
84 There are no Gnus dependencies in this file.
87 TLS/SSL support via wrapper around GnuTLS
88 @c As of 2005-10-21...
89 There are no Gnus dependencies in this file.
92 Glue for the various PGP implementations.
93 @c As of 2005-10-21...
94 There are no Gnus dependencies in these files.
98 @subsection Networking
102 Domain Name System dig interface.
103 @c As of 2005-10-21...
104 There are no serious Gnus dependencies in this file. Uses
105 @code{gnus-run-mode-hooks} (a wrapper function).
108 Domain Name Service lookups.
109 @c As of 2005-10-21...
110 There are no Gnus dependencies in these files.
113 @subsection Mail and News related RFCs
117 Post Office Protocol (RFC 1460) interface.
118 @c As of 2005-10-21...
119 There are no Gnus dependencies in this file.
122 @acronym{IMAP} library.
123 @c As of 2005-10-21...
124 There are no Gnus dependencies in this file.
127 Functions for parsing RFC822bis headers.
128 @c As of 2005-10-21...
129 There are no Gnus dependencies in this file.
132 HZ (rfc1843) decoding. HZ is a data format for exchanging files of
133 arbitrarily mixed Chinese and @acronym{ASCII} characters.
134 @c As of 2005-10-21...
135 @code{rfc1843-gnus-setup} seem to be useful only for Gnus. Maybe this
136 function should be relocated to remove dependencies on Gnus. Other
137 minor dependencies: @code{gnus-newsgroup-name} could be eliminated by
138 using an optional argument to @code{rfc1843-decode-article-body}.
141 Functions for decoding rfc2045 headers
144 Functions for encoding and decoding rfc2047 messages
147 RFC2104 Hashed Message Authentication Codes
150 Functions for decoding rfc2231 headers
155 All message composition from Gnus (both mail and news) takes place in
156 Message mode buffers. Message mode is intended to be a replacement for
157 Emacs mail mode. There should be no Gnus dependencies in
160 @subsection Gnus backends
162 The files @file{nn*.el} provide functionality for accessing NNTP
163 (@file{nntp.el}), IMAP (@file{nnimap.el}) and several other Mail back
164 ends (probably @file{nnml.el}, @file{nnfolder.el} and
165 @file{nnmaildir.el} are the ones most widely used mail back ends).
177 @c tla netrc pop3 dig dns ...
181 @section Compatibility
183 @c Compatibility with XEmacs and older Emacs versions in v5-10 and in the
190 @chapter Gnus Maintainance Guide
192 @section Stable and development versions
194 The CVS trunk is developed quite actively.
196 @c Most of the time Gnus is developed on the trunk.
198 @c Exeption: several month of feature freeze after a release,
204 @c Some MIDs related to this follow. Use http://thread.gmane.org/MID
205 @c (and click on the subject) to get the thread on Gmane.
207 @c Some quotes from Miles Bader follow...
209 @c <v9eklyke6b.fsf@marauder.physik.uni-ulm.de>
210 @c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp>
212 I do Emacs->Gnus less often (than Gnus->Emacs) because it tends to
213 require more manual work.
215 By default I sync about once a week. I also try to follow any Gnus
216 threads on the mailing lists and make sure any changes being discussed
217 are kept more up-to-date (so say 1-2 days delay for "topical" changes).
220 @c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp>
222 BTW, just to add even more verbose explanation about the syncing thing:
224 Basically my idea is that the Emacs-Gnus gateway will cause all common
225 files in Emacs and Gnus v5-10 to be identical except when there's a very
226 good reason (e.g., the Gnus version string in Emacs says "5.11", but the
227 v5-10 version string remains "5.10.whatever"). Furthermore, all changes
228 in these files in either Emacs or the v5-10 branch will be installed
229 into the Gnus CVS trunk, again except where there's a good reason
230 (typically so far the only exception has been that the changes already
231 exist in the trunk in modified form). Because of this, when the next
232 Emacs Gnus upgrade comes, it should be very easy -- just plonk in the
233 files from the Gnus trunk without worrying about lost changes from the
236 The effect of this is that as hacker, you should generally only have to
237 make changes in one place:
239 1) If it's a file which is thought of as being outside of Gnus (e.g.,
240 the new "encrypt.el"), you should probably make the change in the
241 Emacs tree, and it will show up in the Gnus tree a few days later.
243 If you don't have Emacs CVS access (or it's inconvenient), you can
244 change such a file in the v5-10 branch, and it should propagate to
245 Emacs CVS -- however, it will get some extra scrutiny (by me) to see
246 if the changes are possibly controversial and need discussion on the
247 mailing list. [Many changes are obvious bug-fixes however, so often
248 there won't be any problem.]
250 2) If it's to a Gnus file, and it's important enough that it should be
251 part of Emacs/v5-10, then you can make the change on the v5-10
252 branch, and it will go into Emacs CVS and the Gnus CVS trunk (a few
255 If you know that there will be conflicts (perhaps because the
256 affected source code is different in v5-10 and the Gnus CVS trunk),
257 then you can install your change in both places, and when I try to
258 sync them, there will be a conflict -- however, since in most such
259 cases there would be a conflict _anyway_, it's often easier for me
260 to resolve it simply if I see two "identical" changes, and can just
261 choose the proper one, rather than having to actually fix the code.
263 3) For general Gnus development changes, of course you just make the
264 change on the Gnus CVS trunk and it goes into Emacs a few years
267 Of course in any case, if you just can't wait for me to sync your
268 change, you can commit it in more than one place and probably there will
269 be no problem; usually the changes are textually identical anyway, so
270 can be easily resolved automatically (sometimes I notice silly things in
271 such multiple commits, like whitespace differences, and unify those ;-).
276 @heading @file{GNUS-NEWS}
278 Starting from No Gnus, the @file{GNUS-NEWS} is created from
279 @file{texi/gnus-news.texi}. Don't edit @file{GNUS-NEWS}. Edit
280 @file{texi/gnus-news.texi}, type @command{make GNUS-NEWS} in the
281 @file{texi} directory and commit @file{GNUS-NEWS} and
282 @file{texi/gnus-news.texi}.
287 @c coding: iso-8859-1
291 arch-tag: ab15234c-2c8a-4cbd-8111-1811bcc6f931