commit bash-20130322 snapshot

doc/bashref.info

@@ -1,10 +1,10 @@
 This is bashref.info, produced by makeinfo version 4.13 from
-/Users/chet/src/bash/src/doc/bashref.texi.
+/usr/homes/chet/src/bash/src/doc/bashref.texi.
 
 This text is a brief description of the features that are present in
-the Bash shell (version 4.2, 8 January 2013).
+the Bash shell (version 4.2, 2 March 2013).
 
-   This is Edition 4.2, last updated 8 January 2013, of `The GNU Bash
+   This is Edition 4.2, last updated 2 March 2013, of `The GNU Bash
 Reference Manual', for `Bash', Version 4.2.
 
    Copyright (C) 1988-2013 Free Software Foundation, Inc.
@@ -28,10 +28,10 @@ Bash Features
 *************
 
 This text is a brief description of the features that are present in
-the Bash shell (version 4.2, 8 January 2013).  The Bash home page is
+the Bash shell (version 4.2, 2 March 2013).  The Bash home page is
 `http://www.gnu.org/software/bash/'.
 
-   This is Edition 4.2, last updated 8 January 2013, of `The GNU Bash
+   This is Edition 4.2, last updated 2 March 2013, of `The GNU Bash
 Reference Manual', for `Bash', Version 4.2.
 
    Bash contains features that appear in other popular shells, and some
@@ -1060,39 +1060,51 @@ File: bashref.info,  Node: GNU Parallel,  Prev: Coprocesses,  Up: Shell Commands
 3.2.6 GNU Parallel
 ------------------
 
-GNU Parallel, as its name suggests, can be used to build and run
+There are ways to run commands in parallel that are not built into Bash.
+GNU Parallel is a tool to do just that.
+
+   GNU Parallel, as its name suggests, can be used to build and run
 commands in parallel.  You may run the same command with different
 arguments, whether they are filenames, usernames, hostnames, or lines
-read from files.
+read from files.  GNU Parallel provides shorthand references to many of
+the most common operations (input lines, various portions of the input
+line, different ways to specify the input source, and so on).  Parallel
+can replace `xargs' or feed commands from its input sources to several
+different instances of Bash.
 
    For a complete description, refer to the GNU Parallel documentation.
 A few examples should provide a brief introduction to its use.
 
-   For example, it is easy to prefix each line in a text file with a
-specified string:
-     cat file | parallel -k echo prefix_string
-   The `-k' option is required to preserve the lines' order.
-
-   Similarly, you can append a specified string to each line in a text
-file:
-     cat file | parallel -k echo {} append_string
+   For example, it is easy to replace `xargs' to gzip all html files in
+the current directory and its subdirectories:
+     find . -type f -name '*.html' -print | parallel gzip
+   If you need to protect special characters such as newlines in file
+names, use find's `-print0' option and parallel's `-0' option.
 
    You can use Parallel to move files from the current directory when
 the number of files is too large to process with one `mv' invocation:
      ls | parallel mv {} destdir
 
    As you can see, the {} is replaced with each line read from standard
-input.  This will run as many `mv' commands as there are files in the
-current directory.  You can emulate a parallel `xargs' by adding the
-`-X' option:
-     ls | parallel -X mv {} destdir
+input.  While using `ls' will work in most instances, it is not
+sufficient to deal with all filenames.  If you need to accommodate
+special characters in filenames, you can use
+
+     find . -depth 1 \! -name '.*' -print0 | parallel -0 mv {} destdir
+
+as alluded to above.
+
+   This will run as many `mv' commands as there are files in the current
+directory.  You can emulate a parallel `xargs' by adding the `-X'
+option:
+     find . -depth 1 \! -name '.*' -print0 | parallel -0 -X mv {} destdir
 
    GNU Parallel can replace certain common idioms that operate on lines
