Index: ossp-pkg/rc/rc.pod
RCS File: /v/ossp/cvs/ossp-pkg/rc/rc.pod,v
rcsdiff -q -kk '-r1.44' '-r1.45' -u '/v/ossp/cvs/ossp-pkg/rc/rc.pod,v' 2>/dev/null
--- rc.pod	2003/07/07 12:55:42	1.44
+++ rc.pod	2003/07/09 10:21:21	1.45
@@ -33,14 +33,14 @@
 
 B<rc>
 [B<-?>|B<--usage>]
-[B<-D>|B<--debug>] 
+[B<-D>|B<--debug>]
 [B<-L>|B<--locate> I<dir>[C<:>I<dir>[...]]]
 [B<-V>|B<--version>]
 [B<-c>|B<--conf> I<file>[C<:>I<file>[...]]]
 [B<-e>|B<--eval>]
-[B<-f>|B<--func> I<file>[C<:>I<file>[...]]] 
+[B<-f>|B<--func> I<file>[C<:>I<file>[...]]]
 [B<-h>|B<--help>]
-[B<-i>|B<--info>] 
+[B<-i>|B<--info>]
 [B<-l>|B<--labels>]
 [B<-p>|B<--print>]
 [B<-q>|B<--query>] I<format>
@@ -48,7 +48,7 @@
 [B<-r>|B<--raw>]
 [B<-t>|B<--tmp> I<dir>]
 [B<-v>|B<--verbose>]
-[B<-x>|B<--exec>] 
+[B<-x>|B<--exec>]
 
 [B<--RequireUmask umask>]
 [B<--RequireOwner uid|name>]
@@ -68,29 +68,32 @@
 
 =head1 DESCRIPTION
 
-OSSP rc is a run-command processor. Its primary function is to scan F<rcfile>
-script files for one or more B<section>s and run the commands listed in each
-B<section>.
-
-The run-command processor can alternatively C<print> the commands in human
-readable format or reformat them for shell C<eval> input without executing
-them. The F<rcfile> files contain variables and the command processor has
-functionality to query their default, set and effective values.
+OSSP rc is a run-command processor. Its primary function is to assemble
+a temporary file from excerpts of F<rcfile>s which are built out of text
+snippets grouped into B<section>s.  The user specifies the desired parts
+to use and also controls the order of assembly.
+
+OSSP rc defaults to B<exec>ute the concatenated temporary file, but it
+can also B<print> it in human readable format or create shell
+instructions suitable for the calling shell to B<eval>uate the temporary
+file. The F<rcfile>s contain variables and the command processor has
+functionality to B<query> their default, set and effective values.
 
 The structure of the F<rcfile>s is simple but the syntax is highly
-configurable. A F<rcfile> is divided into B<section>s, clearly identified by
-applying a regular expression. The default regular expression leads to
-identification of section text starting with a percent (%) and label (any
-text). Various examples of this and other syntax possibilities is given in the
-manpage B<rc(1)>.
-
-Often, only a single B<rcfile> name is processed. To process all B<rcfile>s,
-substitute the keyword 'all' for the B<rcfile> name. The B<section>s of a
-B<rcfil> processed match exactly the B<section>s given on the command line,
-and even the ordering is kept.
+configurable. Included B<section>s are labeled for identification by the
+user, while rc uses regular expressions to identifiy their boundaries.
+The default regular expression leads to identification of section text
+starting with a percent (%) and any subsequent text until a whitespace
+identifies the label.  Various examples are listed below.
+
+Often, only a single B<rcfile> is processed. To process all B<rcfile>s,
+substitute the keyword 'all' for the B<rcfile> name. This convenience
+inhibits 'all' being used as a file name.
 
 =head1 OPTIONS
 
+=over 4
+
 =item B<-?>|B<--usage>
 
 print short usage summary, then exit.
@@ -128,7 +131,7 @@
 
 =item B<-h>|B<--help>
 
-print this help, then exit.
+print help, then exit.
 
 =item B<-i>|B<--info>
 
@@ -151,7 +154,7 @@
 
 output text using no terminal control sequences. The rc facility usually
 tries to improve output text for human readability using terminal control
-sequences for color, bold and italic rendering. The default is determines at
+sequences for color, bold and italic rendering. The default is determined at
 runtime and is automagically disabled if stdout is detached from a terminal.
 
 =item B<-s>|B<--silent>
@@ -222,6 +225,8 @@
 
 name of the error section, defaults to %error.
 
+=back
+
 =head1 OPTIONS ORDERING
 
 B<OSSP rc> reads its options from three sources and builds a global
@@ -294,10 +299,10 @@
 the commands by executing them directly.
 
  /usr/local/bin/rc --info
- /sbin/rc --query lmtp2nntp
+ /usr/local/bin/rc --query lmtp2nntp
  /usr/local/bin/rc httpd reload
- /cw/etc/rc --conf /etc/rc.conf --debug smtpd stop
- /opt/bin/rc ntpd --silent start sync stop start
+ /usr/local/bin/rc --conf /etc/rc.conf --debug smtpd stop
+ /usr/local/bin/rc ntpd --silent start sync stop start
 
 B<OSSP rc> offers more than just command execution. In the following examples
 because the 'eval' run mode option is specified, B<OSSP rc> will prepare the
@@ -311,7 +316,7 @@
 To read the results of a B<OSSP rc> operation without executing or evaluting
 the run-commands, use the 'print' run mode.
 
- /opt/binbin/rc --print --info mico
+ /usr/local/bin/rc --print --info mico
  /usr/local/bin/rc --print httpd reload
 
 Arguments in the form of name=value pairs may be passed to the B<sections>
@@ -322,11 +327,11 @@
 more than one section, then repeat its definition after each section given on
 the command line.
 
- ./rc all start sFac="LOG_USER"  # pass LOG_USER as argument to 'start'
- ./rc lmtp2nntp start nSleep=2   # sleep for 2 seconds before returning
- /cw/etc/rc/ ftpd start nMax=32  # a maximum of 32 users can connect
- /bin/rc rsyncd restart nSleep=4 # pause 4 seconds between start and stop
- /bin/rc -rdv all stop nSleep=2 start nSleep=4 sLevel="LOG_INFO" bQuiet=1
+ /usr/local/bin/rc all start sFac="LOG_USER"  # pass LOG_USER as argument to 'start'
+ /usr/local/bin/rc lmtp2nntp start nSleep=2   # sleep for 2 seconds before returning
+ /usr/local/bin/rc ftpd start nMax=32         # a maximum of 32 users can connect
+ /usr/local/bin/rc rsyncd restart nSleep=4    # pause 4 seconds between start and stop
+ /usr/local/bin/rc -rdv all stop nSleep=2 start nSleep=4 sLevel="LOG_INFO" bQuiet=1
 
 =head1 FILES