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. Escpecially a single patch fixing several problems at once
 161 should be avoided.
 162
 163
 164 A word about warnings
 165 ---------------------
 166
 167 Mutt's default build process sets some pretty restrictive compiler
 168 flags which may lead to lots of warnings.  Generally, warnings are
 169 something which should be eliminated.
 170
 171 Nevertheless, the code in intl/ is said to generate some warnings with
 172 the compiler settings we usually rely upon.  This code is not
 173 maintained by the mutt developers, so please redirect any comments to
 174 the GNU gettext library's developers.
 175
 176
 177 Style Guide
 178 -----------
 179
 180 - global functions should have the prefix "mutt_".  All
 181   other functions should be declared "static".
 182
 183 - avoid global variables where possible.  If one is required,
 184   try to contain it to a single source file and declare it
 185   "static".  Global variables should have the first letter of
 186   each word capitalized, and no underscores should be used
 187   (e.g., MailGid, LastFolder, MailDir).
 188
 189 - re-use code as much as possible.  There are a lot of
 190   "library" functions. One of the biggest causes of bloat
 191   in ELM and PINE is the tremendous duplication of code...
 192   Help keep Mutt small!
 193
 194 - when adding new options, make the old behavior the
 195   default.
 196
 197 - try to keep mutt as portable as possible.
 198
 199 - special characters should be in utf-8.  If you find remnants
 200   from the times when this was an iso-8859-1 source code tree,
 201   please feel free to fix them.
 202
 203 Documentation
 204 -------------
 205
 206 Please document your changes.  Note that there are several places
 207 where 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
 218 Configuration _variables_ are documented directly in init.h.   Note
 219 that this includes documentation for possibly added format flags!
 220
 221 The parts of The Manual and the muttrc manual page dealing with
 222 these variables, and the global Muttrc, are generated automatically
 223 from that documentation.  To start this process, type "make
 224 update-doc" in the top-level source directory.
 225
 226 Note that you may have to update the makedoc utility (makedoc.c)
 227 when adding new data types to init.h.
 228
 229 More precisely, variable name, type, and default value are directly
 230 extracted from the initializer for the MuttVars array. Documentation
 231 is expected in special comments which _follow_ the initializer.
 232 For a line to be included with the documentation, it must (after,
 233 possibly, some white space) begin with either "/**" or "**".
 234 Any following white space is ignored. The rest of the line is
 235 expected to be plain text, with some formatting instructions roughly
 236 similar 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
 279 Do _not_ use any other SGML or nroff formatting instructions here!
 280