From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 21 Jul 2022 18:13:43 GMT
Subject: Re: [PATCH v5 0/9] docs: create & use "(user|developer) interfaces" categories
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:

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