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

diff --cc Documentation/diff-options.adoc
Simple merge

diff --cc Documentation/for-each-ref-options.adoc
index 4a033d3e1618db0145b6c56cb44703b45e716531,0000000000000000000000000000000000000000..f13efb5f2556cf8c02b76e9580b7e4d4cf1a9855
mode 100644,000000..100644
--- 1/Documentation/for-each-ref-options.adoc
--- /dev/null
+++ b/Documentation/for-each-ref-options.adoc
@@@ -1,88 -1,0 +1,85 @@@
- <pattern>...::
-       If one or more patterns are given, only refs are shown that
-       match against at least one pattern, either using fnmatch(3) or
++`<pattern>...`::
++      If one or more _<pattern>_ parameters are given, only refs are shown that
++      match against at least one pattern, either using `fnmatch`(3) or
 +      literally, in the latter case matching completely or from the
 +      beginning up to a slash.
 +
- --stdin::
-       If `--stdin` is supplied, then the list of patterns is read from
-       standard input instead of from the argument list.
++`--stdin`::
++      The list of patterns is read from standard input instead of from
++      the argument list.
 +
- --count=<count>::
-       By default the command shows all refs that match
-       `<pattern>`.  This option makes it stop after showing
-       that many refs.
++`--count=<count>`::
++      Stop after showing _<count>_ refs.
 +
- --sort=<key>::
-       A field name to sort on.  Prefix `-` to sort in
++`--sort=<key>`::
++      Sort on the field name _<key>_.  Prefix `-` to sort in
 +      descending order of the value.  When unspecified,
-       `refname` is used.  You may use the --sort=<key> option
++      `refname` is used.  You may use the `--sort=<key>` option
 +      multiple times, in which case the last key becomes the primary
 +      key.
 +
- --format=<format>::
++`--format[=<format>]`::
 +      A string that interpolates `%(fieldname)` from a ref being shown and
 +      the object it points at. In addition, the string literal `%%`
 +      renders as `%` and `%xx` - where `xx` are hex digits - renders as
 +      the character with hex code `xx`. For example, `%00` interpolates to
