From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@xxxxxxx>
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@xxxxxxxxx>
Signed-off-by: Jean-Noël Avila <jn.avila@xxxxxxx>
---
Documentation/Makefile | 10 +++++++++
Documentation/git-check-attr.adoc | 3 ++-
Documentation/git-check-ignore.adoc | 9 +++++---
Documentation/git-http-fetch.adoc | 5 ++++-
Documentation/lint-documentation-style.perl | 24 +++++++++++++++++++++
Documentation/technical/api-path-walk.adoc | 5 ++++-
shared.mak | 1 +
7 files changed, 51 insertions(+), 6 deletions(-)
create mode 100755 Documentation/lint-documentation-style.perl
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 76a9e1d02b26..6fb83d0c6ebf 100644
--- 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 503b6446574d..15a37a38e3f7 100644
--- 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 3e3b4e344629..a6c6c1b6e5be 100644
--- 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 4ec7c68d3b9e..2200f073c471 100644
--- 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
index 000000000000..1f35a6a116da
--- /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 34c905eb9c31..a67de1b143ab 100644
--- 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 57095d6cf96c..5c7bc9478544 100644
--- 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
--
gitgitgadget
