parallel.pod: --header + EXAMPLE: Using shell variables

src/parallel

@@ -541,7 +541,7 @@ sub get_options_from_array {
 sub parse_options {
     # Returns: N/A
     # Defaults:
-    $Global::version = 20120111;
+    $Global::version = 20120113;
     $Global::progname = 'parallel';
     $Global::infinity = 2**31;
     $Global::debug = 0;

src/parallel.pod

@@ -237,7 +237,7 @@ Another way to write B<-a> I<argfile1> B<-a> I<argfile2> ...
 
 B<:::> and B<::::> can be mixed.
 
-See B<-a> and B<:::>.
+See B<-a>, B<:::> and B<--xapply>.
 
 
 =item B<--null>
@@ -499,6 +499,17 @@ status will be the exit status from the failing job.
 =back
 
 
+=item B<--header> I<regexp> (alpha testing)
+
+Use upto regexp as header. For normal usage the matched header
+(typically the first line: B<--header '\n'>) will be split using
+B<--colsep> (which will default to '\t') and column names can be used
+as replacement variables: B<{column name}>. For B<--pipe> the matched
+header will be prepended to each output.
+
+B<--header :> is an alias for B<--header '\n'>.
+
+
 =item B<-I> I<replace-str>
 
 Use the replacement string I<replace-str> instead of {}.
@@ -731,9 +742,9 @@ Instead of printing the output to stdout (standard output) the output
 of each job is saved in a file and the filename is then printed.
 
 
-=item B<--pipe> (alpha testing)
+=item B<--pipe> (beta testing)
 
-=item B<--spreadstdin> (alpha testing)
+=item B<--spreadstdin> (beta testing)
 
 Spread input to jobs on stdin (standard input). Read a block of data
 from stdin (standard input) and give one block of data as input to one
@@ -925,7 +936,7 @@ it to the command.
 Only used with B<--pipe>.
 
 
-=item B<--resume>
+=item B<--resume> (alpha testing)
 
 Resumes from the last unfinished job. By reading B<--joblog> GNU
 B<parallel> will figure out the last unfinished job and continue from
@@ -1181,7 +1192,7 @@ different dir for the files. Setting B<--tmpdir> is equivalent to
 setting $TMPDIR.
 
 
-=item B<--timeout> I<sec> (alpha testing)
+=item B<--timeout> I<sec> (beta testing)
 
 Time out for command. If the command runs for longer than I<sec>
 seconds it will get killed with SIGTERM, followed by SIGTERM 200 ms
@@ -1356,11 +1367,12 @@ Exit if the size (see the B<-s> option) is exceeded.
 
 =item B<--xapply>
 
-Read multiple files like B<xapply>. If multiple B<-a> are given, one
+Read multiple input sources like B<xapply>. If multiple input sources
-line will be read from each of the files. The arguments can be
+are given, one argument will be read from each of the input
-accessed in the command as B<{1}> .. B<{>I<n>B<}>, so B<{1}> will be a
+sources. The arguments can be accessed in the command as B<{1}>
-line from the first file, and B<{6}> will refer to the line with the
+.. B<{>I<n>B<}>, so B<{1}> will be a line from the first input source, and
-same line number from the 6th file.
+B<{6}> will refer to the line with the same line number from the 6th
+input source.
 
 Compare these two:
 
@@ -1673,6 +1685,30 @@ can be written like this:
 B<cat list | parallel "do_something {} scale {.}.jpg ; do_step2 <{} {.}" | process_output>
 
 
+=head1 EXAMPLE: Using shell variables
+
+When using shell variables you need to quote them correctly as they
+may otherwise be split on spaces.
+
+Notice the difference between:
+
+ V=("My brother's 12\" records are worth <\$\$\$>"'!' Foo Bar)
+ parallel echo ::: ${V[@]} # This is probably not what you want
+
+and:
+
+ V=("My brother's 12\" records are worth <\$\$\$>"'!' Foo Bar)
+ parallel echo ::: "${V[@]}"
+
+When using variables in the actual command that contains special
+characters (e.g. space) you can quote them using B<'"$VAR"'> or using
+"'s and B<-q>:
+
+ V="Here  are  two "
+ parallel echo "'$V'" ::: spaces
+ parallel -q echo "$V" ::: spaces
+
+
 =head1 EXAMPLE: Rewriting nested for-loops
 
 Nested for-loops like this: