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