Merge branch 'ja/doc-lint-sections-and-synopsis'

Doc lint updates to encourage the newer and easier-to-use
`synopsis` format, with fixes to a handful of existing uses.

* ja/doc-lint-sections-and-synopsis:
  doc lint: check that synopsis manpages have synopsis inlines
  doc:git-for-each-ref: fix styling and typos
  doc: check for absence of the form --[no-]parameter
  doc: check for absence of multiple terms in each entry of desc list
  doc: check well-formedness of delimited sections
  doc: test linkgit macros for well-formedness

1 files changed, 90 insertions, 87 deletions

diff --git a/Documentation/git-for-each-ref.adoc b/Documentation/git-for-each-ref.adoc
index 130d452de0..c02cb7f886 100644
--- a/Documentation/git-for-each-ref.adoc
+++ b/Documentation/git-for-each-ref.adoc
@@ -14,15 +14,15 @@ git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl]
 		   [--merged[=<object>]] [--no-merged[=<object>]]
 		   [--contains[=<object>]] [--no-contains[=<object>]]
 		   [(--exclude=<pattern>)...] [--start-after=<marker>]
-		   [ --stdin | <pattern>... ]
+		   [ --stdin | (<pattern>...)]
 
 DESCRIPTION
 -----------
 
-Iterate over all refs that match `<pattern>` and show them
-according to the given `<format>`, after sorting them according
-to the given set of `<key>`.  If `<count>` is given, stop after
-showing that many refs.  The interpolated values in `<format>`
+Iterate over all refs that match _<pattern>_ and show them
+according to the given _<format>_, after sorting them according
+to the given set of _<key>_.  If _<count>_ is given, stop after
+showing that many refs.  The interpolated values in _<format>_
 can optionally be quoted as string literals in the specified
 host language allowing their direct evaluation in that language.
 
@@ -39,44 +39,44 @@ keys.
 
 For all objects, the following names can be used:
 
-refname::
-	The name of the ref (the part after $GIT_DIR/).
+`refname`::
+	The name of the ref (the part after `$GIT_DIR/`).
 	For a non-ambiguous short name of the ref append `:short`.
-	The option core.warnAmbiguousRefs is used to select the strict
-	abbreviation mode. If `lstrip=<N>` (`rstrip=<N>`) is appended, strips `<N>`
+	The option `core.warnAmbiguousRefs` is used to select the strict
+	abbreviation mode. If `lstrip=<n>` (`rstrip=<n>`) is appended, strip _<n>_
 	slash-separated path components from the front (back) of the refname
 	(e.g. `%(refname:lstrip=2)` turns `refs/tags/foo` into `foo` and
 	`%(refname:rstrip=2)` turns `refs/tags/foo` into `refs`).
-	If `<N>` is a negative number, strip as many path components as
-	necessary from the specified end to leave `-<N>` path components
+	If _<n>_ is a negative number, strip as many path components as
+	necessary from the specified end to leave `-<n>` path components
 	(e.g. `%(refname:lstrip=-2)` turns
 	`refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)`
 	turns `refs/tags/foo` into `refs`). When the ref does not have
 	enough components, the result becomes an empty string if
-	stripping with positive <N>, or it becomes the full refname if
-	stripping with negative <N>.  Neither is an error.
+	stripping with positive _<n>_, or it becomes the full refname if
+	stripping with negative _<N>_.  Neither is an error.
 +
 `strip` can be used as a synonym to `lstrip`.
 
-objecttype::
+`objecttype`::
 	The type of the object (`blob`, `tree`, `commit`, `tag`).
 
-objectsize::
+`objectsize`::
 	The size of the object (the same as 'git cat-file -s' reports).
 	Append `:disk` to get the size, in bytes, that the object takes up on
-	disk. See the note about on-disk sizes in the `CAVEATS` section below.
-objectname::
+	disk. See the note about on-disk sizes in the 'CAVEATS' section below.
+`objectname`::
 	The object name (aka SHA-1).
 	For a non-ambiguous abbreviation of the object name append `:short`.
 	For an abbreviation of the object name with desired length append
