Required tools
--------------

If you are planning to hack on Mutt-ng, please subscribe to the
Mutt-ng-devel mailinglist (mutt-ng-deve-l@lists.berlios.de).
Announcements about recent development
versions go to that mailing list, as go technical discussions and
patches.

You'll need several GNU development utilities for working on mutt-ng:

- automake

- autoconf

- autoheader

- The i18n stuff requires GNU gettext.  See intl/VERSION for the
  version we are currently relying on.  Please note that using
  gettext-0.10 will most probably not work - get the latest test
  release from alpha.gnu.org, it's the recommended version of
  gettext anyway.

  If you are experiencing problems with unknown "dcgettext" symbols,
  the autoconf/automake macros from your gettext package are broken.
  Apply the following patch to that macro file (usually found under
  /usr/share/aclocal/gettext.m4):

--- gettext.m4.bak	Thu Jul  2 18:46:08 1998
+++ gettext.m4	Mon Oct  5 23:32:54 1998
@@ -46,12 +46,13 @@
 
 	   if test "$gt_cv_func_gettext_libc" != "yes"; then
 	     AC_CHECK_LIB(intl, bindtextdomain,
-	       [AC_CACHE_CHECK([for gettext in libintl],
-		 gt_cv_func_gettext_libintl,
-		 [AC_CHECK_LIB(intl, gettext,
-		  gt_cv_func_gettext_libintl=yes,
-		  gt_cv_func_gettext_libintl=no)],
+	       [AC_CHECK_LIB(intl, gettext,
+	         gt_cv_func_gettext_libintl=yes,
 		 gt_cv_func_gettext_libintl=no)])
+	   fi
+
+	   if test "$gt_cv_func_gettext_libintl" = "yes" ; then
+	     LIBS="-lintl $LIBS"
 	   fi
 
 	   if test "$gt_cv_func_gettext_libc" = "yes" \


- GNU make may be needed for the dependency tricks


Getting started from SVN
------------------------

Once you've checked out a copy of the source from SVN from
svn.berlios.de/svnroot/repos/mutt-ng , you'll need to run the script
called 'autogen.sh' that is in the root directory.  The script does all the
automake/autoconf magic that needs to be done with a fresh checkout. If
all steps succeed, you'll have a configure script to start off with.


A word about warnings
---------------------

Mutt-ng's default build process sets some pretty restrictive compiler
flags which may lead to lots of warnings.  Generally, warnings are
something which should be eliminated.

Nevertheless, the code in intl/ is said to generate some warnings with
the compiler settings we usually rely upon.  This code is not
maintained by the Mutt-ng developpers, so please redirect any comments to
the GNU gettext library's developpers.


Style Guide
-----------

- global functions outside the library directory should have the prefix
  "mutt_". All other functions should be declared "static". All global
  functions defined within the library directory should have the the
  prefix according to their source file, i.e. "str_" for everything in
  lib/str.[ch] etc.

- avoid global vars where possible.  If one is required,
  try to contain it to a single source file and declare it
  "static".  Global vars should have the first letter of
  each word capitilized, and no underscores should be used
  (e.g., MailGid, LastFolder, MailDir).

- re-use code as much as possible.  There are a lot of
  "library" functions. One of the biggest causes of bloat
  in ELM and PINE is the tremendous duplication of code...
  Help keep Mutt small!

- When adding new options, make the old behaviour the default. Also,
  add them to UPGRADING in the top-level source directory.

- try to keep Mutt-ng as portable as possible.

Documentation
-------------

Please document your changes.  Note that there are several places
where you may have to add documentation:

- doc/manual.sgml.{head,tail} contain The Manual.

- doc/muttngrc.man.{head,tail} contain an abriged version of The
  Manual in nroff format (see man(7)), which deals with
  configuration file commands.

Configuration _variables_ are documented directly in init.h.   Note
that this includes documentation for possibly added format flags!

When adding variables which depend on system-functionality and/or
./configure switches, you have to add additional "availability"
information to init.h to avoid confusion in the manual. Please see
init.h for examples.

The parts of The Manual and the muttngrc manual page dealing with
these variables, and the global Muttrc, are generated automatically
from that documentation.  To start this process, type "make
update-doc" in the top-level source directory.

Note that you may have to update the makedoc utility (makedoc.c)
when adding new data types to init.h.

More precisely, variable name, type, and default value are directly
extracted from the initializer for the MuttVars array. Documentation
is exepected in special comments which _follow_ the initializer.
For a line to be included with the documentation, it must (after,
possibly, some white space) begin with with either "/**" or "**".
Any following white space is ignored. The rest of the line is
expected to be plain text, with some formatting instructions roughly
similar to [ntg]roff:

 - \fI switches to italics
 
 - \fB switches to boldface

 - \fT switches to typewriter (only for SGML and ignored otherwise)

 - \fP switches to normal display

 - \(as can be used to represent an asterisk (*).  This is intended
   to help avoiding character sequences such as /* or */ inside
   comments.

 - \(rs can be used to represent a backslash (\).  This is intended
   to help avoiding poblems when trying to represent any of the \
   sequences used by makedoc.

 - .dl on a line starts a "definition list" environment (name taken
    from HTML) where terms and definitions alternate.

 - .dt marks a term in a definition list.

 - .dd marks a definition in a definition list.

 - .de on a line finishes a definition list environment.

 - .ts on a line starts a "verbose tscreen" environment (name taken from
   SGML).  Please try to keep lines inside such an environment
   short; a length of abut 40 characters should be ok.  This is
   necessary to avoid a really bad-looking muttngrc (5) manual page.

 - .te on a line finishes this environment.

 - .pp on a line starts a paragraph.

 - $word will be converted to a reference to word, where appropriate.
   Note that $$word is possible as well.
   Use $$$ to get a literal $ without making a reference.

 - '. ' in the beginning of a line expands to two space characters.
   This is used to protect indentations in tables.

Do _not_ use any other SGML or nroff formatting instructions here!


String comparison
-----------------

A word of warning about string comparisons: Since Mutt-ng may run in a
huge variety of locales, case-insensitive string comparisons and
case conversions may be dangerous.  For instance, in iso-8859-9,
tolower('I') is DIFFERENT from 'i' - it's indeed the Turkish dotless
lowercase i.

For this reason, always use the ascii_* functions defined in ascii.h
and implemented in ascii.c when comparing or handling strings which
are defined as us-ascii.  This concerns lots of text-based
protocols, message header tags, character set names, domain names,
e-mail addresses, etc.
