[src/trunk]: src/usr.bin/apply Rework for clarity.

[dholland <dholland%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/3649c352a3bd
branches:  trunk
changeset: 344092:3649c352a3bd
user:      dholland <dholland%NetBSD.org@localhost>
date:      Sat Mar 12 22:07:48 2016 +0000

description:
Rework for clarity.

diffstat:

 usr.bin/apply/apply.1 |  125 +++++++++++++++++++++++++++++--------------------
 1 files changed, 73 insertions(+), 52 deletions(-)

diffs (183 lines):

diff -r 731b87900b52 -r 3649c352a3bd usr.bin/apply/apply.1
--- a/usr.bin/apply/apply.1     Sat Mar 12 21:51:02 2016 +0000
+++ b/usr.bin/apply/apply.1     Sat Mar 12 22:07:48 2016 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: apply.1,v 1.12 2006/12/24 10:07:18 wiz Exp $
+.\"    $NetBSD: apply.1,v 1.13 2016/03/12 22:07:48 dholland Exp $
 .\"
 .\" Copyright (c) 1983, 1990, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -29,91 +29,101 @@
 .\"
 .\"     @(#)apply.1    8.2 (Berkeley) 4/4/94
 .\"
-.Dd April 4, 1994
+.Dd March 12, 2016
 .Dt APPLY 1
 .Os
 .Sh NAME
 .Nm apply
-.Nd apply a command to a set of arguments
+.Nd apply a command to a list of arguments
 .Sh SYNOPSIS
 .Nm
 .Op Fl a Ns Ar c
 .Op Fl Ns Ar #
-.Ar command argument ...
+.Ar command arguments ...
 .Sh DESCRIPTION
 .Nm
-runs the named
+divides its
+.Ar arguments
+into fixed-size groups and runs
 .Ar command
-on each
-argument
-.Ar argument
-in turn.
+in turn on each group.
 .Pp
-Character sequences of the form
+On each execution of
+.Ar command ,
+each character sequence of the form
 .Dq Li \&%d
 in
 .Ar command ,
 where
-.Dq Li d
-is a digit from 1 to 9, are replaced by the
-.Li d Ns \'th
-following unused
-.Ar argument .
-In this case, the largest digit number of arguments are discarded for
-each execution of
-.Ar command .
+.Ar d
+is a digit from 1 to 9, is replaced with the
+.Ar d Ns \'th
+argument from the current argument group.
+The argument group size is set to the largest such
+.Ar d
+found.
+Any given argument number can be used arbitrarily many times.
+(Including zero.)
+.Pp
+If no explicit substitution sequences are found in
+.Ar command ,
+the current argument group is substituted after
+.Ar command
+delimited by spaces, and the argument group size defaults to 1 and can
+be set with the
+.Fl #
+option.
+.Pp
+If the argument group size is set to 0, one argument from
+.Ar arguments
+is taken for each execution of
+.Ar command
+anyway, but is discarded and not substituted; thus,
+.Ar command
+is run verbatim once for every argument.
 .Pp
 The options are as follows:
 .Bl -tag -width "-ac"
 .It Fl Ns Ar #
-Normally arguments are taken singly; the optional number
-.Fl #
-specifies the number of arguments to be passed to
-.Ar command .
-If the number is zero,
-.Ar command
-is run, without arguments, once for each
-.Ar argument .
-.Pp
-If any sequences of
-.Dq Li \&%d
-occur in command, the
-.Fl #
-option is ignored.
+Set the argument group size.
+Ignored if explicit substitutions are used.
 .It Fl a Ns Ar c
-The use of the character
+Change the magic substitution character from the default
 .Dq Li %
-as a magic character may be changed with the
-.Fl a
-option.
+to
+.Ar c .
 .El
 .Sh ENVIRONMENT
 The following environment variable affects the execution of
 .Nm :
 .Bl -tag -width SHELL
 .It Ev SHELL
-Pathname of shell to use.
+Pathname of the shell to use to execute
+.Ar command .
 If this variable is not defined, the Bourne shell is used.
 .El
 .Sh FILES
 .Bl -tag -width /bin/sh -compact
 .It Pa /bin/sh
-Default shell
+Default shell.
 .El
 .Sh EXAMPLES
 .Bl -tag -width apply -compact
 .It Li "apply echo *"
-is similar to
-.Xr ls 1 ;
-.It Li "apply \-2 cmp a1 b1 a2 b2 a3 b3"
-compares the `a' files to the `b' files;
+Prints the name of every file in the current directory.
+.It Li "apply \-2 diff a1 b1 a2 b2 a3 b3"
+Compares the `a' files to the `b' files.
 .It Li "apply \-0 who 1 2 3 4 5"
-runs
+Runs
 .Xr who 1
-5 times; and
-.It Li "apply \'ln %1 /usr/joe\'" *
-links all files in the current directory to the directory
-.Pa /usr/joe .
+5 times.
+.It Li "apply \'ln %1 /home/joe/joe.%1\'" *
+Hard-links all files in the current directory into the directory
+.Pa /home/joe ,
+with their names prefixed with "joe".
+.It Li "apply \'cvs diff %1 > %1.diff'" *.c
+Diff all C sources in the current directory against the last
+checked-in version and store each result in its own output file.
 .El
 .Sh HISTORY
 The
@@ -122,9 +132,20 @@
 .Bx 4.2 .
 .Sh AUTHORS
 .An Rob Pike
-.Sh BUGS
-Shell metacharacters in
+.Sh RESTRICTIONS
+The complete command to be executed on each iteration is assembled as
+a string without additional quoting and then passed to a copy of the
+shell for parsing and execution.
+Thus, commands or arguments that contain spaces or shell
+metacharacters may behave in unexpected ways.
+.Pp
+To protect a shell metacharacter fully it must be quoted twice, once
+against the current shell and once against the subshell used for
+execution.
+Similarly, for a shell metacharacter to be interpreted by the subshell
+it must be quoted to protect it from the current shell.
+A simple rule of thumb is to enclose the entire
 .Ar command
-may have bizarre effects; it is best to enclose complicated
-commands in single quotes
-.Pq '' .
+in single quotes
+.Pq ''
+so that the current shell does not interpret any of it.