doc/devel-notes.txt

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