{"thread":{"id":"48601","subject":"verifying syntax for optional and replaceable content in man pages","startedAt":"2018-05-30T11:41:20Z","lastAt":"2018-05-30T18:10:58Z","messageCount":3,"participants":["Robert P. J. Day","Stefan Beller"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"348803","messageId":"alpine.LFD.2.21.1805300733440.10096@localhost.localdomain","threadId":"48601","inReplyTo":null,"subject":"verifying syntax for optional and replaceable content in man pages","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2018-05-30T11:39:15Z","receivedAt":"2018-05-30T11:41:20Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"\n willing to submit some patches to standardize the syntax of man\npages in terms of rendering \"optional\" and/or \"replaceable\" content,\nand it seems like \"man git-config\" would be a good place to start:\n\nSYNOPSIS\n git config [] [type] [--show-origin] [-z|--null] name [value [value_regex]]\n git config [] [type] --add name value\n git config [] [type] --replace-all name value [value_regex]\n ...snip ...\n\n can i assume the proper (uniform) syntax for the above would be\n(shortening lines):\n\n ... [] [--show-origin] [-z|--null] [ []]\n ... [] --add \n ... [] --replace-all []\n\nand so on. is that the consensus? i wouldn't try to do it all at once,\nmaybe just a page at a time to not be too disruptive.\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day Ottawa, Ontario, CANADA\n http://crashcourse.ca/dokuwiki\n\nTwitter: http://twitter.com/rpjday\nLinkedIn: http://ca.linkedin.com/in/rpjday\n========================================================================\n"},{"id":"348823","messageId":"CAGZ79kbdbV8r6Vr06ECOy9XXnBO_r=F-XcQU3WCCtOuCr0cfiQ@mail.gmail.com","threadId":"48601","inReplyTo":"alpine.LFD.2.21.1805300733440.10096@localhost.localdomain","subject":"Re: verifying syntax for optional and replaceable content in man pages","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2018-05-30T17:54:02Z","receivedAt":"2018-05-30T17:54:07Z","isPatch":false,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Wed, May 30, 2018 at 4:39 AM, Robert P. J. Day wrote:\n>\n> willing to submit some patches to standardize the syntax of man\n> pages in terms of rendering \"optional\" and/or \"replaceable\" content,\n> and it seems like \"man git-config\" would be a good place to start:\n>\n> SYNOPSIS\n> git config [] [type] [--show-origin] [-z|--null] name [value [value_regex]]\n> git config [] [type] --add name value\n> git config [] [type] --replace-all name value [value_regex]\n> ...snip ...\n>\n> can i assume the proper (uniform) syntax for the above would be\n> (shortening lines):\n>\n> ... [] [--show-origin] [-z|--null] [ []]\n\nSo the difference are the angle brackets around 'name', otherwise no change?\n\n> ... [] --add \n\nall the same but angle brackets around name and value,\n\n> ... [] --replace-all []\n\nsame.\n\n> and so on. is that the consensus? i wouldn't try to do it all at once,\n> maybe just a page at a time to not be too disruptive.\n\nI would think there is consensus for unifying the syntax across all man pages\nand put variable texts (name, path, key, value, etc) into angle brackets.\n\nI used git-blame to find all the changes throughout history touching\nthe first line\nof the synopsis (or rather: I used gitk, right click \"show origin of line\"),\nand there were no edit wars whether to use angle brackets or not; it looks like\nnobody cared or paid attention since the first revision of that line, which is\n\n git-config' [--global] [type] name [value [value_regex]]\n\nfrom e0d10e1c63b ([PATCH] Rename git-repo-config to git-config., 2007-01-28)\n\nThanks for taking care of these!\nStefan\n"},{"id":"348824","messageId":"alpine.LFD.2.21.1805301405200.9810@localhost.localdomain","threadId":"48601","inReplyTo":"CAGZ79kbdbV8r6Vr06ECOy9XXnBO_r=F-XcQU3WCCtOuCr0cfiQ@mail.gmail.com","subject":"Re: verifying syntax for optional and replaceable content in man pages","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2018-05-30T18:08:54Z","receivedAt":"2018-05-30T18:10:58Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Wed, 30 May 2018, Stefan Beller wrote:\n\n> On Wed, May 30, 2018 at 4:39 AM, Robert P. J. Day wrote:\n> >\n> > willing to submit some patches to standardize the syntax of man\n> > pages in terms of rendering \"optional\" and/or \"replaceable\"\n> > content, and it seems like \"man git-config\" would be a good place\n> > to start:\n> >\n> > SYNOPSIS\n> > git config [] [type] [--show-origin] [-z|--null] name [value [value_regex]]\n> > git config [] [type] --add name value\n> > git config [] [type] --replace-all name value [value_regex]\n> > ...snip ...\n> >\n> > can i assume the proper (uniform) syntax for the above would be\n> > (shortening lines):\n> >\n> > ... [] [--show-origin] [-z|--null] [ []]\n>\n> So the difference are the angle brackets around 'name', otherwise no\n> change?\n\n more precisely, angle brackets would represent any \"replaceable\"\ncontent, regardless of where it occurs.\n>\n> > ... [] --add \n>\n> all the same but angle brackets around name and value,\n\n same rationale as above, [<...>] would represent both optional *and*\nreplaceable content. and so on, and so on.\n\n the only other obvious inconsistency i've seen is, when referring to\nan environment variable, i've seen both of:\n\n `VARIABLE`\n `$VARIABLE`\n\nmy personal preference is the one without the $ if just referring to\nthe variable, without trying to dereference it. but that's just me.\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day Ottawa, Ontario, CANADA\n http://crashcourse.ca/dokuwiki\n\nTwitter: http://twitter.com/rpjday\nLinkedIn: http://ca.linkedin.com/in/rpjday\n========================================================================\n"}]}