jcs.org
mutt stable branch with some hacks
1Required tools
2--------------
3
4If you are planning to hack on mutt, please subscribe to the
5mutt-dev mailing list (mutt-dev@mutt.org, contact
6majordomo@mutt.org). Announcements about recent development
7versions go to that mailing list, as go technical discussions and
8patches.
9
10Patches should, if possible, be made using Mercurial against
11the latest revision.
12
13You'll need several GNU development utilities for working on mutt:
14
15- autoconf (versions less than 2.59 are unsupported)
16 (this package includes autoheader and autoreconf)
17
18 If the build fails during any of the auto* stages, first of all try if
19 re-running the ./prepare script fixes things. Remember to give the
20 same options you passed to it or to the configure it generated the
21 last time, you can query them with:
22 ./config.status --version
23
24- automake (versions less than 1.9 are not officially supported)
25 (this package includes aclocal)
26
27 Note that you MUST re-run ./prepare (with the original arguments)
28 if you change the automake version between builds for the same source
29 directory.
30
31- GNU make may be needed for the dependency tricks
32
33- The internationalization (i18n) stuff requires GNU gettext.
34 See intl/VERSION for the version we are currently relying on.
35 Please note that using gettext-0.10 will most probably not work -
36 get the latest test release from alpha.gnu.org, it's the recommended
37 version of gettext anyway.
38
39 If you are experiencing problems with unknown "dcgettext" symbols,
40 the autoconf/automake macros from your gettext package are broken.
41 Apply the following patch to that macro file (usually found under
42 /usr/share/aclocal/gettext.m4):
43
44--- gettext.m4.bak Thu Jul 2 18:46:08 1998
45+++ gettext.m4 Mon Oct 5 23:32:54 1998
46@@ -46,12 +46,13 @@
47
48 if test "$gt_cv_func_gettext_libc" != "yes"; then
49 AC_CHECK_LIB(intl, bindtextdomain,
50- [AC_CACHE_CHECK([for gettext in libintl],
51- gt_cv_func_gettext_libintl,
52- [AC_CHECK_LIB(intl, gettext,
53- gt_cv_func_gettext_libintl=yes,
54- gt_cv_func_gettext_libintl=no)],
55+ [AC_CHECK_LIB(intl, gettext,
56+ gt_cv_func_gettext_libintl=yes,
57 gt_cv_func_gettext_libintl=no)])
58+ fi
59+
60+ if test "$gt_cv_func_gettext_libintl" = "yes" ; then
61+ LIBS="-lintl $LIBS"
62 fi
63
64 if test "$gt_cv_func_gettext_libc" = "yes" \
65
66
67Generating Mutt Documentation From Source
68-----------------------------------------
69
70To translate Mutt's Docbook XML documentation into HTML (and then text),
71you'll need one tool and two sets of data which you may need to download
72and install. The tool is xsltproc (part of the libxslt package), and
73it's a command-line program for performing XSL transformations on XML
74documents. The data sets are the Docbook XML and Docbook XSL libraries.
75
76Whenever your operating system provides packages or pkgsrc or ports of
77these, you should install them. Some systems, for instance SUSE Linux
78and FreeBSD's ports system, automatically set up a registry of installed
79XML/XSL and SGML catalogs so that the user does not need to care about
80what to install where, how to set environment variables, and so on.
81
82If your system does not provide these libraries and data sets,
83you can download them from:
84
85 . xsltproc
86 http://xmlsoft.org/
87 ftp://xmlsoft.org/libxslt/libxslt-1.1.17.tar.gz
88
89 . docbook-xml-4.2
90 http://www.docbook.org/
91 http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip
92
93 . docbook-xsl-1.70.1
94 http://docbook.sourceforge.net/
95 http://prdownloads.sourceforge.net/docbook/docbook-xsl-1.70.1.zip
96
97First, if you don't already have xsltproc, build and install libxslt,
98which will provide xsltproc, too.
99
100Next, obtain and unpack the two docbook archives. You can unpack these
101anywhere that you want to have them installed -- there's no installation
102procedure other than unarchival. On my Solaris system, I install
103packages under /opt/pkgs/packagename-version, so I unpacked these ZIP
104archives to /opt/pkgs/docbook-xml-4.2 and /opt/pkgs/docbook-xsl-1.70.1.
105
106Now you need to create (and export) an environment variable to process
107the manuals. The environment variable will contain a space-separated
108list of "catalog" files for the two docbook archives, so substitute
109the path where you unpacked them below:
110
111 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
112or
113 csh$ setenv XML_CATALOG_FILES "/path/to/docbook-xml-4.2/catalog.xml /path/to/docbook-xsl-1.70.1/catalog.xml"
114
115Once all these are installed and XML_CATALOG_FILES is set, you should be
116able to generate manual.html with a simple "make" -- all as a part of
117the mutt compilation.
118
119The Makefile depends upon lynx (or any other text-mode web browser)
120to turn the HTML into text, so if that fails you may need to install
121something else.
122
123
124Getting started from Mercurial
125------------------------------
126
127The official Mercurial repository is located at:
128http://dev.mutt.org/hg/mutt/. You can get a fresh clone via:
129
130 $ hg clone http://dev.mutt.org/hg/mutt/ mutt
131
132Once you've checked out a copy of the source, or changed your
133automake version, you'll need to run the script called './prepare' that
134is in the root directory. The script does all the automake/autoconf
135magic that needs to be done with a fresh checkout.
136
137
138Contributing patches
139--------------------
140
141As Mercurial is a distributed version control system, it's easy to
142commit changes locally without impacting anybody else's work, starting
143over again, or turn several commit and backouts into a new single patch
144ready for submission.
145
146These so-called "changesets" (a diff with a reasonable message
147describing the change) can be exported using Mercurial through the
148"patchbomb" extension shipped with Mercurial (please see the hg
149documentation for details) which also is the preferred format for
150submission to the mutt-dev mailing list for discussion and review.
151
152In order to ease later bisecting in case of bugs and code history,
153changes should be grouped logically, feature by feature or bugfix by
154bugfix. Especially a single patch fixing several problems at once
155should be avoided.
156
157Before submitting patches, please make sure the check_sec.sh script
158in the top-level source directory reports no errors/warnings.
159
160A word about warnings
161---------------------
162
163Mutt's default build process sets some pretty restrictive compiler
164flags which may lead to lots of warnings. Generally, warnings are
165something which should be eliminated.
166
167Nevertheless, the code in intl/ is said to generate some warnings with
168the compiler settings we usually rely upon. This code is not
169maintained by the mutt developers, so please redirect any comments to
170the GNU gettext library's developers.
171
172
173Style Guide
174-----------
175
176- global functions should have the prefix "mutt_". All
177 other functions should be declared "static".
178
179- avoid global variables where possible. If one is required,
180 try to contain it to a single source file and declare it
181 "static". Global variables should have the first letter of
182 each word capitalized, and no underscores should be used
183 (e.g., MailGid, LastFolder, MailDir).
184
185- re-use code as much as possible. There are a lot of
186 "library" functions. One of the biggest causes of bloat
187 in ELM and PINE is the tremendous duplication of code...
188 Help keep Mutt small!
189
190- when adding new options, make the old behavior the
191 default.
192
193- try to keep mutt as portable as possible.
194
195- special characters should be in utf-8. If you find remnants
196 from the times when this was an iso-8859-1 source code tree,
197 please feel free to fix them.
198
199- prefix translator comments with L10N:
200 /* L10N: this is a translator comment */
201 puts(_("String to translate));
202
203Documentation
204-------------
205
206Please document your changes. Note that there are several places
207where you may have to add documentation:
208
209- doc/manual.xml.{head,tail} contain The Manual.
210
211- doc/muttrc.man.{head,tail} contain an abridged version of The
212 Manual in nroff format (see man(7)), which deals with
213 configuration file commands.
214
215- UPDATING includes short documentation of user-visible
216 changes, i.e., any incompatibilities should go here.
217
218Configuration _variables_ are documented directly in init.h. Note
219that this includes documentation for possibly added format flags!
220
221The parts of The Manual and the muttrc manual page dealing with
222these variables, and the global Muttrc, are generated automatically
223from that documentation. To start this process, type "make
224update-doc" in the top-level source directory.
225
226Note that you may have to update the makedoc utility (makedoc.c)
227when adding new data types to init.h.
228
229More precisely, variable name, type, and default value are directly
230extracted from the initializer for the MuttVars array. Documentation
231is expected in special comments which _follow_ the initializer.
232For a line to be included with the documentation, it must (after,
233possibly, some white space) begin with either "/**" or "**".
234Any following white space is ignored. The rest of the line is
235expected to be plain text, with some formatting instructions roughly
236similar to [ntg]roff:
237
238 - \fI switches to italics
239
240 - \fB switches to boldface
241
242 - \fT switches to monospace
243
244 - \fP switches to normal display after \fI, \fB or \fT
245
246 - \(as can be used to represent an asterisk (*). This is intended
247 to help avoiding character sequences such as /* or */ inside
248 comments.
249
250 - \(rs can be used to represent a backslash (\). This is intended
251 to help avoiding problems when trying to represent any of the \
252 sequences used by makedoc.
253
254 - .dl on a line starts a "definition list" environment (name taken
255 from HTML) where terms and definitions alternate.
256
257 - .dt marks a term in a definition list.
258
259 - .dd marks a definition in a definition list.
260
261 - .de on a line finishes a definition list environment.
262
263 - .ts on a line starts a "verbose tscreen" environment (name taken from
264 SGML). Please try to keep lines inside such an environment
265 short; a length of about 40 characters should be OK. This is
266 necessary to avoid a really bad-looking muttrc (5) manual page.
267
268 - .te on a line finishes this environment.
269
270 - .pp on a line starts a paragraph.
271
272 - $word will be converted to a reference to word, where appropriate.
273 Note that $$word is possible as well.
274 Use $$$ to get a literal $ without making a reference.
275
276 - '. ' in the beginning of a line expands to two space characters.
277 This is used to protect indentations in tables.
278
279Do _not_ use any other SGML or nroff formatting instructions here!
280