parallel: Moved examples to parallel_examples.

doc/haikus

@@ -4,6 +4,15 @@
  
 Quote of the month:
 
+  I've learned a lot during my internship, but getting even slightly more proficient with GNU parallel is probably the most important thing I've learned...
+    -- Elijah Rippeth @terrible_coder@twitter
+
+  reduced our backend test pipelines from 4 to 1.30 hrs. gnu parallel for the win!!!
+     -- Swapnil Sahu @CaffeinatedWryy@twitter
+
+  I honestly don't know how I'd survive without @Docker and @GNU_Parallel
+    -- Eric Pauley @EricPauley_@twitter
+
   Gnu parallel is indeed slick. I always try to align my data to make it possible to loop over it with a nice for loop added in a call to run the jobs in parallel then becomes super easy. I love the {1..99} syntax in bash.
     -- ragsofx
 

src/Makefile.am

@@ -14,24 +14,28 @@ install-exec-hook:
 
 if DOCUMENTATION
 man_MANS = parallel.1 env_parallel.1 sem.1 sql.1 niceload.1		\
-	parallel_tutorial.7 parallel_book.7 parallel_design.7	\
+	parallel_examples.7 parallel_tutorial.7 parallel_book.7		\
-	parallel_alternatives.7 parcat.1 parset.1 parsort.1
+	parallel_design.7 parallel_alternatives.7 parcat.1 parset.1	\
+	parsort.1
 doc_DATA = parallel.html env_parallel.html sem.html sql.html		\
-	niceload.html parallel_tutorial.html parallel_book.html		\
+	niceload.html parallel_examples.html parallel_tutorial.html	\
-	parallel_design.html parallel_alternatives.html parcat.html	\
+	parallel_book.html parallel_design.html				\
-	parset.html parsort.html \
+	parallel_alternatives.html parcat.html parset.html		\
+	parsort.html \
 	parallel.texi env_parallel.texi sem.texi sql.texi		\
-	niceload.texi parallel_tutorial.texi parallel_book.texi		\
+	niceload.texi parallel_examples.texi parallel_tutorial.texi	\
-	parallel_design.texi parallel_alternatives.texi parcat.texi	\
+	parallel_book.texi parallel_design.texi				\
-	parset.texi parsort.texi \
+	parallel_alternatives.texi parcat.texi parset.texi		\
-        parallel.rst env_parallel.rst sem.rst sql.rst 			\
+	parsort.texi \
-	niceload.rst parallel_tutorial.rst parallel_book.rst		\
+	parallel.rst env_parallel.rst sem.rst sql.rst niceload.rst	\
+	parallel_examples.rst parallel_tutorial.rst parallel_book.rst	\
 	parallel_design.rst parallel_alternatives.rst parcat.rst	\
 	parset.rst parsort.rst \
 	parallel.pdf env_parallel.pdf sem.pdf sql.pdf niceload.pdf	\
-	parallel_tutorial.pdf parallel_book.pdf parallel_design.pdf	\
+	parallel_examples.pdf parallel_tutorial.pdf parallel_book.pdf	\
-	parallel_alternatives.pdf parcat.pdf parset.pdf	parsort.pdf 	\
+	parallel_design.pdf parallel_alternatives.pdf parcat.pdf	\
-	parallel_cheat_bw.pdf parallel_options_map.pdf
+	parset.pdf parsort.pdf parallel_cheat_bw.pdf			\
+	parallel_options_map.pdf
 endif
 
 web: sphinx
@@ -54,6 +58,12 @@ env_parallel.1: env_parallel.pod
 	&& mv "$(srcdir)"/env_parallel.1n "$(srcdir)"/env_parallel.1 \
 	|| echo "Warning: pod2man not found. Using old env_parallel.1"
 
+parallel_examples.7: parallel_examples.pod
+	pod2man --release='$(PACKAGE_VERSION)' --center='$(PACKAGE_NAME)' \
+		--section=7 "$(srcdir)"/parallel_examples.pod > "$(srcdir)"/parallel_examples.7n \
+	&& mv "$(srcdir)"/parallel_examples.7n "$(srcdir)"/parallel_examples.7 \
+	|| echo "Warning: pod2man not found. Using old parallel_examples.7"
+
 parallel_tutorial.7: parallel_tutorial.pod
 	pod2man --release='$(PACKAGE_VERSION)' --center='$(PACKAGE_NAME)' \
 		--section=7 "$(srcdir)"/parallel_tutorial.pod > "$(srcdir)"/parallel_tutorial.7n \
@@ -128,6 +138,13 @@ env_parallel.html: env_parallel.pod parallel.html
 	rm -f "$(srcdir)"/pod2htm*
 
 # Depending on env_parallel.html to avoid stupid pod2html race condition
