| Message ID | patch-v3-36.36-b56113dd620-20220930T180415Z-avarab@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | doc/UX: make txt & -h output more consistent | expand |
On Fri, Sep 30, 2022 at 2:10 PM Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote: > Add a test for the *.txt and *.c output assertions which asserts that > for "-h" lines that aren't the "usage: " or " or: " lines they start > with the same amount of whitespace. This ensures that we won't have > buggy output like: > > [...] > or: git tag [-n[<num>]] > [...] > [--create-reflog] [...] > > Which should instead be like this instead, i.e. the options lines > should be aligned: Too many "instead"s. > [...] > or: git tag [-n[<num>]] > [...] > [--create-reflog] [...] > > It would be better to be able to use "test_cmp" here, i.e. to > construct the output we expect, and compare it against the actual > output. > > For most built-in commands this would be rather straightforward. In > "t0450-txt-doc-vs-help.sh" we already compute the whitespace that a > "git-$builtin" needs, and strip away "usage: " or " or: " from the > start of lines. The problem is: > > * For commands that implement subcommands, such as "git bundle", we > don't know whether e.g. "git bundle create" is the subcommand > "create", or the argument "create" to "bundle" for the purposes of > alignment. > > We *do* have that information from the *.txt version, since the > part within the ''-quotes should be the command & subcommand, but > that isn't consistent (e.g. see "git bundle" and "git > commit-graph", only the latter is correct), and parsing that out > would be non-trivial. > > * If we were to make this stricter we have various > non-parse_options() users (e.g. "git diff-tree") that don't have the > nicely aligned output which we've had since > 4631cfc20bd (parse-options: properly align continued usage output, > 2021-09-21). > > So rather than make perfect the enemy of the good let's assert that > for those lines that are indented they should all use the same > indentation. > > Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh index 6a710b07408..adc81ec590b 100755 --- a/t/t0450-txt-doc-vs-help.sh +++ b/t/t0450-txt-doc-vs-help.sh @@ -66,6 +66,21 @@ do ! grep "$HT" help.raw ' + test_expect_success "$builtin -h output has consistent spacing" ' + builtin_to_synopsis "$builtin" >help.raw && + sed -n \ + -e "/^ / { + s/[^ ].*//; + p; + }" \ + <help.raw >help && + sort -u help >help.ws && + if test -s help.ws + then + test_line_count = 1 help.ws + fi + ' + txt="$(builtin_to_txt "$builtin")" && preq="$(echo BUILTIN_TXT_$builtin | tr '[:lower:]-' '[:upper:]_')" &&
Add a test for the *.txt and *.c output assertions which asserts that for "-h" lines that aren't the "usage: " or " or: " lines they start with the same amount of whitespace. This ensures that we won't have buggy output like: [...] or: git tag [-n[<num>]] [...] [--create-reflog] [...] Which should instead be like this instead, i.e. the options lines should be aligned: [...] or: git tag [-n[<num>]] [...] [--create-reflog] [...] It would be better to be able to use "test_cmp" here, i.e. to construct the output we expect, and compare it against the actual output. For most built-in commands this would be rather straightforward. In "t0450-txt-doc-vs-help.sh" we already compute the whitespace that a "git-$builtin" needs, and strip away "usage: " or " or: " from the start of lines. The problem is: * For commands that implement subcommands, such as "git bundle", we don't know whether e.g. "git bundle create" is the subcommand "create", or the argument "create" to "bundle" for the purposes of alignment. We *do* have that information from the *.txt version, since the part within the ''-quotes should be the command & subcommand, but that isn't consistent (e.g. see "git bundle" and "git commit-graph", only the latter is correct), and parsing that out would be non-trivial. * If we were to make this stricter we have various non-parse_options() users (e.g. "git diff-tree") that don't have the nicely aligned output which we've had since 4631cfc20bd (parse-options: properly align continued usage output, 2021-09-21). So rather than make perfect the enemy of the good let's assert that for those lines that are indented they should all use the same indentation. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> --- t/t0450-txt-doc-vs-help.sh | 15 +++++++++++++++ 1 file changed, 15 insertions(+)