cgit.sxemacs.org Git - gnus/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
  47 @chapter Gnus Coding Style
  48 @section Dependencies
  49
  50 The Gnus distribution contains a lot of libraries that have been written
  51 for Gnus and used intensively for Gnus.  But many of those libraries are
  52 useful on their own.  E.g. other Emacs Lisp packages might use the
  53 @acronym{MIME} library @xref{Top, ,Top, emacs-mime, The Emacs MIME
  54 Manual}.
  55
  56 @subsection General purpose libraries
  57
  58 @table @file
  59
  60 @item netrc.el
  61 @file{.netrc} parsing functionality.
  62 @c As of 2005-10-21...
  63 There are no Gnus dependencies in this file.
  64
  65 @item format-spec.el
  66 Functions for formatting arbitrary formatting strings.
  67 @c As of 2005-10-21...
  68 There are no Gnus dependencies in this file.
  69
  70 @end table
  71
  72 @subsection Encryption and security
  73
  74 @table @file
  75 @item encrypt.el
  76 File encryption routines
  77 @c As of 2005-10-25...
  78 There are no Gnus dependencies in this file.
  79
  80 @item password.el
  81 Read passwords from user, possibly using a password cache.
  82 @c As of 2005-10-21...
  83 There are no Gnus dependencies in this file.
  84
  85 @item tls.el
  86 TLS/SSL support via wrapper around GnuTLS
  87 @c As of 2005-10-21...
  88 There are no Gnus dependencies in this file.
  89
  90 @item pgg*.el
  91 Glue for the various PGP implementations.
  92 @c As of 2005-10-21...
  93 There are no Gnus dependencies in these files.
  94
  95 @end table
  96
  97 @subsection Networking
  98
  99 @table @file
 100 @item dig.el
 101 Domain Name System dig interface.
 102 @c As of 2005-10-21...
 103 There are no serious Gnus dependencies in this file.  Uses
 104 @code{gnus-run-mode-hooks} (a wrapper function).
 105
 106 @item dns*.el
 107 Domain Name Service lookups.
 108 @c As of 2005-10-21...
 109 There are no Gnus dependencies in these files.
 110 @end table
 111
 112 @subsection Mail and News related RFCs
 113
 114 @table @file
 115 @item pop3.el
 116 Post Office Protocol (RFC 1460) interface.
 117 @c As of 2005-10-21...
 118 There are no Gnus dependencies in this file.
 119
 120 @item imap.el
 121 @acronym{IMAP} library.
 122 @c As of 2005-10-21...
 123 There are no Gnus dependencies in this file.
 124
 125 @item ietf-drums.el
 126 Functions for parsing RFC822bis headers.
 127 @c As of 2005-10-21...
 128 There are no Gnus dependencies in this file.
 129
 130 @item rfc1843.el
 131 HZ (rfc1843) decoding.  HZ is a data format for exchanging files of
 132 arbitrarily mixed Chinese and @acronym{ASCII} characters.
 133 @c As of 2005-10-21...
 134 @code{rfc1843-gnus-setup} seem to be useful only for Gnus.  Maybe this
 135 function should be relocated to remove dependencies on Gnus.  Other
 136 minor dependencies: @code{gnus-newsgroup-name} could be eliminated by
 137 using an optional argument to @code{rfc1843-decode-article-body}.
 138
 139 @item rfc2045.el
 140 Functions for decoding rfc2045 headers
 141
 142 @item rfc2047.el
 143 Functions for encoding and decoding rfc2047 messages
 144
 145 @item rfc2104.el
 146 RFC2104 Hashed Message Authentication Codes
 147
 148 @item rfc2231.el
 149 Functions for decoding rfc2231 headers
 150 @end table
 151
 152 @subsection message
 153
 154 All message composition from Gnus (both mail and news) takes place in
 155 Message mode buffers.  Message mode is intended to be a replacement for
 156 Emacs mail mode.  There should be no Gnus dependencies in
 157 @file{message.el}.
 158
 159 @subsection Gnus backends
 160
 161 The files @file{nn*.el} provide functionality for accessing NNTP
 162 (@file{nntp.el}), IMAP (@file{nnimap.el}) and several other Mail back
 163 ends (probably @file{nnml.el}, @file{nnfolder.el} and
 164 @file{nnmaildir.el} are the ones most widely used mail back ends).
 165
 166
 167 @c message / gnus
 168 @c
 169 @c nn*
 170 @c
 171 @c mm*
 172 @c
 173 @c rfc*
 174 @c
 175 @c pgg*
 176 @c tla netrc pop3 dig dns ...
 177 @c format-spec.el
 178
 179
 180 @section Compatibility
 181
 182 @c Compatibility with XEmacs and older Emacs versions in v5-10 and in the
 183 @c trunk.
 184
 185 @c @table
 186 @c x
 187 @c @end table
 188
 189 @chapter Gnus Maintainance Guide
 190
 191 @section Stable and development versions
 192
 193 The CVS trunk is developed quite actively.
 194
 195 @c Most of the time Gnus is developed on the trunk.
 196
 197 @c Exeption: several month of feature freeze after a release,
 198 @c e.g. 5.10.1
 199
 200
 201 @section Syncing
 202
 203 @c Some MIDs related to this follow.  Use http://thread.gmane.org/MID
 204 @c (and click on the subject) to get the thread on Gmane.
 205
 206 @c Some quotes from Miles Bader follow...
 207
 208 @c <v9eklyke6b.fsf@marauder.physik.uni-ulm.de>
 209 @c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp>
 210
 211 I do Emacs->Gnus less often (than Gnus->Emacs) because it tends to
 212 require more manual work.
 213
 214 By default I sync about once a week.  I also try to follow any Gnus
 215 threads on the mailing lists and make sure any changes being discussed
 216 are kept more up-to-date (so say 1-2 days delay for "topical" changes).
 217
 218
 219 @c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp>
 220
 221 BTW, just to add even more verbose explanation about the syncing thing:
 222
 223 Basically my idea is that the Emacs-Gnus gateway will cause all common
 224 files in Emacs and Gnus v5-10 to be identical except when there's a very
 225 good reason (e.g., the Gnus version string in Emacs says "5.11", but the
 226 v5-10 version string remains "5.10.whatever").  Furthermore, all changes
 227 in these files in either Emacs or the v5-10 branch will be installed
 228 into the Gnus CVS trunk, again except where there's a good reason
 229 (typically so far the only exception has been that the changes already
 230 exist in the trunk in modified form).  Because of this, when the next
 231 Emacs Gnus upgrade comes, it should be very easy -- just plonk in the
 232 files from the Gnus trunk without worrying about lost changes from the
 233 Emacs tree.
 234
 235 The effect of this is that as hacker, you should generally only have to
 236 make changes in one place:
 237
 238   1) If it's a file which is thought of as being outside of Gnus (e.g.,
 239      the new "encrypt.el"), you should probably make the change in the
 240      Emacs tree, and it will show up in the Gnus tree a few days later.
 241
 242      If you don't have Emacs CVS access (or it's inconvenient), you can
 243      change such a file in the v5-10 branch, and it should propagate to
 244      Emacs CVS -- however, it will get some extra scrutiny (by me) to see
 245      if the changes are possibly controversial and need discussion on the
 246      mailing list.  [Many changes are obvious bug-fixes however, so often
 247      there won't be any problem.]
 248
 249   2) If it's to a Gnus file, and it's important enough that it should be
 250      part of Emacs/v5-10, then you can make the change on the v5-10
 251      branch, and it will go into Emacs CVS and the Gnus CVS trunk (a few
 252      days later).
 253
 254      If you know that there will be conflicts (perhaps because the
 255      affected source code is different in v5-10 and the Gnus CVS trunk),
 256      then you can install your change in both places, and when I try to
 257      sync them, there will be a conflict -- however, since in most such
 258      cases there would be a conflict _anyway_, it's often easier for me
 259      to resolve it simply if I see two "identical" changes, and can just
 260      choose the proper one, rather than having to actually fix the code.
 261
 262   3) For general Gnus development changes, of course you just make the
 263      change on the Gnus CVS trunk and it goes into Emacs a few years
 264      later... :-)
 265
 266 Of course in any case, if you just can't wait for me to sync your
 267 change, you can commit it in more than one place and probably there will
 268 be no problem; usually the changes are textually identical anyway, so
 269 can be easily resolved automatically (sometimes I notice silly things in
 270 such multiple commits, like whitespace differences, and unify those ;-).
 271
 272
 273 @section Miscellanea
 274
 275 @heading @file{GNUS-NEWS}
 276
 277 Starting from No Gnus, the @file{GNUS-NEWS} is created from
 278 @file{texi/gnus-news.texi}.  Don't edit @file{GNUS-NEWS}.  Edit
 279 @file{texi/gnus-news.texi}, type @command{make GNUS-NEWS} in the
 280 @file{texi} directory and commit @file{GNUS-NEWS} and
 281 @file{texi/gnus-news.texi}.
 282
 283
 284 @c Local Variables:
 285 @c mode: texinfo
 286 @c coding: iso-8859-1
 287 @c End:
 288
 289 @ignore
 290    arch-tag: ab15234c-2c8a-4cbd-8111-1811bcc6f931
 291 @end ignore