In the hullaballoo with moving stuff back and forth out of the docs/ directory,

and trying to figure out the right way to preserve the old version history, this
file's version history prior to the first move into docs/ got wiped.  I
introduced this file into the project after 1.0.3 was released, and was the only
one to modify it until after the 1.0.4 release.  The post-1.0.4 changes have
survived in docs/README.developers, so I just need to check in the 1.0.4 version
and tag it as such, then remove it again, to make a `cvs checkout' of nmh 1.0.4
work again.

diff --git a/README.developers b/README.developers
new file mode 100644 (file)
index 0000000..78fad7a
--- /dev/null
+++ b/README.developers
@@ -0,0 +1,130 @@
+#
+# 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.