Commit | Line | Data |
---|---|---|
01c52d31 MB |
1 | \input texinfo |
2 | ||
3 | @setfilename gnus-coding | |
4 | @settitle Gnus Coding Style and Maintainance Guide | |
5 | @syncodeindex fn cp | |
6 | @syncodeindex vr cp | |
7 | @syncodeindex pg cp | |
8 | ||
9 | @copying | |
dcb8ac09 | 10 | Copyright (C) 2004, 2005, 2007, 2008 Free Software Foundation, Inc. |
01c52d31 MB |
11 | |
12 | @quotation | |
13 | Permission is granted to copy, distribute and/or modify this document | |
6f093307 | 14 | under the terms of the GNU Free Documentation License, Version 1.2 or |
01c52d31 MB |
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 | |
5471fa1e | 19 | License'' in the Gnus manual. |
01c52d31 | 20 | |
6f093307 GM |
21 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and |
22 | modify this GNU manual. Buying copies from the FSF supports it in | |
23 | developing GNU and promoting software freedom.'' | |
01c52d31 MB |
24 | |
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 | |
31 | ||
32 | ||
33 | @titlepage | |
34 | @title Gnus Coding Style and Maintainance Guide | |
35 | ||
36 | @author by Reiner Steib <Reiner.Steib@@gmx.de> | |
37 | ||
38 | @insertcopying | |
39 | @end titlepage | |
40 | ||
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. | |
44 | ||
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 | |
52 | ||
53 | @c @ref{Gnus Reference Guide, ,Gnus Reference Guide, gnus, The Gnus Newsreader} | |
54 | ||
55 | @node Gnus Coding Style | |
56 | @chapter Gnus Coding Style | |
57 | @section Dependencies | |
58 | ||
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}. | |
64 | ||
65 | @subsection General purpose libraries | |
66 | ||
67 | @table @file | |
68 | ||
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. | |
73 | ||
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. | |
78 | ||
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 | |
84 | ||
85 | @subsection Encryption and security | |
86 | ||
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. | |
92 | ||
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. | |
97 | ||
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. | |
102 | ||
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. | |
107 | ||
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 | |
113 | ||
114 | @subsection Networking | |
115 | ||
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). | |
122 | ||
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 | |
128 | ||
129 | @subsection Mail and News related RFCs | |
130 | ||
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. | |
136 | ||
137 | @item imap.el | |
138 | @acronym{IMAP} library. | |
139 | @c As of 2005-10-21... | |
140 | There are no Gnus dependencies in this file. | |
141 | ||
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. | |
146 | ||
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}. | |
155 | ||
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. | |
160 | ||
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. | |
165 | @c | |
166 | Only a couple of tests for gnusy symbols. | |
167 | ||
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. | |
172 | ||
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. | |
177 | ||
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. | |
182 | ||
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. | |
188 | ||
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. | |
196 | ||
197 | @end table | |
198 | ||
199 | @subsection message | |
200 | ||
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. | |
206 | ||
207 | @c message.el requires nnheader which requires gnus-util. | |
208 | ||
209 | @subsection Emacs @acronym{MIME} | |
210 | ||
211 | The files @file{mml*.el} and @file{mm-*.el} provide @acronym{MIME} | |
212 | functionality for Emacs. | |
213 | ||
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. | |
217 | ||
218 | @subsection Gnus backends | |
219 | ||
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). | |
224 | ||
225 | @c mm-uu requires nnheader which requires gnus-util. message.el also | |
226 | @c requires nnheader. | |
227 | ||
228 | ||
229 | @section Compatibility | |
230 | ||
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 | |
238 | ||
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 | |
246 | ||
247 | @node Gnus Maintainance Guide | |
248 | @chapter Gnus Maintainance Guide | |
249 | ||
250 | @section Stable and development versions | |
251 | ||
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 | |
8f7abae3 | 259 | releases will be done when needed (5.10.8, @dots{}). |
01c52d31 MB |
260 | @ref{Gnus Development, ,Gnus Development, gnus, The Gnus Newsreader} |
261 | ||
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. | |
265 | ||
266 | @section Syncing | |
267 | ||
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. | |
270 | ||
271 | @c Some quotes from Miles Bader follow... | |
272 | ||
273 | @c <v9eklyke6b.fsf@marauder.physik.uni-ulm.de> | |
274 | @c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp> | |
275 | ||
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. | |
280 | ||
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. | |
296 | ||
297 | The effect of this is that as hacker, you should generally only have to | |
298 | make changes in one place: | |
299 | ||
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. | |
305 | ||
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. | |
312 | ||
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. | |
319 | ||
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. | |
327 | ||
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 | |
333 | ||
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 ;-). | |
339 | ||
340 | ||
341 | @c I do Emacs->Gnus less often (than Gnus->Emacs) because it tends to | |
342 | @c require more manual work. | |
343 | ||
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). | |
347 | ||
348 | @c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp> | |
349 | ||
350 | @c BTW, just to add even more verbose explanation about the syncing thing: | |
351 | ||
352 | @section Miscellanea | |
353 | ||
354 | @heading @file{GNUS-NEWS} | |
355 | ||
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}. | |
361 | ||
362 | @heading Conventions for version information in defcustoms | |
363 | ||
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. | |
368 | @c | |
8f7abae3 | 369 | If the variable is new in No Gnus use @code{:version "23.1" ;; No Gnus}. |
01c52d31 MB |
370 | |
371 | The same applies for customizable variables when its default value was | |
372 | changed. | |
373 | ||
374 | @c Local Variables: | |
375 | @c mode: texinfo | |
376 | @c coding: iso-8859-1 | |
377 | @c End: | |
378 | ||
379 | @ignore | |
380 | arch-tag: ab15234c-2c8a-4cbd-8111-1811bcc6f931 | |
381 | @end ignore |