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

Robert Shearman· Jul 8, 2008, 22:18 UTC · lore

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(-)

Show changes to Documentation/git-imap-send.txt +52 −13

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

Brian Gernhardt· Jul 9, 2008, 01:35 UTC · re: Robert Shearman · lore

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

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

Show 15 quoted lines

> +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

Rob Shearman· Jul 9, 2008, 12:05 UTC · re: Brian Gernhardt · lore

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

2008/7/9 Brian Gernhardt <benji@silverinsanity.com>:

Show 22 quoted lines

>
> 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 partsDocumentation: Improve documentation for git-imap-send(1).