[PATCH v3 1/4] doc: convert git-submodule to synopsis style

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

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

 * convert commands to synopsis style
 * use _<placeholder>_ for arguments
 * 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>
---
 Documentation/git-submodule.adoc | 389 ++++++++++++++++---------------
 1 file changed, 196 insertions(+), 193 deletions(-)

diff --git a/Documentation/git-submodule.adoc b/Documentation/git-submodule.adoc
index 95beaee561..e581b0c7aa 100644
--- a/Documentation/git-submodule.adoc
+++ b/Documentation/git-submodule.adoc
@@ -8,19 +8,19 @@ git-submodule - Initialize, update or inspect submodules
 
 SYNOPSIS
 --------
-[verse]
-'git submodule' [--quiet] [--cached]
-'git submodule' [--quiet] add [<options>] [--] <repository> [<path>]
-'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...]
-'git submodule' [--quiet] init [--] [<path>...]
-'git submodule' [--quiet] deinit [-f|--force] (--all|[--] <path>...)
-'git submodule' [--quiet] update [<options>] [--] [<path>...]
-'git submodule' [--quiet] set-branch [<options>] [--] <path>
-'git submodule' [--quiet] set-url [--] <path> <newurl>
-'git submodule' [--quiet] summary [<options>] [--] [<path>...]
-'git submodule' [--quiet] foreach [--recursive] <command>
-'git submodule' [--quiet] sync [--recursive] [--] [<path>...]
-'git submodule' [--quiet] absorbgitdirs [--] [<path>...]
+[synopsis]
+git submodule [--quiet] [--cached]
+git submodule [--quiet] add [<options>] [--] <repository> [<path>]
+git submodule [--quiet] status [--cached] [--recursive] [--] [<path>...]
+git submodule [--quiet] init [--] [<path>...]
+git submodule [--quiet] deinit [-f|--force] (--all|[--] <path>...)
+git submodule [--quiet] update [<options>] [--] [<path>...]
+git submodule [--quiet] set-branch [<options>] [--] <path>
+git submodule [--quiet] set-url [--] <path> <newurl>
+git submodule [--quiet] summary [<options>] [--] [<path>...]
+git submodule [--quiet] foreach [--recursive] <command>
+git submodule [--quiet] sync [--recursive] [--] [<path>...]
+git submodule [--quiet] absorbgitdirs [--] [<path>...]
 
 
 DESCRIPTION
@@ -34,16 +34,16 @@ COMMANDS
 With no arguments, shows the status of existing submodules.  Several
 subcommands are available to perform operations on the submodules.
 
-add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--] <repository> [<path>]::
+`add [-b <branch>] [-f | --force] [--name <name>] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--] <repository> [<path>]`::
 	Add the given repository as a submodule at the given path
 	to the changeset to be committed next to the current
 	project: the current project is termed the "superproject".
 +
-<repository> is the URL of the new submodule's origin repository.
-This may be either an absolute URL, or (if it begins with ./
-or ../), the location relative to the superproject's default remote
-repository (Please note that to specify a repository 'foo.git'
-which is located right next to a superproject 'bar.git', you'll
+_<repository>_ is the URL of the new submodule's `origin` repository.
+This may be either an absolute URL, or (if it begins with `./`
+or `../`), the location relative to the superproject's default remote
+repository (Please note that to specify a repository `foo.git`
+which is located right next to a superproject `bar.git`, you'll
 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).
@@ -55,13 +55,13 @@ 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.
 +
-The optional argument <path> is the relative location for the cloned
-submodule to exist in the superproject. If <path> is not given, the
-canonical part of the source repository is used ("repo" for
-"/path/to/repo.git" and "foo" for "host.xz:foo/.git"). If <path>
+The optional argument _<path>_ is the relative location for the cloned
+submodule to exist in the superproject. If _<path>_ is not given, the
+canonical part of the source repository is used (`repo` for
+`/path/to/repo.git` and `foo` for `host.xz:foo/.git`). If _<path>_
 exists and is already a valid Git repository, then it is staged
-for commit without cloning. The <path> is also used as the submodule's
-logical name in its configuration entries unless `--name` is used
+for commit without cloning. The _<path>_ is also used as the submodule's
+logical name in its configuration entries unless `--name <name>` is used
 to specify a logical name.
 +
 The given URL is recorded into `.gitmodules` for use by subsequent users
@@ -75,10 +75,10 @@ URL in `.gitmodules`.
 If `--ref-format <format>`  is specified, the ref storage format of newly
 cloned submodules will be set accordingly.
 
-status [--cached] [--recursive] [--] [<path>...]::
+`status [--cached] [--recursive] [--] [<path>...]`::
 	Show the status of the submodules. This will print the SHA-1 of the
 	currently checked out commit for each submodule, along with the
-	submodule path and the output of 'git describe' for the
+	submodule path and the output of linkgit:git-describe[1] for the
 	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
@@ -95,7 +95,7 @@ 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).
 
