Parameter --color-words not documented for "git show"

Parameter --color-words not documented for "git show"

[Sebastian Pipping]

Hello,


I noticed that

  git show --color-words

works just fine, but it's not listed in

  man git-show

I am referring to this version:

  $ git --version
  git version 1.7.4.rc2

Thanks,



Sebastian

Re: Parameter --color-words not documented for "git show"

[Thomas Rast]

Sebastian Pipping wrote:
> 
> I noticed that
> 
>   git show --color-words
> 
> works just fine, but it's not listed in
> 
>   man git-show

Quote from the latter:

       This manual page describes only the most frequently used options.


-- 
Thomas Rast
trast@{inf,student}.ethz.ch

Re: Parameter --color-words not documented for "git show"

[Sebastian Pipping]

On 01/20/11 21:27, Thomas Rast wrote:
> Quote from the latter:
> 
>        This manual page describes only the most frequently used options.

Okay.  Is that a good a idea?  Is --abbrev-commit really used more
frequently with "git show" than --color-words is?



Sebastian

Re: Parameter --color-words not documented for "git show"

[Junio C Hamano]

Sebastian Pipping <webmaster@hartwork.org> writes:

> On 01/20/11 21:27, Thomas Rast wrote:
>> Quote from the latter:
>> 
>>        This manual page describes only the most frequently used options.
>
> Okay.  Is that a good a idea?

Yes; the alternative is to list everything.

> Is --abbrev-commit really used more
> frequently with "git show" than --color-words is?

I see this as a not-so-helpful-but-still-interesting question.

It depends on who you are, and if one wants to pick the most often used
ones, that selection may or may not coincide with _your_ usage pattern nor
mine.  The original author apparently thought so, you seem to think
color-words is used a lot more often, and I personally think neither is
used often at all.  So should we swap them, keep things as-is, or remove
both?

We obviously cannot take a poll to update the list every time a new user
starts using git, but it might make sense to review them every once in a
while.

Re: Parameter --color-words not documented for "git show"

[Nicolas Sebrecht]

The 20/01/11, Junio C Hamano wrote:
> Sebastian Pipping <webmaster@hartwork.org> writes:
> 
> > On 01/20/11 21:27, Thomas Rast wrote:
> >> Quote from the latter:
> >> 
> >>        This manual page describes only the most frequently used options.
> >
> > Okay.  Is that a good a idea?
> 
> Yes; the alternative is to list everything.

Would it be bad? I tend to think that a manual page is the good place to
list everything the program accepts as parameters and how to use them.
FMHO, Manual page is not where newcomers look to learn but it should
help everybody to find and understand all of the available options.

-- 
Nicolas Sebrecht

Re: Parameter --color-words not documented for "git show"

[Jeff King]

On Fri, Jan 21, 2011 at 12:16:49AM +0100, Nicolas Sebrecht wrote:

> The 20/01/11, Junio C Hamano wrote:
> > Sebastian Pipping <webmaster@hartwork.org> writes:
> > 
> > > On 01/20/11 21:27, Thomas Rast wrote:
> > >> Quote from the latter:
> > >> 
> > >>        This manual page describes only the most frequently used options.
> > >
> > > Okay.  Is that a good a idea?
> > 
> > Yes; the alternative is to list everything.
> 
> Would it be bad? I tend to think that a manual page is the good place to
> list everything the program accepts as parameters and how to use them.
> FMHO, Manual page is not where newcomers look to learn but it should
> help everybody to find and understand all of the available options.

The problem is that we have a bazillion diff options that appear in many
manpages, so you are stuck with one of:

  1. repeat them all in each manpage (usually via some automagic
     include), which dwarfs the original content, and makes it hard for
     users to see subtle differences between commands

  2. Say "this describes only the most frequently used options", which
     leaves the user wondering which infrequently used options exist.

  3. Say "we also take diff options, and you can find out more about
     diff options in git-diff(1)." This at least points the user in the
     right direction, but you can't search for "--color-words" in the
     page.

  4. Do (3), but also list the all (or common) diff options in a succint
     list without descriptions, and refer the user to git-diff(1). Then
     they can grep if they like, and while they won't get the immediate
     answer, they will get referred to the right place.

As you can probably guess, I favor option (4), though we already do (3)
in some places.

-Peff

Re: Parameter --color-words not documented for "git show"

[Sebastian Pipping]

