From: Philip Oakley <philipoakley@iee.org>
Date: Wed, 09 Oct 2013 22:35:19 GMT
Subject: Re: [RFC] Documentation: --options in man-pages synopsys
Message-ID: <AB54BA13FC634F47B15CFE796CECADC4@PhilipOakley>
In-Reply-To: <FCEE4469EE8B234199968ECA9B0661E230EC61C0@STNEEX10MB01.stone.ne.gov>

From: "Loyall, David" <david.loyall@nebraska.gov>
Sent: Tuesday, October 08, 2013 3:03 PM
> 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>.

Philip

>
> Hope this helps,
> --Dave
>
>> -----Original Message-----
>> From: git-owner@vger.kernel.org [mailto:git-owner@vger.kernel.org] On
>> Behalf Of Dmitry Ivankov
>> Sent: Tuesday, October 08, 2013 7:07 AM
>> To: Git List
>> Subject: [RFC] Documentation: --options in man-pages synopsys
>>
>> Hi,
>>
>> I've noticed that man git-pack-objects describes cmdline as following
>>
>> SYNOPSYS
>> 'git pack-objects' [-q | --progress | --all-progress] 
>> [--all-progress-implied] [--
>> no-reuse-delta] [--delta-base-offset] [--non-empty] [--local] 
>> [--incremental]
>> [--window=<n>] [--depth=<n>] [--revs [--unpacked | --all]] [--stdout 
>> | base-
>> name] [--keep-true-parents] < object-list
>>
>> while OPTIONS sections has even more options, --no-reuse-objects for
>> instance.
>>
>> Should it be dealt with and how?
>> - add smth like ... at the tail of options in synopsys to indicate 
>> that there are
>> more options
>> - add all the [--options] to synopsys
>> - drop all the [--options] as they all are optional
>> - pick only the most common/important ones like -q --progress, per
>> command or per command classes (hard to maintain and/or verify?)
>> --
>> To unsubscribe from this list: send the line "unsubscribe git" in the 
>> body of a
>> message to majordomo@vger.kernel.org More majordomo info at
>> http://vger.kernel.org/majordomo-info.html
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>