{"thread":{"id":"20533","subject":"[PATCH] [TRIVIAL] Documentation: merge: one is required","startedAt":"2009-08-11T13:03:58Z","lastAt":"2009-08-12T20:47:40Z","messageCount":9,"participants":["Paul Bolle","Nicolas Sebrecht","Junio C Hamano","Jakub Narebski"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"120261","messageId":"1249995838.1589.3.camel@localhost.localdomain","threadId":"20533","inReplyTo":null,"subject":"[PATCH] [TRIVIAL] Documentation: merge: one is required","fromName":"Paul Bolle","fromEmail":"pebolle@tiscali.nl","sentAt":"2009-08-11T13:03:58Z","receivedAt":"2009-08-11T13:03:58Z","isPatch":true,"sender":{"key":"pebolle@tiscali.nl","avatar":null},"body":"merge only requires one , so \"...\" should be used in the\nsynopsis (and not \" ...\").\n\nSigned-off-by: Paul Bolle \n---\n Documentation/git-merge.txt | 2 +-\n 1 files changed, 1 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex c04ae73..af68d69 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -10,7 +10,7 @@ SYNOPSIS\n --------\n [verse]\n 'git merge' [-n] [--stat] [--no-commit] [--squash] [-s ]...\n-\t[-m ] ...\n+\t[-m ] ...\n 'git merge' HEAD ...\n \n DESCRIPTION\n-- \n1.6.4\n"},{"id":"120272","messageId":"20090811144253.GA12956@vidovic","threadId":"20533","inReplyTo":"1249995838.1589.3.camel@localhost.localdomain","subject":"[PATCH] Re: [TRIVIAL] Documentation: merge: one is required","fromName":"Nicolas Sebrecht","fromEmail":"nicolas.s.dev@gmx.fr","sentAt":"2009-08-11T14:42:53Z","receivedAt":"2009-08-11T14:42:53Z","isPatch":true,"sender":{"key":"nicolas.s.dev@gmx.fr","avatar":null},"body":"The 11/08/09, Paul Bolle wrote:\n> merge only requires one , so \"...\" should be used in the\n> synopsis (and not \" ...\").\n> \n\n<...>\n\n> 'git merge' [-n] [--stat] [--no-commit] [--squash] [-s ]...\n> -\t[-m ] ...\n> +\t[-m ] ...\n> 'git merge' HEAD ...\n\nShoudn't be \n\n [-m ] [...]\n\nor\n\n [-m ] [...]\n\ninstead?\n\n-- \nNicolas Sebrecht\n"},{"id":"120275","messageId":"1250002681.2707.2.camel@localhost.localdomain","threadId":"20533","inReplyTo":"20090811144253.GA12956@vidovic","subject":"Re: [PATCH] Re: [TRIVIAL] Documentation: merge: one is required","fromName":"Paul Bolle","fromEmail":"pebolle@tiscali.nl","sentAt":"2009-08-11T14:58:01Z","receivedAt":"2009-08-11T14:58:01Z","isPatch":true,"sender":{"key":"pebolle@tiscali.nl","avatar":null},"body":"On Tue, 2009-08-11 at 16:42 +0200, Nicolas Sebrecht wrote:\n> The 11/08/09, Paul Bolle wrote:\n> > 'git merge' [-n] [--stat] [--no-commit] [--squash] [-s ]...\n> > -\t[-m ] ...\n> > +\t[-m ] ...\n> > 'git merge' HEAD ...\n> \n> Shoudn't be \n> \n> [-m ] [...]\n\nNo, since \"...\" means one or more instances of the \"\"\noption. \n\n> or\n> \n> [-m ] [...]\n\nIs \"<$something>[...]\" used anywhere? It makes little sense to me.\n\n> instead?\n\nPaul Bolle\n"},{"id":"120353","messageId":"7vy6ppbvdf.fsf@alter.siamese.dyndns.org","threadId":"20533","inReplyTo":"1250002681.2707.2.camel@localhost.localdomain","subject":"Re: [PATCH] Re: [TRIVIAL] Documentation: merge: one is required","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-08-12T02:48:12Z","receivedAt":"2009-08-12T02:48:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Paul Bolle writes:\n\n>> Shoudn't be \n>> \n>> [-m ] [...]\n>\n> No, since \"...\" means one or more instances of the \"\"\n> option. \n\nDoes it really?\n\nAfter you brought up this \"one or more\", I re-read the docs your patches\ntouched, thinking that the author might have meant 'zero or more of A'\nwith these '...' notation.\n\nAnd I realized that they made perfect sense.\n\nIn general, you can write:\n\n\t ...\n\nand read this as \"The can be followed by nothing or something\n(zero or more) of unspecified kind\". If takes only one type of\nzero or more things, you can _clarify the ellipses_ by prefixing them with\nwhat kind of \"stuff\" you are talking about:\n\n\t ...\n\nand read this as \"The can be followed by nothing or something\n(zero or more) of s\".\n\nOn the other hand, you can also say (note that the ellipses stand on their\nown and are not associated with ):\n\n\t ...\n\nand read this as \"It takes one followed by nothing or something\n(zero or more) of unspecified kind\".\n"},{"id":"120399","messageId":"m31vnhpc5v.fsf@localhost.localdomain","threadId":"20533","inReplyTo":"7vy6ppbvdf.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Re: [TRIVIAL] Documentation: merge: one is required","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2009-08-12T10:19:30Z","receivedAt":"2009-08-12T10:19:30Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Junio C Hamano writes:\n> Paul Bolle writes:\n> \n>>> Shoudn't be \n>>> \n>>> [-m ] [...]\n>>\n>> No, since \"...\" means one or more instances of the \"\"\n>> option. \n> \n> Does it really?\n> \n> After you brought up this \"one or more\", I re-read the docs your patches\n> touched, thinking that the author might have meant 'zero or more of A'\n> with these '...' notation.\n> \n> And I realized that they made perfect sense.\n> \n> In general, you can write:\n> \n> \t ...\n> \n> and read this as \"The can be followed by nothing or something\n> (zero or more) of unspecified kind\". If takes only one type of\n> zero or more things, you can _clarify the ellipses_ by prefixing them with\n> what kind of \"stuff\" you are talking about:\n> \n> \t ...\n> \n> and read this as \"The can be followed by nothing or something\n> (zero or more) of s\".\n\nI would have thought that it makes more sense to have\n\n ...\n\nfor one or more, and\n\n [... ]\n\nfor zero or more (optional one or more).\n\nDocumentation/DocumentationLanguage, anyone? ;-))))\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"120400","messageId":"1250074578.7545.2.camel@localhost.localdomain","threadId":"20533","inReplyTo":"7vy6ppbvdf.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Re: [TRIVIAL] Documentation: merge: one is required","fromName":"Paul Bolle","fromEmail":"pebolle@tiscali.nl","sentAt":"2009-08-12T10:56:18Z","receivedAt":"2009-08-12T10:56:18Z","isPatch":true,"sender":{"key":"pebolle@tiscali.nl","avatar":null},"body":"On Tue, 2009-08-11 at 19:48 -0700, Junio C Hamano wrote: \n> Paul Bolle writes:\n> > No, since \"...\" means one or more instances of the \"\"\n> > option. \n> \n> Does it really?\n> \n> After you brought up this \"one or more\", I re-read the docs your patches\n> touched, thinking that the author might have meant 'zero or more of A'\n> with these '...' notation.\n> \n> And I realized that they made perfect sense.\n> \n> In general, you can write:\n> \n> \t ...\n> \n> and read this as \"The can be followed by nothing or something\n> (zero or more) of unspecified kind\". If takes only one type of\n> zero or more things, you can _clarify the ellipses_ by prefixing them with\n> what kind of \"stuff\" you are talking about:\n> \n> \t ...\n> \n> and read this as \"The can be followed by nothing or something\n> (zero or more) of s\".\n> \n> On the other hand, you can also say (note that the ellipses stand on their\n> own and are not associated with ):\n> \n> \t ...\n> \n> and read this as \"It takes one followed by nothing or something\n> (zero or more) of unspecified kind\".\n\nIt is (now) clear to me that in these two documents the author(s) meant\n\"zero or more\". Still, I find the \"one or more\" meaning more obvious.\nThe (GNU) manpages of \"cp\", \"mv\", \"rm\", and \"ls\" use the \"one or more\"\nmeaning. (Note that the explanation quoted above can easily be rewritten\nwith for \"one or more\" meaning and still make sense.) \n\nAnyway, I now see that \"zero or more\" is used quite a lot in git's\nmanpages. But, that meaning doesn't fit so well with the\n\"[...]\" syntax that is also used a lot in these manpages. (I\nfind \"optionally one or more of \" more obvious as otherwise\n\"...\" and \"[...]\" are basically identical.)\n\nConfusingly, as far as I can see, the manpages of the following commands\nseem to use the \"one or more\" meaning:\n git merge-base\n git mv\n git name-rev\n git rm\n git send-email\n git tag -d\n git tag -v\n git verify-tag\n\n(\"git mv\" uses both meanings in its synopsis. The two \"git tag\"\ninvocations seem to do nothing with zero arguments and do not return an\nerror.)\n\nIf the above commands really use the \"one or more\" meaning, that would\nmean both versions are used in the documentation. I'd say it would be\nbetter to stick to one meaning throughout the manpages.\n\n\nPaul Bolle\n"},{"id":"120403","messageId":"20090812132924.GA28345@vidovic","threadId":"20533","inReplyTo":"m31vnhpc5v.fsf@localhost.localdomain","subject":"[PATCH] Re: [TRIVIAL] Documentation: merge: one is required","fromName":"Nicolas Sebrecht","fromEmail":"nicolas.s.dev@gmx.fr","sentAt":"2009-08-12T13:29:24Z","receivedAt":"2009-08-12T13:29:24Z","isPatch":true,"sender":{"key":"nicolas.s.dev@gmx.fr","avatar":null},"body":"The 12/08/09, Jakub Narebski wrote:\n> Junio C Hamano writes:\n>\n> > After you brought up this \"one or more\", I re-read the docs your patches\n> > touched, thinking that the author might have meant 'zero or more of A'\n> > with these '...' notation.\n> > \n> > And I realized that they made perfect sense.\n\nThis was my initial thought but...\n\n> I would have thought that it makes more sense to have\n> \n> ...\n> \n> for one or more, and\n> \n> [... ]\n> \n> for zero or more (optional one or more).\n\n...their sense is what Posix states:\n\n Ellipses ( \"...\" ) are used to denote that one or more occurrences of an\n operand are allowed. When an option or an operand followed by ellipses\n is enclosed in brackets, zero or more options or operands can be\n specified. The form:\n\n utility_name [-g option_argument]...[operand...]\n\nhttp://www.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_01\n(& 12.1.9)\n\n\n-- \nNicolas Sebrecht\n"},{"id":"120448","messageId":"7vhbwcydtn.fsf@alter.siamese.dyndns.org","threadId":"20533","inReplyTo":"1250074578.7545.2.camel@localhost.localdomain","subject":"Re: [PATCH] Re: [TRIVIAL] Documentation: merge: one is required","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-08-12T20:31:00Z","receivedAt":"2009-08-12T20:31:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Paul Bolle writes:\n\n> Confusingly, as far as I can see, the manpages of the following commands\n> seem to use the \"one or more\" meaning:\n> git merge-base\n> ...\n> (\"git mv\" uses both meanings in its synopsis. The two \"git tag\"\n> invocations seem to do nothing with zero arguments and do not return an\n> error.)\n>\n> If the above commands really use the \"one or more\" meaning, that would\n> mean both versions are used in the documentation. I'd say it would be\n> better to stick to one meaning throughout the manpages.\n\nYou are absolutely right. We would want consistency.\n\nI do not have any objection to make sure that we uniformly use ellipses\nfor one-or-more (and enclose them in [] if we want zero-or-more). Are\nthese two that your patch touched the only ones that need fixing?\n"},{"id":"120452","messageId":"1250110060.2500.8.camel@x61.thuisdomein","threadId":"20533","inReplyTo":"7vhbwcydtn.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Re: [TRIVIAL] Documentation: merge: one is required","fromName":"Paul Bolle","fromEmail":"pebolle@tiscali.nl","sentAt":"2009-08-12T20:47:40Z","receivedAt":"2009-08-12T20:47:40Z","isPatch":true,"sender":{"key":"pebolle@tiscali.nl","avatar":null},"body":"On Wed, 2009-08-12 at 13:31 -0700, Junio C Hamano wrote:\n> Paul Bolle writes:\n> I do not have any objection to make sure that we uniformly use ellipses\n> for one-or-more (and enclose them in [] if we want zero-or-more). Are\n> these two that your patch touched the only ones that need fixing?\n\nI guess not (these two were the ones that annoyed me enough to write\npatches when I read them in order to learn more about the commands they\ndescribed).\n\nWhat is the best way to fix small issues like this: one set of patches\nthat tries to fix as much as possible in one go or a stream of little\npatches whenever similar issues are found in one of the documents?\n"}]}