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 <[email protected]>

+ Signed-off-by: Jean-Noël Avila <[email protected]>

## 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 <[email protected]>

+ Signed-off-by: Jean-Noël Avila <[email protected]>

## 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 <[email protected]>

+ Signed-off-by: Jean-Noël Avila <[email protected]>

## 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 <[email protected]>

+ Signed-off-by: Jean-Noël Avila <[email protected]>

## Documentation/asciidoc.conf.in ##
@@ Documentation/asciidoc.conf.in: endif::backend-xhtml11[]

gitgitgadget