doc/devel-notes.txt

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