From: Ævar Arnfjörð Bjarmason Date: Wed, 28 Sep 2022 08:38:55 GMT Subject: [PATCH v2 00/35] doc/UX: make txt & -h output more consistent Message-ID: In-Reply-To: We are currently wildly inconsistent in whether the SYNOPSIS in the manual page matches the first line of the -h output, and as we add new options we routinely forget to add them to one or the other (or both). Without a more complex approach it's hard to do something about the "or both" case. But we can rather easily test whether the -h output matches the *.txt version, and report differences. As this series shows that allows us to fix a lot of issues we've effectively already "fixed", we just fixed them in one version, but not the other. For the rest of the general overview (the first paragraphs are copy/pasted) see the v1 at: https://lore.kernel.org/git/cover-00.34-00000000000-20220902T092734Z-avarab@gmail.com/ Changes since v1: * Clarified the CodingGuidelines update with Junio's suggested wording/changes. * Fixed a mention to a "preceding" commit noted by Victoria. * Made one minor bit of "sed" syntax in 34/35 consistent with the rest. * Added an assertion that "-h" output only has SP whitespace, not TABs. * 20/35 shows a bug in v1 of this. I compared the -h and *.txt output, but because I normalized (stripped away) the whitespace I didn't notice that "git tag" was left unindented. There's now a new test in 35/35 to test for that. Victoria: I decided not to go for your suggestion of trimming this series down in [1]. Reasons: * It would take me time I don't have to spend on this, as some of it isn't easy to cleanly re-arrange. E.g. the later "make consistent" commits rely on earlier whitespace/basic syntax fixes. * A major advantage of reviewing this in one go is that the 34-35/35 tests at the end are asserting everything that came before it. That's what I meant re the "mostly trust" comment you replied to in [1]. I.e. I aimed to make it easy for reviewers to trust that the "doc txt & -h consistency" patches were only altering one side of either -h or *.txt, with the other side being in-tree already. * I originally hacked this up with 34/35 coming first, but then to make the commits atomic I needed to update the test with each change to alter the list of built-ins expected to pass. I think that original approach is arguably better, as you can assert each commit in isolation, and it would certainly make it easier to split this up. But to re-do it again at this point would be more work & churn than I think this is worth. I'm attaching a "Documentation/doc-diff @{u} HEAD" below the range diff, to make it easy to see what the end result of the *.txt changes here is. 1. https://lore.kernel.org/git/af319ab4-2351-2d74-e0c7-6153f229d88c@github.com/ Ævar Arnfjörð Bjarmason (35): CodingGuidelines: update and clarify command-line conventions builtin/bundle.c: use \t, not fix indentation 2-SP indentation bundle: define subcommand -h in terms of command -h blame: use a more detailed usage_msg_optf() error on bad -L doc SYNOPSIS: don't use ' for subcommands doc SYNOPSIS: consistently use ' for commands doc SYNOPSIS & -h: fix incorrect alternates syntax built-ins: consistently add "\n" between "usage" and options doc txt & -h consistency: word-wrap doc txt & -h consistency: fix incorrect alternates syntax doc txt & -h consistency: add "-z" to cat-file "-h" doc txt & -h consistency: add missing "]" to bugreport "-h" doc txt & -h consistency: correct padding around "[]()" stash doc SYNOPSIS & -h: correct padding around "[]()" doc txt & -h consistency: use "", not "..." t/helper/test-proc-receive.c: use "", not "..." doc txt & -h consistency: fix mismatching labels doc txt & -h consistency: add or fix optional "--" syntax doc txt & -h consistency: make output order consistent doc txt & -h consistency: add missing options and labels doc txt & -h consistency: make "rerere" consistent doc txt & -h consistency: make "read-tree" consistent doc txt & -h consistency: make "bundle" consistent doc txt & -h consistency: use "git foo" form, not "git-foo" doc txt & -h consistency: add missing options doc txt & -h consistency: make "stash" consistent doc txt & -h consistency: make "annotate" consistent doc txt & -h consistency: use "[