Index: ossp-pkg/rc/00TODO RCS File: /v/ossp/cvs/ossp-pkg/rc/00TODO,v rcsdiff -q -kk '-r1.5' '-r1.6' -u '/v/ossp/cvs/ossp-pkg/rc/00TODO,v' 2>/dev/null --- 00TODO 2002/01/18 16:47:17 1.5 +++ 00TODO 2002/01/23 13:09:20 1.6 @@ -5,6 +5,7 @@ Enclose rc.c in its own project and write autoconf logic. Must do + Automake raus. Translate rc bourne shell script to ANSI C. Finish man page. Start latex or Docbook guide. Remove autogen.sh after devtool is finished. Index: ossp-pkg/rc/rc.pod RCS File: /v/ossp/cvs/ossp-pkg/rc/rc.pod,v rcsdiff -q -kk '-r1.7' '-r1.8' -u '/v/ossp/cvs/ossp-pkg/rc/rc.pod,v' 2>/dev/null --- 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 - 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]
[
...] +=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. 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 +specify the location of the configuration file, +overriding the environment variable $OSSP_RC_ROOT + +=item B<-n>, B<--func> F[C<:>F[...]] +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 +use the configuration and section data of a particular file -=item B<-v>, B<--verbose> +=item B<-d>, B<--dirs> I[C<:>I[...] +override OSSP_RC_ROOT, and use these paths instead + +=item B<-t>, B<--tmpdir> I +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
=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 @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 +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[C<:>I[...] +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[C<:>I[...]] +OSSP_RC_IMPLS - Other rc implementations -=item B<-F>, B<--rcfunc> I[C<:>I[...]] +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 +=back 4 -Force the use of a particular temporary directory. By default B -tries to use (in this order) C<$TMPDIR>, C<$TEMPDIR>, C<~/tmp> and -C. +=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 has output it will write ASCII text to F for normal output, and F for abnormal output (such as warnings and @@ -294,16 +304,13 @@ connected to a terminal (such as with most daemons,) B 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 -=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 to use the given temporary directory +I for all its temporary output. If this option is not given, B will +try to use C<$TMPDIR>, C<$TEMPDIR>, C<~/tmp> and C (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 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 variable specifications ("C<${>IC<}>" 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