[PATCH 4/4] Documentation: Improve documentation for git-imap-send(1).

[PATCH 4/4] Documentation: Improve documentation for git-imap-send(1).

[Robert Shearman]

Change the description to be similar to that used for git-send-email(1) to give a better description of what the tool can be used for and sound more user-friendly.

Document the configuration variables used by git-imap-send, split the example into tunnel and direct examples. Rephrase other parts of the git-imap-send documentation to use better grammar and to be clearer.
---
 Documentation/git-imap-send.txt |   65 +++++++++++++++++++++++++++++++--------
 1 files changed, 52 insertions(+), 13 deletions(-)

diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index e4a5873..4429e06 100644
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt
@@ -3,7 +3,7 @@ git-imap-send(1)
 
 NAME
 ----
-git-imap-send - Dump a mailbox from stdin into an imap folder
+git-imap-send - Send a collection of patches from stdin to an IMAP folder
 
 
 SYNOPSIS
@@ -13,9 +13,9 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-This command uploads a mailbox generated with git-format-patch
-into an imap drafts folder.  This allows patches to be sent as
-other email is sent with mail clients that cannot read mailbox
+This command uploads a mailbox generated with git format-patch
+into an IMAP drafts folder.  This allows patches to be sent as
+other email is when using mail clients that cannot read mailbox
 files directly.
 
 Typical usage is something like:
@@ -26,21 +26,60 @@ git format-patch --signoff --stdout --attach origin | git imap-send
 CONFIGURATION
 -------------
 
-'git-imap-send' requires the following values in the repository
-configuration file (shown with examples):
+To use the tool imap.folder and either imap.tunnel or imap.host must be set
+to appropriate values.
+
+Variables
+~~~~~~~~~
+
+imap.folder::
+	The folder to drop the mails into, which is typically the Drafts
+	folder. For example: "INBOX.Drafts". Required to use imap-send.
+
+imap.tunnel::
+	Command used to setup a tunnel to the IMAP server through which
+	commands will be piped instead of using a direct network connection
+	to the server. Required when imap.host is not set to use imap-send.
+
+imap.host::
+	A URL identifying the server. Use a `imap://` prefix for non-secure
+	connections and a `imaps://` prefix for secure connections.
+	Required when imap.tunnel is not set to use imap-send.
+
+imap.user::
+	The username to use when logging in to the server.
+
+imap.password::
+	The password to use when logging in to the server.
+ 
+imap.port::
+	An integer port number to connect to on the server.
+	Defaults to 143 for imap:// and 993 for imaps://.
+
+imap.sslverify::
+	A boolean to enable/disable verification of the server certificate
+	used by the SSL/TLS connection. Default is `true`.
+
+Examples
+~~~~~~~~
+
+Using tunnel mode:
 
 ..........................
 [imap]
-    Folder = "INBOX.Drafts"
+    folder = "INBOX.Drafts"
+    tunnel = "ssh -q -C user@example.com /usr/bin/imapd ./Maildir 2> /dev/null"
+..........................
 
-[imap]
-    Tunnel = "ssh -q user@server.com /usr/bin/imapd ./Maildir 2> /dev/null"
+Using direct mode:
 
+.........................
 [imap]
-    Host = imaps://imap.example.com
-    User = bob
-    Pass = pwd
-    Port = 993
+    folder = "[Gmail]/Drafts"
+    host = imaps://imap.example.com
+    user = bob
+    pass = p4ssw0rd
+    port = 123
     sslverify = false
 ..........................
 
-- 
1.5.6.GIT

Re: [PATCH 4/4] Documentation: Improve documentation for git-imap-send(1).

[Brian Gernhardt]

On Jul 8, 2008, at 6:18 PM, Robert Shearman wrote:

> +Using direct mode:
>
> +.........................
> [imap]
> -    Host = imaps://imap.example.com
> -    User = bob
> -    Pass = pwd
> -    Port = 993
> +    folder = "[Gmail]/Drafts"
> +    host = imaps://imap.example.com
> +    user = bob
> +    pass = p4ssw0rd
> +    port = 123
>     sslverify = false
> ..........................

If you're going to use [Gmail]/Drafts as the example folder, shouldn't  
you just use mail.google.com as your example?  Google themselves use username@gmail.com 
  as an example[1], so that should be safe. So:

..............................
[imap]
     folder = "[Gmail]/Drafts"
     host = imaps://imap.gmail.com
     port = 993
     user = username
     pass = password
..............................

And I also assume that someone has tried this with Gmail and it  
doesn't mangle the Drafts.  I'd also move the sslverify option into  
the tunneling example, as it's more likely to be needed there.

[1] http://mail.google.com/support/bin/answer.py?answer=78799

~~ Brian

Re: [PATCH 4/4] Documentation: Improve documentation for git-imap-send(1).

[Rob Shearman]

