--- rc.pod 2002/01/29 07:31:11 1.20
+++ rc.pod 2002/01/29 08:42:20 1.21
@@ -1,7 +1,3 @@
---------------------------------------------------------------------------------
-DO NOT EDIT. MAJOR REWRITES JOINING OPTIONS, NOTES AND DEFAULTS IN PROGRESS. THL
---------------------------------------------------------------------------------
-
##
## rc.pod -- OSSP Run Command Processor (Manual Page)
## Copyright (c) 2000-2002 Cable & Wireless Deutschland GmbH
@@ -41,64 +37,27 @@
=over 4
-=item B<General>
-
@l_prefix@/etc/rc
-[B<-c>|B<--conf> I<file>[C<:>I<file>[...]]]
-[B<-t>|B<--tmp> I<dir>]
-[B<-r>|B<--raw>]
-[B<-v>|B<--verbose>]
+[B<-?>|B<--usage>]
[B<-D>|B<--debug>]
-
-=item B<Run-Command Execution>
-
-@l_prefix@/etc/rc
-[I<General options>]
-[B<-x>|B<--exec>]
-[B<-p>|B<--print>]
-[B<-e>|B<--eval>]
-[B<-d>|B<--dirs> I<dir>[C<:>I<dir>[...]]
-[B<-f>|B<--func> I<file>[C<:>I<file>[...]]]
[B<-F>|B<--force>]
+[B<-V>|B<--version>]
+[B<-c>|B<--conf> I<file>[C<:>I<file>[...]]]
+[B<-d>|B<--dirs> I<dir>[C<:>I<dir>[...]]]
+[B<-e>|B<--eval>]
+[B<-f>|B<--func> I<file>[C<:>I<file>[...]]]
+[B<-h>|B<--help>]
+[B<-i>|B<--info>]
+[B<-l>|B<--labels>]
+[B<-p>|B<--print>]
+[B<-q>|B<--query>] I<format>
+[B<-s>|B<--silent>]
+[B<-r>|B<--raw>]
+[B<-t>|B<--tmp> I<dir>]
+[B<-v>|B<--verbose>]
+[B<-x>|B<--exec>]
I<rcfile>
I<section>
-[I<section> ...]
-
-=item B<Configuration Query>
-
-@l_prefix@/etc/rc
-[I<General options>]
-B<-q>|B<--query> I<format>
-[B<-d>|B<--dirs> I<dir>[C<:>I<dir>[...]]
-[B<-F>|B<--force>]
-I<rcfile>
-
-=item B<Looking up available labels>
-
-[I<General options>]
-<-l>|<--labels>
-[B<-d>|B<--dirs> I<dir>[C<:>I<dir>[...]]
-[B<-F>|B<--force>]
-I<rcfile>
-
-# FIXME Ralf, what's that?
-# @l_prefix@/etc/rc
-# [I<parameter-options>]
-# [B<-c>|B<--conf>]
-# [I<package>]
-
-=item B<Facility Information>
-
-@l_prefix@/etc/rc
-[I<General options>]
-[B<-i>|B<--info>]
-
-=item B<Other>
-
-@l_prefix@/etc/rc
-[B<-?>|B<--usage>]
-[B<-h>|B<--help>]
-[B<-V>|B<--version>]
=back 4
@@ -106,272 +65,135 @@
=over 4
-OSSP rc is a run command processor. It's primary function is to scan F<rcfile>
-script files for B<section>(s) identified by corresponding label(s) and run the
-commands in the section(s).
-
-The run command processor can also only print the commands without executing
-them or reformat them to C<eval> input. The F<rcfile> files contain variables
-and the command processor has functionality to query their default, set and
-effective values.
-
-To understand the structure and syntax of F<rcfile> script files, an example
-called F<rc.example> is included in the distribution. The rc environment and
-behaviour is very configurable, so the syntax may vary and not match exactly
-the example provided.
+OSSP rc is a run command processor. It's primary function is to scan
+F<rcfile> script files for B<section>(s) and run the commands listed in the
+section(s).
+
+The run command processor can alternatively 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.
+
+The structure of the F<rcfile>s is simple but the syntax is highly
+configurable. A F<rcfile> is divided into B<section>s and each of them is
+identified by a label build from the B<section> name. The distribution
+contains various examples.
With a single call to rc usually one F<rcfile> may be processed at, although
-many sections can be given to source their corresponding commands, see
-EXAMPLES below.
-
-There is one exception to this rule in which an rc keyword named `all' is
-reserved to mean `all F<rcfile>s.' The user may thus give the `all' wildcard
-in place of the C<rcfile> parameter to process the commands from the given
-sections of all C<rcfile>s found.
-
-#THL! does "all stop start" mean "a stop stop, a start, b start" or " a stop,
-#a start, b stop, b start"?
-#Prioritaeten
-
-#Using the `all' wildcard may be risky in some cases, because successful
-#performance then depends not only on the code written into each program's
-#sections but also if every single program found has the named section label at
-#all. For information about the rc exit status after such an operation see
-#`DIAGNOSTICS.'
+many sections can be passed which are executed in given order. The only
+exception to this rule is when the reserved keyword `all' is used as F<rcfile>
+meaning `all F<rcfile>s.'
=back 4
=head1 OPTIONS
=over 4
+=item B<-?>|B<--usage>
-Inclusive options which may be used with another
-
-=item B<-c>, B<--conf> F<file>
-
-specify the location of the configuration file.
-
-=item B<-f>, B<--func> F<file>[C<:>F<file>[...]]
-
-specify the location of one or more optional function files, containing
-commands which are prepended to the sections of their corresponding
-C<rcfile>s.
-
-=item B<-F>, B<--force>
-
-Disable ${OSSP_RC_PREFIX} and ${OSSP_RC_SUFFIX} expansion on F<rcfile>.
-Disable searching for F<rcfile>. This mode assumes F<rcfile> is a filename. It
-is automagically entered when the F<rcfile> matches the regex '^\.{0,2}/'.
-
-=item B<-d>, B<--dirs> I<dir>[C<:>I<dir>[...]
-
-override OSSP_RC_DIRS, and use these paths to search for F<rcfile>s instead.
-
-=item B<-t>, B<--tmpdir> I<dir>
-
-specify the location of the temporary directory
-
-=item B<-v>, B<--verbose>
-
-verbosely report processing, including all warnings
-
-=item B<-s>, B<--silent>
-
-be silent, and disable output
+print short usage summary, then exit.
-=item B<-D>, B<--debug>
+=item B<-D>|B<--debug>
don't remove temporary files, and output debug messages to stderr
-=item B<-r>, B<--raw>
+=item B<-F>|B<--force>
-output text using no terminal control sequences
+Usually F<rcfile> is a fraction of a filename and the run command facility
+prefixes this name with ${OSSP_RC_PREFIX} and appends ${OSSP_RC_SUFFIX} to it,
+then searches the file in directories given using --dirs. If the initial
+F<rcfile> matches the regex '^\.{0,2}/', --force is automagically assumed.
-=back 4
-
-Mutually exclusive options, i.e. only a single one can be given
-
-=over 4
-
-=item B<-h>, B<--help>
-
-print this help, then exit
-
-=item B<-?>, B<--usage>
-
-print short usage summary, then exit.
-
-=item B<-V>, B<--version>
+=item B<-V>|B<--version>
print version and copyright, then exit
-=item B<-p>, B<--print>
+=item B<-c>|B<--conf> I<file>[C<:>I<file>[...]]
-output the commands as they would by seen by the command interpreter, but do
-not run them.
+specify the location of the configuration file. If omitted, the fallback is
+to look for C<$OSSP_RC_CONF>, and "@l_prefix@/etc/rc.conf", in that order.
-=item B<-e>, B<--eval>
+=item B<-d>|B<--dirs> I<dir>[C<:>I<dir>[...]]
-output the text for a command suitable for shell evaluation, but do not run
-it.
+directories to search for F<rcfile>s.
-=item B<-x>, B<--exec>
+=item B<-e>|B<--eval>
-execute the command interpreter in a subprocess and actually run the commands.
+output the commands text in a format suitable for shell evaluation, but do not run it.
-=item B<-q>, B<--query>
+=item B<-f>|B<--func> I<file>[C<:>I<file>[...]]
-print the value(s) of rc configuration variables defined in the %config section.
+specify the location of one or more optional function files. They act like
+libraries, containing commands which are prepended to the sections of their
+corresponding C<rcfile>s just before execution.
-=item B<-l>, B<--labels>
+=item B<-h>|B<--help>
-learn what section labels a F<rcfile> offers.
+print this help, then exit
-=item B<-i>, B<--info>
+=item B<-i>|B<--info>
print a comprehensive summary of the rc environment
-=back 4
-
-=head1 NOTES
-
-=over 4
+=item B<-l>|B<--labels>
-=item B<-h>, B<--help>, B<-V>, B<--version>, B<-v>, B<--verbose>, and B<-q>
-B<--silent>
+learn what section labels a F<rcfile> offers.
-The B<--help>, B<--version>, B<--verbose>, and B<--silent> options are used to
-control the screen output of B<rc> and control the general output of all
-sections found in the F<rcfile>s as well. For example, specifying
-B<--silent> will mute B<rc>'s output and also all command output that B<rc>
-runs.
-
-=item B<-r>, B<--raw> I<dir>
-
-The option B<-r> or B<--raw> turns on raw output mode. In this case, no
-formatting is done to the screen output. This mode is different from formatted
-output mode, in which the output is annotated with terminal control sequences
-for better readability.
-
-=item B<-t>, B<--tmp> I<dir>
-
-Specifying this option will force B<rc> to use the given temporary
-directory I<dir> for all its temporary output.
-
-=item B<-e>, B<--eval> and B<-p>, B<--print>
-
-With the B<--eval> or B<--print> options, the run command will not be
-executed. Rather, B<rc> will print a command suitable for later evaluation in
-the current shell. Given alone, this option will cause B<rc> to not execute
-the run command. Used together with B<--exec>, B<rc> will execute the run
-command and print a similar command for later execution as well. The B<--eval>
-option cannot be used together with B<--print>, because of conflicting output
-and the way that B<rc> constructs the evaluation text. Specifically, most
-Bourne shells and derivatives report errors with commands spanning multiple
-lines.
-
-Consider using the B<--eval> option for batch evaluation with the Bourne shell
-C<eval> command. Use the B<--print> option for better human readability. See
-`EXAMPLES' for an example.
-
-=item B<-x>, B<--exec>
-
-The B<--exec> is the most common option of all, in which B<rc> executes a run command
-made up of a given program and section. Options controlling the flow of
-execution include B<--print>, B<--eval>, and B<--exec>.
-
-=item B<-q>, B<--query>
-
-The B<--query> option queries the I<effective> value of one or more
-configuration variables. These variables are set in the C<%config> section of
-the corresponding F<rcfile>. The B<--query> option reports the
-I<effective> value, and not necessarily that written in the F<rcfile>
-file, which can be overridden by variable settings in the F<rc.env> file.
-
-Used with the B<--query> option, B<rc> will expect exactly one command line
-argument to follow. This must be a I<format> string containing arbitrary text
-and optionally one or more B<OSSP var> variable specifications
-("C<${>I<name>C<}>" in its simplest form.)
-!FIXME what is var here!
+=item B<-p>|B<--print>
-=back 4
+output the commands text in a format suitable for human reading, but do not run it.
-=head1 DEFAULT VALUES
+=item B<-q>|B<--query> I<format>
-=over 4
+query the effective value of configuration variables from the %config section
+and print them using the I<format> string specified in RPM style.
-In B<OSSP rc>, all options have a reasonable default value. This allows for a
-configurationless B<rc> installation.
+=item B<-r>|B<--raw>
-=item B<-r>, B<--raw>
+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
+runtime and is automagically disabled if stdout is detached from a terminal.
-The B<--raw> option determines its default at runtime. If the raw mode option
-is not specified, B<rc> will determine whether F<stdout> is connected to a
-terminal. If so, B<rc> will run in formatted output mode. If F<stdout> is not
-connected to a terminal (such as with most daemons,) B<rc> will run in raw
-output mode even though it was not specified as an option.
+=item B<-s>|B<--silent>
-=item B<-t>, B<--tmpdir> I<dir>
-
-If the B<--dirs> option is not given, B<rc> will try to use C<$TMPDIR>,
-C<$TEMPDIR>, C<~/tmp> and C</tmp> (in that order.)
+be silent, and disable output
-=item B<-p>, B<--print>, B<-e>, B<--eval>, B<-x>, B<--exec>
+=item B<-t>|B<--tmp> I<dir>
-If neither B<--print>, B<--eval>, or B<-exec> is given B<rc> will default to
-B<--exec>.
+specify the location of the temporary directory. If omitted, the fallback is
+to look for C<$TMPDIR>, C<$TMPDIR>, try using C<~/tmp> and C</tmp>, in that
+order.
-=item B<-c>, B<--conf> F<file>
+=item B<-v>|B<--verbose>
-Using F<file> from command line option -c aka --conf, fallback to
-${OSSP_RC_CONF}, fallback to "@l_prefix@/etc/rc.conf".
+be verbose, output what's going on.
-=item B<-f>, B<--func> F<file>[C<:>F<file>[...]]
-=item B<-F>, B<--force>
-=item B<-d>, B<--dirs> I<dir>[C<:>I<dir>[...]
+=item B<-x>|B<--exec>
-#!FIXME! Sprech mal von Pfad und Dateien defaults wieviel rc.conf erlaubt
-#!FIXME! sind, und welche genommen wird oder sonst wie gemerged.
+execute the command interpreter in a subprocess and actually run the commands.
+If neither B<--print>, B<--eval>, or B<-exec> is given, the default is
+B<--exec> anyway.
-F<rc.conf>
-F<rc.func>
-F<rc.env>
-F<rcfile>
+=back 4
=head1 ENVIRONMENT
=over 4
-Every command line longoption is also a keyword in the rc.conf file and,
+Every command line longoption is also a keyword in the F<rc.conf> file and,
prefixed with "OSSP_RC_" and it's name in upper case, also available as an
environment variable.
-The environment determines where rc will search before beginning to process
-run commands. It also influences B<rc's> behaviour, just as the command line
-options do. There is no difference between typing an option in the command
-line, and appending the same option to the OSSP_RC_OPTS variable.
-
-#!FIXME! Study this and determine if it is needed
-#OSSP_RC_IMPLS - Other rc implementations
-#
-#The OSSP_RC_IMPLS variable plays a role only when the user has more than one
-#logical set of run command sections. If rc reads anything but EOL in this
-#variable, it will assume that more than one rc implementation exists. The
-#variable should contain a chain of paths where other rc implementations are.
-#This allows the user to build several OSSP rc hierarchies and then switch from
-#each... Blah FIXME I don't know if we should be paying attention to the
-#ENVIRONMENT guys. Maybe this is not a good solution for our dynamic OpenPKG
-#environment problem after all.
-
=back 4
=head1 RETURN VALUE
=over 4
--1 Faulty run command hierarchy
+-1 Error in rc
0 Success
- 1 One or more run commands failed
+ 1 Error in command executed by rc
=back 4
@@ -398,30 +220,14 @@
command. This is often seen when importing the environment of packages of an
B<OpenPKG> hierarchy.
-=over 4
-
-$ eval `@l_prefix@/etc/rc --eval all env`
-
-=back 4
-
-=back 4
-
=head1 FILES
=over 4
F<rc.conf> - Master configuration file
-
-The following filenames are specified in F<rc.conf>. Both their names and
-locations may be different due to user customizations.
-
-=over 4
-
-F<rc.func> - User defined functions file
+F<rc.func> - User defined functions library
F<rc.env> - Postprocess variable declaration file
-F<rc.\<rcfile\>> - Run command file
-
-=back 4
+F<rc.foo> - Run commands for "foo" application
=back 4
@@ -437,24 +243,6 @@
=back 4
-=head1 DIAGNOSTICS
-
-=over 4
-
-If rc fails while processing a run command, the exit status will be 1. If rc
-failed due to a broken run command configuration, the exit status will be -1.
-This can happen if a script file is moved or renamed, for example. If the run
-command configuration is broken, no further action is taken and no run
-commands are processed.
-
-Importantly, if the keyword `all' is given as the program wildcard parameter,
-then processing will begin and continue until the first error is reached.
-Should an error arise, processing will stop and the exit status will be 1.
-There is no way to learn which command caused the error unless it is apparent
-from the text output of the rc process.
-
-=back 4
-
=head1 AUTHORS
=over 4
|
