##
##  shtool.pod -- Manual Page in Plain Old Document (POD) format
##
##  This file is part of shtool and free software; you can redistribute
##  it and/or modify it under the terms of the GNU General Public
##  License as published by the Free Software Foundation; either version
##  2 of the License, or (at your option) any later version.
##
##  This file is distributed in the hope that it will be useful,
##  but WITHOUT ANY WARRANTY; without even the implied warranty of
##  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
##  General Public License for more details.
##
##  You should have received a copy of the GNU General Public License
##  along with this program; if not, write to the Free Software
##  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
##  USA, or contact Ralf S. Engelschall <rse@engelschall.com>.
##

=pod

=head1 NAME

B<GNU shtool> - The GNU Portable Shell Tool

=head1 VERSION

SHTOOL_VERSION_STR

=head1 SYNOPSIS

B<shtool> 
[ I<global_options> ] 
I<command> 
[ I<command_options> ] 
[ I<command_args> ]

=head1 DESCRIPTION

The B<GNU shtool> program is a compilation of small but very stable and
portable shell scripts into a single shell tool. All ingredients were in
successful use over many years in various free software projects. The
compiled B<shtool> program is intended to be used inside the source tree of
those free software packages.  There it can take over various (usually
non-portable) tasks related to the building and installation of such
packages.

=head2 Context Background

For the configuration, build and installation environment of modern free
software packages one nowadays uses GNU B<autoconf> and friends (i.e.
usually B<autoconf>, B<automake> and B<libtool>). B<Autoconf> covers the
configuration, B<automake> covers the generation of the build environment and
B<libtool> covers most of the build process itself. But at least when it comes
to the installation step one usually have to use a few auxiliary scripts like
C<mkdir.sh>, C<install.sh>, etc.  And these things are usually all the time
needed. The result is usually an C<etc/> subdirectory in the source tree where
over time a lot shell scripts accumulate.

=head2 Maintainance Problem

The problem with those C<etc/> shell scripts starts when one has to maintain
I<lots> of free software packages as it's the case for the author of B<shtool>.
Then over time all C<etc/> directories diverge and with every day it gets more
and more nasty to always keep them in sync. Especially when some scripts
were locally adjusted because no centralized maintainance location exists, of
course. For B<autoconf> no such problem exists, because the resulting
C<configure> script is generated on-the-fly. The same applies to B<automake>
and the various C<Makefiles>. 

Only for B<libtool> one always has to grab the latest copy. But because it's
just two files (C<ltmain.sh> and C<ltconfig>), keeping a source trees in sync
is not too complicated (especially not when using C<libtoolize>). But the
C<etc/> shell script mess is nasty, especially because there is no master
version on the net. Additionally everytime one starts a new project, one has
to establish a new source tree. For a hacker it's immediately clear that
B<autoconf> and friends are part of the game. But which C<etc/> shell scripts
are needed this time? And from which existing source tree to copy them from?
Hmmm...

=head2 The Aesthetic Problem

When a free software package has a large source tree (say, more than 50 files
and especially with one or more subdirectories) it's usually no problem to
have an additional C<etc/> subdirectory with some scripts. They then totally
go down. But for smaller packages, especially those living in a single source
directory (a degenerated tree), some people like the author of B<shtool> have
aesthetic problems. Because it looks strange to them that 20% of the files in
the source tree are just auxiliary scripts. Sure, the actual amount of script
code even B<shtool> cannot reduce, but B<shtool> merges them together into a
single file and this way they optically totally disappear from the source
tree. 

This is a pure aesthetical issue, of course. But hey, hacking is a piece of
art. And a source tree is a piece of art for hackers, too.  Oh, and those who
insist on a technical reason: it's also easier to upgrade a single file than
multiple files ;)

=head2 Filling the gap

So, wouldn't it be nice to have a fourth package (beside B<autoconf>,
B<automake> and B<libtool>) which fills the gap, i.e.  which provides the
functionality of the old files in C<etc/>, is maintained externally and at a
centralized location and even consists of just a single (perhaps large) script
one can overtake as a black box the same way one already does this for
B<libtool>? The author thought this I<would> be actually very useful and the
result is the current B<shtool> package which at least successfully solved the
above problems of the author.

=head2 The goals in detail

To better understand the intentions behind B<shtool>, here are the original
goals of the B<shtool> script: 

=over 3

=item B<1. It has to be self-contained and reside in a single file>