2008/7/9 Brian Gernhardt <benji@silverinsanity.com>:
>
> On Jul 8, 2008, at 6:18 PM, Robert Shearman wrote:
>
>> +Using direct mode:
>>
>> +.........................
>> [imap]
>> -    Host = imaps://imap.example.com
>> -    User = bob
>> -    Pass = pwd
>> -    Port = 993
>> +    folder = "[Gmail]/Drafts"
>> +    host = imaps://imap.example.com
>> +    user = bob
>> +    pass = p4ssw0rd
>> +    port = 123
>>    sslverify = false
>> ..........................
>
> If you're going to use [Gmail]/Drafts as the example folder, shouldn't you
> just use mail.google.com as your example?  Google themselves use
> username@gmail.com as an example[1], so that should be safe. So:

I'll fix it not to use "[Gmail]/Drafts" in the example as that is the
exception rather than the norm.

> And I also assume that someone has tried this with Gmail and it doesn't
> mangle the Drafts.

Yes, as specified in my previous email I tested with two different
IMAP servers, one of which was Gmail.

>  I'd also move the sslverify option into the tunneling
> example, as it's more likely to be needed there.

Actually, the sslverify option is ignored in tunnel mode (since you're
likely to be using your own encryption with the tunnel). I'll document
this and other ignored options in a revised patch.

-- 
Rob Shearman

[PATCH 4/4] Documentation: Improve documentation for git-imap-send(1).

[Robert Shearman]

Change the description to be similar to that used for git-send-email(1) to give a better description of what the tool can be used for and sound more user-friendly.

Document the configuration variables used by git-imap-send, split the example into tunnel and direct examples. Rephrase other parts of the git-imap-send documentation to use better grammar and to be clearer.

Signed-off-by: Robert Shearman <robertshearman@gmail.com>
---
 Documentation/git-imap-send.txt |   77 +++++++++++++++++++++++++++++++++------
 1 files changed, 65 insertions(+), 12 deletions(-)

diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index 136c82b..f9e7288 100644
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt
@@ -3,7 +3,7 @@ git-imap-send(1)
 
 NAME
 ----
-git-imap-send - Dump a mailbox from stdin into an imap folder
+git-imap-send - Send a collection of patches from stdin to an IMAP folder
 
 
 SYNOPSIS
@@ -13,9 +13,9 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-This command uploads a mailbox generated with git-format-patch
-into an imap drafts folder.  This allows patches to be sent as
-other email is sent with mail clients that cannot read mailbox
+This command uploads a mailbox generated with git format-patch
+into an IMAP drafts folder.  This allows patches to be sent as
+other email is when using mail clients that cannot read mailbox
 files directly.
 
 Typical usage is something like:
@@ -26,21 +26,74 @@ git format-patch --signoff --stdout --attach origin | git imap-send
 CONFIGURATION
 -------------
 
-'git-imap-send' requires the following values in the repository
-configuration file (shown with examples):
+To use the tool imap.folder and either imap.tunnel or imap.host must be set
+to appropriate values.
+
+Variables
+~~~~~~~~~
+
+imap.folder::
+	The folder to drop the mails into, which is typically the Drafts
+	folder. For example: "INBOX.Drafts", "INBOX/Drafts" or
+	"[Gmail]/Drafts". Required to use imap-send.
+
+imap.tunnel::
+	Command used to setup a tunnel to the IMAP server through which
+	commands will be piped instead of using a direct network connection
+	to the server. Required when imap.host is not set to use imap-send.
+
+imap.host::
+	A URL identifying the server. Use a `imap://` prefix for non-secure
+	connections and a `imaps://` prefix for secure connections.
+	Ignored when imap.tunnel is set, but required to use imap-send
+	otherwise.
+
+imap.user::
+	The username to use when logging in to the server.
+
+imap.password::
+	The password to use when logging in to the server.
+ 
+imap.port::
+	An integer port number to connect to on the server.
+	Defaults to 143 for imap:// hosts and 993 for imaps:// hosts.
+	Ignored when imap.tunnel is set.
+
+imap.sslverify::
+	A boolean to enable/disable verification of the server certificate
+	used by the SSL/TLS connection. Default is `true`. Ignored when
+	imap.tunnel is set.
+
+Examples
+~~~~~~~~
+
+Using tunnel mode:
 
 ..........................
 [imap]
-    Folder = "INBOX.Drafts"
+    folder = "INBOX.Drafts"
+    tunnel = "ssh -q -C user@example.com /usr/bin/imapd ./Maildir 2> /dev/null"
+..........................
 
+Using direct mode:
+
+.........................
 [imap]
-    Tunnel = "ssh -q user@server.com /usr/bin/imapd ./Maildir 2> /dev/null"
+    folder = "INBOX.Drafts"
+    host = imap://imap.example.com
+    user = bob
+    pass = p4ssw0rd
+..........................
+
+Using direct mode with SSL:
 
+.........................
 [imap]
-    Host = imap://imap.example.com
-    User = bob
-    Pass = pwd
-    Port = 143
+    folder = "INBOX.Drafts"
+    host = imaps://imap.example.com
+    user = bob
+    pass = p4ssw0rd
+    port = 123
     sslverify = false
 ..........................
 
-- 
1.5.6.2.224.g26efb.dirty