[PATCH v2 0/4] A new batch of synopsis conversion

["Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com>]

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 = user@gmail.com
     +     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 = user@gmail.com
     +     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 = user@outlook.com
     +     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 <tony.luck@intel.com>
     + 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

-- 
gitgitgadget