Re: [PATCH] doc: Remove explanation of "--" from several man pages

["Robert P. J. Day" <rpjday@crashcourse.ca>]

On Mon, 13 Nov 2017, Junio C Hamano wrote:

> "Robert P. J. Day" <rpjday@crashcourse.ca> writes:
>
> > There is no value in individual man pages explaining the purpose
> > of the "--" separator.
> >
> > Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> >
> > ---
> >
> >   unless every man page explains that option, it's pointless to
> > have just *some* man pages explaining it, so might as well remove
> > it from all of them.
>
> Please do not remove diffstat that format-patch gave you at this
> point.  While commenting on the hunk on "git add", I wanted to see
> if you touched "git rm", and the diffstat at front _is_ the go-to
> place to do so for reviewers.

  apologies, won't happen again.

> > diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
> > index b700beaff..69d625285 100644
> > --- a/Documentation/git-add.txt
> > +++ b/Documentation/git-add.txt
> > @@ -180,11 +180,6 @@ for "git add --no-all <pathspec>...", i.e. ignored removed files.
> >  	bit is only changed in the index, the files on disk are left
> >  	unchanged.
> >
> > -\--::
> > -	This option can be used to separate command-line options from
> > -	the list of files, (useful when filenames might be mistaken
> > -	for command-line options).
> > -
>
> I do not think if this removal alone is a good idea.
>
> Before this can happen, the description for "--" in other pages,
> (like gitcli(7), may need to be extended.  Right now, gitcli's
> mention of "--" is only about turning off disambiguation between
> revs and pathspecs, and it does not cover this case
>
> 	$ >./--foo-bar
> 	$ git add -- --foo-bar
>
> even though the description you are removing would have helped the
> reader to understand why "--" is there.  The hunk on "git rm" shares
> the same issue.

  i don't see the problem here ... in the above, "--foobar" is clearly
a pathspec. and if you think that's a special case that needs special
explanation, then that argument surely applies to several other
commands and their man pages.

  the main point here is that it's inconsistent to have *some* man
pages explicitly explain "--" and not have *all* of them explain it.
either they all should, or none of them should, and there's little
value in suggesting that the occasional man page somehow deserves
special treatment.

> >  Configuration
> >  -------------
> > diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt
> > index aa3b2bf2f..0ae2523e0 100644
> > --- a/Documentation/git-check-attr.txt
> > +++ b/Documentation/git-check-attr.txt
> > @@ -36,10 +36,6 @@ OPTIONS
> >  	If `--stdin` is also given, input paths are separated
> >  	with a NUL character instead of a linefeed character.
> >
> > -\--::
> > -	Interpret all preceding arguments as attributes and all following
> > -	arguments as path names.
> > -
>
> This also has a similar issue.  "--" here is not between revs and
> pathspecs but is between attributes and pathspecs.

  that can already be seen in the SYNOPSIS for that command, it does
not require further explanation:

  SYNOPSIS
       git check-attr [-a | --all | attr...] [--] pathname...

> > diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
> > index d153c17e0..93ebb020c 100644
> > --- a/Documentation/git-ls-files.txt
> > +++ b/Documentation/git-ls-files.txt
> > @@ -171,9 +171,6 @@ Both the <eolinfo> in the index ("i/<eolinfo>")
> >  and in the working tree ("w/<eolinfo>") are shown for regular files,
> >  followed by the  ("attr/<eolattr>").
> >
> > -\--::
> > -	Do not interpret any more arguments as options.
>
> These removals would become a good idea, once we say that we would
> use "--" to mean "you will not see any --flags after this point" (as
> commonly seen in programs that are not Git) somewhere central like
> gitcli(7).

  if you want to suggest some wording to make that happen, that would
be great, but i'm standing by my opinion that there is no rationale
for *any* man page explaining what "--" means when, as far as i can
tell, it always means the same thing.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================