[PATCH v4 0/4] doc: some more synopsis conversions and fixes

This time, git-show and git-submodule are converted. Some mistakes on previous work were also spotted and fixed.

Changes since V1:

 * fix mistakes spotted by Kristoffer Haugsbakk Changes since V2:
 * more fixes Changes since V3:
 * again more fixes, origin and HEAD

Jean-Noël Avila (4):
  doc: convert git-submodule to synopsis style
  doc: finalize git-clone documentation conversion to synopsis style
  doc: fix some style issues in git-clone and for-each-ref-options
  doc: convert git-show to synopsis style

 Documentation/asciidoc.conf.in          |   6 +
 Documentation/for-each-ref-options.adoc |   4 +-
 Documentation/git-clone.adoc            |  54 ++--
 Documentation/git-show.adoc             |  16 +-
 Documentation/git-submodule.adoc        | 395 ++++++++++++------------
 Documentation/pretty-formats.adoc       | 169 +++++-----
 Documentation/ref-storage-format.adoc   |   4 +-
 7 files changed, 341 insertions(+), 307 deletions(-)

base-commit: d8af7cadaa79d5837d73ec949e10b57dedb43e9b
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2036%2Fjnavila%2Fgit_submodule-v4
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2036/jnavila/git_submodule-v4
Pull-Request: https://github.com/gitgitgadget/git/pull/2036

Range-diff vs v3:

 1:  8d22e6952a ! 1:  7798802b59 doc: convert git-submodule to synopsis style
     @@ Commit message
           * convert inline lists into proper definition lists
           * minor formatting fixes
      
     -    Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
          Reviewed-by: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
     +    Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
      
       ## Documentation/git-submodule.adoc ##
      @@ Documentation/git-submodule.adoc: git-submodule - Initialize, update or inspect submodules
     @@ Documentation/git-submodule.adoc: COMMANDS
       have to use `../foo.git` instead of `./foo.git` - as one might expect
       when following the rules for relative URLs - because the evaluation
       of relative URLs in Git is identical to that of relative directories).
     -@@ Documentation/git-submodule.adoc: If the superproject doesn't have a default remote configured
     + +
     + The default remote is the remote of the remote-tracking branch
     + of the current branch. If no such remote-tracking branch exists or
     +-the HEAD is detached, "origin" is assumed to be the default remote.
     ++the `HEAD` is detached, `origin` is assumed to be the default remote.
     + If the superproject doesn't have a default remote configured
       the superproject is its own authoritative upstream and the current
       working directory is used instead.
       +
     @@ Documentation/git-submodule.adoc: URL in `.gitmodules`.
       	SHA-1. Each SHA-1 will possibly be prefixed with `-` if the submodule is
       	not initialized, `+` if the currently checked out submodule commit
       	does not match the SHA-1 found in the index of the containing
     -@@ Documentation/git-submodule.adoc: submodules with respect to the commit recorded in the index or the HEAD,
     +@@ Documentation/git-submodule.adoc: If `--recursive` is specified, this command will recurse into nested
     + submodules, and show their status as well.
     + +
     + If you are only interested in changes of the currently initialized
     +-submodules with respect to the commit recorded in the index or the HEAD,
     ++submodules with respect to the commit recorded in the index or the `HEAD`,
       linkgit:git-status[1] and linkgit:git-diff[1] will provide that information
       too (and can also report changes to a submodule's work tree).
       
     @@ Documentation/git-submodule.adoc: in submodules and updating the working tree of
      -	checkout;; the commit recorded in the superproject will be
      -	    checked out in the submodule on a detached HEAD.
      +`checkout`;; the commit recorded in the superproject will be
     -+checked out in the submodule on a detached HEAD.
     ++checked out in the submodule on a detached `HEAD`.
       +
       If `--force` is specified, the submodule will be checked out (using
       `git checkout --force`), even if the commit specified
     @@ Documentation/git-submodule.adoc: to distribute the default upstream branch with
      -	superproject. If this option is given, the submodule's HEAD will not
      +`--rebase`::
      +	Rebase the current branch onto the commit recorded in the superproject.
     -+	This option is only valid for the update command. The submodule's HEAD will not
     ++	This option is only valid for the `update` command. The submodule's `HEAD` will not
       	be detached. If a merge failure prevents this process, you will have
       	to resolve these failures with linkgit:git-rebase[1].
      -	If the key `submodule.$name.update` is set to `rebase`, this option is
     @@ Documentation/git-submodule.adoc: to distribute the default upstream branch with
      ---name::
      -	This option is only valid for the add command. It sets the submodule's
      -	name to the given string instead of defaulting to its path. The name
     +-	must be valid as a directory name and may not end with a '/'.
      +`--name=<name>`::
      +	Set the submodule's name to the given string instead of defaulting to its path. _<name>_
     - 	must be valid as a directory name and may not end with a '/'.
     ++	must be valid as a directory name and may not end with a `/`.
       
      ---reference <repository>::
      -	This option is only valid for add and update commands.  These
 2:  5fd9f6d41a ! 2:  41aefe8147 doc: finalize git-clone documentation conversion to synopsis style
     @@ Commit message
      
          Use backticks where appropriate for command-line options
      
     -    Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
          Reviewed-by: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
     +    Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
      
       ## Documentation/git-clone.adoc ##
      @@ Documentation/git-clone.adoc: objects from the source repository into a pack in the cloned repository.
 3:  d097065303 ! 3:  fe928fe0ed doc: fix some style issues in git-clone and for-each-ref-options
     @@ Commit message
           * Use asciidoc NOTE macro
           * fix markups
      
     -    Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
          Reviewed-by: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
     +    Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
      
       ## Documentation/for-each-ref-options.adoc ##
      @@ Documentation/for-each-ref-options.adoc: TAB %(refname)`.
 4:  d179137d81 ! 4:  6a2b94e720 doc: convert git-show to synopsis style
     @@ Commit message
           * use _<placeholder>_ for arguments
           * minor formatting fixes
      
     -    Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
          Reviewed-by: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
     +    Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
      
       ## Documentation/asciidoc.conf.in ##
      @@ Documentation/asciidoc.conf.in: endif::backend-xhtml11[]