##
##  rc.pod -- OpenPKG Run-Command Facility (Manual Page)
##  Copyright (c) 2000-2002 Cable & Wireless Deutschland GmbH
##  Copyright (c) 2000-2002 The OpenPKG Project <http://www.openpkg.org/>
##  Copyright (c) 2000-2002 Ralf S. Engelschall <rse@engelschall.com>
##
##  Permission to use, copy, modify, and distribute this software for
##  any purpose with or without fee is hereby granted, provided that
##  the above copyright notice and this permission notice appear in all
##  copies.
##
##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
##  SUCH DAMAGE.
##

# 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

=pod

=head1 NAME

B<rc> - OpenPKG Run-Command Facility

=head1 SYNOPSIS

rc [-h|--help] [-V|--version] [-v|--verbose]
   [-d|--debug] [-p|--print] [-e|--eval]
   [-c|--config] [-q|--query] [-r|--raw]
   <command> <section> [<section> ...]

=over 4

=item B<General>

@l_prefix@/etc/rc
[B<-f>|B<--rcfile> I<file>] 
[B<-d>|B<--rcdir> I<dir>[C<:>I<dir>[...]] 
[B<-C>|B<--rcconf> I<file>[C<:>I<file>[...]]] 
[B<-F>|B<--rcfunc> I<file>[C<:>I<file>[...]]] 
[B<-t>|B<--tmpdir> I<dir>]
[B<-r>|B<--raw>]
[B<-v>|B<--verbose>] 
[B<-D>|B<--debug>] 
[I<command-options>]
[I<command-arguments>]

=item B<Run-Command Execution>

@l_prefix@/etc/rc
[I<parameter-options>]
[B<-x>|B<--exec>] 
[B<-p>|B<--print>] 
[B<-e>|B<--eval>] 
I<package> 
I<command>

=item B<Configuration Query>

@l_prefix@/etc/rc
[I<parameter-options>]
[B<-q>|B<--query>] 
I<format>

@l_prefix@/etc/rc
[I<parameter-options>]
[B<-c>|B<--config>] 
[I<package>]

=item B<Facility Query>

@l_prefix@/etc/rc
[I<parameter-options>]
[B<-i>|B<--info>] 

@l_prefix@/etc/rc
[B<-h>|B<--help>]
[B<-V>|B<--version>] 

=head1 DESCRIPTION

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
sections. OSSP rc references these command entries by reading the
configuration file (see FILES) and searching the directory where the command
entries reside.

Each section of script code extends a type of functionality described by its
section label. This label is the same one given before the desired command(s).
Although only one section is possible for each call to OSSP rc, many
`commands' can follow the section label. This allows for an abbreviated input
format when calling the same script section of many commands. An example of
this is given in (EXAMPLES.)

=head1 PARAMETER OPTIONS

-h, --help
       print this help, then exit

-V, --version
       print version number, then exit

-v, --verbose
       verbosely report processing, including all warnings

-d, --debug
       don't remove any temporary files

-p, --print
       print the name of each section as it is processed

-e, --eval
       evaluate the nature of a fat tomato sandwich FIXME!

-c, --config
       locate the configuration file in the following path

-q, --query
       ask Ralf what he thinks about snails FIXME!

-r, --raw
       the sushi is too raw, and must be cooked longer FIXME!

All of these options have reasonable default values,
which OSSP rc assumes when no option is given.

=over 4

=item B<-f>, B<--rcfile> I<file>

=item B<-d>, B<--rcdir> I<dir>[C<:>I<dir>[...]

=item B<-C>, B<--rcconf> I<file>[C<:>I<file>[...]] 

=item B<-F>, B<--rcfunc> I<file>[C<:>I<file>[...]]

=item B<-t>, B<--tmpdir> I<dir>

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>.

=item B<-r>, B<--raw>

Control whether the output controlled by the options B<--config>,
B<--help>, B<--version> and B<--verbose> are raw text or annotated with
terminal control sequences for better readability. By default B<rc>
automatically determines whether F<stdout> is connected to a terminal or
not and uses terminal sequences in the output or respectively raw text
output only.

=item B<-v>, B<--verbose>

Enables verbose messages on F<stdout>.

=item B<-D>, B<--debug>

Enables debugging messages on F<stderr>.

=back4 

=head1 COMMAND OPTIONS

These options are mutually exclusive, i.e., you can specify only a
single one to select the type of operation.

=over 4

=item B<-x>, B<--exec>

This is the default where all run-commands are executed in sub-shells.
It expects exactly two non-option command line arguments: a I<package>
name and a I<command> name.

=item B<-p>, B<--print>

Instead of (by default) executing the run-commands, print them to
F<stdout> only.

=item B<-e>, B<--eval>

Instead of (by default) executing the run-commands in a sub-shell,
return a command suitable for evaluation the run-commands in the
current shell. Do not intermix this with option B<--print>, because
B<--eval> prepares the run-commands in a temporary file and just
outputs the necessary run and cleanup commands on F<stdout>. This is
because most Bourne-Shell flavors dislike to C<eval> commands spanning
multiple lines. So, B<--print> is for human readability and batch
post-processing, while B<--eval> is for batch evaluation through the
Bourne-Shell C<eval> command.

This is usually used from within F<.profile> files to import the shell
environment of the packages of an B<OpenPKG> hierarchy:

 $ eval `@l_prefix@/etc/rc --eval all env`

=item B<-q>, B<--query> 

Query the current (still default or overridden) value of one or more
run-command configuration variables (see rc-file section C<%config>).
It expects exactly one non-option command line argument: a I<format>
string. This is an arbitrary text string which can contain one or more
B<OSSP var> variable specifications ("C<${>I<name>C<}>" in its simplest
form).

=item B<-c>, B<--config>

=item B<-i>, B<--info>

Prints a summary of the whole run-command environment of B<rc>
and exits immediately.

=item B<-h>, B<--help>

Prints the B<rc> usage information and exits immediately.

=item B<-V>, B<--version>

Prints the B<rc> version and copyright information and exits immediately.

=back

=head1 RETURN VALUE

Will return an error every single time ;-)

=head1 EXAMPLES

/myetc/rc start sshd
/etc/rc close docview primary
/sfw/etc/rc restart lmtp2nntp
/cw/etc/rc restart apache

=head1 ENVIRONMENT

=head1 FILES

rc.conf

=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

=head1 WARNINGS

=head1 DIAGNOSTICS

Rc will print out error messages to stderr. The messages can be used to
diagnose possible sources of failure of the chosen command, or even within the
run command structure itself. FIXME! Marcus Bemerkung. The possible errors
observed include the following.

=over 4

OSSP rc: The ice cream is too hot
Possible solution: This error happens alot.

OSSP rc: The hot chocolate has a fly in it
Possible solution: Just take the fly out and drink the coffee.

=back 4

=head1 BUGS

=head1 RESTRICTIONS

Bugs we don't plan to fix include washing out the bathtub.

=head1 AUTHORS

Ralf S. Engelschall
Michael Schloh von Bennewitz

=head1 HISTORY

Part of the OpenPKG distribution. Had its start in OpenPKG development.

=cut