git.chise.org Git - elisp/gnus.git-/blob - texi/gnus-coding.texi

   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
  10 Copyright (c) 2004, 2005  Free Software Foundation, Inc.
  11
  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.
  20
  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.''
  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 @end table
  80
  81 @subsection Encryption and security
  82
  83 @table @file
  84 @item encrypt.el
  85 File encryption routines
  86 @c As of 2005-10-25...
  87 There are no Gnus dependencies in this file.
  88
  89 @item password.el
  90 Read passwords from user, possibly using a password cache.
  91 @c As of 2005-10-21...
  92 There are no Gnus dependencies in this file.
  93
  94 @item tls.el
  95 TLS/SSL support via wrapper around GnuTLS
  96 @c As of 2005-10-21...
  97 There are no Gnus dependencies in this file.
  98
  99 @item pgg*.el
 100 Glue for the various PGP implementations.
 101 @c As of 2005-10-21...
 102 There are no Gnus dependencies in these files.
 103
 104 @end table
 105
 106 @subsection Networking
 107
 108 @table @file
 109 @item dig.el
 110 Domain Name System dig interface.
 111 @c As of 2005-10-21...
 112 There are no serious Gnus dependencies in this file.  Uses
 113 @code{gnus-run-mode-hooks} (a wrapper function).
 114
 115 @item dns*.el
 116 Domain Name Service lookups.
 117 @c As of 2005-10-21...
 118 There are no Gnus dependencies in these files.
 119 @end table
 120
 121 @subsection Mail and News related RFCs
 122
 123 @table @file
 124 @item pop3.el
 125 Post Office Protocol (RFC 1460) interface.
 126 @c As of 2005-10-21...
 127 There are no Gnus dependencies in this file.
 128
 129 @item imap.el
 130 @acronym{IMAP} library.
 131 @c As of 2005-10-21...
 132 There are no Gnus dependencies in this file.
 133
 134 @item ietf-drums.el
 135 Functions for parsing RFC822bis headers.
 136 @c As of 2005-10-21...
 137 There are no Gnus dependencies in this file.
 138
 139 @item rfc1843.el
 140 HZ (rfc1843) decoding.  HZ is a data format for exchanging files of
 141 arbitrarily mixed Chinese and @acronym{ASCII} characters.
 142 @c As of 2005-10-21...
 143 @code{rfc1843-gnus-setup} seem to be useful only for Gnus.  Maybe this
 144 function should be relocated to remove dependencies on Gnus.  Other
 145 minor dependencies: @code{gnus-newsgroup-name} could be eliminated by
 146 using an optional argument to @code{rfc1843-decode-article-body}.
 147
 148 @item rfc2045.el
 149 Functions for decoding rfc2045 headers
 150
 151 @item rfc2047.el
 152 Functions for encoding and decoding rfc2047 messages
 153
 154 @item rfc2104.el
 155 RFC2104 Hashed Message Authentication Codes
 156
 157 @item rfc2231.el
 158 Functions for decoding rfc2231 headers
 159
 160 @item flow-fill.el
 161 Interpret RFC2646 "flowed" text.
 162 @c As of 2005-10-27...
 163 There are no Gnus dependencies in this file.
 164
 165 @item uudecode.el
 166 Elisp native uudecode.
 167 @c As of 2005-12-06...
 168 There are no Gnus dependencies in this file.
 169 @c ... but the custom group is gnus-extract.
 170 @end table
 171
 172 @subsection message
 173
 174 All message composition from Gnus (both mail and news) takes place in
 175 Message mode buffers.  Message mode is intended to be a replacement for
 176 Emacs mail mode.  There should be no Gnus dependencies in
 177 @file{message.el}.
 178
 179 @subsection Emacs @acronym{MIME}
 180
 181 The files @file{mml*.el} and @file{mm-*.el} provide @acronym{MIME}
 182 functionality for Emacs.
 183
 184 @acronym{MML} (@acronym{MIME} Meta Language) is supposed to be
 185 independent from Gnus.  Alas it is not anymore.
 186
 187
 188 @subsection Gnus backends
 189
 190 The files @file{nn*.el} provide functionality for accessing NNTP
 191 (@file{nntp.el}), IMAP (@file{nnimap.el}) and several other Mail back
 192 ends (probably @file{nnml.el}, @file{nnfolder.el} and
 193 @file{nnmaildir.el} are the most widely used mail back ends).
 194
 195
 196
 197 @c mm-uu requires nnheader which requires gnus-util.  message.el also
 198 @c requires nnheader.
 199
 200 @c message / gnus
 201 @c
 202 @c nn*
 203 @c
 204 @c mm*
 205 @c
 206 @c rfc*
 207 @c
 208 @c pgg*
 209 @c tla netrc pop3 dig dns ...
 210 @c format-spec.el
 211
 212
 213 @section Compatibility
 214
 215 No Gnus should work on:
 216 @itemize @bullet
 217 @item
 218 Emacs 21.1 and up.
 219 @item
 220 XEmacs 21.4 and up.
 221 @end itemize
 222
 223 Gnus 5.10 should work on:
 224 @itemize @bullet
 225 @item
 226 Emacs 20.7 and up.
 227 @item
 228 XEmacs 21.1 and up.
 229 @end itemize
 230
 231 @node Gnus Maintainance Guide
 232 @chapter Gnus Maintainance Guide
 233
 234 @section Stable and development versions
 235
 236 The development of Gnus normally is done on the CVS trunk, i.e. there
 237 are no separate branches to develop and test new features.  Most of the
 238 time, the trunk is developed quite actively with more or less daily
 239 changes.  Only after a new major release, e.g. 5.10.1, there's usually a
 240 feature period of several months.  After the release of Gnus 5.10.6 the
 241 development of new features started again on the trunk while the 5.10
 242 series is continued on the stable branch (v5-10) from which more stable
 243 releases will be done when needed (5.10.7, @dots{}).
 244 @ref{Gnus Development, ,Gnus Development, gnus, The Gnus Newsreader}
 245
 246 Stable releases of Gnus finally become part of Emacs.  E.g. Gnus 5.8
 247 became a part of Emacs 21 (relabeled to Gnus 5.9).  The 5.10 series will
 248 become part of Emacs 22 (as Gnus 5.11).
 249
 250 @section Syncing
 251
 252 @c Some MIDs related to this follow.  Use http://thread.gmane.org/MID
 253 @c (and click on the subject) to get the thread on Gmane.
 254
 255 @c Some quotes from Miles Bader follow...
 256
 257 @c <v9eklyke6b.fsf@marauder.physik.uni-ulm.de>
 258 @c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp>
 259
 260 In the past, the inclusion of Gnus into Emacs was quite cumbersome.  For
 261 each change made to Gnus in Emacs repository, it had to be checked that
 262 it was applied to the new Gnus version, too.  Else, bug fixes done in
 263 Emacs repository might have been lost.
 264
 265 With the inclusion of Gnus 5.10, Miles Bader has set up an Emacs-Gnus
 266 gateway to ensure the bug fixes from Emacs CVS are propagated to Gnus
 267 CVS semi-automatically.  These bug fixes are installed on the stable
 268 branch and on the trunk.  Basically the idea is that the gateway will
 269 cause all common files in Emacs and Gnus v5-10 to be identical except
 270 when there's a very good reason (e.g., the Gnus version string in Emacs
 271 says @samp{5.11}, but the v5-10 version string remains @samp{5.10.x}).
 272 Furthermore, all changes in these files in either Emacs or the v5-10
 273 branch will be installed into the Gnus CVS trunk, again except where
 274 there's a good reason.
 275 @c (typically so far the only exception has been that the changes
 276 @c already exist in the trunk in modified form).
 277 Because of this, when the next major version of Gnus will be included in
 278 Emacs, it should be very easy -- just plonk in the files from the Gnus
 279 trunk without worrying about lost changes from the Emacs tree.
 280
 281 The effect of this is that as hacker, you should generally only have to
 282 make changes in one place:
 283
 284 @itemize
 285 @item
 286 If it's a file which is thought of as being outside of Gnus (e.g., the
 287 new @file{encrypt.el}), you should probably make the change in the Emacs
 288 tree, and it will show up in the Gnus tree a few days later.
 289
 290 If you don't have Emacs CVS access (or it's inconvenient), you can
 291 change such a file in the v5-10 branch, and it should propagate to Emacs
 292 CVS -- however, it will get some extra scrutiny (by Miles) to see if the
 293 changes are possibly controversial and need discussion on the mailing
 294 list.  Many changes are obvious bug-fixes however, so often there won't
 295 be any problem.
 296
 297 @item
 298 If it's to a Gnus file, and it's important enough that it should be part
 299 of Emacs and the v5-10 branch, then you can make the change on the v5-10
 300 branch, and it will go into Emacs CVS and the Gnus CVS trunk (a few days
 301 later).  The most prominent examples for such changes are bug-fixed
 302 including improvements on the documentation.
 303
 304 If you know that there will be conflicts (perhaps because the affected
 305 source code is different in v5-10 and the Gnus CVS trunk), then you can
 306 install your change in both places, and when I try to sync them, there
 307 will be a conflict -- however, since in most such cases there would be a
 308 conflict @emph{anyway}, it's often easier for me to resolve it simply if
 309 I see two @samp{identical} changes, and can just choose the proper one,
 310 rather than having to actually fix the code.
 311
 312 @item
 313 For general Gnus development changes, of course you just make the
 314 change on the Gnus CVS trunk and it goes into Emacs a few years
 315 later... :-)
 316 @end itemize
 317
 318 Of course in any case, if you just can't wait for me to sync your
 319 change, you can commit it in more than one place and probably there will
 320 be no problem; usually the changes are textually identical anyway, so
 321 can be easily resolved automatically (sometimes I notice silly things in
 322 such multiple commits, like whitespace differences, and unify those ;-).
 323
 324
 325 @c I do Emacs->Gnus less often (than Gnus->Emacs) because it tends to
 326 @c require more manual work.
 327
 328 @c By default I sync about once a week.  I also try to follow any Gnus
 329 @c threads on the mailing lists and make sure any changes being discussed
 330 @c are kept more up-to-date (so say 1-2 days delay for "topical" changes).
 331
 332 @c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp>
 333
 334 @c BTW, just to add even more verbose explanation about the syncing thing:
 335
 336 @section Miscellanea
 337
 338 @heading @file{GNUS-NEWS}
 339
 340 Starting from No Gnus, the @file{GNUS-NEWS} is created from
 341 @file{texi/gnus-news.texi}.  Don't edit @file{GNUS-NEWS}.  Edit
 342 @file{texi/gnus-news.texi}, type @command{make GNUS-NEWS} in the
 343 @file{texi} directory and commit @file{GNUS-NEWS} and
 344 @file{texi/gnus-news.texi}.
 345
 346 @heading Conventions for version information in defcustoms
 347
 348 For new customizable variables introduced in Oort Gnus (including the
 349 v5-10 branch) use @code{:version "22.1" ;; Oort Gnus} including the
 350 comment.
 351 @c
 352 If the variable is new in No Gnus use @code{:version "23.0" ;; No Gnus}.
 353
 354 @c Local Variables:
 355 @c mode: texinfo
 356 @c coding: iso-8859-1
 357 @c End:
 358
 359 @ignore
 360    arch-tag: ab15234c-2c8a-4cbd-8111-1811bcc6f931
 361 @end ignore