+parallel_examples.html: parallel_examples.pod env_parallel.html
+	pod2html --title "GNU Parallel examples" "$(srcdir)"/parallel_examples.pod > "$(srcdir)"/parallel_examples.htmln \
+	&& mv "$(srcdir)"/parallel_examples.htmln "$(srcdir)"/parallel_examples.html \
+	|| echo "Warning: pod2html not found. Using old parallel_examples.html"
+	rm -f "$(srcdir)"/pod2htm*
+
+# Depending on parallel_examples.html to avoid stupid pod2html race condition
 parallel_tutorial.html: parallel_tutorial.pod env_parallel.html
 	pod2html --title "GNU Parallel tutorial" "$(srcdir)"/parallel_tutorial.pod > "$(srcdir)"/parallel_tutorial.htmln \
 	&& mv "$(srcdir)"/parallel_tutorial.htmln "$(srcdir)"/parallel_tutorial.html \
@@ -205,6 +222,10 @@ env_parallel.texi: env_parallel.pod
 	pod2texi --output="$(srcdir)"/env_parallel.texi "$(srcdir)"/env_parallel.pod \
 	|| echo "Warning: pod2texi not found. Using old env_parallel.texi"
 
+parallel_examples.texi: parallel_examples.pod
+	pod2texi --output="$(srcdir)"/parallel_examples.texi "$(srcdir)"/parallel_examples.pod \
+	|| echo "Warning: pod2texi not found. Using old parallel_examples.texi"
+
 parallel_tutorial.texi: parallel_tutorial.pod
 	pod2texi --output="$(srcdir)"/parallel_tutorial.texi "$(srcdir)"/parallel_tutorial.pod \
 	|| echo "Warning: pod2texi not found. Using old parallel_tutorial.texi"
@@ -253,6 +274,10 @@ env_parallel.rst: env_parallel.pod
 	./pod2rst-fix < "$(srcdir)"/env_parallel.pod > "$(srcdir)"/env_parallel.rst \
 	|| echo "Warning: pod2rst not found. Using old env_parallel.rst"
 
+parallel_examples.rst: parallel_examples.pod
+	./pod2rst-fix < "$(srcdir)"/parallel_examples.pod > "$(srcdir)"/parallel_examples.rst \
+	|| echo "Warning: pod2rst not found. Using old parallel_examples.rst"
+
 parallel_tutorial.rst: parallel_tutorial.pod
 	./pod2rst-fix < "$(srcdir)"/parallel_tutorial.pod > "$(srcdir)"/parallel_tutorial.rst \
 	|| echo "Warning: pod2rst not found. Using old parallel_tutorial.rst"
@@ -301,6 +326,10 @@ env_parallel.pdf: env_parallel.pod
 	pod2pdf --output-file "$(srcdir)"/env_parallel.pdf "$(srcdir)"/env_parallel.pod --title "GNU Parallel with environment" \
 	|| echo "Warning: pod2pdf not found. Using old env_parallel.pdf"
 
+parallel_examples.pdf: parallel_examples.pod
+	pod2pdf --output-file "$(srcdir)"/parallel_examples.pdf "$(srcdir)"/parallel_examples.pod --title "GNU Parallel Examples" \
+	|| echo "Warning: pod2pdf not found. Using old parallel_examples.pdf"
+
 parallel_tutorial.pdf: parallel_tutorial.pod
 	pod2pdf --output-file "$(srcdir)"/parallel_tutorial.pdf "$(srcdir)"/parallel_tutorial.pod --title "GNU Parallel Tutorial" \
 	|| echo "Warning: pod2pdf not found. Using old parallel_tutorial.pdf"
@@ -353,23 +382,28 @@ sem: parallel
 	ln -fs parallel sem
 
 DISTCLEANFILES = parallel.1 env_parallel.1 sem.1 sql.1 niceload.1	\
-	parallel_tutorial.7 parallel_book.7 parallel_design.7		\
+	parallel_examples.7 parallel_tutorial.7 parallel_book.7		\
-	parallel_alternatives.7 parcat.1 parset.1 parsort.1		\
+	parallel_design.7 parallel_alternatives.7 parcat.1 parset.1	\
+	parsort.1 \
 	parallel.html env_parallel.html sem.html sql.html		\
-	niceload.html parallel_tutorial.html parallel_book.html		\
+	niceload.html parallel_examples.html parallel_tutorial.html	\
-	parallel_design.html parallel_alternatives.html parcat.html	\
+	parallel_book.html parallel_design.html				\
-	parset.html parsort.html parallel.texi env_parallel.texi	\
+	parallel_alternatives.html parcat.html parset.html		\
-	sem.texi sql.texi niceload.texi parallel_tutorial.texi		\
+	parsort.html \
+	parallel.texi env_parallel.texi sem.texi sql.texi		\
+	niceload.texi parallel_examples.texi parallel_tutorial.texi	\
 	parallel_book.texi parallel_design.texi				\
 	parallel_alternatives.texi parcat.texi parset.texi		\
 	parsort.texi \
 	parallel.rst env_parallel.rst sem.rst sql.rst niceload.rst	\
