simplify whatnow.c/main() function
[mmh] / docs / README.developers
index e2834a2..dcec2a7 100644 (file)
 #
 # 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'.
+This file is intended to provide a few tips for anyone doing development
+on mmh. Developers who learn things "the hard way" about the mmh codebase
+(as opposed to local info best encoded in a comment) are encouraged to
+share their wisdom here.
 
-The correct order to commit the configure-related files is:
-
-% cvs commit acconfig.h aclocal.m4 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).
+Absolute beginners should start reading docs/README.start-devel.
 
 
 -------------------
 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. 
+Following is a list of mmh'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.
+    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.
+    Contains utility files for the `configure' process. Ordinarily
+    nothing in here needs to be messed with, but config/config.c is
+    very interesting to have a look at.
+
+docs/
+    Contains more specialized documentation, such as this file and
+    the FAQ.
 
 etc/
-    Contains files, file templates, and scripts to generate files that will be
-    installed in the ${prefix}/etc directory.  Stuff like replcomps.
+    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.
+    Most of mmh's header files are kept in this central location instead
+    of in the individual source directories.
 
 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.
+    Contains all the input files that are processed to generate mmh's
+    manual pages.
 
 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.  
+    "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 mmh.
 
 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.
+    "uip" stands for "User Interface Programs". Most mmh 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.
 
-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.
+----------------------
+version control system
+----------------------
 
+As of December 2010, nmh has switched to using git for revision control
+instead of CVS. Mmh has stick to git. While the topic of git is beyond
+the scope of this FAQ, to get started with git and mmh, you can run the
+following command to checkout the mmh repository:
 
--------------
-releasing nmh
--------------
+    % git clone http://git.marmaro.de/mmh
 
-To make a public release of nmh (we'll use version 1.0.4 and my mhost.com
-account, danh, as examples here):
+That will create a workspace called mmh. To update that workspace
+change to it and run:
 
-1. % echo 1.0.4 > VERSION
+    % git pull
 
-2. Put a comment like "Released nmh-1.0.4." in the ChangeLog.
 
-3. % cvs commit ChangeLog VERSION
-
-4. % cvs tag nmh-1_0_4
-   (cvs treats dots specially, so underscores are substituted here.)
-
-5. % make nmhdist
-
-6. Preferably make an MD5 hash and/or a PGP signature of nmh-1.0.4.tar.gz.
+--------------
+autoconf files
+--------------
 
-7. Preferably test out the tarball, making sure you can uncompress and untar it,
-   and configure, make, install, and use nmh from it.
+If you wish to change the `configure' script or its related files,
+you'll need to first install GNU m4 and GNU autoconf. Mmh is currently
+using a minimum of autoconf 2.61.
 
-8. % scp -p nmh-1.0.4.tar.gz* danh@mhost.com:/home/ftp/pub/nmh
+Most of the configure-related files are automatically generated. The
+only files you should need to manually edit are `acconfig.h' and
+`configure.ac'. 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).
 
-9. Send an announcement to exmh-users@redhat.com, exmh-workers@redhat.com,
-   mh-users@ics.uci.edu, and nmh-announce@mhost.com.  If the release fixes
-   significant security holes, also send an announcement to
-   bugtraq@securityfocus.com.  The exmh lists require you to be subscribed in
-   order to post.  Note that you don't need to post separately to comp.mail.mh,
-   as the mh-users mailing list is apparently bidirectionally gatewayed to it.
+Note that the automatically generated autoconf files (such as
+`config.h.in', `stamp-h.in', and `configure'), are NOT kept in the
+version control system. Thus, when you check out the source tree,
+you need to run the `autogen.sh' script before you can build anything:
 
-   Preferably, the announcement should contain the MD5 hash generated above, and
-   should be PGP-signed.  It should include the FTP URL for the tarball as well
-   as the URL of the website.  It should contain a brief summary of visible
-   changes, as well as the URL of the cvsweb diff page that would show a
-   detailed list of changes.  The changes between 1.0.3 and 1.0.4 would be shown
-   by:
+       % ./autogen.sh
 
-       http://www.mhost.com/cgi-bin/cvsweb/nmh/ChangeLog?r1=1.40&r2=1.71