This was achieved by compiling the resulting B<shtool> script out of the
ingredient source scripts. The advantage is that B<shtool> is still easily
maintainable, because one can test each script seperately. But the final
functionality then resides in an all-in-one script which can be easily spread
over multiple source trees.

=item B<2. It has to cover all functionality of the old scripts>

This was achieved by (re)implementing really all functionality which
experience showed is important in source trees of typical free software
packages.  

=item B<3. It has to be maximum portable over all Unix flavors>

This was achieved by using only well-proven shell code which already survived
practice in other projects over more than a few months. Especially this means
that a lot of complicated emulations are done to avoid the use of unportable
Unix programs (like C<fmt>, C<tr>, etc) or unportable features of well-known
Unix programs (like shell functions, special C<sed> features, etc. pp).
That's why B<shtool>'s code sometimes looks crazy and like overkill.  But it's
often this way mainly for portability reasons.

=item B<4. It has to be clean and fully documented>

This was achieved by reimplementing too ugly functionality from scratch and
cleaning up old shell script code plus writing this manual page.  

=item B<5. It has to stay under a reasonable and common license>

This was achieved by placing the B<shtool> package under the GNU General
Public License (GPL).  This way the B<shtool> package itself is well protected
and will always be free software, but the resulting B<shtool> script can be
nevertheless I<used> in I<all> types of source trees.  Notice here: given that
one includes GNU B<shtool> verbatim into an own source tree, one is justified
in saying that it remains separate from the own package, and that this way one
is simply just I<using> B<shtool>.  So, in this situation, there is no
requirement that the package itself is licensed under the GNU General Public
License in order to take advantage of B<shtool>. Keep this in mind ;)

=back

=head1 GLOBAL OPTIONS

The following I<global options> are available for B<shtool>. Any I<command>s
are ignored when one of them is present on the B<shtool> command line.

=over 4

=item B<-h>

Displays a short help page describing the usage of B<shtool> and it's
ingredient I<command>s in a compact way.

=item B<-v>

Displays the version number of B<shtool>.

=back 

=head1 COMMANDS

The following I<command>s are provided by B<shtool>. They are all called via
``C<shtool> I<command>''. Any trailing I<command_options> are specific to the
particular I<command>. 

=over 12

=item B<echo>

echo(1) style print command providing special expansion constructs (terminal
bold mode, environment details, date) and newline control.

=item B<mdate>

Pretty-prints the last modification time of a file or directory.

=item B<table>

Pretty-print a field-sperarated list as a table.

=item B<prop> 

Display a processing indication though a running propeller.

=item B<move>

mv(1) style command, but can rename/move multiple files at once and allows
source files just to be deleted when contents doesn't change.

=item B<install>

Install a program, script or datafile in a portable way.

=item B<mkdir>

mkdir(1) style command providing support for auto-parent-dir creation,
directory permission control and smart skipping when directory already
exists.

=item B<mkln>

ln(1) style command providing automatic calculation and usage of relative
links when possible.

=item B<mkshadow>

Create a shadow source tree by the help of symbolic links.

=item B<fixperm>

Fix file permissions inside a source tree by cleaning up the permission bits.

=item B<guessos>

Simple operating system and platform architecture guesser which
determines a GNU I<platform-triple> style identification string.

=item B<arx>

Extended archive command which can even put existing archives into an archive.

=item B<slo>

Separate linker options by library class.

=item B<scpp>

An additional C source file pre-processor for sharing cpp(1) code, internal
variables and internal functions.

=item B<version>

Generate and maintain a version information file in either text, C or Perl
format.

=item B<path>

Deal with shell path variables.

=back

=head1 COMMAND DESCRIPTION

In the following the available I<commands> and their corresponding
I<command_options> are described in detail.

=over 4

=item B<echo> [B<-n>] [B<-e>] I<str>

This is an echo(1) style print command which provides special expansion
constructs (terminal bold mode, environment details, date) and newline
control.  Per default I<string> is written to I<stdout> followed by a newline
character (``C<\n>''). When option ``B<-n>'' is used this newline character is
left out. 

The I<str> can contain special ``B<%>I<x>'' constructs which which are
expanded before the output is written when option ``B<-e>'' is used.
Currently the following constructs are recognized: ``B<%B>'' for switching to
terminal bold mode, ``B<%b>'' for switching terminal mode back to normal
display mode, ``B<%u>'' for the current user name, ``B<%U>'' for the current
user id (numerical), ``B<%h>'' for the current hostname, ``B<%d>'' for the
current domain name, ``B<%D>'' for the current day of the month, ``B<%M>'' for
the current month (numerical), ``B<%m>'' for the current month name and
``B<%Y>'' for the current year.

