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

Patrick Steinhardt [off-list ref] writes:

Fix remaining instances where "pack-file" is used instead of
"packfile".

Signed-off-by: Patrick Steinhardt <redacted>
---
This patch now also fixes instances where we refer to EBNF-style
command line parameters, as discussed by Junio and Peff.

Thanks.

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.

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.

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.

All changes to this file are good.

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.

On Thu, May 21, 2015 at 09:37:14AM -0700, Junio C Hamano wrote:

Patrick Steinhardt [off-list ref] writes:

quoted

Fix remaining instances where "pack-file" is used instead of
"packfile".

Signed-off-by: Patrick Steinhardt <redacted>
---
This patch now also fixes instances where we refer to EBNF-style
command line parameters, as discussed by Junio and Peff.

Thanks.

quoted

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.

quoted

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

quoted

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

quoted

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.

quoted

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.

quoted

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?

I did not find any referrers pointing to this, so I just changed
it. I do not know if there are any referrers from outside, so I
guess I'll just revert that back to [[pack-files]] as it is not
seen by users anyway.

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.

Exactly my thought by now. While it sure is nice to have the
technically most-correct terms in use I guess the user will not
realize that we are talking about different things when referring
to "pack-files" as opposed to "packfiles". I doubt it will hurt
though as the user will certainly just skim over it without
realizing that we sometimes use one or the other, as long as they
are not used together in a single paragraph.

Patrick