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