The trick of this command is that it provides a portable ``B<-n>'' option and
hides the gory details needed to find out the environment details.

Examples:

 #   shell script
 shtool echo -n -e "Enter your name [%B%u%b]: "; read name
 shtool echo -e "Your Email address might be %u@%h%d"
 shtool echo -e "The current date is %D-%m-%Y"

=item B<mdate> [B<-n>] [B<-z>] [B<-s>] [B<-d>] [B<-f> I<str>] [B<-o> I<spec>] I<path>

This command pretty-prints the last modification time of a file or directory
I<path>. Option ``B<-n>'' suppresses the output of a trailing newline
character, option ``B<-z>'' pads numeric day (and optionally month) with a
leading zero, option ``B<-s>'' shortens the months name to an abbreviation of
three characters, option ``B<-d>'' replaces the month name with the
corresponding digits, option ``B<-f>'' uses I<str> as the field separator
(default is a single space character) and option ``B<-o>'' specified the order
in which the fields are printed. The default for I<spec> is ``C<dmy>'' which
means an output of ``<day> <month> <year>''.  Any combination of the chars
``C<d>'', ``C<m>'' and ``C<y>'' or allowed for I<spec>.

The trick of this command is that it provides a portable way to find out the
date of a file or directory while still allowing one to specify the format of
the date display.

Examples:

 #   shell script
 shtool mdate -n /
 shtool mdate -f '/' -z -d -o ymd foo.txt
 shtool mdate -f '-' -s foo.txt

=item B<table> [B<-F> I<sep>] [B<-w> I<width>] [B<-c> I<cols>] [B<-s> I<strip>] I<str>B<sep>I<str>...

This pretty-prints a I<sep>-sperarated list of I<str>ings as a table.  Per
default a colon-seperated list (I<sep>=":") is pretty printed as a
three-column (<cols>=3) table no longer than 79 chars (I<strip>=79) is
generated where each column is 15 characters wide (I<width>=15). 

The trick of this command is that it avoids to use the unportable tr(1) and
fmt(1) commands and instead is based entirely on sh(1), awk(1) and sed(1)
functionality.

Example:

 #   shell script
 shtool table -F , -w 5 -c 4 "1,2,3,4,5,6,7,8,9,10,11,12"

=item B<prop> [B<-p> I<str>]

This command displays a processing indication though a running propeller. The
option ``B<-p>'' can be used to set a particular prefix I<str> which is
displayed in front of the propeller. The default is no prefix string, i.e. the
propeller is at the left border of the terminal.  This command is intended to
be run at the end of a pipe (``C<|>'') sequence where on C<stdin>
logging/processing informations found.  For every line on C<stdin> the
propeller cycles one step clock-wise.

The trick of this command is that it provides a portable and easy to use way
to display such nice and psychologically important process indicators.

Example:

 #   shell script
 configure 2>&1 |\
     tee logfile |\
     shtool prop -p "Configuring sources"

=item B<move> [-e] [-p] I<src-file> I<dst-file>

