mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Jeff King <>
To: "Martin Ågren" <>
Cc:, "Victoria Dye" <>,
	"Ævar Arnfjörð Bjarmason" <>
Subject: Re: [PATCH] cmd-list.perl: fix identifying man sections
Date: Fri, 23 Sep 2022 18:07:09 -0400	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

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

> 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. :)


  parent reply	other threads:[~2022-09-23 22:07 UTC|newest]

Thread overview: 10+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-09-23  7:03 [PATCH] cmd-list.perl: fix identifying man sections Martin Ågren
2022-09-23  7:38 ` Ævar Arnfjörð Bjarmason
2022-09-23  8:07   ` [PATCH v2] " Martin Ågren
2022-09-23  8:37     ` Ævar Arnfjörð Bjarmason
2022-09-23 11:42       ` Martin Ågren
2022-09-23 17:01     ` Junio C Hamano
2022-09-23 22:07 ` Jeff King [this message]
2022-09-26  7:16   ` [PATCH] " Martin Ågren
2022-09-26 17:06     ` Junio C Hamano
2022-09-26 13:35   ` Ævar Arnfjörð Bjarmason

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

  List information:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).