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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Thu, May 21, 2015 at 09:37:14AM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@xxxxxx> writes:
> 
> > Fix remaining instances where "pack-file" is used instead of
> > "packfile".
> >
> > Signed-off-by: Patrick Steinhardt <ps@xxxxxx>
> > ---
> > 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?

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

Attachment: signature.asc
Description: PGP signature


[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]