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