Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings
- From
Jeff King <peff@peff.net>
- Date
- Nov 4, 2010, 18:13 UTC
- Message-ID
- <20101104181357.GA31016@sigill.intra.peff.net>
- In-Reply-To
- <20101104180242.GA16431@burratino>
On Thu, Nov 04, 2010 at 01:02:42PM -0500, Jonathan Nieder wrote:
> Yes, that's way more verbose than a typical manpage synopsis.
Well, yes, but...
Show 20 quoted lines
> For example, from printf(3): > > SYNOPSIS > #include <stdio.h> > > int printf(const char *format, ...); > int fprintf(FILE *stream, const char *format, ...); > int sprintf(char *str, const char *format, ...); > int snprintf(char *str, size_t size, const char *format, ...); > > #include <stdarg.h> > > int vprintf(const char *format, va_list ap); > int vfprintf(FILE *stream, const char *format, va_list ap); > int vsprintf(char *str, const char *format, va_list ap); > int vsnprintf(char *str, size_t size, const char *format, va_list ap); > > Feature Test Macro Requirements for glibc (see feature_test_macros(7)): > > snprintf(), vsnprintf(): _BSD_SOURCE || _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE; or cc -std=c99
That's a little unfair as a comparison, as it's from a different section. Try "man IO::Handle", or most other perl modules, for example. They are quite a bit more verbose.
But yes, in general it is more verbose than other commands in section 1.
Show 10 quoted lines
> which would suggest that for git-diff(!) we should say something like: > > SYNOPSIS > > git diff [options] [--] [<path>...] > git diff [options] --cached [--] [<path>...] > git diff [options] <commit> [--] [<path>...] > git diff [options] --cached <commit> [--] [<path>...] > git diff [options] <commit> <commit> [--] [<path>...] > git diff [options] --no-index [--] <path> <path>
I would be OK with that; my comment lines were an attempt to make it a bit more clear to the user. But reading your revised versions, they seem pretty clear to me. I think your example there can actually be collapsed down to:
git diff [options] [<commit>] [--] [<path>...] git diff [options] --cached [<commit>] [--] [<path>...] git diff [options] <commit> <commit> [--] [<path>...] git diff [options] [--no-index] [--] <path> <path>
which covers the four major modes.
> I would rather treat --cached as one of the options ("instead of
> comparing the worktree, compare its cached content in the index to the
> specified commit"),Except it is not quite that. For the first two that I listed above, --cached makes that distinction. But --cached doesn't make sense at all in the third or fourth ones. So I think in practice it ends up defining a mode of operation more than simply an option.
But I do recognize that such a distinction is largely in the mental model of the user. On the other hand, this is documentation, so we are trying to promote healthy mental models for users. :)
> and if I were running the world, I'd leave off the [options]. :)
I have no strong opinion on that. There are pretty few unix programs that don't take [options] at the beginning, so it really is kind of superfluous. But it's also pretty standard, and clues the user in that we are a normal program.
-Peff