Re: [PATCH] cmd-list.perl: fix identifying man sections

From: Jeff King <peff@peff.net>
Date: Sep 23, 2022, 22:07 UTC
Message-ID: <Yy4uDW9YjpleFUHW@coredump.intra.peff.net>
In-Reply-To: <20220923070334.1970213-1-martin.agren@gmail.com>

On Fri, Sep 23, 2022 at 09:03:34AM +0200, Martin Ågren wrote:

Show 13 quoted lines

> This makes our git(1) manpage look as follows:
> 
>   Main porcelain commands
>        git-add(git)
>            Add file contents to the index.
> 
>   [...]
> 
>        gitk(git)
>            The Git repository browser.
> 
>        scalar(scalar)
>            A tool for managing large Git repositories.

Good catch. The patch looks good (I was going to suggest ?:, but I see Ævar beat me to it).

I wondered if we might have caught this in a more automatic way. The output of:

  cd Documentation
  ./doc-diff cc75e556a9^ cc75e556a9

makes the problem apparent, but I don't fault reviewers for not running it. I rarely remember to do so. And in general you need a human looking at doc-diff output to know if it was the intended change or not.

I wondered if it might be worth running

  ./doc-diff v2.37.0 v2.38.0-rc1

near a release to scan over all of the changes. But the diff is over 8000 lines, and I admit my eyes glazed over before I got to the problematic hunks (even though I knew I was looking for them!). You can limit it a bit with --diff-filter=a, which drops new entries (which can't have regressed!), but it's still over 4000 lines.

So I dunno. I think doc-diff is a potentially useful tool, but I'm not sure how to point the human attention at the right spot to find a bug. Maybe "given enough eyeballs, all bugs are shallow" is our best bet here. After all, it did find this bug before the release. :)

-Peff