perldelta: Clarify removal vs deprecation of modules

2 files changed, 48 insertions, 14 deletions

diff --git a/Porting/perldelta_template.pod b/Porting/perldelta_template.pod
index 8a066db904..98be13b2c6 100644
--- a/Porting/perldelta_template.pod
+++ b/Porting/perldelta_template.pod
@@ -47,11 +47,33 @@ XXX For a release on a stable branch, this section aspires to be:
 
 =head1 Deprecations
 
-XXX Any deprecated features, syntax, modules etc. should be listed here.  In
-particular, deprecated modules should be listed here even if they are listed as
-an updated module in the L</Modules and Pragmata> section.
+XXX Any deprecated features, syntax, modules etc. should be listed here.
 
-[ List each deprecation as a =head2 entry ]
+=head2 Module removals
+
+XXX Remove this section if inapplicable.
+
+The following modules will be removed from the core distribution in a future
+release, and will at that time need to be installed from CPAN. Distributions
+on CPAN which require these modules will need to list them as prerequisites.
+
+The core versions of these modules will now issue C<"deprecated">-category
+warnings to alert you to this fact. To silence these deprecation warnings,
+install the modules in question from CPAN.
+
+Note that these are (with rare exceptions) fine modules that you are encouraged
+to continue to use. Their disinclusion from core primarily hinges on their
+necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
+not usually on concerns over their design.
+
+=over
+
+XXX Note that deprecated modules should be listed here even if they are listed
+as an updated module in the L</Modules and Pragmata> section.
+
+=back
+
+[ List each other deprecation as a =head2 entry ]
 
 =head1 Performance Enhancements
 
diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index fc95dc4cb8..19991106da 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -563,19 +563,33 @@ containing one space once was.
 
 =head1 Deprecations
 
-=head2 Deprecated modules
+=head2 Module removals
 
-The following modules will be removed from the core distribution in a
-future release, and should be installed from CPAN instead. Distributions
-on CPAN which require these should add them to their prerequisites.
-The core versions of these modules will issue C<"deprecated">-category
-warnings.
+The following modules will be removed from the core distribution in a future
+release, and will at that time need to be installed from CPAN. Distributions
+on CPAN which require these modules will need to list them as prerequisites.
+
+The core versions of these modules will now issue C<"deprecated">-category
+warnings to alert you to this fact. To silence these deprecation warnings,
+install the modules in question from CPAN.
 
-You can silence these deprecation warnings by installing the modules
-in question from CPAN.
+Note that these are (with rare exceptions) fine modules that you are encouraged
+to continue to use. Their disinclusion from core primarily hinges on their
+necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
+not usually on concerns over their design.
 
 =over
 
+=item L<encoding>
+
+The use of this pragma is now strongly discouraged. It conflates the encoding
+of source text with the encoding of I/O data, reinterprets escape sequences in
+source text (a questionable choice), and introduces the UTF-8 bug to all runtime
+handling of character strings. It is broken as designed and beyond repair.
+
+For using non-ASCII literal characters in source text, please refer to L<utf8>.
+For dealing with textual I/O data, please refer to L<Encode> and L<open>.
+
 =item L<Archive::Extract>
 
 =item L<B::Lint>
@@ -586,8 +600,6 @@ in question from CPAN.
 
 =item L<Devel::InnerPackage>
 
-=item L<encoding>
-
 =item L<Log::Message>
 
 =item L<Log::Message::Config>