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...
> 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.
> 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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html