Skip to contentSkip to conversation

A new batch of synopsis conversion

PATCH Superseded Jean-Noël Avila via GitGitGadget 3 participants 16 messages Jul 19 – Jul 29 Documentation

lore
Share & tools
lore
#0 lore raw

cover A new batch of synopsis conversion

The conversion to synopsis continues. Now the commands are less common, so I may propose larger PRs if it's ok.

Jean-Noël Avila (4):
doc: convert git-imap-send synopsis and options to new style
doc: convert git-format-patch synopsis and options to new style
doc: convert git-send-email synopsis and options to new style
doc: convert git-request-pull synopsis and options to new style

 Documentation/config/imap.adoc      |   2 +-
 Documentation/config/sendemail.adoc |  92 +++++-----
 Documentation/diff-options.adoc     |   8 +-
 Documentation/git-format-patch.adoc | 264 ++++++++++++++--------------
 Documentation/git-imap-send.adoc    |   7 +-
 Documentation/git-request-pull.adoc |  38 ++--
 Documentation/git-send-email.adoc   | 162 ++++++++---------
 7 files changed, 292 insertions(+), 281 deletions(-)

base-commit: 08621c32d5536babd139ab1a9086349b3672edd6
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2185%2Fjnavila%2Fconvert_synopsis_202606-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2185/jnavila/convert_synopsis_202606-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/2185

Signature · 1 line
gitgitgadget
#1 lore raw

PATCH 1/4 doc: convert git-imap-send synopsis and options to new style

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>

Convert git-imap-send from [verse]/single-quote style to the modern synopsis-block style:

- Replace [verse] with [synopsis] in SYNOPSIS block
- Backtick-quote all OPTIONS terms
- Backtick-quote all config keys in config/imap.adoc
- Backtick-quote bare config key references in prose

---
 Documentation/config/imap.adoc   | 2 +-
 Documentation/git-imap-send.adoc | 7 +++++--
 2 files changed, 6 insertions(+), 3 deletions(-)
Documentation/config/imap.adoc +1 -1
index cb8f5e2700..6b97776bc3 100644
@@ -41,7 +41,7 @@
 `imap.authMethod`::
 	Specify the authentication method for authenticating with the IMAP server.
 	If Git was built with the NO_CURL option, or if your curl version is older
-	than 7.34.0, or if you're running git-imap-send with the `--no-curl`
+	than 7.34.0, or if you're running `git-imap-send` with the `--no-curl`
 	option, the only supported methods are `PLAIN`, `CRAM-MD5`, `OAUTHBEARER`
 	and `XOAUTH2`. If this is not set then `git imap-send` uses the basic IMAP
 	plaintext `LOGIN` command.
Documentation/git-imap-send.adoc +5 -2
index 538b91afc0..dd1e0a3718 100644
@@ -192,7 +192,10 @@ supports only `XOAUTH2` as the mechanism.
 
 Once the commits are ready to be sent, run the following command:
 
-  $ git format-patch --cover-letter -M --stdout origin/master | git imap-send
+
+---------
+$ 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
 interface will wrap lines no matter what, so you need to use a real
@@ -217,7 +220,7 @@ users may wish to visit this web page for more information:
 
 SEE ALSO
 --------
-linkgit:git-format-patch[1], linkgit:git-send-email[1], mbox(5)
+linkgit:git-format-patch[1], linkgit:git-send-email[1], `mbox`(5)
 
 GIT
 ---
Signature · 1 line
gitgitgadget
#2 lore raw

PATCH 2/4 doc: convert git-format-patch synopsis and options to new style

In reply to Jean-Noël Avila via GitGitGadget

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>

Replace [verse] with [synopsis] in the SYNOPSIS block and remove single-quote formatting from the command name.

Backtick-quote all option terms in the OPTIONS section, convert standalone placeholders to _<placeholder>_ form, and convert single-quoted commands and tools in prose to backtick form.

Also update the included files:
- diff-options.adoc: backtick-quote the git-format-patch-specific option terms (-p, --no-stat, --max-depth=<depth>)
- format-patch-caveats.adoc: convert patch(1) to patch(1)

---
 Documentation/diff-options.adoc     |   8 +-
 Documentation/git-format-patch.adoc | 264 ++++++++++++++--------------
 2 files changed, 136 insertions(+), 136 deletions(-)
Documentation/diff-options.adoc +4 -4
index c8242e2462..e605d28678 100644
@@ -13,8 +13,8 @@ endif::git-diff[]
 endif::git-format-patch[]
 
 ifdef::git-format-patch[]
--p::
---no-stat::
+`-p`::
+`--no-stat`::
 	Generate plain patches without any diffstats.
 endif::git-format-patch[]
 
@@ -893,8 +893,8 @@ endif::git-format-patch[]
 	reverted with `--ita-visible-in-index`. Both options are
 	experimental and could be removed in future.
 
---max-depth=<depth>::
-	For each pathspec given on command line, descend at most `<depth>`
+`--max-depth=<depth>`::
+	For each pathspec given on command line, descend at most _<depth>_
 	levels of directories. A value of `-1` means no limit.
 	Cannot be combined with wildcards in the pathspec.
 	Given a tree containing `foo/bar/baz`, the following list shows the
Documentation/git-format-patch.adoc +132 -132

596 lines not on this page · raw message

Signature · 1 line
gitgitgadget
#5 lore raw

PATCH 3/4 doc: convert git-send-email synopsis and options to new style

In reply to Jean-Noël Avila via GitGitGadget

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>

Replace [verse] with [synopsis] in the SYNOPSIS block and remove single-quote formatting from the command name.

Backtick-quote all option terms in the OPTIONS section, convert the standalone placeholder _<encoding>_ in prose, fix single-quoted server names to backtick form, and convert mbox(5) to mbox(5).

Also update config/sendemail.adoc: backtick-quote all configuration key terms and fix a bare sendemail.aliasesFile reference in prose.

---
 Documentation/config/sendemail.adoc |  92 ++++++++--------
 Documentation/git-send-email.adoc   | 162 ++++++++++++++--------------
 2 files changed, 127 insertions(+), 127 deletions(-)
Documentation/config/sendemail.adoc +46 -46
index 1d700559b4..5499f91036 100644
@@ -1,25 +1,25 @@
-sendemail.identity::
+`sendemail.identity`::
 	A configuration identity. When given, causes values in the
 	`sendemail.<identity>` subsection to take precedence over
 	values in the `sendemail` section. The default identity is
 	the value of `sendemail.identity`.
 
-sendemail.smtpEncryption::
+`sendemail.smtpEncryption`::
 	See linkgit:git-send-email[1] for description.  Note that this
 	setting is not subject to the `identity` mechanism.
 
