[PATCH] Bug #26327: xargs manpage: clarify the number of times command is executed.

[James Youngman]

Fix Savannah bug #26327: xargs man page is vague about the number
of times command is executed.
* xargs/xargs.1 (DESCRIPTION): Explain more clearly that the
command will be executed many times.  Indicate that -L can also be
useful with -P.
* NEWS: Mention this change.
---
 ChangeLog     |    9 +++++++++
 NEWS          |    4 ++++
 xargs/xargs.1 |   19 +++++++++++++++++++
 3 files changed, 32 insertions(+), 0 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index cccc2f9..22b68f2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2009-07-12  James Youngman  <address@hidden>
+
+       Fix Savannah bug #26327: xargs man page is vague about the number
+       of times command is executed.
+       * xargs/xargs.1 (DESCRIPTION): Explain more clearly that the
+       command will be executed many times.  Indicate that -L can also be
+       useful with -P.
+       * NEWS: Mention this change.
+
 2009-07-11  James Youngman  <address@hidden>
 
        * NEWS: Set the version to 4.5.6-git, so that we can make test
diff --git a/NEWS b/NEWS
index 25a17f6..b7ae0af 100644
--- a/NEWS
+++ b/NEWS
@@ -8,6 +8,10 @@ GNU findutils NEWS - User visible changes.     -*- outline -*- 
(allout)
 
 #19120: Patch to fix single quotes in man page find(1)
 
+** Documentation Changes
+
+#26327: xargs man page is vague about the number of times command is executed.
+
 * Major changes in release 4.5.5, 2009-07-06
 
 xargs now handles the case where the system's actual exec limits are
diff --git a/xargs/xargs.1 b/xargs/xargs.1
index 57c37d5..84564e6 100644
--- a/xargs/xargs.1
+++ b/xargs/xargs.1
@@ -49,6 +49,23 @@ one or more times with any
 followed by items read from standard input.  Blank lines on the
 standard input are ignored.
 .P
+The command line for
+.I command
+is built up until it reaches a system-defined limit (unless the
+.B \-n
+and
+.B \-L
+options are used).  The specified
+.I command
+will be invoked as many times as necessary to use up the list of input
+items.  In general, there will be many fewer invocations of
+.I command
+than there were items in the input.  This will normally have
+significant performance benefits.  Some commands can usefully be
+executed in prarallel too; see the
+.B \-P
+option.
+.P
 Because Unix filenames can contain blanks and newlines, this default
 behaviour is often problematic; filenames containing blanks
 and/or newlines are incorrectly processed by
@@ -299,6 +316,8 @@ is 0,
 will run as many processes as
 possible at a time.  Use the
 .B \-n
+option or the
+.B \-L
 option with
 .BR \-P ;
 otherwise chances are that only one exec will be done.
-- 
1.5.6.5