On 01/21/11 00:34, Jeff King wrote:
>>> Yes; the alternative is to list everything.
>>
>> Would it be bad? I tend to think that a manual page is the good place to
>> list everything the program accepts as parameters and how to use them.
>> FMHO, Manual page is not where newcomers look to learn but it should
>> help everybody to find and understand all of the available options.
> 
> The problem is that we have a bazillion diff options that appear in many
> manpages, so you are stuck with one of:
> 
>   1. repeat them all in each manpage (usually via some automagic
>      include), which dwarfs the original content, and makes it hard for
>      users to see subtle differences between commands
> 
>   2. Say "this describes only the most frequently used options", which
>      leaves the user wondering which infrequently used options exist.
> 
>   3. Say "we also take diff options, and you can find out more about
>      diff options in git-diff(1)." This at least points the user in the
>      right direction, but you can't search for "--color-words" in the
>      page.
> 
>   4. Do (3), but also list the all (or common) diff options in a succint
>      list without descriptions, and refer the user to git-diff(1). Then
>      they can grep if they like, and while they won't get the immediate
>      answer, they will get referred to the right place.
> 
> As you can probably guess, I favor option (4), though we already do (3)
> in some places.

I agree with Thomas here.  (1) is the only option I find acceptable,
personally.  If you'd rather not do that, then at least know I now.
Great to have --color-words around btw.

Best,



Sebastian

Re: Parameter --color-words not documented for "git show"

[Jeff King]

On Fri, Jan 21, 2011 at 01:05:24AM +0100, Sebastian Pipping wrote:

> > The problem is that we have a bazillion diff options that appear in many
> > manpages, so you are stuck with one of:
> > 
> >   1. repeat them all in each manpage (usually via some automagic
> >      include), which dwarfs the original content, and makes it hard for
> >      users to see subtle differences between commands
> > 
> >   2. Say "this describes only the most frequently used options", which
> >      leaves the user wondering which infrequently used options exist.
> > 
> >   3. Say "we also take diff options, and you can find out more about
> >      diff options in git-diff(1)." This at least points the user in the
> >      right direction, but you can't search for "--color-words" in the
> >      page.
> > 
> >   4. Do (3), but also list the all (or common) diff options in a succint
> >      list without descriptions, and refer the user to git-diff(1). Then
> >      they can grep if they like, and while they won't get the immediate
> >      answer, they will get referred to the right place.
> > 
> > As you can probably guess, I favor option (4), though we already do (3)
> > in some places.
> 
> I agree with Thomas here.  (1) is the only option I find acceptable,
> personally.  If you'd rather not do that, then at least know I now.
> Great to have --color-words around btw.

