Subject: Re: [PATCH v4 2/8] git docs: split "User-facing file formats" off from "Guides"

From: Junio C Hamano <[email-masked]>
Date: Tue, 19 Jul 2022 16:21:36 -0700

Ævar Arnfjörð Bjarmason <[email-masked]> writes:

>> If we can come up with a word that is more appropriate than
>> "format", it would be great.  If we do not place too much emphasis
>> on "format", I agree that both "gitignore" and "githook" fall into
>> the same category, because they define how the contents written in
>> these files affect the operation of Git commands.
>
> *nod*, another word would be most welcome :)

True.  What I am absolutely sure about is that the word is not
"format" X-<.  It is the interface end-users interact with internals
of Git, with need similar to how "plugin" interfaces need to have
documentation for their users.

> I do think that if we have --user-formats or --user-X it makes sense to
> have to have that match the --git-X. I.e. the "format" of say the
> commit-graph includes how we arrange those files on disk, just as is the
> case with the hoks.
>
>>> -With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'
>>> +With no options and no '<command>', '<guide>' or '<doc>' given, the synopsis of the 'git'
>>
>> At some point, we will have enough <doc> that it would probably
>> become meaningless to treat <guide> as a separate class, no?
>> Guides, user-supplied customization files, and implementation
>> details of on-disk files that may help reimplementations of Git, all
>> will become <doc>.
>
> Maybe I should just use <name> here?

I think <doc> is very good, much better than <name>, here.