--- Urlader/Urlader.pm	2012/01/03 13:28:10	1.3
+++ Urlader/Urlader.pm	2012/01/04 14:19:05	1.4
@@ -8,6 +8,105 @@
 
 =head1 DESCRIPTION
 
+Urlader (that's german for "bootloader" btw.) was created out of
+frustration over PAR again not working, again not being flexible enough
+for simple things, and again causing mysterious missing files issues on
+various platforms.
+
+That doesn't mean this module replaces PAR, in fact, you should stay with
+it for many reasons, user-friendlyness is one of them.
+
+However, if you want to make single-file distributions out of your perl
+programs (or python, or C or whatever), and you are prepared to fiddle a
+LOT, this module might provide a tiny step towards your goal. Well, if it
+ever gets finished.
+
+Also, I<nothing in this module is considered very stable yet>, and it's
+far from feature-complete.
+
+Having said all that, Urlader basically provides three services:
+
+=over 4
+
+=item A simple archiver that packs a directory tree into a single file.
+
+=item A small C program that works on windows and unix, which unpacks an attached
+archive and runs a program.
+
+=item A perl module support module (I<this one>), that can be used to query
+the runtime environment, find out where to install updates and so on.
+
+=back
+
+=head1 EXAMPLE
+
+How can it be used to provide single-file executables?
+
+So simple, create a directory with everything that's needed, e.g.:
+
+   # find bintree
+   bintree/perl
+   bintree/libperl.so.5.10
+   bintree/run
+   bintree/pm/Guard.pm
+   bintree/pm/auto/Guard/Guard.so
+
+   # cat bintree/run
+   @INC = ("pm", "."); # "." works around buggy AutoLoader
+   use Guard;
+   guard { warn "hello, world!\n" }; # just to show off
+   exit 0; # tell the urlader that everything was fine
+
+Then pack it:
+
+   # wget http://urlader.schmorp.de/prebuilt/1.0/linux-x86
+   # urlader-util --urlader linux-x86 --pack myprog ver1_000 bintree \
+                  LD_LIBRARY_PATH=. ./perl run \
+                  >myprog
+   # chmod 755 myprog
+
+=head1 CONCEPTS
+
+=over 4
+
+=item urlader
+
+A small (hopefully) and relatively portable (hopefully) binary that is
+prepended to a pack file to make it executable.
+
+You can build it yourself from sources (see F<prebuilt/Makefile> in the
+distribution) or use one of the precompiled ones at:
+
+   http://urlader.schmorp.de/prebuilt/1.0/
+
+The F<README> there has further information on the binaries provided.
+
+=item exe_id
+
+A string that uniquely identifies your program - all branches of it. It
+must consist of the characters C<A-Za-z0-9_-> only and should be a valid
+directory name on all systems you want to deploy on.
+
+=item exe_ver
+
+A string the uniquely identifies the contents of the archive, i.e. the
+version.  It has the same restrictions as the C<exe_id>, and should be
+fixed-length, as Urlader assumes lexicographically higher versions are
+newer, and thus preferable.
+
+=item pack file (archive)
+
+This contains the C<exe_id>, the C<exe_ver>, a number of environment
+variable assignments, the program name to execute, the initial arguments
+it receives, and finally, a list of files (with contents :) and
+directories.
+
+=item override
+
+=back
+
+=head1 FUNCTIONS AND VARIABLES IN THIS MODULE
+
 =over 4
 
 =cut