add more prominent caveat notices about experimental features

p4raw-id: //depot/maint-5.6/perl@9513

2 files changed, 22 insertions, 4 deletions

diff --git a/pod/perlfork.pod b/pod/perlfork.pod
index 82ac6891db..dc0a82bfd6 100644
--- a/pod/perlfork.pod
+++ b/pod/perlfork.pod
@@ -1,9 +1,14 @@
 =head1 NAME
 
-perlfork - Perl's fork() emulation
+perlfork - Perl's fork() emulation (EXPERIMENTAL, subject to change)
 
 =head1 SYNOPSIS
 
+    WARNING:  As of the 5.6.1 release, the fork() emulation continues
+    to be an experimental feature.  Use in production applications is
+    not recommended.  See the "BUGS" and "CAVEATS AND LIMITATIONS"
+    sections below.
+
 Perl provides a fork() keyword that corresponds to the Unix system call
 of the same name.  On most Unix-like platforms where the fork() system
 call is available, Perl's fork() simply calls it.
@@ -274,6 +279,17 @@ are expected to be fixed for thread-safety.
 
 =item *
 
+Perl's regular expression engine currently does not play very nicely
+with the fork() emulation.  There are known race conditions arising
+from the regular expression engine modifying state carried in the opcode
+tree at run time (the fork() emulation relies on the opcode tree being
+immutable).  This typically happens when the regex contains paren groups
+or variables interpolated within it that force a run time recompilation
+of the regex.  Due to this major bug, the fork() emulation is not
+recommended for use in production applications at this time.
+
+=item *
+
 Having pseudo-process IDs be negative integers breaks down for the integer
 C<-1> because the wait() and waitpid() functions treat this number as
 being special.  The tacit assumption in the current implementation is that
diff --git a/pod/perlunicode.pod b/pod/perlunicode.pod
index 30a4482260..5b0fe2faaf 100644
--- a/pod/perlunicode.pod
+++ b/pod/perlunicode.pod
@@ -1,14 +1,16 @@
 =head1 NAME
 
-perlunicode - Unicode support in Perl
+perlunicode - Unicode support in Perl (EXPERIMENTAL, subject to change)
 
 =head1 DESCRIPTION
 
 =head2 Important Caveat
 
-WARNING: The implementation of Unicode support in Perl is incomplete.
+    WARNING:  As of the 5.6.1 release, the implementation of Unicode
+    support in Perl is incomplete, and continues to be highly experimental.
 
-The following areas need further work.
+The following areas need further work.  They are being rapidly addressed
+in the 5.7.x development branch.
 
 =over 4