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 majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html