Rocco Rutte:
[apps/madmutt.git] / 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 'autogen.sh' 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 outside the library directory should have the prefix
82   "mutt_". All other functions should be declared "static". All global
83   functions defined within the library directory should have the the
84   prefix according to their source file, i.e. "str_" for everything in
85   lib/str.[ch] etc.
86
87 - avoid global vars where possible.  If one is required,
88   try to contain it to a single source file and declare it
89   "static".  Global vars should have the first letter of
90   each word capitilized, and no underscores should be used
91   (e.g., MailGid, LastFolder, MailDir).
92
93 - re-use code as much as possible.  There are a lot of
94   "library" functions. One of the biggest causes of bloat
95   in ELM and PINE is the tremendous duplication of code...
96   Help keep Mutt small!
97
98 - When adding new options, make the old behaviour the default. Also,
99   add them to UPGRADING in the top-level source directory.
100
101 - try to keep Mutt-ng as portable as possible.
102
103 Documentation
104 -------------
105
106 Please document your changes.  Note that there are several places
107 where you may have to add documentation:
108
109 - doc/manual.sgml.{head,tail} contain The Manual.
110
111 - doc/muttngrc.man.{head,tail} contain an abriged version of The
112   Manual in nroff format (see man(7)), which deals with
113   configuration file commands.
114
115 Configuration _variables_ are documented directly in init.h.   Note
116 that this includes documentation for possibly added format flags!
117
118 When adding variables which depend on system-functionality and/or
119 ./configure switches, you have to add additional "availability"
120 information to init.h to avoid confusion in the manual. Please see
121 init.h for examples.
122
123 The parts of The Manual and the muttngrc manual page dealing with
124 these variables, and the global Muttrc, are generated automatically
125 from that documentation.  To start this process, type "make
126 update-doc" in the top-level source directory.
127
128 Note that you may have to update the makedoc utility (makedoc.c)
129 when adding new data types to init.h.
130
131 More precisely, variable name, type, and default value are directly
132 extracted from the initializer for the MuttVars array. Documentation
133 is exepected in special comments which _follow_ the initializer.
134 For a line to be included with the documentation, it must (after,
135 possibly, some white space) begin with with either "/**" or "**".
136 Any following white space is ignored. The rest of the line is
137 expected to be plain text, with some formatting instructions roughly
138 similar to [ntg]roff:
139
140  - \fI switches to italics
141  
142  - \fB switches to boldface
143
144  - \fT switches to typewriter (only for SGML and ignored otherwise)
145
146  - \fP switches to normal display
147
148  - \(as can be used to represent an asterisk (*).  This is intended
149    to help avoiding character sequences such as /* or */ inside
150    comments.
151
152  - \(rs can be used to represent a backslash (\).  This is intended
153    to help avoiding poblems when trying to represent any of the \
154    sequences used by makedoc.
155
156  - .dl on a line starts a "definition list" environment (name taken
157     from HTML) where terms and definitions alternate.
158
159  - .dt marks a term in a definition list.
160
161  - .dd marks a definition in a definition list.
162
163  - .de on a line finishes a definition list environment.
164
165  - .ts on a line starts a "verbose tscreen" environment (name taken from
166    SGML).  Please try to keep lines inside such an environment
167    short; a length of abut 40 characters should be ok.  This is
168    necessary to avoid a really bad-looking muttngrc (5) manual page.
169
170  - .te on a line finishes this environment.
171
172  - .pp on a line starts a paragraph.
173
174  - $word will be converted to a reference to word, where appropriate.
175    Note that $$word is possible as well.
176    Use $$$ to get a literal $ without making a reference.
177
178  - '. ' in the beginning of a line expands to two space characters.
179    This is used to protect indentations in tables.
180
181 Do _not_ use any other SGML or nroff formatting instructions here!
182
183
184 String comparison
185 -----------------
186
187 A word of warning about string comparisons: Since Mutt-ng may run in a
188 huge variety of locales, case-insensitive string comparisons and
189 case conversions may be dangerous.  For instance, in iso-8859-9,
190 tolower('I') is DIFFERENT from 'i' - it's indeed the Turkish dotless
191 lowercase i.
192
193 For this reason, always use the ascii_* functions defined in ascii.h
194 and implemented in ascii.c when comparing or handling strings which
195 are defined as us-ascii.  This concerns lots of text-based
196 protocols, message header tags, character set names, domain names,
197 e-mail addresses, etc.