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

[Junio C Hamano <gitster@pobox.com>]

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

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