This is a mv(1) style command, but with two special features: First when
option ``B<-e>'' (`expand') is used and an asterisk occurs somewhere in I<src>
one can use ``C<%>I<n>'' (where I<n> is C<1>,C<2>,...) in I<dst-file>. This is
useful for renaming multiple files at once.  Second, when option ``B<-p>''
(for `preserve') is used and I<src-file> and I<dst-file> are byte-wise the
same it just deletes I<src-file>. The intention is that the permissions and
time stamps on I<dst> are't changed which is important when I<dst-file> is
used in conjunction with Makefiles.

The trick of this command is that it can rename multiple files at once and
preserves the timestamps when the contents isn't changed.

Examples:

 #   shell script
 shtool move -e *.txt %1.asc

 #   Makefile
 scanner.c: scanner.l
     lex scanner.l
     shtool move -p lex.yy.c scanner.c

=item B<install> [B<-c>] [B<-C>] [B<-s>] [B<-m> I<mode>] [B<-o> I<owner>] [B<-g> I<group>] [B<-e> I<ext>] <file> I<path>

This command installs a program, script or datafile (dependent on I<mode>) in
a portable way while providing all important options of the BSD install(1)
command. Per default I<file> is moved to the target I<path>, but with option
``B<-c>'' I<file> is copied. The target file is created with owner/group set
to the current active uid/gid, but when this script is called as root (uid 0)
the options ``B<-o>'' and ``B<-g>'' can be used to override this. Additionally
program executables is stripped with strip(1) after installation when option
``B<-s>'' is used.  Option ``B<-C>'' is like ``B<-c>'', except if the
destination file already exists and the files are the same, the source is just
removed.  Option ``B<-e>'' can be used to set an implicit executable
extension.

The trick of this command is that it provides the functionality of BSD
install(1) in a portable emulated way.

Example:

 #   Makefile
 install:
      :
     shtool install -c -s -m 4755 foo $(bindir)/
     shtool install -c -m 644 foo.man $(mandir)/man1/foo.1

=item B<mkdir> [B<-f>] [B<-p>] [B<-m> I<mode>] I<dir> [I<dir> ...]

This is a mkdir(1) style command providing support for auto-parent-dir
creation (when option ``B<-p>'' is used), directory permission control (with
option ``B<-m> I<mode>'' where I<mode> can be in any of the formats specified
to the chmod(1) command) and smart skipping when I<DIR> already exists
(triggered by the force option ``B<-f>'').

The trick of this command is that it provides both a portable ``B<-p>''
functionality and the ability to be smart when the directory already exists
which is important for installation procedures.

Example:

 #   Makefile
 install:
     shtool mkdir -f -p -m 755 $(bindir)
     shtool mkdir -f -p -m 755 $(mandir)/man1
      :

=item B<mkln> [B<-v>] [B<-f>] [B<-s>] I<src-path> [I<src-path> ...] I<dst-path>

This is a ln(1) style command which provides automatic calculation and usage
of relative links when possible, i.e. usually when I<src-path> and I<dst-path>
are not absolute paths or at least they share a common prefix except the root
directory (``C</>''). When more than one I<src-path> is specified, all of them
are linked into I<dst-path>. Options ``B<-f>'' and ``B<-s>'' are similar to
ln(1), i.e.  they force the creation of the link (even when it exists) and
create a symbolic link instead of a hard-link. Option ``B<-v>'' is just
interesting for debugging the complicated paths calculation.

The trick of this command is that it tried hard to calculate the paths to get
the maximum possible relative paths.

Example:

 #   shell script
 shtool mkln -s foo/bar baz/quux

=item B<mkshadow> [B<-v>] I<src-dir> I<dst-dir>

This command creates a shadow tree of I<src-dir> under I<dst-dir> by the help
of symbolic links. Here the directory hierarchy of I<src> is recreated under
I<dst-dir> and the files of I<src-dir> are linked into the corresponding
directories under I<dst-dir> via symbolic links. When I<src-dir> can be
reached via releative paths from I<dst-dir>, relative symbolic links are used,
too.  Option ``B<-v>'' can be used to enable some displaying of processing
information.

The trick of this is that is provides such a high-level functionality with a
single command and hides all gory details.

Example: 

 #   shell script
 shtool mkshadow . /tmp/shadow

=item B<fixperm> [B<-v>] I<path> [ I<path> ... ]

This command fixes file permissions inside a source tree under I<path> by
cleaning up the permission bits. It determines the cleaned up permission from
the already set bits. It's intended to be run before a tarball is rolled out
of the source tree. Option ``B<-v>'' can be used to display some processing
information.

The trick is that this is more convinient that having to set the permissions
manually or with a large file list.

Example:

  #  Makefile.in
  dist:
      shtool fixperm -v *

=item B<guessos>

This command is a simple operating system and platform architecture guesser
which determines a so-called ``GNU I<platform-triple>'' style identification
string ``I<arch>-I<hardware>-I<os>I<osversion>''. For instance a FreeBSD 3.1
running on a Pentium II is identified as ``C<i686-pc-freebsd3.1>''.  When you
need a more sophisticated platform guesser, use the GNU
C<config.guess>/C<config.sub> scripts, please.

 #   configure.in
 OS=`shtool guessos`

=item B<arx> [B<-v>] [B<-C> I<cmd>] I<op> I<archive> I<file> [I<file> ...]

This is a wrapper around the archive (``C<ar>'') tool. It provides the ability
to create archives out of existing archives, i.e.  when one of I<file> matches
``C<*.a>'' the archive member files of I<file> are used instead of I<file>
itself. When option ``B<-v>'' (verbose) is given B<arx> shows the actually
involved shell commands. Option ``B<-C>'' can be used to set the ``ar''
command to I<cmd>.

The trick of this command is the automatic handling of archive members which
is especially interesting when one wants to construct a (usually top-level)
library archive out of pre-build sub-library archives (usually staying inside
subdirs) in a large source tree.

Example:

 #   Makefile
 AR=ar
 RANLIB=ranlib
   :
 OBJS=foo.o bar.o
 LIBS=baz/libbaz.a quux/libquux.a
   :
 libfoo.a: $(OBJS) $(LIBS)
     shtool arx -C $(AR) rc libfoo.a $(OBJS) $(LIBS)
     $(RANLIB) libfoo.a

=item B<slo> -- B<-L>I<dir> B<-l>I<lib> [ B<-L>I<dir> B<-l>I<lib> ... ]

This command separates the linker options ``B<-L>'' and ``B<-l>'' by library
class. It's argument line can actually be an abitrary command line where those
options are contained. B<slo> parses these two options only and ignores the
remaining contents. The result is a trivial shell script on C<stdout> which
defines six variables containing the ``B<-L>'' and ``B<-l>'' options sorted by
class: ``C<SLO_DIRS_OBJ>'' and ``C<SLO_LIBS_OBJ>'' contains the ``B<-L>'' and
``B<-l>'' options of static libraries,  ``C<SLO_DIRS_PIC>'' and
``C<SLO_LIBS_PIC>'' contains the ``B<-L>'' and ``B<-l>'' options of static
libraries containing PIC ("Position Independent Code") and ``C<SLO_DIRS_DSO>''
and ``C<SLO_LIBS_DSO>'' contains the ``B<-L>'' and ``B<-l>'' options of shared
libraries. 

The intent of this seperation is to provide a way between static and shared
libraries which is important when one wants to link custom DSOs against
libraries, because not all platforms all one to link these DSOs against shared
libraries. So one first has to separate out the shared libraries and link the
DSO only against the static libraries.  One can use this command also to just
sort the options.

Example:

  #   configure.in
  LINK_STD="$LDFLAGS $LIBS"
  eval `shtool slo $LINK_STD`
  LINK_DSO="$SLO_DIRS_OBJ $SLO_LIBS_OBJ $SLO_DIRS_PIC $SLO_LIBS_PIC"
    :

=item B<scpp> [B<-v>] [B<-p>] [B<-o> I<ofile>] [B<-t> I<tfile>] [B<-M> I<mark>] [B<-D> I<dname>] [B<-C> I<cname>] I<file> [I<file> ...]

This command is an additional ANSI C source file pre-processor for sharing
cpp(1) code segments, internal variables and internal functions. The intention
for this comes from writing libraries in ANSI C. Here a common shared internal
header file is usually used for sharing information between the library
source files. The operation is to parse special constructs in I<file>s,
generate a few things out of these constructs and insert them at position
I<mark> in I<tfile> by writing the output to I<ofile>. Additionally the
I<file>s are never touched or modified. Instead the constructs are removed
later by the cpp(1) phase of the build process. The only prerequisite is that
every I<file> has a ``C<#include ">I<ofile>C<">'' at the top.

This command provides the following features: First it avoids namespace
pollution and reduces prototyping efforts for internal symbols by recognizing
functions and variables which are defined with the storage class identifier
``I<cname>''.  For instance when I<cname> is ``intern'', a function ``C<intern
void *foobar(int quux)>'' in one of the I<file>s is translated into both a
``C<#define foobar __foobar>'' and a ``C<extern void *foobar(int quux);>'' in
I<ofile>. Additionally a global ``C<#define> I<cname> C</**/>'' is also
created in I<ofile> to let the compiler silently ignore this additional
storage class identifier.

Second, the library source files usually want to share C<typedef>s,
C<#define>s, etc.  over the source file boundaries. To achieve this one can
either place this stuff manually into I<tfile> or use the second feature of
B<scpp>: All code in I<file>s encapsulated with ``C<#if >I<dname> ...
C<#endif>'' is automatically copied to I<ofile>. Additionally a global
``C<#define> I<dname> C<0>'' is also created in I<ofile> to let the compiler
silently skip this parts (because it was already found in the header).

Option ``B<-v>'' can be used to enable some processing output.  Option
``B<-p>'' can be used to make the decision whether to overwrite I<ofile>
independent of the generated ``#line'' lines. This is useful for Makefiles
when the real contents of I<ofile> will not change, just line numbers.

Example:

  #   Makefile
  SRCS=foo_bar.c foo_quux.c
  foo_p.h: foo_p.h.in
       shtool scpp -o foo_p.h -t foo_p.h.in \
                   -M %%MARK%% -D cpp -C intern $(SRCS)

  /* foo_p.h.in */
  #ifndef FOO_P_H
  #define FOO_P_H
  %%MARK%%
  #endif /* FOO_P_H */

  /* foo_bar.c */
  #include "foo_p.h"
  #if cpp
  #define OURS_INIT 4711
  #endif
  intern int ours;
  static int myone = 0815;
  intern int bar(void) 
  {
      ours += myone;
  }

  /* foo_quux.c */
  #include "foo_p.h"
  int main(int argc, char *argv[]) 
  {
      int i;
      ours = OURS_INIT
      for (i = 0; i < 10; i++) {
          bar();
          printf("ours now %d\n", ours);
      }
      return 0;
  }

=item B<version> [B<-l> I<lang>] [B<-n> I<name>] [B<-p> I<prefix>] [B<-s> I<version>] [B<-i> I<knob>] [B<-d> I<type>] I<file>

This command generates and maintains a version information file I<file> for
program name I<name> in either textual (I<lang>="C<txt>"), ANSI C
(I<lang>="c") or Perl (I<lang>="perl") language.  The version is always
described with a triple
E<lt>I<version>,I<revision>,I<patch/alpha/beta-level>E<gt> and is represented
by a string which always matches the regular expression
``C<[0-9]+\.[0-9]+[.abps][0-9]+>''. When the option ``B<-s>'' is given, the
contents of I<file> is overridden with the specified I<version>. 

When option ``B<-i>'' is used the version ingredients in I<file> are updated
by adjusting one I<knob> of the version where I<knob> can be one of the
following: ``C<a>'', ``C<b>'', ``C<p>'', ``C<P>'' and ``C<s>'' just increase
the alpha/beta/patch/snap level by 1 (and set the seperator character between
version and the level position). ``C<r>'' increases the revision by 1 and sets
the alpha/beta/patch/snap level to 0.  ``C<v>'' increases the version by 1 and
sets both the revision and alpha/beta/patch/snap level to 0.  

When option ``B<-d>'' is given the current version in I<file> is displayed
either in short (I<type>="short") or long (I<type>="long") texual format or in
a format suitable for use with GNU libtool (I<type>="libtool") or in a
hexadecimal format (I<type>="hex").

When no option is given at all, ``C<-i P>'' is assumed.

Example:

 #   shell script
 shtool version -l c -n FooBar -p foobar -s 1.2b3 version.c

 #   configure.in
 V=`shtool version -l c -d long version.c`
 echo "Configuring FooBar, Version $V"

=item B<path> [B<-s>] [B<-r>] [B<-d>] [B<-b>] [B<-m>] [-p I<path>] I<str> [I<str> ...]

This command deals with shell C<$PATH> variables. It can find a program
executable in $PATH or I<path> through one or more filenames (given by one or
more I<str> arguments). The result is the absolute filesystem path to the
program displayed on C<stdout> plus an exit code of 0 when it was really
found.  The option ``B<-s>'' can be used to suppress the output which is
useful to just test whether a program exists with the help of the return code.
The option ``B<-m>'' enables some magic where currently for the programs
``C<perl>'' and ``C<cpp>'' an advanced magic search is done. The option
``B<-r>'' can be used to transform a forward path to a subdirectory into a
reverse path. Option ``B<-d>'' and ``B<-b>'' just output the directory or base
name of I<str>.

Examples:

 #   shell script
 awk=`shtool path -p "${PATH}:." gawk nawk awk`
 perl=`shtool path -m perl5 perl`
 cpp=`shtool path -m cpp`
 revpath=`shtool path -r path/to/subdir`

=back

=head1 SEE ALSO

sh(1), cp(1), rm(1), mkdir(1), awk(1), sed(1).

=head1 HISTORY

Some scripts contained in B<shtool> were already written in 1994 by I<Ralf S.
Engelschall> for use inside some private source trees. Then they evolved into
more elaborated versions over the years and were used in various free software
projects like ePerl, WML, iSelect, gFONT, etc. They were complemented with
other scripts from the author which he wrote in March 1998 for the ``Apache
Autoconf-style Interface'' (APACI).  In April 1999 the B<shtool> package was
created out of the accumulated master versions of the scripts. In June 1999 it
finally entered the status of an official GNU program.

=head1 AUTHOR

 Ralf S. Engelschall
 rse@engelschall.com
 www.engelschall.com

=cut

