Re: [PATCH v2] Documentation: avoid dangling modifier for imap-send

"brian m. carlson" [off-list ref] writes:

To be honest, I find both versions are equally confusing.

How about dropping the three words "to use imap-send"?

On Mon, Aug 04, 2014 at 11:29:33AM -0700, Junio C Hamano wrote:

"brian m. carlson" [off-list ref] writes:

quoted

Avoid a nonsensical misreading by moving the modifier closer to the
word it modifies.

Signed-off-by: brian m. carlson <redacted>
---
 Documentation/git-imap-send.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index 875d283..23231e1 100644
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt

@@ -43,7 +43,7 @@ imap.folder::
 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.
+	to the server. Required to use imap-send when imap.host is not set.

To be honest, I find both versions are equally confusing.

How about dropping the three words "to use imap-send"?

Fine by me.

-- 
brian m. carlson / brian with sandals: Houston, Texas, US
+1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187

Avoid a nonsensical misreading by removing needless text.

Signed-off-by: brian m. carlson <redacted>
---
 Documentation/git-imap-send.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index 875d283..e50b1c4 100644
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt

@@ -43,7 +43,7 @@ imap.folder::
 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.
+	to the server. Required when imap.host is not set.
 
 imap.host::
 	A URL identifying the server. Use a `imap://` prefix for non-secure

-- 
2.0.1

brian m. carlson wrote:

Should the neighboring instances of '[Rr]equired to use imap-send
be changed to plain "Required", too?  (I suspect yes.)

Thanks,
Jonathan

Jonathan Nieder wrote:

Should the neighboring instances of '[Rr]equired to use imap-send
be changed to plain "Required", too?  (I suspect yes.)

Here's what that would look like.

-- >8 --
From: brian m. carlson <redacted>
Subject: imap-send doc: omit confusing "to use imap-send" modifier

It wouldn't make sense for these configuration variables to be
required for Git in general to function.  'Required' in this context
means required for git imap-send to work.

Noticed while trying to figure out what the sentence describing
imap.tunnel meant.

[jn: expanded to also simplify explanation of imap.folder and
 imap.host in the same way]

Signed-off-by: brian m. carlson <redacted>
Signed-off-by: Jonathan Nieder <redacted>
---
 Documentation/git-imap-send.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index 875d283..d3b465d 100644
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt

@@ -38,17 +38,17 @@ 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.
+	"[Gmail]/Drafts". Required.
 
 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.
+	to the server. Required when imap.host is not set.
 
 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
+	Ignored when imap.tunnel is set, but required.
 	otherwise.
 
 imap.user::

-- 

On Mon, Aug 04, 2014 at 07:51:08PM -0700, Jonathan Nieder wrote:

This has an extra period at the end of the line.

 	otherwise.
 
 imap.user::
-- 

-- 
brian m. carlson / brian with sandals: Houston, Texas, US
+1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187

It wouldn't make sense for these configuration variables to be
required for Git in general to function.  'Required' in this context
means required for git imap-send to work.

Noticed while trying to figure out what the sentence describing
imap.tunnel meant.

[jn: expanded to also simplify explanation of imap.folder and
 imap.host in the same way]

Signed-off-by: brian m. carlson <redacted>
Signed-off-by: Jonathan Nieder <redacted>
---
 Documentation/git-imap-send.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index 875d283..d3b465d 100644
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt

@@ -38,17 +38,17 @@ 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.
+	"[Gmail]/Drafts". Required.
 
 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.
+	to the server. Required when imap.host is not set.
 
 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
+	Ignored when imap.tunnel is set, but required.
 	otherwise.
 
 imap.user::

-- 
2.0.1

brian m. carlson wrote:

This has an extra period at the end of the line.

Good catch.

-- >8 --
Subject: fixup! imap-send doc: omit confusing "to use imap-send" modifier
---
Thanks,
Jonathan

 Documentation/git-imap-send.txt | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index d3b465d..eabcaf0 100644
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt

@@ -48,8 +48,7 @@ imap.tunnel::
 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.
-	otherwise.
+	Ignored when imap.tunnel is set, but required otherwise.
 
 imap.user::
 	The username to use when logging in to the server.

--