Re: [PATCH v5 0/9] docs: create & use "(user|developer) interfaces" categories

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 21, 2022, 18:13 UTC
Message-ID: <xmqqr12egwq0.fsf@gitster.g>
In-Reply-To: <cover-v5-0.9-00000000000-20220721T160721Z-avarab@gmail.com>

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

Show 7 quoted lines

> See v3[1] for lofty goals. The changes since v4 are mainly to rename
> the "user formats" and "developer formats" to "user interfaces" and
> "developer interfaces".
>
> Now:
>
> 	$ ./git help --user-interfaces

Hopefully this is a much better choice of words. "formats" would have had a very high chance of getting misunderstood and confusing readers. The interaction with hooks (e.g. you stop the operation X that asks the hook's decision by writing hooks/pre-X that exits with non-zero status) would probably be much better understood if it is described as "interface" than "format".

> And for "--developer-interfaces" (I wondered about calling this --apis):

"api" might be less misunderstanding-prone, but both should probably be OK. Again, much better than calling it "format".

Thanks.