Documented movemail.

1 files changed, 157 insertions, 1 deletions

diff --git a/doc/texinfo/programs.texi b/doc/texinfo/programs.texi
index 309f47caa..bd99623cf 100644
--- a/doc/texinfo/programs.texi
+++ b/doc/texinfo/programs.texi
@@ -2174,7 +2174,163 @@ Output program version and exit.
 @section @command{movemail} --- Moves Mail from the User Maildrop to the Local File
 @pindex movemail
 
-[FIXME]
+The purpose of @command{movemail}, as its name implies, is to move mail
+from one location to another. For example, the following invocation:
+
+@smallexample
+movemail /var/mail/smith INBOX
+@end smallexample
+
+@noindent
+moves messages from file @file{/var/mail/smith} to file @file{INBOX}.
+
+You will probably never have to run this program manually. It is
+intended as a replacement for @command{movemail} from GNU Emacs. The
+@command{movemail} program is run by Emacs @code{Rmail}
+module. @xref{Rmail,,,emacs,Reading Mail with Rmail}, for detailed
+description of @code{Rmail} interface.
+
+Mailutils version of @command{movemail} is completely
+backward-compatible with its Emacs predecessor, so it should run
+flawlessly with older versions of Emacs. Emacs version 21.4, which is
+being developed at the time of this writing, will contain improved
+@code{Rmail} interface for work with mailutils @command{movemail}.
+
+@menu
+* Movemail Options::     Description of the Available Options
+* Summary::              Short Movemail Invocation Summary
+@end menu
+
+@node Movemail Options
+@subsection Movemail Options
+
+This subsection discusses @command{movemail} options from the point of
+view of an Emacs @code{Rmail} user.
+
+To set various options to @command{movemail} from @code{Rmail}, use
+@code{rmail-movemail-flags} variable, or @samp{Rmail Movemail Flags}
+section from the menu. 
+
+Some POP servers return messages in reversed order. To fix the
+order, use @option{-p} option or its synonym @option{--reverse}.
+
+If the remote server supports @acronym{TLS} encryption, use
+@option{--tls} to instruct @command{movemail} to initiate encrypted
+connection.
+
+Quite a few options control how @command{movemail} handles mail
+locking (a way of preventing simultaneous access to the source
+mailbox). By default, before accessing mailbox @var{file},
+@command{movemail} will first see if the file named
+@file{@var{file}.lock} (so called @dfn{lock file}) exists. If so, it
+will assume that the mailbox is being used by another program and will
+sleep one second. If @file{@var{file}.lock} file disappears after this
+wait period, the program will proceed. Otherwise, it will repeat this
+action ten times. If after ten wait periods the lock file does not
+disappear, @command{movemail} gives up and exits.
+
+If the lock file does not exist, @command{movemail} will create it,
+thereby indicating to other programs that the mailbox is being used,
+and will proceed to copying messages to the destination file. When
+finished, @command{movemail} closes the mailbox and removes the lock
+file.
+
+Several options control this behavior. To change the default sleep period
+use @option{--lock-retry-timeout}. Its argument is the timeout value
+in seconds.
+
+To change number of retries, use @option{--lock-retry-count}. For
+example, setting @code{rmail-movemail-flags} to
+
+@smallexample
+--lock-retry-timeout=2 --lock-retry-count=5
+@end smallexample
+
+@noindent
+instructs @command{movemail} to make five attempts to acquire the lock
+file, with two-second intervals between the attempts.
+
+You may also force @command{movemail} to remove the lock file if it is
+older than a given amount of time (a so called @dfn{stale lock
+file}). To do so, use the following option:
+
+@smallexample
+--lock-expire-timeout=@var{seconds}
+@end smallexample
+
+The @option{--lock-expire-timeout} sets the number of seconds after
+which a lock file is considered stale.
+
+There are special programs that can be used to lock and unlock
+mailboxes. A common example of such programs is @command{dotlock}. If
+you wish to use such @dfn{external locking program} instead of the
+default mailutils locking mechanism, use option
+@option{--external-locker}. Argument to this option specifies the full
+name of the external program to use.
+
+@node Summary
+@subsection Summary of Movemail Usage
+
+@smallexample
+movemail [@var{option}...] @var{inbox} @var{destfile} [@var{remote-password}]
+@end smallexample
+
+The first argument, @var{inbox}, is the @acronym{url} (@pxref{URL}) of
+the source mailbox. The second argument, @var{destfile}, traditionally
+means destination file, i.e. the UNIX mailbox to copy messages
+to. However, mailutils @command{movemail} extends the meaning of this
+parameter. You may actually specify any valid @acronym{url} as
+@var{destfile} parameter.@footnote{Rmail does not use this
+feature}. Finally, optional third argument is a traditional way of
+specifying user passwords for remote (@acronym{POP} or @acronym{IMAP})
+mailboxes.
+
+Following is the summary of available command line options:
+
+@table @option
+@item --emacs
+Output information used by Emacs rmail interface
+
+@item -p
+@itemx --preserve
+@itemx --keep-messages
+Preserve the source mailbox
+
+@item -r
+@itemx --reverse
+Reverse the sorting order
+
+@item --license
+Print GPL license and exit
+
+@item --external-locker=@var{program}
+Use given @var{program} as the external locker program.
+
+@item --lock-expire-timeout=@var{seconds}
+Set number of seconds after which the lock expires
+
+@item --lock-flags=@var{flags}
+Set locker flags. @var{flags} is composed of the following letters:
+@samp{E} -- use external locker program @command{dotlock},
+@samp{R} -- retry 10 times if acquiring of the lock failed (see also
+@option{--lock-retry-count} below), @samp{T} -- remove stale locks
+after 10 minutes (see also @option{--lock-expire-timeout},
+and @samp{P} -- write process @acronym{PID} to the lock file.
+
+@item --lock-retry-count=@var{number}
+Set the maximum number of times to retry acquiring the lockfile
+
+@item --lock-retry-timeout=@var{seconds}
+Set timeout for acquiring the lockfile
+
+@item -m @var{url}
+@itemx --mail-spool @var{URL}
+Use specified URL as a mailspool directory
+
+@item --tls[=@var{bool}]
+Enable (default) or disable TLS support
+
+@end table
 
 @page
 @node readmsg