--- App-Staticperl/staticperl.pod	2011/06/27 21:56:51	1.45
+++ App-Staticperl/staticperl.pod	2011/07/10 01:37:56	1.48
@@ -86,7 +86,7 @@
 This means the modules to include often need to be tweaked manually.
 
 All this does not preclude more permissive modes to be implemented in
-the future, but right now, you have to resolve state hidden dependencies
+the future, but right now, you have to resolve hidden dependencies
 manually.
 
 =item * PAR works out of the box, F<staticperl> does not.
@@ -204,7 +204,9 @@
 Starts an interactive CPAN shell that you can use to install further
 modules. Installs the perl first if necessary, but apart from that,
 no magic is involved: you could just as well run it manually via
-F<~/.staticperl/perl/bin/cpan>.
+F<~/.staticperl/perl/bin/cpan>, except that F<staticperl> additionally
+sets the environment variable C<$PERL> to the path of the perl
+interpreter, which is handy in subshells.
 
 Any additional arguments are simply passed to the F<cpan> command.
 
@@ -549,16 +551,16 @@
 without any postprocessing (perl files might get stripped to reduce their
 size).
 
-If you specify an alias you should probably add a C<&> prefix to avoid
-clashing with embedded perl files (whose paths never start with C<&>),
-and/or use a special directory prefix, such as C<&res/name>.
+If you specify an alias you should probably add a C</> prefix to avoid
+clashing with embedded perl files (whose paths never start with C</>),
+and/or use a special directory prefix, such as C</res/name>.
 
 You can later get a copy of these files by calling C<staticperl::find
 "alias">.
 
 An alternative way to embed binary files is to convert them to perl and
 use C<do> to get the contents - this method is a bit cumbersome, but works
-both inside and outside of a staticperl bundle:
+both inside and outside of a staticperl bundle, without extra ado:
 
    # a "binary" file, call it "bindata.pl"
    <<'SOME_MARKER'
@@ -568,6 +570,23 @@
    # load the binary
    chomp (my $data = do "bindata.pl");
 
+=item C<--allow-dynamic>
+
+By default, when F<mkbundle> hits a dynamic perl extension (e.g. a F<.so>
+or F<.dll> file), it will stop with a fatal error.
+
+When this option is enabled, F<mkbundle> packages the shared
+object into the bundle instead, with a prefix of F<!>
+(e.g. F<!auto/List/Util/Util.so>). What you do with that is currently up
+to you, F<staticperl> has no special support for this at the moment, apart
+from working around the lack of availability of F<PerlIO::scalar> while
+bootstrapping, at a speed cost.
+
+One way to deal with this is to write all files starting with F<!> into
+some directory and then C<unshift> that path onto C<@INC>.
+
+#TODO: example
+
 =back
 
 =item Step 2: filter all files using C<--include> and C<--exclude> options.
@@ -1124,20 +1143,66 @@
 
 =head1 RUNTIME FUNCTIONALITY
 
-Binaries created with C<mkbundle>/C<mkperl> contain extra functions, which
-are required to access the bundled perl sources, but might be useful for
-other purposes.
+Binaries created with C<mkbundle>/C<mkperl> contain extra functionality,
+mostly related to the extra files bundled in the binary (the virtual
+filesystem). All of this data is statically compiled into the binary, and
+accessing means copying it from a read-only section of your binary. Data
+pages in this way is usually freed by the operating system, as it isn't
+use more the onace.
+
+=head2 VIRTUAL FILESYSTEM
+
+Every bundle has a virtual filesystem. The only information stored in it
+is the path and contents of each file that was bundled.
+
+=head3 LAYOUT
+
+Any path starting with an ampersand (F<&>) or exclamation mark (F<!>) are
+reserved by F<staticperl>. They must only be used as described in this
+section.
 
-In addition, for the embedded loading of perl files to work, F<staticperl>
-overrides the C<@INC> array.
+=over 4
+
+=item !
+
+All files that typically cannot be loaded from memory (such as dynamic
+objects or shared libraries), but have to reside in the filesystem, are
+prefixed with F<!>. Typically these files get written out to some
+(semi-)temporary directory shortly after program startup, or before being
+used.
+
+=item !boot
+
+The bootstrap file, if specified during bundling.
+
+=item !auto/
+
+Shared objects or dlls corresponding to dynamically-linked perl extensions
+are stored with an F<!auto/> prefix.
+
+=item !lib/
+
+External shared libraries are stored in this directory.
+
+=item any letter
+
+Any path starting with a letter is a perl library file. For example,
+F<Coro/AIO.pm> corresponds to the file loaded by C<use Coro::AIO>, and
+F<Coro/jit.pl> corresponds to C<require "Coro/jit.pl">. 
+
+Obviously, module names shouldn't start with any other characters than
+letters :)
+
+=back
+
+=head3 FUNCTIONS
 
 =over 4
 
 =item $file = staticperl::find $path
 
 Returns the data associated with the given C<$path>
-(e.g. C<Digest/MD5.pm>, C<auto/POSIX/autosplit.ix>), which is basically
-the UNIX path relative to the perl library directory.
+(e.g. C<Digest/MD5.pm>, C<auto/POSIX/autosplit.ix>).
 
 Returns C<undef> if the file isn't embedded.
 
@@ -1147,6 +1212,11 @@
 
 =back
 
+=head2 EXTRA FEATURES
+
+In addition, for the embedded loading of perl files to work, F<staticperl>
+overrides the C<@INC> array.
+
 =head1 FULLY STATIC BINARIES - UCLIBC AND BUILDROOT
 
 To make truly static (Linux-) libraries, you might want to have a look at