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>

diff --git a/builtin/credential-cache--daemon.c b/builtin/credential-cache--daemon.c
index 4c6c89ab0de2eb3dbc2785033249e853aea32f16..ca672a6a61965918db26d6be206e8188623de457 100644 (file)
--- a/builtin/credential-cache--daemon.c
+++ b/builtin/credential-cache--daemon.c
@@ -267,7 +267,7 @@ int cmd_credential_cache_daemon(int argc, const char **argv, const char *prefix)
        const char *socket_path;
        int ignore_sighup = 0;
        static const char *usage[] = {
-               "git-credential-cache--daemon [opts] <socket_path>",
+               "git-credential-cache--daemon [opts] <socket-path>",
                NULL
        };
        int debug = 0;

diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
index c8820bdd38f2a12a2061c2906e0d28d73dc08233..efd00cfc51a1e98597e9b420bbf17bb4b1c6fc76 100755 (executable)
--- a/t/t0450-txt-doc-vs-help.sh
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -30,6 +30,35 @@ help_to_synopsis () {
        echo "$out"
 }
 
+builtin_to_txt () {
+       echo "$GIT_BUILD_DIR/Documentation/git-$1.txt"
+}
+
+txt_to_synopsis () {
+       builtin="$1" &&
+       out_dir="out/$builtin" &&
+       out="$out_dir/txt.synopsis" &&
+       if test -f "$out"
+       then
+               echo "$out" &&
+               return 0
+       fi &&
+       b2t="$(builtin_to_txt "$builtin")" &&
+       sed -n \
+               -e '/^\[verse\]$/,/^$/ {
+                       /^$/d;
+                       /^\[verse\]$/d;
+
+                       p;
+               }' \
+               <"$b2t" >"$out" &&
+       echo "$out"
+}
+
+check_dashed_labels () {
+       ! grep -E "<[^>_-]+_" "$1"
+}
+
 HT="   "
 
 while read builtin
@@ -39,6 +68,23 @@ do
                h2s="$(help_to_synopsis "$builtin")" &&
                ! grep "$HT" "$h2s"
        '
+
+       test_expect_success "$builtin -h output has dashed labels" '
+               check_dashed_labels "$(help_to_synopsis "$builtin")"
+       '
+
+       txt="$(builtin_to_txt "$builtin")" &&
+       preq="$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')" &&
+
+       if test -f "$txt"
+       then
+               test_set_prereq "$preq"
+       fi &&
+
+       # *.txt output assertions
+       test_expect_success "$preq" "$builtin *.txt SYNOPSIS has dashed labels" '
+               check_dashed_labels "$(txt_to_synopsis "$builtin")"
+       '
 done <builtins
 
 test_done