-init [--] [<path>...]::
+`init [--] [<path>...]`::
 	Initialize the submodules recorded in the index (which were
 	added and committed elsewhere) by setting `submodule.$name.url`
 	in `.git/config`, using the same setting from `.gitmodules` as
@@ -103,7 +103,7 @@ init [--] [<path>...]::
 	the default remote. If there is no default remote, the current
 	repository will be assumed to be upstream.
 +
-Optional <path> arguments limit which submodules will be initialized.
+Optional _<path>_ arguments limit which submodules will be initialized.
 If no path is specified and submodule.active has been configured, submodules
 configured to be active will be initialized, otherwise all submodules are
 initialized.
@@ -116,12 +116,12 @@ that is set to a custom command is *not* copied for security reasons.
 You can then customize the submodule clone URLs in `.git/config`
 for your local setup and proceed to `git submodule update`;
 you can also just use `git submodule update --init` without
-the explicit 'init' step if you do not intend to customize
+the explicit `init` step if you do not intend to customize
 any submodule locations.
 +
 See the add subcommand for the definition of default remote.
 
-deinit [-f|--force] (--all|[--] <path>...)::
+`deinit [-f | --force] (--all|[--] <path>...)`::
 	Unregister the given submodules, i.e. remove the whole
 	`submodule.$name` section from .git/config together with their work
 	tree. Further calls to `git submodule update`, `git submodule foreach`
@@ -139,7 +139,7 @@ If you really want to remove a submodule from the repository and commit
 that use linkgit:git-rm[1] instead. See linkgit:gitsubmodules[7] for removal
 options.
 
-update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter-spec>] [--] [<path>...]::
+`update [--init] [--remote] [-N | --no-fetch] [--[no-]recommend-shallow] [-f | --force] [--checkout | --rebase | --merge] [--reference=<repository>] [--ref-format=<format>] [--depth=<depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter=<filter-spec>] [--] [<path>...]`::
 +
 --
 Update the registered submodules to match what the superproject
@@ -148,38 +148,38 @@ in submodules and updating the working tree of
 the submodules. The "updating" can be done in several ways depending
 on command line options and the value of `submodule.<name>.update`
 configuration variable. The command line option takes precedence over
-the configuration variable. If neither is given, a 'checkout' is performed.
+the configuration variable. If neither is given, a `checkout` is performed.
 (note: what is in `.gitmodules` file is irrelevant at this point;
 see `git submodule init` above for how `.gitmodules` is used).
-The 'update' procedures supported both from the command line as well as
+The `update` procedures supported both from the command line as well as
 through the `submodule.<name>.update` configuration are:
 
-	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.
 +
 If `--force` is specified, the submodule will be checked out (using
 `git checkout --force`), even if the commit specified
 in the index of the containing repository already matches the commit
 checked out in the submodule.
 
-	rebase;; the current branch of the submodule will be rebased
-	    onto the commit recorded in the superproject.
+`rebase`;; the current branch of the submodule will be rebased
+onto the commit recorded in the superproject.
 
-	merge;; the commit recorded in the superproject will be merged
-	    into the current branch in the submodule.
+`merge`;; the commit recorded in the superproject will be merged
+into the current branch in the submodule.
 
 The following update procedures have additional limitations:
 
-	custom command;; mechanism for running arbitrary commands with the
-	    commit ID as an argument. Specifically, if the
-	    `submodule.<name>.update` configuration variable is set to
-	    `!custom command`, the object name of the commit recorded in the
-	    superproject for the submodule is appended to the `custom command`
-	    string and executed. Note that this mechanism is not supported in
-	    the `.gitmodules` file or on the command line.
+`!<custom-command>`;; mechanism for running arbitrary commands with the
+commit ID as an argument. Specifically, if the
+`submodule.<name>.update` configuration variable is set to
+`!<custom-command>`, the object name of the commit recorded in the
+superproject for the submodule is appended to the _<custom-command>_
+string and executed. Note that this mechanism is not supported in
+the `.gitmodules` file or on the command line.
 
