-febootstrap creates a Fedora root filesystem, based on the Fedora
-version specified by I<REPO> under the directory specified by
-I<TARGET>. Optionally I<MIRROR> can point to a local mirror
-(otherwise the public Fedora mirrors are used). I<REPO> names are
-C<fedora-I<VERSION>> (eg. C<fedora-10>) or C<rawhide>.
-
-febootstrap does I<not> need to be run as root. If for some reason
-you do run it as root, then it works slightly differently and may have
-side effects such as stopping or starting system daemons.
-
-For more advanced needs, take a look at L<mock(1)>, C<livecd-creator>
-and I<thincrust.net>'s C<appliance-creator>.
-
-The normal output is a root directory located at I<TARGET> and
-a fakeroot logfile at C<I<TARGET>/fakeroot.log>.
+febootstrap is a tool for building supermin appliances. These are
+tiny appliances (similar to virtual machines), usually around 100KB in
+size, which get fully instantiated on-the-fly in a fraction of a
+second when you need to boot one of them.
+
+Originally "fe" in febootstrap stood for "Fedora", but this tool is
+now distro-independent and can build supermin appliances for several
+popular Linux distros, and adding support for others is reasonably
+easy.
+
+Note that this manual page documents febootstrap 3.x which is a
+complete rewrite and quite different from version 2.x. If you are
+looking for the febootstrap 2.x tools, then this is not the right
+place.
+
+=head2 BASIC OPERATION
+
+There are two modes for using febootstrap. With the I<--names>
+parameter, febootstrap takes a list of package names and creates a
+supermin appliance containing those packages and all dependencies that
+those packages require. In this mode febootstrap usually needs
+network access because it may need to consult package repositories in
+order to work out dependencies and download packages.
+
+Without I<--names>, febootstrap takes a list of packages (ie.
+filenames of locally available packages). This package set must be
+complete and consistent with no dependencies outside the set of
+packages you provide. In this mode febootstrap does not require any
+network access. It works by looking at the package files themselves.
+
+By "package" we mean the RPM, DEB, (etc.) package. A package name
+might be the fully qualified name (eg. C<coreutils-8.5-7.fc14.x86_64>)
+or some abbreviation (eg. C<coreutils>). The precise format of the
+name and what abbreviations are allowed depends on the package
+manager.
+
+The supermin appliance that febootstrap writes consists of two files
+called C<hostfiles> and C<base.img> (see L</SUPERMIN APPLIANCES>
+below). By default these are written to the current directory. If
+you specify the I<-o OUTPUTDIR> option then these files are written to
+the named directory instead (traditionally this directory is named
+C<supermin.d> but you can call it whatever you want).
+
+In all cases febootstrap can only build a supermin appliance which is
+identical in distro, version and architecture to the host. It does
+I<not> do cross-builds.