{"thread":{"id":"17122","subject":"[PATCH/RFC] Documentation/git-mailsplit.txt: Emphasize -o more","startedAt":"2009-01-12T21:28:55Z","lastAt":"2009-01-12T22:55:30Z","messageCount":3,"participants":["jidanni@jidanni.org","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"100165","messageId":"877i50jjs8.fsf@jidanni.org","threadId":"17122","inReplyTo":null,"subject":"[PATCH/RFC] Documentation/git-mailsplit.txt: Emphasize -o more","fromName":"","fromEmail":"jidanni@jidanni.org","sentAt":"2009-01-12T21:28:55Z","receivedAt":"2009-01-12T21:28:55Z","isPatch":true,"sender":{"key":"jidanni@jidanni.org","avatar":"https://gravatar.com/avatar/36568d4af4c8d3e71627ef3b8c8d00e39065b12f29676cccd38ced75e68fa2a6?d=mp&s=160"},"body":"The need for -o cannot be overstated. Else the arguments get\ninterpreted differently. We also mention the output.\n(By the way, \"fatal: unknown option: -o\" is seen if a space comes\nafter it.)\n\nSigned-off-by: jidanni <jidanni@jidanni.org>\n---\n Documentation/git-mailsplit.txt |   11 ++++++++---\n 1 files changed, 8 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt\nindex 5cc94ec..5dc24c9 100644\n--- a/Documentation/git-mailsplit.txt\n+++ b/Documentation/git-mailsplit.txt\n@@ -13,10 +13,18 @@ DESCRIPTION\n -----------\n Splits a mbox file or a Maildir into a list of files: \"0001\" \"0002\" ..  in the\n specified directory so you can process them further from there.\n+The number of files produced is printed to the standard output.\n \n IMPORTANT: Maildir splitting relies upon filenames being sorted to output\n patches in the correct order.\n \n+REQUIRED OPTIONS\n+-------\n+-o<directory>::\n+\tDirectory in which to place the individual messages.\n+\t-o is required or else arguments may be misinterpreted in a\n+\tbackwards compatibility mode.\n+\n OPTIONS\n -------\n <mbox>::\n@@ -27,9 +35,6 @@ OPTIONS\n \tRoot of the Maildir to split. This directory should contain the cur, tmp\n \tand new subdirectories.\n \n--o<directory>::\n-\tDirectory in which to place the individual messages.\n-\n -b::\n \tIf any file doesn't begin with a From line, assume it is a\n \tsingle mail message instead of signaling error.\n-- \n1.6.0.6\n"},{"id":"100178","messageId":"7vhc44gowr.fsf@gitster.siamese.dyndns.org","threadId":"17122","inReplyTo":"877i50jjs8.fsf@jidanni.org","subject":"Re: [PATCH/RFC] Documentation/git-mailsplit.txt: Emphasize -o more","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-01-12T22:06:28Z","receivedAt":"2009-01-12T22:06:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"jidanni@jidanni.org writes:\n\n> The need for -o cannot be overstated. Else the arguments get\n> interpreted differently.\n\nI do not think there is any ambiguity with the existing SYNOPSIS.\n\n'git mailsplit' [-b] [-f<nn>] [-d<prec>] -o<directory> [--] [<mbox>|<Maildir>...]\n\n> +REQUIRED OPTIONS\n> +-------\n> +-o<directory>::\n> +\tDirectory in which to place the individual messages.\n> +\t-o is required or else arguments may be misinterpreted in a\n> +\tbackwards compatibility mode.\n> +\n\nI think you are being overly alarmist without being helpful.\n\nYou hint that there is a backwards compatible syntax but you do not say\nwhat it is, and you hint that the backwards compatible syntax is bad in\nsome unspecified way by saying \"misinterpreted\", without substantiating\nthe claim in any way.\n\nThe worst part in the new description is \"may be\", which only injects FUD\n(\"is my use trigger that pitfall? how do I decide? the manual page does\nnot say!\") without being helpful at all to the readers.\n\nProbably a better alternative would be to describe what the backward\ncompatible syntax is and what it does (which I won't do here), and mention\nsomething like the attached patchlet, without moving where -o<dir> is\ndescribed, _if_ you want to talk about it.\n\ndiff --git i/Documentation/git-mailsplit.txt w/Documentation/git-mailsplit.txt\nindex 5cc94ec..1b12014 100644\n--- i/Documentation/git-mailsplit.txt\n+++ w/Documentation/git-mailsplit.txt\n@@ -28,7 +28,10 @@ OPTIONS\n \tand new subdirectories.\n \n -o<directory>::\n-\tDirectory in which to place the individual messages.\n+\tDirectory in which to place the individual messages.  This option\n+\tis required in a modern usage of the command; when omitted, the\n+\targuments are parsed differently and the command works in a\n+\tbackward compatible mode (see below).\n \n -b::\n \tIf any file doesn't begin with a From line, assume it is a\n"},{"id":"100189","messageId":"87prisi17h.fsf@jidanni.org","threadId":"17122","inReplyTo":"7vhc44gowr.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH/RFC] Documentation/git-mailsplit.txt: Emphasize -o more","fromName":"","fromEmail":"jidanni@jidanni.org","sentAt":"2009-01-12T22:55:30Z","receivedAt":"2009-01-12T22:55:30Z","isPatch":true,"sender":{"key":"jidanni@jidanni.org","avatar":"https://gravatar.com/avatar/36568d4af4c8d3e71627ef3b8c8d00e39065b12f29676cccd38ced75e68fa2a6?d=mp&s=160"},"body":"All I know is the user had better not forget -o<directory> or else his\nprecious mailbox will be interpreted as something else... Actually the\nproblem is with builtin-mailsplit.c,\n$ git mailsplit -o\nfatal: unknown option: -o\nOne big tangle. So I would just say\n+\tcertain backward compatibility mode (that we won't detail here).\n"}]}