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

* ja/doc-lint-sections-and-synopsis:
  fixup! doc: check for absence of multiple terms in each entry of desc list
  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

Author: gitster

Documentation/Makefile

@@ -497,9 +497,26 @@ $(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.adoc
 	$(call mkdir_p_parent_template)
 	$(QUIET_GEN)$(PERL_PATH) lint-fsck-msgids.perl \
 		../fsck.h fsck-msgids.adoc $@
-
 lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS)
 
+## Lint: delimited sections
+LINT_DOCS_DELIMITED_SECTIONS = $(patsubst %.adoc,.build/lint-docs/delimited-sections/%.ok,$(MAN_TXT))
+$(LINT_DOCS_DELIMITED_SECTIONS): lint-delimited-sections.perl
+$(LINT_DOCS_DELIMITED_SECTIONS): .build/lint-docs/delimited-sections/%.ok: %.adoc
+	$(call mkdir_p_parent_template)
+	$(QUIET_LINT_DELIMSEC)$(PERL_PATH) lint-delimited-sections.perl $< >$@
+.PHONY: lint-docs-delimited-sections
+lint-docs-delimited-sections: $(LINT_DOCS_DELIMITED_SECTIONS)
+
+## Lint: Documentation style
+LINT_DOCS_DOC_STYLE = $(patsubst %.adoc,.build/lint-docs/doc-style/%.ok,$(MAN_TXT))
+$(LINT_DOCS_DOC_STYLE): lint-documentation-style.perl
+$(LINT_DOCS_DOC_STYLE): .build/lint-docs/doc-style/%.ok: %.adoc
+	$(call mkdir_p_parent_template)
+	$(QUIET_LINT_DOCSTYLE)$(PERL_PATH) lint-documentation-style.perl $< >$@
+.PHONY: lint-docs-doc-style
+lint-docs-doc-style: $(LINT_DOCS_DOC_STYLE)
+
 lint-docs-manpages:
 	$(QUIET_GEN)./lint-manpages.sh
 
@@ -528,6 +545,8 @@ lint-docs: lint-docs-fsck-msgids
 lint-docs: lint-docs-gitlink
 lint-docs: lint-docs-man-end-blurb
 lint-docs: lint-docs-man-section-order
+lint-docs: lint-docs-delimited-sections
+lint-docs: lint-docs-doc-style
 lint-docs: lint-docs-manpages
 lint-docs: lint-docs-meson
 

Documentation/RelNotes/1.6.2.4.adoc

@@ -37,3 +37,4 @@ exec >/var/tmp/1
 echo O=$(git describe maint)
 O=v1.6.2.3-38-g318b847
 git shortlog --no-merges $O..maint
+---

Documentation/blame-options.adoc

@@ -75,7 +75,8 @@ include::line-range-format.adoc[]
 	iso format is used. For supported values, see the discussion
 	of the --date option at linkgit:git-log[1].
 
---[no-]progress::
+--progress::
+--no-progress::
 	Progress status is reported on the standard error stream
 	by default when it is attached to a terminal. This flag
 	enables progress reporting even if not attached to a

Documentation/diff-format.adoc

@@ -103,6 +103,7 @@ if the file was renamed on any side of history.  With
 followed by the name of the path in the merge commit.
 
 Examples for `-c` and `--cc` without `--combined-all-paths`:
+
 ------------------------------------------------
 ::100644 100644 100644 fabadb8 cc95eb0 4866510 MM	desc.c
 ::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM	bar.sh

Documentation/diff-options.adoc

@@ -505,7 +505,8 @@ endif::git-format-patch[]
 	Turn off rename detection, even when the configuration
 	file gives the default to do so.
 
-`--[no-]rename-empty`::
+`--rename-empty`::
+`--no-rename-empty`::
 	Whether to use empty blobs as rename source.
 
 ifndef::git-format-patch[]

Documentation/fetch-options.adoc

@@ -1,4 +1,5 @@
---[no-]all::
+--all::
+--no-all::
 	Fetch all remotes, except for the ones that has the
 	`remote.<name>.skipFetchAll` configuration variable set.
 	This overrides the configuration variable fetch.all`.
@@ -88,7 +89,8 @@ This is incompatible with `--recurse-submodules=[yes|on-demand]` and takes
 precedence over the `fetch.output` config option.
 
 ifndef::git-pull[]
---[no-]write-fetch-head::
+--write-fetch-head::
+--no-write-fetch-head::
 	Write the list of remote refs fetched in the `FETCH_HEAD`
 	file directly under `$GIT_DIR`.  This is the default.
 	Passing `--no-write-fetch-head` from the command line tells
@@ -118,13 +120,16 @@ ifndef::git-pull[]
 	Allow several <repository> and <group> arguments to be
 	specified. No <refspec>s may be specified.
 
---[no-]auto-maintenance::
---[no-]auto-gc::
+--auto-maintenance::
+--no-auto-maintenance::
+--auto-gc::
+--no-auto-gc::
 	Run `git maintenance run --auto` at the end to perform automatic
 	repository maintenance if needed. (`--[no-]auto-gc` is a synonym.)
 	This is enabled by default.
 
---[no-]write-commit-graph::
+--write-commit-graph::
+--no-write-commit-graph::
 	Write a commit-graph after fetching. This overrides the config
 	setting `fetch.writeCommitGraph`.
 endif::git-pull[]

Documentation/for-each-ref-options.adoc

@@ -1,84 +1,81 @@
-<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

Documentation/git-am.adoc

@@ -48,7 +48,8 @@ OPTIONS
 --keep-non-patch::
 	Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
 
---[no-]keep-cr::
+--keep-cr::
+--no-keep-cr::
 	With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1])
 	with the same option, to prevent it from stripping CR at the end of
 	lines. `am.keepcr` configuration variable can be used to specify the

Documentation/git-backfill.adoc

@@ -57,7 +57,8 @@ OPTIONS
 	blobs seen at a given path. The default minimum batch size is
 	50,000.
 
-`--[no-]sparse`::
+`--sparse`::
+`--no-sparse`::
 	Only download objects if they appear at a path that matches the
 	current sparse-checkout. If the sparse-checkout feature is enabled,
 	then `--sparse` is assumed and can be disabled with `--no-sparse`.

Documentation/git-cat-file.adoc

@@ -62,8 +62,10 @@ OPTIONS
 	or to ask for a "blob" with `<object>` being a tag object that
 	points at it.
 
---[no-]mailmap::
---[no-]use-mailmap::
+--mailmap::
+--no-mailmap::
+--use-mailmap::
+--no-use-mailmap::
        Use mailmap file to map author, committer and tagger names
        and email addresses to canonical real names and email addresses.
        See linkgit:git-shortlog[1].