On Wed, Oct 09, 2013 at 11:35:19PM +0100, Philip Oakley wrote:
> >As a unix user I'd expect the SYNOPSIS section at the top of the
> >man page to include all options that the command accepts. Mutually
> >exclusive options are expected to be in the form [-q | --progress |
> >--all-progress], such is already done.
> >
> >I believe that you'd be safe in following
> >http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html
> >unless the git-* family of commands and documentation deviate from
> >it in a way that I am not aware of.
>
>
> For an example of a command with a long list of options try `git
> rev-parse --help`.
>
> SYNOPSIS
> git rev-parse [ --option ] <args>.
The current documentation is quite inconsistent between the two forms.
Personally, I favor the shorter form as I think the longer ones end up
quite unwieldy (see "git help rev-list" for example). But I do think the
synopsis should show the major modes of the command. You can see
examples of both in the GNU pages for "cat" and "sort":
$ man cat | sed -n '/SYNOPSIS/,${p; /^$/q}'
SYNOPSIS
cat [OPTION]... [FILE]...
$ man sort | sed -n '/SYNOPSIS/,${p; /^$/q}'
SYNOPSIS
sort [OPTION]... [FILE]...
sort [OPTION]... --files0-from=F
A similar example in git would be "git help branch", whose synopsis
should include listing mode, creation mode, deleting mode, etc.
However, I am not sure everyone on the list agrees with me on this. Last
time it came up (which was probably several years now) there was some
discussion but not enough consensus for somebody to actually go through
and standardize it.
-Peff
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
