From 349d2990c225a3160c826a44271545f23973ba47 Mon Sep 17 00:00:00 2001
From: Manos Pitsidianakis <el13635@mail.ntua.gr>
Date: Wed, 15 Jul 2020 15:19:27 +0300
Subject: [PATCH] docs: add `send_mail` documentation

---
 meli.1                     |  9 ++--
 meli.conf.5                | 99 +++++++++++++++++++++++++++++++++++---
 samples/sample-config.toml |  3 +-
 3 files changed, 100 insertions(+), 11 deletions(-)

diff --git a/meli.1 b/meli.1
index ede7a5ae..475208da 100644
--- a/meli.1
+++ b/meli.1
@@ -222,11 +222,14 @@ Attachments may be handled with the
 commands (see below).
 Finally, pressing
 .Cm s
-will send your message by piping it into a binary of your choosing (see
+will send your message according to your settings
+.Po
+see
 .Xr meli.conf 5 COMPOSING Ns
 , setting
-.Ic mailer_command Ns
-).
+.Ic send_mail
+.Pc Ns
+\&.
 To save your draft without sending it, issue command
 .Cm close
 and select 'save as draft'.
diff --git a/meli.conf.5 b/meli.conf.5
index 54550c1c..e85b4776 100644
--- a/meli.conf.5
+++ b/meli.conf.5
@@ -96,6 +96,7 @@ root_mailbox = "/var/mail/username"
 format = "mbox"
 index_style = "Compact"
 identity="username@hostname.local"
+composing.send_mail = { hostname = "localhost", port = 25, auth = { type = "none" }, security = { type = "none" } }
 
 [pager]
 filter = "COLUMNS=72 /usr/local/bin/pygmentize -l email"
@@ -106,7 +107,8 @@ script = "notify-send"
 
 [composing]
 # required for sending e-mail
-mailer_command = 'msmtp --read-recipients --read-envelope-from'
+send_mail = 'msmtp --read-recipients --read-envelope-from'
+#send_mail = { hostname = "smtp.mail.tld", port = 587, auth = { type = "auto", username = "user", password = { type = "command_eval", value = "gpg2 --no-tty -q -d ~/.passwords/user.gpg" } }, security = { type = "STARTTLS" } }
 editor_command = 'vim +/^$'
 
 [shortcuts]
@@ -174,7 +176,7 @@ Its format is described below in
 .Sx mailboxes Ns
 \&.
 .El
-.Sh notmuch only
+.Ss notmuch only
 .Ic root_mailbox
 points to the directory which contains the
 .Pa .notmuch/
@@ -195,7 +197,7 @@ format = "notmuch"
   "Drafts" = {  query="tag:draft", subscribe = true }
   "Sent" = {  query="from:username@server.tld from:username2@server.tld", subscribe = true }
 .Ed
-.Sh IMAP only
+.Ss IMAP only
 IMAP specific options are:
 .Bl -tag -width 36n
 .It Ic server_hostname Ar String
@@ -219,7 +221,7 @@ example:
 .\" default value
 .Pq Em false
 .El
-.Sh JMAP only
+.Ss JMAP only
 JMAP specific options are:
 .Bl -tag -width 36n
 .It Ic server_hostname Ar String
@@ -236,7 +238,7 @@ example:
 .\" default value
 .Pq Em false
 .El
-.Sh mbox only
+.Ss mbox only
 mbox specific options are:
 .Bl -tag -width 36n
 .It Ic prefer_mbox_type Ar String
@@ -323,8 +325,11 @@ Example:
 .El
 .Sh COMPOSING
 .Bl -tag -width 36n
-.It Ic mailer_command Ar String
-command to pipe new mail to, exit code must be 0 for success.
+.It Ic send_mail Ar String|SmtpServerConf
+command to pipe new mail to (exit code must be 0 for success) or settings for an SMTP server connection.
+See section
+.Sx SMTP Connections
+for its fields.
 .It Ic editor_command Ar String
 command to launch editor.
 Can have arguments.
@@ -789,6 +794,86 @@ to
 .\" default value
 .Pq Em INFO
 .El
+.Sh SMTP Connections
+.Bl -tag -width 36n
+.It Ic hostname Ar String
+server hostname
+.It Ic port Ar Integer
+server port
+.It Ic envelope_from Ar String
+(optional) address to set as sender in SMTP transactions
+.\" default value
+.Pq Em none
+.It Ic auth Ar SmtpAuth
+SMTP server authentication.
+See
+.Sx SmtpAuth
+subsection.
+.It Ic security Ar SmtpSecurity
+(optional) gpg binary name or file location to use
+.\" default value
+.Po see
+.Sx SmtpSecurity
+subsection
+.Pc
+.It Ic extensions Ar SmtpExtensions
+(optional) set support for SMTP extensions if they are advertised by the server
+.\" default value
+.Po see
+.Sx SmtpExtensions
+subsection
+.Pc
+.El
+.Ss SmtpAuth
+.Bl -tag -width 36n
+.It Ic type Ar "none" | "auto"
+.El
+.Pp
+For type "auto":
+.Bl -tag -width 36n
+.It Ic username Ar String
+.It Ic password Ar String|SmtpPassword
+.It Ic require_auth Ar bool
+(optional) require authentication in every case
+.\" default value
+.Pq Em true
+.El
+.Ss SmtpPassword
+.Bl -tag -width 36n
+.It Ic type Ar "raw" | "command_evaluation"
+.It Ic value Ar String
+Either a raw password string, or command to execute.
+.El
+.Ss SmtpSecurity
+Default security type is
+.Em auto Ns
+\&.
+.Bl -tag -width 36n
+.It Ic type Ar "none" | "auto" | "starttls" | "tls"
+.It Ic danger_accept_invalid_certs Ar bool
+Accept invalid SSL/TLS certificates
+.\" default value
+.Pq Em false
+.El
+.Ss SmtpExtensions
+.Bl -tag -width 36n
+.It Ic pipelining Ar bool
+rfc2920
+.\" default value
+.Pq Em true
+.It Ic chunking Ar bool
+rfc3030
+.\" default value
+.Pq Em true
+.It Ic prdr Ar bool
+draft-hall-prdr-00
+.\" default value
+.Pq Em true
+.It Ic dsn_notify Ar String
+RFC3461
+.\" default value
+.Pq Em FAILURE
+.El
 .Sh SEE ALSO
 .Xr meli 1 ,
 .Xr meli-themes 5
diff --git a/samples/sample-config.toml b/samples/sample-config.toml
index 808640f7..e135f7ce 100644
--- a/samples/sample-config.toml
+++ b/samples/sample-config.toml
@@ -105,7 +105,8 @@
 
 #[composing]
 # required for sending e-mail
-#mailer_command = 'msmtp --read-recipients --read-envelope-from'
+#send_mail = 'msmtp --read-recipients --read-envelope-from'
+#send_mail = { hostname = "smtp.mail.tld", port = 587, auth = { type = "auto", username = "user", password = { type = "command_eval", value = "gpg2 --no-tty -q -d ~/.passwords/user.gpg" } }, security = { type = "STARTTLS" } }
 #editor_command = 'vim +/^$' # optional, by default $EDITOR is used.
 #
 #