Re: [PATCH] doc: fix inconsistent spelling of "packfile"

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

Patrick Steinhardt <ps@pks.im> writes:

> Fix remaining instances where "pack-file" is used instead of
> "packfile".
>
> Signed-off-by: Patrick Steinhardt <ps@pks.im>
> ---
> This patch now also fixes instances where we refer to EBNF-style
> command line parameters, as discussed by Junio and Peff.

Thanks.

> diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt
> index 7a4e055..49621da 100644
> --- a/Documentation/git-index-pack.txt
> +++ b/Documentation/git-index-pack.txt
> @@ -9,9 +9,9 @@ git-index-pack - Build pack index file for an existing packed archive
>  SYNOPSIS
>  --------
>  [verse]
> -'git index-pack' [-v] [-o <index-file>] <pack-file>
> +'git index-pack' [-v] [-o <index-file>] <packfile>
>  'git index-pack' --stdin [--fix-thin] [--keep] [-v] [-o <index-file>]
> -                 [<pack-file>]
> +		  [<packfile>]

Hmm.  The former is taking a concrete *.pack file on disk, and the
latter is optionally writing the pack stream out to a *.pack file on
disk.  If we follow "'packfile' for the concept, 'pack-file' to
refer to a file with .pack ending" guideline, I'd think both should
be 'pack-file'.

	Side note: because these invocations, especially the latter
	form, can take any filename, you could do:

        	git index-pack foo.tmp && mv foo.tmp $realfilename.pack

	in which case the arguments may not be files whose names end
	with ".pack"; it is just a file that holds pack data stream,
	so it could be argued that "packfile" is not incorrect.  But
	the reason why you are doing the above is to ultimately
	create a *.pack file, and I'd say "pack-file" would be more
	correct.

> @@ -37,11 +37,11 @@ OPTIONS
>  
>  --stdin::
>  	When this flag is provided, the pack is read from stdin
> -	instead and a copy is then written to <pack-file>. If

Likewise; we are writing to a *.pack file, "written to" is not
talking about what (i.e. "packfile", the pack data stream) is
written but what accepts and holds that data stream in the end.

> -	<pack-file> is not specified, the pack is written to
> +	instead and a copy is then written to <packfile>. If
> +	<packfile> is not specified, the pack is written to
>  	objects/pack/ directory of the current Git repository with
>  	a default name determined from the pack content.  If
> -	<pack-file> is not specified consider using --keep to
> +	<packfile> is not specified consider using --keep to
>  	prevent a race condition between this process and
>  	'git repack'.

All of the above talk about that same entity on the filesystem that
receives the pack data stream.

> diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt
> index 894d20b..07d4329 100644
> --- a/Documentation/git-unpack-objects.txt
> +++ b/Documentation/git-unpack-objects.txt
> @@ -9,7 +9,7 @@ git-unpack-objects - Unpack objects from a packed archive
>  SYNOPSIS
>  --------
>  [verse]
> -'git unpack-objects' [-n] [-q] [-r] [--strict] < <pack-file>
> +'git unpack-objects' [-n] [-q] [-r] [--strict] < <packfile>

This feeds the pack data stream to the command from its standard
input, so would be a good change.

	Side note: if you have an on-disk file to feed this command
	from its standard input, it is more than likely that the
	file is a *.pack file, i.e. a "pack-file".  But in practice,
	the command is more often than not fed an output of another
	command via pipe, and it only cares about it being a pack
	data stream.  So in that sense, both are correct but the
	updated one is more correct.

> diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
> index 812d857..fc09c63 100644
> --- a/Documentation/technical/pack-protocol.txt
> +++ b/Documentation/technical/pack-protocol.txt
> @@ -465,7 +465,7 @@ contain all the objects that the server will need to complete the new
>  references.

All changes to this file are good.

> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 68978f5..7147519 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -3164,7 +3164,7 @@ objects.  (Note that linkgit:git-tag[1] can also be used to create
>  "lightweight tags", which are not tag objects at all, but just simple
>  references whose names begin with `refs/tags/`).
>  
> -[[pack-files]]
> +[[packfiles]]

Isn't this a xref target?  Can you change it without changing all
the referrers?


In any case, after doing the above two side notes, I am not sure if
readers would appreciate our careful choice of words between
"packfile" and "pack-file" when they read the documentation.