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

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

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

> We take a wide view of what's considered a "user format", it's not
> just a file format, but e.g. githooks(5) also belongs, since the
> layout of the ".git/hooks/" and the placement of hooks in it is
> something the user might be expected to interact with.

I am afraid it is a bit big a stretch.  Other documents that fall
into the user-format category all have "format" the users must
follow while writing the "contents" in the file.  ".gitignore" has
certain format and syntax and the document describes what effect the
file has, based on the contents of the file that follows the syntax.

A hook can be written in any language, even though our UNIX lineage
makes our samples all in written in the shell, so there is no
"format" for the users to follow that we should force upon them.

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.

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

> @@ -26,8 +27,8 @@ printed on the standard output.
>  If the option `--guides` or `-g` is given, a list of the
>  Git concept guides is also printed on the standard output.
>  
> -If a command, or a guide, is given, a manual page for that command or
> -guide is brought up. The 'man' program is used by default for this
> +If a command or other documentation is given, the relevant manual page
> +will be brought up. The 'man' program is used by default for this

Good.