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

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Jul 21, 2022, 07:02 UTC
Message-ID: <220721.864jzbueg5.gmgdl@evledraar.gmail.com>
In-Reply-To: <xmqqcze0664f.fsf@gitster.g>

On Tue, Jul 19 2022, Junio C Hamano wrote:

Show 14 quoted lines

> Ævar Arnfjörð Bjarmason <avarab@gmail.com> 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.

My goal here is just to make this part of our documentation more accessible, so I don't care about the term. But this series also seems blocked on you not liking the term, so...

A few ways I can think of to go forward:

1. Use "format", but explain that we're using it loosely. Perhaps with
   this on top?
	
	diff --git a/Documentation/git.txt b/Documentation/git.txt
	index 1980a0e29cd..9f8d7a3543e 100644
	--- a/Documentation/git.txt
	+++ b/Documentation/git.txt
	@@ -343,7 +343,10 @@ User-facing file formats
	 ------------------------
	 
	 This documentation discusses file formats that users are expected to
	-edit. These can also be listed with 'git help --user-formats'.
	+edit. "Format" here refers more broadly to files and/or file contents
	+that the user is expected to edit or know about.
	+
	+These can also be listed with 'git help --user-formats'.
	 
	 include::cmds-userformats.txt[]

2. I could submit this without the "git help --user-formats" change for
   now, and just focus on --git-formats:
	
	Internal file formats and protocols:
	   format-bundle                  The bundle file format
	   format-chunk                   Chunk-based file formats
	   format-commit-graph            Git commit graph format
	   format-index                   Git index format
	   format-multi-pack-index        The multi-pack-index file format
	   format-pack                    Git pack format
	   format-pack-cruft              The cruft pack file format
	   format-pack-protocol           How packs are transferred over-the-wire
	   format-protocol-capabilities   Protocol v0 and v1 capabilities
	   format-protocol-common         Things common to various protocols
	   format-protocol-http           Git HTTP-based protocols
	   format-protocol-v2             Git Wire Protocol, Version 2
	   format-signature               Git cryptographic signature formats

   Do you have an objection to any of those being labeled "format"? I
   understood your comments above to not include those, i.e. that you
   took objection to githooks(5) in particular being in that new
   --user-formats category.

3. A re-roll of this series pretty much as-is (sans other fixes), but
   remove "githooks" from this re-categorization.

4. Come up with s/format/<something>/g, but I have no idea what that
   "something" would be. "Protocol?", After all a secret handshake is
   also a protocol....