--- toast	2003/11/08 21:52:54	1.238
+++ toast	2003/11/09 23:43:26	1.239
@@ -4454,6 +4454,93 @@
 in some precompiled or specialized binary format, such as RPM.  Binary
 packages are also supported.
+=head2 Purpose
+B<toast> is designed to be used in any of three ways:
+=over 4
+=item 1.
+Installing and managing software in the home directory of a non-root user
+on a multi-user system.  For example, I like to be able to run valgrind,
+xdaliclock, Opera, and a few other programs on the Linux cluster at work
+without having to bother the IT department about installing or supporting
+those packages.
+=item 2.
+Installing and managing software packages in parallel to those installed
+by a conventional package manager.  For example, if I were maintaining a
+computer system running some kind of mainstream Unix-like OS, it might be
+convenient to be able to quickly install the latest OpenSSH from source
+into C</usr/local> in order to work around a security vulnerability,
+and then conveniently remove it once my vendor or distribution releases
+an official package for that version.
+=item 3.
+Installing and managing all software for an entire Unix system; that is,
+using B<toast> as the one true package manager for the system.  This is
+what I do on my (single-user) Linux box at home.
+Use #1 seems to be by far the most common in practice.  As far as I know,
+I'm the only one crazy enough to attempt #3, and no one bothers with #2.
+In general, it's probably a good idea to use a real distribution (such
+as Debian), and to use its native package management system whenever
+possible, rather than using B<toast> to replace it or go behind its back.
+=head2 Requirements
+B<toast> itself is known to work with Perl 5.005_03 through 5.8.x under
+Linux, FreeBSD and Cygwin, without relying on the presence or absence
+of any Perl modules or other tools.  Additional requirements for B<toast
+build> vary according to the package being built.
+=head2 Setup
+To have the latest version of B<toast> download and install itself,
+run one of the following commands.  The first requires GNU wget; the
+second relies on the C<GET> utility that comes with the LWP Perl module.
+  sh -c 'u=http://toastball.net/toast;wget -O- $u/toast|perl - arm $u/'
+  sh -c 'u=http://toastball.net/toast;GET $u/toast|perl - arm $u/'
+If you ran either of the above commands as root, B<toast> should now be
+installed in C</toast> with appropriate symlinks under C</usr/local>,
+and you should be all set.  If you ran either command as a non-root
+user, B<toast> will have installed itself and everything it needs under
+C<$HOME/.toast>, and you'll probably need to add C<$HOME/.toast/armed/bin>
+to your PATH environment variable in order to be able to use B<toast>
+and any other packages it installs.  For example, in a Bourne-like shell:
+  PATH=$HOME/.toast/armed/bin:$PATH
+If you would like to use any man pages, info pages, libraries or header
+files installed by B<toast>, you may also want to adjust MANPATH,
+INFOPATH, LD_LIBRARY_PATH, or CFLAGS as appropriate.  Note that setting
+LD_LIBRARY_PATH may have unintended consequences; for more information,
+search the Web for <LD_LIBRARY_PATH considered harmful>.  If your C
+compiler is gcc, you may be able to use the CPATH environment variable
+instead of messing with CFLAGS; see the gcc documentation for details.
+The above procedure is by no means required in order to install or
+use B<toast>.  The unmodified script can be copied to and run from any
+location, and you can use B<toast man> to view the man page without
+having to install it first.  The default option settings should be
+sensible, and any necessary directories will be created on demand.
+A GNU-like C<configure> wrapper script is also provided with the official
+B<toast> distribution for your convenience.  You can supply an alternate
+installation directory prefix with C<./configure --prefix=foo>, or keep
+the default prefix of C</usr> by running C<./configure> without arguments.
+Then run C<make>, become root if necessary, and run C<make install>, which
+will install both the B<toast> script and a man page.  Sadly, B<toast>'s
+C<configure> script does not support the other command-line options and
+features of B<configure> scripts produced by the real GNU autoconf.
 =head2 Commands
 =over 4
@@ -5017,10 +5104,7 @@
 B<toast> may be downloaded from C<http://toastball.net/toast/> under
-the terms of the GNU GPL.  B<toast> itself is known to work with Perl
-5.005_03 through 5.8.x under Linux, FreeBSD and Cygwin, without relying
-on the presence or absence of any Perl modules or other tools.  Additional
-requirements for B<toast build> vary according to the package being built.
+the terms of the GNU GPL.
 =head1 BUGS
@@ -5063,8 +5147,6 @@
 Questions left unanswered by this documentation:
-  - For what purposes might one actually use toast?
-  - What environment variables should I set?
   - What are some realistic examples of toast commands?
   - What kinds of packages can be expected to build?
   - What protocols and archive formats are supported?