On 29 May 2025, at 11:46 PM, Junio C Hamano [off-list ref] wrote:

Aditya Garg [off-list ref] writes:

quoted

The current documentation for git-send-email had an inconsistent use of
"", ``, and '' for quoting. This commit improves the formatting by
using the same style throughout the documentation.

Nice.

quoted

Also, at some places, minor grammatical errors were fixed, and some
non existent links were removed.

Finally, the cpan links of necessary perl modules have been added to
make their installation easier.

Hmmm.

quoted

sendemail.multiEdit::
-    If true (default), a single editor instance will be spawned to edit
+    If `true` (default), a single editor instance will be spawned to edit
   files you have to edit (patches when `--annotate` is used, and the
-    summary when `--compose` is used). If false, files will be edited one
+    summary when `--compose` is used). If `false`, files will be edited one
   after the other, spawning a new editor each time.

Looks good.  "edit files you have to edit" reads somewhat funny, but
the topic of this change is to correct mark-up, so it is the right
thing to do to leave it as-is, at least in this step.

quoted

sendemail.confirm::

@@ -101,7 +101,7 @@ sendemail.signedOffCc (deprecated)::

sendemail.smtpBatchSize::
   Number of messages to be sent per connection, after that a relogin
-    will happen.  If the value is 0 or undefined, send all messages in
+    will happen.  If the value is `0` or undefined, send all messages in

Ditto.  "or undefined" will make readers wonder how they would
specify such a value (i.e. 'undef' in Perl) in their configuration
file, and may need rephrasing, but again not within the topic of
this step.

quoted

-When `--compose` is used, git send-email will use the From, To, Cc, Bcc,
-Subject, Reply-To, and In-Reply-To headers specified in the message. If
-the body of the message (what you type after the headers and a blank
-line) only contains blank (or Git: prefixed) lines, the summary won't be
+When `--compose` is used, `git send-email` will use the 'From', 'To', 'Cc',
+'Bcc', 'Subject', 'Reply-To', and 'In-Reply-To' headers specified in the
+message. If the body of the message (what you type after the headers and a
+blank line) only contains blank (or Git: prefixed) lines, the summary won't be

Shouldn't 'Git:' in "or Git: prefixed" be marked-up somehow as well?

As these mail header names are all literal parts, shouldn't ehy be
marked up like `To`, `Cc`, etc.?

I think its ok to let these remain in '', and deviate from the rules a bit.
If backticks are used, it will be a mess when rendered on the website.

quoted

-    by 'c_rehash', or a single file containing one or more PEM format
-    certificates concatenated together: see verify(1) -CAfile and
-    -CApath for more information on these). Set it to an empty string
+    by `c_rehash`, or a single file containing one or more PEM format
+    certificates concatenated together). Set it to an empty string

What is this change about?  grammatical errors?  non existent links?
cpan links?  It does not look any of these.

Non existing links. Checkout the website.

quoted

@@ -298,18 +297,18 @@ must be used for each option.
   connection and authentication problems.

--batch-size=<num>::
-    Some email servers (e.g. smtp.163.com) limit the number emails to be
+    Some email servers (e.g. 'smtp.163.com') limit the number of emails to be
   sent per session (connection) and this will lead to a failure when
   sending many messages.  With this option, send-email will disconnect after
-    sending $<num> messages and wait for a few seconds (see --relogin-delay)
-    and reconnect, to work around such a limit.  You may want to
-    use some form of credential helper to avoid having to retype
-    your password every time this happens.  Defaults to the
+    sending `$<num>` messages and wait for a few seconds
+    (see `--relogin-delay`) and reconnect, to work around such a limit.
+    You may want to use some form of credential helper to avoid having to
+    retype your password every time this happens.  Defaults to the
   `sendemail.smtpBatchSize` configuration variable.

--relogin-delay=<int>::
-    Waiting $<int> seconds before reconnecting to SMTP server. Used together
-    with --batch-size option.  Defaults to the `sendemail.smtpReloginDelay`
+    Waiting `$<int>` seconds before reconnecting to SMTP server. Used together
+    with `--batch-size` option.  Defaults to the `sendemail.smtpReloginDelay`
   configuration variable.

Together with the previous hunk, "$" before the placeholder looks
incorrect, but it would be preferrable to leave it alone in order to
keep the patch focused on mark-up fixes alone.

As <num> and <int> are both placeholders, not something the users
would literally give, neither `<num>` or `num` is appropriate
mark-up for them, though.  Probably "_<num>_" (without double quotes
around it), if you look at Documentation/CodingGuidelines, I guess.

Ok

quoted

Automating

@@ -318,7 +317,7 @@ Automating
--no-to::
--no-cc::
--no-bcc::
-    Clears any list of "To:", "Cc:", "Bcc:" addresses previously
+    Clears any list of 'To:', 'Cc:', 'Bcc:' addresses previously
   set via config.

The same comment about mail-headers being literal applies here.

Even though the proposed log message talks about "minor grammatical
errors" and "non existent links", I didn't spot any changes about
them.  It is very possible that they are buried in the mark-up
fixes---it would make the patch much better to separate out such
changes and group the changes of the exact same kind into a single
patch.

Minor grammatical errors were that of a missing full stop at the end of a line.

Missing links, look above.

I'll stop here for now; I may come back and continue from here
later.

Thanks.