-sendemail.smtpSSLCertPath::
+`sendemail.smtpSSLCertPath`::
 	Path to ca-certificates (either a directory or a single file).
 	Set it to an empty string to disable certificate verification.
 
-sendemail.smtpSSLClientCert::
+`sendemail.smtpSSLClientCert`::
 	Path to the client certificate file to present if requested by the
 	server. This is required when the server is set up to verify client
 	certificates. If the corresponding private key is not included in the
 	file, it must be supplied using `sendemail.smtpSSLClientKey` or the
 	`--smtp-ssl-client-key` option.
 
-sendemail.smtpSSLClientKey::
+`sendemail.smtpSSLClientKey`::
 	Path to the client private key file that corresponds to the client
 	certificate. To avoid misconfiguration, this configuration must be used
 	in conjunction with `sendemail.smtpSSLClientCert` or the
@@ -28,45 +28,45 @@ sendemail.smtpSSLClientKey::
 	the certificate. Visit https://metacpan.org/pod/IO::Socket::SSL for more
 	details.
 
-sendemail.<identity>.*::
-	Identity-specific versions of the `sendemail.*` parameters
+`sendemail.<identity>.<config>`::
+	Identity-specific versions of the `sendemail.<config>` parameters
 	found below, taking precedence over those when this
 	identity is selected, through either the command-line or
 	`sendemail.identity`.
 
-sendemail.multiEdit::
+`sendemail.multiEdit`::
 	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
 	after the other, spawning a new editor each time.
 
-sendemail.confirm::
+`sendemail.confirm`::
 	Sets the default for whether to confirm before sending. Must be
 	one of `always`, `never`, `cc`, `compose`, or `auto`. See `--confirm`
 	in the linkgit:git-send-email[1] documentation for the meaning of these
 	values.
 
-sendemail.mailmap::
+`sendemail.mailmap`::
 	If `true`, makes linkgit:git-send-email[1] assume `--mailmap`,
 	otherwise assume `--no-mailmap`. `False` by default.
 
-sendemail.mailmap.file::
+`sendemail.mailmap.file`::
 	The location of a linkgit:git-send-email[1] specific augmenting
 	mailmap file. The default mailmap and `mailmap.file` are loaded
 	first. Thus, entries in this file take precedence over entries in
 	the default mailmap locations. See linkgit:gitmailmap[5].
 
-sendemail.mailmap.blob::
+`sendemail.mailmap.blob`::
 	Like `sendemail.mailmap.file`, but consider the value as a reference
 	to a blob in the repository. Entries in `sendemail.mailmap.file`
 	take precedence over entries here. See linkgit:gitmailmap[5].
 
-sendemail.aliasesFile::
+`sendemail.aliasesFile`::
 	To avoid typing long email addresses, point this to one or more
 	email aliases files.  You must also supply `sendemail.aliasFileType`.
 
-sendemail.aliasFileType::
-	Format of the file(s) specified in sendemail.aliasesFile. Must be
+`sendemail.aliasFileType`::
+	Format of the file(s) specified in `sendemail.aliasesFile`. Must be
 	one of `mutt`, `mailrc`, `pine`, `elm`, `gnus`, or `sendmail`.
 +
 What an alias file in each format looks like can be found in
@@ -75,7 +75,7 @@ differences and limitations from the standard formats are
 described below:
 +
 --
-sendmail;;
+`sendmail`;;
 *	Quoted aliases and quoted addresses are not supported: lines that
 	contain a `"` symbol are ignored.
 *	Redirection to a file (`/path/name`) or pipe (`|command`) is not
@@ -85,54 +85,54 @@ sendmail;;
 	explicitly unsupported constructs, and any other lines that are not
 	recognized by the parser.
 --
-sendemail.annotate::
-sendemail.bcc::
-sendemail.cc::
-sendemail.ccCmd::
-sendemail.chainReplyTo::
-sendemail.envelopeSender::
-sendemail.from::
-sendemail.headerCmd::
-sendemail.signedOffByCc::
-sendemail.smtpPass::
-sendemail.suppressCc::
-sendemail.suppressFrom::
-sendemail.to::
-sendemail.toCmd::
-sendemail.smtpDomain::
-sendemail.smtpServer::
-sendemail.smtpServerPort::
-sendemail.smtpServerOption::
-sendemail.smtpUser::
-sendemail.imapSentFolder::
-sendemail.useImapOnly::
-sendemail.thread::
-sendemail.transferEncoding::
-sendemail.validate::
-sendemail.xmailer::
+`sendemail.annotate`::
+`sendemail.bcc`::
+`sendemail.cc`::
+`sendemail.ccCmd`::
+`sendemail.chainReplyTo`::
+`sendemail.envelopeSender`::
+`sendemail.from`::
+`sendemail.headerCmd`::
+`sendemail.signedOffByCc`::
+`sendemail.smtpPass`::
+`sendemail.suppressCc`::
+`sendemail.suppressFrom`::
+`sendemail.to`::
+`sendemail.toCmd`::
+`sendemail.smtpDomain`::
+`sendemail.smtpServer`::
+`sendemail.smtpServerPort`::
+`sendemail.smtpServerOption`::
+`sendemail.smtpUser`::
+`sendemail.imapSentFolder`::
+`sendemail.useImapOnly`::
+`sendemail.thread`::
+`sendemail.transferEncoding`::
+`sendemail.validate`::
+`sendemail.xmailer`::
 	These configuration variables all provide a default for
 	linkgit:git-send-email[1] command-line options. See its
 	documentation for details.
 
-sendemail.outlookidfix::
+`sendemail.outlookidfix`::
 	If `true`, makes linkgit:git-send-email[1] assume `--outlook-id-fix`,
 	and if `false` assume `--no-outlook-id-fix`. If not specified, it will
 	behave the same way as if `--outlook-id-fix` is not specified.
 
-sendemail.signedOffCc (deprecated)::
+`sendemail.signedOffCc` (deprecated)::
 	Deprecated alias for `sendemail.signedOffByCc`.
 
