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

[Robert P. J. Day]

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

> "Robert P. J. Day"  writes:
>
> >> > 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...
>
> Nah.  With the same logic you could say --all is already on synopsis
> and no need for explanation.

  uh, that's not what i meant. what i *meant* was that the purpose of
"--" was already in the SYNOPSIS (as it appears to be in *all* man
pages) to visually show that it is a separator between the first part
of the command and possible pathnames. i was *not* suggesting that, if
something is in the SYNOPSIS, there is no further need to explain it.

  anyway, i can see this is a losing battle so i'll let it go.

rday

-- 


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

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

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

[Junio C Hamano]

"Robert P. J. Day"  writes:

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

Nah.  With the same logic you could say --all is already on synopsis
and no need for explanation.

If you are shooting for pedantic consistency, adding to pages that
are missing would be less problematic than removing from the ones
that have them, especially given that people thought the use of
double-dash in commands described on these pages are common or
special enough to deserve extra attention.

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

[Robert P. J. Day]

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

> "Robert P. J. Day"  writes:
>
> > There is no value in individual man pages explaining the purpose
> > of the "--" separator.
> >
> > Signed-off-by: Robert P. J. Day 
> >
> > ---
> >
> >   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 ...", 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  in the index ("i/")
> >  and in the working tree ("w/") are shown for regular files,
> >  followed by the  ("attr/").
> >
> > -\--::
> > -   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

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

[Junio C Hamano]

"Robert P. J. Day"  writes:

> There is no value in individual man pages explaining the purpose of
> the "--" separator.
>
> Signed-off-by: Robert P. J. Day 
>
> ---
>
>   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.

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

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

> 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  in the index ("i/")
>  and in the working tree ("w/") are shown for regular files,
>  followed by the  ("attr/").
>
> -\--::
> - 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).