@matheusbsbs / matheus-bagliano / commits / a0c3244796

doc SYNOPSIS & -h: use "-" to separate words in labels, not "_"

Change "builtin/credential-cache--daemon.c" to use "<socket-path>" not "<socket_path>" in a placeholder label, almost all of our documentation uses this form. This is now consistent with the "If a placeholder has multiple words, they are separated by dashes" guideline added in 9c9b4f2f8b7 (standardize usage info string format, 2015-01-13), let's add a now-passing test to assert that that's the case. To do this we need to introduce a very sed-powered parser to extract the SYNOPSIS from the *.txt, and handle not all commands with "-h" having a corresponding *.txt (e.g. "bisect--helper"). We'll still want to handle syntax edge cases in the *.txt in subsequent commits for other checks, but let's do that then. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Ævar Arnfjörð Bjarmason committed Oct 13, 2022 at 17:39 UTC a0c3244796e22c54f247b0685067b7d204c62f0f
2 files changed +47 -1
builtin/credential-cache--daemon.c
+1 -1
@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
267 const char *socket_path;
268 int ignore_sighup = 0;
269 static const char *usage[] = {
270 - "git-credential-cache--daemon [opts] <socket_path>",
270 + "git-credential-cache--daemon [opts] <socket-path>",
271 NULL
272 };
273 int debug = 0;
t/t0450-txt-doc-vs-help.sh
+46
@@ -30,6 +30,35 @@ help_to_synopsis () {
30 echo "$out"
31 }
32
33 +builtin_to_txt () {
34 + echo "$GIT_BUILD_DIR/Documentation/git-$1.txt"
35 +}
36 +
37 +txt_to_synopsis () {
38 + builtin="$1" &&
39 + out_dir="out/$builtin" &&
40 + out="$out_dir/txt.synopsis" &&
41 + if test -f "$out"
42 + then
43 + echo "$out" &&
44 + return 0
45 + fi &&
46 + b2t="$(builtin_to_txt "$builtin")" &&
47 + sed -n \
48 + -e '/^\[verse\]$/,/^$/ {
49 + /^$/d;
50 + /^\[verse\]$/d;
51 +
52 + p;
53 + }' \
54 + <"$b2t" >"$out" &&
55 + echo "$out"
56 +}
57 +
58 +check_dashed_labels () {
59 + ! grep -E "<[^>_-]+_" "$1"
60 +}
61 +
62 HT=" "
63
64 while read builtin
@@ -39,6 +68,23 @@ do
68 h2s="$(help_to_synopsis "$builtin")" &&
69 ! grep "$HT" "$h2s"
70 '
71 +
72 + test_expect_success "$builtin -h output has dashed labels" '
73 + check_dashed_labels "$(help_to_synopsis "$builtin")"
74 + '
75 +
76 + txt="$(builtin_to_txt "$builtin")" &&
77 + preq="$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')" &&
78 +
79 + if test -f "$txt"
80 + then
81 + test_set_prereq "$preq"
82 + fi &&
83 +
84 + # *.txt output assertions
85 + test_expect_success "$preq" "$builtin *.txt SYNOPSIS has dashed labels" '
86 + check_dashed_labels "$(txt_to_synopsis "$builtin")"
87 + '
88 done <builtins
89
90 test_done