add autoconf magic to support old systems that don't support multibyte charsets
[mmh] / INSTALL
diff --git a/INSTALL b/INSTALL
index b1e1d10..37a38e5 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -14,28 +14,36 @@ You should check the MACHINES file to see if there are any specific
 build instructions for your operating system.  To build nmh, you will
 need an ANSI C compiler such as gcc.
 
-1) Run the command
+1) From the top-level source directory, run the command
 
-   sh configure [options]
+   ./configure [options]
 
-   This will check the configuration of your OS, and create
-   the include file config.h, as well as the various Makefiles.
+   This will check the configuration of your OS, and create the 
+   include file config.h, as well as the various Makefiles.
 
-   The configure script accepts various options.  The options of
-   most interest are listed below.  To see the list of all available
-   options, you can run
+   The configure script accepts various options.  The options of 
+   most interest are listed in a section below.  To see the list 
+   of all available options, you can run
 
-   sh configure --help
+   ./configure --help
 
 2) Look through the user configuration section at the beginning
-   of the generated include file `config.h'.  All system-specific
-   definitions should be sensed automatically now, but you may
+   of the generated include file `config.h'. You may
    want to customize some #defines for your environment.
 
 3) make
 
 4) make install
 
+   Note that if you have [n]mh files in your install directories with
+   the same names as the files being installed, the old ones will get
+   overwritten without any warning.  The only directory that isn't
+   true for is the `etc' directory -- in that directory, the previous
+   copy of each <file> will be backed up as <file>.prev if it differs
+   from the newly-installed copy.  Watch for any diff output while
+   make is processing that directory to see if you need to merge
+   changes from *.prev files into the new versions.
+
 5) Edit the file `mts.conf' (installed in the nmh `etc' directory)
    and make any necessary changes for the mail transport interface
    you are using.
@@ -45,62 +53,33 @@ need an ANSI C compiler such as gcc.
    injecting the message to a mail transfer agent (such as sendmail)
    on the local machine via SMTP.
 
-   If you have enabled POP support and you want this to be the
-   default method of accessing new mail, you will need to change
-   the values of the variables "servers", "pophost", "localname",
-   and possibly "mmailid".
-
-   a) "servers" defines the server to which you send outgoing SMTP
-      traffic.
-
-   b) "pophost" defines the server that runs the POP daemon, and to
-      which `inc' and `msgchk' will query for new mail.
-
-   c) "localname" defines the hostname that nmh considers local.
-      If not set, then nmh queries your OS for this value.  You may
-      want to change this if you wish your e-mail to appear as if it
-      originated on the POP server.
-
-   d) "mmailid" allows two different types of email address masquerading
-      when it's set to be non-zero.  The first type is GECOS-based
-      masquerading.  nmh will check if the user's pw_gecos field in the passwd
-      is of the form:
-
-          Full Name <fakeusername>
-
-      If it is, the internal nmh routines that find the username and full
-      name of that user will return "fakeusername" and "Full Name"
-      respectively.  This is useful if you want the messages you send to
-      always appear to come from the name of an MTA alias rather than your
-      actual account name.  For instance, many organizations set up
-      "First.Last" sendmail aliases for all users.  If this is the case,
-      the GECOS field for each user should look like:
-
-          First [Middle] Last <First.Last>
-
-      The other type of masquerading that mmailid turns on is envelope
-      "From:" masquerading based on draft contents.  When a user explicitly
-      specifies a "From:" header in a message, nmh uses it rather than
-      constructing its own.  However, the SMTP envelope "From:" and the
-      "Sender:" header are set to the user's real address.  Turning on
-      mmailid prevents this latter behavior.  This is useful when the user
-      wants to pretend to be sending mail "directly" from a remote POP3
-      account, or when remote mail robots incorrectly use the envelope
-      "From:" in preference to the body "From:" (or refuse to take action
-      when the two don't match).
+   If, instead, all your mail sending and receiving occurs on a 
+   remote POP/SMTP server, you will need to look at the values of the 
+   variables "localname", "pophost", and "servers":
+
+    a) "localname" defines the hostname that nmh considers local.
+       If not set, then nmh queries your OS for this value.  You will
+       want to change this if you wish your e-mail to appear as if it
+       originated on the POP server.
+
+    b) "pophost" defines the server that runs the POP daemon, and to
+       which `inc' and `msgchk' will always query for new mail.
+
+    c) "servers" defines the server to which you send outgoing SMTP
+       traffic.
 
    If you compile with POP support, but don't want to use it exclusively,
    you can use the `-host' and `-user' options to `inc' and `msgchk'
-   rather than hardcoding values in `mts.conf'.
+   rather than hardcoding pophost in `mts.conf'.
 
    Check the `mh-tailor' man page for a list of all the available options
