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