-	none;; the submodule is not updated. This update procedure is not
-	    allowed on the command line.
+`none`;; the submodule is not updated. This update procedure is not
+allowed on the command line.
 
 If the submodule is not yet initialized, and you just want to use the
 setting as stored in `.gitmodules`, you can automatically initialize the
@@ -195,20 +195,20 @@ If `--filter <filter-spec>` is specified, the given partial clone filter will be
 applied to the submodule. See linkgit:git-rev-list[1] for details on filter
 specifications.
 --
-set-branch (-b|--branch) <branch> [--] <path>::
-set-branch (-d|--default) [--] <path>::
-	Sets the default remote tracking branch for the submodule. The
+`set-branch (-b|--branch) <branch> [--] <path>`::
+`set-branch (-d|--default) [--] <path>`::
+	Set the default remote tracking branch for the submodule. The
 	`--branch` option allows the remote branch to be specified. The
-	`--default` option removes the submodule.<name>.branch configuration
-	key, which causes the tracking branch to default to the remote 'HEAD'.
+	`--default` option removes the `submodule.<name>.branch` configuration
+	key, which causes the tracking branch to default to the remote `HEAD`.
 
-set-url [--] <path> <newurl>::
-	Sets the URL of the specified submodule to <newurl>. Then, it will
+`set-url [--] <path> <newurl>`::
+	Set the URL of the specified submodule to _<newurl>_. Then, it will
 	automatically synchronize the submodule's new remote URL
 	configuration.
 
-summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]::
-	Show commit summary between the given commit (defaults to HEAD) and
+`summary [--cached | --files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]`::
+	Show commit summary between the given commit (defaults to `HEAD`) and
 	working tree/index. For a submodule in question, a series of commits
 	in the submodule between the given super project commit and the
 	index or working tree (switched by `--cached`) are shown. If the option
@@ -220,27 +220,31 @@ summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]:
 Using the `--submodule=log` option with linkgit:git-diff[1] will provide that
 information too.
 
-foreach [--recursive] <command>::
-	Evaluates an arbitrary shell command in each checked out submodule.
-	The command has access to the variables $name, $sm_path, $displaypath,
-	$sha1 and $toplevel:
-	$name is the name of the relevant submodule section in `.gitmodules`,
-	$sm_path is the path of the submodule as recorded in the immediate
-	superproject, $displaypath contains the relative path from the
-	current working directory to the submodules root directory,
-	$sha1 is the commit as recorded in the immediate
-	superproject, and $toplevel is the absolute path to the top-level
-	of the immediate superproject.
-	Note that to avoid conflicts with '$PATH' on Windows, the '$path'
-	variable is now a deprecated synonym of '$sm_path' variable.
-	Any submodules defined in the superproject but not checked out are
-	ignored by this command. Unless given `--quiet`, foreach prints the name
-	of each submodule before evaluating the command.
-	If `--recursive` is given, submodules are traversed recursively (i.e.
-	the given shell command is evaluated in nested submodules as well).
-	A non-zero return from the command in any submodule causes
-	the processing to terminate. This can be overridden by adding '|| :'
-	to the end of the command.
+`foreach [--recursive] <command>`::
+	Evaluate an arbitrary shell _<command>_ in each checked out submodule.
+	The command has access to the variables `$name`, `$sm_path`, `$displaypath`,
+	`$sha1` and `$toplevel`:
++
+--
+`$name`;; the name of the relevant submodule section in `.gitmodules`
+`$sm_path`;; the path of the submodule as recorded in the immediate
+	superproject
+`$displaypath`;; the relative path from the
+	current working directory to the submodules root directory
+`$sha1`;; the commit as recorded in the immediate superproject
+`$toplevel`;; the absolute path to the top-level of the immediate superproject.
+--
++
+Note that to avoid conflicts with `$PATH` on Windows, the `$path`
+variable is now a deprecated synonym of `$sm_path` variable.
+Any submodules defined in the superproject but not checked out are
+ignored by this command. Unless given `--quiet`, foreach prints the name
+of each submodule before evaluating the command.
+If `--recursive` is given, submodules are traversed recursively (i.e.
+the given shell command is evaluated in nested submodules as well).
+A non-zero return from the command in any submodule causes
+the processing to terminate. This can be overridden by adding ++||:++
+to the end of the command.
 +
 As an example, the command below will show the path and currently
 checked out commit for each submodule:
