diff -r 333964c621f1 -r cb59d6afeb61 openpkg/rpmtool.pod
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/openpkg/rpmtool.pod	Tue Jan 06 23:40:39 2009 +0100
@@ -0,0 +1,190 @@
+##
+##  rpmtool.pod -- OpenPKG RPM Auxiliary Tool (Manual Page)
+##  Copyright (c) 2000-2007 OpenPKG Foundation e.V. <http://openpkg.net/>
+##  Copyright (c) 2000-2007 Ralf S. Engelschall <http://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.
+##
+
+=pod
+
+=head1 NAME
+
+B<rpmtool> - RPM Auxiliary Tool
+
+=head1 SYNOPSIS
+
+B<rpmtool>
+I<command>
+[I<command-options>]
+
+=head1 DESCRIPTION
+
+This is an auxiliary tool to the RedHat Package Manager (RPM). It
+provides additional functionality for use in RPM I<spec> files while
+building packages. The following I<command>s are available:
+
+=over 4
+
+=item B<platform>
+
+This command outputs a unique platform id in the format
+"<architecture>-<system><release>". For instance, the output on a
+FreeBSD platform can be "i386-freebsd4.2", the output on a Linux
+platform can be "i686-linux2.2.16", the output on a Solaris platform can
+be "sun4u-sunos5.8", etc.
+
+Example:
+
+ case `rpmtool platform`; in
+     *-freebsd[34].* ) ... ;;
+     *-sunos5.[678]  ) ... ;;
+     *-linux2.[24].* ) ... ;;
+ esac
+
+=item B<mflags> [B<-O>] I<tool>
+
+This command outputs additional flags for make(1) for
+use with the program I<tool>. It provides only standard flags which
+always can be used. In conjunction with B<-O> (optimization), it also provides
+reasonable job control for use on multi-processor platforms (for instance it
+outputs "-j4" on an SMP system with 2 CPUs if GNU make or BSD pmake is used).
+
+Example:
+
+ make `rpmtool mflags -O make`
+
+=item B<cflags> [B<-O>] I<tool>
+
+This command outputs additional flags for cc(1) for use with the program
+I<tool>. It provides only standard flags which always can be used.
+conjunction with B<-O> it provides also optimization flags (for instance
+it outputs "-O2 -pipe" for GNU C/C++ compiler).
+
+Example:
+
+ CC="$CC" CFLAGS=`rpmtool cflags -O $CC` ./configure ...
+
+=item B<cppflags> [B<-p> I<prefix>] [[C<+|->I<subdir> ...]
+
+This command output cpp(1) C<-I> options for the OpenPKG instance
+I<prefix>. It optionally can prefix or suffix with one or more I<subdir>
+related options, too. If I<subdir> is prefixed with C<+> (or not
+prefixed at all), the generated option is appended. If I<subdir> is
+prefixed with C<-> the generated option is prepended.
+
+Example:
+
+ rpmtool cppflags -p /foo bar -baz +quux
+
+=item B<ldflags> [B<-p> I<prefix>] [[C<+|->I<subdir> ...]
+
+This command output ld(1) C<-L> options for the OpenPKG instance
+I<prefix>. It optionally can prefix or suffix with one or more I<subdir>
+related options, too. If I<subdir> is prefixed with C<+> (or not
+prefixed at all), the generated option is appended. If I<subdir> is
+prefixed with C<-> the generated option is prepended.
+
+Example:
+
+ rpmtool ldflags -p /foo bar -baz +quux
+
+=item B<files> [B<-v>] [B<-o> I<outfile>] [B<-r> I<build-root>] [I<entry> ...]
+
+This is a dynamic variant of the RPM C<%files> section, i.e., it
+dynamically creates the contents of the C<%files> section for use with
+the C<%files -f> command. For this the file list entries are read from
+the command line (or from stdin if no arguments are given or a single
+argument C<-> is given) and written to stdout (if no B<-o> option is
+given or its I<outfile> argument is C<->) or to I<outfile>.
+
+The trick of this approach is to be able to use additional features in
+the file list which RPM does not provide. The following features are
+provided:
+
+=over 4
+
+=item B<Trailing Tags>
+
+RPM requires that all tags (like C<%attr(...)> or C<%dir>) preceed the
+path in a file list entry. This sometimes leads to ugly and unreadable
+file lists, because all paths cannot be left-aligned. With rpmtool(8)
+tags in the input file list can be at leading and trailing positions.
+The output file list will nevertheless have all tags in leading
+positions for RPM.
+
+=item B<Syntactical Set Pattern>
+
+RPM supports simple wildcard patterns like C</path/*> or C</path/[a-z]>,
+etc. Sometimes it is convenient, to also have (in addition to character
+sets) string sets like C</path/{foo,bar,quux}>. rpmtool(8) provides this
+by syntactically (without checking the filesystem) expanding those
+string sets.
+
+=item B<Overriding Entries>
+
+This is the most important feature and the reason why shtool(1)'s
+B<files> command was implemented. Although RPM allows one to specify a
+directory in a file list and then implicitly expands this recursively
+into its contents, it unfortunately does not allow one to later
+explcitly override particular entries (usually if an individual
+C<%attr(...)> tag is required). rpmtool(8) now supports overriding
+entries, i.e., if a path occurs multiple times, only the last occurance
+is kept.
+
+=item B<Negation Tag>
+
+This provides an additional tag C<%not> which can be used to explicitly
+exclude a previously implicitly added entry.
+
+=back
+
+Example:
+
+ %install
+   :
+ rpmtool files -o files -r$RPM_BUILD_ROOT \
+     '%defattr(-,foo,foo)' \
+     '%{prefix}' \
+     '%attr(1755,root,foo) %{prefix}/bin/bar' \
+     '%not %dir {%{prefix},%{prefix}/*,%{prefix}/man/*}' \
+     '%not %{prefix}/info/dir'
+
+ %files -f files
+
+=item B<msg> [B<-b>]
+
+This displays the contents of F<stdin> as a boxed message. If option
+B<-b> is given it additionally beeps once before displaying the box.
+
+=back
+
+=head1 HISTORY
+
+This tool was created in November 2000 for use in OpenPKG, the
+cross-platform RPM-based Unix software packaging facility.
+
+=head1 AUTHOR
+
+ Ralf S. Engelschall
+ rse@engelschall.com
+ www.engelschall.com
+
+=cut
+