-read from a file (in this case, filenames):
-     	for x in $(cat list); do
-     		do-something1 $x config-$x
-     		do-something2 < $x
-     	done | process-output
+read from a file (in this case, filenames listed one per line):
+     	while read -r x; do
+     		do-something1 "$x" "config-$x"
+     		do-something2 < "$x"
+     	done < file | process-output
 
 with a more compact syntax reminiscent of lambdas:
      cat list | parallel "do-something1 {} config-{} ; do-something2 < {}" | process-output
@@ -1102,17 +1114,34 @@ extensions, which lends itself to batch file transformations or
 renaming:
      ls *.gz | parallel -j+0 "zcat {} | bzip2 >{.}.bz2 && rm {}"
    This will recompress all files in the current directory with names
-ending in .gz using bzip2, running one job per CPU (-j+0)  in parallel.
+ending in .gz using bzip2, running one job per CPU (-j+0) in parallel.
+(We use `ls' for brevity here; using `find' as above is more robust in
+the face of filenames containing unexpected characters.)  Parallel can
+take arguments from the command line; the above can also be written as
+
+     parallel "zcat {} | bzip2 >{.}.bz2 && rm {}" ::: *.gz
 
    If a command generates output, you may want to preserve the input
 order in the output.  For instance, the following command
      { echo foss.org.my ; echo debian.org; echo freenetproject.org; } | parallel traceroute
-   will display as output the traceroute invocation that finishes
-first.  Using the `-k' option, as we saw above
+   will display as output the traceroute invocation that finishes first.
+Adding the `-k' option
      { echo foss.org.my ; echo debian.org; echo freenetproject.org; } | parallel -k traceroute
    will ensure that the output of `traceroute foss.org.my' is displayed
 first.
 
+   Finally, Parallel can be used to run a sequence of shell commands in
+parallel, similar to `cat file | bash'.  It is not uncommon to take a
+list of filenames, create a series of shell commands to operate on
+them, and feed that list of commnds to a shell.  Parallel can speed
+this up.  Assuming that `file' contains a list of shell commands, one
+per line,
+
+     parallel -j 10 < file
+
+will evaluate the commands using the shell (since no explicit command is
+supplied as an argument), in blocks of ten shell jobs at a time.
+
 
 File: bashref.info,  Node: Shell Functions,  Next: Shell Parameters,  Prev: Shell Commands,  Up: Basic Shell Features
 
@@ -4248,7 +4277,7 @@ This builtin allows you to change additional shell optional behavior.
           continue with the next command in the list.
 
     `compat41'
-          If set, Bash, when in posix mode, treats a single quote in a
+          If set, Bash, when in POSIX mode, treats a single quote in a
           double-quoted parameter expansion as a special character.
           The single quotes must match (an even number) and the
           characters between the single quotes are considered quoted.
@@ -11082,133 +11111,133 @@ D.5 Concept Index
 
 Tag Table:
 Node: Top924
