1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
|
Required tools
--------------
If you are planning to hack on mutt, please subscribe to the
mutt-dev mailing list (mutt-dev@mutt.org). To subscribe, send an
email with as subject "subscribe" to mutt-dev-request@mutt.org .
Announcements about recent development versions go to that mailing
list, as go technical discussions and patches.
Patches should, if possible, be made using Git against the latest
revision.
You'll need several GNU development utilities for working on mutt:
- autoconf (versions less than 2.59 are unsupported)
(this package includes autoheader and autoreconf)
If the build fails during any of the auto* stages, first of all try if
re-running the ./prepare script fixes things. Remember to give the
same options you passed to it or to the configure it generated the
last time, you can query them with:
./config.status --version
- automake (versions less than 1.9 are not officially supported)
(this package includes aclocal)
Note that you MUST re-run ./prepare (with the original arguments)
if you change the automake version between builds for the same source
directory.
- GNU make may be needed for the dependency tricks
- The internationalization (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" \
Generating Mutt Documentation From Source
-----------------------------------------
To translate Mutt's Docbook XML documentation into HTML (and then text),
you'll need one tool and two sets of data which you may need to download
and install. The tool is xsltproc (part of the libxslt package), and
it's a command-line program for performing XSL transformations on XML
documents. The data sets are the Docbook XML and Docbook XSL libraries.
Whenever your operating system provides packages or pkgsrc or ports of
these, you should install them. Some systems, for instance SUSE Linux
and FreeBSD's ports system, automatically set up a registry of installed
XML/XSL and SGML catalogs so that the user does not need to care about
what to install where, how to set environment variables, and so on.
If your system does not provide these libraries and data sets,
you can download them from:
. xsltproc
http://xmlsoft.org/
ftp://xmlsoft.org/libxslt/libxslt-1.1.17.tar.gz
. docbook-xml-4.2
http://www.docbook.org/
http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip
. docbook-xsl-1.70.1
http://docbook.sourceforge.net/
http://prdownloads.sourceforge.net/docbook/docbook-xsl-1.70.1.zip
First, if you don't already have xsltproc, build and install libxslt,
which will provide xsltproc, too.
Next, obtain and unpack the two docbook archives. You can unpack these
anywhere that you want to have them installed -- there's no installation
procedure other than unarchival. On my Solaris system, I install
packages under /opt/pkgs/packagename-version, so I unpacked these ZIP
archives to /opt/pkgs/docbook-xml-4.2 and /opt/pkgs/docbook-xsl-1.70.1.
Now you need to create (and export) an environment variable to process
the manuals. The environment variable will contain a space-separated
list of "catalog" files for the two docbook archives, so substitute
the path where you unpacked them below:
sh$ XML_CATALOG_FILES="/path/to/docbook-xml-4.2/catalog.xml /path/to/docbook-xsl-1.70.1/catalog.xml"; export XML_CATALOG_FILES
or
csh$ setenv XML_CATALOG_FILES "/path/to/docbook-xml-4.2/catalog.xml /path/to/docbook-xsl-1.70.1/catalog.xml"
Once all these are installed and XML_CATALOG_FILES is set, you should be
able to generate manual.html with a simple "make" -- all as a part of
the mutt compilation.
The Makefile depends upon lynx (or any other text-mode web browser)
to turn the HTML into text, so if that fails you may need to install
something else.
Getting started from Git
------------------------
The official Git repository is located at:
https://gitlab.com/muttmua/mutt. You can get a fresh clone via:
$ git clone https://gitlab.com/muttmua/mutt.git mutt
Once you've checked out a copy of the source, or changed your
automake version, you'll need to run the script called './prepare' that
is in the root directory. The script does all the automake/autoconf
magic that needs to be done with a fresh checkout.
Contributing patches
--------------------
As Git is a distributed version control system, it's easy to
commit changes locally without impacting anybody else's work, starting
over again, or turn several commit and backouts into a new single patch
ready for submission.
These so-called "changesets" (a diff with a reasonable message
describing the change) can be exported using Git through the
"send-email" command (please see the git documentation for details)
which also is the preferred format for submission to the mutt-dev
mailing list for discussion and review.
In order to ease later bisecting in case of bugs and code history,
changes should be grouped logically, feature by feature or bugfix by
bugfix. Especially a single patch fixing several problems at once
should be avoided.
Before submitting patches, please make sure the check_sec.sh script
in the top-level source directory reports no errors/warnings.
Documentation changes should be validated by running 'make validate'
in the doc subdirectory.
String comparisons
------------------
A word of warning about string comparisons: Since mutt 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.
A word about warnings
---------------------
Mutt'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 developers, so please redirect any comments to
the GNU gettext library's developers.
Style Guide
-----------
- global functions should have the prefix "mutt_". All
other functions should be declared "static".
- avoid global variables where possible. If one is required,
try to contain it to a single source file and declare it
"static". Global variables should have the first letter of
each word capitalized, 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 behavior the
default.
- try to keep mutt as portable as possible.
- special characters should be in utf-8. If you find remnants
from the times when this was an iso-8859-1 source code tree,
please feel free to fix them.
- prefix translator comments with L10N:
/* L10N: this is a translator comment */
puts(_("String to translate));
Documentation
-------------
Please document your changes. Note that there are several places
where you may have to add documentation:
- doc/manual.xml.{head,tail} contain The Manual.
- doc/muttrc.man.{head,tail} contain an abridged version of The
Manual in nroff format (see man(7)), which deals with
configuration file commands.
- UPDATING includes short documentation of user-visible
changes, i.e., any incompatibilities should go here.
Configuration _variables_ are documented directly in init.h. Note
that this includes documentation for possibly added format flags!
The parts of The Manual and the muttrc 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.pl)
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 expected 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 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 monospace
- \fP switches to normal display after \fI, \fB or \fT
- \(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 problems 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 about 40 characters should be OK. This is
necessary to avoid a really bad-looking muttrc (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!
|