-   for this file.
+   for this file ("masquerade" may be of particular interest).
 
 6) If you have enabled POP support, make sure that `pop3' (or more
    precisely the value of the define POPSERVICE in config.h) is defined
    in the /etc/services file (or its NIS/NIS+ equivalent) on the client
    machine.  It should be something equivalent to "110/tcp".  This might
-   have already been done when the pop daemon was installed.
+   have already been done when the POP daemon was installed.
 
 7) Edit the file `mhn.defaults' (installed in the nmh `etc' directory).
    This file contains the default profile entries for the nmh command
@@ -111,8 +90,8 @@ need an ANSI C compiler such as gcc.
    want to re-run this script later if you install new programs to
    display content.  An example of this is:
 
-   cd support/general
-   ./mhn.defaults.sh /usr/local/bin:/usr/X11/bin:/usr/ucb > mhn.defaults
+    % cd support/general
+    % ./mhn.defaults.sh /usr/local/bin:/usr/X11/bin:/usr/ucb > mhn.defaults
 
    and then move `mhn.defaults' into the nmh `etc' directory.
 
@@ -188,24 +167,29 @@ Options for configure
 --mandir=DIR     (DEFAULT is ${prefix}/man)
      nmh's man pages are installed here.
 
---with-mts=MTS   (DEFAULT is smtp)
-     specify the mail transport system you want to use.  The two
-     acceptable options are "smtp" (which is the default), and
-     "sendmail".
+--enable-debug
+     Enable debugging support.
 
-     If you use "smtp", this will enable a direct SMTP (simple
-     mail transport protocol) interface in nmh.  When sending
-     mail, instead of passing the message to the mail transport
-     agent, `post' will open a socket connection to the mail
-     port on the machine specified in the `mts.conf' file
-     (default is localhost), and speak SMTP directly.
+--enable-masquerade[='draft_from mmailid username_extension']    
+     If this option is not specified, the mts.conf file will contain the line
+     "masquerade: " (with no value), which may be manually edited later.  You
+     may find it convenient to specify a value at configure-time, however, so
+     that each time nmh is reinstalled, the right value will be there.
 
-     If you use "sendmail", then `post' will send messages by
-     passing forking a local copy of sendmail.  Currently it
-     will still speak SMTP with this local copy of sendmail.
+     The above usage shows all three masquerade options being specified, but any
+     subset of the three may be specified.  If you do want to enable all three,
+     you can simply use `configure --enable-masquerade' as a shortcut.
 
-     If you wish to use a transport agent other than sendmail, you will
-     need to use a `sendmail wrapper'.
+     See the mh-tailor(5) man page for full documentation of "masquerade:".
+
+--enable-mhe    (DEFAULT)
+     Add support for the Emacs front-end `mhe'.
+
+--enable-pop
+     Enable client-side support for pop.
+
+--enable-apop
+     Enable client-side support for apop (Authenticated POP).
 
 --with-editor=EDITOR  (DEFAULT is vi)
      specify the full path of the default editor to use.  If this
@@ -215,29 +199,78 @@ Options for configure
      nmh command `prompter'.  If you specify `prompter', then you don't
      need to give the full pathname.
 
