threads / patch / 54161

patch, 3 partsClean up and improve git-imap-send.txt

Subject: [PATCH 0/3] Clean up and improve git-imap-send.txt

## tl;dr

4 messages between Aug 30, 2020 and Aug 30, 2020. Diffs are folded; open one to read it.

replies: 3people: 1as markdown or json

Philippe Blain via GitGitGadget· Aug 30, 2020, 22:01 UTC · lore

This series cleans up the documentation page for 'git imap-send', removes the sslVerify config from the Gmail example, and uses more appropriate Asciidoc syntax.

It is a rework of [1], incorporating Junio's suggestions from [2].

I split the suggestions in 2 commits to make reviewing the patches easier. The third commit adds a note about localized Gmail folder names, which bit me when I was configuring 'git imap-send' myself.

[1] https://lore.kernel.org/git/51758EE8.7030800@gmail.com/[2] https://lore.kernel.org/git/7vr4hzetki.fsf@alter.siamese.dyndns.org/

Philippe Blain (3):
  git-imap-send.txt: don't duplicate 'Examples' sections
  git-imap-send.txt: do verify SSL certificate for gmail.com
  git-imap-send.txt: add note about localized Gmail folders

 Documentation/git-imap-send.txt | 34 ++++++++++++++++++---------------
 1 file changed, 19 insertions(+), 15 deletions(-)

base-commit: d9cd4331470f4d9d78677f12dc79063dab832f53
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-715%2Fphil-blain%2Fimap-send-ssl-verify-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-715/phil-blain/imap-send-ssl-verify-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/715

-- 
gitgitgadget

Philippe Blain via GitGitGadget· Aug 30, 2020, 22:01 UTC · re: Philippe Blain via GitGitGadget · lore

[PATCH 3/3] git-imap-send.txt: add note about localized Gmail folders

From: Philippe Blain <levraiphilippeblain@gmail.com>

The name of the "Special-Use Mailboxes" in Gmail are localized using the user's localization settings. Add a note to that effect in `git imap-send`'s documentation, to make it easier for users to configure their account.

Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
 Documentation/git-imap-send.txt | 4 ++++
 1 file changed, 4 insertions(+)

Show changes to Documentation/git-imap-send.txt +4 −0

diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index 5e4d4d43b9..63cf498ce9 100644
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt
@@ -110,6 +110,10 @@ Using Gmail's IMAP interface:
 You might need to instead use: `folder = "[Google Mail]/Drafts"` if you get an error
 that the "Folder doesn't exist".
 
+[NOTE]
+If your Gmail account is set to another language than English, the name of the "Drafts"
+folder will be localized.
+
 Once the commits are ready to be sent, run the following command:
 
   $ git format-patch --cover-letter -M --stdout origin/master | git imap-send

-- 
gitgitgadget

Philippe Blain via GitGitGadget· Aug 30, 2020, 22:01 UTC · re: Philippe Blain via GitGitGadget · lore

[PATCH 2/3] git-imap-send.txt: do verify SSL certificate for gmail.com

From: Philippe Blain <levraiphilippeblain@gmail.com>

As a public service, it is unlikely that the Gmail server is configured to throw a certificate that does not verify at the user.

Remove the `sslVerify=false` config from the Gmail example.

Also, comment it in the `example.com` example, and add a note to the user explaining that they might want to uncomment it if they are having trouble connecting. While at it, use an Asciidoc 'Note' section in the Gmail example also.

Based-on-patch-by: Barbu Paul - Gheorghe <barbu.paul.gheorghe@gmail.com>
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
 Documentation/git-imap-send.txt | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

Show changes to Documentation/git-imap-send.txt +9 −2

diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index 0a00a1236b..5e4d4d43b9 100644
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt
@@ -85,10 +85,17 @@ Using direct mode with SSL:
     user = bob
     pass = p4ssw0rd
     port = 123
-    sslverify = false
+    ; sslVerify = false
 .........................
 
 
+[NOTE]
+You may want to use `sslVerify=false`
+while troubleshooting, if you suspect that the reason you are
+having trouble connecting is because the certificate you use at
+the private server `example.com` you are trying to set up (or
+have set up) may not be verified correctly.
+
 Using Gmail's IMAP interface:
 
 ---------
@@ -97,9 +104,9 @@ Using Gmail's IMAP interface:
 	host = imaps://imap.gmail.com
 	user = user@gmail.com
 	port = 993
-	sslverify = false
 ---------
 
+[NOTE]
 You might need to instead use: `folder = "[Google Mail]/Drafts"` if you get an error
 that the "Folder doesn't exist".

-- 
gitgitgadget

Philippe Blain via GitGitGadget· Aug 30, 2020, 22:01 UTC · re: Philippe Blain via GitGitGadget · lore

[PATCH 1/3] git-imap-send.txt: don't duplicate 'Examples' sections

From: Philippe Blain <levraiphilippeblain@gmail.com>

Remove the 'Examples' subsection in the 'Configuration' section and move these examples to the 'Examples' section. Also remove the 'Variables' title since it is now useless.

Also, use appropriate Asciidoc syntax for configuration values, and capitalize 'Gmail' properly.

Suggested-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
 Documentation/git-imap-send.txt | 19 ++++++-------------
 1 file changed, 6 insertions(+), 13 deletions(-)

Show changes to Documentation/git-imap-send.txt +6 −12

diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index 65b53fcc47..0a00a1236b 100644
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt
@@ -51,17 +51,13 @@ OPTIONS
 CONFIGURATION
 -------------
 
-To use the tool, imap.folder and either imap.tunnel or imap.host must be set
+To use the tool, `imap.folder` and either `imap.tunnel` or `imap.host` must be set
 to appropriate values.
 
-Variables
-~~~~~~~~~
-
 include::config/imap.txt[]
 
-Examples
-~~~~~~~~
-
+EXAMPLES
+--------
 Using tunnel mode:
 
 ..........................
@@ -93,10 +89,7 @@ Using direct mode with SSL:
 .........................
 
 
-EXAMPLES
---------
-To submit patches using GMail's IMAP interface, first, edit your ~/.gitconfig
-to specify your account settings:
+Using Gmail's IMAP interface:
 
 ---------
 [imap]
@@ -107,14 +100,14 @@ to specify your account settings:
 	sslverify = false
 ---------
 
-You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error
+You might need to instead use: `folder = "[Google Mail]/Drafts"` if you get an error
 that the "Folder doesn't exist".
 
 Once the commits are ready to be sent, run the following command:
 
   $ git format-patch --cover-letter -M --stdout origin/master | git imap-send
 
-Just make sure to disable line wrapping in the email client (GMail's web
+Just make sure to disable line wrapping in the email client (Gmail's web
 interface will wrap lines no matter what, so you need to use a real
 IMAP client).

-- 
gitgitgadget