-sendemail.smtpBatchSize::
+`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
 	one connection.
 	See also the `--batch-size` option of linkgit:git-send-email[1].
 
-sendemail.smtpReloginDelay::
+`sendemail.smtpReloginDelay`::
 	Seconds to wait before reconnecting to the smtp server.
 	See also the `--relogin-delay` option of linkgit:git-send-email[1].
 
-sendemail.forbidSendmailVariables::
+`sendemail.forbidSendmailVariables`::
 	To avoid common misconfiguration mistakes, linkgit:git-send-email[1]
 	will abort with a warning if any configuration options for `sendmail`
 	exist. Set this variable to bypass the check.
Documentation/git-send-email.adoc +81 -81

473 lines not on this page · raw message

Signature · 1 line
gitgitgadget
#6 lore raw

PATCH 4/4 doc: convert git-request-pull synopsis and options to new style

In reply to Jean-Noël Avila via GitGitGadget

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>

* Replace [verse] with [synopsis] in the SYNOPSIS block
* remove single-quote formatting from the command name
* backtick-quote the flag
* use _<placeholder>_ form for positional parameter terms

---
 Documentation/git-request-pull.adoc | 38 +++++++++++++++++------------
 1 file changed, 23 insertions(+), 15 deletions(-)
Documentation/git-request-pull.adoc +23 -15
index 15dcbb6d91..8b6642b312 100644
@@ -7,8 +7,8 @@ git-request-pull - Generates a summary of pending changes
 
 SYNOPSIS
 --------
-[verse]
-'git request-pull' [-p] <start> <URL> [<end>]
+[synopsis]
+git request-pull [-p] <start> <URL> [<end>]
 
 DESCRIPTION
 -----------
@@ -19,28 +19,28 @@ begins with the branch description, summarizes
 the changes, and indicates from where they can be pulled.
 
 The upstream project is expected to have the commit named by
-`<start>` and the output asks it to integrate the changes you made
-since that commit, up to the commit named by `<end>`, by visiting
-the repository named by `<URL>`.
+_<start>_ and the output asks it to integrate the changes you made
+since that commit, up to the commit named by _<end>_, by visiting
+the repository named by _<URL>_.
 
 
 OPTIONS
 -------
--p::
+`-p`::
 	Include patch text in the output.
 
-<start>::
+_<start>_::
 	Commit to start at.  This names a commit that is already in
 	the upstream history.
 
-<URL>::
+_<URL>_::
 	The repository URL to be pulled from.
 
-<end>::
-	Commit to end at (defaults to HEAD).  This names the commit
+_<end>_::
+	Commit to end at (defaults to `HEAD`).  This names the commit
 	at the tip of the history you are asking to be pulled.
 +
-When the repository named by `<URL>` has the commit at a tip of a
+When the repository named by _<URL>_ has the commit at a tip of a
 ref that is different from the ref you have locally, you can use the
 `<local>:<remote>` syntax, to have its local name, a colon `:`, and
 its remote name.
@@ -54,11 +54,15 @@ the `v1.0` release, and want it to be integrated into the project.
 First you push that change to your public repository for others to
 see:
 
-	git push https://git.ko.xz/project master
+-----
+git push https://git.ko.xz/project master
+-----
 
 Then, you run this command:
 
-	git request-pull v1.0 https://git.ko.xz/project master
+------
+git request-pull v1.0 https://git.ko.xz/project master
+------
 
 which will produce a request to the upstream, summarizing the
 changes between the `v1.0` release and your `master`, to pull it
@@ -67,11 +71,15 @@ from your public repository.
 If you pushed your change to a branch whose name is different from
 the one you have locally, e.g.
 
-	git push https://git.ko.xz/project master:for-linus
+-----
+git push https://git.ko.xz/project master:for-linus
+-----
 
 then you can ask that to be pulled with
 
-	git request-pull v1.0 https://git.ko.xz/project master:for-linus
+-----
+git request-pull v1.0 https://git.ko.xz/project master:for-linus
+-----
 
 
 GIT
Signature · 1 line
gitgitgadget
#3 lore raw

Re: [PATCH 2/4] doc: convert git-format-patch synopsis and options to new style

In reply to Jean-Noël Avila via GitGitGadget
Quoted 3 lines · Jean-Noël Avila via GitGitGadget

Backtick-quote all option terms in the OPTIONS section, convert standalone placeholders to _<placeholder>_ form, and convert single-quoted commands and tools in prose to backtick form.

OK.

Documentation/git-format-patch.adoc BASE TREE INFORMATION · line 715

Quoted 9 lines
Documentation/git-format-patch.adoc +4 -0
@@ -708,15 +708,15 @@ BASE TREE INFORMATION
 
 The base tree information block is used for maintainers or third party
 testers to know the exact state the patch series applies to. It consists
+of the "base commit", which is a well-known commit that is part of the
 stable part of the project history everybody else works off of, and zero
+or more "prerequisite patches", which are well-known patches in flight
+that is not yet part of the "base commit" that need to be applied on top
+of "base commit" in topological order before the patches can be applied.

GIven that the last part of this hunk below uses backtick-quoting for prerequisite patch and patch id, shouldn't the references to base commit, and prerequisite patch(es) in the above also be backtick quoted for consistency?

Quoted 5 lines
Documentation/git-format-patch.adoc +3 -0
+The "base commit" is shown as "base-commit: " followed by the 40-hex of
+the commit object name.  A `prerequisite patch` is shown as
+"prerequisite-patch-id: " followed by the 40-hex `patch id`, which can
 be obtained by passing the patch through the `git patch-id --stable`
 command.
#7 lore raw

Re: [PATCH 4/4] doc: convert git-request-pull synopsis and options to new style

In reply to Jean-Noël Avila via GitGitGadget
Quoted 23 lines · Jean-Noël Avila via GitGitGadget
(quoted diff) +6 -3
@@ -54,11 +54,15 @@ the `v1.0` release, and want it to be integrated into the project.
 First you push that change to your public repository for others to
 see:
 
-	git push https://git.ko.xz/project master
+-----
+git push https://git.ko.xz/project master
+-----
 
 Then, you run this command:
 
-	git request-pull v1.0 https://git.ko.xz/project master
+------
+git request-pull v1.0 https://git.ko.xz/project master
+------
 
 which will produce a request to the upstream, summarizing the
 changes between the `v1.0` release and your `master`, to pull it
@@ -67,11 +71,15 @@ from your public repository.
 If you pushed your change to a branch whose name is different from
 the one you have locally, e.g.
 
-	git push https://git.ko.xz/project master:for-linus

Review from your public repository. · line 82

Quoted 10 lines
(quoted diff) +6 -1
+-----
+git push https://git.ko.xz/project master:for-linus
+-----
 
 then you can ask that to be pulled with
 
-	git request-pull v1.0 https://git.ko.xz/project master:for-linus
+-----
+git request-pull v1.0 https://git.ko.xz/project master:for-linus
+-----

Is there a widely accepted guideline among AsciiDoc users governing how many dashes should delimit these blocks, other than "at least four, with the opening and closing counts matching"? If so, what is it? We see five, six, five, and five dashes in the proposed changes above, and in '[PATCH 1/4]' we saw nine. Even if varying counts are functionally equivalent, the inconsistency is a bit distracting.

Thanks.

[Footnote]

* an excerpt from [PATCH 1/4]

Documentation/git-imap-send.adoc +4 -1
index 538b91afc0..dd1e0a3718 100644
@@ -192,7 +192,10 @@ supports only `XOAUTH2` as the mechanism.
 
 Once the commits are ready to be sent, run the following command:
 
-  $ git format-patch --cover-letter -M --stdout origin/master | git imap-send
+
+---------
+$ git format-patch --cover-letter -M --stdout origin/master | git imap-send
+---------
#4 lore raw

Re: [PATCH 2/4] doc: convert git-format-patch synopsis and options to new style

In reply to Junio C Hamano
Quoted 16 lines · On Monday, 20 July 2026 01:40:17 CEST Junio C Hamano wrote:
Quoted 3 lines · Jean-Noël Avila via GitGitGadget

Backtick-quote all option terms in the OPTIONS section, convert standalone placeholders to _<placeholder>_ form, and convert single-quoted commands and tools in prose to backtick form.

OK.

Quoted 9 lines
Documentation/git-format-patch.adoc +1 -0
@@ -708,15 +708,15 @@ BASE TREE INFORMATION
 
 The base tree information block is used for maintainers or third party
 testers to know the exact state the patch series applies to. It consists
 
+of the "base commit", which is a well-known commit that is part of the
 
 stable part of the project history everybody else works off of, and zero
 
Quoted 9 lines

Documentation/git-format-patch.adoc BASE TREE INFORMATION · line 715

Quoted 3 lines
Documentation/git-format-patch.adoc +3 -0
+or more "prerequisite patches", which are well-known patches in flight
+that is not yet part of the "base commit" that need to be applied on top
+of "base commit" in topological order before the patches can be applied.

GIven that the last part of this hunk below uses backtick-quoting for prerequisite patch and patch id, shouldn't the references to base commit, and prerequisite patch(es) in the above also be backtick quoted for consistency?

In fact, the formatting were swapped. For proper rendering and preservation of spaces, it should be:

The "base commit" is shown as "base-commit: " followed by the 40-hex of the commit object name. A "prerequisite patch" is shown as "prerequisite-patch-id: " followed by the 40-hex "patch id", which can be obtained by passing the patch through the git patch-id --stable command.

Only the constant strings are back-ticked. The others are only quoted.

Will reroll.

Quoted 6 lines
Quoted 6 lines
Documentation/git-format-patch.adoc +3 -0
+The "base commit" is shown as "base-commit: " followed by the 40-hex of
+the commit object name.  A `prerequisite patch` is shown as
+"prerequisite-patch-id: " followed by the 40-hex `patch id`, which can
 
 be obtained by passing the patch through the `git patch-id --stable`
 command.
#8 lore raw

Re: [PATCH 4/4] doc: convert git-request-pull synopsis and options to new style

In reply to Junio C Hamano
Quoted 2 lines · On Monday, 20 July 2026 01:47:02 CEST Junio C Hamano wrote:

Review the `v1.0` release, and want it to be integrated into

Quoted 1 line · Jean-Noël Avila via GitGitGadget
(quoted diff) +0 -0
@@ -54,11 +54,15 @@ the `v1.0` release, and want it to be integrated into 

the

Documentation/git-imap-

Quoted 49 lines
Quoted 24 lines

project.>
First you push that change to your public repository for others to

see:

(quoted diff) +6 -3
-	git push https://git.ko.xz/project master
+-----
+git push https://git.ko.xz/project master
+-----
 
 Then, you run this command:
-	git request-pull v1.0 https://git.ko.xz/project master
+------
+git request-pull v1.0 https://git.ko.xz/project master
+------
 
 which will produce a request to the upstream, summarizing the
 changes between the `v1.0` release and your `master`, to pull it
@@ -67,11 +71,15 @@ from your public repository.
 
 If you pushed your change to a branch whose name is different from
 the one you have locally, e.g.
 
-	git push https://git.ko.xz/project master:for-linus

Review from your public repository. · line 83

Quoted 10 lines
(quoted diff) +6 -1
+-----
+git push https://git.ko.xz/project master:for-linus
+-----
 
 then you can ask that to be pulled with
 
-	git request-pull v1.0 https://git.ko.xz/project master:for-linus
+-----
+git request-pull v1.0 https://git.ko.xz/project master:for-linus
+-----

Is there a widely accepted guideline among AsciiDoc users governing how many dashes should delimit these blocks, other than "at least four, with the opening and closing counts matching"? If so, what is it? We see five, six, five, and five dashes in the proposed changes above, and in '[PATCH 1/4]' we saw nine. Even if varying counts are functionally equivalent, the inconsistency is a bit distracting.

Thanks.

[Footnote]

* an excerpt from [PATCH 1/4]

Documentation/git-imap- renamed from Documentation/git-imap-send.adoc +0 -0

send.adoc

Documentation/git-imap-send.adoc supports only `XOAUTH2` as the mechanism. · line 195

Quoted 8 lines

index 538b91afc0..dd1e0a3718 100644

Documentation/git-imap-send.adoc +0 -1
@@ -192,7 +192,10 @@ supports only `XOAUTH2` as the mechanism.
 
 Once the commits are ready to be sent, run the following command:
 
-  $ git format-patch --cover-letter -M --stdout origin/master | git imap-

send

Documentation/git-imap-send.adoc supports only `XOAUTH2` as the mechanism. · line 198

Quoted 4 lines
Documentation/git-imap-send.adoc +4 -0
+
+---------
+$ git format-patch --cover-letter -M --stdout origin/master | git imap-send
+---------

"Widely accepted", I do not know. I would better frame it as "because at least four is needed and I'm lazy, then it's four". I'm not expert enough the asciidoc specification to have a definitive answer of mine, but the asciidoctor specification says exactly four [1]

We could indeed apply the rule of 4 dashes by default.

Note that this only applies because it is a listing block which does not accept nesting.

I will reroll.

[1]: https://docs.asciidoctor.org/asciidoc/latest/verbatim/listing-blocks/
#delimited-listing-block

#9 lore raw

Re: [PATCH 4/4] doc: convert git-request-pull synopsis and options to new style

Quoted 11 lines · Jean-Noël AVILA

"Widely accepted", I do not know. I would better frame it as "because at least four is needed and I'm lazy, then it's four". I'm not expert enough the asciidoc specification to have a definitive answer of mine, but the asciidoctor specification says exactly four [1]

We could indeed apply the rule of 4 dashes by default.

Note that this only applies because it is a listing block which does not accept nesting.

I will reroll.

Thanks. Sounds like a good plan to me.

#10 lore raw

v2 cover A new batch of synopsis conversion

In reply to Jean-Noël Avila via GitGitGadget

The conversion to synopsis continues. Now the commands are less common, so I may propose larger PRs if it's ok.

Changes since v1:

* swap formats following comments
* switch all listing blocks to 4 dash fences

Jean-Noël Avila (4):
doc: convert git-imap-send synopsis and options to new style
doc: convert git-format-patch synopsis and options to new style
doc: convert git-send-email synopsis and options to new style
doc: convert git-request-pull synopsis and options to new style

 Documentation/config/imap.adoc      |   2 +-
 Documentation/config/sendemail.adoc |  92 ++++-----
 Documentation/diff-options.adoc     |   8 +-
 Documentation/git-format-patch.adoc | 289 ++++++++++++++--------------
 Documentation/git-imap-send.adoc    |  22 ++-
 Documentation/git-request-pull.adoc |  38 ++--
 Documentation/git-send-email.adoc   | 162 ++++++++--------
 7 files changed, 311 insertions(+), 302 deletions(-)

base-commit: 08621c32d5536babd139ab1a9086349b3672edd6
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2185%2Fjnavila%2Fconvert_synopsis_202606-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2185/jnavila/convert_synopsis_202606-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/2185

Range-diff vs v1:

1: 798c064390 ! 1: 697b4b55c3 doc: convert git-imap-send synopsis and options to new style
@@ Documentation/config/imap.adoc
plaintext LOGIN command.

## Documentation/git-imap-send.adoc ##
-@@ Documentation/git-imap-send.adoc: supports only XOAUTH2 as the mechanism.
+@@ Documentation/git-imap-send.adoc: that order.
+
+ Typical usage is something like:
+
+-------
++----
+ $ git format-patch --signoff --stdout --attach origin | git imap-send
+-------
++----
+
+
+ OPTIONS
+@@ Documentation/git-imap-send.adoc: have set up) may not be verified correctly.
+
+ Using Gmail's IMAP interface:
+
+----------
++----
+ [imap]
+ folder = "[Gmail]/Drafts"
+ host = imaps://imap.gmail.com
+ user = [email protected]
+ port = 993
+----------
++----
+
+ Gmail does not allow using your regular password for git imap-send.
+ If you have multi-factor authentication set up on your Gmail account, you
+@@ Documentation/git-imap-send.adoc: than using app-specific passwords, and also does not enforce the need of
+ having multi-factor authentication. You will have to use an OAuth2.0
+ access token in place of your password when using this authentication.
+
+----------
++----
+ [imap]
+ folder = "[Gmail]/Drafts"
+ host = imaps://imap.gmail.com
+ user = [email protected]
+ port = 993
+ authmethod = OAUTHBEARER
+----------
++----
+
+ Using Outlook's IMAP interface:
+
+ Unlike Gmail, Outlook only supports OAuth2.0 based authentication. Also, it
+ supports only XOAUTH2 as the mechanism.
+
+----------
++----
+ [imap]
+ folder = "Drafts"
+ host = imaps://outlook.office365.com
+ user = [email protected]
+ port = 993
+ authmethod = XOAUTH2
+----------
++----

Once the commits are ready to be sent, run the following command:

- $ git format-patch --cover-letter -M --stdout origin/master | git imap-send
-+
-+---------
++----
+$ 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 interface will wrap lines no matter what, so you need to use a real
2: e1ed85e3f2 ! 2: 3850fb33ff doc: convert git-format-patch synopsis and options to new style
@@ Documentation/git-format-patch.adoc: set.
Show progress reports on stderr as patches are generated.

CONFIGURATION
+@@ Documentation/git-format-patch.adoc: outputting more than one patch, add "To:" or "Cc:" headers, configure
+ attachments, change the patch output directory, and sign off patches
+ with configuration variables.
+
+-------------
++----
+ [format]
+ headers = "Organization: git-foo\n"
+ subjectPrefix = CHANGE
@@ Documentation/git-format-patch.adoc: with configuration variables.
+ coverLetter = auto
+ commitListFormat = shortlog
+ coverFromDescription = auto
+-------------
+-
++----
+
DISCUSSION
----------

@@ Documentation/git-format-patch.adoc: with configuration variables.
with a fixed "magic" time stamp to indicate that the file is output from format-patch rather than a real mailbox, like so:

+-------------
++----
+ From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
+ From: Tony Luck <[email protected]>
+ Date: Tue, 13 Jul 2010 11:42:54 -0700
+@@ Documentation/git-format-patch.adoc: arch/arm config files were slimmed down using a python script +
+ Do the same for ia64 so we can have sleek & trim looking
+ ...
+-------------
++----
+
+ Typically it will be placed in a MUA's drafts folder, edited to add
+ timely commentary that should not go in the changelog after the three
@@ Documentation/git-format-patch.adoc: can save interesting patches in a UNIX mailbox and apply them with
linkgit:git-am[1].

@@ Documentation/git-format-patch.adoc: can save interesting patches in a UNIX mail
line that consists solely of "-- >8 --" (scissors and perforation), followed by the patch with unnecessary header fields removed:

+-------------
++----
+ ...
+ > So we should do such-and-such.
+
+@@ Documentation/git-format-patch.adoc: Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet +
+ arch/arm config files were slimmed down using a python script
+ ...
+-------------
++----
+
+ When sending a patch this way, most often you are sending your own
+ patch, so in addition to the "From $SHA1 $magic_timestamp" marker you
@@ Documentation/git-format-patch.adoc: two common types of corruption:
One way to test if your MUA is set up correctly is:

@@ Documentation/git-format-patch.adoc: External Editor from https://globs.org/arti
window for the patch, use Tools->about:config to set the
following to the indicated values:
+
+-----------
++----
+ mailnews.send_plaintext_flowed => false
+ mailnews.wraplength => 0
+-----------
++----
+
+ 4. Open a compose window and click the external editor icon.
+
+@@ Documentation/git-format-patch.adoc: External Editor from https://globs.org/articles.php?lng=en&pg=8
+ Side note: it may be possible to do step 2 with
+ about:config and the following settings but no one's tried yet.
+
+-----------
++----
+ mail.html_compose => false
+ mail.identity.default.compose_html => false
+ mail.identity.id?.compose_html => false
+-----------
++----
+
+ There is a script in contrib/thunderbird-patch-inline which can help
+ you include patches with Thunderbird in an easy way. To use it, do the
@@ Documentation/git-format-patch.adoc: BASE TREE INFORMATION

The base tree information block is used for maintainers or third party
@@ Documentation/git-format-patch.adoc: BASE TREE INFORMATION
-The 'base commit' is shown as "base-commit: " followed by the 40-hex of -the commit object name. A 'prerequisite patch' is shown as -"prerequisite-patch-id: " followed by the 40-hex 'patch id', which can
-+The "base commit" is shown as "base-commit: " followed by the 40-hex of -+the commit object name. A prerequisite patch is shown as -+"prerequisite-patch-id: " followed by the 40-hex patch id, which can ++The "base commit" is shown as "base-commit: " followed by the 40-hex of ++the commit object name. A "prerequisite patch" is shown as ++"prerequisite-patch-id: " followed by the 40-hex "patch id", which can
be obtained by passing the patch through the git patch-id --stable command.

+@@ Documentation/git-format-patch.adoc: range), the base tree information block is shown at the end of the
+ first message the command outputs (either the first patch, or the
+ cover letter), like this:
+
+-------------
++----
+ base-commit: P
+ prerequisite-patch-id: X
+ prerequisite-patch-id: Y
+ prerequisite-patch-id: Z
+-------------
++----
+
+ For non-linear topology, such as
+
@@ Documentation/git-format-patch.adoc: EXAMPLES
--------

 3:  723450c5a0 = 3:  94751ae58b doc: convert git-send-email synopsis and options to new style
 4:  5b6e9bd3f3 ! 4:  740b24631d doc: convert git-request-pull synopsis and options to new style
     @@ Documentation/git-request-pull.adoc: the `v1.0` release, and want it to be integ
       see:
       
      -	git push https://git.ko.xz/project master
     -+-----
     ++----
      +git push https://git.ko.xz/project master
     -+-----
     ++----
       
       Then, you run this command:
       
      -	git request-pull v1.0 https://git.ko.xz/project master
     -+------
     ++----
      +git request-pull v1.0 https://git.ko.xz/project master
     -+------
     ++----
       
       which will produce a request to the upstream, summarizing the
       changes between the `v1.0` release and your `master`, to pull it
     @@ Documentation/git-request-pull.adoc: from your public repository.
       the one you have locally, e.g.
       
      -	git push https://git.ko.xz/project master:for-linus
     -+-----
     ++----
      +git push https://git.ko.xz/project master:for-linus
     -+-----
     ++----
       
       then you can ask that to be pulled with
       
      -	git request-pull v1.0 https://git.ko.xz/project master:for-linus
     -+-----
     ++----
      +git request-pull v1.0 https://git.ko.xz/project master:for-linus
     -+-----
     ++----
       
       
       GIT
Signature · 1 line
gitgitgadget
#11 lore raw

PATCH v2 1/4 doc: convert git-imap-send synopsis and options to new style

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>

Convert git-imap-send from [verse]/single-quote style to the modern synopsis-block style:

- Replace [verse] with [synopsis] in SYNOPSIS block
- Backtick-quote all OPTIONS terms
- Backtick-quote all config keys in config/imap.adoc
- Backtick-quote bare config key references in prose

---
 Documentation/config/imap.adoc   |  2 +-
 Documentation/git-imap-send.adoc | 22 ++++++++++++----------
 2 files changed, 13 insertions(+), 11 deletions(-)
Documentation/config/imap.adoc +1 -1
index cb8f5e2700..6b97776bc3 100644
@@ -41,7 +41,7 @@
 `imap.authMethod`::
 	Specify the authentication method for authenticating with the IMAP server.
 	If Git was built with the NO_CURL option, or if your curl version is older
-	than 7.34.0, or if you're running git-imap-send with the `--no-curl`
+	than 7.34.0, or if you're running `git-imap-send` with the `--no-curl`
 	option, the only supported methods are `PLAIN`, `CRAM-MD5`, `OAUTHBEARER`
 	and `XOAUTH2`. If this is not set then `git imap-send` uses the basic IMAP
 	plaintext `LOGIN` command.
Documentation/git-imap-send.adoc +12 -10
index 538b91afc0..1814d94491 100644
@@ -24,9 +24,9 @@ that order.
 
 Typical usage is something like:
 
-------
+----
 $ git format-patch --signoff --stdout --attach origin | git imap-send
-------
+----
 
 
 OPTIONS
@@ -138,13 +138,13 @@ have set up) may not be verified correctly.
 
 Using Gmail's IMAP interface:
 
----------
+----
 [imap]
     folder = "[Gmail]/Drafts"
     host = imaps://imap.gmail.com
     user = [email protected]
     port = 993
----------
+----
 
 Gmail does not allow using your regular password for `git imap-send`.
 If you have multi-factor authentication set up on your Gmail account, you
@@ -167,32 +167,34 @@ than using app-specific passwords, and also does not enforce the need of
 having multi-factor authentication. You will have to use an OAuth2.0
 access token in place of your password when using this authentication.
 
----------
+----
 [imap]
     folder = "[Gmail]/Drafts"
     host = imaps://imap.gmail.com
     user = [email protected]
     port = 993
     authmethod = OAUTHBEARER
----------
+----
 
 Using Outlook's IMAP interface:
 
 Unlike Gmail, Outlook only supports OAuth2.0 based authentication. Also, it
 supports only `XOAUTH2` as the mechanism.
 
----------
+----
 [imap]
     folder = "Drafts"
     host = imaps://outlook.office365.com
     user = [email protected]
     port = 993
     authmethod = XOAUTH2
----------
+----
 
 Once the commits are ready to be sent, run the following command:
 
-  $ git format-patch --cover-letter -M --stdout origin/master | git imap-send
+----
+$ 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
 interface will wrap lines no matter what, so you need to use a real
@@ -217,7 +219,7 @@ users may wish to visit this web page for more information:
 
 SEE ALSO
 --------
-linkgit:git-format-patch[1], linkgit:git-send-email[1], mbox(5)
+linkgit:git-format-patch[1], linkgit:git-send-email[1], `mbox`(5)
 
 GIT
 ---
Signature · 1 line
gitgitgadget
#12 lore raw

PATCH v2 2/4 doc: convert git-format-patch synopsis and options to new style

In reply to Jean-Noël Avila via GitGitGadget

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>

Replace [verse] with [synopsis] in the SYNOPSIS block and remove single-quote formatting from the command name.

Backtick-quote all option terms in the OPTIONS section, convert standalone placeholders to _<placeholder>_ form, and convert single-quoted commands and tools in prose to backtick form.

Also update the included files:
- diff-options.adoc: backtick-quote the git-format-patch-specific option terms (-p, --no-stat, --max-depth=<depth>)
- format-patch-caveats.adoc: convert patch(1) to patch(1)

---
 Documentation/diff-options.adoc     |   8 +-
 Documentation/git-format-patch.adoc | 289 ++++++++++++++--------------
 2 files changed, 148 insertions(+), 149 deletions(-)
Documentation/diff-options.adoc +4 -4
index c8242e2462..e605d28678 100644
@@ -13,8 +13,8 @@ endif::git-diff[]
 endif::git-format-patch[]
 
 ifdef::git-format-patch[]
--p::
---no-stat::
+`-p`::
+`--no-stat`::
 	Generate plain patches without any diffstats.
 endif::git-format-patch[]
 
@@ -893,8 +893,8 @@ endif::git-format-patch[]
 	reverted with `--ita-visible-in-index`. Both options are
 	experimental and could be removed in future.
 
---max-depth=<depth>::
-	For each pathspec given on command line, descend at most `<depth>`
+`--max-depth=<depth>`::
+	For each pathspec given on command line, descend at most _<depth>_
 	levels of directories. A value of `-1` means no limit.
 	Cannot be combined with wildcards in the pathspec.
 	Given a tree containing `foo/bar/baz`, the following list shows the
Documentation/git-format-patch.adoc +144 -145

673 lines not on this page · raw message

Signature · 1 line
gitgitgadget
#13 lore raw

PATCH v2 3/4 doc: convert git-send-email synopsis and options to new style

In reply to Jean-Noël Avila via GitGitGadget

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>

Replace [verse] with [synopsis] in the SYNOPSIS block and remove single-quote formatting from the command name.

Backtick-quote all option terms in the OPTIONS section, convert the standalone placeholder _<encoding>_ in prose, fix single-quoted server names to backtick form, and convert mbox(5) to mbox(5).

Also update config/sendemail.adoc: backtick-quote all configuration key terms and fix a bare sendemail.aliasesFile reference in prose.

---
 Documentation/config/sendemail.adoc |  92 ++++++++--------
 Documentation/git-send-email.adoc   | 162 ++++++++++++++--------------
 2 files changed, 127 insertions(+), 127 deletions(-)
Documentation/config/sendemail.adoc +46 -46
index 1d700559b4..5499f91036 100644
@@ -1,25 +1,25 @@
-sendemail.identity::
+`sendemail.identity`::
 	A configuration identity. When given, causes values in the
 	`sendemail.<identity>` subsection to take precedence over
 	values in the `sendemail` section. The default identity is
 	the value of `sendemail.identity`.
 
-sendemail.smtpEncryption::
+`sendemail.smtpEncryption`::
 	See linkgit:git-send-email[1] for description.  Note that this
 	setting is not subject to the `identity` mechanism.
 
-sendemail.smtpSSLCertPath::
+`sendemail.smtpSSLCertPath`::
 	Path to ca-certificates (either a directory or a single file).
 	Set it to an empty string to disable certificate verification.
 
-sendemail.smtpSSLClientCert::
+`sendemail.smtpSSLClientCert`::
 	Path to the client certificate file to present if requested by the
 	server. This is required when the server is set up to verify client
 	certificates. If the corresponding private key is not included in the
 	file, it must be supplied using `sendemail.smtpSSLClientKey` or the
 	`--smtp-ssl-client-key` option.
 
-sendemail.smtpSSLClientKey::
+`sendemail.smtpSSLClientKey`::
 	Path to the client private key file that corresponds to the client
 	certificate. To avoid misconfiguration, this configuration must be used
 	in conjunction with `sendemail.smtpSSLClientCert` or the
@@ -28,45 +28,45 @@ sendemail.smtpSSLClientKey::
 	the certificate. Visit https://metacpan.org/pod/IO::Socket::SSL for more
 	details.
 
-sendemail.<identity>.*::
-	Identity-specific versions of the `sendemail.*` parameters
+`sendemail.<identity>.<config>`::
+	Identity-specific versions of the `sendemail.<config>` parameters
 	found below, taking precedence over those when this
 	identity is selected, through either the command-line or
 	`sendemail.identity`.
 
-sendemail.multiEdit::
+`sendemail.multiEdit`::
 	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
 	after the other, spawning a new editor each time.
 
-sendemail.confirm::
+`sendemail.confirm`::
 	Sets the default for whether to confirm before sending. Must be
 	one of `always`, `never`, `cc`, `compose`, or `auto`. See `--confirm`
 	in the linkgit:git-send-email[1] documentation for the meaning of these
 	values.
 
-sendemail.mailmap::
+`sendemail.mailmap`::
 	If `true`, makes linkgit:git-send-email[1] assume `--mailmap`,
 	otherwise assume `--no-mailmap`. `False` by default.
 
-sendemail.mailmap.file::
+`sendemail.mailmap.file`::
 	The location of a linkgit:git-send-email[1] specific augmenting
 	mailmap file. The default mailmap and `mailmap.file` are loaded
 	first. Thus, entries in this file take precedence over entries in
 	the default mailmap locations. See linkgit:gitmailmap[5].
 
-sendemail.mailmap.blob::
+`sendemail.mailmap.blob`::
 	Like `sendemail.mailmap.file`, but consider the value as a reference
 	to a blob in the repository. Entries in `sendemail.mailmap.file`
 	take precedence over entries here. See linkgit:gitmailmap[5].
 
-sendemail.aliasesFile::
+`sendemail.aliasesFile`::
 	To avoid typing long email addresses, point this to one or more
 	email aliases files.  You must also supply `sendemail.aliasFileType`.
 
-sendemail.aliasFileType::
-	Format of the file(s) specified in sendemail.aliasesFile. Must be
+`sendemail.aliasFileType`::
+	Format of the file(s) specified in `sendemail.aliasesFile`. Must be
 	one of `mutt`, `mailrc`, `pine`, `elm`, `gnus`, or `sendmail`.
 +
 What an alias file in each format looks like can be found in
@@ -75,7 +75,7 @@ differences and limitations from the standard formats are
 described below:
 +
 --
-sendmail;;
+`sendmail`;;
 *	Quoted aliases and quoted addresses are not supported: lines that
 	contain a `"` symbol are ignored.
 *	Redirection to a file (`/path/name`) or pipe (`|command`) is not
