C: POD DESCRIPTION for package walker, CAVEAT warnings explained

lib/B/C.pm

@@ -2572,7 +2572,7 @@ sub B::PVMG::save_magic {
       # stored by some PMOP *pm = cLOGOP->op_other (pp_ctl.c) in C.xs
       my $pmop = $Regexp{$rx};
       if (!$pmop) {
-	warn "C.xs Warning: PMOP missing for QR\n";
+	warn "Warning: C.xs PMOP missing for QR\n";
       } else {
 	my ($resym, $relen);
 	if ($PERL56) {
@@ -6194,11 +6194,25 @@ execution speed of your program but may improve the start-up time.
 Depending on the environment in which your program runs this may be
 either a help or a hindrance.
 
+The compiler detects all immediate objects in the main (or optionally other)
+package, and then in a second pass tries to verify if all not by the compiler
+itself loaded packages are used by the program. This is done in a loop until
+no new packages are found. These package detection passes are not fool proof,
+since there are either too many unneeded compiled packages with its
+sub-dependencies (i.e. too big executable size) or some packages are missed,
+e.g. C<eval "require $name;">. Nevertheless are all detected functions, objects
+and methods compiled.
+
+You can tune these steps with the options C<-u> (I<used>) and C<-U>
+(I<unused>). Not statically detected packages will be loaded then at run-time
+at the client environment, with the compile-time @INC path. Note that fully
+self-contained executables should include all at the client needed packages.
+
 =head1 OPTIONS
 
 If there are any non-option arguments, they are taken to be
-names of objects to be saved (probably doesn't work properly yet).
-Without extra arguments, it saves the main program.
+names of objects (packages, functions, scalars) to be saved.
+Without extra arguments, it saves the main program, i.e. %main::
 
 =over 4
 
@@ -6551,6 +6565,56 @@ help make use of this compiler.
 
     perl -MO=C,-v,-DcA,-l2048 bar.pl > /dev/null
 
+=head1 CAVEAT
+
+With 5.6 it is not possible to use the __DATA__ filehandle, because
+compatible access via PerlIO::scalar was added with 5.8.1
+
+It is generally not possible to restore all of the compiled BEGIN-time state.
+Esp. problematic are non-standard filehandles (i.e. fd>2), process ids,
+environment specific knowledge, because only with the compiler BEGIN blocks
+are not executed in the client environment.
+
+The compiler produces some warnings, which might need source code changes
+or changed compiler options.
+
+=over
+
+=item Warning: Problem with require "$name" - $INC{file.pm}
+
+Dynamic load of $name did not add the expected %INC key.
+
+=item Warning: C.xs PMOP missing for QR
+
+In an initial C.xs runloop all QR regex ops are stored, so that they
+can matched later to PMOPs.
+
+=item Warning: DynaLoader broken with 5.15.2-5.15.3.
+
+[perl #100138] DynaLoader symbols were XS_INTERNAL. Strict linking
+could not resolve it. Usually libperl was patched to overcome this
+for these two versions.
+Setting the environment variable NO_DL_WARN=1 omits this warning.
+
+=item Warning: __DATA__ handle $fullname not stored. Need -O2 or -fsave-data.
+
+Since processing the __DATA__ filehandle involves some overhead, requiring
+PerlIO::scalar with all its dependencies, you must use -O2 or -fsave-data.
+
+=item Warning: Write BEGIN-block $fullname to FileHandle $iotype \&$fd
+
+Critical problem. This must be fixed in the source.
+
+=item Warning: Read BEGIN-block $fullname from FileHandle $iotype \&$fd
+
+Critical problem. This must be fixed in the source.
+
+=item Warning: -o argument ignored with -c
+
+-c does only check, but not accumulate C output lines.
+
+=back
+
 =head1 BUGS
 
 Current status: A few known bugs.
@@ -6563,7 +6627,7 @@ Current status: A few known bugs.
     &XSLoader::load sometimes missing
     reading from __DATA__ handles (15) non-threaded
     handling npP magic for shared threaded variables (41-43)
-    destruction of variables in END blocks
+    destruction of shared strings in end of scope and END blocks
 
 =head1 AUTHOR