Re: [PATCH] Documentation/git-fsck.txt: include fsck.* config variables

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 29, 2019, 15:48 UTC
Message-ID: <xmqq36iox2nn.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <87sgqo6ejk.fsf@evledraar.gmail.com>

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

Show 27 quoted lines

> On Mon, Jul 29 2019, SZEDER Gábor wrote:
>
>> The 'fsck.skipList' and 'fsck.<msg-id>' config variables might be
>> easier to discover when they are documented in 'git fsck's man page.
>>
>> Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com>
>> ---
>>  Documentation/git-fsck.txt | 5 +++++
>>  1 file changed, 5 insertions(+)
>>
>> diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt
>> index e0eae642c1..d72d15be5b 100644
>> --- a/Documentation/git-fsck.txt
>> +++ b/Documentation/git-fsck.txt
>> @@ -104,6 +104,11 @@ care about this output and want to speed it up further.
>>  	progress status even if the standard error stream is not
>>  	directed to a terminal.
>>
>> +CONFIGURATION
>> +-------------
>> +
>> +include::config/fsck.txt[]
>
> Before this include let's add:
>
>     The below documentation is the same as what’s found in
>     git-config(1):

I actually do not think we would want to do that. I am all for the kind of 'include' proposed by this patch, and we should strive to make it easier for us to make sure the duplicated text are in sync.

But that would mean that the readers will have to see the "is the same as the other one" over and over. If our documentation set is consistent, they should not have to.

I think we *must* make such a note in a total opposite case, i.e. "here are the summary of the most often used options; for full list, see git-config(1)".

> As I did for a similar change in git-gc in b6a8d09f6d ("gc docs: include
> the "gc.*" section from "config" in "gc"", 2019-04-07). Sometimes we
> repeat ourselves, it helps the reader to know this isn't some slightly
> different prose than what's in git-config.

So, I think we should revert that part out of b6a8d09f6d, too.