-	`:short=<length>`, where the minimum length is MINIMUM_ABBREV. The
+	`:short=<length>`, where the minimum length is `MINIMUM_ABBREV`. The
 	length may be exceeded to ensure unique object names.
-deltabase::
+`deltabase`::
 	This expands to the object name of the delta base for the
 	given object, if it is stored as a delta.  Otherwise it
 	expands to the null object name (all zeroes).
 
-upstream::
+`upstream`::
 	The name of a local ref which can be considered ``upstream''
 	from the displayed ref. Respects `:short`, `:lstrip` and
 	`:rstrip` in the same way as `refname` above.  Additionally
@@ -98,100 +98,103 @@ Has no effect if the ref does not have tracking information associated
 with it.  All the options apart from `nobracket` are mutually exclusive,
 but if used together the last option is selected.
 
-push::
+`push`::
 	The name of a local ref which represents the `@{push}`
 	location for the displayed ref. Respects `:short`, `:lstrip`,
 	`:rstrip`, `:track`, `:trackshort`, `:remotename`, and `:remoteref`
 	options as `upstream` does. Produces an empty string if no `@{push}`
 	ref is configured.
 
-HEAD::
-	'*' if HEAD matches current ref (the checked out branch), ' '
+`HEAD`::
+	`*` if `HEAD` matches current ref (the checked out branch), ' '
 	otherwise.
 
-color::
+`color`::
 	Change output color. Followed by `:<colorname>`, where color
 	names are described under Values in the "CONFIGURATION FILE"
 	section of linkgit:git-config[1].  For example,
 	`%(color:bold red)`.
 
-align::
+`align`::
 	Left-, middle-, or right-align the content between
-	%(align:...) and %(end). The "align:" is followed by
+	`%(align:...)` and `%(end)`. The "`align:`" is followed by
 	`width=<width>` and `position=<position>` in any order
-	separated by a comma, where the `<position>` is either left,
-	right or middle, default being left and `<width>` is the total
+	separated by a comma, where the _<position>_ is either `left`,
+	`right` or `middle`, default being `left` and _<width>_ is the total
 	length of the content with alignment. For brevity, the
 	"width=" and/or "position=" prefixes may be omitted, and bare
-	<width> and <position> used instead.  For instance,
+	_<width>_ and _<position>_ used instead.  For instance,
 	`%(align:<width>,<position>)`. If the contents length is more
 	than the width then no alignment is performed. If used with
-	`--quote` everything in between %(align:...) and %(end) is
+	`--quote` everything in between `%(align:...)` and `%(end)` is
 	quoted, but if nested then only the topmost level performs
 	quoting.
 
-if::
-	Used as %(if)...%(then)...%(end) or
-	%(if)...%(then)...%(else)...%(end).  If there is an atom with
-	value or string literal after the %(if) then everything after
-	the %(then) is printed, else if the %(else) atom is used, then
+`if`::
+	Used as `%(if)...%(then)...%(end)` or
+	`%(if)...%(then)...%(else)...%(end)`.  If there is an atom with
+	value or string literal after the `%(if)` then everything after
+	the `%(then)` is printed, else if the `%(else)` atom is used, then
 	everything after %(else) is printed. We ignore space when
-	evaluating the string before %(then), this is useful when we
-	use the %(HEAD) atom which prints either "*" or " " and we
-	want to apply the 'if' condition only on the 'HEAD' ref.
-	Append ":equals=<string>" or ":notequals=<string>" to compare
-	the value between the %(if:...) and %(then) atoms with the
+	evaluating the string before `%(then)`, this is useful when we
+	use the `%(HEAD)` atom which prints either "`*`" or " " and we
+	want to apply the 'if' condition only on the `HEAD` ref.
+	Append "`:equals=<string>`" or "`:notequals=<string>`" to compare
+	the value between the `%(if:...)` and `%(then)` atoms with the
 	given string.
 
-symref::
+`symref`::
 	The ref which the given symbolic ref refers to. If not a
 	symbolic ref, nothing is printed. Respects the `:short`,
 	`:lstrip` and `:rstrip` options in the same way as `refname`
 	above.
 
