[darcs-users] darcs patch: More online help for --sendmail-command and SENDMAIL

[Trent W. Buck]

Warning: I am not pulling punches in this review.  Please understand
this is a critique of the patch, not a personal attack on anybody.

Also, the reason that FIXME stayed a FIXME is because it's a hard bit of
documentation -- it needs a lot of terminology, and that terminology is
easily conflated (e.g. "sendmail" could mean the sendmail(8) interface,
or the sendmail project).


More online help for --sendmail-command and SENDMAIL.
-----------------------------------------------------

> -sendmail_cmd = DarcsArgOption [] ["sendmail-command"] SendmailCmd "COMMAND" "specify sendmail command"
> +sendmail_cmd = DarcsArgOption [] ["sendmail-command"] SendmailCmd "COMMAND"
> +                 "specify sendmail command. (See 'SENDMAIL' in 'darcs help environment' for details!)"

I think there are formatting problems with making options descriptions
longer than a few words.  Petr, do you remember offhand what they are?
ISTR you made a bunch of them shorter.

> --- FIXME: mention the following also:
> --- * sendmail(8) is not sendmail-specific;
> --- * nowadays, desktops often have no MTA or an unconfigured MTA --
> ---   which is awful, because it accepts mail but doesn't relay it;
> --- * in this case, can be a sendmail(8)-emulating wrapper on top of an
> ---   MUA that sends mail directly to a smarthost; and
> --- * on a multi-user system without an MTA and on which you haven't
> ---   got root, can be msmtp.

I don't think you've actually covered all the points mentioned in this
FIXME, so it shouldn't be removed.

> - "provide an explicit path to this program; otherwise the standard",
> - "locations /usr/sbin/sendmail and /usr/lib/sendmail will be tried."])
> + "provide an explicit path to this program.  If `--sendmail-command' is",
> + "not present, $SENDMAIL is used; if both are not present, the standard",
> + "locations /usr/sbin/sendmail and /usr/lib/sendmail are used.  (Other",

What was the rationale for the rewording above?

> + "MTAs, e.g. postfix, sometimes provide aliases to work with software",

On Unix, at least, I think *all* MTAs provide sendmail(8).  Is there a
counterexample?  (msmtp is mentioned in the FIXME above because it's the
only example I know of that *can*, but doesn't necessarily, provide
sendmail(8).)

> + "that expects sendmail; if in doubt whether your setup works, just send",
> + "yourself a patch and see what happens.)",

This sounds a bit colloquial; can it be made more formal?

> + "If your machine has no working MTA (mail server), it may loose your",
> + "e-mails without telling you.  In that case, take a look at msmtp and",
> + "the offline wrapper msmtp-runqueue.sh.",
> + "Example: `--sendmail-command=\"/usr/local/bin/msmtp-enqueue.sh -a me %<\"'",
> + "(Without %<, the e-mail is not piped into your MTA's stdin.)"])

AFAICT, you are describing the case where the user is attempting to use
"darcs send" with msmtp, while offline.

This issue is specific to msmtp.  Every other MTA I've encountered will
handle this case by locally queueing the mail, and periodically
attempting to resend it.

By contrast, msmtp will BY DESIGN runs synchronously, and returns a
failure condition to the invoking program instead of queuing:

    $ darcs send --repo R S -a --to nobody at example.net --dont-sign --dont-edit
    Creating patch to "/tmp/with-temp-dir.bGCLM6/S"...
    Successfully sent patch bundle to: nobody at example.net.
    $ # Now, I pull out my network cable to simulate disconnectedness.
    $ darcs send --repo R S -a --to nobody at example.net --dont-sign --dont-edit
    Creating patch to "/tmp/with-temp-dir.bGCLM6/S"...
    sendmail: cannot locate host smtp.gmail.com: Temporary failure in name resolution
    sendmail: could not send mail (account default from /home/twb/.msmtprc)

    darcs failed:  failed to send mail to: nobody at example.net
    Perhaps sendmail is not configured.

The Debian msmtp package includes example script bundles "msmtpqueue"
and "msmtpq", both of which attempt to extend msmtp to handle queueing.
The former is, incidentally, deprecated in favour of the latter.

I fundamentally believe that it is inappropriate to bolt things onto
msmtp to make it support offline operation (queueing) -- if you need
that, set up an MTA designed for that (e.g. postfix, nullmailer).

I also think it's inappropriate for "darcs send --help" to be discussing
msmtp-specific hacks, particularly since it doesn't give enough
information to set up msmtpqueue correctly (compare the proposed
paragraph above to msmtpqueue's README file).

It *is* useful to msmtp users to mention msmtpq and/or msmtpqueue.  I
think this should be done within msmtp (e.g. in its manpage).  I would
also be amendable to mentioning them briefly in the Darcs wiki, where we
already explain how to use msmtp as an MTA.

> hunk ./src/Darcs/Arguments.lhs 1308
> --- |'get_sendmail_cmd' takes a list of flags and returns the sendmail command
> --- to be used by @darcs send at . Looks for a command specified by
> --- @SendmailCmd \"command\"@ in that list of flags, if any.
> --- This flag is present if darcs was invoked with @--sendmail-command=COMMAND@
> --- Alternatively the user can set @$S@@ENDMAIL@ which will be used as a fallback if present.
> +-- |'get_sendmail_cmd' takes a list of flags (command line parameters)
> +-- and returns the sendmail command to be used by @darcs send at .  If
> +-- darcs was invoked with @--sendmail-command=COMMAND@, the flag
> +-- @SendmailCmd \"command\"@ is used.  Otherwise, the shell variable
> +-- @$S@@ENDMAIL@ will be used as a fallback.  If neither is present,
> +-- "" is returned.

This hunk looks fine to me.