doc: convert git push to synopsis style

- Switch the synopsis to a synopsis block which will automatically
  format placeholders in italics and keywords in monospace
- Use _<placeholder>_ instead of <placeholder> in the description
- Use `backticks` for keywords and more complex option
descriptions. The new rendering engine will apply synopsis rules to
these spans.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

1 files changed, 55 insertions, 50 deletions

diff --git a/Documentation/config/push.adoc b/Documentation/config/push.adoc
index 0acbbea18a..d9112b2260 100644
--- a/Documentation/config/push.adoc
+++ b/Documentation/config/push.adoc
@@ -1,15 +1,15 @@
-push.autoSetupRemote::
-	If set to "true" assume `--set-upstream` on default push when no
+`push.autoSetupRemote`::
+	If set to `true` assume `--set-upstream` on default push when no
 	upstream tracking exists for the current branch; this option
-	takes effect with push.default options 'simple', 'upstream',
-	and 'current'. It is useful if by default you want new branches
+	takes effect with `push.default` options `simple`, `upstream`,
+	and `current`. It is useful if by default you want new branches
 	to be pushed to the default remote (like the behavior of
-	'push.default=current') and you also want the upstream tracking
+	`push.default=current`) and you also want the upstream tracking
 	to be set. Workflows most likely to benefit from this option are
-	'simple' central workflows where all branches are expected to
+	`simple` central workflows where all branches are expected to
 	have the same name on the remote.
 
-push.default::
+`push.default`::
 	Defines the action `git push` should take if no refspec is
 	given (whether from the command-line, config, or elsewhere).
 	Different values are well-suited for
@@ -18,24 +18,28 @@ push.default::
 	`upstream` is probably what you want.  Possible values are:
 +
 --
+`nothing`;;
+do not push anything (error out) unless a refspec is
+given. This is primarily meant for people who want to
+avoid mistakes by always being explicit.
 
-* `nothing` - do not push anything (error out) unless a refspec is
-  given. This is primarily meant for people who want to
-  avoid mistakes by always being explicit.
+`current`;;
+push the current branch to update a branch with the same
+name on the receiving end.  Works in both central and non-central
+workflows.
 
-* `current` - push the current branch to update a branch with the same
-  name on the receiving end.  Works in both central and non-central
-  workflows.
+`upstream`;;
+push the current branch back to the branch whose
+changes are usually integrated into the current branch (which is
+called `@{upstream}`).  This mode only makes sense if you are
+pushing to the same repository you would normally pull from
+(i.e. central workflow).
 
-* `upstream` - push the current branch back to the branch whose
-  changes are usually integrated into the current branch (which is
-  called `@{upstream}`).  This mode only makes sense if you are
-  pushing to the same repository you would normally pull from
-  (i.e. central workflow).
+`tracking`;;
+this is a deprecated synonym for `upstream`.
 
-* `tracking` - This is a deprecated synonym for `upstream`.
-
-* `simple` - push the current branch with the same name on the remote.
+`simple`;;
+push the current branch with the same name on the remote.
 +
 If you are working on a centralized workflow (pushing to the same repository you
 pull from, which is typically `origin`), then you need to configure an upstream
@@ -44,16 +48,17 @@ branch with the same name.
 This mode is the default since Git 2.0, and is the safest option suited for
 beginners.
 
-* `matching` - push all branches having the same name on both ends.
-  This makes the repository you are pushing to remember the set of
-  branches that will be pushed out (e.g. if you always push 'maint'
-  and 'master' there and no other branches, the repository you push
-  to will have these two branches, and your local 'maint' and
-  'master' will be pushed there).
+`matching`;;
+push all branches having the same name on both ends.
+This makes the repository you are pushing to remember the set of
+branches that will be pushed out (e.g. if you always push `maint`
+and `master` there and no other branches, the repository you push
+to will have these two branches, and your local `maint` and
+`master` will be pushed there).
 +
 To use this mode effectively, you have to make sure _all_ the
 branches you would push out are ready to be pushed out before
-running 'git push', as the whole point of this mode is to allow you
+running `git push`, as the whole point of this mode is to allow you
 to push all of the branches in one go.  If you usually finish work
 on only one branch and push out the result, while other branches are
 unfinished, this mode is not for you.  Also this mode is not
@@ -66,24 +71,24 @@ new default).
 
 --
 
-push.followTags::
+`push.followTags`::
 	If set to true, enable `--follow-tags` option by default.  You
 	may override this configuration at time of push by specifying
 	`--no-follow-tags`.
 
-push.gpgSign::
-	May be set to a boolean value, or the string 'if-asked'. A true
+`push.gpgSign`::
+	May be set to a boolean value, or the string `if-asked`. A true
 	value causes all pushes to be GPG signed, as if `--signed` is
-	passed to linkgit:git-push[1]. The string 'if-asked' causes
+	passed to linkgit:git-push[1]. The string `if-asked` causes
 	pushes to be signed if the server supports it, as if
-	`--signed=if-asked` is passed to 'git push'. A false value may
+	`--signed=if-asked` is passed to `git push`. A false value may
 	override a value from a lower-priority config file. An explicit
 	command-line flag always overrides this config option.
 
-push.pushOption::
+`push.pushOption`::
 	When no `--push-option=<option>` argument is given from the
-	command line, `git push` behaves as if each <value> of
-	this variable is given as `--push-option=<value>`.
+	command line, `git push` behaves as if each _<option>_ of
+	this variable is given as `--push-option=<option>`.
 +
 This is a multi-valued variable, and an empty value can be used in a
 higher priority configuration file (e.g. `.git/config` in a
@@ -109,26 +114,26 @@ This will result in only b (a and c are cleared).
 
 ----
 
-push.recurseSubmodules::
-	May be "check", "on-demand", "only", or "no", with the same behavior
-	as that of "push --recurse-submodules".
-	If not set, 'no' is used by default, unless 'submodule.recurse' is
-	set (in which case a 'true' value means 'on-demand').
+`push.recurseSubmodules`::
+	May be `check`, `on-demand`, `only`, or `no`, with the same behavior
+	as that of `push --recurse-submodules`.
+	If not set, `no` is used by default, unless `submodule.recurse` is
+	set (in which case a `true` value means `on-demand`).
 
-push.useForceIfIncludes::
-	If set to "true", it is equivalent to specifying
+`push.useForceIfIncludes`::
+	If set to `true`, it is equivalent to specifying
 	`--force-if-includes` as an option to linkgit:git-push[1]
 	in the command line. Adding `--no-force-if-includes` at the
 	time of push overrides this configuration setting.
 
-push.negotiate::
-	If set to "true", attempt to reduce the size of the packfile
+`push.negotiate`::
+	If set to `true`, attempt to reduce the size of the packfile
 	sent by rounds of negotiation in which the client and the
-	server attempt to find commits in common. If "false", Git will
+	server attempt to find commits in common. If `false`, Git will
 	rely solely on the server's ref advertisement to find commits
 	in common.
 
-push.useBitmaps::
-	If set to "false", disable use of bitmaps for "git push" even if
-	`pack.useBitmaps` is "true", without preventing other git operations
-	from using bitmaps. Default is true.
+`push.useBitmaps`::
+	If set to `false`, disable use of bitmaps for `git push` even if
+	`pack.useBitmaps` is `true`, without preventing other git operations
+	from using bitmaps. Default is `true`.