-signature::
+`signature`::
 	The GPG signature of a commit.
 
-signature:grade::
-	Show "G" for a good (valid) signature, "B" for a bad
-	signature, "U" for a good signature with unknown validity, "X"
-	for a good signature that has expired, "Y" for a good
-	signature made by an expired key, "R" for a good signature
-	made by a revoked key, "E" if the signature cannot be
-	checked (e.g. missing key) and "N" for no signature.
+`signature:grade`::
+	Show
+`G`;; for a good (valid) signature
+`B`;; for a bad signature
+`U`;; for a good signature with unknown validity
+`X`;;	for a good signature that has expired
+`Y`;; for a good signature made by an expired key
+`R`;; for a good signature made by a revoked key
+`E`;; if the signature cannot be checked (e.g. missing key)
+`N`;; for no signature.
 
-signature:signer::
+`signature:signer`::
 	The signer of the GPG signature of a commit.
 
-signature:key::
+`signature:key`::
 	The key of the GPG signature of a commit.
 
-signature:fingerprint::
+`signature:fingerprint`::
 	The fingerprint of the GPG signature of a commit.
 
-signature:primarykeyfingerprint::
+`signature:primarykeyfingerprint`::
 	The primary key fingerprint of the GPG signature of a commit.
 
-signature:trustlevel::
+`signature:trustlevel`::
 	The trust level of the GPG signature of a commit. Possible
 	outputs are `ultimate`, `fully`, `marginal`, `never` and `undefined`.
 
-worktreepath::
+`worktreepath`::
 	The absolute path to the worktree in which the ref is checked
 	out, if it is checked out in any linked worktree. Empty string
 	otherwise.
 
-ahead-behind:<committish>::
+`ahead-behind:<commit-ish>`::
 	Two integers, separated by a space, demonstrating the number of
 	commits ahead and behind, respectively, when comparing the output
-	ref to the `<committish>` specified in the format.
+	ref to the _<committish>_ specified in the format.
 
-is-base:<committish>::
-	In at most one row, `(<committish>)` will appear to indicate the ref
+`is-base:<commit-ish>`::
+	In at most one row, `(<commit-ish>)` will appear to indicate the ref
 	that is most likely the ref used as a starting point for the branch
-	that produced `<committish>`. This choice is made using a heuristic:
+	that produced _<commit-ish>_. This choice is made using a heuristic:
 	choose the ref that minimizes the number of commits in the
-	first-parent history of `<committish>` and not in the first-parent
+	first-parent history of _<commit-ish>_ and not in the first-parent
 	history of the ref.
 +
 For example, consider the following figure of first-parent histories of
@@ -225,29 +228,29 @@ common first-parent ancestor of `B` and `C` and ties are broken by the
 earliest ref in the sorted order.
 +
 Note that this token will not appear if the first-parent history of
-`<committish>` does not intersect the first-parent histories of the
+_<commit-ish>_ does not intersect the first-parent histories of the
 filtered refs.
 
-describe[:options]::
+`describe[:<option>,...]`::
 	A human-readable name, like linkgit:git-describe[1];
 	empty string for undescribable commits. The `describe` string may
 	be followed by a colon and one or more comma-separated options.
 +
 --
-tags=<bool-value>;;
+`tags=<bool-value>`;;
 	Instead of only considering annotated tags, consider
 	lightweight tags as well; see the corresponding option in
 	linkgit:git-describe[1] for details.
-abbrev=<number>;;
-	Use at least <number> hexadecimal digits; see the corresponding
+`abbrev=<number>`;;
+	Use at least _<number>_ hexadecimal digits; see the corresponding
 	option in linkgit:git-describe[1] for details.
-match=<pattern>;;
-	Only consider tags matching the given `glob(7)` pattern,
-	excluding the "refs/tags/" prefix; see the corresponding option
+`match=<pattern>`;;
+	Only consider tags matching the `glob`(7) _<pattern>_,
+	excluding the `refs/tags/` prefix; see the corresponding option
 	in linkgit:git-describe[1] for details.
