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

=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 PARAMETER OPTIONS

All these options have reasonable builtin defaults by can be used to
adjust one or more parameters of the B<rc> facility.

=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

=cut