From de6d5888938c13dedebd7761861a90ff675700a0 Mon Sep 17 00:00:00 2001
From: Ole Tange <ole@tange.dk>
Date: Mon, 27 Jun 2011 23:21:26 +0200
Subject: [PATCH] Fixed: #33629: Update documentation for -X to reflect current
 behavior. --help give one line description of the options I use mostly.

---
 src/parallel     | 30 ++++++++++++++++++++++++------
 src/parallel.pod | 19 +++++++++++++------
 2 files changed, 37 insertions(+), 12 deletions(-)

diff --git a/src/parallel b/src/parallel
index 2996a56d..d29a8e57 100755
--- a/src/parallel
+++ b/src/parallel
@@ -1641,12 +1641,30 @@ sub die_usage {
 
 sub usage {
     # Returns: N/A
-    print "Usage:\n";
-    print "$Global::progname [options] [command [arguments]] < list_of_arguments\n";
-    print "$Global::progname [options] [command [arguments]] ::: arguments\n";
-    print "$Global::progname [options] [command [arguments]] :::: argfile(s)\n";
-    print "\n";
-    print "See 'man $Global::progname' for the options\n";
+    print join
+	("\n",
+	 "Usage:",
+	 "$Global::progname [options] [command [arguments]] < list_of_arguments",
+	 "$Global::progname [options] [command [arguments]] (::: arguments|:::: argfile(s))...",
+	 "",
+	 "-j n       Run n jobs in parallel",
+	 "-k         Keep same order",
+	 "-X         Multiple arguments with context replace",
+	 "--colsep regexp  Split input on regexp for positional replacements",
+	 "{} {.} {/} {/.}  Replacement strings",
+	 "{3} {3.} {3/} {3/.}  Positional replacement strings",
+	 "",
+	 "-S         sshlogin - e.g. foo\@server.example.com",
+	 "--trc {}.bar  Shorthand for --transfer --return {}.bar --cleanup",
+	 "--onall    Run the given command with argument on all sshlogins",
+	 "--nonall   Run the given command with no arguments on all sshlogins",
+	 "",
+	 "--pipe     Split stdin (standard input) to multiple jobs.",
+	 "--recend   Record end separator for --pipe.",
+	 "--recstart Record start separator for --pipe.",
+	 "",
+	 "See 'man $Global::progname' for details",
+	 "");
 }
 
 sub die_bug {
diff --git a/src/parallel.pod b/src/parallel.pod
index 0e83e579..efd92301 100644
--- a/src/parallel.pod
+++ b/src/parallel.pod
@@ -610,8 +610,11 @@ that specify their own ssh command.
 
 =item B<-m>
 
-Multiple. Insert as many arguments as the command line length
-permits. If B<{}> is not used the arguments will be appended to the
+Multiple arguments. Insert as many arguments as the command line
+length permits. If multiple jobs are being run in parallel: distribute
+the arguments evenly among the jobs. Use B<-j1> to avoid this.
+
+If B<{}> is not used the arguments will be appended to the
 line.  If B<{}> is used multiple times each B<{}> will be replaced
 with all the arguments.
 
@@ -1221,10 +1224,14 @@ See also: B<man sem>
 =item B<-X>
 
 Multiple arguments with context replace. Insert as many arguments as
-the command line length permits. If B<{}> is not used the arguments
-will be appended to the line.  If B<{}> is used as part of a word
-(like I<pic{}.jpg>) then the whole word will be repeated. If B<{}> is
-used multiple times each B<{}> will be replaced with the arguments.
+the command line length permits. If multiple jobs are being run in
+parallel: distribute the arguments evenly among the jobs. Use B<-j1>
+to avoid this.
+
+If B<{}> is not used the arguments will be appended to the line.  If
+B<{}> is used as part of a word (like I<pic{}.jpg>) then the whole
+word will be repeated. If B<{}> is used multiple times each B<{}> will
+be replaced with the arguments.
 
 Normally B<-X> will do the right thing, whereas B<-m> can give
 unexpected results if B<{}> is used as part of a word.