{"thread":{"id":"47269","subject":"pedantry: is there a standard for what should be in the SYNOPSIS?","startedAt":"2017-11-21T14:51:09Z","lastAt":"2017-11-21T21:18:05Z","messageCount":3,"participants":["Robert P. J. Day","Jonathan Nieder"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"333098","messageId":"alpine.LFD.2.21.1711210925530.6795@DESKTOP-1GPMCEJ","threadId":"47269","inReplyTo":null,"subject":"pedantry: is there a standard for what should be in the SYNOPSIS?","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-11-21T14:49:41Z","receivedAt":"2017-11-21T14:51:09Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"\n  following up on an earlier question of mine, is there a standard for\nwhat options should be listed in either the SYNOPSIS or the\nDESCRIPTION sections of a man page? i ask since i'm seeing some\ndefinite inconsistency.\n\n  in addition to the patch i submitted earlier, here are some other\nexamples.\n\n  \"man git-clone\", the SYNOPSIS says nothing about options \"--verbose\"\nor \"-v\", even though \"git clone\" supports those options and they're\nmentioned further down that man page.\n\n  on that same man page, there are a number of options that have two\nsupported forms (eg., \"-l\" and \"--local\"), but the SYNOPSIS shows only\nthe short form, while many other man pages show both (for another\nexample of this, see \"man git-clean\", which shows only the short\nforms).\n\n  also, regarding what seems to be a standard for some options, it\nseems that many commands support both options \"--verbose\" and \"-v\" to\nmean verbose operation (as long as \"-v\" isn't reserved for some other\noption for that command, which occasionally happens). in cases where\n\"-v\" is not being used, is there a reason to not just add it as an\nequivalent to \"--verbose\"?\n\n  the same thing could be said with respect to \"-n\" (as long as it's\navailable) always being the short form of \"--dry-run\". and so on, and\nso on.\n\n  oh, and i'm still wondering why some commands feel the need to\nexplain the function of \"--\", when that's the sort of thing that more\nproperly belongs in \"man gitcli\".\n\n  thoughts?\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day                                 Ottawa, Ontario, CANADA\n                        http://crashcourse.ca\n\nTwitter:                                       http://twitter.com/rpjday\nLinkedIn:                               http://ca.linkedin.com/in/rpjday\n========================================================================\n"},{"id":"333110","messageId":"20171121175436.GA27041@aiede.mtv.corp.google.com","threadId":"47269","inReplyTo":"alpine.LFD.2.21.1711210925530.6795@DESKTOP-1GPMCEJ","subject":"Re: pedantry: is there a standard for what should be in the SYNOPSIS?","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2017-11-21T17:54:36Z","receivedAt":"2017-11-21T17:55:10Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi,\n\nRobert P. J. Day wrote:\n\n> following up on an earlier question of mine, is there a standard for\n> what options should be listed in either the SYNOPSIS or the\n> DESCRIPTION sections of a man page? i ask since i'm seeing some\n> definite inconsistency.\n\nNo standard.  Seems worth starting a discussion on what you'd like the\nstandard to be.\n\nJonathan\n"},{"id":"333163","messageId":"alpine.LFD.2.21.1711211615510.25800@localhost.localdomain","threadId":"47269","inReplyTo":"20171121175436.GA27041@aiede.mtv.corp.google.com","subject":"Re: pedantry: is there a standard for what should be in the SYNOPSIS?","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-11-21T21:16:38Z","receivedAt":"2017-11-21T21:18:05Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Tue, 21 Nov 2017, Jonathan Nieder wrote:\n\n> Hi,\n>\n> Robert P. J. Day wrote:\n>\n> > following up on an earlier question of mine, is there a standard\n> > for what options should be listed in either the SYNOPSIS or the\n> > DESCRIPTION sections of a man page? i ask since i'm seeing some\n> > definite inconsistency.\n>\n> No standard.  Seems worth starting a discussion on what you'd like\n> the standard to be.\n\n  so i'm in charge? awesome. you won't regret it. :-)\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day                                 Ottawa, Ontario, CANADA\n                        http://crashcourse.ca\n\nTwitter:                                       http://twitter.com/rpjday\nLinkedIn:                               http://ca.linkedin.com/in/rpjday\n========================================================================\n"}]}