mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Jeff King <>
To: Nicolas Sebrecht <>
Cc: Junio C Hamano <>,
	Sebastian Pipping <>,
	Thomas Rast <>, Git ML <>
Subject: Re: Parameter --color-words not documented for "git show"
Date: Thu, 20 Jan 2011 18:34:29 -0500	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <20110120231649.GC14184@vidovic>

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

> The 20/01/11, Junio C Hamano wrote:
> > Sebastian Pipping <> 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

  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.


  reply	other threads:[~2011-01-20 23:34 UTC|newest]

Thread overview: 14+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2011-01-20 19:58 Parameter --color-words not documented for "git show" Sebastian Pipping
2011-01-20 20:27 ` Thomas Rast
2011-01-20 20:43   ` Sebastian Pipping
2011-01-20 21:25     ` Junio C Hamano
2011-01-20 23:16       ` Nicolas Sebrecht
2011-01-20 23:34         ` Jeff King [this message]
2011-01-21  0:05           ` Sebastian Pipping
2011-01-21  0:20             ` Jeff King
2011-01-21  0:27               ` Sebastian Pipping
2011-01-21  6:08           ` Junio C Hamano
2011-01-21 16:16             ` Jeff King
2011-01-21 10:08           ` Maaartin
2011-01-21 16:17             ` Jeff King
2011-01-23 10:35       ` Jakub Narebski

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

  List information:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).