This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta: Clarify removal vs deprecation of modules
[perl5.git] / pod / perldelta.pod
index fc95dc4..1999110 100644 (file)
@@ -563,19 +563,33 @@ containing one space once was.
 
 =head1 Deprecations
 
 
 =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
 
 
 =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>
 =item L<Archive::Extract>
 
 =item L<B::Lint>
@@ -586,8 +600,6 @@ in question from CPAN.
 
 =item L<Devel::InnerPackage>
 
 
 =item L<Devel::InnerPackage>
 
-=item L<encoding>
-
 =item L<Log::Message>
 
 =item L<Log::Message::Config>
 =item L<Log::Message>
 
 =item L<Log::Message::Config>