--- rc.pod 2002/01/22 20:10:27 1.7
+++ rc.pod 2002/01/23 13:09:20 1.8
@@ -27,17 +27,27 @@
=head1 NAME
+=over 4
+
B<rc> - OSSP Run Command Facility
+=back 4
+
=head1 SYNOPSIS
+=over 4
+
rc [-h|--help] [-V|--version] [-v|--verbose]
[-d|--debug] [-p|--print] [-e|--eval]
[-c|--config] [-q|--query] [-r|--raw]
<command> <section> [<section> ...]
+=back 4
+
=head1 DESCRIPTION
+=over 4
+
OSSP rc is a run command processor. It applies the script code associated with
a given section label to one or more given commands. The command(s) must each
have entries in the form rc.<command> including script code grouped into
@@ -52,81 +62,90 @@
format when calling the same script section of many commands. An example of
this is given in `EXAMPLES.'
+=back 4
+
=head1 OPTIONS
=over 4
+!FIXME! Remark, difference between PARAMETER OPTIONS and COMMAND OPTIONS
+
Inclusive options which may be used with another
-=item B<-c>, B<--config>
+=item B<-c>, B<--config> F<file>
+specify the location of the configuration file,
+overriding the environment variable $OSSP_RC_ROOT
+
+=item B<-n>, B<--func> F<file>[C<:>F<file>[...]]
+specify the location of an optional functions file,
+containing Bourne shell script code
-locate the configuration file in the following path,
-overriding the environment variable $OSSP_RC_ROOT when
-locating the configuration file
+=item B<-f>, B<--file> F<file>
+use the configuration and section data of a particular file
-=item B<-v>, B<--verbose>
+=item B<-d>, B<--dirs> I<dir>[C<:>I<dir>[...]
+override OSSP_RC_ROOT, and use these paths 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>
-
hold silence, and output no text messages whatsoever
=item B<-d>, B<--debug>
-
don't remove temporary files, and output debug messages to stderr
=item B<-r>, B<--raw>
-
output text using no terminal control sequences
Mutually exclusive options, i.e. only a single one can be given
=item B<-h>, B<--help>
-
print this help, then exit
=item B<-V>, B<--version>
-
print version and copyright, then exit
=item B<-p>, B<--print>
-
output the text as it would be interpreted
by the shell, but do not run the commands
=item B<-e>, B<--eval>
-
output the text for a command suitable for shell evaluation
=item B<-x>, B<--exec>
-
execute in subshell(s), follow with <program> <section>
=item B<-q>, B<--query>
-
print the value(s) of rc configuration variables
=item B<-l>, B<--labels>
-
-learn what section labels a run command extends
+learn what section labels a run command offers
=item B<-i>, B<--info>
-
print a comprehensive summary of the rc environment
All of these options have reasonable default values, which OSSP rc assumes
-when no option is otherwise given. For details of each listed option see
+when no option is otherwise given. For details of some listed option see
`NOTES'.
=back 4
=head1 RETURN VALUE
+=over 4
+
Returns zero if successful, or nonzero if otherwise.
+=back 4
+
=head1 ERRORS
+=over 4
+
-1 Faulty run command hierarchy
0 Success
1 First (or only) run command failed
@@ -136,8 +155,12 @@
Positive error values are indexed to their respective run commands by command
line ordering. For more information see `DIAGNOSTICS.'
+=back 4
+
=head1 EXAMPLES
+=over 4
+
Some short one line examples include the following. Note that a run command
consists of a single program name and one or more sections. The wildcard `all'
can be given in place of a program name to denote all programs with entries in
@@ -159,50 +182,6 @@
$ eval `@l_prefix@/etc/rc --eval all env`
-=head1 ENVIRONMENT
-
-OSSP_RC_ROOT - Where the OSSP rc hierarchy is located
-OSSP_RC_OPTIONS - Options, same as the command line ones
-
-The environment determines where rc will look before beginning to process run
-commands. It also influences the behaviour, just as the command line options
-do. There is no difference between typing an option in the command line, and
-adding the same option to the OSSP_RC_OPTIONS variable.
-
-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.
-
-=head1 FILES
-
-/$OSSP_RC_ROOT/rc.conf - Configuration file
-
-=head1 SEE ALSO
-
-OSSP rc integrates concepts taken from other run command architectures. For
-more information, inspect the /etc/rc structures provided by FreeBSD, Solaris,
-and Red Hat distributions.
-
-biff(1), bagg(1), honk(1), gonk(1), and quatch(1).
-
-=head1 NOTES
-
-=nada
-
-# ref: %start; %stop
-# cfg
-# --glob-rcfile='rc.%s'
-# --regex-section='(?<=^|\n)%%%s\s*\n(.+?)(?=\n%\S+|$)'
-# --regex-reference='(?<=^|\n)%%%s\s*(.+?)(?=\n|;)'
-# def --showdefault, --defsetion=config
-
=item B<General>
@l_prefix@/etc/rc
@@ -247,38 +226,69 @@
@l_prefix@/etc/rc
[B<-h>|B<--help>]
-[B<-V>|B<--version>]
+[B<-V>|B<--version>]
+
+=back 4
+
+=head1 ENVIRONMENT
=over 4
-=item B<-f>, B<--rcfile> I<file>
+OSSP_RC_ROOT - Where the OSSP rc hierarchy is located
+OSSP_RC_OPTIONS - Options, same as the command line ones
-=item B<-d>, B<--rcdir> I<dir>[C<:>I<dir>[...]
+The environment determines where rc will look before beginning to process run
+commands. It also influences the behaviour, just as the command line options
+do. There is no difference between typing an option in the command line, and
+adding the same option to the OSSP_RC_OPTIONS variable.
-=item B<-C>, B<--rcconf> I<file>[C<:>I<file>[...]]
+OSSP_RC_IMPLS - Other rc implementations
-=item B<-F>, B<--rcfunc> I<file>[C<:>I<file>[...]]
+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.
-=item B<-t>, B<--tmpdir> I<dir>
+=back 4
-Force the use of a particular temporary directory. By default B<rc>
-tries to use (in this order) C<$TMPDIR>, C<$TEMPDIR>, C<~/tmp> and
-C</tmp>.
+=head1 FILES
-!FIXME! Remark, difference between PARAMETER OPTIONS and COMMAND OPTIONS
+=over 4
+
+/$OSSP_RC_ROOT/rc.conf - Configuration file
-=nada
+=back 4
+
+=head1 SEE ALSO
=over 4
-=item B<-v>, B<--verbose>
- verbosely report processing, including all warnings
+OSSP rc integrates concepts taken from other run command architectures. For
+more information, inspect the /etc/rc structures provided by FreeBSD, Solaris,
+and Red Hat distributions.
-=item B<-s>, B<--silent>
- hold silence, and output no text messages whatsoever
+biff(1), bagg(1), honk(1), gonk(1), and quatch(1).
-=item B<-d>, B<--debug>
- don't remove any temporary files, and output debug messages
+=back 4
+
+=head1 NOTES
+
+=over 4
+
+# ref: %start; %stop
+# cfg
+# --glob-rcfile='rc.%s'
+# --regex-section='(?<=^|\n)%%%s\s*\n(.+?)(?=\n%\S+|$)'
+# --regex-reference='(?<=^|\n)%%%s\s*(.+?)(?=\n|;)'
+# def --showdefault, --defsetion=config
+
+!FIXME! Remark, difference between PARAMETER OPTIONS and COMMAND OPTIONS
+
+=over 4
As expected, when B<rc> has output it will write ASCII text to F<stdout> for
normal output, and F<stderr> for abnormal output (such as warnings and
@@ -294,16 +304,13 @@
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<-c>, B<--config>
- locate the configuration file in the following path,
- overriding the environment variable $OSSP_RC_ROOT when
- locating the configuration file
+=item B<-t>, B<--tmpdir> I<dir>
-=item B<-p>, B<--print>
- output the text as it would be interpreted
- by the shell, but do not run the commands
+Specifying this option will force B<rc> to use the given temporary directory
+I<dir> for all its temporary output. If this option is not given, B<rc> will
+try to use C<$TMPDIR>, C<$TEMPDIR>, C<~/tmp> and C</tmp> (in that order.)
-=item B<-e>, B<--eval>
+=item B<-e>, B<--eval> and B<-p>, B<--print>
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
@@ -336,16 +343,16 @@
containing arbitrary text and optionally one or more B<OSSP var> variable
specifications ("C<${>I<name>C<}>" in its simplest form.)
-=item B<-l>, B<--labels>
- learn what section labels a run command extends
-
-=item B<-i>, B<--info>
- print a comprehensive summary of the rc environment
-
=back 4
=head1 WARNINGS
+=over 4
+
+There are no warnings. OSSP rc is perfect ;-)
+
+=back 4
+
=head1 DIAGNOSTICS
=over 4
@@ -377,23 +384,37 @@
=head1 BUGS
+=over 4
+
!FIXME!
To report a bug, please visit the web page http://www.ossp.org/bugdb.html. Be
sure to include the word "rc" in the subject field of your bug report.
OSSP rc contains no known bugs to date.
+=back 4
+
=head1 RESTRICTIONS
+=over 4
+
Bugs we don't plan to fix include washing out the bathtub. !FIXME!
+=back 4
+
=head1 AUTHORS
+=over 4
+
Ralf S. Engelschall
Michael Schloh von Bennewitz
+=back 4
+
=head1 HISTORY
+=over 4
+
OSSP rc was born to replace the run command logic used in the OpenPKG project.
In the first version of OpenPKG (http://www.openpkg.org), a run command script
called `rc' could issue run commands to programs installed under the OpenPKG
@@ -404,4 +425,6 @@
that OSSP rc can be used for any project needing generic run command logic as
well as the OpenPKG project as first planned.
+=back 4
+
=cut
|
