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>
Jean-Noël Avila committed
Aug 11, 2025 at 20:53 UTC
ed260220948595b1311d4639dbfc20f02c807fac
7 files changed
+51
-6
Documentation/Makefile
+10
@@ -508,6 +508,15 @@ $(LINT_DOCS_DELIMITED_SECTIONS): .build/lint-docs/delimited-sections/%.ok: %.ado
508
.PHONY: lint-docs-delimited-sections
509
lint-docs-delimited-sections: $(LINT_DOCS_DELIMITED_SECTIONS)
510
511
+## Lint: Documentation style
512
+LINT_DOCS_DOC_STYLE = $(patsubst %.adoc,.build/lint-docs/doc-style/%.ok,$(DOC_DEP_TXT))
513
+$(LINT_DOCS_DOC_STYLE): lint-documentation-style.perl
514
+$(LINT_DOCS_DOC_STYLE): .build/lint-docs/doc-style/%.ok: %.adoc
515
+ $(call mkdir_p_parent_template)
516
+ $(QUIET_LINT_DOCSTYLE)$(PERL_PATH) lint-documentation-style.perl $< >$@
517
+.PHONY: lint-docs-doc-style
518
+lint-docs-doc-style: $(LINT_DOCS_DOC_STYLE)
519
+
520
lint-docs-manpages:
521
$(QUIET_GEN)./lint-manpages.sh
522
@@ -537,6 +546,7 @@ lint-docs: lint-docs-gitlink
546
lint-docs: lint-docs-man-end-blurb
547
lint-docs: lint-docs-man-section-order
548
lint-docs: lint-docs-delimited-sections
549
+lint-docs: lint-docs-doc-style
550
lint-docs: lint-docs-manpages
551
lint-docs: lint-docs-meson
552
Documentation/git-check-attr.adoc
+2
-1
@@ -19,7 +19,8 @@ For every pathname, this command will list if each attribute is 'unspecified',
19
20
OPTIONS
21
-------
22
--a, --all::
22
+-a::
23
+--all::
24
List all attributes that are associated with the specified
25
paths. If this option is used, then 'unspecified' attributes
26
will not be included in the output.
Documentation/git-check-ignore.adoc
+6
-3
@@ -25,11 +25,13 @@ subject to exclude rules; but see `--no-index'.
25
26
OPTIONS
27
-------
28
--q, --quiet::
28
+-q::
29
+--quiet::
30
Don't output anything, just set exit status. This is only
31
valid with a single pathname.
32
32
--v, --verbose::
33
+-v::
34
+--verbose::
35
Instead of printing the paths that are excluded, for each path
36
that matches an exclude pattern, print the exclude pattern
37
together with the path. (Matching an exclude pattern usually
@@ -49,7 +51,8 @@ linkgit:gitignore[5].
51
below). If `--stdin` is also given, input paths are separated
52
with a NUL character instead of a linefeed character.
53
52
--n, --non-matching::
54
+-n::
55
+--non-matching::
56
Show given paths which don't match any pattern. This only
57
makes sense when `--verbose` is enabled, otherwise it would
58
not be possible to distinguish between paths which match a
Documentation/git-http-fetch.adoc
+4
-1
@@ -25,8 +25,11 @@ commit-id::
25
Either the hash or the filename under [URL]/refs/ to
26
pull.
27
28
--a, -c, -t::
28
+-a::
29
+-c::
30
+-t::
31
These options are ignored for historical reasons.
32
+
33
-v::
34
Report what is downloaded.
35
Documentation/lint-documentation-style.perl
new
+24
@@ -0,0 +1,24 @@
1
+#!/usr/bin/perl
2
+
3
+use strict;
4
+use warnings;
5
+
6
+my $exit_code = 0;
7
+sub report {
8
+ my ($line, $msg) = @_;
9
+ chomp $line;
10
+ print STDERR "$ARGV:$.: '$line' $msg\n";
11
+ $exit_code = 1;
12
+}
13
+
14
+my $synopsis_style = 0;
15
+
16
+while (my $line = <>) {
17
+ if ($line =~ /^[ \t]*`?[-a-z0-9.]+`?(, `?[-a-z0-9.]+`?)+(::|;;)$/) {
18
+
19
+ report($line, "multiple parameters in a definition list item");
20
+ }
21
+}
22
+
23
+
24
+exit $exit_code;
Documentation/technical/api-path-walk.adoc
+4
-1
@@ -39,7 +39,10 @@ It is also important that you do not specify the `--objects` flag for the
39
the objects will be walked in a separate way based on those starting
40
commits.
41
42
-`commits`, `blobs`, `trees`, `tags`::
42
+`commits`::
43
+`blobs`::
44
+`trees`::
45
+`tags`::
46
By default, these members are enabled and signal that the path-walk
47
API should call the `path_fn` on objects of these types. Specialized
48
applications could disable some options to make it simpler to walk
shared.mak
+1
@@ -89,6 +89,7 @@ ifndef V
89
QUIET_LINT_GITLINK = @echo ' ' LINT GITLINK $<;
90
QUIET_LINT_MANSEC = @echo ' ' LINT MAN SEC $<;
91
QUIET_LINT_DELIMSEC = @echo ' ' LINT DEL SEC $<;
92
+ QUIET_LINT_DOCSTYLE = @echo ' ' LINT DOCSTYLE $<;
93
QUIET_LINT_MANEND = @echo ' ' LINT MAN END $<;
94
95
export V