doc: check for absence of multiple terms in each entry of desc list

For simplifying automated translation of the documentation, it is better to
only present one term in each entry of a description list of options. This
is because most of these terms can automatically be marked as
notranslatable.

Also, due to portability issues, the script generate-configlist.sh can no
longer insert newlines in the output. However, the result is that it no
longer correctly handles multiple terms in a single entry of definition
lists.

As a result, we now check that these entries do not exist in the
documentation.

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

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 76a9e1d02b2643930aa4fef3975178b495e55404..6fb83d0c6ebf22067271718b644d82265161e723 100644 (file)
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -508,6 +508,15 @@ $(LINT_DOCS_DELIMITED_SECTIONS): .build/lint-docs/delimited-sections/%.ok: %.ado
 .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,$(DOC_DEP_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
 
@@ -537,6 +546,7 @@ 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
 

diff --git a/Documentation/git-check-attr.adoc b/Documentation/git-check-attr.adoc
index 503b6446574d18cea9aea0cb4303a1d0464bf862..15a37a38e3f7ff9f4e5a3ce408f4faebd76bc034 100644 (file)
--- a/Documentation/git-check-attr.adoc
+++ b/Documentation/git-check-attr.adoc
@@ -19,7 +19,8 @@ For every pathname, this command will list if each attribute is 'unspecified',
 
 OPTIONS
 -------
--a, --all::
+-a::
+--all::
        List all attributes that are associated with the specified
        paths.  If this option is used, then 'unspecified' attributes
        will not be included in the output.

diff --git a/Documentation/git-check-ignore.adoc b/Documentation/git-check-ignore.adoc
index 3e3b4e344629d951e7318dace83f38d5752fc76c..a6c6c1b6e5bee8bbeb8b951359289b3867f94f8c 100644 (file)
--- a/Documentation/git-check-ignore.adoc
+++ b/Documentation/git-check-ignore.adoc
@@ -25,11 +25,13 @@ subject to exclude rules; but see `--no-index'.
 
 OPTIONS
 -------
--q, --quiet::
+-q::
+--quiet::
        Don't output anything, just set exit status.  This is only
        valid with a single pathname.
 
--v, --verbose::
+-v::
+--verbose::
        Instead of printing the paths that are excluded, for each path
        that matches an exclude pattern, print the exclude pattern
        together with the path.  (Matching an exclude pattern usually
@@ -49,7 +51,8 @@ linkgit:gitignore[5].
        below).  If `--stdin` is also given, input paths are separated
        with a NUL character instead of a linefeed character.
 
--n, --non-matching::
+-n::
+--non-matching::
        Show given paths which don't match any pattern.  This only
        makes sense when `--verbose` is enabled, otherwise it would
        not be possible to distinguish between paths which match a

diff --git a/Documentation/git-http-fetch.adoc b/Documentation/git-http-fetch.adoc
index 4ec7c68d3b9ecd18b3358563c2c1de4addff6eb0..2200f073c47120c180f94b47c4434c7689b99c6c 100644 (file)
--- a/Documentation/git-http-fetch.adoc
+++ b/Documentation/git-http-fetch.adoc
@@ -25,8 +25,11 @@ commit-id::
         Either the hash or the filename under [URL]/refs/ to
         pull.
 
--a, -c, -t::
+-a::
+-c::
+-t::
        These options are ignored for historical reasons.
+
 -v::
        Report what is downloaded.
 

diff --git a/Documentation/lint-documentation-style.perl b/Documentation/lint-documentation-style.perl
new file mode 100755 (executable)
index 0000000..1f35a6a
--- /dev/null
+++ b/Documentation/lint-documentation-style.perl
@@ -0,0 +1,24 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+
+my $exit_code = 0;
+sub report {
+       my ($line, $msg) = @_;
+       chomp $line;
+       print STDERR "$ARGV:$.: '$line' $msg\n";
+       $exit_code = 1;
+}
+
+my $synopsis_style = 0;
+
+while (my $line = <>) {
+       if ($line =~ /^[ \t]*`?[-a-z0-9.]+`?(, `?[-a-z0-9.]+`?)+(::|;;)$/) {
+
+               report($line, "multiple parameters in a definition list item");
+       }
+}
+
+
+exit $exit_code;

diff --git a/Documentation/technical/api-path-walk.adoc b/Documentation/technical/api-path-walk.adoc
index 34c905eb9c313080fb3dd5f7c2be67adc9cfb90d..a67de1b143ab5b81c72275130e931fa63745106b 100644 (file)
--- a/Documentation/technical/api-path-walk.adoc
+++ b/Documentation/technical/api-path-walk.adoc
@@ -39,7 +39,10 @@ It is also important that you do not specify the `--objects` flag for the
 the objects will be walked in a separate way based on those starting
 commits.
 
-`commits`, `blobs`, `trees`, `tags`::
+`commits`::
+`blobs`::
+`trees`::
+`tags`::
        By default, these members are enabled and signal that the path-walk
        API should call the `path_fn` on objects of these types. Specialized
        applications could disable some options to make it simpler to walk

diff --git a/shared.mak b/shared.mak
index 57095d6cf96c1271a79efadea9c4013f6d66d58b..5c7bc9478544c8354daacbc7a131de653faaada6 100644 (file)
--- a/shared.mak
+++ b/shared.mak
@@ -89,6 +89,7 @@ ifndef V
        QUIET_LINT_GITLINK      = @echo '   ' LINT GITLINK $<;
        QUIET_LINT_MANSEC       = @echo '   ' LINT MAN SEC $<;
        QUIET_LINT_DELIMSEC     = @echo '   ' LINT DEL SEC $<;
+       QUIET_LINT_DOCSTYLE     = @echo '   ' LINT DOCSTYLE $<;
        QUIET_LINT_MANEND       = @echo '   ' LINT MAN END $<;
 
        export V