I'm curious why (4) doesn't work for you. I assumed you came to the
problem by one of:

  - you wanted to know which options "git show" had, so you looked in
    the manpage. Nothing told you about "--color-words", nor referred
    you to a list of diff options. With (4), you would find that it
    accepted all diff options, and then go read the list of diff options
    (if you weren't already familiar with it).

  - you knew about --color-words, and wondered if "git show" supported
    it. In the current case, searching the page turns up nothing. In
    option (4), a search would find it (with a reference to diff options
    if you wanted more details).

The downside is that you sometimes have to be referred. The upside to me
is that it becomes explicit that there is a concept of "diff options"
that you can look up easily and which we can refer to easily in other
parts of the manual. That helps establish a mental model of how git's
options work.

So is it just that being referred is annoying, or something else?

-Peff

Re: Parameter --color-words not documented for "git show"

[Sebastian Pipping]

On 01/21/11 01:20, Jeff King wrote:
>> I agree with Thomas here.  (1) is the only option I find acceptable,
>> personally.  If you'd rather not do that, then at least know I now.
>> Great to have --color-words around btw.
> 
> I'm curious why (4) doesn't work for you. I assumed you came to the
> problem by one of:
> 
>   - you wanted to know which options "git show" had, so you looked in
>     the manpage. Nothing told you about "--color-words", nor referred
>     you to a list of diff options. With (4), you would find that it
>     accepted all diff options, and then go read the list of diff options
>     (if you weren't already familiar with it).
> 
>   - you knew about --color-words, and wondered if "git show" supported
>     it. In the current case, searching the page turns up nothing. In
>     option (4), a search would find it (with a reference to diff options
>     if you wanted more details).
> 
> The downside is that you sometimes have to be referred. The upside to me
> is that it becomes explicit that there is a concept of "diff options"
> that you can look up easily and which we can refer to easily in other
> parts of the manual. That helps establish a mental model of how git's
> options work.
> 
> So is it just that being referred is annoying, or something else?

Actually that approach is perfect.  I misunderstood (4) on the first
read somehow.  Really not my day today, sorry.  I would love to see you
push (4) forward.

Best,



Sebastian

Re: Parameter --color-words not documented for "git show"

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> The problem is that we have a bazillion diff options that appear in many
> manpages, so you are stuck with one of:
>
>   1. repeat them all in each manpage (usually via some automagic
>      include), which dwarfs the original content, and makes it hard for
>      users to see subtle differences between commands
>
>   2. Say "this describes only the most frequently used options", which
>      leaves the user wondering which infrequently used options exist.
>
>   3. Say "we also take diff options, and you can find out more about
>      diff options in git-diff(1)." This at least points the user in the
>      right direction, but you can't search for "--color-words" in the
>      page.
>
>   4. Do (3), but also list the all (or common) diff options in a succint
>      list without descriptions, and refer the user to git-diff(1). Then
>      they can grep if they like, and while they won't get the immediate
>      answer, they will get referred to the right place.
>
> As you can probably guess, I favor option (4), though we already do (3)
> in some places.

We attempt to do 1 to solve it "nicely" in some manual pages, and indeed
there are many "exclude this option from the command X's manpage" magic
that causes the problem of subtle differences you mentioned (which I
agree).

One complication in either 3 or 4 is that they sometimes need to be
accompanied with "... except these diff options do not make sense in the
context of this command, so they are no-op".  That is probably a price
worth paying to be more helpful than 2 is.

Re: Parameter --color-words not documented for "git show"

[Maaartin]

On 11-01-21 00:34, Jeff King wrote:
> On Fri, Jan 21, 2011 at 12:16:49AM +0100, Nicolas Sebrecht wrote:

>   4. Do (3), but also list the all (or common) diff options in a succint
>      list without descriptions, and refer the user to git-diff(1). Then
>      they can grep if they like, and while they won't get the immediate
>      answer, they will get referred to the right place.
> 
> As you can probably guess, I favor option (4), though we already do (3)
> in some places.

I also favor (4), for the following reasons:

- sometimes you want to read the whole manpage, e.g., it's good for
beginners to get feeling what is it all about.

- repeated information makes the page too long and reading too boring.

- too long manpages may scare beginners.

Maybe there could be sort-of extended manpage, containing everything,
but it would need some markup beyond the capabilities of a terminal (a
grayed or collapsed area in html, or whatever). However, this could be a
lot of additional work, and I don't claim it should be done, just an idea.

Re: Parameter --color-words not documented for "git show"

[Jeff King]

On Thu, Jan 20, 2011 at 10:08:36PM -0800, Junio C Hamano wrote:

> >   3. Say "we also take diff options, and you can find out more about
> >      diff options in git-diff(1)." This at least points the user in the
> >      right direction, but you can't search for "--color-words" in the
> >      page.
> >
> >   4. Do (3), but also list the all (or common) diff options in a succint
> >      list without descriptions, and refer the user to git-diff(1). Then
> >      they can grep if they like, and while they won't get the immediate
> >      answer, they will get referred to the right place.
> [...]
> One complication in either 3 or 4 is that they sometimes need to be
> accompanied with "... except these diff options do not make sense in the
> context of this command, so they are no-op".  That is probably a price
> worth paying to be more helpful than 2 is.

Yeah, I took a quick look at diff-options.txt. I think many of those
special cases can be handled by just mentioning the exceptions in the
text. They are usually simple and obvious special cases, like "for -M,
if you are in a command which is traversing, you might be interested in
--follow". I don't think it will hurt people to read that, even if they
are looking at the diff-options because they want to know about "git
diff".

I'll this to my documentation cleanup todo list. It's lower priority
than many other things, but believe it or not I am working towards it.
:)

-Peff

Re: Parameter --color-words not documented for "git show"

[Jeff King]

On Fri, Jan 21, 2011 at 11:08:21AM +0100, Maaartin wrote:

> Maybe there could be sort-of extended manpage, containing everything,
> but it would need some markup beyond the capabilities of a terminal (a
> grayed or collapsed area in html, or whatever). However, this could be a
> lot of additional work, and I don't claim it should be done, just an idea.

Yeah, that would be nice, but it is beyond the manpage format. For HTML
versions, we can (and will) hyperlink, which at least makes following
the reference easy to do.

-Peff

Re: Parameter --color-words not documented for "git show"

[Jakub Narebski]

Junio C Hamano <gitster@pobox.com> writes:
> Sebastian Pipping <webmaster@hartwork.org> writes:
>> On 01/20/11 21:27, Thomas Rast wrote:
>>> Quote from the latter:
>>> 
>>>        This manual page describes only the most frequently used options.
>>
>> Okay.  Is that a good a idea?
> 
> Yes; the alternative is to list everything.
> 
>> Is --abbrev-commit really used more
>> frequently with "git show" than --color-words is?
> 
> I see this as a not-so-helpful-but-still-interesting question.
> 
> It depends on who you are, and if one wants to pick the most often used
> ones, that selection may or may not coincide with _your_ usage pattern nor
> mine.  The original author apparently thought so, you seem to think
> color-words is used a lot more often, and I personally think neither is
> used often at all.  So should we swap them, keep things as-is, or remove
> both?
> 
> We obviously cannot take a poll to update the list every time a new user
> starts using git, but it might make sense to review them every once in a
> while.

There is also additional problem, namely that because "git show" shows
commit and can show diff, therefore it accepts same formatting options
as "git log", and when set to display patch it accepts any diff family
options.

Should we then list most common porcelanish diff options, or just
refer to git-diff(1) manpage?

-- 
Jakub Narebski
Poland
ShadeHawk on #git