+#
+# README.developers
+#
+# $Id$
+#
+
+This file is intended to provide a few tips for anyone doing development on nmh.
+Developers who learn things "the hard way" about the nmh codebase (as opposed to
+local info best encoded in a comment) are encouraged to share their wisdom here.
+
+The topics are organized alphabetically.
+
+
+--------------
+autoconf files
+--------------
+
+If you wish to change the `configure' script or its related files, you'll need
+to first install GNU m4, available from <ftp://ftp.gnu.org/pub/gnu/m4/> and then
+GNU autoconf (<ftp://ftp.gnu.org/pub/gnu/autoconf/>).
+
+Most of the configure-related files are automatically generated. The only files
+you should need to manually edit are acconfig.h and configure.in. Don't, for
+instance, edit config.h.in. Though it is an input file from the point of view
+of the users (and the configure script) it is an output file from the point of
+view of the developers (and the autoconf script).
+
+If you do change acconfig.h or configure.in and want to `cvs commit' them, be
+sure to regenerate the output files and commit them as well. The easiest way to
+regenerate the files is to simply run `make' -- it'll do the necessary calls of
+autoconf and autoheader and will do a `./config.status --recheck', which will
+exercise your new configure script.
+
+When you commit the configure-related files, it's very important to commit them
+in the right order. The timestamps on the files in the CVS archive are based on
+the current time at the moment they were committed -- the timestamps from the
+local files you commit are not copied over. If you commit the files in the
+wrong order, you'll cause unnecessary calls of `autoconf' to occur when people
+try to `make' their copies of the latest CVS source. These people may be
+end-users who don't have any interest in changing the configure-related files
+and don't have autoconf installed. They'll be unable to make without playing
+around with `touch'.
+
+The correct order to commit the configure-related files is:
+
+ % cvs commit acconfig.h config.h.in configure.in configure stamp-h.in
+
+If you haven't changed all of those files, just commit the rest in the stated
+order (e.g. cvs commit acconfig.h config.h.in stamp-h.in).
+
+
+-------------------
+directory structure
+-------------------
+
+Following is a list of nmh's directories along with a brief description of the
+purpose of each one. Meanings are given for the abbreviations, but note that
+these meanings are just informed guesses as to what the MH developers were
+thinking.
+
+./
+ The top-level directory. Contains files like README and INSTALL.
+
+config/
+ Contains utility files for the `configure' process. Ordinarily nothing in
+ here needs to be messed with.
+
+etc/
+ Contains files, file templates, and scripts to generate files that will be
+ installed in the ${prefix}/etc directory. Stuff like replcomps.
+
+h/
+ Most of nmh's header (.h) files are kept not in the individual source
+ directories, but in this central location.
+
+man/
+ Contains all the input files that are processed to generate nmh's manual
+ pages.
+
+mts/
+ "mts" stands for "Message Transfer Service". Source files specific to the
+ different MTSs go in the subdirectories.
+
+mts/mmdf/
+ "mmdf" stands for "Multichannel Memorandum Distribution Facility". It is an
+ alternative to sendmail used primarily on SCO UNIX.
+
+mts/sendmail/
+ When nmh is configured --with-mts=sendmail, the files in this directory are
+ used.
+
+mts/smtp/
+ When nmh is configured to just talk to an SMTP server over TCP/IP, the
+ source in this directory is compiled.
+
+sbr/
+ "sbr" stands for "subroutine(s)". For the most part, each source file in
+ this directory contains a single function with the same name as the source
+ file. These functions are of general use and are called from throughout
+ nmh.
+
+uip/
+ "uip" stands for "User Interface Programs". Most nmh commands have a file
+ in this directory named <command>.c containing the code for that command
+ (e.g. repl.c). In some cases there is also an auxiliary file called
+ <command>sbr.c which contains additional subroutines called from <command>.c
+ (which would contain not much else besides main()).
+
+zotnet/
+ Files in this hierarchy were either written by or moved here by UCI
+ (University of California, Irvine) after they took over MH from the Rand
+ Corporation. "Zot!" is the sound effect made by the anteater in the "B.C."
+ comic strip when its tongue lashes out at ants. The anteater is UCI's
+ official mascot. Not sure whether UCInet was once called ZotNet...
+
+zotnet/bboards/
+ UCI added Bulletin Board functionality to MH with the `bbc' command. This
+ functionality has been removed from nmh but apparently files in this
+ directory are still needed for other purposes.
+
+zotnet/mf/
+ "mf" stands for "Mail Filter". The filtering in this case apparently refers
+ to translation between different address and mailbox formats.
+
+zotnet/mts/
+ MTS code not specific to any single MTS apparently goes here.
+
+zotnet/tws/
+ No idea what "tws" stands for, other than 't' almost certainly standing for
+ "time". Date and time manipulation routines go here.
projects / mmh / commitdiff