---with-pager=PAGER    (DEFAULT is more)
-     specify the default pager (file lister) to use.  If this option
-     is not given, then the configuration process will search for the
-     command `more' and use it as the default.
+--with-hesiod=PREFIX
+     Specify the location of Hesiod.
 
---enable-nmh-mhe    (DEFAULT)
-     Add support for the Emacs front-end `mhe'.
+--with-krb4=PREFIX
+     Specify the location of Kerberos V4 for KPOP support. After
+     running configure, you will need to change the POPSERVICE #define in
+     config.h if you want to use KPOP exclusively (rather than being able
+     to switch between KPOP and normal POP3).  See the comments inside
+     config.h for details.
+
+--with-locking=LOCKTYPE    (DEFAULT is dot)
+     Specify the locking mechanism when attempting to "inc" or
+     "msgchk" a local mail spool. Valid options are "dot",
+     "fcntl", "flock", and "lockf". Of the four, dot-locking
+     requires no special kernel or filesystem support, and simply
+     creates a file called "FILE.lock" to indicate that "FILE" is
+     locked.
+
+     In order to be effective, you should contact the site
+     administrator to find out what locking mechanisms other
+     mail delivery and user programs respect. The most common
+     reason not to use dot-locking is if the mail spool directory
+     is not world- or user-writeable, and thus a lock file cannot
+     be created.
 
---enable-nmh-pop
-    Enable client-side support for pop.
+--with-mts=MTS   (DEFAULT is smtp)
+     Specify the default mail transport system you want to use.  The two
+     acceptable options are "smtp" (which is the default), and
+     "sendmail".  This value will be put into the mts.conf file.  You
+     may find it convenient to specify a value at configure-time,
+     however, so that each time nmh is reinstalled, the right value will
+     be there.
+
+     If you use "smtp", this will enable a direct SMTP (simple mail
+     transport protocol) interface in nmh.  When sending mail, instead
+     of passing the message to the mail transport agent, `post' will
+     open a socket connection to the mail port on the machine specified
+     in the `mts.conf' file (default is localhost), and speak SMTP
+     directly.
+
+     If you use "sendmail", then `post' will send messages by forking a
+     local copy of sendmail.  Currently it will still speak SMTP with
+     this local copy of sendmail.
 
---with-krb4=PREFIX
-    Specify the location of Kerberos V4 for KPOP support.  You will
-    also need to specify the option `--enable-nmh-pop'.  After running
-    configure, you will probably need to change the POPSERVICE define
-    in config.h.  See the comments inside config.h for details.
+     If you wish to use a transport agent other than sendmail, you will
+     need to use a `sendmail wrapper'.
 
---with-hesiod=PREFIX
-    Specify the location of Hesiod.
+--with-ndbm=LIB    (DEFAULT is to autodetect)
+--with-ndbmheader=HEADER     (DEFAULT is to autodetect)
+     Specify the header file (eg ndbm.h) and library (eg ndbm) to use
+     to compile against the ndbm database library. By default, configure
+     will try various possibilities until it finds one that works; this
+     option only needs to be specified if the autodetection fails or
+     makes the wrong choice.
+
+     If either of these options is given then the other must also be
+     specified.
+
+--with-pager=PAGER    (DEFAULT is more)
+     Specify the default pager (file lister) to use.  If this option
+     is not given, then the configuration process will search for the
+     command `more' and use it as the default.
+
+--with-smtpservers='SMTPSERVER1[ SMTPSERVER2...]'    (DEFAULT is localhost)
+     If this option is not specified, the mts.conf file will contain
+     the line "servers: localhost", which may be manually edited later.
+     You may find it convenient to specify a value at configure-time,
+     however, so that each time nmh is reinstalled, the right value will be
+     there.
 
---enable-nmh-debug
-    Enable debugging support.
+     See the mh-tailor(5) man page for full documentation of "servers:".
 
 --
 The nmh team
-nmh-workers@mhost.com
+nmh-workers@nongnu.org