-	parallel_tutorial.rst parallel_book.rst parallel_design.rst	\
+	parallel_examples.rst parallel_tutorial.rst parallel_book.rst	\
-	parallel_alternatives.rst parcat.rst parset.rst parsort.rst	\
+	parallel_design.rst parallel_alternatives.rst parcat.rst	\
+	parset.rst parsort.rst \
 	parallel.pdf env_parallel.pdf sem.pdf sql.pdf niceload.pdf	\
-	parallel_tutorial.pdf parallel_book.pdf parallel_design.pdf	\
+	parallel_examples.pdf parallel_tutorial.pdf parallel_book.pdf	\
-	parallel_alternatives.pdf parcat.pdf parset.pdf parsort.pdf	\
+	parallel_design.pdf parallel_alternatives.pdf parcat.pdf	\
-	parallel_cheat_bw.pdf parallel_options_map.pdf
+	parset.pdf parsort.pdf parallel_cheat_bw.pdf			\
+	parallel_options_map.pdf
 
 EXTRA_DIST = parallel sem sql niceload parcat parset parsort		\
 	env_parallel env_parallel.ash env_parallel.bash			\
@@ -377,6 +411,6 @@ EXTRA_DIST = parallel sem sql niceload parcat parset parsort		\
 	env_parallel.ksh env_parallel.mksh env_parallel.pdksh		\
 	env_parallel.sh env_parallel.tcsh env_parallel.zsh parcat.pod	\
 	parset.pod sem.pod parallel.pod env_parallel.pod niceload.pod	\
-	parallel_tutorial.pod parallel_book.pod parallel_design.pod	\
+	parallel_examples.pod parallel_tutorial.pod parallel_book.pod	\
-	parallel_alternatives.pod parallel_cheat_bw.fodt		\
+	parallel_design.pod parallel_alternatives.pod			\
-	pod2graph $(DISTCLEANFILES)
+	parallel_cheat_bw.fodt pod2graph $(DISTCLEANFILES)

src/parallel

@@ -11402,21 +11402,28 @@ sub print_parset($) {
 
     ::debug("parset","print $Global::parset");
     if($Global::parset eq "assoc") {
+	# Start: (done in parse_parset())
 	#   eval "`echo 'declare -A myassoc; myassoc=(
-	# Each:
+	# Each: (done here)
 	#   [$'a\tb']=$'a\tb\tc	 ddd'
-	# End:
+	# End: (done in wait_and_exit())
 	#   )'`"
 	print '[',::Q($self->{'commandline'}->
 		      replace_placeholders(["\257<\257>"],0,0)),']=';
     } elsif($Global::parset eq "array") {
+	# Start: (done in parse_parset())
 	#   eval "`echo 'myassoc=(
-	# Each:
+	# Each: (done here)
 	#   $'a\tb\tc  ddd'
-	# End:
+	# End: (done in wait_and_exit())
 	#   )'`"
     } elsif($Global::parset eq "var") {
+	# Start: (done in parse_parset())
+	#   <empty>
+	# Each: (done here)
 	#   var=$'a\tb\tc  ddd'
+	# End: (done in wait_and_exit())
+	#   <empty>
 	if(not @Global::parset_vars) {
 	    ::error("Too few named destination variables");
 	    ::wait_and_exit(255);

src/pod2graph

@@ -30,8 +30,11 @@
 # to a graph.pdf with link between --option and --other-option
 
 $pod=join("",<>);
+# Remove stuff before OPTIONS
 $pod=~s/^.*=head1 OPTIONS//s;
+# Remove from EXAMPLES (which is next section) and till end
 $pod=~s/=head1 EXAMPLES.*//s;
+# Remove =over / =back pairs
 $pod=~s/^.*?=over//s;
 $pod=~s/=back\s*$//s;
 $pod=~s/=over.*?=back//sg;
@@ -40,19 +43,21 @@ $in_text = 0;
 $in_item = 0;
 $in_see_also = 0;
 
-
 for(split(/\n\n+/,$pod)) {
     if(/^See also:\s+(\S.*)/s) {
+	# "See also" paragraph
 	$lex = "seealso";
 	$in_text = 0;
 	$in_item = 0;
 	$in_see_only = 1;
     } elsif(/^=item\s+(B<[{]=.*?perl expression.*?=[}]>|[IB]<.*?>)(\s|$)/s) {
+	# "=item" paragraph
 	$lex = "item";
 	$in_text = 0;
 	$in_item = 1;
 	$in_see_only = 0;
     } elsif(/\S/) {
+	# else it is just text
 	$lex = "text";
 	$in_text = 1;
 	$in_item = 0;
@@ -60,11 +65,13 @@ for(split(/\n\n+/,$pod)) {
     }
   
     if($lex eq "seealso") {
+	# We found "See also": output edge
 	if($lastlex eq "item") {
 	    @saveditems = @items;
 	    @items = ();
 	}
 	my $to = $1;
+	# Edge from = item/item/item
 	my $from = (join "/",
 		    map {
 			s/I<(.*?)>/$1/g;