-exclude=<pattern>;;
-	Do not consider tags matching the given `glob(7)` pattern,
-	excluding the "refs/tags/" prefix; see the corresponding option
+`exclude=<pattern>`;;
+	Do not consider tags matching the `glob`(7) _<pattern>_,
+	excluding the `refs/tags/` prefix; see the corresponding option
 	in linkgit:git-describe[1] for details.
 --
 
@@ -279,7 +282,7 @@ variable (see linkgit:gitmailmap[5]).
 
 The raw data in an object is `raw`.
 
-raw:size::
+`raw:size`::
 	The raw data size of the object.
 
 Note that `--format=%(raw)` can not be used with `--python`, `--shell`, `--tcl`,
@@ -289,10 +292,10 @@ variable type.
 The message in a commit or a tag object is `contents`, from which
 `contents:<part>` can be used to extract various parts out of:
 
-contents:size::
+`contents:size`::
 	The size in bytes of the commit or tag message.
 
-contents:subject::
+`contents:subject`::
 	The first paragraph of the message, which typically is a
 	single line, is taken as the "subject" of the commit or the
 	tag message.
@@ -300,19 +303,19 @@ contents:subject::
 	obtain same results. `:sanitize` can be appended to `subject` for
 	subject line suitable for filename.
 
-contents:body::
+`contents:body`::
 	The remainder of the commit or the tag message that follows
 	the "subject".
 
-contents:signature::
+`contents:signature`::
 	The optional GPG signature of the tag.
 
-contents:lines=N::
-	The first `N` lines of the message.
+`contents:lines=<n>`::
+	The first _<n>_ lines of the message.
 
 Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1]
-are obtained as `trailers[:options]` (or by using the historical alias
-`contents:trailers[:options]`). For valid [:option] values see `trailers`
+are obtained as `trailers[:<option>,...]` (or by using the historical alias
+`contents:trailers[:<option>,...]`). For valid _<option>_ values see `trailers`
 section of linkgit:git-log[1].
 
 For sorting purposes, fields with numeric values sort in numeric order
@@ -332,8 +335,8 @@ option to linkgit:git-rev-list[1] takes). If this formatting is provided in
 a `--sort` key, references will be sorted according to the byte-value of the
 formatted string rather than the numeric value of the underlying timestamp.
 
-Some atoms like %(align) and %(if) always require a matching %(end).
-We call them "opening atoms" and sometimes denote them as %($open).
+Some atoms like `%(align)` and `%(if)` always require a matching `%(end)`.
+We call them "opening atoms" and sometimes denote them as `%($open)`.
 
 When a scripting language specific quoting is in effect, everything
 between a top-level opening atom and its matching %(end) is evaluated
@@ -351,7 +354,7 @@ An example directly producing formatted text.  Show the most recent
 #!/bin/sh
 
 git for-each-ref --count=3 --sort='-*authordate' \
---format='From: %(*authorname) %(*authoremail)
+`--format='From: %(*authorname) %(*authoremail)
 Subject: %(*subject)
 Date: %(*authordate)
 Ref: %(*refname)
@@ -362,7 +365,7 @@ Ref: %(*refname)
 
 
 A simple example showing the use of shell eval on the output,
-demonstrating the use of --shell.  List the prefixes of all heads:
+demonstrating the use of `--shell`.  List the prefixes of all heads:
 
 ------------
 #!/bin/sh
@@ -430,7 +433,7 @@ eval "$eval"
 ------------
 
 
-An example to show the usage of %(if)...%(then)...%(else)...%(end).
+An example to show the usage of `%(if)...%(then)...%(else)...%(end)`.
 This prefixes the current branch with a star.
 
 ------------
@@ -438,7 +441,7 @@ git for-each-ref --format="%(if)%(HEAD)%(then)* %(else)  %(end)%(refname:short)"
 ------------
 
 
-An example to show the usage of %(if)...%(then)...%(end).
+An example to show the usage of `%(if)...%(then)...%(end)`.
 This prints the authorname, if present.
 
 ------------