* Re: Parameter --color-words not documented for "git show"
2011-01-20 23:34 ` Jeff King
@ 2011-01-21 0:05 ` Sebastian Pipping
2011-01-21 0:20 ` Jeff King
2011-01-21 6:08 ` Junio C Hamano
2011-01-21 10:08 ` Maaartin
2 siblings, 1 reply; 14+ messages in thread
From: Sebastian Pipping @ 2011-01-21 0:05 UTC (permalink / raw)
To: Jeff King; +Cc: Nicolas Sebrecht, Junio C Hamano, Thomas Rast, Git ML
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
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: Parameter --color-words not documented for "git show"
2011-01-21 0:05 ` Sebastian Pipping
@ 2011-01-21 0:20 ` Jeff King
2011-01-21 0:27 ` Sebastian Pipping
0 siblings, 1 reply; 14+ messages in thread
From: Jeff King @ 2011-01-21 0:20 UTC (permalink / raw)
To: Sebastian Pipping; +Cc: Nicolas Sebrecht, Junio C Hamano, Thomas Rast, Git ML
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
^ permalink raw reply [flat|nested] 14+ messages in thread* Re: Parameter --color-words not documented for "git show"
2011-01-21 0:20 ` Jeff King
@ 2011-01-21 0:27 ` Sebastian Pipping
0 siblings, 0 replies; 14+ messages in thread
From: Sebastian Pipping @ 2011-01-21 0:27 UTC (permalink / raw)
To: Jeff King; +Cc: Nicolas Sebrecht, Junio C Hamano, Thomas Rast, Git ML
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
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: Parameter --color-words not documented for "git show"
2011-01-20 23:34 ` Jeff King
2011-01-21 0:05 ` Sebastian Pipping
@ 2011-01-21 6:08 ` Junio C Hamano
2011-01-21 16:16 ` Jeff King
2011-01-21 10:08 ` Maaartin
2 siblings, 1 reply; 14+ messages in thread
From: Junio C Hamano @ 2011-01-21 6:08 UTC (permalink / raw)
To: Jeff King; +Cc: Nicolas Sebrecht, Sebastian Pipping, Thomas Rast, Git ML
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.
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: Parameter --color-words not documented for "git show"
2011-01-21 6:08 ` Junio C Hamano
@ 2011-01-21 16:16 ` Jeff King
0 siblings, 0 replies; 14+ messages in thread
From: Jeff King @ 2011-01-21 16:16 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Nicolas Sebrecht, Sebastian Pipping, Thomas Rast, Git ML
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
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: Parameter --color-words not documented for "git show"
2011-01-20 23:34 ` Jeff King
2011-01-21 0:05 ` Sebastian Pipping
2011-01-21 6:08 ` Junio C Hamano
@ 2011-01-21 10:08 ` Maaartin
2011-01-21 16:17 ` Jeff King
2 siblings, 1 reply; 14+ messages in thread
From: Maaartin @ 2011-01-21 10:08 UTC (permalink / raw)
To: Jeff King
Cc: Nicolas Sebrecht, Junio C Hamano, Sebastian Pipping, Thomas Rast,
Git ML
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.
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: Parameter --color-words not documented for "git show"
2011-01-21 10:08 ` Maaartin
@ 2011-01-21 16:17 ` Jeff King
0 siblings, 0 replies; 14+ messages in thread
From: Jeff King @ 2011-01-21 16:17 UTC (permalink / raw)
To: Maaartin
Cc: Nicolas Sebrecht, Junio C Hamano, Sebastian Pipping, Thomas Rast,
Git ML
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
^ permalink raw reply [flat|nested] 14+ messages in thread