threads / rfc / 17122

RFC patchDocumentation/git-mailsplit.txt: Emphasize -o more

Subject: [PATCH/RFC] Documentation/git-mailsplit.txt: Emphasize -o more

## tl;dr

3 messages between Jan 12, 2009 and Jan 12, 2009. Diffs are folded; open one to read it.

replies: 2people: 2as markdown or json

jidanni@jidanni.org· Jan 12, 2009, 21:28 UTC · lore

The need for -o cannot be overstated. Else the arguments get interpreted differently. We also mention the output. (By the way, "fatal: unknown option: -o" is seen if a space comes after it.)

Signed-off-by: jidanni <jidanni@jidanni.org>
---
 Documentation/git-mailsplit.txt |   11 ++++++++---
 1 files changed, 8 insertions(+), 3 deletions(-)

Show changes to Documentation/git-mailsplit.txt +8 −3

diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt
index 5cc94ec..5dc24c9 100644
--- a/Documentation/git-mailsplit.txt
+++ b/Documentation/git-mailsplit.txt
@@ -13,10 +13,18 @@ DESCRIPTION
 -----------
 Splits a mbox file or a Maildir into a list of files: "0001" "0002" ..  in the
 specified directory so you can process them further from there.
+The number of files produced is printed to the standard output.
 
 IMPORTANT: Maildir splitting relies upon filenames being sorted to output
 patches in the correct order.
 
+REQUIRED OPTIONS
+-------
+-o<directory>::
+	Directory in which to place the individual messages.
+	-o is required or else arguments may be misinterpreted in a
+	backwards compatibility mode.
+
 OPTIONS
 -------
 <mbox>::
@@ -27,9 +35,6 @@ OPTIONS
 	Root of the Maildir to split. This directory should contain the cur, tmp
 	and new subdirectories.
 
--o<directory>::
-	Directory in which to place the individual messages.
-
 -b::
 	If any file doesn't begin with a From line, assume it is a
 	single mail message instead of signaling error.

-- 
1.6.0.6

Junio C Hamano· Jan 12, 2009, 22:06 UTC · re: jidanni@jidanni.org · lore

Re: [PATCH/RFC] Documentation/git-mailsplit.txt: Emphasize -o more

jidanni@jidanni.org writes:

> The need for -o cannot be overstated. Else the arguments get
> interpreted differently.

I do not think there is any ambiguity with the existing SYNOPSIS.

'git mailsplit' [-b] [-f<nn>] [-d<prec>] -o<directory> [--] [<mbox>|<Maildir>...]

Show 7 quoted lines

> +REQUIRED OPTIONS
> +-------
> +-o<directory>::
> +	Directory in which to place the individual messages.
> +	-o is required or else arguments may be misinterpreted in a
> +	backwards compatibility mode.
> +

I think you are being overly alarmist without being helpful.

You hint that there is a backwards compatible syntax but you do not say what it is, and you hint that the backwards compatible syntax is bad in some unspecified way by saying "misinterpreted", without substantiating the claim in any way.

The worst part in the new description is "may be", which only injects FUD ("is my use trigger that pitfall? how do I decide? the manual page does not say!") without being helpful at all to the readers.

Probably a better alternative would be to describe what the backward compatible syntax is and what it does (which I won't do here), and mention something like the attached patchlet, without moving where -o<dir> is described, _if_ you want to talk about it.

Show changes to diff +4 −1

diff --git i/Documentation/git-mailsplit.txt w/Documentation/git-mailsplit.txt
index 5cc94ec..1b12014 100644
--- i/Documentation/git-mailsplit.txt
+++ w/Documentation/git-mailsplit.txt
@@ -28,7 +28,10 @@ OPTIONS
 	and new subdirectories.
 
 -o<directory>::
-	Directory in which to place the individual messages.
+	Directory in which to place the individual messages.  This option
+	is required in a modern usage of the command; when omitted, the
+	arguments are parsed differently and the command works in a
+	backward compatible mode (see below).
 
 -b::
 	If any file doesn't begin with a From line, assume it is a

jidanni@jidanni.org· Jan 12, 2009, 22:55 UTC · re: Junio C Hamano · lore

Re: [PATCH/RFC] Documentation/git-mailsplit.txt: Emphasize -o more

All I know is the user had better not forget -o<directory> or else his precious mailbox will be interpreted as something else... Actually the problem is with builtin-mailsplit.c, $ git mailsplit -o fatal: unknown option: -o One big tangle. So I would just say + certain backward compatibility mode (that we won't detail here).