{"thread":{"id":"35081","subject":"[RFC] Documentation: --options in man-pages synopsys","startedAt":"2013-10-08T12:07:07Z","lastAt":"2013-10-10T01:52:55Z","messageCount":4,"participants":["Dmitry Ivankov","Loyall, David","Philip Oakley","Jeff King"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"228608","messageId":"CA+gfSn-o7cH3a-KWx_iggNc4-rYzQysbTj7OGdaggutLu-X-BA@mail.gmail.com","threadId":"35081","inReplyTo":null,"subject":"[RFC] Documentation: --options in man-pages synopsys","fromName":"Dmitry Ivankov","fromEmail":"divanorama@gmail.com","sentAt":"2013-10-08T12:07:07Z","receivedAt":"2013-10-08T12:07:07Z","isPatch":false,"sender":{"key":"divanorama@gmail.com","avatar":"https://avatars.githubusercontent.com/u/158999?v=4"},"body":"Hi,\n\nI've noticed that man git-pack-objects describes cmdline as following\n\nSYNOPSYS\n'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied]\n[--no-reuse-delta] [--delta-base-offset] [--non-empty]\n[--local] [--incremental] [--window=] [--depth=]\n[--revs [--unpacked | --all]] [--stdout | base-name]\n[--keep-true-parents] < object-list\n\nwhile OPTIONS sections has even more options, --no-reuse-objects for instance.\n\nShould it be dealt with and how?\n- add smth like ... at the tail of options in synopsys to indicate\nthat there are more options\n- add all the [--options] to synopsys\n- drop all the [--options] as they all are optional\n- pick only the most common/important ones like -q --progress, per\ncommand or per command classes (hard to maintain and/or verify?)\n"},{"id":"228609","messageId":"FCEE4469EE8B234199968ECA9B0661E230EC61C0@STNEEX10MB01.stone.ne.gov","threadId":"35081","inReplyTo":"CA+gfSn-o7cH3a-KWx_iggNc4-rYzQysbTj7OGdaggutLu-X-BA@mail.gmail.com","subject":"RE: [RFC] Documentation: --options in man-pages synopsys","fromName":"Loyall, David","fromEmail":"david.loyall@nebraska.gov","sentAt":"2013-10-08T14:03:03Z","receivedAt":"2013-10-08T14:03:03Z","isPatch":false,"sender":{"key":"david.loyall@nebraska.gov","avatar":null},"body":"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.\n\nI 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.\n\nHope this helps,\n--Dave\n\n> -----Original Message-----\n> From: git-owner@vger.kernel.org [mailto:git-owner@vger.kernel.org] On\n> Behalf Of Dmitry Ivankov\n> Sent: Tuesday, October 08, 2013 7:07 AM\n> To: Git List\n> Subject: [RFC] Documentation: --options in man-pages synopsys\n> \n> Hi,\n> \n> I've noticed that man git-pack-objects describes cmdline as following\n> \n> SYNOPSYS\n> 'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied] [--\n> no-reuse-delta] [--delta-base-offset] [--non-empty] [--local] [--incremental]\n> [--window=] [--depth=] [--revs [--unpacked | --all]] [--stdout | base-\n> name] [--keep-true-parents] < object-list\n> \n> while OPTIONS sections has even more options, --no-reuse-objects for\n> instance.\n> \n> Should it be dealt with and how?\n> - add smth like ... at the tail of options in synopsys to indicate that there are\n> more options\n> - add all the [--options] to synopsys\n> - drop all the [--options] as they all are optional\n> - pick only the most common/important ones like -q --progress, per\n> command or per command classes (hard to maintain and/or verify?)\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in the body of a\n> message to majordomo@vger.kernel.org More majordomo info at\n> http://vger.kernel.org/majordomo-info.html\n"},{"id":"228677","messageId":"AB54BA13FC634F47B15CFE796CECADC4@PhilipOakley","threadId":"35081","inReplyTo":"FCEE4469EE8B234199968ECA9B0661E230EC61C0@STNEEX10MB01.stone.ne.gov","subject":"Re: [RFC] Documentation: --options in man-pages synopsys","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2013-10-09T22:35:19Z","receivedAt":"2013-10-09T22:35:19Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Loyall, David\" \nSent: Tuesday, October 08, 2013 3:03 PM\n> As a unix user I'd expect the SYNOPSIS section at the top of the man \n> page to include all options that the command accepts. Mutually \n> exclusive options are expected to be in the form [-q | --progress \n> | --all-progress], such is already done.\n>\n> I believe that you'd be safe in following \n> http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html \n> unless the git-* family of commands and documentation deviate from it \n> in a way that I am not aware of.\n\n\nFor an example of a command with a long list of options try `git \nrev-parse --help`.\n\nSYNOPSIS\n git rev-parse [ --option ] .\n\nPhilip\n\n>\n> Hope this helps,\n> --Dave\n>\n>> -----Original Message-----\n>> From: git-owner@vger.kernel.org [mailto:git-owner@vger.kernel.org] On\n>> Behalf Of Dmitry Ivankov\n>> Sent: Tuesday, October 08, 2013 7:07 AM\n>> To: Git List\n>> Subject: [RFC] Documentation: --options in man-pages synopsys\n>>\n>> Hi,\n>>\n>> I've noticed that man git-pack-objects describes cmdline as following\n>>\n>> SYNOPSYS\n>> 'git pack-objects' [-q | --progress | --all-progress] \n>> [--all-progress-implied] [--\n>> no-reuse-delta] [--delta-base-offset] [--non-empty] [--local] \n>> [--incremental]\n>> [--window=] [--depth=] [--revs [--unpacked | --all]] [--stdout \n>> | base-\n>> name] [--keep-true-parents] < object-list\n>>\n>> while OPTIONS sections has even more options, --no-reuse-objects for\n>> instance.\n>>\n>> Should it be dealt with and how?\n>> - add smth like ... at the tail of options in synopsys to indicate \n>> that there are\n>> more options\n>> - add all the [--options] to synopsys\n>> - drop all the [--options] as they all are optional\n>> - pick only the most common/important ones like -q --progress, per\n>> command or per command classes (hard to maintain and/or verify?)\n>> --\n>> To unsubscribe from this list: send the line \"unsubscribe git\" in the \n>> body of a\n>> message to majordomo@vger.kernel.org More majordomo info at\n>> http://vger.kernel.org/majordomo-info.html\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at http://vger.kernel.org/majordomo-info.html\n> \n"},{"id":"228682","messageId":"20131010015255.GB15106@sigill.intra.peff.net","threadId":"35081","inReplyTo":"AB54BA13FC634F47B15CFE796CECADC4@PhilipOakley","subject":"Re: [RFC] Documentation: --options in man-pages synopsys","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2013-10-10T01:52:55Z","receivedAt":"2013-10-10T01:52:55Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Oct 09, 2013 at 11:35:19PM +0100, Philip Oakley wrote:\n\n> >As a unix user I'd expect the SYNOPSIS section at the top of the\n> >man page to include all options that the command accepts. Mutually\n> >exclusive options are expected to be in the form [-q | --progress |\n> >--all-progress], such is already done.\n> >\n> >I believe that you'd be safe in following http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html\n> >unless the git-* family of commands and documentation deviate from\n> >it in a way that I am not aware of.\n> \n> \n> For an example of a command with a long list of options try `git\n> rev-parse --help`.\n> \n> SYNOPSIS\n> git rev-parse [ --option ] .\n\nThe current documentation is quite inconsistent between the two forms.\nPersonally, I favor the shorter form as I think the longer ones end up\nquite unwieldy (see \"git help rev-list\" for example). But I do think the\nsynopsis should show the major modes of the command. You can see\nexamples of both in the GNU pages for \"cat\" and \"sort\":\n\n $ man cat | sed -n '/SYNOPSIS/,${p; /^$/q}'\n SYNOPSIS\n cat [OPTION]... [FILE]...\n\n $ man sort | sed -n '/SYNOPSIS/,${p; /^$/q}'\n SYNOPSIS\n sort [OPTION]... [FILE]...\n sort [OPTION]... --files0-from=F\n\nA similar example in git would be \"git help branch\", whose synopsis\nshould include listing mode, creation mode, deleting mode, etc.\n\nHowever, I am not sure everyone on the list agrees with me on this. Last\ntime it came up (which was probably several years now) there was some\ndiscussion but not enough consensus for somebody to actually go through\nand standardize it.\n\n-Peff\n"}]}