@@ -249,26 +253,26 @@ checked out commit for each submodule:
 git submodule foreach 'echo $sm_path `git rev-parse HEAD`'
 --------------
 
-sync [--recursive] [--] [<path>...]::
-	Synchronizes submodules' remote URL configuration setting
+`sync [--recursive] [--] [<path>...]`::
+	Synchronize submodules' remote URL configuration setting
 	to the value specified in `.gitmodules`. It will only affect those
-	submodules which already have a URL entry in .git/config (that is the
+	submodules which already have a URL entry in `.git/config` (that is the
 	case when they are initialized or freshly added). This is useful when
 	submodule URLs change upstream and you need to update your local
 	repositories accordingly.
 +
 `git submodule sync` synchronizes all submodules while
-`git submodule sync -- A` synchronizes submodule "A" only.
+`git submodule sync -- A` synchronizes submodule `A` only.
 +
 If `--recursive` is specified, this command will recurse into the
 registered submodules, and sync any nested submodules within.
 
-absorbgitdirs::
+`absorbgitdirs`::
 	If a git directory of a submodule is inside the submodule,
 	move the git directory of the submodule into its superproject's
 	`$GIT_DIR/modules` path and then connect the git directory and
 	its working directory by setting the `core.worktree` and adding
-	a .git file pointing to the git directory embedded in the
+	a `.git` file pointing to the git directory embedded in the
 	superprojects git directory.
 +
 A repository that was cloned independently and later added as a submodule or
@@ -279,72 +283,70 @@ This command is recursive by default.
 
 OPTIONS
 -------
--q::
---quiet::
+`-q`::
+`--quiet`::
 	Only print error messages.
 
---progress::
-	This option is only valid for add and update commands.
-	Progress status is reported on the standard error stream
-	by default when it is attached to a terminal, unless -q
+`--progress`::
+	Report progress status on the standard error stream
+	by default when it is attached to a terminal, unless `-q`
 	is specified. This flag forces progress status even if the
-	standard error stream is not directed to a terminal.
+	standard error stream is not directed to a terminal. It is
+	only valid for `add` and `update` commands.
 
---all::
-	This option is only valid for the deinit command. Unregister all
-	submodules in the working tree.
+`--all`::
+	Unregister all submodules in the working tree. This option is only
+	valid for the `deinit` command.
 
--b <branch>::
---branch <branch>::
+`-b<branch>`::
+`--branch=<branch>`::
 	Branch of repository to add as submodule.
 	The name of the branch is recorded as `submodule.<name>.branch` in
 	`.gitmodules` for `update --remote`.  A special value of `.` is used to
 	indicate that the name of the branch in the submodule should be the
 	same name as the current branch in the current repository.  If the
-	option is not specified, it defaults to the remote 'HEAD'.
-
--f::
---force::
-	This option is only valid for add, deinit and update commands.
-	When running add, allow adding an otherwise ignored submodule path.
-	This option is also used to bypass a check that the submodule's name
-	is not already in use. By default, 'git submodule add' will fail if
-	the proposed name (which is derived from the path) is already registered
-	for another submodule in the repository. Using '--force' allows the command
-	to proceed by automatically generating a unique name by appending a number
-	to the conflicting name (e.g., if a submodule named 'child' exists, it will
-	try 'child1', and so on).
-	When running deinit the submodule working trees will be removed even
-	if they contain local changes.
-	When running update (only effective with the checkout procedure),
-	throw away local changes in submodules when switching to a
-	different commit; and always run a checkout operation in the
-	submodule, even if the commit listed in the index of the
-	containing repository matches the commit checked out in the
-	submodule.
-
---cached::
-	This option is only valid for status and summary commands.  These
-	commands typically use the commit found in the submodule HEAD, but
-	with this option, the commit stored in the index is used instead.
-
---files::
-	This option is only valid for the summary command. This command
-	compares the commit in the index with that in the submodule HEAD
-	when this option is used.
-
--n::
---summary-limit::
-	This option is only valid for the summary command.
-	Limit the summary size (number of commits shown in total).
+	option is not specified, it defaults to the remote `HEAD`.
+
+`-f`::
+`--force`::
+	Force the command to proceed, even if it would otherwise fail.
+	This option is only valid for `add`, `deinit` and `update` commands.
+`add`;; allow adding an otherwise ignored submodule path.
+This option is also used to bypass a check that the submodule's name
+is not already in use. By default, `git submodule add` will fail if
+the proposed name (which is derived from the path) is already registered
+for another submodule in the repository. Using `--force` allows the command
+to proceed by automatically generating a unique name by appending a number
+to the conflicting name (e.g., if a submodule named 'child' exists, it will
+try 'child1', and so on).
+`deinit`;; the submodule working trees will be removed even
+if they contain local changes.
+`update`;; (only effective with the checkout procedure),
+throw away local changes in submodules when switching to a
+different commit; and always run a checkout operation in the
+submodule, even if the commit listed in the index of the
+containing repository matches the commit checked out in the
+submodule.
+
+`--cached`::
+	Use the index to determine the commit instead of the `HEAD`.
+	This option is only valid for `status` and `summary` commands.
+
+`--files`::
+	Make the `summary` command compare the commit in the index with that in
+	the submodule `HEAD`.
+
+`-n<n>`::
+`--summary-limit=<n>`::
+	Limit the `summary` size (number of commits shown in total) to _<n>_.
 	Giving 0 will disable the summary; a negative number means unlimited
 	(the default). This limit only applies to modified submodules. The
 	size is always limited to 1 for added/deleted/typechanged submodules.
 
---remote::
-	This option is only valid for the update command.  Instead of using
-	the superproject's recorded SHA-1 to update the submodule, use the
-	status of the submodule's remote-tracking branch.  The remote used
+`--remote`::
+	Instead of using the superproject's recorded SHA-1 to update the
+	submodule, use the status of the submodule's remote-tracking branch.
+	This option is only valid for the `update` command. The remote used
 	is branch's remote (`branch.<name>.remote`), defaulting to `origin`.
 	The remote branch used defaults to the remote `HEAD`, but the branch
 	name may be overridden by setting the `submodule.<name>.branch`
@@ -363,7 +365,7 @@ SHA-1.  If you don't want to fetch, you should use `submodule update
 --remote --no-fetch`.
 +
 Use this option to integrate changes from the upstream subproject with
-your submodule's current HEAD.  Alternatively, you can run `git pull`
+your submodule's current `HEAD`.  Alternatively, you can run `git pull`
 from the submodule, which is equivalent except for the remote branch
 name: `update --remote` uses the default upstream repository and
 `submodule.<name>.branch`, while `git pull` uses the submodule's
@@ -372,105 +374,106 @@ to distribute the default upstream branch with the superproject and
 `branch.<name>.merge` if you want a more native feel while working in
 the submodule itself.
 
--N::
---no-fetch::
-	This option is only valid for the update command.
+`-N`::
+`--no-fetch`::
 	Don't fetch new objects from the remote site.
+	This option is only valid for the `update` command.
 
---checkout::
-	This option is only valid for the update command.
-	Checkout the commit recorded in the superproject on a detached HEAD
-	in the submodule. This is the default behavior, the main use of
-	this option is to override `submodule.$name.update` when set to
+`--checkout`::
+	Checkout the commit recorded in the superproject on a detached `HEAD`
+	in the submodule. This option is only valid for the `update` command.
+	This is the default behavior, the main use of
+	this option is to override `submodule.<name>.update` when set to
 	a value other than `checkout`.
-	If the key `submodule.$name.update` is either not explicitly set or
+	If the key `submodule.<name>.update` is either not explicitly set or
 	set to `checkout`, this option is implicit.
 
---merge::
-	This option is only valid for the update command.
+`--merge`::
 	Merge the commit recorded in the superproject into the current branch
-	of the submodule. If this option is given, the submodule's HEAD will
+	of the submodule. This option is only valid for the `update` command.
+	If this option is given, the submodule's `HEAD` will
 	not be detached. If a merge failure prevents this process, you will
 	have to resolve the resulting conflicts within the submodule with the
 	usual conflict resolution tools.
-	If the key `submodule.$name.update` is set to `merge`, this option is
+	If the key `submodule.<name>.update` is set to `merge`, this option is
 	implicit.
 
---rebase::
-	This option is only valid for the update command.
-	Rebase the current branch onto the commit recorded in the
-	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
 	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
+	If the key `submodule.<name>.update` is set to `rebase`, this option is
 	implicit.
 
---init::
-	This option is only valid for the update command.
-	Initialize all submodules for which "git submodule init" has not been
-	called so far before updating.
+`--init`::
+	Initialize all submodules for which `git submodule init` has not been
+	called so far before updating. 	This option is only valid for the `update`
+	command.
+
 
---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
+`--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 '/'.
 
---reference <repository>::
-	This option is only valid for add and update commands.  These
-	commands sometimes need to clone a remote repository. In this case,
+`--reference=<repository>`::
+	Pass the local _<repository>_ as a reference when cloning the submodule.
+	This option is only valid for `add` and `update` commands.
+	These commands sometimes need to clone a remote repository. In this case,
 	this option will be passed to the linkgit:git-clone[1] command.
 +
-*NOTE*: Do *not* use this option unless you have read the note
+NOTE: Do *not* use this option unless you have read the note
 for linkgit:git-clone[1]'s `--reference`, `--shared`, and `--dissociate`
 options carefully.
 
---dissociate::
-	This option is only valid for add and update commands.  These
-	commands sometimes need to clone a remote repository. In this case,
+`--dissociate`::
+	After using a reference repository to clone from, do not rely on it anymore.
+	This option is only valid for `add` and `update` commands.
+	These commands sometimes need to clone a remote repository. In this case,
 	this option will be passed to the linkgit:git-clone[1] command.
 +
-*NOTE*: see the NOTE for the `--reference` option.
+NOTE: See the NOTE above for the `--reference` option.
 
---recursive::
-	This option is only valid for foreach, update, status and sync commands.
-	Traverse submodules recursively. The operation is performed not
+`--recursive`::
+	Traverse submodules recursively. This option is only valid for `foreach`,
+	`update`, `status` and `sync` commands. The operation is performed not
 	only in the submodules of the current repo, but also
 	in any nested submodules inside those submodules (and so on).
 
---depth::
-	This option is valid for add and update commands. Create a 'shallow'
-	clone with a history truncated to the specified number of revisions.
-	See linkgit:git-clone[1]
+`--depth=<depth>`::
+	Create a 'shallow' clone with a history truncated to the _<depth>_ revisions.
+	This option is valid for `add` and `update` commands. See linkgit:git-clone[1]
 
---recommend-shallow::
---no-recommend-shallow::
-	This option is only valid for the update command.
+`--recommend-shallow`::
+`--no-recommend-shallow`::
+	Recommend or not shallow cloning of submodules.
+	This option is only valid for the `update` command.
 	The initial clone of a submodule will use the recommended
 	`submodule.<name>.shallow` as provided by the `.gitmodules` file
 	by default. To ignore the suggestions use `--no-recommend-shallow`.
 
--j <n>::
---jobs <n>::
-	This option is only valid for the update command.
-	Clone new submodules in parallel with as many jobs.
+`-j<n>`::
+`--jobs=<n>`::
+	Clone new submodules in parallel with _<n>_ jobs.
+	This option is only valid for the `update` command.
 	Defaults to the `submodule.fetchJobs` option.
 
---single-branch::
---no-single-branch::
-	This option is only valid for the update command.
-	Clone only one branch during update: HEAD or one specified by --branch.
+`--single-branch`::
+`--no-single-branch`::
+	Clone only one branch during update: `HEAD` or one specified by `--branch`.
+	This option is only valid for the `update` command.
 
-<path>...::
+`<path>...`::
 	Paths to submodule(s). When specified this will restrict the command
 	to only operate on the submodules found at the specified paths.
-	(This argument is required with add).
+	(This argument is required with `add`).
 
 FILES
 -----
 When initializing submodules, a `.gitmodules` file in the top-level directory
-of the containing repository is used to find the url of each submodule.
+of the containing repository is used to find the URL of each submodule.
 This file should be formatted in the same way as `$GIT_DIR/config`. The key
-to each submodule url is "submodule.$name.url".  See linkgit:gitmodules[5]
+to each submodule URL is `submodule.<name>.url`.  See linkgit:gitmodules[5]
 for details.
 
 SEE ALSO
-- 
gitgitgadget