doc/devel-notes.txt

   1 Subject: Developers' notes
   2 From: Thomas Roessler <roessler@guug.de>
   3 Date: Tue,  9 May 2000 19:48:08 +0200
   4
   5
   6 Required tools
   7 --------------
   8
   9 If you are planning to hack on mutt, please subscribe to the
  10 mutt-dev mailinglist (mutt-dev@mutt.org, contact
  11 majordomo@mutt.org).  Announcements about recent development
  12 versions go to that mailing list, as go technical discussions and
  13 patches.
  14
  15 You'll need several GNU development utilities for working on mutt:
  16
  17 - automake
  18
  19 - autoconf
  20
  21 - autoheader
  22
  23 - The i18n stuff requires GNU gettext.  See intl/VERSION for the
  24   version we are currently relying on.  Please note that using
  25   gettext-0.10 will most probably not work - get the latest test
  26   release from alpha.gnu.org, it's the recommended version of
  27   gettext anyway.
  28
  29   If you are experiencing problems with unknown "dcgettext" symbols,
  30   the autoconf/automake macros from your gettext package are broken.
  31   Apply the following patch to that macro file (usually found under
  32   /usr/share/aclocal/gettext.m4):
  33
  34 --- gettext.m4.bak      Thu Jul  2 18:46:08 1998
  35 +++ gettext.m4  Mon Oct  5 23:32:54 1998
  36 @@ -46,12 +46,13 @@
  37
  38            if test "$gt_cv_func_gettext_libc" != "yes"; then
  39              AC_CHECK_LIB(intl, bindtextdomain,
  40 -              [AC_CACHE_CHECK([for gettext in libintl],
  41 -                gt_cv_func_gettext_libintl,
  42 -                [AC_CHECK_LIB(intl, gettext,
  43 -                 gt_cv_func_gettext_libintl=yes,
  44 -                 gt_cv_func_gettext_libintl=no)],
  45 +              [AC_CHECK_LIB(intl, gettext,
  46 +                gt_cv_func_gettext_libintl=yes,
  47                  gt_cv_func_gettext_libintl=no)])
  48 +          fi
  49 +
  50 +          if test "$gt_cv_func_gettext_libintl" = "yes" ; then
  51 +            LIBS="-lintl $LIBS"
  52            fi
  53
  54            if test "$gt_cv_func_gettext_libc" = "yes" \
  55
  56
  57 - GNU make may be needed for the dependency tricks
  58
  59
  60 Getting started from CVS
  61 ------------------------
  62
  63 Once you've checked out a copy of the source from CVS, you'll need to
  64 run the script called 'prepare' that is in the root directory.  The
  65 script does all the automake/autoconf magic that needs to be done with
  66 a fresh checkout.
  67
  68
  69 A word about warnings
  70 ---------------------
  71
  72 Mutt's default build process sets some pretty restrictive compiler
  73 flags which may lead to lots of warnings.  Generally, warnings are
  74 something which should be eliminated.
  75
  76 Nevertheless, the code in intl/ is said to generate some warnings with
  77 the compiler settings we usually rely upon.  This code is not
  78 maintained by the mutt developpers, so please redirect any comments to
  79 the GNU gettext library's developpers.
  80
  81
  82 Style Guide
  83 -----------
  84
  85 - global functions should have the prefix "mutt_".  All
  86   other functions should be declared "static".
  87
  88 - avoid global vars where possible.  If one is required,
  89   try to contain it to a single source file and declare it
  90   "static".  Global vars should have the first letter of
  91   each word capitilized, and no underscores should be used
  92   (e.g., MailGid, LastFolder, MailDir).
  93
  94 - re-use code as much as possible.  There are a lot of
  95   "library" functions. One of the biggest causes of bloat
  96   in ELM and PINE is the tremendous duplication of code...
  97   Help keep Mutt small!
  98
  99 - when adding new options, make the old behaviour the
 100   default.
 101
 102 - try to keep mutt as portable as possible.
 103
 104
 105 Documentation
 106 -------------
 107
 108 Please document your changes.  Note that there are several places
 109 where you may have to add documentation:
 110
 111 - doc/manual.sgml.{head,tail} contain The Manual.
 112
 113 - doc/muttrc.man.{head,tail} contain an abriged version of The
 114   Manual in nroff format (see man(7)), which deals with
 115   configuration file commands.
 116
 117 Configuration _variables_ are documented directly in init.h.   Note
 118 that this includes documentation for possibly added format flags!
 119
 120 The parts of The Manual and the muttrc manual page dealing with
 121 these variables, and the global Muttrc, are generated automatically
 122 from that documentation.  To start this process, type "make
 123 update-doc" in the top-level source directory.
 124
 125 Note that you may have to update the makedoc utility (makedoc.c)
 126 when adding new data types to init.h.
 127
 128 More precisely, variable name, type, and default value are directly
 129 extracted from the initializer for the MuttVars array. Documentation
 130 is exepected in special comments which _follow_ the initializer.
 131 For a line to be included with the documentation, it must (after,
 132 possibly, some white space) begin with with either "/**" or "**".
 133 Any following white space is ignored. The rest of the line is
 134 expected to be plain text, with some formatting instructions roughly
 135 similar to [ntg]roff:
 136
 137  - \fI switches to italics
 138
 139  - \fB switches to boldface
 140
 141  - \fP switches to normal display
 142
 143  - \(as can be used to represent an asterisk (*).  This is intended
 144    to help avoiding character sequences such as /* or */ inside
 145    comments.
 146
 147  - \(rs can be used to represent a backslash (\).  This is intended
 148    to help avoiding poblems when trying to represent any of the \
 149    sequences used by makedoc.
 150
 151  - .dl on a line starts a "definition list" environment (name taken
 152     from HTML) where terms and definitions alternate.
 153
 154  - .dt marks a term in a definition list.
 155
 156  - .dd marks a definition in a definition list.
 157
 158  - .de on a line finishes a definition list environment.
 159
 160  - .ts on a line starts a "verbose tscreen" environment (name taken from
 161    SGML).  Please try to keep lines inside such an environment
 162    short; a length of abut 40 characters should be ok.  This is
 163    necessary to avoid a really bad-looking muttrc (5) manual page.
 164
 165  - .te on a line finishes this environment.
 166
 167  - .pp on a line starts a paragraph.
 168
 169  - $word will be converted to a reference to word, where appropriate.
 170    Note that $$word is possible as well.
 171    Use $$$ to get a literal $ without making a reference.
 172
 173  - '. ' in the beginning of a line expands to two space characters.
 174    This is used to protect indentations in tables.
 175
 176 Do _not_ use any other SGML or nroff formatting instructions here!
 177
 178 $Id: devel-notes.txt,v 3.0 2002/01/24 13:35:07 roessler Exp $