Re: [PATCH 2/2] fsck: document msg-id

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Oct 25, 2022, 09:41 UTC
Message-ID: <221025.86wn8ock07.gmgdl@evledraar.gmail.com>
In-Reply-To: <xmqq8rl5t9ca.fsf@gitster.g>

On Mon, Oct 24 2022, Junio C Hamano wrote:

Show 8 quoted lines

> "John Cai via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> I almost suggested to extend the FOREACH_FSCK_MSG_ID() definition in
> fsck.h so that fsck-msgids.txt gets auto-generated (what is missing
> in fsck.h that prevents us from doing so is the textual explanation
> you added in the new file in your patch---they could come from
> comments on the same line, for example, and can be extracted via a
> Perl or sed script at build time).

I think this is the best eventual approach, whether we want it now is another matter...

> I do not know if it is a good
> idea, especially if we forsee a future in which we may be
> translating the documentation, so decided against making such a
> suggestion.

...I just wanted to point out that difficulty of translating such a thing should not be a reason to hold that back, because it's not hard to translate such an arrangement.

We'd just point the po-doc extraction at the generated *.txt, we'd need to re-arrange the Makefile dependencies a bit, but it shouldn't be a problem.

The *.pot-file generation is a step that only the translation coordinator *needs* to run, so even if it's a manual procedure, or requires first building the sources...

Show 6 quoted lines

> But at least, we could _lint_ the manually curated fsck-msgids.txt
> using what is in fsck.h to see if a new MSG_ID added to fsck.h is
> missing from the doc, or a MSG_ID whose default severity is updated
> in fsck.h is stale in the doc, etc.  That can be left for the future
> updates, but we should at least instruct developers to keep them in
> sync in fsck.h by adding a comment.

Yeah, that's a good step.