@@ -85,54 +85,54 @@ sendmail;;
 	explicitly unsupported constructs, and any other lines that are not
 	recognized by the parser.
 --
-sendemail.annotate::
-sendemail.bcc::
-sendemail.cc::
-sendemail.ccCmd::
-sendemail.chainReplyTo::
-sendemail.envelopeSender::
-sendemail.from::
-sendemail.headerCmd::
-sendemail.signedOffByCc::
-sendemail.smtpPass::
-sendemail.suppressCc::
-sendemail.suppressFrom::
-sendemail.to::
-sendemail.toCmd::
-sendemail.smtpDomain::
-sendemail.smtpServer::
-sendemail.smtpServerPort::
-sendemail.smtpServerOption::
-sendemail.smtpUser::
-sendemail.imapSentFolder::
-sendemail.useImapOnly::
-sendemail.thread::
-sendemail.transferEncoding::
-sendemail.validate::
-sendemail.xmailer::
+`sendemail.annotate`::
+`sendemail.bcc`::
+`sendemail.cc`::
+`sendemail.ccCmd`::
+`sendemail.chainReplyTo`::
+`sendemail.envelopeSender`::
+`sendemail.from`::
+`sendemail.headerCmd`::
+`sendemail.signedOffByCc`::
+`sendemail.smtpPass`::
+`sendemail.suppressCc`::
+`sendemail.suppressFrom`::
+`sendemail.to`::
+`sendemail.toCmd`::
+`sendemail.smtpDomain`::
+`sendemail.smtpServer`::
+`sendemail.smtpServerPort`::
+`sendemail.smtpServerOption`::
+`sendemail.smtpUser`::
+`sendemail.imapSentFolder`::
+`sendemail.useImapOnly`::
+`sendemail.thread`::
+`sendemail.transferEncoding`::
+`sendemail.validate`::
+`sendemail.xmailer`::
 	These configuration variables all provide a default for
 	linkgit:git-send-email[1] command-line options. See its
 	documentation for details.
 
