1 Subject: Developers' notes
2 From: Thomas Roessler <roessler@guug.de>
3 Date: Tue, 9 May 2000 19:48:08 +0200
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
15 You'll need several GNU development utilities for working on mutt:
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
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):
34 --- gettext.m4.bak Thu Jul 2 18:46:08 1998
35 +++ gettext.m4 Mon Oct 5 23:32:54 1998
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)])
50 + if test "$gt_cv_func_gettext_libintl" = "yes" ; then
54 if test "$gt_cv_func_gettext_libc" = "yes" \
57 - GNU make may be needed for the dependency tricks
60 Getting started from CVS
61 ------------------------
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
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.
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.
85 - global functions should have the prefix "mutt_". All
86 other functions should be declared "static".
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).
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...
99 - when adding new options, make the old behaviour the
102 - try to keep mutt as portable as possible.
108 Please document your changes. Note that there are several places
109 where you may have to add documentation:
111 - doc/manual.sgml.{head,tail} contain The Manual.
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.
117 Configuration _variables_ are documented directly in init.h. Note
118 that this includes documentation for possibly added format flags!
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.
125 Note that you may have to update the makedoc utility (makedoc.c)
126 when adding new data types to init.h.
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:
137 - \fI switches to italics
139 - \fB switches to boldface
141 - \fP switches to normal display
143 - \(as can be used to represent an asterisk (*). This is intended
144 to help avoiding character sequences such as /* or */ inside
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.
151 - .dl on a line starts a "definition list" environment (name taken
152 from HTML) where terms and definitions alternate.
154 - .dt marks a term in a definition list.
156 - .dd marks a definition in a definition list.
158 - .de on a line finishes a definition list environment.
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.
165 - .te on a line finishes this environment.
167 - .pp on a line starts a paragraph.
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.
173 - '. ' in the beginning of a line expands to two space characters.
174 This is used to protect indentations in tables.
176 Do _not_ use any other SGML or nroff formatting instructions here!
178 $Id: devel-notes.txt,v 3.0 2002/01/24 13:35:07 roessler Exp $