-Node: Introduction2840
-Node: What is Bash?3068
-Node: What is a shell?4181
-Node: Definitions6720
-Node: Basic Shell Features9638
-Node: Shell Syntax10857
-Node: Shell Operation11887
-Node: Quoting13181
-Node: Escape Character14484
-Node: Single Quotes14969
-Node: Double Quotes15317
-Node: ANSI-C Quoting16442
-Node: Locale Translation17686
-Node: Comments18582
-Node: Shell Commands19200
-Node: Simple Commands20072
-Node: Pipelines20703
-Node: Lists23402
-Node: Compound Commands25131
-Node: Looping Constructs26137
-Node: Conditional Constructs28600
-Node: Command Grouping39478
-Node: Coprocesses40957
-Node: GNU Parallel42790
-Node: Shell Functions45258
-Node: Shell Parameters50342
-Node: Positional Parameters54471
-Node: Special Parameters55371
-Node: Shell Expansions58335
-Node: Brace Expansion60261
-Node: Tilde Expansion63042
-Node: Shell Parameter Expansion65391
-Node: Command Substitution77685
-Node: Arithmetic Expansion79018
-Node: Process Substitution79868
-Node: Word Splitting80918
-Node: Filename Expansion82541
-Node: Pattern Matching84706
-Node: Quote Removal88406
-Node: Redirections88701
-Node: Executing Commands97865
-Node: Simple Command Expansion98535
-Node: Command Search and Execution100465
-Node: Command Execution Environment102802
-Node: Environment105788
-Node: Exit Status107447
-Node: Signals109069
-Node: Shell Scripts111037
-Node: Shell Builtin Commands113555
-Node: Bourne Shell Builtins115583
-Node: Bash Builtins135359
-Node: Modifying Shell Behavior162686
-Node: The Set Builtin163031
-Node: The Shopt Builtin173357
-Node: Special Builtins187561
-Node: Shell Variables188540
-Node: Bourne Shell Variables188980
-Node: Bash Variables191011
-Node: Bash Features217886
-Node: Invoking Bash218785
-Node: Bash Startup Files224563
-Node: Interactive Shells229582
-Node: What is an Interactive Shell?229992
-Node: Is this Shell Interactive?230641
-Node: Interactive Shell Behavior231456
-Node: Bash Conditional Expressions234744
-Node: Shell Arithmetic238746
-Node: Aliases241522
-Node: Arrays244078
-Node: The Directory Stack248767
-Node: Directory Stack Builtins249486
-Node: Controlling the Prompt252442
-Node: The Restricted Shell255214
-Node: Bash POSIX Mode257051
-Node: Job Control266438
-Node: Job Control Basics266898
-Node: Job Control Builtins271617
-Node: Job Control Variables276079
-Node: Command Line Editing277237
-Node: Introduction and Notation278909
-Node: Readline Interaction280531
-Node: Readline Bare Essentials281722
-Node: Readline Movement Commands283511
-Node: Readline Killing Commands284476
-Node: Readline Arguments286396
-Node: Searching287440
-Node: Readline Init File289626
-Node: Readline Init File Syntax290773
-Node: Conditional Init Constructs307610
-Node: Sample Init File310143
-Node: Bindable Readline Commands313260
-Node: Commands For Moving314467
-Node: Commands For History315611
-Node: Commands For Text319796
-Node: Commands For Killing322469
-Node: Numeric Arguments324926
-Node: Commands For Completion326065
-Node: Keyboard Macros330257
-Node: Miscellaneous Commands330945
-Node: Readline vi Mode336751
-Node: Programmable Completion337658
-Node: Programmable Completion Builtins344908
-Node: A Programmable Completion Example354654
-Node: Using History Interactively359904
-Node: Bash History Facilities360588
-Node: Bash History Builtins363587
-Node: History Interaction367515
-Node: Event Designators370220
-Node: Word Designators371442
-Node: Modifiers373081
-Node: Installing Bash374485
-Node: Basic Installation375622
-Node: Compilers and Options378314
-Node: Compiling For Multiple Architectures379055
-Node: Installation Names380719
-Node: Specifying the System Type381537
-Node: Sharing Defaults382253
-Node: Operation Controls382926
-Node: Optional Features383884
-Node: Reporting Bugs393672
-Node: Major Differences From The Bourne Shell394870
-Node: GNU Free Documentation License411729
-Node: Indexes436925
-Node: Builtin Index437379
-Node: Reserved Word Index444206
-Node: Variable Index446654
-Node: Function Index460177
-Node: Concept Index467405
+Node: Introduction2836
+Node: What is Bash?3064
+Node: What is a shell?4177
+Node: Definitions6716
+Node: Basic Shell Features9634
+Node: Shell Syntax10853
+Node: Shell Operation11883
+Node: Quoting13177
+Node: Escape Character14480
+Node: Single Quotes14965
+Node: Double Quotes15313
+Node: ANSI-C Quoting16438
+Node: Locale Translation17682
+Node: Comments18578
+Node: Shell Commands19196
+Node: Simple Commands20068
+Node: Pipelines20699
+Node: Lists23398
+Node: Compound Commands25127
+Node: Looping Constructs26133
+Node: Conditional Constructs28596
+Node: Command Grouping39474
+Node: Coprocesses40953
+Node: GNU Parallel42786
+Node: Shell Functions46767
+Node: Shell Parameters51851
+Node: Positional Parameters55980
+Node: Special Parameters56880
+Node: Shell Expansions59844
+Node: Brace Expansion61770
+Node: Tilde Expansion64551
+Node: Shell Parameter Expansion66900
+Node: Command Substitution79194
+Node: Arithmetic Expansion80527
+Node: Process Substitution81377
+Node: Word Splitting82427
+Node: Filename Expansion84050
+Node: Pattern Matching86215
+Node: Quote Removal89915
+Node: Redirections90210
+Node: Executing Commands99374
+Node: Simple Command Expansion100044
+Node: Command Search and Execution101974
+Node: Command Execution Environment104311
+Node: Environment107297
+Node: Exit Status108956
+Node: Signals110578
+Node: Shell Scripts112546
+Node: Shell Builtin Commands115064
+Node: Bourne Shell Builtins117092
+Node: Bash Builtins136868
+Node: Modifying Shell Behavior164195
+Node: The Set Builtin164540
+Node: The Shopt Builtin174866
+Node: Special Builtins189070
+Node: Shell Variables190049
+Node: Bourne Shell Variables190489
+Node: Bash Variables192520
+Node: Bash Features219395
+Node: Invoking Bash220294
+Node: Bash Startup Files226072
+Node: Interactive Shells231091
+Node: What is an Interactive Shell?231501
+Node: Is this Shell Interactive?232150
+Node: Interactive Shell Behavior232965
+Node: Bash Conditional Expressions236253
+Node: Shell Arithmetic240255
+Node: Aliases243031
+Node: Arrays245587
+Node: The Directory Stack250276
+Node: Directory Stack Builtins250995
+Node: Controlling the Prompt253951
+Node: The Restricted Shell256723
+Node: Bash POSIX Mode258560
+Node: Job Control267947
+Node: Job Control Basics268407
+Node: Job Control Builtins273126
+Node: Job Control Variables277588
+Node: Command Line Editing278746
+Node: Introduction and Notation280418
+Node: Readline Interaction282040
+Node: Readline Bare Essentials283231
+Node: Readline Movement Commands285020
+Node: Readline Killing Commands285985
+Node: Readline Arguments287905
+Node: Searching288949
+Node: Readline Init File291135
+Node: Readline Init File Syntax292282
+Node: Conditional Init Constructs309119
+Node: Sample Init File311652
+Node: Bindable Readline Commands314769
+Node: Commands For Moving315976
+Node: Commands For History317120
+Node: Commands For Text321305
+Node: Commands For Killing323978
+Node: Numeric Arguments326435
+Node: Commands For Completion327574
+Node: Keyboard Macros331766
+Node: Miscellaneous Commands332454
+Node: Readline vi Mode338260
+Node: Programmable Completion339167
+Node: Programmable Completion Builtins346417
+Node: A Programmable Completion Example356163
+Node: Using History Interactively361413
+Node: Bash History Facilities362097
+Node: Bash History Builtins365096
+Node: History Interaction369024
+Node: Event Designators371729
+Node: Word Designators372951
+Node: Modifiers374590
+Node: Installing Bash375994
+Node: Basic Installation377131
+Node: Compilers and Options379823
+Node: Compiling For Multiple Architectures380564
+Node: Installation Names382228
+Node: Specifying the System Type383046
+Node: Sharing Defaults383762
+Node: Operation Controls384435
+Node: Optional Features385393
+Node: Reporting Bugs395181
+Node: Major Differences From The Bourne Shell396379
+Node: GNU Free Documentation License413238
+Node: Indexes438434
+Node: Builtin Index438888
+Node: Reserved Word Index445715
+Node: Variable Index448163
+Node: Function Index461686
+Node: Concept Index468914
 
 End Tag Table