-sendemail.outlookidfix::
+`sendemail.outlookidfix`::
 	If `true`, makes linkgit:git-send-email[1] assume `--outlook-id-fix`,
 	and if `false` assume `--no-outlook-id-fix`. If not specified, it will
 	behave the same way as if `--outlook-id-fix` is not specified.
 
-sendemail.signedOffCc (deprecated)::
+`sendemail.signedOffCc` (deprecated)::
 	Deprecated alias for `sendemail.signedOffByCc`.
 
-sendemail.smtpBatchSize::
+`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
 	one connection.
 	See also the `--batch-size` option of linkgit:git-send-email[1].
 
-sendemail.smtpReloginDelay::
+`sendemail.smtpReloginDelay`::
 	Seconds to wait before reconnecting to the smtp server.
 	See also the `--relogin-delay` option of linkgit:git-send-email[1].
 
-sendemail.forbidSendmailVariables::
+`sendemail.forbidSendmailVariables`::
 	To avoid common misconfiguration mistakes, linkgit:git-send-email[1]
 	will abort with a warning if any configuration options for `sendmail`
 	exist. Set this variable to bypass the check.
Documentation/git-send-email.adoc +81 -81

473 lines not on this page · raw message

Signature · 1 line
gitgitgadget
#14 lore raw

PATCH v2 4/4 doc: convert git-request-pull synopsis and options to new style

In reply to Jean-Noël Avila via GitGitGadget

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>

* Replace [verse] with [synopsis] in the SYNOPSIS block
* remove single-quote formatting from the command name
* backtick-quote the flag
* use _<placeholder>_ form for positional parameter terms

---
 Documentation/git-request-pull.adoc | 38 +++++++++++++++++------------
 1 file changed, 23 insertions(+), 15 deletions(-)
Documentation/git-request-pull.adoc +23 -15
index 15dcbb6d91..8523c4e6bb 100644
@@ -7,8 +7,8 @@ git-request-pull - Generates a summary of pending changes
 
 SYNOPSIS
 --------
-[verse]
-'git request-pull' [-p] <start> <URL> [<end>]
+[synopsis]
+git request-pull [-p] <start> <URL> [<end>]
 
 DESCRIPTION
 -----------
@@ -19,28 +19,28 @@ begins with the branch description, summarizes
 the changes, and indicates from where they can be pulled.
 
 The upstream project is expected to have the commit named by
-`<start>` and the output asks it to integrate the changes you made
-since that commit, up to the commit named by `<end>`, by visiting
-the repository named by `<URL>`.
+_<start>_ and the output asks it to integrate the changes you made
+since that commit, up to the commit named by _<end>_, by visiting
+the repository named by _<URL>_.
 
 
 OPTIONS
 -------
--p::
+`-p`::
 	Include patch text in the output.
 
-<start>::
+_<start>_::
 	Commit to start at.  This names a commit that is already in
 	the upstream history.
 
-<URL>::
+_<URL>_::
 	The repository URL to be pulled from.
 
-<end>::
-	Commit to end at (defaults to HEAD).  This names the commit
+_<end>_::
+	Commit to end at (defaults to `HEAD`).  This names the commit
 	at the tip of the history you are asking to be pulled.
 +
-When the repository named by `<URL>` has the commit at a tip of a
+When the repository named by _<URL>_ has the commit at a tip of a
 ref that is different from the ref you have locally, you can use the
 `<local>:<remote>` syntax, to have its local name, a colon `:`, and
 its remote name.
@@ -54,11 +54,15 @@ the `v1.0` release, and want it to be integrated into the project.
 First you push that change to your public repository for others to
 see:
 
-	git push https://git.ko.xz/project master
+----
+git push https://git.ko.xz/project master
+----
 
 Then, you run this command:
 
-	git request-pull v1.0 https://git.ko.xz/project master
+----
+git request-pull v1.0 https://git.ko.xz/project master
+----
 
 which will produce a request to the upstream, summarizing the
 changes between the `v1.0` release and your `master`, to pull it
@@ -67,11 +71,15 @@ from your public repository.
 If you pushed your change to a branch whose name is different from
 the one you have locally, e.g.
 
-	git push https://git.ko.xz/project master:for-linus
+----
+git push https://git.ko.xz/project master:for-linus
+----
 
 then you can ask that to be pulled with
 
-	git request-pull v1.0 https://git.ko.xz/project master:for-linus
+----
+git request-pull v1.0 https://git.ko.xz/project master:for-linus
+----
 
 
 GIT
Signature · 1 line
gitgitgadget
#15 lore raw
In reply to Jean-Noël Avila via GitGitGadget
Quoted 7 lines · Jean-Noël Avila via GitGitGadget

The conversion to synopsis continues. Now the commands are less common, so I may propose larger PRs if it's ok.

Changes since v1:

* swap formats following comments
* switch all listing blocks to 4 dash fences

All of these changes look as expected.

Shall we mark the topic for 'next'?

Thanks.