-       `\0` (NUL), `%09` to `\t` (TAB), and `%0a` to `\n` (LF).
- +
- When unspecified, `<format>` defaults to `%(objectname) SPC %(objecttype)
++      `\0` (_NUL_), `%09` to `\t` (_TAB_), and `%0a` to `\n` (_LF_).
++
++When unspecified, _<format>_ defaults to `%(objectname) SPC %(objecttype)
 +TAB %(refname)`.
 +
- --color[=<when>]::
++`--color[=<when>]`::
 +      Respect any colors specified in the `--format` option. The
-       `<when>` field must be one of `always`, `never`, or `auto` (if
++      _<when__ field must be one of `always`, `never`, or `auto` (if
 +      `<when>` is absent, behave as if `always` was given).
 +
- --shell::
- --perl::
- --python::
- --tcl::
++`--shell`::
++`--perl`::
++`--python`::
++`--tcl`::
 +      If given, strings that substitute `%(fieldname)`
 +      placeholders are quoted as string literals suitable for
 +      the specified host language.  This is meant to produce
-       a scriptlet that can directly be `eval`ed.
++      a scriptlet that can directly be "eval"ed.
 +
- --points-at=<object>::
++`--points-at=<object>`::
 +      Only list refs which points at the given object.
 +
- --merged[=<object>]::
++`--merged[=<object>]`::
 +      Only list refs whose tips are reachable from the
-       specified commit (HEAD if not specified).
- 
- --no-merged[=<object>]::
-       Only list refs whose tips are not reachable from the
-       specified commit (HEAD if not specified).
++      specified commit (`HEAD` if not specified).
 +
- --contains[=<object>]::
-       Only list refs which contain the specified commit (HEAD if not
++`--no-merged[=<object>]`::
++      Only list refs whose tips are not reachable from _<object>_(`HEAD` if not
 +      specified).
 +
- --no-contains[=<object>]::
-       Only list refs which don't contain the specified commit (HEAD
++`--contains[=<object>]`::
++      Only list refs which contain _<object>_(`HEAD` if not specified).
++
++`--no-contains[=<object>]`::
++      Only list refs which don't contain _<object>_ (`HEAD`
 +      if not specified).
 +
- --ignore-case::
++`--ignore-case`::
 +      Sorting and filtering refs are case insensitive.
 +
- --omit-empty::
++`--omit-empty`::
 +      Do not print a newline after formatted refs where the format expands
 +      to the empty string.
 +
- --exclude=<pattern>::
-       If one or more patterns are given, only refs which do not match
-       any excluded pattern(s) are shown. Matching is done using the
-       same rules as `<pattern>` above.
++`--exclude=<excluded-pattern>`::
++      If one or more `--exclude` options are given, only refs which do not
++      match any _<excluded-pattern>_ parameters are shown. Matching is done
++      using the same rules as _<pattern>_ above.
 +
- --include-root-refs::
-       List root refs (HEAD and pseudorefs) apart from regular refs.
++`--include-root-refs`::
++      List root refs (`HEAD` and pseudorefs) apart from regular refs.
 +
- --start-after=<marker>::
++`--start-after=<marker>`::
 +    Allows paginating the output by skipping references up to and including the
 +    specified marker. When paging, it should be noted that references may be
 +    deleted, modified or added between invocations. Output will only yield those
 +    references which follow the marker lexicographically. Output begins from the
 +    first reference that would come after the marker alphabetically. Cannot be
 +    used with `--sort=<key>` or `--stdin` options, or the _<pattern>_ argument(s)
 +    to limit the refs.

diff --cc Documentation/git-clone.adoc
Simple merge

diff --cc Documentation/git-for-each-ref.adoc
Simple merge

diff --cc Documentation/git-refs.adoc
index e608980711814ae4c7b186efdb4eb5a25cb8ae0a,5d26de8acb22aae216ea3e5bf55ec52a636e7c18..d462953fb5ee3a82ac8230b45a01861ecb6b93b2
--- 1/Documentation/git-refs.adoc
--- 2/Documentation/git-refs.adoc
+++ b/Documentation/git-refs.adoc
@@@ -11,13 -11,6 +11,13 @@@ SYNOPSI
  [synopsis]
  git refs migrate --ref-format=<format> [--no-reflog] [--dry-run]
  git refs verify [--strict] [--verbose]
-                  [ --stdin | <pattern>... ]
 +git refs list [--count=<count>] [--shell|--perl|--python|--tcl]
 +                 [(--sort=<key>)...] [--format=<format>]
 +                 [--include-root-refs] [--points-at=<object>]
 +                 [--merged[=<object>]] [--no-merged[=<object>]]
 +                 [--contains[=<object>]] [--no-contains[=<object>]]
 +                 [(--exclude=<pattern>)...] [--start-after=<marker>]
++                 [ --stdin | (<pattern>...)]
  
  DESCRIPTION
  -----------
@@@ -27,17 -20,12 +27,17 @@@ This command provides low-level access 
  COMMANDS
  --------
  
- migrate::
+ `migrate`::
        Migrate ref store between different formats.
  
- verify::
+ `verify`::
        Verify reference database consistency.
  
 +list::
 +      List references in the repository with support for filtering,
 +      formatting, and sorting. This subcommand is an alias for
 +      linkgit:git-for-each-ref[1] and offers identical functionality.
 +
  OPTIONS
  -------
  
@@@ -66,13 -54,9 +66,13 @@@ The following options are specific to `
        Enable stricter error checking. This will cause warnings to be
        reported as errors. See linkgit:git-fsck[1].
  
- --verbose::
+ `--verbose`::
        When verifying the reference database consistency, be chatty.
  
 +The following options are specific to 'git refs list':
 +
 +include::for-each-ref-options.adoc[]
 +
  KNOWN LIMITATIONS
  -----------------
  

diff --cc Documentation/git-submodule.adoc
Simple merge

diff --cc for-each-ref.h
index a5e0b6d17aa0d6525b86ee5a2d27a7e029ac12bc,0000000000000000000000000000000000000000..c8d021917953cd4b6fb96cd3c381c81a5f74759c
mode 100644,000000..100644
--- 1/for-each-ref.h
--- /dev/null
+++ b/for-each-ref.h
@@@ -1,26 -1,0 +1,26 @@@
-       "                         [ --stdin | <pattern>... ]"
 +#ifndef FOR_EACH_REF_H
 +#define FOR_EACH_REF_H
 +
 +struct repository;
 +
 +/*
 + * Shared usage string for options common to git-for-each-ref(1)
 + * and git-refs-list(1). The command-specific part (e.g., "git refs list ")
 + * must be prepended by the caller.
 + */
 +#define COMMON_USAGE_FOR_EACH_REF \
 +      "[--count=<count>] [--shell|--perl|--python|--tcl]\n" \
 +      "                         [(--sort=<key>)...] [--format=<format>]\n" \
 +      "                         [--include-root-refs] [--points-at=<object>]\n" \
 +      "                         [--merged[=<object>]] [--no-merged[=<object>]]\n" \
 +      "                         [--contains[=<object>]] [--no-contains[=<object>]]\n" \
 +      "                         [(--exclude=<pattern>)...] [--start-after=<marker>]\n" \
++      "                         [ --stdin | (<pattern>...)]"
 +
 +/*
 + * The core logic for for-each-ref and its clones.
 + */
 +int for_each_ref_core(int argc, const char **argv, const char *prefix,
 +                    struct repository *repo, const char *const *usage);
 +
 +#endif /* FOR_EACH_REF_H */