(hebrew-calendar-leap-year-p)
[emacs.git] / doc / misc / gnus-coding.texi
blobb6dc3148da234d4dad241ade8e8b016e2f588780
1 \input texinfo
3 @setfilename gnus-coding
4 @settitle Gnus Coding Style and Maintainance Guide
5 @syncodeindex fn cp
6 @syncodeindex vr cp
7 @syncodeindex pg cp
9 @copying
10 Copyright (C) 2004, 2005, 2007, 2008  Free Software Foundation, Inc.
12 @quotation
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.
29 @end quotation
30 @end copying
33 @titlepage
34 @title Gnus Coding Style and Maintainance Guide
36 @author by Reiner Steib  <Reiner.Steib@@gmx.de>
38 @insertcopying
39 @end titlepage
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.
45 @node Top
46 @top Gnus Coding Style and Maintainance Guide
47 This manual describes @dots{}
48 @menu
49 * Gnus Coding Style:: Gnus Coding Style
50 * Gnus Maintainance Guide:: Gnus Maintainance Guide
51 @end menu
53 @c @ref{Gnus Reference Guide, ,Gnus Reference Guide, gnus, The Gnus Newsreader}
55 @node Gnus Coding Style
56 @chapter Gnus Coding Style
57 @section Dependencies
59 The Gnus distribution contains a lot of libraries that have been written
60 for Gnus and used intensively for Gnus.  But many of those libraries are
61 useful on their own.  E.g. other Emacs Lisp packages might use the
62 @acronym{MIME} library @xref{Top, ,Top, emacs-mime, The Emacs MIME
63 Manual}.
65 @subsection General purpose libraries
67 @table @file
69 @item netrc.el
70 @file{.netrc} parsing functionality.
71 @c As of 2005-10-21...
72 There are no Gnus dependencies in this file.
74 @item format-spec.el
75 Functions for formatting arbitrary formatting strings.
76 @c As of 2005-10-21...
77 There are no Gnus dependencies in this file.
79 @item hex-util.el
80 Functions to encode/decode hexadecimal string.
81 @c As of 2007-08-25...
82 There are no Gnus dependencies in these files.
83 @end table
85 @subsection Encryption and security
87 @table @file
88 @item encrypt.el
89 File encryption routines
90 @c As of 2005-10-25...
91 There are no Gnus dependencies in this file.
93 @item password.el
94 Read passwords from user, possibly using a password cache.
95 @c As of 2005-10-21...
96 There are no Gnus dependencies in this file.
98 @item tls.el
99 TLS/SSL support via wrapper around GnuTLS
100 @c As of 2005-10-21...
101 There are no Gnus dependencies in this file.
103 @item pgg*.el
104 Glue for the various PGP implementations.
105 @c As of 2005-10-21...
106 There are no Gnus dependencies in these files.
108 @item sha1.el
109 SHA1 Secure Hash Algorithm.
110 @c As of 2007-08-25...
111 There are no Gnus dependencies in these files.
112 @end table
114 @subsection Networking
116 @table @file
117 @item dig.el
118 Domain Name System dig interface.
119 @c As of 2005-10-21...
120 There are no serious Gnus dependencies in this file.  Uses
121 @code{gnus-run-mode-hooks} (a wrapper function).
123 @item dns.el, dns-mode.el
124 Domain Name Service lookups.
125 @c As of 2005-10-21...
126 There are no Gnus dependencies in these files.
127 @end table
129 @subsection Mail and News related RFCs
131 @table @file
132 @item pop3.el
133 Post Office Protocol (RFC 1460) interface.
134 @c As of 2005-10-21...
135 There are no Gnus dependencies in this file.
137 @item imap.el
138 @acronym{IMAP} library.
139 @c As of 2005-10-21...
140 There are no Gnus dependencies in this file.
142 @item ietf-drums.el
143 Functions for parsing RFC822bis headers.
144 @c As of 2005-10-21...
145 There are no Gnus dependencies in this file.
147 @item rfc1843.el
148 HZ (rfc1843) decoding.  HZ is a data format for exchanging files of
149 arbitrarily mixed Chinese and @acronym{ASCII} characters.
150 @c As of 2005-10-21...
151 @code{rfc1843-gnus-setup} seem to be useful only for Gnus.  Maybe this
152 function should be relocated to remove dependencies on Gnus.  Other
153 minor dependencies: @code{gnus-newsgroup-name} could be eliminated by
154 using an optional argument to @code{rfc1843-decode-article-body}.
156 @item rfc2045.el
157 Functions for decoding rfc2045 headers
158 @c As of 2007-08-25...
159 There are no Gnus dependencies in these files.
161 @item rfc2047.el
162 Functions for encoding and decoding rfc2047 messages
163 @c As of 2007-08-25...
164 There are no Gnus dependencies in these files.
166 Only a couple of tests for gnusy symbols.
168 @item rfc2104.el
169 RFC2104 Hashed Message Authentication Codes
170 @c As of 2007-08-25...
171 There are no Gnus dependencies in these files.
173 @item rfc2231.el
174 Functions for decoding rfc2231 headers
175 @c As of 2007-08-25...
176 There are no Gnus dependencies in these files.
178 @item flow-fill.el
179 Interpret RFC2646 "flowed" text.
180 @c As of 2005-10-27...
181 There are no Gnus dependencies in this file.
183 @item uudecode.el
184 Elisp native uudecode.
185 @c As of 2005-12-06...
186 There are no Gnus dependencies in this file.
187 @c ... but the custom group is gnus-extract.
189 @item canlock.el
190 Functions for Cancel-Lock feature
191 @c Cf. draft-ietf-usefor-cancel-lock-01.txt
192 @c Although this draft has expired, Canlock-Lock revived in 2007 when
193 @c major news providers (e.g. news.individual.org) started to use it.
194 @c As of 2007-08-25...
195 There are no Gnus dependencies in these files.
197 @end table
199 @subsection message
201 All message composition from Gnus (both mail and news) takes place in
202 Message mode buffers.  Message mode is intended to be a replacement for
203 Emacs mail mode.  There should be no Gnus dependencies in
204 @file{message.el}.  Alas it is not anymore.  Patches and suggestions to
205 remove the dependencies are welcome.
207 @c message.el requires nnheader which requires gnus-util.
209 @subsection Emacs @acronym{MIME}
211 The files @file{mml*.el} and @file{mm-*.el} provide @acronym{MIME}
212 functionality for Emacs.
214 @acronym{MML} (@acronym{MIME} Meta Language) is supposed to be
215 independent from Gnus.  Alas it is not anymore.  Patches and suggestions
216 to remove the dependencies are welcome.
218 @subsection Gnus backends
220 The files @file{nn*.el} provide functionality for accessing NNTP
221 (@file{nntp.el}), IMAP (@file{nnimap.el}) and several other Mail back
222 ends (probably @file{nnml.el}, @file{nnfolder.el} and
223 @file{nnmaildir.el} are the most widely used mail back ends).
225 @c mm-uu requires nnheader which requires gnus-util.  message.el also
226 @c requires nnheader.
229 @section Compatibility
231 No Gnus and Gnus 5.10.10 and up should work on:
232 @itemize @bullet
233 @item
234 Emacs 21.1 and up.
235 @item
236 XEmacs 21.4 and up.
237 @end itemize
239 Gnus 5.10.8 and below should work on:
240 @itemize @bullet
241 @item
242 Emacs 20.7 and up.
243 @item
244 XEmacs 21.1 and up.
245 @end itemize
247 @node Gnus Maintainance Guide
248 @chapter Gnus Maintainance Guide
250 @section Stable and development versions
252 The development of Gnus normally is done on the CVS trunk, i.e. there
253 are no separate branches to develop and test new features.  Most of the
254 time, the trunk is developed quite actively with more or less daily
255 changes.  Only after a new major release, e.g. 5.10.1, there's usually a
256 feature period of several months.  After the release of Gnus 5.10.6 the
257 development of new features started again on the trunk while the 5.10
258 series is continued on the stable branch (v5-10) from which more stable
259 releases will be done when needed (5.10.7, @dots{}).
260 @ref{Gnus Development, ,Gnus Development, gnus, The Gnus Newsreader}
262 Stable releases of Gnus finally become part of Emacs.  E.g. Gnus 5.8
263 became a part of Emacs 21 (relabeled to Gnus 5.9).  The 5.10 series 
264 became part of Emacs 22 as Gnus 5.11.
266 @section Syncing
268 @c Some MIDs related to this follow.  Use http://thread.gmane.org/MID
269 @c (and click on the subject) to get the thread on Gmane.
271 @c Some quotes from Miles Bader follow...
273 @c <v9eklyke6b.fsf@marauder.physik.uni-ulm.de>
274 @c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp>
276 In the past, the inclusion of Gnus into Emacs was quite cumbersome.  For
277 each change made to Gnus in Emacs repository, it had to be checked that
278 it was applied to the new Gnus version, too.  Else, bug fixes done in
279 Emacs repository might have been lost.
281 With the inclusion of Gnus 5.10, Miles Bader has set up an Emacs-Gnus
282 gateway to ensure the bug fixes from Emacs CVS are propagated to Gnus
283 CVS semi-automatically.  These bug fixes are installed on the stable
284 branch and on the trunk.  Basically the idea is that the gateway will
285 cause all common files in Emacs and Gnus v5-10 to be identical except
286 when there's a very good reason (e.g., the Gnus version string in Emacs
287 says @samp{5.11}, but the v5-10 version string remains @samp{5.10.x}).
288 Furthermore, all changes in these files in either Emacs or the v5-10
289 branch will be installed into the Gnus CVS trunk, again except where
290 there's a good reason.
291 @c (typically so far the only exception has been that the changes
292 @c already exist in the trunk in modified form).
293 Because of this, when the next major version of Gnus will be included in
294 Emacs, it should be very easy -- just plonk in the files from the Gnus
295 trunk without worrying about lost changes from the Emacs tree.
297 The effect of this is that as hacker, you should generally only have to
298 make changes in one place:
300 @itemize
301 @item
302 If it's a file which is thought of as being outside of Gnus (e.g., the
303 new @file{encrypt.el}), you should probably make the change in the Emacs
304 tree, and it will show up in the Gnus tree a few days later.
306 If you don't have Emacs CVS access (or it's inconvenient), you can
307 change such a file in the v5-10 branch, and it should propagate to Emacs
308 CVS -- however, it will get some extra scrutiny (by Miles) to see if the
309 changes are possibly controversial and need discussion on the mailing
310 list.  Many changes are obvious bug-fixes however, so often there won't
311 be any problem.
313 @item
314 If it's to a Gnus file, and it's important enough that it should be part
315 of Emacs and the v5-10 branch, then you can make the change on the v5-10
316 branch, and it will go into Emacs CVS and the Gnus CVS trunk (a few days
317 later).  The most prominent examples for such changes are bug-fixed
318 including improvements on the documentation.
320 If you know that there will be conflicts (perhaps because the affected
321 source code is different in v5-10 and the Gnus CVS trunk), then you can
322 install your change in both places, and when I try to sync them, there
323 will be a conflict -- however, since in most such cases there would be a
324 conflict @emph{anyway}, it's often easier for me to resolve it simply if
325 I see two @samp{identical} changes, and can just choose the proper one,
326 rather than having to actually fix the code.
328 @item
329 For general Gnus development changes, of course you just make the
330 change on the Gnus CVS trunk and it goes into Emacs a few years
331 later... :-)
332 @end itemize
334 Of course in any case, if you just can't wait for me to sync your
335 change, you can commit it in more than one place and probably there will
336 be no problem; usually the changes are textually identical anyway, so
337 can be easily resolved automatically (sometimes I notice silly things in
338 such multiple commits, like whitespace differences, and unify those ;-).
341 @c I do Emacs->Gnus less often (than Gnus->Emacs) because it tends to
342 @c require more manual work.
344 @c By default I sync about once a week.  I also try to follow any Gnus
345 @c threads on the mailing lists and make sure any changes being discussed
346 @c are kept more up-to-date (so say 1-2 days delay for "topical" changes).
348 @c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp>
350 @c BTW, just to add even more verbose explanation about the syncing thing:
352 @section Miscellanea
354 @heading @file{GNUS-NEWS}
356 Starting from No Gnus, the @file{GNUS-NEWS} is created from
357 @file{texi/gnus-news.texi}.  Don't edit @file{GNUS-NEWS}.  Edit
358 @file{texi/gnus-news.texi}, type @command{make GNUS-NEWS} in the
359 @file{texi} directory and commit @file{GNUS-NEWS} and
360 @file{texi/gnus-news.texi}.
362 @heading Conventions for version information in defcustoms
364 For new customizable variables introduced in Oort Gnus (including the
365 v5-10 branch) use @code{:version "22.1" ;; Oort Gnus} (including the
366 comment) or e.g. @code{:version "22.2" ;; Gnus 5.10.10} if the feature
367 was added for Emacs 22.2 and Gnus 5.10.10.
369 If the variable is new in No Gnus use @code{:version "23.0" ;; No Gnus}.
371 The same applies for customizable variables when its default value was
372 changed.
374 @c Local Variables:
375 @c mode: texinfo
376 @c coding: iso-8859-1
377 @c End:
379 @ignore
380    arch-tag: ab15234c-2c8a-4cbd-8111-1811bcc6f931
381 @end ignore